Upgrading the Gateway

Changes to the Gateway configuration file and Helm values between versions.

Major Gateway versions rename or move configuration values. This page lists what changes and whether it affects you. The Gateway repository has full migration guides with before-and-after examples for every setting:

If you install the Gateway as a subchart of the Twingate Kubernetes Operator, the Helm values below sit under the gateway: key. The Operator chart bundles Gateway 2.0 from Operator v3. See the Operator’s v2 to v3 migration guide.

Gateway 2.1

Upgrading from 2.0 needs no configuration or Helm changes.

  • New optional Helm value: twingateOperator.gateway.address (host and port) registers the Gateway under an explicit address instead of the one resolved from its Service. Use it when Connectors reach the Gateway through a proxy, an ingress controller, a NodePort, or a private endpoint. It requires Twingate Kubernetes Operator 3.1.0 or later.
  • HTTP/2: Kubernetes and Web App connections can now use HTTP/2.
  • Misdirected requests: The Gateway responds with 421 Misdirected Request when a request’s host doesn’t belong to the Resource the connection was opened for.
  • Web Apps: The X-Forwarded-Proto header now reflects whether the client connected with TLS.

Gateway 2.0

Gateway 2.0 changes the configuration file and Helm values for TLS certificates, the SSH certificate authority, debug logging, and session recording. You are affected if you set any of these:

  • Configuration file: tls, ssh.ca.manual, auditLog, or cas
  • Helm values: tls, ssh.ca, auditLog, or the TWINGATE_DEBUG environment variable
  • Command line: the --debug or -d flag
  • Log filters: session recordings selected by the gateway.audit logger name

TLS certificates

The Gateway can now serve more than one certificate.

  • Configuration file: tls.certificateFile and tls.privateKeyFile become an entry in the tls.certificates.files list.
  • Helm values: tls.dnsNames, tls.ipAddresses, and tls.autoGenerated move under tls.certificates.autoGenerated. tls.existingSecret and inline tls.cert, tls.key, and tls.ca become entries in tls.certificates.secrets. The boolean form tls.autoGenerated: true is removed.

Before (1.x):

tls:
autoGenerated:
enabled: true
dnsNames: ["acme.int"]

After (2.0):

tls:
certificates:
autoGenerated:
enabled: true
dnsNames: ["acme.int"]

SSH certificate authority

  • ssh.ca.manual becomes ssh.ca.local in the configuration file and Helm values.
  • Helm values only:
    • ssh.ca.manual.existingSecret becomes ssh.ca.local.secretName.

    • ssh.ca.vault.existingCABundleSecret becomes ssh.ca.vault.caBundleConfigMapName. The bundle is now a ConfigMap, so create one with the same ca.crt key before upgrading.

    • ssh.ca.vault.auth.appRole.existingSecretIdSecret becomes ssh.ca.vault.auth.appRole.secretIdSecretName.

    • ssh.ca.vault.auth.token and ssh.ca.vault.auth.existingTokenSecret are removed. Pass the token as the VAULT_TOKEN environment variable through extraEnvVars:

      extraEnvVars:
      - name: VAULT_TOKEN
      valueFrom:
      secretKeyRef:
      name: "vault-token"
      key: "token"

VAULT_TOKEN applies to every Vault client in the Gateway. If you use Vault for both the SSH CA and TLS certificates, the one token needs access to both. Use AppRole for one of them to keep the credentials separate.

Debug logging

The --debug flag, its -d short form, and the TWINGATE_DEBUG environment variable are removed. Starting the Gateway with the flag fails. Set the level in the configuration file or Helm values instead:

log:
system:
level: debug

Session recording

auditLog moves to log.sessionRecording.segment in the configuration file and Helm values:

Before (1.x)After (2.0)
auditLog.flushIntervallog.sessionRecording.segment.maxDuration
auditLog.flushSizeThresholdlog.sessionRecording.segment.maxSize

maxSize is now a quoted size string such as "64KiB". Its default drops from 1MB (1,000,000 bytes) to 64KiB, and it is capped at 256KiB, so lower any larger value you set.

The session recording logger name changes from gateway.audit to session_recording. Update log filters and routing rules that match on it. See Session Recordings.

Upstream trusted CA bundles

This applies only to the configuration file, when upgrading from 1.1. cas becomes upstreamTrustedCABundles, each entry’s certFile becomes file, and name is removed.

Gateway 1.0

Gateway 1.0 replaces annotations on the Gateway Service with Twingate custom resources. The chart renders a TwingateGateway, a TwingateCertificateAuthority, and optionally a Kubernetes TwingateResource for the cluster’s API server.

You are affected if your Helm values set twingate.resource.*. Installs that followed the Twingate Operator setup set it. Standalone Gateway chart installs are affected only if you set it yourself.

Move twingate.resource.* to twingateOperator.gateway.* and twingateOperator.kubernetesResource.*.

Before (0.21):

twingate:
network: "<network-name>"
resource:
enabled: true
extraAnnotations:
resource.twingate.com/name: "My Kubernetes Cluster"
resource.twingate.com/alias: "my-k8s-cluster.int"

After (1.0):

twingate:
network: "<network-name>"
twingateOperator:
gateway:
enabled: true
kubernetesResource:
enabled: true
name: "My Kubernetes Cluster"
alias: "my-k8s-cluster.int"

Any TwingateResource spec field, such as securityPolicyId, can be set under twingateOperator.kubernetesResource. The chart owns type, address, and gatewayRef, and the Remote Network comes from twingateOperator.remoteNetworkId.

In the names below, <fullname> is <release>-gateway, or just <release> if the release name already contains gateway. For example, with the Operator’s twop release it is twop-gateway.

The in-cluster TwingateResource keeps its Kubernetes object name, <fullname>-resource, so existing TwingateResourceAccess references still resolve. If you never set a display name, the name in the Admin Console changes from <fullname>-resource to <fullname> Kubernetes cluster. Set twingateOperator.kubernetesResource.name to keep the old name. Access is unchanged.

Certificate authority name

The chart registers the certificate authority with Twingate as <fullname>-ca-<hash>. The name must be unique in your network and can’t be changed after creation. The hash is read from the cluster at render time, so rendering fails without Kubernetes API access, as with ArgoCD, helm template, or --dry-run=client. In those cases, set the name yourself:

twingateOperator:
gateway:
enabled: true
certificateAuthority:
name: "<a name unique within your Twingate network>"

Last updated