Upgrading Apigee hybrid to version 1.7

You are currently viewing version 1.7 of the Apigee hybrid documentation.This version is end of life. You should upgrade to a newer version. For more information, seeSupported versions.
Note:This procedure covers upgrading from Apigee hybrid version 1.6.x or from previous releases of Apigee hybrid version 1.7.x to Apigee hybrid version 1.7.6.

Use the same procedures for minor version upgrades (for example version 1.6 to 1.7) and for patch release upgrades (for example 1.7.0 to 1.7.6).

If you are upgrading from Apigee hybrid version 1.5 or older, you must first upgrade to hybrid version 1.6 before upgrading to version 1.7.6. See the instructions forUpgrading Apigee hybrid to version 1.6.

Upgrading to version 1.7.6 overview.

Upgrading to Apigee hybrid version 1.7 may require downtime:

The procedures for upgrading Apigee hybrid are organized in the following sections:

  1. Prepare to upgrade to version 1.7.
  2. Install hybrid runtime version 1.7.6.
  3. Upgrade cert-manager.
  4. Upgrade ASM.

Prerequisite

These upgrade instructions assume you have Apigee hybrid version 1.6.x or an earlier patch release of version 1.7.x installed and wish to upgrade it to version 1.7.6. If you are updating from an earlier version see the instructions forUpgrading Apigee hybrid to version 1.6.

Prepare to upgrade to version 1.7

Back up your hybrid installation

  1. These instructions use the environment variable$APIGEECTL_HOME for the directory in your file system where theapigeectl utility is installed. If needed,cd into yourapigeectl directory and define the variable with the following command:

    Linux

    export APIGEECTL_HOME=$PWD
    echo $APIGEECTL_HOME

    Mac OS

    export APIGEECTL_HOME=$PWD
    echo $APIGEECTL_HOME

    Windows

    set APIGEECTL_HOME=%CD%
    echo %APIGEECTL_HOME%
  2. (Recommended) Make a backup copy of your version 1.6$APIGEECTL_HOME/ directory. For example:
    tar -czvf$APIGEECTL_HOME/../apigeectl-v1.6-backup.tar.gz$APIGEECTL_HOME
  3. (Recommended) Back up your Cassandra database following the instructions inCassandra backup and recovery

Upgrade your Kubernetes version

Upgrade your Kubernetes platform to the versions supported by hybrid 1.7. Follow your platform's documentation if you need help.

Click to expand a list of supported platforms

Apigee hybrid versions

Platforms

 1.6(4)not supported1.71.8
Anthos (Google Cloud - GKE)1.19.x
1.20.x
1.21.x		1.20.x
1.21.x
1.22.x(≥ 1.7.2)
1.23.x(≥ 1.7.2)		1.21.x(≤ 1.8.3)
1.22.x(≤ 1.8.3)
1.23.x(≤ 1.8.4)
1.24.x(≥ 1.8.4)
1.25.x(≥ 1.8.4)
Anthos (AWS)1.7.x
1.8.x
1.9.3+
1.10.x		1.9.x
1.10.x
1.12.x(≥ 1.7.2)		1.10.x
1.11.x
1.12.x
1.13.x
1.14.x
Anthos (Azure)1.8.x1.9.x
1.10.x
1.12.x(≥ 1.7.2)		1.10.x
1.11.x
1.12.x
1.13.x
1.14.x
Anthos(1) (on-premises - VMware)1.7.x
1.8.x
1.9.3+
1.10.x		1.9.xnot supported(7)
1.10.xnot supported(7)
1.11.xnot supported(7)(≥ 1.7.2)
1.12.xnot supported(7)(≥ 1.7.2)		1.10.xnot supported(7)
1.11.xnot supported(7)
1.12.xnot supported(7)(5)
1.13.x(5)
1.14.x(5)
1.15.x
Anthos(1) (Bare Metal)1.7.x
1.8.2+
1.9.3+
1.10.x		1.9.xnot supported(7)
1.10.xnot supported(7)
1.11.xnot supported(7)(≥ 1.7.2)
1.12.xnot supported(7)(≥ 1.7.2)		1.10.xnot supported(7)
1.11.xnot supported(7)
1.12.xnot supported(7)(5)
1.13.x(5)
1.14.x(5)
1.15.x
Anthos (Multi-cloud context on EKS with Anthosattached clusters)1.19.x
1.20.x
1.21.x		1.21.x
1.22.x(≥ 1.7.2)
1.23.x(≥ 1.7.2)		1.22.x(≤ 1.8.3)
1.23.x(≤ 1.8.4)
1.24.x(≥ 1.8.4)
1.25.x(≥ 1.8.4)
Anthos (Multi-cloud context on AKS with Anthosattached clusters)1.19.x
1.20.x
1.21.x		1.21.x
1.22.x(≥ 1.7.2)
1.23.x(≥ 1.7.2)		1.22.x(≤ 1.8.3)
1.23.x(≤ 1.8.4)
1.24.x(≥ 1.8.4)
1.25.x(≥ 1.8.4)
Anthos (Multi-cloud context on OpenShift with Anthosattached clusters)4.6
4.7
4.8		4.7
4.8		4.8
4.9
4.10
Anthos (Multi-cloud context on Konvoy with Anthosattached clusters)1.7.xN/AN/A

Components

1.61.71.8
Anthos Service Mesh (ASM)1.9.xnot supported
1.10.xnot supported
1.12.xnot supported(2)		1.10.xnot supported
1.11.xnot supported
1.12.xnot supported
1.13.x(3)		1.11.xnot supported
1.12.xnot supported
1.13.x
1.14.xnot supported
1.15.x
JDKJDK 11JDK 11JDK 11
cert-manager1.5.41.7.x1.7.x
Cassandra3.11.103.11.103.11.10

(1) On Anthos versions 1.8.2 and above, follow the instructions in these documents to avoid conflict withcert-manager:

(2) Support available with Apigee hybrid version 1.6.6 and newer.

(3) Support available with Apigee hybrid version 1.7.2 and newer.

(4) The official EOL dates for Apigee hybrid versions 1.6, 1.7, and 1.8 have been reached. Regular monthly patches are no longer available. These releases are no longer officially supported except for customers with explicit and official exceptions for continued support. Other customers must upgrade.

(5)Anthos on Bare Metal and VMWare requires ASM 1.14 or later. We recommend that you upgrade to hybrid v1.8 and switch to Apigee ingress gateway which no longer requires you to install ASM on your hybrid cluster.

(6) Support available with Apigee hybrid version 1.8.4 and newer.

(7)Anthos on Bare Metal and VMWare versions 1.12 and earlier are out of support. See the Anthos on Bare Metal Version Support Policy and the Anthos clusters on VMware versions.

(8) Not supported with Apigee hybrid version 1.8.4 and newer.

(9) Support available with Apigee hybrid version 1.7.6 and newer.

