Web App 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

This guide deploys a small demo web app into the cluster so you can see the Gateway inject your Twingate identity as request headers. Once you understand the flow, you can point the Gateway at your own web application instead.

Installation

The easiest way to install the 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 environment:
  • 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 Operator and Gateway with the Web App proxy enabled

• Create values.yaml with the following content. Note that <network-name> is the name of your Twingate Network i.e. you access Twingate via https://<network-name>.twingate.com.

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

gateway:
  enabled: true  # Enable Gateway subchart
  twingate:
    network: <network-name>
  tls:
    dnsNames:
      # Include the resource alias and address in the TLS certificate served by the Gateway
      - "app.int"                            # resource alias
      - "httpbin.default.svc.cluster.local"  # resource address
  webApp:
    enabled: true

• Install the Twingate Kubernetes Operator and the Gateway:

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-gateway-857d66957f-8hbzx              1/1     Running   0          55s
twop-twingate-operator-6f5798f47c-kxnck    1/1     Running   0          55s

Step 3: Deploy and expose the demo web app

Deploy go-httpbin, a tiny HTTP request/response service. Its /headers endpoint echoes back the request headers it receives, which lets you confirm that the Gateway injects your Twingate identity.

The Service carries resource.twingate.com/* annotations so the operator creates the Web App resource for you, bound to the Gateway from Step 2. This avoids a separate TwingateResource. See the operator's Annotating a Service guide for the full list of supported annotations.

• Create httpbin.yaml with the following content:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: httpbin
spec:
  replicas: 1
  selector:
    matchLabels:
      app: httpbin
  template:
    metadata:
      labels:
        app: httpbin
    spec:
      containers:
        - name: httpbin
          image: ghcr.io/mccutchen/go-httpbin
          ports:
            - containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
  name: httpbin
  annotations:
    resource.twingate.com: "true"
    resource.twingate.com/type: "WebApp"
    resource.twingate.com/name: "Demo Web App"
    resource.twingate.com/gatewayName: "twop-gateway"
    resource.twingate.com/alias: "app.int"
    resource.twingate.com/downstreamPort: "80"
    resource.twingate.com/requestHeaderRewrites: '{"Authorization": "Bearer {{jwt}}"}'
spec:
  selector:
    app: httpbin
  ports:
    - port: 8080
      targetPort: 8080

• Deploy it:

kubectl apply -f httpbin.yaml

This creates a Service reachable at httpbin.default.svc.cluster.local:8080, and the operator reconciles the annotations into a Web App resource.

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

Step 4: 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

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

Step 5: Connect to the web app via the Gateway

• Install the latest Twingate Client from the Twingate website.

• In your client, you should see the "Demo Web App" resource.

• Open the demo app's headers endpoint in your browser using the resource alias:

http://app.int/headers

The Twingate Client routes the request to the Gateway, which forwards it to the demo app and injects your Twingate identity as request headers. The /headers endpoint returns the headers it received, so you should see the injected identity, for example:

{
  "headers": {
    "Authorization": "Bearer <a JWT signed by Twingate>"
  }
}

Congratulations! You have successfully set up web app access via the Gateway. To protect your own application instead, move these annotations onto your own Service and remove the httpbin deployment.