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

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"}}}}
   # ...

   Determine 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-egress-b894fbea-bd87-4cdf-b5ff-f3073c6fed64               HEALTHY   172m
   # xcpgw-ingress-e1a064b1-50d7-4e66-b405-f719e0b01c31              HEALTHY   172m
   # xcpgw-tier1-d265d1d7-4af7-4de9-afbf-afbc6a517d7f                HEALTHY   172m

   Check the ownership of the corresponding service resource:

   Verify ownership

   kubectl get service -n bookinfo app-gw -o yaml
   # Expected Output
   # apiVersion: v1
   # kind: Service
   # metadata:
   #   annotations:
   #     gslb.tetrate.io/name: test-internal
   #   labels:
   #     app: my-gateway
   #     install.operator.istio.io/owning-resource: xcpgw-ingress-e1a064b1-50d7-4e66-b405-f719e0b01c31
   #     install.operator.istio.io/owning-resource-namespace: istio-system
   #   ...

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

   Determine 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-egress-b894fbea-bd87-4cdf-b5ff-f3073c6fed64               HEALTHY   176m
   # xcpgw-ingress-e1a064b1-50d7-4e66-b405-f719e0b01c31              HEALTHY   177m
   # xcpgw-tier1-d265d1d7-4af7-4de9-afbf-afbc6a517d7f                HEALTHY   177m
   # xcpgw-unified-44c6e3e5-85d4-40a0-8f87-b007ae0e4989              HEALTHY   33s

3. Wait until ownership of the service is moved to the new gateway

   Monitor the ownership of the corresponding service resource, waiting until it is transferred.

   warning

   Do not apply any other configuration changes or gateway resources. These may prevent the ownership moving to the new gateway.

   Check ownership of service resource

   kubectl get service -n bookinfo app-gw -o yaml
   # Expected Output
   # apiVersion: v1
   # kind: Service
   # metadata:
   #   annotations:
   #     gslb.tetrate.io/name: test-internal
   #   labels:
   #     app: app-gw
   #     install.operator.istio.io/owning-resource: xcpgw-unified-44c6e3e5-85d4-40a0-8f87-b007ae0e4989
   #     install.operator.istio.io/owning-resource-namespace: istio-system

4. Delete the previous Ingress or Tier1 gateway

   Promptly delete the previous gateway instance:

   Delete old gateway instance

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

   This will delete the gateway but not affect the corresponding Service, as the service is owned by the more-recently-deployed Unified gateway of the same name.

   warning

   Note that it is essential to do this promptly, when the service object is owned by the new gateway istiooperator. Additional configuration changes could cause the ownership to change unexpectedly.

5. Validate the current configuration

   Verify that the service has not changed; for example, see the AGE and other properties:

   Check the service properties

   kubectl get svc -n bookinfo app-gw
   # Expected Output:
   # NAME     TYPE           CLUSTER-IP    EXTERNAL-IP     PORT(S)                                      AGE
   # app-gw   LoadBalancer   10.0.68.110   52.249.242.54   15443:32326/TCP,80:31921/TCP,443:31954/TCP   3h2m

   Verify that the old istiooperator has been removed:

   List running istiooperator instances

   kubectl get iop -n istio-system
   # Expected Output
   # NAME                                                 REVISION   STATUS    AGE
   # xcp-iop-default                                                 HEALTHY   3h30m
   # xcpgw-egress-b894fbea-bd87-4cdf-b5ff-f3073c6fed64               HEALTHY   3h3m
   # xcpgw-tier1-d265d1d7-4af7-4de9-afbf-afbc6a517d7f                HEALTHY   3h3m
   # xcpgw-unified-44c6e3e5-85d4-40a0-8f87-b007ae0e4989              HEALTHY   7m28s

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