Quick Start Guide

Prerequisites

Before you begin, make sure you have:

• A Kubernetes cluster (v1.31+)
• A Twingate account with administrator privileges
• Helm installed
• kubectl installed

Installation

The easiest way to install the Twingate Kubernetes Access Gateway is using the Twingate Kubernetes Operator.

Step 1: Prepare your Twingate network

• Log in to your Twingate Admin console at https://<network-name>.twingate.com
• Create a new Remote Network that represents your Kubernetes cluster:
  • Navigate to Network tab > Remote Networks and click the "+ Remote Network" button.
  • Take note of the Remote Network ID from the URL: https://<network-name>.twingate.com/networks/<remote-network-id>.
• Create an API key:
  • Go to Settings > API (or navigate to https://<network-name>.twingate.com/settings/api)
  • Create a new API key with "Read, Write, & Provision" permissions
  • Save the API key securely - you won't be able to see it again

Step 2: Install the Twingate Kubernetes Operator and the Gateway using Helm

• Create values.yaml with the following content:

twingateOperator:
  apiKey: "<the API key from step 1>"
  network: "<network-name>"
  remoteNetworkId: "<the ID of the Remote Network from step 1>"

kubernetes-access-gateway:
  enabled: true  # Enable Gateway subchart
  twingate:
    network: <network-name>
    resource:
      # Annotate Gateway service as a Twingate resource
      enabled: true
      extraAnnotations:
        resource.twingate.com/name: "My Kubernetes Cluster"
        resource.twingate.com/alias: "my-k8s-cluster.int"

• Install the Twingate Kubernetes Operator:

helm upgrade twop oci://ghcr.io/twingate/helmcharts/twingate-operator --install --wait -f ./values.yaml

• Upon successful installation, you should see 2 pods created: one for the operator and one for the gateway.

$ kubectl get pods
NAME                                              READY   STATUS    RESTARTS   AGE
twop-kubernetes-access-gateway-857d66957f-8hbzx   1/1     Running   0          55s
twop-twingate-operator-6f5798f47c-kxnck           1/1     Running   0          55s

• There should be a TwingateResource created by the operator. This resource represents the Kubernetes API Server of the cluster.

$ kubectl get twingateresources
NAME                                      ID                         DISPLAY NAME            ADDRESS                                ALIAS                AGE
twop-kubernetes-access-gateway-resource   UmVzb3VyY2U6Mjk2OTI1Mw==   My Kubernetes Cluster   kubernetes.default.svc.cluster.local   my-k8s-cluster.int   67s

• After a few moments, a Resource should be created and visible in Twingate Admin Console. Assign your user or group to the Resource.

• When a user connects to the Resource, Twingate forwards their authenticated identity to the Kubernetes cluster. As a result, you will need to configure Kubernetes RBAC using ClusterRoleBindings or RoleBindings to authorize user actions based on this identity.

Step 3: Install a connector

The Gateway is now installed but in order for Twingate Client to reach the Gateway, we need to install a Connector.

• Create connector.yaml with the following content:

apiVersion: twingate.com/v1beta
kind: TwingateConnector
metadata:
  name: my-connector
spec:
  # Auto update the connector image every day
  imagePolicy:
    schedule: "0 0 * * *"

• Install the connector:

kubectl apply -f connector.yaml

• There should be a TwingateConnector created by the operator.

$ kubectl get twingateconnectors
NAME           ID                         DISPLAY NAME       AGE
my-connector   Q29ubmVjdG9yOjU0NzQ0MQ==   indigo-spoonbill   10s

• After a few moments, a connector should be created and visible in Twingate Admin Console.

Step 4: Connect to the Kubernetes cluster via the Gateway

• Install the latest Twingate Client from the Twingate website.

  • Minimum Client version is 2025.175. Privileged Access is only available on macOS, Windows, and Linux platforms.

• In your client, you should see the "My Kubernetes Cluster" resource. Hovering the resource should show the "Sync Kubernetes Configuration" button.

• Click the button. A new twingate-my-kubernetes-cluster context will be added to your ~/.kube/config file.

• Now you can connect to the cluster using the new context. You should see your Twingate username and the groups that allow you to access to the "My Kubernetes Cluster" resource.

$ kubectl --context twingate-my-kubernetes-cluster auth whoami
ATTRIBUTE   VALUE
Username    [email protected]
Groups      [Everyone system:authenticated]

Congratulations! You have successfully installed the Twingate Kubernetes Access Gateway.