Getting Started

The Twingate Operator's goal is to make exposing services running on Kubernetes via Twingate as easy as possible.

This guide will show you how to deploy the Twingate Operator and define your first TwingateResource.

Pre-requisites

Before you begin, ensure you have:

• A Kubernetes cluster (v1.16+) with admin permissions
• kubectl configured to access your cluster
• Helm v3 installed
• A Twingate account with admin access

Installing the Operator

1. Set up your Twingate network:
   1. Log in to your Twingate Admin console at https://<network-name>.twingate.com
   2. Create a new Remote Network for your Kubernetes cluster:
      • Navigate to Network tab > Remote Networks and click the "+Remote Network" button.
      • Note the Remote Network ID from the URL: https://<network-name>.twingate.com/networks/<remote-network-id>.
   3. 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
2. Create a values.yaml with the following values:

twingateOperator:
  apiKey: "<the api key from step 1>"
  network: "<network slug>"
  remoteNetworkId: "<the id of the remote network from step 1>"

(You can look at reference values.yaml to see the full list of configuration values)

1. Install the operator using Helm (add -n [namespace] if you want to install to a specific namespace):

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

The Twingate Operator introduces new custom resources definitions (CRDs) to Kubernetes to allow declaring various Twingate related settings as Kubernetes objects and have their settings sync to Twingate. You can see the full references for these CRDs at the API Reference. For this guide the CRDs of interest are:

• TwingateConnector
• TwingateResource
• TwingateResourceAccess

Deploy a Connector to connect your cluster to Twingate

In order to start exposing resources on your cluster via Twingate, you first need to run a Twingate Connector on your cluster. To do that we simply need to define a TwingateConnector resource:

apiVersion: twingate.com/v1beta
kind: TwingateConnector
metadata:
  name: my-connector
spec:
  imagePolicy:
    provider: dockerhub
    schedule: "0 0 * * *"

This will:

1. Have the operator provision a new connector and deploy it to the cluster
2. Configure automatic updates through the imagePolicy:
   • provider: dockerhub - pulls updates from Docker Hub
   • schedule: "0 0 * * *" - checks for updates daily at midnight UTC

For more details on image policy configuration, see the imagePolicy documentation.

Defining your first Twingate Resource

Let's create a Twingate resource for an existing Kubernetes service. In this example, we'll use a service named foo in the default namespace:

• Internal DNS name: foo.default.svc.cluster.local
• Twingate alias: foo.local (this will be the hostname users use to access the service)

Create a TwingateResource with the following configuration:

apiVersion: twingate.com/v1beta
kind: TwingateResource
metadata:
  name: foo
spec:
  name: Foo
  address: foo.default.svc.cluster.local
  alias: foo.local

(Instead of working directly with TwingateResource object you can also annotate the service and have the operator create the resource for you)

Now, lets also configure who can access this resource using TwingateResourceAccess. TwingateResourceAccess expects a principal which is a Group\ServiceAccount that we want to give access to. We can specify the principal by principalId which is an ID for a Group\Service-Account or we can reference it by name using principalExternalRef. Lets assume we have a DevOps Engineers group that we want to allow accessing this resource:

apiVersion: twingate.com/v1beta
kind: TwingateResourceAccess
metadata:
  name: foo-devops-access
spec:
  resourceRef:
    name: foo
    namespace: default
  principalExternalRef:
    type: group
    name: DevOps Engineers