Skip to content

Migration v2 to v3

Minh Tu Le edited this page Oct 8, 2026 · 1 revision

v3 makes two breaking changes: the bundled gateway subchart moves to Gateway 2.0, which restructures its Helm values, and TwingateResource.spec.protocols is only accepted on Network resources. Start with Does this affect you? to see which of them apply to your install.

If you are upgrading from v1, follow Migration: v1 to v2 first, including the upgrade through v1.3, using the v3 chart and CRDs wherever it names v2. Then apply the changes on this page.

Does this affect you?

If your install has What you have to do Access impact
Any install Apply the new CRDs, then run helm upgrade None
The bundled gateway subchart (gateway.enabled: true) with gateway.tls, gateway.ssh.ca or gateway.auditLog set Move those values to the Gateway 2.0 layout None
A TwingateResource of type: Kubernetes or WebApp that sets spec.protocols Remove spec.protocols None, but the operator stops syncing the resource until it is removed

What changed

Bundled gateway subchart upgraded to Gateway 2.0

The bundled gateway subchart is now the Gateway 2.0 chart, which serves multiple TLS certificates and renames or moves the Helm values for TLS certificates, the SSH certificate authority and session recording. Update them as described in Update your values in the Gateway migration guide. Only its Helm values file sections apply; the config file sections are for Gateways deployed without the Helm chart.

The Gateway guide gives paths relative to the Gateway chart. In the operator chart the subchart's values are nested under gateway, so prefix every path with gateway.: tls.certificates.autoGenerated.enabled in the Gateway guide is gateway.tls.certificates.autoGenerated.enabled in the operator chart's values.yaml.

# values.yaml
gateway:
  enabled: true
  tls:
    certificates:
      autoGenerated:
        enabled: true

protocols only allowed on Network resources

Port-based restrictions only apply to Network resources, so spec.protocols is now rejected on Kubernetes and WebApp resources.

  • The API server rejects a create or update of a TwingateResource of type: Kubernetes or WebApp that sets spec.protocols, with protocols can only be set for Network Resources. An explicit protocols: null counts as unset.
  • Applying the new CRDs does not rewrite stored objects. For a Kubernetes or WebApp resource stored with spec.protocols, the operator fails the reconcile permanently with a validation error containing Only Network resources can set `protocols`. instead of retrying it. Its Twingate Resource stays registered and existing access to it is unaffected, but changes to the object are no longer synced, and every TwingateResourceAccess that references it fails the same way. Any other edit to the object's spec is also rejected by the API server until spec.protocols is removed.

Resources the operator generates from Service annotations never carry spec.protocols on these types, so only resources you wrote yourself are affected. To list them:

kubectl get twingateresources.twingate.com -A -o json \
  | jq -r '.items[] | select(.spec.type != "Network" and .spec.protocols != null)
           | "\(.metadata.namespace)/\(.metadata.name)"'

Remove spec.protocols from each manifest and re-apply it, or patch the object directly:

kubectl patch twingateresource my-cluster --type=merge \
  -p '{"spec":{"protocols":null}}'

This works before or after the upgrade. After the upgrade, the operator resumes syncing the resource on that update.

Upgrade to v3

  1. Remove spec.protocols from Kubernetes and WebApp resources. Optional before the upgrade, but doing it first avoids any window in which the operator stops syncing them; see protocols only allowed on Network resources.

  2. Apply the new CRDs. Helm does not upgrade CRDs, and they are not published on their own; they ship inside the chart. Pull the same chart you are about to install and apply the CRDs from its crds/ directory so they match the chart version:

    helm pull oci://ghcr.io/twingate/helmcharts/twingate-operator --version 3.0.0 --untar
    kubectl apply -f twingate-operator/crds/
  3. Upgrade the operator. If you use the bundled gateway subchart, move its values to the Gateway 2.0 layout first; see Bundled gateway subchart upgraded to Gateway 2.0.

    helm upgrade twop oci://ghcr.io/twingate/helmcharts/twingate-operator --version 3.0.0 --install --wait -f ./values.yaml

Clone this wiki locally