Installation Guide

This guide covers detailed installation options for the Tailscale Gateway Operator.

Prerequisites

Required Components

Component	Version	Description
Kubernetes	v1.25+	Target cluster for operator deployment
kubectl	Latest	Kubernetes CLI tool
Helm	v3.8+	Package manager for Kubernetes
Envoy Gateway	v1.0.0+	Gateway API implementation
Tailscale Account	-	With admin permissions for OAuth setup

Supported Platforms

✅ Kubernetes Distributions: EKS, GKE, AKS, kind, k3s, OpenShift
✅ Operating Systems: Linux, macOS, Windows
✅ Architectures: x86_64, ARM64

Installation Methods

Choose the installation method that best fits your environment:

Method 1: Helm Installation (Recommended)

The Helm chart provides the easiest way to install and manage the operator.

Step 1: Install from OCI Registry

The Tailscale Gateway Operator is available as an OCI package:

Step 2: Create Namespace

kubectl create namespace tailscale-gateway-system

Step 3: Configure OAuth Credentials

Create a Kubernetes secret with your Tailscale OAuth credentials:

kubectl create secret generic tailscale-oauth \
  --from-literal=client-id=YOUR_CLIENT_ID \
  --from-literal=client-secret=YOUR_CLIENT_SECRET \
  -n tailscale-gateway-system

Step 4: Install the Operator

# Install Tailscale Gateway Operator from OCI registry with development version
helm install tailscale-gateway-operator oci://ghcr.io/rajsinghtech/charts/tailscale-gateway-operator \
  --namespace tailscale-gateway-system \
  --create-namespace \
  --version 0.0.0-latest

Step 5: Verify Installation

kubectl get pods -n tailscale-gateway-system
kubectl get crd | grep tailscale

Method 2: Raw Manifests

For environments where Helm is not available:

Step 1: Download Manifests

# Download the latest release manifests
curl -L -o tailscale-gateway.yaml \
  https://github.com/rajsinghtech/tailscale-gateway/releases/latest/download/operator.yaml

Step 2: Create OAuth Secret

kubectl create namespace tailscale-gateway-system

kubectl create secret generic tailscale-oauth \
  --from-literal=client-id=YOUR_CLIENT_ID \
  --from-literal=client-secret=YOUR_CLIENT_SECRET \
  -n tailscale-gateway-system

Step 3: Apply Manifests

kubectl apply -f tailscale-gateway.yaml

Method 3: Development Installation

For development and testing purposes:

Step 1: Clone Repository

git clone https://github.com/rajsinghtech/tailscale-gateway.git
cd tailscale-gateway

Step 2: Build and Deploy

# Generate CRDs and manifests
make manifests

# Build Docker images
make docker-build

# Load images into kind (if using kind)
kind load docker-image tailscale-gateway:latest
kind load docker-image tailscale-gateway-extension-server:latest

# Deploy to cluster
make deploy

Envoy Gateway Setup

Tailscale Gateway requires Envoy Gateway to be installed first.

Install Envoy Gateway

Envoy Gateway is a prerequisite for Tailscale Gateway. Install it first:

# Install Envoy Gateway using Helm with latest development version
helm install my-gateway-helm oci://docker.io/envoyproxy/gateway-helm \
  --version 0.0.0-latest \
  -n envoy-gateway-system \
  --create-namespace

# Wait for deployment to be ready
kubectl wait --timeout=5m -n envoy-gateway-system \
  deployment/envoy-gateway --for=condition=Available

Configure Envoy Gateway

Create a Gateway API Gateway resource:

envoy-gateway.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: envoy-gateway
  namespace: envoy-gateway-system
spec:
  gatewayClassName: eg
  listeners:
    - name: http
      protocol: HTTP
      port: 80
    - name: https
      protocol: HTTPS
      port: 443
      tls:
        mode: Terminate
        certificateRefs:
          - name: gateway-tls

Apply the gateway:

kubectl apply -f envoy-gateway.yaml

Configuration Options

Helm Chart Values

The Helm chart supports extensive customization through values:

values.yaml
# Operator configuration
operator:
  image:
    repository: ghcr.io/rajsinghtech/tailscale-gateway
    tag: latest
  replicas: 1
  resources:
    limits:
      cpu: 500m
      memory: 128Mi
    requests:
      cpu: 10m
      memory: 64Mi

# Extension server configuration
extensionServer:
  image:
    repository: ghcr.io/rajsinghtech/tailscale-gateway-extension-server
    tag: latest
  replicas: 2
  grpcPort: 5005
  resources:
    limits:
      cpu: 500m
      memory: 128Mi

# OAuth configuration
oauth:
  existingSecret: tailscale-oauth
  clientIdKey: client-id
  clientSecretKey: client-secret

# Metrics and monitoring
metrics:
  enabled: true
  port: 8080

# Health probes
healthProbe:
  enabled: true
  port: 8081

# RBAC
rbac:
  create: true

# Service accounts
serviceAccount:
  create: true
  name: ""

Custom Installation

Install with custom values:

helm install tailscale-gateway tailscale-gateway/tailscale-gateway \
  --namespace tailscale-gateway-system \
  --values custom-values.yaml

OAuth Setup Guide

Step 1: Access Tailscale Admin Console

Go to Tailscale Admin Console
Sign in with your Tailscale account

Step 2: Create OAuth Client

Click "Generate OAuth client"
Enter a descriptive name: Tailscale Gateway Operator
Add required scopes:
- device:create - Create new devices
- device:read - Read device information
- device:write - Modify device settings
- tailnet:read - Read tailnet information

