Migration 0.21 to 1.0

Gateway 1.0 replaces the annotation-based install with Twingate Custom Resources.

Important

Setting twingateOperator.gateway.enabled=true requires Twingate Operator v2, with its CRDs applied. Upgrade the operator before the Gateway, following the operator's Migration v1 to v2 guide. A standalone install that leaves the value unset renders no Custom Resources and needs no operator.

The values migration below applies only if your values set twingate.resource.*. The installation guide set it when the Gateway runs as a subchart of the Twingate Operator, so those installs are affected; a standalone install of the Gateway chart is affected only if you set it yourself, as you would to expose the cluster's API server through one of several Gateways. If you never set it, no values changes are needed.

What changed

In 0.21, the Gateway Helm chart annotated the Gateway Service and the operator created a TwingateResource from those annotations. The Gateway itself had no Custom Resource.

In 1.0, the chart renders the Custom Resources directly and the operator reconciles them:

• A TwingateGateway, and a TwingateCertificateAuthority that it references through spec.x509CertificateAuthorityRef. Both are rendered when twingateOperator.gateway.enabled is true.
• An optional TwingateResource of type Kubernetes for the cluster's API server, bound to the Gateway through spec.gatewayRef. It is rendered when twingateOperator.kubernetesResource.enabled is true, which requires twingateOperator.gateway.enabled=true.

The chart is now the source of truth for what the Gateway registers with Twingate, so your values.yaml changes accordingly.

Breaking change

In values.yaml, the twingate.resource.* values have been removed. Move your configuration to twingateOperator.gateway.* and twingateOperator.kubernetesResource.*:

• twingate.resource.enabled splits into two toggles: twingateOperator.gateway.enabled renders the Gateway, and twingateOperator.kubernetesResource.enabled renders the in-cluster Kubernetes resource.
• The resource.twingate.com/* annotations under twingate.resource.extraAnnotations are replaced by fields under twingateOperator.kubernetesResource. Any TwingateResource spec field passes through directly, including name (formerly the resource.twingate.com/name annotation), alias (formerly resource.twingate.com/alias), and others such as securityPolicyId. The chart owns type, address and gatewayRef, so setting them there has no effect, and the Remote Network is set with twingateOperator.remoteNetworkId rather than under twingateOperator.kubernetesResource.

Update your values

The examples below use the Gateway chart's own values.yaml. If you install the Gateway as a subchart of the Twingate Operator, these values are nested under the gateway: key; see the operator's Migration v1 to v2 guide.

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"

The in-cluster TwingateResource keeps its 0.21 Kubernetes object name, <release>-resource, so existing TwingateResourceAccess references continue to resolve after the upgrade.

The name the resource shows in the Twingate Admin Console is separate, and it changes if you never set the resource.twingate.com/name annotation: 0.21 fell back to the Kubernetes object name, <release>-resource, while 1.0 defaults to <release> Kubernetes cluster. Set twingateOperator.kubernetesResource.name to keep the old name or to choose your own. This is a display change only, as it is the same resource and it keeps its access.

Certificate authority name

The TwingateCertificateAuthority registers a certificate authority with Twingate under a name that has to be unique across your network and is immutable once created. The chart derives it as <release>-ca-<hash>, hashing the cluster and the release namespace so separate clusters and namespaces do not collide.

Important

The hash is read from the cluster while the chart renders, so it is unavailable wherever rendering has no Kubernetes API access, as with ArgoCD, helm template, or --dry-run=client. Rendering fails there, and you have to name the certificate authority yourself.

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