> [!CAUTION]
> You are currently viewing version 1.4 of the Apigee hybrid documentation. **This version is end of life.** You should upgrade to a newer version. For more information, see [Supported versions](https://docs.cloud.google.com/apigee/docs/hybrid/supported-platforms.md.txt#supported-versions).

<button class="button button-with-icon cloud-select-dropdown__button button-primary" aria-haspopup="true">Version 1.4 (unsupported)</button>

- Supported versions:
- [v1.17 (latest)](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt)
- [v1.16](https://docs.cloud.google.com/apigee/docs/hybrid/v1.16/upgrade.md.txt)
- [v1.15](https://docs.cloud.google.com/apigee/docs/hybrid/v1.15/upgrade.md.txt)
- [v1.14](https://docs.cloud.google.com/apigee/docs/hybrid/v1.14/upgrade.md.txt)
- [List of supported versions](https://docs.cloud.google.com/apigee/docs/hybrid/supported-platforms.md.txt#supported-versions)
- Unsupported versions:
- [v1.13](https://docs.cloud.google.com/apigee/docs/hybrid/v1.13/upgrade.md.txt)
- [v1.12](https://docs.cloud.google.com/apigee/docs/hybrid/v1.12/upgrade.md.txt)
- [v1.11](https://docs.cloud.google.com/apigee/docs/hybrid/v1.11/upgrade.md.txt)
- [v1.10](https://docs.cloud.google.com/apigee/docs/hybrid/v1.10/upgrade.md.txt)
- [v1.9](https://docs.cloud.google.com/apigee/docs/hybrid/v1.9/upgrade.md.txt)
- [v1.8](https://docs.cloud.google.com/apigee/docs/hybrid/v1.8/upgrade.md.txt)
- [v1.7](https://docs.cloud.google.com/apigee/docs/hybrid/v1.7/upgrade.md.txt)
- [v1.6](https://docs.cloud.google.com/apigee/docs/hybrid/v1.6/upgrade.md.txt)
- [v1.5](https://docs.cloud.google.com/apigee/docs/hybrid/v1.5/upgrade.md.txt)
- [v1.4](https://docs.cloud.google.com/apigee/docs/hybrid/v1.4/upgrade.md.txt)
- [v1.3](https://docs.cloud.google.com/apigee/docs/hybrid/v1.3/upgrade.md.txt)
- [v1.2](https://docs.cloud.google.com/apigee/docs/hybrid/v1.2/upgrade.md.txt)
- [v1.1](https://docs.cloud.google.com/apigee/docs/hybrid/v1.1/upgrade.md.txt)

> [!NOTE]
> **Note:** This procedure covers upgrading from Apigee hybrid version 1.3.x to Apigee hybrid version 1.4.4 only.
>
>
> If you are upgrading from Apigee hybrid version 1.2 or older, you must first upgrade to
> hybrid version 1.3 before upgrading to version 1.4.4.
> See the instructions for [Upgrading
> Apigee hybrid to version 1.3](https://docs.cloud.google.com/apigee/docs/hybrid/v1.3/upgrade).

## Upgrading to version 1.4.4 overview.

> [!WARNING]
> Upgrading to Apigee hybrid version 1.4.4 may require downtime:
>
> - When upgrading Anthos Service Mesh (ASM) 1.5.x Ingress Gateway to version 1.6.x, you should expect a few seconds of downtime when the ingress changes between the two versions.
> - When upgrading the Apigee controller to version 1.4.4, all Apigee deployments undergo a rolling restart.
>
>
> To minimize downtime in production hybrid environments, make sure you are running at least two
> clusters (in the same or different region/data center). Divert all production traffic to a
> single cluster and take the cluster you are about to upgrade offline, and then proceed with the
> upgrade process. Repeat the process for each cluster.


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

1. Backup your hybrid installation.
2. Check your Kubernetes version and upgrade as appropriate.
3. Upgrade ASM.
4. Install hybrid runtime version 1.4.

> [!NOTE]
> **Note:**Do not create new environments during the upgrade process.

## Prerequisite

- Apigee hybrid version 1.3. If you are updating from an earlier version see the instructions for [Upgrading Apigee hybrid to version 1.3](https://docs.cloud.google.com/apigee/docs/hybrid/v1.3/upgrade.md.txt).

## Upgrade to version 1.4

1. (Recommended) Make a backup copy of your version 1.3 `$APIGEECTL_HOME/` directory. For example:

       tar -czvf $APIGEECTL_HOME/../apigeectl-v1.3-backup.tar.gz $APIGEECTL_HOME

2. (Recommended) Backup your Cassandra database following the instructions in [Cassandra backup and recovery](https://docs.cloud.google.com/apigee/docs/hybrid/v1.4/backup-recovery.md.txt)
3. Upgrade your Kubernetes platform as follows. Follow your platform's documentation if you need help:

   | Platform | Upgrade to version |
   |---|---|
   | GKE | 1.18.x |
   | GKE on-prem (Anthos) | 1.5.x |
   | AKS | 1.18.x using [Anthos attached clusters](https://cloud.google.com/anthos/docs/setup/attach-kubernetes-clusters) |
   | EKS | 1.18.x using [Anthos attached clusters](https://cloud.google.com/anthos/docs/setup/attach-kubernetes-clusters) |

4. Upgrade ASM to version 1.6.x.

   > [!NOTE]
   > 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:
   > 1. Disable your load balancer.
   > 2. Upgrade ASM on one cluster at a time.
   > 3. Enable your load balancer.

   1. Perform the upgrade using the ASM documentation:
      - GKE on-prem (Anthos): [Upgrading
        Anthos Service Mesh on premises](https://cloud.google.com/service-mesh/docs/archive/1.6/docs/gke-on-prem-upgrading)
      - All other platforms: [Upgrading
        Anthos Service Mesh on GKE](https://cloud.google.com/service-mesh/docs/archive/1.6/docs/upgrading-gke)
   2. Specify the following ingress ports and set the `runAsRoot` property to `true` in your `istio-operator.yaml` file"

      ```
          … … …
                  ports:
                  - port: 15021
                    name: status-port
                    targetPort: 15021
                  - port: 80
                    name: http2
                    targetPort: 80
                  - port: 443
                    name: https
                    targetPort: 443

          … … …
          values:
            gateways:
              istio-ingressgateway:
                runAsRoot: true 
      ```
   3. Create PeerAuthentication CRs for disabling mTLS in your `istio-operator.yaml` file:

      ```
      ---
      apiVersion: security.istio.io/v1beta1
      kind: PeerAuthentication
      metadata:
        name: apigee-system
        namespace: apigee-system
      spec:
        mtls:
          mode: DISABLE
      ---
      apiVersion: security.istio.io/v1beta1
      kind: PeerAuthentication
      metadata:
        name: user-namespace
        namespace: user-namespace
      spec:
        mtls:
          mode: DISABLE
      ```
   4. Apply these changes with `istioctl` as described in the ASM documentation:
      - GKE on-prem (Anthos): [Updating the control plane](https://cloud.google.com/service-mesh/docs/archive/1.6/docs/gke-on-prem-upgrading?hl=en#updating_the_control_plane)
      - All other platforms: [Updating the control plane](https://cloud.google.com/service-mesh/docs/archive/1.6/docs/upgrading-gke?hl=en#updating_the_control_plane)

## Install the hybrid 1.4.4 runtime

1. Store the latest version number in a variable:

   ```
   export VERSION=$(curl -s \
       https://storage.googleapis.com/apigee-release/hybrid/apigee-hybrid-setup/current-version.txt?ignoreCache=1)
   ```
2. Check that the variable was populated with a version number. If you want to use a different version, you can save that in an environment variable instead. For example:

   ```
   echo $VERSION
   ```

   ```
     1.4.4
   ```
3. Download the release package for your operating system:

   **Mac 64 bit:**

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

   **Linux 64 bit:**

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

   **Mac 32 bit:**

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

   **Linux 32 bit:**

   ```
   curl -LO \
       https://storage.googleapis.com/apigee-release/hybrid/apigee-hybrid-setup/$VERSION/apigeectl_linux_32.tar.gz
   ```
4. Rename your current `apigeectl/` directory to a backup directory name. For example:

       mv $APIGEECTL_HOME/ $APIGEECTL_HOME-v1.2/ 

5. Extract the downloaded gzip file contents into your hybrid base directory. For example:

   ```
   tar xvzf filename.tar.gz -C hybrid-base-directory
   ```
6. `cd` to the base directory.
7. The tar contents are, by default, expanded into a directory with the version and platform in its
   name. For example: `./apigeectl_1.4.4-xxx_linux_64`. Rename that directory
   to `apigeectl`:

   ```
   mv apigeectl_1.4.5-xxx_linux_64 apigeectl
   ```
8. In the **new** `apigeectl/` directory, run `apigeectl init`, `apigeectl apply`, and `apigeectl check-ready`:
   1. Initialize hybrid 1.4.4:

      ```
      apigeectl init -f overrides.yaml
      ```


      Where <var translate="no">overrides.yaml</var> is your edited overrides.yaml file.
   2. Check that it initialized correctly with the following commands:

      ```
      apigeectl check-ready -f overrides.yaml
      ```

      ```
      kubectl describe apigeeds -n apigee
      ```


      Your output should look something like:

      ```
      Status:
        Cassandra Data Replication:
        Cassandra Pod Ips:
          10.8.2.204
        Cassandra Ready Replicas:  1
        Components:
          Cassandra:
            Last Successfully Released Version:
              Revision:  v1-f8aa9a82b9f69613
              Version:   v1
            Replicas:
              Available:  1
              Ready:      1
              Total:      1
              Updated:    1
            State:        running
        Scaling:
          In Progress:         false
          Operation:
          Requested Replicas:  0
        State:                 running
      ```
   3. The syntax of the `apigeectl` `--dry-run` flag depends on the version of `kubectl` you are running. Check the version of `kubectl`:

      ```
      gcloud version
      ```
   4. Check for errors with a dry run with the command appropriate to your version of `kubectl`:


      `kubectl` version 1.17 and older:

      ```
      apigeectl apply -f overrides.yaml --dry-run=true
      ```


      `kubectl` version 1.18 and newer:

      ```
      apigeectl apply -f overrides.yaml --dry-run=client
      ```
   5. Apply your overrides. Select and follow the instructions for production environments or demo/experimental environments, depending on your installation.

      > [!TIP]
      > 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. Apply your overrides to upgrade Cassandra:

         ```
         apigeectl apply -f overrides.yaml --datastore
         ```
      2. Check completion:

         ```
         kubectl -n namespace get pods
         ```

         ```
         apigeectl check-ready -f overrides.yaml
         ```


         Where <var translate="no">namespace</var> is your Apigee hybrid namespace.


         Proceed to the next step only when the pods are ready.
      3. Apply your overrides to upgrade Telemetry components and check completion:

         ```
         apigeectl apply -f overrides.yaml --telemetry
         ```

         ```
         kubectl -n namespace get pods
         ```

         ```
         apigeectl check-ready -f overrides.yaml
         ```
      4. Apply your overrides to upgrade the org-level components (MART, Watcher and Apigee Connect) and check completion:

         ```
         apigeectl apply -f overrides.yaml --org
         ```

         ```
         kubectl -n namespace get pods
         ```

         ```
         apigeectl check-ready -f overrides.yaml
         ```
      5. 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 apply -f overrides.yaml --env env_name
           ```

           ```
           kubectl -n namespace get pods
           ```

           ```
           apigeectl check-ready -f overrides.yaml
           ```


           Where <var translate="no">env_name</var> 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 apply -f overrides.yaml --all-envs
           ```

           ```
           kubectl -n namespace get pods
           ```

           ```
           apigeectl check-ready -f 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 upgrading
      [production environments](https://docs.cloud.google.com/apigee/docs/hybrid/v1.4/upgrade.md.txt#production)
      1.

         ```
         apigeectl apply -f overrides.yaml
         ```
      2. Check the status:

         ```
         apigeectl check-ready -f overrides.yaml
         ```


   **Congratulations!** You have successfully upgraded to Apigee hybrid version 1.4.4.