Kubernetes Overview

Authentication

The Twingate Client authenticates to the Gateway using a Gateway Access Token (GAT). See How It Works for details. The Gateway handles authentication to the Kubernetes API server on behalf of the user - kubectl does not need a bearer token or client certificate.

The Gateway connects to the Kubernetes API server using a service account token and forwards the Twingate user's identity using Kubernetes impersonation headers.

• In-cluster: When the Gateway is deployed inside the protected Kubernetes cluster, it uses the token of the service account associated with the Gateway pod. The Gateway Helm chart creates a dedicated service account with the required permissions.
• Out-cluster: When the Gateway is deployed outside the protected Kubernetes cluster, it must be configured with a service account token that has the required permissions.

Authorization

Kubernetes RBAC authorization can be configured based on Twingate identity forwarded by the Gateway via impersonation headers.

The Gateway forwards the Twingate user's email and groups to the Kubernetes API server. Only groups that grant the user access to the Kubernetes resource are forwarded.

$ kubectl --context twingate-k8s-cluster auth whoami
ATTRIBUTE   VALUE
Username    alex@acme.com
Groups      [engineering on-call twingate:authenticated system:authenticated]

For Twingate service accounts, the Gateway forwards the key ID as the username, and the service account's name and ID as groups to the Kubernetes API server.

$ kubectl --context twingate-k8s-cluster auth whoami
ATTRIBUTE   VALUE
Username    <service-account-key-id>
Groups      [<service-account-name> <service-account-id> twingate:service-accounts twingate:authenticated system:authenticated]

Special groups:

• twingate:authenticated: All entities authenticated by Twingate
• twingate:service-accounts: All service accounts authenticated by Twingate

These groups are only meaningful for Kubernetes RBAC, so they are forwarded only for Kubernetes resources. A GAT issued for an SSH or web app resource carries only the groups that grant access to that resource.

Audit

The Gateway logs all API requests and interactive sessions (e.g. kubectl exec), which can be forwarded to a storage system. See Session Recordings for collection and storage options.

kubeconfig Sync

After a user is given access to a Kubernetes resource, the Twingate Client syncs the kubeconfig file (~/.kube/config) with the resource's cluster address and CA certificate. The synced kubeconfig does not contain any credentials - there are no tokens or client certificates to rotate or manage.

Auto-sync is recommended to keep the kubeconfig updated as resources are added or removed. Users can also sync manually for a specific resource or all resources at once.

Resource Address

Like Network resources in Twingate, a Kubernetes resource's address should point to the final destination - the Kubernetes API server that the Gateway can reach.

Multiple Clusters with the Same Address

When the Gateway is deployed inside the protected Kubernetes cluster, multiple Kubernetes resources may share the same address, e.g. kubernetes.default.svc.cluster.local. To distinguish between them, use resource aliases:

• Resource A
  • Address: kubernetes.default.svc.cluster.local
  • Alias: cluster-a.int
• Resource B
  • Address: kubernetes.default.svc.cluster.local
  • Alias: cluster-b.int

The Twingate Client uses the resource aliases instead of the addresses when syncing kubeconfig. Each resource gets a unique context in ~/.kube/config, allowing users to switch between clusters even when they share the same underlying address.