Repository navigation
Migration 1.0 to 2.0
Gateway 2.0 changes the Gateway configuration file for TLS certificates, the SSH certificate authority, debug logging, session recording and the upstream trusted CA bundles.
If you deploy Gateway via the Helm chart, Gateway 2.0 also changes the Helm values file for TLS certificates, the SSH certificate authority, debug logging and session recording.
Important
The migration below applies only if you have configured these fields in:
Config file: tls, ssh.ca.manual, auditLog or cas
Helm values file: tls, ssh.ca, auditLog or the TWINGATE_DEBUG environment variable
Command line: Use of --debug flag
Log filtering: session recordings selected by the gateway.audit logger name
-
TLS certificates: the certificate and private key file paths move into a list under
tls.certificates.files, so the Gateway can serve more than one certificate. -
SSH certificate authority:
ssh.ca.manualis renamed tossh.ca.local. -
Debug logging: the
--debugflag is removed. Setlog.system.leveltodebuginstead. -
Session recording:
auditLogmoves tolog.sessionRecording.segment, and session recording's log name is renamed fromgateway.audittosession_recording. -
Upstream trusted CA bundles (1.1 only):
casis renamed toupstreamTrustedCABundles.
In 1.0, the Helm chart serves either an auto-generated TLS certificate, an existing TLS certificate from a Secret, or an inline certificate. In 2.0, it serves multiple TLS certificates and can use all three sources at the same time. The tls.dnsNames and tls.ipAddresses values move under tls.certificates.autoGenerated.
The TWINGATE_DEBUG environment variable no longer turns on debug logging, so set log.system.level to debug instead.
The SSH certificate authority and session recording values are renamed and moved to match the config file. See Breaking Change for the full details.
-
tls.certificateFileandtls.privateKeyFilebecome an entry in thetls.certificates.fileslist. Each entry takes the samecertificateFileandprivateKeyFilefields.
-
tls.existingSecretand the inlinetls.cert/tls.key/tls.cabecome entries in thetls.certificates.secretslist. -
tls.autoGeneratedbecomestls.certificates.autoGenerated, andtls.ipAddressesandtls.dnsNamesmove undertls.certificates.autoGenerated. - Support for
tls.autoGenerated: booleanis dropped. The boolean form was deprecated in 1.0 and is now removed, usetls.certificates.autoGenerated.enabled. - Auto-generation no longer switches itself off. In 1.0, setting
tls.existingSecretstopped the chart generating a self-signed certificate. In 2.0, settingtls.certificates.secretsdoes not switch auto-generation off, so settls.certificates.autoGenerated.enabled: falsewhen you want to supply every certificate yourself.
-
ssh.ca.manualbecomesssh.ca.localin both the config file and the Helm values file.
The rest of the changes apply to the Helm values file only:
- The
existingSecretfield underssh.ca.manualis renamed tosecretName. -
ssh.ca.vault.existingCABundleSecretbecomesssh.ca.vault.caBundleConfigMapName. The Vault CA bundle is stored in a ConfigMap instead of a Secret, so you have to re-create one holding the sameca.crtkey. -
ssh.ca.vault.auth.appRole.existingSecretIdSecretbecomesssh.ca.vault.auth.appRole.secretIdSecretName. - Vault token authentication is no longer a value field. Pass the token as the
VAULT_TOKENenvironment variable throughextraEnvVars.
- The
--debugflag and its-dshort form are removed. Starting the Gateway with either one now fails, so remove the flag. - The
TWINGATE_DEBUGenvironment variable is no longer read, so setting it has no effect. - Set
log.system.leveltodebugin the config file or the Helm values file to turn on debug logging.
auditLog becomes log.sessionRecording.segment in both the config file and the Helm values file, and in the Helm values file the size limit is now a quoted size rather than a number. The size limit is capped at 256KB, and its default drops from 1MB to 64KB.
The session recording logger name is renamed from gateway.audit to session_recording. No config file or Helm values file change is needed, but if you filter or route logs by logger name, update the filter.
This change only applies to the config file and if you are upgrading from 1.1.
-
casbecomesupstreamTrustedCABundles. - The
certFilefield in each entry is renamed tofile. - The
namefield is removed. Each entry must point at a different file instead.
In 1.0:
tls:
certificateFile: "/etc/gateway/tls/tls.crt"
privateKeyFile: "/etc/gateway/tls/tls.key"In 2.0:
tls:
certificates:
files:
- certificateFile: "/etc/gateway/tls/tls.crt"
privateKeyFile: "/etc/gateway/tls/tls.key"| Scenario | Before (1.0) | After (2.0) |
|---|---|---|
| Point the certificate at an existing Secret. |
tls:
existingSecret: "tls-secret" |
tls:
certificates:
autoGenerated:
enabled: false
secrets:
- name: "tls-secret" |
| Helm chart generates a self-signed certificate. |
tls:
autoGenerated:
enabled: true
ipAddresses: ["10.0.0.1"]
dnsNames: ["acme.int"] |
tls:
certificates:
autoGenerated:
enabled: true
ipAddresses: ["10.0.0.1"]
dnsNames: ["acme.int"] |
| Inline the certificate content. |
tls:
autoGenerated:
enabled: false
cert: "<certificate PEM>"
key: "<private key PEM>"
ca: "<CA certificate PEM>" |
tls:
certificates:
autoGenerated:
enabled: false
secrets:
- cert: "<certificate PEM>"
key: "<private key PEM>"
ca: "<CA certificate PEM>" |
For both self-signed and cert-manager certificates, the chart adds the in-cluster Kubernetes names only when the Gateway's Kubernetes proxy is enabled. List the names you need under tls.certificates.autoGenerated.dnsNames, otherwise the release fails to render.
If Helm chart generates your certificate, upgrading to 2.0 replaces it and the CA that signed it, even when the names it covers are unchanged. The Twingate Kubernetes Operator picks up the new CA on its own. Anything else that pinned the old CA has to trust the new one.
A cert-manager certificate is reissued only if the change above alters the names it covers.
tls.autoGenerated.certManager becomes tls.certificates.autoGenerated.certManager and keeps its fields. certManager.commonName is now left out of the certificate when you do not set it. In 1.0, it was filled in with the Gateway's name.
In 1.0:
ssh:
ca:
manual:
privateKeyFile: "/etc/gateway/ssh/ca-private-key"In 2.0:
ssh:
ca:
local:
privateKeyFile: "/etc/gateway/ssh/ca-private-key"The table lists each 1.0 value and the 2.0 value that replaces it. Move your settings to the new names.
| Before (1.0) | After (2.0) |
|---|---|
ssh.ca.manual |
ssh.ca.local |
ssh.ca.manual.existingSecret |
ssh.ca.local.secretName |
ssh.ca.vault.existingCABundleSecret |
ssh.ca.vault.caBundleConfigMapName |
ssh.ca.vault.auth.appRole.existingSecretIdSecret |
ssh.ca.vault.auth.appRole.secretIdSecretName |
ssh.ca.vault.auth.existingTokenSecret |
Removed. See Vault token authentication. |
ssh.ca.vault.auth.token |
Removed. See Vault token authentication. |
The CA bundle moves from a Secret to a ConfigMap, so re-create one in ConfigMap from the bundle you already hold before you upgrade, keeping the ca.crt key.
The config file is unchanged, so this section applies to the Helm values file only.
The ssh.ca.vault.auth.token and ssh.ca.vault.auth.existingTokenSecret values are removed. Set the Vault token as the VAULT_TOKEN environment variable through extraEnvVars instead.
In the 1.0 Helm values file:
ssh:
ca:
vault:
auth:
existingTokenSecret: "vault-token"In the 2.0 Helm values file:
extraEnvVars:
- name: VAULT_TOKEN
valueFrom:
secretKeyRef:
name: "vault-token"
key: "token"The Secret is unchanged, so an existing one works as it is.
Important
VAULT_TOKEN is set on the Gateway container, so it reaches every Vault client the Gateway runs. If you use Vault for both the SSH certificate authority and TLS automation, this one token covers both of them, and it needs access to everything each of them signs. Configure AppRole on one of them if they have to use separate credentials.
In 1.0, debug logging is turned on with the --debug flag on the command line:
./gateway start --config config.yaml --debugIn 2.0, remove the flag and set the level in the config file:
log:
system:
level: debugIn 1.0, debug logging is turned on with the TWINGATE_DEBUG environment variable:
extraEnvVars:
- name: TWINGATE_DEBUG
value: "true"In 2.0, remove the environment variable and set the level in the Helm values file:
log:
system:
level: debugThe keys are the same in the config file and the Helm values file, so the table and example below apply to both files. Move your settings to the new names.
| Before (1.0) | After (2.0) |
|---|---|
auditLog.flushInterval |
log.sessionRecording.segment.maxDuration |
auditLog.flushSizeThreshold |
log.sessionRecording.segment.maxSize |
Recordings are still split into segments the same way, but the size limit is now capped at 256KB and defaults to 64KB. In 1.0, the default of 1MB is above the cap, so lower it if you set it explicitly.
maxSize now takes a size as a string, such as "64KB". A number with no unit is read as bytes. These are the supported units:
| Unit type | Units | Example |
|---|---|---|
| Bytes | No unit, or B
|
"64000" is 64,000 bytes |
| Decimal (multiples of 1000) |
KB or K
|
"64KB" is 64,000 bytes |
| Binary (multiples of 1024) |
KiB or Ki
|
"64KiB" is 65,536 bytes |
Note that a binary value such as "256KiB" (262,144 bytes) is over the 256KB cap and rejected.
In 1.0 config file or Helm values file:
auditLog:
flushInterval: 5m
flushSizeThreshold: 64000In 2.0 config file or Helm values file:
log:
sessionRecording:
segment:
maxDuration: 5m
maxSize: "64KB"If you filter or route session recordings by the logger field, it is renamed gateway.audit to session_recording. The other fields of a session recording log are unchanged. Here's a before and after sample of session recording logs:
| Before (1.0) | After (2.0) |
|---|---|
{
"levelname": "info",
"ts": "2026-10-15T08:16:10.176Z",
"logger": "session_recording", // ⬅️ New name
"caller": "...",
"message": "session finished",
"version": "2.0.0",
"request_id": "...",
"requested_at": "2026-10-15T08:16:07.167Z",
"method": "GET",
"url": "...",
"remote_addr": "...",
"user": { ... },
"conn_id": "...",
"asciicast": "...",
"asciicast_sequence_num": 1
} |
This section applies to the config file only, when you are upgrading from 1.1.
| Before (1.1) | After (2.0) |
|---|---|
cas |
upstreamTrustedCABundles |
cas[].certFile |
upstreamTrustedCABundles[].file |
cas[].name |
Removed. |
In 1.1 config file:
cas:
- name: "internal-ca"
certFile: "/etc/gateway/ca/internal-ca.crt"In 2.0 config file:
upstreamTrustedCABundles:
- file: "/etc/gateway/ca/internal-ca.crt"Copyright © 2025 Twingate.
Kubernetes
SSH
Web App
Operations
Development
Migration
{ "levelname": "info", "ts": "2026-10-15T08:16:10.176Z", "logger": "gateway.audit", // ⬅️ Old name "caller": "...", "message": "session finished", "version": "1.0.0", "request_id": "...", "requested_at": "2026-10-15T08:16:07.167Z", "method": "GET", "url": "...", "remote_addr": "...", "user": { ... }, "conn_id": "...", "asciicast": "...", "asciicast_sequence_num": 1 }