Kubernetes Kubeconfig Sync

Use the Twingate Client to sync kubeconfig and access Kubernetes clusters without cloud provider CLIs.

After you set up a Kubernetes Cluster Resource with Privileged Access for Kubernetes, users and Service Accounts need to configure kubectl on their machines to connect. The Twingate Client handles this automatically with twingate kube config sync, which writes standard kubeconfig contexts for every Kubernetes Cluster Resource the user has access to.

This eliminates the need for cloud provider CLIs like gcloud, doctl, or aws eks to obtain cluster credentials. Once synced, kubectl --context=<cluster-name> works directly.

Prerequisites

Twingate Client version 2025.175 or later on macOS, Windows, or Linux.
At least one Kubernetes Cluster Resource configured with Privileged Access for Kubernetes.
The user or Service Account must have access to the Kubernetes Resource through a Twingate Group.

Sync all Kubernetes Resources

twingate kube config sync

Syncs kubeconfig entries for every Kubernetes Cluster Resource the user has access to. Each Resource gets a kubeconfig context named after the cluster, so you can switch between clusters with kubectl --context=<cluster-name>.

Sync a specific Resource

twingate kube config sync <resource-name>

Syncs the kubeconfig entry for a single Kubernetes Cluster Resource by name. Useful when you only need access to one cluster or want to update a specific context without touching the rest.

Enable or disable automatic sync

twingate kube config autosync on
twingate kube config autosync off

When autosync is enabled, the Twingate Client keeps your kubeconfig up to date as Resources are added, removed, or changed. This is the recommended setting for interactive use so that new clusters appear in your kubeconfig automatically.

Interactive usage

For developers and operators using the Twingate Client on their workstation:

Ensure the Twingate Client is running and you are authenticated.
Sync your kubeconfig:
```
twingate kube config sync
```
List available contexts to see your Kubernetes Resources:
```
kubectl config get-contexts
```
Access a cluster:
```
kubectl --context=my-cluster get pods
```
Optionally, enable autosync so your kubeconfig stays current:
```
twingate kube config autosync on
```

Headless usage for CI/CD

In CI/CD pipelines and other automated environments, the Twingate Client runs in headless mode with a Service Key. After starting the headless Client, twingate kube config sync works the same way and writes kubeconfig contexts that kubectl can use immediately.

This means your pipelines no longer need cloud provider CLIs (gcloud, doctl, aws eks, etc.) to authenticate to Kubernetes clusters. The Twingate Client handles authentication and the kubeconfig sync provides the cluster credentials.

CircleCI example

jobs:
  deploy:
    docker:
      - image: cimg/base:current
    steps:
      - checkout

      - run:
          name: Install Twingate
          command: |
            echo "deb [trusted=yes] https://packages.twingate.com/apt/ /" | sudo tee /etc/apt/sources.list.d/twingate.list
            sudo apt update -yq
            sudo apt install -yq twingate

      - run:
          name: Start Twingate headless
          command: |
            echo "$SERVICE_KEY" | sudo twingate setup --headless=-
            sudo twingate start

      - run:
          name: Sync kubeconfig and deploy
          command: |
            twingate kube config sync
            kubectl --context=my-cluster get pods

Set the SERVICE_KEY environment variable in your CircleCI project settings to the Service Key from the Twingate Admin Console.

GitHub Actions example

name: Deploy to Kubernetes
on: [push]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Twingate
        run: |
          echo "deb [trusted=yes] https://packages.twingate.com/apt/ /" | sudo tee /etc/apt/sources.list.d/twingate.list
          sudo apt update -yq
          sudo apt install -yq twingate

      - name: Start Twingate headless
        env:
          TWINGATE_SERVICE_KEY: ${{ secrets.SERVICE_KEY }}
        run: |
          echo $TWINGATE_SERVICE_KEY | sudo twingate setup --headless=-
          sudo twingate start

      - name: Sync kubeconfig and deploy
        run: |
          twingate kube config sync
          kubectl --context=my-cluster get pods

For more CI/CD examples and general headless Client setup, see CI/CD Configuration and Linux Headless Mode.

How it works

When you run twingate kube config sync, the Twingate Client:

Queries the Twingate Controller for all Kubernetes Cluster Resources the user has access to.
Writes a kubeconfig context for each Resource to the standard kubeconfig file (~/.kube/config by default, or the path specified by KUBECONFIG).
Configures each context to route kubectl traffic through the Twingate Client to the cluster via the Connector and Gateway.

The resulting kubeconfig contexts are standard Kubernetes contexts. Any tool that reads kubeconfig (Helm, Skaffold, k9s, Lens, etc.) works without modification.

Troubleshooting

twingate kube config sync returns no resources

Cause: The user or Service Account does not have access to any Kubernetes Cluster Resources, or the Twingate Client is not authenticated.

Fix:

Verify the Twingate Client is running and connected: twingate status.
Check that Kubernetes Resources are assigned to the user’s Group in the Admin Console.
Ensure the Resources are of type Kubernetes Cluster (set up via the Kubernetes Operator with Privileged Access).

kubectl returns connection errors after sync

Cause: The Twingate Client is not running, or the Connector serving the Resource is offline.