(10) Not supported with Apigee hybrid version 1.8.5 and newer.

About attached clusters

For Apigee hybrid versions 1.7.x and older, you must use Anthosattached clusters if you want to run Apigee hybrid in a multi-cloud context on Elastic Kubernetes Service (EKS), Azure Kubernetes Service (AKS), or another supported third-party Kubernetes service provider. Cluster attachment allows Google to measure the usage of Anthos Service Mesh (ASM).Registering the third-party cluster is optional. Register only if you wish to view the attached cluster in the Google Cloud console. For more information, seeAttach third-party Kubernetes clusters to Google Cloud.

For Apigee hybrid version 1.8.x, Anthos attached clusters are required if you are using Anthos Service Mesh for your ingress gateway. If you are using Apigee ingress gateway, Anthos attached clusters are optional.

Note: Hybrid installations are not currently supported on GKE Autopilot.

Add theCloud Trace Agent role to theapigee-runtime service account

Optional: If you plan to useCloud trace, ensure yourapigee-runtime service account has theCloud Trace Agent (roles/cloudtrace.agent) Google role. You can do so in theCloud console > IAM & Admin > Service accounts UI or with the following commands:

  1. Get the email address for yourapigee-runtime service account with the following command:
    gcloud iam service-accounts list --filter "apigee-runtime"

    If it matches the patternapigee-runtime@$ORG_NAME.iam.gserviceaccount.com, you can use that pattern in the next step.

  2. Assign theCloud Trace Agent role to the service account:
    gcloud projects add-iam-policy-binding$PROJECT_ID \    --member="serviceAccount:apigee-runtime@$PROJECT_ID.iam.gserviceaccount.com" \    --role="roles/cloudtrace.agent"

    Where:$PROJECT_ID is the name of the Google Cloud project where Apigee hybrid is installed.

Replacemetrics:stackdriverExporter properties in your overrides.

Note: This step is only necessary if you have specifiedmetrics:stackdriverExporter in youroverrides.yaml file.

Starting in Hybrid version 1.7,metrics:stackdriverExporter has been replaced withmetrics:appStackdriverExporter andmetrics:proxyStackdriverExporter. Replace those properties with equivalent properties. For example, replace:

metrics:  ... ...  stackdriverExporter:    resources:      limits:        cpu: 500m        memory: 1Gi      requests:        cpu: 128m        memory: 512Mi

with:

metrics:  ... ...  appStackdriverExporter:    resources:      limits:        cpu: 500m        memory: 1Gi      requests:        cpu: 128m        memory: 512Mi  proxyStackdriverExporter:    resources:      limits:        cpu: 500m        memory: 1Gi      requests:        cpu: 128m        memory: 512Mi

Seethe Configuration property reference: metrics

Install the hybrid 1.7.6 runtime

