Skip to content

Migration 1.0 to 2.0

Clement Tee edited this page Oct 15, 2026 · 6 revisions

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

What changed

Config file

  • 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.manual is renamed to ssh.ca.local.
  • Debug logging: the --debug flag is removed. Set log.system.level to debug instead.
  • Session recording: auditLog moves to log.sessionRecording.segment, and session recording's log name is renamed from gateway.audit to session_recording.
  • Upstream trusted CA bundles (1.1 only): cas is renamed to upstreamTrustedCABundles.

Helm values file

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.

Breaking Change

TLS certificates

Config file

  • tls.certificateFile and tls.privateKeyFile become an entry in the tls.certificates.files list. Each entry takes the same certificateFile and privateKeyFile fields.

Helm values file

  • tls.existingSecret and the inline tls.cert / tls.key / tls.ca become entries in the tls.certificates.secrets list.
  • tls.autoGenerated becomes tls.certificates.autoGenerated, and tls.ipAddresses and tls.dnsNames move under tls.certificates.autoGenerated.
  • Support for tls.autoGenerated: boolean is dropped. The boolean form was deprecated in 1.0 and is now removed, use tls.certificates.autoGenerated.enabled.
  • Auto-generation no longer switches itself off. In 1.0, setting tls.existingSecret stopped the chart generating a self-signed certificate. In 2.0, setting tls.certificates.secrets does not switch auto-generation off, so set tls.certificates.autoGenerated.enabled: false when you want to supply every certificate yourself.

SSH certificate authority

  • ssh.ca.manual becomes ssh.ca.local in both the config file and the Helm values file.

The rest of the changes apply to the Helm values file only:

  • The existingSecret field under ssh.ca.manual is renamed to secretName.
  • ssh.ca.vault.existingCABundleSecret becomes ssh.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 same ca.crt key.
  • ssh.ca.vault.auth.appRole.existingSecretIdSecret becomes ssh.ca.vault.auth.appRole.secretIdSecretName.
  • Vault token authentication is no longer a value field. Pass the token as the VAULT_TOKEN environment variable through extraEnvVars.

Debug logging

  • The --debug flag and its -d short form are removed. Starting the Gateway with either one now fails, so remove the flag.
  • The TWINGATE_DEBUG environment variable is no longer read, so setting it has no effect.
  • Set log.system.level to debug in the config file or the Helm values file to turn on debug logging.

Session recording

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.

Upstream trusted CA bundles

This change only applies to the config file and if you are upgrading from 1.1.

  • cas becomes upstreamTrustedCABundles.
  • The certFile field in each entry is renamed to file.
  • The name field is removed. Each entry must point at a different file instead.

Update your values

TLS certificates

Config file

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"

Helm values file

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>"
In-cluster Kubernetes names

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.

Self-signed certificates are reissued on upgrade

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.

cert-manager

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.

SSH certificate authority

Config file

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"

Helm values file

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.

Vault token authentication

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.

Debug logging

Config file

In 1.0, debug logging is turned on with the --debug flag on the command line:

./gateway start --config config.yaml --debug

In 2.0, remove the flag and set the level in the config file:

log:
  system:
    level: debug

Helm values file

In 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: debug

Session recording

The 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: 64000

In 2.0 config file or Helm values file:

log:
  sessionRecording:
    segment:
      maxDuration: 5m
      maxSize: "64KB"

Logger name renamed

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": "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
}
{
  "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
}

Upstream trusted CA bundles

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"

Clone this wiki locally