Step 3: Save Credentials

Copy the Client ID and Client Secret
Store them securely (they won't be shown again)

Step 4: Create Kubernetes Secret

kubectl create secret generic tailscale-oauth \
  --from-literal=client-id=YOUR_CLIENT_ID \
  --from-literal=client-secret=YOUR_CLIENT_SECRET \
  -n tailscale-gateway-system

Verification

Check Operator Status

# Check pod status
kubectl get pods -n tailscale-gateway-system

# Check operator logs
kubectl logs -n tailscale-gateway-system deployment/tailscale-gateway-operator

# Check extension server logs
kubectl logs -n tailscale-gateway-system deployment/tailscale-gateway-extension-server

Verify CRDs

# List custom resource definitions
kubectl get crd | grep tailscale

# Expected output:
# tailscaleendpoints.gateway.tailscale.com
# tailscalegateways.gateway.tailscale.com
# tailscaleroutepolicies.gateway.tailscale.com
# tailscaletailnets.gateway.tailscale.com

Test API Access

# Create a simple TailscaleTailnet resource
cat <<EOF | kubectl apply -f -
apiVersion: gateway.tailscale.com/v1alpha1
kind: TailscaleTailnet
metadata:
  name: test-tailnet
  namespace: default
spec:
  tailnet: "your-tailnet.ts.net"
EOF

# Check if it was created successfully
kubectl get tailscaletailnets

Troubleshooting Installation

Common Issues

1. OAuth Authentication Failures

Error: Failed to authenticate with Tailscale API

Solution:

# Verify secret exists and has correct keys
kubectl get secret tailscale-oauth -n tailscale-gateway-system -o yaml

# Check if credentials are valid
kubectl logs -n tailscale-gateway-system deployment/tailscale-gateway-operator | grep oauth

2. CRD Installation Issues

Error: Custom Resource Definitions not found

Solution:

# Manually install CRDs
kubectl apply -f https://github.com/rajsinghtech/tailscale-gateway/releases/latest/download/crds.yaml

3. Envoy Gateway Not Found

Error: Gateway envoy-gateway not found

Solution:

# Install Envoy Gateway first
helm install eg oci://docker.io/envoyproxy/gateway-helm --version v1.0.0 -n envoy-gateway-system --create-namespace

4. Permission Issues

Error: User cannot list/create resources

Solution:

# Check RBAC configuration
kubectl get clusterrole,clusterrolebinding | grep tailscale

# Verify service account permissions
kubectl auth can-i create tailscaleendpoints --as=system:serviceaccount:tailscale-gateway-system:tailscale-gateway-operator

Debug Commands

# Get comprehensive status
kubectl get all -n tailscale-gateway-system

# Check events for errors
kubectl get events -n tailscale-gateway-system --sort-by='.lastTimestamp'

# Describe problematic resources
kubectl describe pod -n tailscale-gateway-system -l app=tailscale-gateway-operator

# View detailed logs with timestamps
kubectl logs -n tailscale-gateway-system deployment/tailscale-gateway-operator --timestamps=true

Next Steps

After successful installation:

Quick Start - Deploy your first gateway
Configuration Guide - Learn about configuration options
Examples - Explore practical examples
Operations - Set up monitoring and observability

Prerequisites​

Required Components​

Supported Platforms​

Installation Methods​

Method 1: Helm Installation (Recommended)​

Step 1: Install from OCI Registry​

Step 2: Create Namespace​

Step 3: Configure OAuth Credentials​

Step 4: Install the Operator​

Step 5: Verify Installation​

Method 2: Raw Manifests​

Step 1: Download Manifests​

Step 2: Create OAuth Secret​

Step 3: Apply Manifests​

Method 3: Development Installation​

Step 1: Clone Repository​

Step 2: Build and Deploy​

Envoy Gateway Setup​

Install Envoy Gateway​

Configure Envoy Gateway​

Configuration Options​

Helm Chart Values​

Custom Installation​

OAuth Setup Guide​

Step 1: Access Tailscale Admin Console​

Step 2: Create OAuth Client​

Step 3: Save Credentials​

Step 4: Create Kubernetes Secret​

Verification​

Check Operator Status​

Verify CRDs​

Test API Access​

Troubleshooting Installation​

Common Issues​

1. OAuth Authentication Failures​

2. CRD Installation Issues​

3. Envoy Gateway Not Found​

4. Permission Issues​

Debug Commands​

Next Steps​

Prerequisites

Required Components

Supported Platforms

Installation Methods

Method 1: Helm Installation (Recommended)

Step 1: Install from OCI Registry

Step 2: Create Namespace

Step 3: Configure OAuth Credentials

Step 4: Install the Operator

Step 5: Verify Installation

Method 2: Raw Manifests

Step 1: Download Manifests

Step 2: Create OAuth Secret

Step 3: Apply Manifests

Method 3: Development Installation

Step 1: Clone Repository

Step 2: Build and Deploy

Envoy Gateway Setup

Install Envoy Gateway

Configure Envoy Gateway

Configuration Options

Helm Chart Values

Custom Installation

OAuth Setup Guide

Step 1: Access Tailscale Admin Console

Step 2: Create OAuth Client

Step 3: Save Credentials

Step 4: Create Kubernetes Secret

Verification

Check Operator Status

Verify CRDs

Test API Access

Troubleshooting Installation

Common Issues

1. OAuth Authentication Failures

2. CRD Installation Issues

3. Envoy Gateway Not Found

4. Permission Issues

Debug Commands

Next Steps