Upgrading to Unified Gateway

Unified Gateway replaces the previous Tier1Gateway and IngressGateway installs. If you are running a previous Gateway instance, you can upgrade it to the Unified gateway seamlessly, without incurring any downtime.

How to Upgrade

Version 1.12.x

Note that the process for upgrading gateways in 1.12 and later differs from the process used in earlier releases. This is because of a change in the Istio Operator implementation.

These instructions explain how to upgrade a gateway named app-gw, deployed in the bookinfo namespace. The upgrade is seamless, with no interruption in service.

1. Check the current state

   Verify that your current gateway is functioning, and make note of any additional configuration that you will need to apply to the new gateway, such as cloud-provider specific annotations or gslb.tetrate.io/name annotations:

   Get current ingress gateway configuration

   kubectl get ingressgateway.install.tetrate.io app-gw -n bookinfo -o yaml
   # Expected Output
   # apiVersion: install.tetrate.io/v1alpha1
   # kind: IngressGateway
   # metadata:
   #   annotations:
   #     kubectl.kubernetes.io/last-applied-configuration: |
   #      {"apiVersion":"install.tetrate.io/v1alpha1","kind":"IngressGateway","metadata":{"annotations":{},"name":"app-gw","namespace":"bookinfo"},"spec":{"kubeSpec":{"service":{"annotations":{"service.beta.kubernetes.io/aws-load-balancer-scheme":"internet-facing"},"type":"LoadBalancer"}}}}
   # ...

   Observe the name of the istiooperator that manages this gateway:

   List IstioOperator resources

   kubectl get iop -n istio-system
   # Expected Output
   # NAME                                                 REVISION   STATUS    AGE
   # xcp-iop-default                                                 HEALTHY   3h19m
   # xcpgw-ingress-e1a064b1-50d7-4e66-b405-f719e0b01c31              HEALTHY   172m

2. Apply the new Unified Gateway install, using the same name.

   Apply the new Unified Gateway manifest, including the additional configuration noted above.

   Apply new Unified Gateway manifest

   cat <<EOF > my-unified-gateway.yaml
   apiVersion: install.tetrate.io/v1alpha1
   kind: Gateway
   metadata:
     name: app-gw
   spec:
     type: UNIFIED
     kubeSpec:
       service:
         type: LoadBalancer
         annotations:
           service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing
   EOF
   
   kubectl apply -n bookinfo -f my-unified-gateway.yaml

   Observe the name of the istiooperator that manages the new gateway:

   Verify that the new istiooperator has been started

   kubectl get iop -n istio-system
   # Expected Output:
   # NAME                                                 REVISION   STATUS    AGE
   # xcp-iop-default                                                 HEALTHY   3h23m
   # xcpgw-ingress-e1a064b1-50d7-4e66-b405-f719e0b01c31              HEALTHY   177m
   # xcpgw-unified-44c6e3e5-85d4-40a0-8f87-b007ae0e4989              HEALTHY   33s

3. Scale down XCP Operator Edge and delete the old Tier1 GW install resources

   Scale down the XCP Operator Edge service:

   Scale down XCP Operator Edge

   kubectl scale -n istio-system deployment/xcp-operator-edge --replicas=0
   # deployment.apps/xcp-operator-edge scaled

   Delete the old Tier1 or Ingress gateway install resource

   Delete old gateway instance

   kubectl delete ingressgateway.install.tetrate.io app-gw -n bookinfo

4. Edit the XCP Gateway Install CR and delete the finalizer

   Remove the finalizer from the XCP Gateway Install custom resource:

   Find the appropriate XCP Gateway Install CR

   kubectl get ingressdeployments.install.xcp.tetrate.io -n istio-system -l install.tetrate.io/owner-name=app-gw
   # Expected Output
   # NAME                                           AGE
   # ingress-fc5a4bd3-3023-4388-9696-ee3922f800ae   141m

   Edit the CR, and remove the highlighted finalizer value:

   Edit the CR and remove the highlighted line

   kubectl edit ingressdeployments.install.xcp.tetrate.io -n istio-system ingress-fc5a4bd3-3023-4388-9696-ee3922f800ae
   
   # ---Editing session follows---
   
   # Please edit the object below. Lines beginning with a '#' will be ignored,
   # and an empty file will abort the edit. If an error occurs while saving this file will be
   # reopened with the relevant failures.
   #
   apiVersion: install.xcp.tetrate.io/v1alpha1
   kind: IngressDeployment
   metadata:
     annotations:
       tsb.tetrate.io/contentHash: a4112bb79e6f3832
     creationTimestamp: "2025-03-17T13:18:20Z"
     deletionGracePeriodSeconds: 0
     deletionTimestamp: "2025-03-17T15:30:49Z"
     finalizers:
     - gateway.install.xcp.tetrate.io
     generation: 3
     labels:
       install.tetrate.io/owner-kind: IngressGateway
       install.tetrate.io/owner-name: app-gw
       install.tetrate.io/owner-namespace: bookinfo
       install.tetrate.io/owner-version: v1alpha1
   ...

   Save your changes, then verify that the CR has been deleted:

   Verify that the CR has been deleted

   kubectl get ingressdeployments.install.xcp.tetrate.io -n istio-system -l install.tetrate.io/owner-name=app-gw
   # Expected output
   # No resources found in istio-system namespace.

5. Scale up XCP Operator Edge to its previous state

   Scale the XCP Operator Edge to 1 replica, restoring its operation:

   Scale up XCP Operator Edge

   kubectl scale -n istio-system deployment/xcp-operator-edge --replicas=1
   # deployment.apps/xcp-operator-edge scaled

   Once the Edge Operator is up, it will delete the old gateway install IOP from the cluster:

   Observe that the xcp-ingress install iop has been removed

   kubectl get iop -n istio-system
   # Expected Output:
   # NAME                                                 REVISION   STATUS    AGE
   # xcp-iop-default                                                 HEALTHY   3h23m
   # xcpgw-unified-44c6e3e5-85d4-40a0-8f87-b007ae0e4989              HEALTHY   33s

You have successfully migrated the gateway from legacy to the new Unified type, without any loss of service.