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(hostandport) registers the Gateway under an explicit address instead of the one resolved from itsService. Use it when Connectors reach the Gateway through a proxy, an ingress controller, aNodePort, 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 Requestwhen a request’s host doesn’t belong to the Resource the connection was opened for. - Web Apps: The
X-Forwarded-Protoheader 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, orcas - Helm values:
tls,ssh.ca,auditLog, or theTWINGATE_DEBUGenvironment variable - Command line: the
--debugor-dflag - Log filters: session recordings selected by the
gateway.auditlogger name
TLS certificates
The Gateway can now serve more than one certificate.
- Configuration file:
tls.certificateFileandtls.privateKeyFilebecome an entry in thetls.certificates.fileslist. - Helm values:
tls.dnsNames,tls.ipAddresses, andtls.autoGeneratedmove undertls.certificates.autoGenerated.tls.existingSecretand inlinetls.cert,tls.key, andtls.cabecome entries intls.certificates.secrets. The boolean formtls.autoGenerated: trueis removed.
Before (1.x):
tls: autoGenerated: enabled: true dnsNames: ["acme.int"]After (2.0):
tls: certificates: autoGenerated: enabled: true dnsNames: ["acme.int"]Upgrade behavior to check
- Setting
tls.certificates.secretsno longer turns off auto-generation. Settls.certificates.autoGenerated.enabled: falseto supply every certificate yourself. - An auto-generated certificate and its CA are reissued on upgrade, even if the names are unchanged. The Twingate Operator registers the new CA. Anything else that pinned the old CA must trust the new one.
- The chart adds in-cluster Kubernetes names only when the Kubernetes proxy is enabled. List any other names you need in
tls.certificates.autoGenerated.dnsNames, or the release fails to render. certManager.commonNameis left out of the certificate unless you set it.
SSH certificate authority
ssh.ca.manualbecomesssh.ca.localin the configuration file and Helm values.- Helm values only:
-
ssh.ca.manual.existingSecretbecomesssh.ca.local.secretName. -
ssh.ca.vault.existingCABundleSecretbecomesssh.ca.vault.caBundleConfigMapName. The bundle is now a ConfigMap, so create one with the sameca.crtkey before upgrading. -
ssh.ca.vault.auth.appRole.existingSecretIdSecretbecomesssh.ca.vault.auth.appRole.secretIdSecretName. -
ssh.ca.vault.auth.tokenandssh.ca.vault.auth.existingTokenSecretare removed. Pass the token as theVAULT_TOKENenvironment variable throughextraEnvVars:extraEnvVars:- name: VAULT_TOKENvalueFrom: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: debugSession recording
auditLog moves to log.sessionRecording.segment in the configuration file and Helm values:
| Before (1.x) | After (2.0) |
|---|---|
auditLog.flushInterval | log.sessionRecording.segment.maxDuration |
auditLog.flushSizeThreshold | log.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.
Upgrade the Operator first
Setting twingateOperator.gateway.enabled=true requires Twingate Kubernetes Operator v2 with its CRDs applied. Follow the Operator’s v1 to v2 migration guide before upgrading the Gateway.
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