Skip to main content
logoTetrate Service BridgeVersion: next

Revisioned to Revisioned

Before you continue, make sure you are familiar with Istio Isolation Boundaries feature.

Control plane upgrade strategy

In case of revisioned to revisioned upgrades, It is going to be 2 step process where - Step 1: User upgrade the control plane cluster to the latest TSB release either using helm or tctl. Step 2: User upgrade dataplane component by updating the TSB release version under "canary" revision with the latest release.

Control plane Canary Upgrades​

For canary upgrades of control plane clusters, you can follow the steps below to facilitate a controlled upgrade of Dataplane components.

Step 1: Upgrade control plane cluster to the new TSB release version​

Assume you have TSB version 1.8.0 running on the control plane clusters and you want to upgrade to 1.9.0. This step assumes you already have IsolationBoundary enabled and installed based on Isolation Boundaries Installation.

Upgrade Using Helm​

Obtain Helm values of control plane used before for installation

helm get values controlplane -n istio-system -o yaml > <CLUSTER_NAME>-cp.yaml

Upgrade the control plane cluster to the latest TSB release version

helm upgrade controlplane -n istio-system -f <CLUSTER_NAME>-cp.yaml tetrate-tsb-helm/controlplane --version <UPGRADE_VERSION>

Update the tsbVersion to the latest ( i.e 1.9.0) in the control plane yaml

spec:
  ...
  components:
    xcp:
      isolationBoundaries:
      - name: global
        revisions:
        - name: default
          istio:
            tsbVersion: 1.8.0
        - name: canary
          istio:
            tsbVersion: 1.9.0

This would update istio control plane (revision canary) with the TSB Istio release corresponding to tsbVersion: 1.6.1. This state will be reconciled by the xcp-operator-edge operator in istio-system namespace. You can check istio-operator and istiod deployment to verify.

kubectl get deployment -n istio-system | grep istio-operator
# Output
istio-operator                 1/1     1            1           15h
istio-operator-canary          1/1     1            1           2m
kubectl get deployment -n istio-system | grep istiod
# Output
istiod                 1/1     1            1           15h
istiod-canary          1/1     1            1           2m

Control plane In-Place upgrades​

For in-place upgrade, you can directly update the tsbVersion field - leaving the revision name intact.

spec:
  ...
  components:
    xcp:
      isolationBoundaries:
      - name: global
        revisions:
        - name: default
          istio:
            tsbVersion: 1.9.0

This would re-deploy the Istio control plane components with the TSB Istio release corresponding to tsbVersion: 1.9.0. This state will be reconciled by the xcp-operator-edge operator in istio-system namespace.

Gateway upgrade​

By default, gateways will be upgraded automatically to use latest tsbVersion. See Gateway upgrades for more details on gateway upgrade behavior.

Application upgrade​

Since the revision name does not change, no updates are required in the workload namespaces (workload-ns in this example). However you still need to restart the application workloads. A rolling update is preferred to avoid traffic disruptions.

kubectl rollout restart deployment -n workload-ns

VM workload upgrade​

To upgrade VM workload, download latest Istio sidecar from your onboarding plane using revisioned link then reinstall Istio sidecar on the VM.

Then restart onboarding-agent running in the VM.

Gateway upgrade​

To upgrade the Gateways, update the spec.revision in the Ingress/Egress/Tier1Gateway resource. This will reconcile the existing gateway pods to connect to the new revisioned Istio control plane. TSB by default configures the Gateway install resources with a RollingUpdate strategy that ensures zero downtime.

You can also update spec.revision by patching gateway CR.

kubectl patch ingressgateway.install <name> -n <namespace> --type=json --patch '[{"op": "replace","path": "/spec/revision","value": "1-6-1"}]'; \

Application upgrade​

To upgrade sidecars, replace istio.io/rev=stable workload namespace label and apply the new revision.

kubectl label namespace workload-ns istio.io/rev=1-6-1 --overwrite=true

Then restart the application workloads. A rolling update is preferred to avoid traffic disruptions.

kubectl rollout restart deployment -n workload-ns

VM workload upgrade​

To upgrade VM workload, download latest Istio sidecar from your onboarding plane using revisioned link then reinstall Istio sidecar on the VM.

Update revision value in onboarding-agent configuration then restart onboarding-agent.

Post-upgrade cleanup​

A revision that is no longer in use can either be removed or marked "disabled" in the ControlPlane CR as mentioned below. Marking it disabled helps in enabling the revision back at any point in time.

spec:
  ...
  components:
    xcp:
      isolationBoundaries:
      - name: global
        revisions:
        - name: default
          istio:
            tsbVersion: 1.8.0
          disable: true
        - name: canary
          istio:
            tsbVersion: 1.9.0
Stale Istio control plane components

After disabling/removing the revision under isolation boundaries, a few stale components might remain. For instance, IstioOperator resource, istio-operator (revisioned) deployment or istiod (revisioned) deployment. This happens due to a race condition in removing the IstioOperator resource and istio-operator deployment. In that case, such Istio components can be removed like regular kubernetes objects using

kubectl delete iop xcp-iop-stable -n istio-system
kubectl delete deployment istio-operator-stable -n istio-system
kubectl delete configmap istio-sidecar-injector-stable -n istio-system
kubectl delete deployment istiod-stable -n istio-system

Rollback from revisioned to revisioned​

This workflow is similar to upgrading from revisioned to revisioned control plane. You need to update your workloads to use old revision.