Note:Do not create new environments during the upgrade process.
  1. Store the latest version number in a variable using the following command:

    Linux

    export VERSION=$(curl -s \  https://storage.googleapis.com/apigee-release/hybrid/apigee-hybrid-setup/current-version.txt?ignoreCache=1)

    Mac OS

    export VERSION=$(curl -s \  https://storage.googleapis.com/apigee-release/hybrid/apigee-hybrid-setup/current-version.txt)

    Windows

    for /f "tokens=*" %a in ('curl -s ^  https://storage.googleapis.com/apigee-release/hybrid/apigee-hybrid-setup/current-version.txt') ^do set VERSION=%a
  2. Check that the variable was populated with a version number using the following command. If you want to use a different version, you can save that in an environment variable instead.
    echo $VERSION
      1.7.6
  3. Be sure you are in the hybrid base directory (the parent of the directory where theapigeectl executable file is located):
    cd$APIGEECTL_HOME/..

  4. Download the release package for your operating system using the following command. Be sure to select your platform in the following table:

    Linux

    Linux 64 bit:

    curl -LO \  https://storage.googleapis.com/apigee-release/hybrid/apigee-hybrid-setup/$VERSION/apigeectl_linux_64.tar.gz

    Mac OS

    Mac 64 bit:

    curl -LO \  https://storage.googleapis.com/apigee-release/hybrid/apigee-hybrid-setup/$VERSION/apigeectl_mac_64.tar.gz

    Windows

    Windows 64 bit:

    curl -LO ^  https://storage.googleapis.com/apigee-release/hybrid/apigee-hybrid-setup/%VERSION%/apigeectl_windows_64.zip
  5. Rename your currentapigeectl/ directory to a backup directory name. For example:

    Linux

    mv$APIGEECTL_HOME/$APIGEECTL_HOME-v1.6/

    Mac OS

    mv$APIGEECTL_HOME/$APIGEECTL_HOME-v1.6/

    Windows

    rename %APIGEECTL_HOME% %APIGEECTL_HOME%-v1.6

  6. Extract the downloaded gzip file contents into your hybrid base directory. The hybrid base directory is the directory where the renamedapigeectl-v1.6 directory is located:

    Linux

    tar xvzffilename.tar.gz -C ./

    Mac OS

    tar xvzffilename.tar.gz -C ./

    Windows

    tar xvzffilename.zip -C ./

  7. The tar contents are, by default, expanded into a directory with the version and platform in its name. For example:./apigeectl_1.7.6-d591b23_linux_64. Rename that directory toapigeectl using the following command:

    Linux

    mvdirectory-name-linux apigeectl

    Mac OS

    mvdirectory-name-mac apigeectl

    Windows

    renamedirectory-name-windows apigeectl
  8. Change to theapigeectl directory:
    cd ./apigeectl

    Theapigeectl executable is in this directory.

  9. These instructions use the environment variable$APIGEECTL_HOME for the directory in your file system where theapigeectl utility is installed. If needed,cd into yourapigeectl directory and define the variable with the following command:

    Linux

    export APIGEECTL_HOME=$PWD
    echo $APIGEECTL_HOME

    Mac OS

    export APIGEECTL_HOME=$PWD
    echo $APIGEECTL_HOME

    Windows

    set APIGEECTL_HOME=%CD%
    echo %APIGEECTL_HOME%
  10. Verify the version ofapigeectl with theversion command:
    ./apigeectl version
    Version:1.7.6
  11. Move to thehybrid-base-directory/hybrid-files directory. Thehybrid-files directory is where configuration files such as the overrides file, certs, and service accounts are located. For example:
    cd$APIGEECTL_HOME/../hybrid-files
  12. Verify thatkubectl is set to the correct context using the following command. The current context should be set to the cluster in which you are upgrading Apigee hybrid.
    kubectl config get-contexts | grep \*
  13. In thehybrid-files directory:
    1. Update the following symbolic links to$APIGEECTL_HOME. These links allow you to run the newly installedapigeectl command from inside thehybrid-files directory:
      ln -nfs$APIGEECTL_HOME/tools toolsln -nfs$APIGEECTL_HOME/config configln -nfs$APIGEECTL_HOME/templates templatesln -nfs$APIGEECTL_HOME/plugins plugins
    2. To check that the symlinks were created correctly, execute the following command and make sure the link paths point to the correct locations:
      ls -l | grep ^l
    3. Do a dry run initialization to check for errors:
      ${APIGEECTL_HOME}/apigeectl init -f ./overrides/OVERRIDES.yaml --dry-run=client

      WhereOVERRIDES is the name of your overrides file.

    4. If there are no errors, initialize hybrid 1.7.6:
      ${APIGEECTL_HOME}/apigeectl init -f ./overrides/OVERRIDES.yaml
    5. Check the initialization status:
      ${APIGEECTL_HOME}/apigeectl check-ready -f ./overrides/OVERRIDES.yaml
    6. Check for errors with a dry run of theapply command:
      ${APIGEECTL_HOME}/apigeectl apply -f ./overrides/OVERRIDES.yaml --dry-run=client
    7. If there are no errors, apply your overrides. Select and follow the instructions for production environments or demo/experimental environments, depending on your installation.During the upgrade process each component will perform a rolling restart. Therefore, for production environments, it is best to apply the upgrade to one component at a time.

      Production

      For production environments you should upgrade each hybrid component individually, and check the status of the upgraded component before proceeding to the next component.

      1. Be sure you are in thehybrid-files directory.
      2. Apply your overrides to upgrade Cassandra:
        ${APIGEECTL_HOME}/apigeectl apply -f ./overrides/OVERRIDES.yaml --datastore
      3. Check completion:
        ${APIGEECTL_HOME}/apigeectl check-ready -f ./overrides/OVERRIDES.yaml
        Tip: Ifcheck-ready fails, you can get more information about your pods with:
        kubectl -nNAMESPACE get pods

        WhereNAMESPACE is your Apigee hybrid namespace.

        Proceed to the next step only when the pods are ready.

      4. Apply your overrides to upgrade Telemetry components and check completion:
        ${APIGEECTL_HOME}/apigeectl apply -f ./overrides/OVERRIDES.yaml --telemetry
        ${APIGEECTL_HOME}/apigeectl check-ready -f ./overrides/OVERRIDES.yaml
      5. Bring up Redis components:
        ${APIGEECTL_HOME}/apigeectl apply -f ./overrides/OVERRIDES.yaml --redis
      6. Apply your overrides to upgrade the org-level components (MART, Watcher and Apigee Connect) and check completion:
        ${APIGEECTL_HOME}/apigeectl apply -f ./overrides/OVERRIDES.yaml --org
        ${APIGEECTL_HOME}/apigeectl check-ready -f ./overrides/OVERRIDES.yaml
      7. Apply your overrides to upgrade your environments. You have two choices:
        • Environment by environment: Apply your overrides to one environment at a time and check completion. Repeat this step for each environment:
          ${APIGEECTL_HOME}/apigeectl apply -f ./overrides/OVERRIDES.yaml --envENV_NAME
          ${APIGEECTL_HOME}/apigeectl check-ready -f ./overrides/OVERRIDES.yaml

          WhereENV_NAME is the name of the environment you are upgrading.

        • All environments at one time: Apply your overrides to all environments at once and check completion:
          ${APIGEECTL_HOME}/apigeectl apply -f ./overrides/OVERRIDES.yaml --all-envs
          ${APIGEECTL_HOME}/apigeectl check-ready -f ./overrides/OVERRIDES.yaml

      Demo/Experimental

      In most demo or experimental environments, you can apply the overrides to all components at once. If your demo/experimental environment large and complex or closely mimics a production environment, you may want to use the instructions for upgradingproduction environments

      1. Be sure you are in thehybrid-files directory.
      2. ${APIGEECTL_HOME}/apigeectl apply -f ./overrides/OVERRIDES.yaml
      3. Check the status:
        ${APIGEECTL_HOME}/apigeectl check-ready -f ./overrides/OVERRIDES.yaml

Upgrade cert-manager to version v1.7.2

If you are running a version ofcert-manager prior to v1.7.2, you need to upgrade it to v1.7.2.

Important:The ASM upgrade (as described in the next step) will install cert-manager in thecert-manager namespace. If for certain reasons, you need to use your own cert-manager,follow the steps described inConflictingcert-manager installation beforecontinuing.

  1. Check the currentcert-manager version using the following command:

    kubectl -n cert-manager get deployment -o yaml | grep 'image:'

    Something similar to the following is returned:

    image:quay.io/jetstack/cert-manager-controller:v1.7.2image:quay.io/jetstack/cert-manager-cainjector:v1.7.2image:quay.io/jetstack/cert-manager-webhook:v1.7.2
  2. Remove the deployments using the following command:
    $ kubectl delete -n cert-manager deployment cert-manager cert-manager-cainjector cert-manager-webhook
  3. Upgradecert-manager to v1.7.2 version using the following command:
    $ kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.7.2/cert-manager.yaml

Upgrade ASM to version 1.28

You may experience a brief interruption of incoming traffic (typically less than two seconds) when you upgrade ASM. If you are running hybrid in two or more clusters, you can avoid this interruption by upgrading one cluster at a time. Divert all production traffic away from the cluster you are about to upgrade, take the cluster offline, and then proceed with the upgrade process. Repeat the process for each cluster.

Perform the upgrade using the ASM documentation appropriate for your platform:

The instructions to install and configure ASM are different depending on your platform. The platforms are divided into the following categories:

  • GKE: Google Kubernetes Engine clusters running on Google Cloud.
  • Outside Google Cloud: Anthos clusters running on:
    • Anthos clusters on VMware (GKE on-prem)
    • Anthos on bare metal
    • Anthos clusters on AWS
    • Amazon EKS
  • Other Kubernetes Platforms: Conformant clusters created and running on:
    • AKS
    • EKS
    • OpenShift
Important:This ASM upgrade will install cert-manager in thecert-manager namespace. If for certain reasons, you need to use your own cert-manager,follow the steps described inConflictingcert-manager installation beforecontinuing.

GKE

The sequence for upgrading to ASM version 1.28.2 for your hybrid installation is as follows:

  1. Prepare for the upgrade.
  2. Install the new version of ASM.
  3. Delete the previous ASM version's deployments, services, and webhooks from your current installation.
  4. Upgrade your gateways and configure the new webhooks.

To upgrade to ASM version 1.28.2 for hybrid on GKE:

Note: You can upgrade directly from ASM version 1.10 or higher to ASM version 1.28.2. If you are running a version of ASM older than 1.10, you must first upgrade to version 1.10. Follow the instructions inUpgrading from earlier versions
  1. Review the requirements inUpgrade Anthos Service Mesh, but do not perform the upgrade yet.
  2. Before installing the new version, determine the current revision. You will need this information to delete the previous ASM version's deployments, services, and webhooks from your current installation. Use the following command to store the current istiod revision to an environment variable:
    export DELETE_REV=$(kubectl get deploy -n istio-system -l app=istiod -o jsonpath={.items[].metadata.labels.'istio\.io\/rev'}'{"\n"}')echo ${DELETE_REV}
  3. Create a newoverlay.yaml file or verify that your existingoverlay.yaml contains the following contents:
    apiVersion:install.istio.io/v1alpha1kind:IstioOperatorspec:revision:asm-1282-4components:ingressGateways:-name:istio-ingressgatewayenabled:truek8s:nodeSelector:# default node selector, if different or not using node selectors, change accordingly.cloud.google.com/gke-nodepool:apigee-runtimeresources:requests:cpu:1000mservice:type:LoadBalancerloadBalancerIP:STATIC_IP# If you do not have a reserved static IP, leave this out.ports:-name:http-status-portport:15021-name:http2port:80targetPort:8080-name:httpsport:443targetPort:8443meshConfig:accessLogFormat:'{"start_time":"%START_TIME%","remote_address":"%DOWNSTREAM_DIRECT_REMOTE_ADDRESS%","user_agent":"%REQ(USER-AGENT)%","host":"%REQ(:AUTHORITY)%","request":"%REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?:PATH)% %PROTOCOL%","request_time":"%DURATION%","status":"%RESPONSE_CODE%","status_details":"%RESPONSE_CODE_DETAILS%","bytes_received":"%BYTES_RECEIVED%","bytes_sent":"%BYTES_SENT%","upstream_address":"%UPSTREAM_HOST%","upstream_response_flags":"%RESPONSE_FLAGS%","upstream_response_time":"%RESPONSE_DURATION%","upstream_service_time":"%RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)%","upstream_cluster":"%UPSTREAM_CLUSTER%","x_forwarded_for":"%REQ(X-FORWARDED-FOR)%","request_method":"%REQ(:METHOD)%","request_path":"%REQ(X-ENVOY-ORIGINAL-PATH?:PATH)%","request_protocol":"%PROTOCOL%","tls_protocol":"%DOWNSTREAM_TLS_VERSION%","request_id":"%REQ(X-REQUEST-ID)%","sni_host":"%REQUESTED_SERVER_NAME%","apigee_dynamic_data":"%DYNAMIC_METADATA(envoy.lua)%"}'
  4. Follow the instructions in the following sections in the ASM documentation:Important: Make sure to follow the instructions to upgrade ASM with optional features, and to include youroverlay.yaml.
    1. Download asmcli
    2. Grant cluster admin permissions
    3. Validate project and cluster
    4. Upgrade with optional features. Stop before starting the "Upgrade Gateways section"
  5. Delete the mutating webhook and validating webhook:
    1. cd into the directory where you installedasmcli.
    2. Store the current new revision in an environment variable to use in the script to delete the webhooks:
      UPGRADE_REV="asm-1282-4"
    3. create a shell script containing the following commands:
      #!/bin/bashset -exPROJECT_ID="YOUR_PROJECT_ID"CLUSTER_NAME="YOUR_CLUSTER_NAME"CLUSTER_LOCATION="YOUR_CLUSTER_LOCATION"kubectl label namespace istio-system istio.io/rev=${UPGRADE_REV} istio-injection- --overwritekubectl rollout restart deployment -n istio-systemkubectl apply -n istio-system -fPATH_TO_INGRESSGATEWAYistio-ingressgatewaykubectl apply -n istio-system -fPATH_TO_INGRESSGATEWAY/istio-ingressgateway-connectorsif [[ "${DELETE_REV}" != "${UPGRADE_REV}" ]]; then  kubectl apply -f out/asm/istio/istiod-service.yaml  kubectl delete deploy -l app=istio-ingressgateway,istio.io/rev=${DELETE_REV} -n istio-system --ignore-not-found=true  kubectl delete deploy -l app=istio-ingressgateway-connectors,istio.io/rev=${DELETE_REV} -n istio-system --ignore-not-found=true  kubectl delete ValidatingWebhookConfiguration -l app=istiod,istio.io/rev=${DELETE_REV} -n istio-system --ignore-not-found=true  kubectl delete MutatingWebhookConfiguration -l app=sidecar-injector,istio.io/rev=${DELETE_REV} -n istio-system --ignore-not-found=true  kubectl delete Service,Deployment,HorizontalPodAutoscaler,PodDisruptionBudget istiod-${DELETE_REV} -n istio-system --ignore-not-found=true  kubectl delete IstioOperator installed-state-${DELETE_REV} -n istio-system --ignore-not-found=truefi
    4. Execute the script to delete the current webhooks.
  6. Follow the steps inUpgrade gateways to create the new webhooks and switch traffic to the new gateways.

Outside Google Cloud

These instructions cover upgrading ASM on:

  • Anthos clusters on VMware (GKE on-prem)
  • Anthos on bare metal
  • Anthos clusters on AWS
  • Amazon EKS
Note: You can upgrade directly from ASM version 1.10 or higher to ASM version 1.28.2. If you are running an older version of ASM, you must first upgrade to version 1.10. Follow the instructions inUpgrading from earlier versions

The sequence for upgrading to ASM version 1.28.2 for your hybrid installation is as follows:

  1. Prepare for the upgrade.
  2. Install the new version of ASM.
  3. Delete the previous ASM version's deployments, services, and webhooks from your current installation.
  4. Upgrade your gateways and configure the new webhooks.
  1. Review the requirements inUpgrade Anthos Service Mesh, but do not perform the upgrade yet.
  2. Before installing the new version, determine the current revision. You will need this information to delete thevalidating webhook andmutating webhook from your current ASM installation. Use the following command to store the current istiod revision to an environment variable:
    export DELETE_REV=$(kubectl get deploy -n istio-system -l app=istiod -o jsonpath={.items[].metadata.labels.'istio\.io\/rev'}'{"\n"}')echo ${DELETE_REV}
  3. Create a newoverlay.yaml file or verify that your existingoverlay.yaml contains the following contents:
    apiVersion:install.istio.io/v1alpha1kind:IstioOperatorspec:revision:asm-1282-4components:ingressGateways:-name:istio-ingressgatewayenabled:truek8s:nodeSelector:# default node selector, if different or not using node selectors, change accordingly.cloud.google.com/gke-nodepool:apigee-runtimeresources:requests:cpu:1000mservice:type:LoadBalancerloadBalancerIP:STATIC_IP# If you do not have a reserved static IP, leave this out.ports:-name:http-status-portport:15021-name:http2port:80targetPort:8080-name:httpsport:443targetPort:8443values:gateways:istio-ingressgateway:runAsRoot:truemeshConfig:accessLogFormat:'{"start_time":"%START_TIME%","remote_address":"%DOWNSTREAM_DIRECT_REMOTE_ADDRESS%","user_agent":"%REQ(USER-AGENT)%","host":"%REQ(:AUTHORITY)%","request":"%REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?:PATH)% %PROTOCOL%","request_time":"%DURATION%","status":"%RESPONSE_CODE%","status_details":"%RESPONSE_CODE_DETAILS%","bytes_received":"%BYTES_RECEIVED%","bytes_sent":"%BYTES_SENT%","upstream_address":"%UPSTREAM_HOST%","upstream_response_flags":"%RESPONSE_FLAGS%","upstream_response_time":"%RESPONSE_DURATION%","upstream_service_time":"%RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)%","upstream_cluster":"%UPSTREAM_CLUSTER%","x_forwarded_for":"%REQ(X-FORWARDED-FOR)%","request_method":"%REQ(:METHOD)%","request_path":"%REQ(X-ENVOY-ORIGINAL-PATH?:PATH)%","request_protocol":"%PROTOCOL%","tls_protocol":"%DOWNSTREAM_TLS_VERSION%","request_id":"%REQ(X-REQUEST-ID)%","sni_host":"%REQUESTED_SERVER_NAME%","apigee_dynamic_data":"%DYNAMIC_METADATA(envoy.lua)%"}'
  4. Follow the instructions in the following sections in the ASM documentation:Important: Make sure to follow the instructions to upgrade ASM with optional features, and to include youroverlay.yaml.
    1. Download asmcli
    2. Grant cluster admin permissions
    3. Validate project and cluster
    4. Upgrade with optional features. Stop before starting the "Upgrade Gateways section"
  5. Delete the mutating webhook and validating webhook:
    1. cd into the directory where you installedasmcli.
    2. Store the current new revision in an environment variable to use in the script to delete the webhooks:
      UPGRADE_REV="asm-1282-4"
    3. create a shell script containing the following commands:
      #!/bin/bashset -exPROJECT_ID="YOUR_PROJECT_ID"CLUSTER_NAME="YOUR_CLUSTER_NAME"CLUSTER_LOCATION="YOUR_CLUSTER_LOCATION"gcloud config configurations activate ${PROJECT_ID}gcloud container clusters get-credentials ${CLUSTER_NAME} --region ${CLUSTER_LOCATION} --project ${PROJECT_ID}kubectl label namespace istio-system istio.io/rev=${UPGRADE_REV} istio-injection- --overwritekubectl rollout restart deployment -n istio-systemkubectl apply -n istio-system -fPATH_TO_INGRESSGATEWAYistio-ingressgatewaykubectl apply -n istio-system -fPATH_TO_INGRESSGATEWAY/istio-ingressgateway-connectorsif [[ "${DELETE_REV}" != "${UPGRADE_REV}" ]]; then  kubectl apply -f out/asm/istio/istiod-service.yaml  kubectl delete deploy -l app=istio-ingressgateway,istio.io/rev=${DELETE_REV} -n istio-system --ignore-not-found=true  kubectl delete deploy -l app=istio-ingressgateway-connectors,istio.io/rev=${DELETE_REV} -n istio-system --ignore-not-found=true  kubectl delete ValidatingWebhookConfiguration -l app=istiod,istio.io/rev=${DELETE_REV} -n istio-system --ignore-not-found=true  kubectl delete MutatingWebhookConfiguration -l app=sidecar-injector,istio.io/rev=${DELETE_REV} -n istio-system --ignore-not-found=true  kubectl delete Service,Deployment,HorizontalPodAutoscaler,PodDisruptionBudget istiod-${DELETE_REV} -n istio-system --ignore-not-found=true  kubectl delete IstioOperator installed-state-${DELETE_REV} -n istio-system --ignore-not-found=truefi
    4. Execute the script to delete the current webhooks.
  6. Follow the steps inUpgrade gateways to create the new webhooks and switch traffic to the new gateways.

AKS / EKS

In these instructions the process of upgrading Anthos Service Mesh (ASM) version istio-1.28.2-asm.4 on Anthos attached clusters is the same as performing a fresh install.

Preparing to install Anthos Service Mesh

  1. Delete the mutating webhook and validating webhook:
    1. cd into the directory where you installedasmcli.
    2. Store the current new revision in an environment variable to use in the script to delete the webhooks:
      UPGRADE_REV="asm-1282-4"
    3. create a shell script containing the following commands:
      #!/bin/bashset -exkubectl label namespace istio-system istio.io/rev=${UPGRADE_REV} istio-injection- --overwritekubectl rollout restart deployment -n istio-systemkubectl apply -n istio-system -fPATH_TO_INGRESSGATEWAYistio-ingressgatewayif [[ "${DELETE_REV}" != "${UPGRADE_REV}" ]]; then  kubectl apply -f out/asm/istio/istiod-service.yaml  kubectl delete deploy -l app=istio-ingressgateway,istio.io/rev=${DELETE_REV} -n istio-system --ignore-not-found=true  kubectl delete deploy -l app=istio-ingressgateway-connectors,istio.io/rev=${DELETE_REV} -n istio-system --ignore-not-found=true  kubectl delete ValidatingWebhookConfiguration -l app=istiod,istio.io/rev=${DELETE_REV} -n istio-system --ignore-not-found=true  kubectl delete MutatingWebhookConfiguration -l app=sidecar-injector,istio.io/rev=${DELETE_REV} -n istio-system --ignore-not-found=true  kubectl delete Service,Deployment,HorizontalPodAutoscaler,PodDisruptionBudget istiod-${DELETE_REV} -n istio-system --ignore-not-found=true  kubectl delete IstioOperator installed-state-${DELETE_REV} -n istio-system --ignore-not-found=truefi
    4. Execute the script to delete the current webhooks.

    2. Linux

  2. Download the Anthos Service Mesh installation file to your current working directory:
    curl -LO https://storage.googleapis.com/gke-release/asm/istio-1.28.2-asm.4-linux-amd64.tar.gz
  3. Download the signature file and use openssl to verify the signature:
    curl -LO https://storage.googleapis.com/gke-release/asm/istio-1.28.2-asm.4-linux-amd64.tar.gz.1.sig
    openssldgst-verify/dev/stdin-signature istio-1.28.2-asm.4-linux-amd64.tar.gz.1.sig istio-1.28.2-asm.4.tar.gz <<'EOF'-----BEGINPUBLICKEY-----MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEWZrGCUaJJr1H8a36sG4UUoXvlXvZwQfk16sxprI2gOJ2vFFggdq3ixF2h4qNBt0kI7ciDhgpwS8t+/960IsIgw==-----ENDPUBLICKEY-----EOF
  4. Extract the contents of the file to any location on your file system. For example, to extract the contents to the current working directory:
    tar xzf istio-1.28.2-asm.4-linux-amd64.tar.gz

    The command creates an installation directory in your current working directory namedistio-1.28.2-asm.4 that contains:

    • Sample applications in thesamples directory.
    • Theistioctl command-line tool that you use to install Anthos Service Mesh is in thebin directory.
    • The Anthos Service Mesh configuration profiles are in themanifests/profiles directory.
  5. Ensure that you're in the Anthos Service Mesh installation's root directory:
    cd istio-1.28.2-asm.4
  6. For convenience, add the tools in the /bin directory to your PATH:
    export PATH=$PWD/bin:$PATH

    7. Mac OS

  7. Download the Anthos Service Mesh installation file to your current working directory:
    curl -LO https://storage.googleapis.com/gke-release/asm/istio-1.28.2-asm.4-osx.tar.gz
  8. Download the signature file and use openssl to verify the signature:
    curl -LO https://storage.googleapis.com/gke-release/asm/istio-1.28.2-asm.4-osx.tar.gz.1.sig
    openssldgst-sha256-verify/dev/stdin-signature istio-1.28.2-asm.4-osx.tar.gz.1.sig istio-1.28.2-asm.4.tar.gz <<'EOF'-----BEGINPUBLICKEY-----MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEWZrGCUaJJr1H8a36sG4UUoXvlXvZwQfk16sxprI2gOJ2vFFggdq3ixF2h4qNBt0kI7ciDhgpwS8t+/960IsIgw==-----ENDPUBLICKEY-----EOF
  9. Extract the contents of the file to any location on your file system. For example, to extract the contents to the current working directory:
    tar xzf istio-1.28.2-asm.4-osx.tar.gz

    The command creates an installation directory in your current working directory namedistio-1.28.2-asm.4 that contains:

    • Sample applications in thesamples directory.
    • Theistioctl command-line tool that you use to install Anthos Service Mesh is in thebin directory.
    • The Anthos Service Mesh configuration profiles are in themanifests/profiles directory.
  10. Ensure that you're in the Anthos Service Mesh installation's root directory:
    cd istio-1.28.2-asm.4
  11. For convenience, add the tools in the /bin directory to your PATH:
    export PATH=$PWD/bin:$PATH

    12. Windows

  12. Download the Anthos Service Mesh installation file to your current working directory:
    curl -LO https://storage.googleapis.com/gke-release/asm/istio-1.28.2-asm.4-win.zip
  13. Download the signature file and use openssl to verify the signature:
    curl -LO https://storage.googleapis.com/gke-release/asm/istio-1.28.2-asm.4-win.zip.1.sig
    openssldgst-verify--signature istio-1.28.2-asm.4-win.zip.1.sig istio-1.28.2-asm.4.win.zip <<'EOF'-----BEGINPUBLICKEY-----MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEWZrGCUaJJr1H8a36sG4UUoXvlXvZwQfk16sxprI2gOJ2vFFggdq3ixF2h4qNBt0kI7ciDhgpwS8t+/960IsIgw==-----ENDPUBLICKEY-----EOF
  14. Extract the contents of the file to any location on your file system. For example, to extract the contents to the current working directory:
    tar xzf istio-1.28.2-asm.4-win.zip

    The command creates an installation directory in your current working directory namedistio-1.28.2-asm.4 that contains:

    • Sample applications in thesamples directory.
    • Theistioctl command-line tool that you use to install Anthos Service Mesh is in thebin directory.
    • The Anthos Service Mesh configuration profiles are in themanifests\profiles directory.
  15. Ensure that you're in the Anthos Service Mesh installation's root directory:
    cd istio-1.28.2-asm.4
  16. For convenience, add the tools in the \bin directory to your PATH:
    set PATH=%CD%\bin:%PATH%
  17. Now that ASM Istio is installed, check the version ofistioctl:
    istioctl version
  18. Create a namespace called istio-system for the control plane components:
    kubectl create namespace istio-system

Installing Anthos Service Mesh

  1. Edit youroverlay.yaml file or create a new one with the following contents:
    apiVersion: install.istio.io/v1alpha1kind: IstioOperatorspec:  meshConfig:    accessLogFile: /dev/stdout    enableTracing: true    accessLogFormat:      '{"start_time":"%START_TIME%","remote_address":"%DOWNSTREAM_DIRECT_REMOTE_ADDRESS%","user_agent":"%REQ(USER-AGENT)%","host":"%REQ(:AUTHORITY)%","request":"%REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?:PATH)% %PROTOCOL%","request_time":"%DURATION%","status":"%RESPONSE_CODE%","status_details":"%RESPONSE_CODE_DETAILS%","bytes_received":"%BYTES_RECEIVED%","bytes_sent":"%BYTES_SENT%","upstream_address":"%UPSTREAM_HOST%","upstream_response_flags":"%RESPONSE_FLAGS%","upstream_response_time":"%RESPONSE_DURATION%","upstream_service_time":"%RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)%","upstream_cluster":"%UPSTREAM_CLUSTER%","x_forwarded_for":"%REQ(X-FORWARDED-FOR)%","request_method":"%REQ(:METHOD)%","request_path":"%REQ(X-ENVOY-ORIGINAL-PATH?:PATH)%","request_protocol":"%PROTOCOL%","tls_protocol":"%DOWNSTREAM_TLS_VERSION%","request_id":"%REQ(X-REQUEST-ID)%","sni_host":"%REQUESTED_SERVER_NAME%","apigee_dynamic_data":"%DYNAMIC_METADATA(envoy.lua)%"}'  components:  - enabled: true    name: istio-ingressgateway    k8s:      service:        type: LoadBalancer        ports:        - name: status-port          port: 15021          targetPort: 15021        - name: http2          port: 80          targetPort: 8080        - name: https          port: 443          targetPort: 8443
  2. Install Anthos Service Mesh withistioctl using theasm-multicloud profile:
    istioctl install \    --set profile=asm-multicloud \    --set revision="asm-1282-4" \    --filename overlayfile.yaml

    Your output should look something like:

    kubectl get pods -n istio-systemNAME                                   READY   STATUS    RESTARTS   AGEistio-ingressgateway-88b6fd976-flgp2   1/1     Running   0          3m13sistio-ingressgateway-88b6fd976-p5dl9   1/1     Running   0          2m57sistiod-asm-1282-4-798ffb964-2ls88       1/1     Running   0          3m21sistiod-asm-1282-4-798ffb964-fnj8c       1/1     Running   1          3m21s

    The--set revision argument adds a revision label in the formatistio.io/rev=asm-1282-4 to istiod. The revision label is used by the automatic sidecar injector webhook to associate injected sidecars with a particular istiod revision. To enable sidecar auto-injection for a namespace, you must label it with a revision that matches the label on istiod.

  3. Verify that your install completed:
    kubectl get svc -n istio-system

    Your output should look something like:

    NAME                   TYPE           CLUSTER-IP       EXTERNAL-IP     PORT(S)                                                                      AGEistio-ingressgateway   LoadBalancer   172.200.48.52    34.74.177.168   15021:30479/TCP,80:30030/TCP,443:32200/TCP,15012:32297/TCP,15443:30244/TCP   3m35sistiod                 ClusterIP      172.200.18.133   <none>          15010/TCP,15012/TCP,443/TCP,15014/TCP                                        4m46sistiod-asm-1282-4       ClusterIP      172.200.63.220   <none>          15010/TCP,15012/TCP,443/TCP,15014/TCP                                        3m43s

OpenShift

In these instructions the process of upgrading Anthos Service Mesh (ASM) version istio-1.28.2-asm.4 on Anthos attached clusters is the same as performing a fresh install.

Preparing to install Anthos Service Mesh

  1. Delete the mutating webhook and validating webhook:
    1. cd into the directory where you installedasmcli.
    2. Store the current new revision in an environment variable to use in the script to delete the webhooks:
      UPGRADE_REV="asm-1282-4"
    3. create a shell script containing the following commands:
      #!/bin/bashset -exkubectl label namespace istio-system istio.io/rev=${UPGRADE_REV} istio-injection- --overwritekubectl rollout restart deployment -n istio-systemkubectl apply -n istio-system -fPATH_TO_INGRESSGATEWAYistio-ingressgatewaykubectl apply -n istio-system -fPATH_TO_INGRESSGATEWAY/istio-ingressgateway-connectorsif [[ "${DELETE_REV}" != "${UPGRADE_REV}" ]]; then  kubectl apply -f out/asm/istio/istiod-service.yaml  kubectl delete deploy -l app=istio-ingressgateway,istio.io/rev=${DELETE_REV} -n istio-system --ignore-not-found=true  kubectl delete deploy -l app=istio-ingressgateway-connectors,istio.io/rev=${DELETE_REV} -n istio-system --ignore-not-found=true  kubectl delete ValidatingWebhookConfiguration -l app=istiod,istio.io/rev=${DELETE_REV} -n istio-system --ignore-not-found=true  kubectl delete MutatingWebhookConfiguration -l app=sidecar-injector,istio.io/rev=${DELETE_REV} -n istio-system --ignore-not-found=true  kubectl delete Service,Deployment,HorizontalPodAutoscaler,PodDisruptionBudget istiod-${DELETE_REV} -n istio-system --ignore-not-found=true  kubectl delete IstioOperator installed-state-${DELETE_REV} -n istio-system --ignore-not-found=truefi
    4. Execute the script to delete the current webhooks.

    2. Linux

  2. Grant theanyuid security context constraint (SCC) to the istio-system with the following OpenShift CLI (oc) command:
    oc adm policy add-scc-to-group anyuid system:serviceaccounts:istio-system
  3. Download the Anthos Service Mesh installation file to your current working directory:
    curl -LO https://storage.googleapis.com/gke-release/asm/istio-1.28.2-asm.4-linux-amd64.tar.gz
  4. Download the signature file and use openssl to verify the signature:
    curl -LO https://storage.googleapis.com/gke-release/asm/istio-1.28.2-asm.4-linux-amd64.tar.gz.1.sig
    openssldgst-verify/dev/stdin-signature istio-1.28.2-asm.4-linux-amd64.tar.gz.1.sig istio-1.28.2-asm.4.tar.gz <<'EOF'-----BEGINPUBLICKEY-----MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEWZrGCUaJJr1H8a36sG4UUoXvlXvZwQfk16sxprI2gOJ2vFFggdq3ixF2h4qNBt0kI7ciDhgpwS8t+/960IsIgw==-----ENDPUBLICKEY-----EOF
  5. Extract the contents of the file to any location on your file system. For example, to extract the contents to the current working directory:
    tar xzf istio-1.28.2-asm.4-linux-amd64.tar.gz

    The command creates an installation directory in your current working directory namedistio-1.28.2-asm.4 that contains:

    • Sample applications in thesamples directory.
    • Theistioctl command-line tool that you use to install Anthos Service Mesh is in thebin directory.
    • The Anthos Service Mesh configuration profiles are in themanifests/profiles directory.
  6. Ensure that you're in the Anthos Service Mesh installation's root directory:
    cd istio-1.28.2-asm.4
  7. For convenience, add the tools in the /bin directory to your PATH:
    export PATH=$PWD/bin:$PATH

    8. Mac OS

  8. Grant theanyuid security context constraint (SCC) to the istio-system with the following OpenShift CLI (oc) command:
    oc adm policy add-scc-to-group anyuid system:serviceaccounts:istio-system
  9. Download the Anthos Service Mesh installation file to your current working directory:
    curl -LO https://storage.googleapis.com/gke-release/asm/istio-1.28.2-asm.4-osx.tar.gz
  10. Download the signature file and use openssl to verify the signature:
    curl -LO https://storage.googleapis.com/gke-release/asm/istio-1.28.2-asm.4-osx.tar.gz.1.sig
    openssldgst-sha256-verify/dev/stdin-signature istio-1.28.2-asm.4-osx.tar.gz.1.sig istio-1.28.2-asm.4.tar.gz <<'EOF'-----BEGINPUBLICKEY-----MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEWZrGCUaJJr1H8a36sG4UUoXvlXvZwQfk16sxprI2gOJ2vFFggdq3ixF2h4qNBt0kI7ciDhgpwS8t+/960IsIgw==-----ENDPUBLICKEY-----EOF
  11. Extract the contents of the file to any location on your file system. For example, to extract the contents to the current working directory:
    tar xzf istio-1.28.2-asm.4-osx.tar.gz

    The command creates an installation directory in your current working directory namedistio-1.28.2-asm.4 that contains:

    • Sample applications in thesamples directory.
    • Theistioctl command-line tool that you use to install Anthos Service Mesh is in thebin directory.
    • The Anthos Service Mesh configuration profiles are in themanifests/profiles directory.
  12. Ensure that you're in the Anthos Service Mesh installation's root directory:
    cd istio-1.28.2-asm.4
  13. For convenience, add the tools in the /bin directory to your PATH:
    export PATH=$PWD/bin:$PATH

    14. Windows

  14. Grant theanyuid security context constraint (SCC) to the istio-system with the following OpenShift CLI (oc) command:
    oc adm policy add-scc-to-group anyuid system:serviceaccounts:istio-system
  15. Download the Anthos Service Mesh installation file to your current working directory:
    curl -LO https://storage.googleapis.com/gke-release/asm/istio-1.28.2-asm.4-win.zip
  16. Download the signature file and use openssl to verify the signature:
    curl -LO https://storage.googleapis.com/gke-release/asm/istio-1.28.2-asm.4-win.zip.1.sig
    openssldgst-verify--signature istio-1.28.2-asm.4-win.zip.1.sig istio-1.28.2-asm.4.win.zip <<'EOF'-----BEGINPUBLICKEY-----MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEWZrGCUaJJr1H8a36sG4UUoXvlXvZwQfk16sxprI2gOJ2vFFggdq3ixF2h4qNBt0kI7ciDhgpwS8t+/960IsIgw==-----ENDPUBLICKEY-----EOF
  17. Extract the contents of the file to any location on your file system. For example, to extract the contents to the current working directory:
    tar xzf istio-1.28.2-asm.4-win.zip

    The command creates an installation directory in your current working directory namedistio-1.28.2-asm.4 that contains:

    • Sample applications in thesamples directory.
    • Theistioctl command-line tool that you use to install Anthos Service Mesh is in thebin directory.
    • The Anthos Service Mesh configuration profiles are in themanifests\profiles directory.
  18. Ensure that you're in the Anthos Service Mesh installation's root directory:
    cd istio-1.28.2-asm.4
  19. For convenience, add the tools in the \bin directory to your PATH:
    set PATH=%CD%\bin:%PATH%
  20. Now that ASM Istio is installed, check the version ofistioctl:
    istioctl version
  21. Create a namespace called istio-system for the control plane components:
    kubectl create namespace istio-system

Installing Anthos Service Mesh

  1. Edit youroverlay.yaml file or create a new one with the following contents:
    apiVersion: install.istio.io/v1alpha1kind: IstioOperatorspec:  meshConfig:    accessLogFile: /dev/stdout    enableTracing: true    accessLogFormat:      '{"start_time":"%START_TIME%","remote_address":"%DOWNSTREAM_DIRECT_REMOTE_ADDRESS%","user_agent":"%REQ(USER-AGENT)%","host":"%REQ(:AUTHORITY)%","request":"%REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?:PATH)% %PROTOCOL%","request_time":"%DURATION%","status":"%RESPONSE_CODE%","status_details":"%RESPONSE_CODE_DETAILS%","bytes_received":"%BYTES_RECEIVED%","bytes_sent":"%BYTES_SENT%","upstream_address":"%UPSTREAM_HOST%","upstream_response_flags":"%RESPONSE_FLAGS%","upstream_response_time":"%RESPONSE_DURATION%","upstream_service_time":"%RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)%","upstream_cluster":"%UPSTREAM_CLUSTER%","x_forwarded_for":"%REQ(X-FORWARDED-FOR)%","request_method":"%REQ(:METHOD)%","request_path":"%REQ(X-ENVOY-ORIGINAL-PATH?:PATH)%","request_protocol":"%PROTOCOL%","tls_protocol":"%DOWNSTREAM_TLS_VERSION%","request_id":"%REQ(X-REQUEST-ID)%","sni_host":"%REQUESTED_SERVER_NAME%","apigee_dynamic_data":"%DYNAMIC_METADATA(envoy.lua)%"}'  components:  - enabled: true    name: istio-ingressgateway    k8s:      service:        type: LoadBalancer        ports:        - name: status-port          port: 15021          targetPort: 15021        - name: http2          port: 80          targetPort: 8080        - name: https          port: 443          targetPort: 8443
  2. Install Anthos Service Mesh withistioctl using theasm-multicloud profile:
    istioctl install \    --set profile=asm-multicloud \    --set revision="asm-1282-4" \    --filename overlayfile.yaml

    Your output should look something like:

    kubectl get pods -n istio-systemNAME                                   READY   STATUS    RESTARTS   AGEistio-ingressgateway-88b6fd976-flgp2   1/1     Running   0          3m13sistio-ingressgateway-88b6fd976-p5dl9   1/1     Running   0          2m57sistiod-asm-1282-4-798ffb964-2ls88       1/1     Running   0          3m21sistiod-asm-1282-4-798ffb964-fnj8c       1/1     Running   1          3m21s

    The--set revision argument adds a revision label in the formatistio.io/rev=1.6.11-asm.1 to istiod. The revision label is used by the automatic sidecar injector webhook to associate injected sidecars with a particular istiod revision. To enable sidecar auto-injection for a namespace, you must label it with a revision that matches the label on istiod.

  3. Verify that your install completed:
    kubectl get svc -n istio-system

    Your output should look something like:

    NAME                   TYPE           CLUSTER-IP       EXTERNAL-IP     PORT(S)                                                                      AGEistio-ingressgateway   LoadBalancer   172.200.48.52    34.74.177.168   15021:30479/TCP,80:30030/TCP,443:32200/TCP,15012:32297/TCP,15443:30244/TCP   3m35sistiod                 ClusterIP      172.200.18.133   <none>          15010/TCP,15012/TCP,443/TCP,15014/TCP                                        4m46sistiod-asm-1282-4       ClusterIP      172.200.63.220   <none>          15010/TCP,15012/TCP,443/TCP,15014/TCP                                        3m43s
Congratulations! You have successfully upgraded to Apigee hybrid version 1.7.6.

Rolling back an upgrade

Follow these steps to roll back a previous upgrade:

  1. Clean up completed jobs for the hybrid runtime namespace, whereNAMESPACE is the namespace specified in your overrides file, if you specified a namespace. If not, the default namespace isapigee:
    kubectl delete job -nNAMESPACE \  $(kubectl get job -nNAMESPACE \  -o=jsonpath='{.items[?(@.status.succeeded==1)].metadata.name}')
  2. Clean up completed jobs for theapigee-system namespace:
    kubectl delete job -n apigee-system \  $(kubectl get job -n apigee-system \  -o=jsonpath='{.items[?(@.status.succeeded==1)].metadata.name}')
  3. Change theAPIGEECTL_HOME variable to point to the directory that contains the previous version ofapigeectl. For example:
    export APIGEECTL_HOME=PATH_TO_PREVIOUS_APIGEECTL_DIRECTORY
  4. In the root directory of the installation you want to roll back to, run${APIGEECTL_HOME}/apigeectl apply, check the status of your pods, and then run${APIGEECTL_HOME}/apigeectl init. Be sure to use the original overrides file for the version you wish to roll back to:
    1. In thehybrid-files directory, run${APIGEECTL_HOME}/apigeectl apply:
      ${APIGEECTL_HOME}/apigeectlapply-f./overrides/ORIGINAL_OVERRIDES.yaml

      WhereORIGINAL_OVERRIDES is the overrides file for your previous version hybrid installation, for example,overrides1.6.yaml.

    2. Check the status of your pods:
      kubectl -nNAMESPACE get pods

      WhereNAMESPACE is your Apigee hybrid namespace.

    3. Check the status ofapigeeds:
      kubectl describe apigeeds -n apigee

      Your output should look something like:

      Status:CassandraDataReplication:CassandraPodIps:10.8.2.204CassandraReadyReplicas:1Components:Cassandra:LastSuccessfullyReleasedVersion:Revision:v1-f8aa9a82b9f69613Version:v1Replicas:Available:1Ready:1Total:1Updated:1State:runningScaling:InProgress:falseOperation:RequestedReplicas:0State:running

      Proceed to the next step only when theapigeeds pod is running.

    4. Runapigeectl init:
      ${APIGEECTL_HOME}/apigeectlinit-f./overrides/ORIGINAL_OVERRIDES.yaml

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-18 UTC.