<button class="button button-with-icon cloud-select-dropdown__button button-primary" aria-haspopup="true">Version 1.17 (latest)</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)

This procedure covers upgrading from Apigee hybrid
version 1.16.x to Apigee hybrid version 1.17.3 and
from previous releases of hybrid 1.17.x to version
1.17.3.


Use the same procedures for minor version upgrades (for example version 1.16
to 1.17) and for patch release upgrades (for example
1.17.0 to 1.17.3).


If you are upgrading from Apigee hybrid version 1.15 or older, you must first upgrade to
hybrid version 1.16 before upgrading to version 1.17.3.
See the instructions for [Upgrading
Apigee hybrid to version 1.16](https://docs.cloud.google.com/apigee/docs/hybrid/v1.16/upgrade).

## Changes from Apigee hybrid v1.16

Please note the following changes:

- **Model Context Protocol (MCP) support** : Apigee hybrid version 1.17 adds support for the [Model Context Protocol (MCP)](https://modelcontextprotocol.io), an open protocol that lets agentic AI applications use your APIs as tools through managed MCP endpoints. Apigee hybrid routes, authorizes, and secures these MCP tool calls the same way it manages your other APIs, so you don't need to run or maintain your own MCP servers. For more information, see [Model Context Protocol (MCP)
  in Apigee overview](https://docs.cloud.google.com/apigee/docs/api-platform/apigee-mcp/apigee-mcp-overview) and the [MCP quickstart](https://docs.cloud.google.com/apigee/docs/api-platform/apigee-mcp/apigee-mcp-quickstart.md.txt).
- **Root CA certificate rotation** : Apigee hybrid version 1.17 adds support for rotating the root certificate authority (CA) certificate that anchors trust for TLS communication between your runtime components. You can now replace the root CA before it expires, without downtime, by following a phased rotation procedure. For more information, see [Rotate the root CA
  certificate](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/rotate-root-ca).
- **TLS 1.3 support** : Apigee hybrid version 1.17 adds support for TLS 1.3, the latest version of the Transport Layer Security protocol. TLS 1.3 offers faster connection handshakes and stronger security than earlier TLS versions. For information about configuring TLS on the ingress gateway, see [Configuring TLS and mTLS on
  the ingress gateway](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/ingress-tls).
- **Forward proxy support for AI policies** : Apigee hybrid version 1.17 adds forward proxy support for the AI policies, such as the Model Armor and semantic caching policies. Outbound calls that these policies make can now be routed through an HTTP forward proxy, which was not supported in earlier versions of Apigee hybrid. For more information, see [Configure forward
  proxying for API proxies](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/forward-proxy).
- **Semantic cache Private Service Connect (PSC) endpoint support** : Apigee hybrid version 1.17 adds Private Service Connect (PSC) endpoint support for semantic caching. The semantic caching policies can now reach their backing services over a Private Service Connect endpoint, which keeps that traffic on your private network. For more information, see [Get started with
  semantic caching policies](https://docs.cloud.google.com/apigee/docs/api-platform/tutorials/using-semantic-caching-policies).

For additional information about features in Hybrid version 1.17, see the
[Apigee hybrid
v1.17.3 release notes](https://docs.cloud.google.com/apigee/docs/hybrid/release-notes#hybrid_v1173).

## Prerequisites


Before upgrading to hybrid version 1.17, make sure your
installation meets the following requirements:

- If your hybrid installation is running a version older than v1.16, you must upgrade to version 1.16 before upgrading to v1.17. See [Upgrading Apigee hybrid to version 1.16](https://docs.cloud.google.com/apigee/docs/hybrid/v1.16/upgrade.md.txt).
- Helm version v3.14.2+.
- `kubectl`: A supported version of `kubectl` appropriate for your Kubernetes platform version. See [Supported platforms and versions: `kubectl`](https://docs.cloud.google.com/apigee/docs/hybrid/supported-platforms.md.txt#kubectl).
- cert-manager: A supported version of cert-manager. See [Supported platforms and versions: cert-manager](https://docs.cloud.google.com/apigee/docs/hybrid/supported-platforms.md.txt#cert-manager). If needed, you will upgrade cert-manager in the [Prepare to upgrade to version 1.17](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#prepare) section below.

## Before you upgrade to 1.17.3 - limitations and important notes

- **Important:** Versions 1.17.3, 1.17.4, and 1.17.5 replace the `ApigeeRedis` resource with the new `ApigeeValkey` resource in three steps. Install these patch releases in order. Before you upgrade to version 1.18, you must upgrade to version 1.17.5 or a later 1.17 patch release.

  In version 1.17.3, the runtime continues to use `ApigeeRedis`, and you don't need
  to change your configuration or install the `apigee-valkey` chart. Version
  1.17.3 adds the following items:
  - The `ApigeeValkey` custom resource definition (CRD). You install it with the other CRDs in [Prepare to upgrade](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#prepare).
  - The `apigee-valkey` Helm chart and the [`valkey`](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/config-prop-ref.md.txt#valkey) configuration properties.
  - The [`ao.args.valkeyBackend`](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/config-prop-ref.md.txt#ao-args-valkeybackend) property, which is `false` by default. Leave it set to `false`.
- Upgrading to Apigee hybrid version 1.17 may require
  downtime.

  When upgrading the Apigee controller to version 1.17.3, all Apigee
  deployments undergo a rolling restart. To minimize downtime in production hybrid environments
  during a rolling restart, 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.

  Apigee recommends that once you begin the upgrade, you should upgrade all clusters as soon as possible to reduce the chances
  of production impact. There is no time limit on when all remaining clusters must be upgraded
  after the first one is upgraded. However, until all remaining clusters are upgraded Cassandra
  backup and restore cannot work with mixed versions. For example, a backup from Hybrid
  1.16 cannot be used to restore a Hybrid 1.17
  instance.
- Management plane changes do not need to be fully suspended during an upgrade.
  Any required temporary suspensions to management plane changes are noted in the upgrade
  instructions below.

## Upgrading to version 1.17.3 overview


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

1. [Prepare to upgrade](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#prepare).
2. [Install hybrid runtime version 1.17.3](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#install-runtime).

## Prepare to upgrade to version 1.17

### Back up your hybrid installation

1. These instructions use the environment variable <var translate="no">APIGEE_HELM_CHARTS_HOME</var> for the directory in your file system where you have installed the Helm charts. If needed, change directory into this directory and define the variable with the following command:

   ### Linux

       export APIGEE_HELM_CHARTS_HOME=$PWD
       echo $APIGEE_HELM_CHARTS_HOME

   ### Mac OS

       export APIGEE_HELM_CHARTS_HOME=$PWD
       echo $APIGEE_HELM_CHARTS_HOME

   ### Windows

       set APIGEE_HELM_CHARTS_HOME=%CD%
       echo %APIGEE_HELM_CHARTS_HOME%

2. Make a backup copy of your version 1.16 `$APIGEE_HELM_CHARTS_HOME/` directory. You can use any backup process. For example, you can create a `tar` file of your entire directory with:

       tar -czvf $APIGEE_HELM_CHARTS_HOME/../apigee-helm-charts-v1.16-backup.tar.gz $APIGEE_HELM_CHARTS_HOME

3. Back up your Cassandra database following the instructions in [Cassandra backup and recovery](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/cassandra-backup-overview.md.txt).
4. Make sure that your TLS certificate and key files (`.crt`, `.key`, and/or `.pem`) reside in the `$APIGEE_HELM_CHARTS_HOME/apigee-virtualhost/` directory.

### Upgrade your Kubernetes version


Check your Kubernetes platform version and if needed, upgrade your Kubernetes platform to a
version that is supported by both hybrid 1.16 and hybrid
1.17. Follow your platform's documentation if you need help.

#### *Click to expand a list of supported platforms*

### Supported versions

|   | 1.14 | 1.15 | 1.16 | 1.17 |
|---|---|---|---|---|---|
| GKE on Google Cloud | 1.28.x 1.29.x 1.30.x 1.31.x 1.32.x 1.33.x 1.34.x 1.35.x 1.36.x | 1.29.x 1.30.x 1.31.x 1.32.x 1.33.x 1.34.x 1.35.x 1.36.x | 1.31.x 1.32.x 1.33.x 1.34.x 1.35.x 1.36.x | 1.33.x 1.34.x 1.35.x 1.36.x |
| Google Distributed Cloud (software only) on VMware [](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note3) | 1.28.x 1.29.x 1.30.x 1.31.x 1.32.x 1.33.x 1.34.x 1.35.x 1.36.x | 1.29.x 1.30.x 1.31.x 1.32.x 1.33.x 1.34.x 1.35.x 1.36.x | 1.31.x 1.32.x 1.33.x 1.34.x 1.35.x 1.36.x | 1.33.x 1.34.x 1.35.x 1.36.x |
| Google Distributed Cloud (software only) on bare metal | 1.28.x 1.29.x 1.30.x 1.31.x 1.32.x 1.33.x 1.34.x 1.35.x 1.36.x | 1.29.x 1.30.x 1.31.x 1.32.x 1.33.x 1.34.x 1.35.x 1.36.x | 1.31.x 1.32.x 1.33.x 1.34.x 1.35.x 1.36.x | 1.33.x 1.34.x 1.35.x 1.36.x |
| EKS | 1.28.x 1.29.x 1.30.x 1.31.x 1.32.x 1.33.x 1.34.x 1.35.x 1.36.x | 1.29.x 1.30.x 1.31.x 1.32.x 1.33.x 1.34.x 1.35.x 1.36.x | 1.31.x 1.32.x 1.33.x 1.34.x 1.35.x 1.36.x | 1.33.x 1.34.x 1.35.x 1.36.x |
| AKS | 1.28.x 1.29.x 1.30.x 1.31.x 1.32.x 1.33.x 1.34.x 1.35.x 1.36.x | 1.29.x 1.30.x 1.31.x 1.32.x 1.33.x 1.34.x 1.35.x 1.36.x | 1.31.x 1.32.x 1.33.x 1.34.x 1.35.x 1.36.x | 1.34.x 1.35.x 1.36.x |
| OpenShift[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note7) | 4.13 4.14 4.15 4.16 4.17 4.18 4.19[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note11) 4.20[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note11) 4.21[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note11) 4.22[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note11) | 4.16 4.17 4.18 4.19[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note10) 4.20[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note10) 4.21[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note10) 4.22[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note10) | 4.16 4.18 4.19 4.20 4.21 4.22 | 4.20 4.21 4.22 |
| Rancher Kubernetes Engine (RKE) | v1.27.x 1.28.x 1.29.x 1.30.x 1.31.x 1.32.x 1.33.x 1.34.x 1.35.x 1.36.x | v1.28.x 1.29.x 1.30.x 1.31.x 1.32.x 1.33.x 1.34.x 1.35.x 1.36.x | 1.31.x 1.32.x 1.33.x 1.34.x 1.35.x 1.36.x | 1.33.x 1.34.x 1.35.x 1.36.x |
| Cloud Service Mesh | 1.22.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note2) | 1.22.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note2) | 1.22.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note2) | 1.22.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note2) |
| JDK | JDK 11 | JDK 11 | JDK 11 | JDK 17 |
| cert-manager | 1.15.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note8) 1.16.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note8) 1.17.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note8) | 1.16.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note8) 1.17.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note8) | 1.16.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note8) 1.17.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note8) 1.18.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note9) 1.19.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note9) | 1.17.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note8) 1.18.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note9) 1.19.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note9) |
| Cassandra | 4.0 | 4.0 | 4.0 | 4.0 |
| Kubernetes | 1.28.x 1.29.x 1.30.x 1.31.x 1.32.x 1.33.x 1.34.x 1.35.x 1.36.x | 1.29.x 1.30.x 1.31.x 1.32.x 1.33.x 1.34.x 1.35.x 1.36.x | 1.30.x 1.31.x 1.32.x 1.33.x 1.34.x 1.35.x 1.36.x | 1.33.x 1.34.x 1.35.x 1.36.x |
| kubectl | 1.28.x 1.29.x 1.30.x 1.31.x 1.32.x 1.33.x 1.34.x 1.35.x 1.36.x | 1.29.x 1.30.x 1.31.x 1.32.x 1.33.x 1.34.x 1.35.x 1.36.x | 1.30.x 1.31.x 1.32.x 1.33.x 1.34.x 1.35.x 1.36.x | 1.33.x 1.34.x 1.35.x 1.36.x |
| Helm | 3.14.2 through 3.x.x | 3.14.2 through 3.x.x | 3.17.0 through 3.x.x | 3.17.0 through 3.x.x |
| Secret Store CSI driver | 1.4.6+ | 1.4.6+ | 1.4.6+ | 1.4.6+ |
| Vault | 1.17.2 | 1.17.2 | 1.17.2 | 1.19.0+ |
| **^(1)^ The official EOL dates for Apigee hybrid versions 1.13 and older 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**. **^(2)^ Cloud Service Mesh is automatically installed with Apigee hybrid 1.9 and newer**. **^(3)^ Vault is not certified on Google Distributed Cloud for VMware.** ****^(4)^ Support available with Apigee hybrid version 1.10.5 and newer**. **^(5)^ Support available with Apigee hybrid version 1.11.2 and newer**. **^(6)^ Support available with Apigee hybrid version 1.12.1 and newer**. **^(7)^ Apigee hybrid is tested and certified on OpenShift using the Kubernetes version bundled with each specific OCP version**. **^(8)^ Some versions of cert-manager have an issue where the webhook TLS server may fail to automatically renew its CA certificate.** To avoid this, Apigee recommends using: - **Hybrid v1.13![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported"):** use cert-manager version [1.15.3](https://cert-manager.io/docs/releases/release-notes/release-notes-1.15/#v1155)+. - **Hybrid v1.14:** use cert-manager versions [1.15.3](https://cert-manager.io/docs/releases/release-notes/release-notes-1.15/#v1155)+ or [1.16.0](https://cert-manager.io/docs/releases/release-notes/release-notes-1.16/#v1163)+. - **Hybrid v1.15:** use cert-manager versions [1.16.0](https://cert-manager.io/docs/releases/release-notes/release-notes-1.16/#v1163)+ or [1.17.2](https://cert-manager.io/docs/releases/release-notes/release-notes-1.17/#v1172)+. - **Hybrid v1.16:** use cert-manager versions [1.16.0](https://cert-manager.io/docs/releases/release-notes/release-notes-1.16/#v1163)+, [1.17.2](https://cert-manager.io/docs/releases/release-notes/release-notes-1.17/#v1172)+, [1.18.0](https://cert-manager.io/docs/releases/release-notes/release-notes-1.18/#v1180)+ or [1.19.0](https://cert-manager.io/docs/releases/release-notes/release-notes-1.19/#v1190)+. See [Known Issue 465834046](https://docs.cloud.google.com/apigee/docs/release/known-issues.md.txt#465834046) for cert-manager releases 1.18 and 1.19. - **Hybrid v1.17:** use cert-manager versions [1.17.2](https://cert-manager.io/docs/releases/release-notes/release-notes-1.17/#v1172)+, [1.18.0](https://cert-manager.io/docs/releases/release-notes/release-notes-1.18/#v1180)+ or [1.19.0](https://cert-manager.io/docs/releases/release-notes/release-notes-1.19/#v1190)+. See [Known Issue 465834046](https://docs.cloud.google.com/apigee/docs/release/known-issues.md.txt#465834046) for cert-manager releases 1.18 and 1.19. **^(9)^ cert-manager release 1.18 introduces a change to the default private key rotation policy that may cause traffic interruptions. See [Known Issue 465834046](https://docs.cloud.google.com/apigee/docs/release/known-issues.md.txt#465834046) for a workaround.** **^(10)^ Support for OpenShift 4.19, 4.20, 4.21, \& 4.22 available with Apigee hybrid version 1.15.2 and newer.** **^(11)^ Support for OpenShift 4.19, 4.20, 4.21, \& 4.22 available with Apigee hybrid version 1.14.4 and newer.**** ||||||

> [!NOTE]
> **Note:** Hybrid installations are not currently supported on Autopilot clusters.

### Unsupported versions

|   | 1.6 ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported") [](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note1) | 1.7 ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported") [](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note1) | 1.8 ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported") [](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note1) | 1.9 ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported") [](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note1) | 1.10 ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported") [](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note1) | 1.11 ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported") [](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note1) | 1.12 ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported") [](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note1) | 1.13 ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported") [](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note1) |
|---|---|---|---|---|---|---|---|---|
| GKE on Google Cloud | 1.19.x 1.20.x 1.21.x | 1.20.x 1.21.x 1.22.x ^1.23.x^ | 1.21.x [](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note5) 1.22.x [](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note5) 1.23.x 1.24.x 1.25.x | 1.23.x 1.24.x 1.25.x 1.26.x | 1.24.x 1.25.x 1.26.x 1.27.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note4) 1.28.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note4) | 1.25.x 1.26.x 1.27.x 1.28.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note5) 1.29.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note5) | 1.26.x 1.27.x 1.28.x 1.29.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note6) | 1.27.x 1.28.x 1.29.x 1.30.x |
| Google Distributed Cloud (software only) on VMware [](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note3) | 1.7.x 1.8.x 1.9.3+ 1.10.x | 1.9.x ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported") 1.10.x ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported") 1.11.x ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported")[^(3)^ ^1.12.x ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported")^](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note3) | 1.10.x ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported") 1.11.x ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported") 1.12.x ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported") 1.13.x 1.14.x 1.15.x (K8s v1.26.x) | 1.12.x ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported") 1.13.x 1.14.x 1.15.x (K8s v1.26.x) | 1.13.x 1.14.x 1.15.x (K8s v1.26.x) 1.16.x (K8s v1.27.x) 1.27.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note4) 1.28.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note4) | 1.14.x 1.15.x (K8s v1.26.x) 1.16.x (K8s v1.27.x) 1.28.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note5) 1.29.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note5) | 1.15.x (K8s v1.26.x) 1.16.x (K8s v1.27.x) 1.28.x 1.29.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note6) | 1.16.x (K8s v1.27.x) 1.28.x 1.29.x 1.30.x |
| Google Distributed Cloud (software only) on bare metal | 1.7.x 1.8.2+ 1.9.3+ 1.10.x | 1.9.x ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported") 1.10.x ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported") 1.11.x ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported") ^1.12.x ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported")^ | 1.10.x ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported") 1.11.x ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported") 1.12.x ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported") 1.13.x 1.14.x 1.15.x | 1.12.x ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported") 1.13.x 1.14.x 1.15.x | 1.13.x 1.14.x (K8s v1.25.x) 1.15.x (K8s v1.26.x) 1.16.x (K8s v1.27.x) 1.27.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note4) 1.28.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note4) | 1.14.x 1.15.x (K8s v1.26.x) 1.16.x (K8s v1.27.x) 1.28.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note5) 1.29.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note5) | 1.15.x (K8s v1.26.x) 1.16.x (K8s v1.27.x) 1.28.x 1.29.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note6) | 1.16.x (K8s v1.27.x) 1.28.x 1.29.x 1.30.x |
| EKS | 1.19.x 1.20.x 1.21.x | 1.21.x 1.22.x ^1.23.x^ | 1.22.x [](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note5) 1.23.x 1.24.x 1.25.x | 1.23.x 1.24.x 1.25.x 1.26.x | 1.24.x 1.25.x 1.26.x 1.27.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note4) 1.28.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note4) | 1.25.x 1.26.x 1.27.x 1.28.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note5) 1.29.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note5) | 1.26.x 1.27.x 1.28.x 1.29.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note6) | 1.27.x 1.28.x 1.29.x 1.30.x |
| AKS | 1.19.x 1.20.x 1.21.x | 1.21.x 1.22.x ^1.23.x^ | 1.22.x [](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note5) 1.23.x 1.24.x 1.25.x | 1.23.x 1.24.x 1.25.x 1.26.x | 1.24.x 1.25.x 1.26.x 1.27.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note4) 1.28.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note4) | 1.25.x 1.26.x 1.27.x 1.28.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note5) 1.29.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note5) | 1.26.x 1.27.x 1.28.x 1.29.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note6) | 1.27.x 1.28.x 1.29.x 1.30.x |
| OpenShift[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note7) | 4.6 4.7 4.8 | 4.7 4.8 | 4.8 4.9 4.10 | 4.10 4.11 | 4.11 4.12 4.14[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note4) 4.15[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note4) | 4.12 4.13 4.14 4.15[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note5) 4.16[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note5) | 4.12 4.13 4.14 4.15 4.16[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note6) | 4.12 4.13 4.14 4.15 4.16 |
| Rancher Kubernetes Engine (RKE) | N/A | N/A | N/A | 1.3.8 | v1.26.2+rke2r1 1.27.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note4) 1.28.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note4) | v1.26.2+rke2r1 v1.27.x 1.28.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note5) 1.29.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note5) | v1.26.2+rke2r1 v1.27.x <br /> 1.28.x 1.29.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note6) | v1.26.2+rke2r1 v1.27.x <br /> 1.28.x 1.29.x 1.30.x |
| Cloud Service Mesh | 1.9.x ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported") 1.10.x ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported") 1.12.x ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported") 1.13.x ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported") | 1.10.x ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported") 1.11.x ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported") 1.12.x ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported") 1.13.x ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported") ^1.14.x ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "Skipped - never supported") 1.15.x^ | 1.11.x ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported") 1.12.x ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported") 1.13.x ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported") 1.14.x ![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "Skipped - never supported") 1.15.x | 1.17.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note2) | 1.17.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note2) | 1.17.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note2) 1.18.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note2) | 1.18.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note2) | 1.19.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note2) |
| JDK | JDK 11 | JDK 11 | JDK 11 | JDK 11 | JDK 11 | JDK 11 | JDK 11 | JDK 11 |
| cert-manager | 1.5.4 | 1.7.x | 1.7.x 1.8.x 1.9.x 1.10.x 1.11.x | 1.10.x 1.11.x | 1.10.x 1.11.x 1.12.x | 1.11.x 1.12.x 1.13.x | 1.11.x 1.12.x 1.13.x | 1.15.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note8) 1.16.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note8) 1.17.x[](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/upgrade.md.txt#note8) |
| Cassandra | 3.11 | 3.11 | 3.11 | 3.11 | 3.11 | 3.11 | 4.0 | 4.0 |
| Kubernetes |   |   |   | 1.23.x 1.24.x 1.25.x | 1.24.x 1.25.x 1.26.x | 1.25.x 1.26.x 1.27.x | 1.26.x 1.27.x 1.28.x 1.29.x | 1.27.x 1.28.x 1.29.x 1.30.x |
| kubectl |   |   |   |   | 1.24.x 1.25.x 1.26.x | 1.25.x 1.26.x 1.27.x | 1.26.x 1.27.x 1.28.x 1.29.x | 1.27.x 1.28.x 1.29.x 1.30.x |
| Helm |   |   |   |   | 3.10+ | 3.10+ | 3.14.2 through 3.x.x | 3.14.2 through 3.x.x |
| Secret Store CSI driver |   |   |   |   |   | 1.3.4+ | 1.4.1+ | 1.4.6+ |
| Vault |   |   |   |   |   | 1.13.x | 1.15.2 | 1.15.2 |
| **^(1)^ The official EOL dates for Apigee hybrid versions 1.13 and older 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**. **^(2)^ Cloud Service Mesh is automatically installed with Apigee hybrid 1.9 and newer**. **^(3)^ Vault is not certified on Google Distributed Cloud for VMware.** ****^(4)^ Support available with Apigee hybrid version 1.10.5 and newer**. **^(5)^ Support available with Apigee hybrid version 1.11.2 and newer**. **^(6)^ Support available with Apigee hybrid version 1.12.1 and newer**. **^(7)^ Apigee hybrid is tested and certified on OpenShift using the Kubernetes version bundled with each specific OCP version**. **^(8)^ Some versions of cert-manager have an issue where the webhook TLS server may fail to automatically renew its CA certificate.** To avoid this, Apigee recommends using: - **Hybrid v1.13![not supported](https://docs.cloud.google.com/static/apigee/docs/images/not-supported.svg "EOL - not supported"):** use cert-manager version [1.15.3](https://cert-manager.io/docs/releases/release-notes/release-notes-1.15/#v1155)+. - **Hybrid v1.14:** use cert-manager versions [1.15.3](https://cert-manager.io/docs/releases/release-notes/release-notes-1.15/#v1155)+ or [1.16.0](https://cert-manager.io/docs/releases/release-notes/release-notes-1.16/#v1163)+. - **Hybrid v1.15:** use cert-manager versions [1.16.0](https://cert-manager.io/docs/releases/release-notes/release-notes-1.16/#v1163)+ or [1.17.2](https://cert-manager.io/docs/releases/release-notes/release-notes-1.17/#v1172)+. - **Hybrid v1.16:** use cert-manager versions [1.16.0](https://cert-manager.io/docs/releases/release-notes/release-notes-1.16/#v1163)+, [1.17.2](https://cert-manager.io/docs/releases/release-notes/release-notes-1.17/#v1172)+, [1.18.0](https://cert-manager.io/docs/releases/release-notes/release-notes-1.18/#v1180)+ or [1.19.0](https://cert-manager.io/docs/releases/release-notes/release-notes-1.19/#v1190)+. See [Known Issue 465834046](https://docs.cloud.google.com/apigee/docs/release/known-issues.md.txt#465834046) for cert-manager releases 1.18 and 1.19. - **Hybrid v1.17:** use cert-manager versions [1.17.2](https://cert-manager.io/docs/releases/release-notes/release-notes-1.17/#v1172)+, [1.18.0](https://cert-manager.io/docs/releases/release-notes/release-notes-1.18/#v1180)+ or [1.19.0](https://cert-manager.io/docs/releases/release-notes/release-notes-1.19/#v1190)+. See [Known Issue 465834046](https://docs.cloud.google.com/apigee/docs/release/known-issues.md.txt#465834046) for cert-manager releases 1.18 and 1.19. **^(9)^ cert-manager release 1.18 introduces a change to the default private key rotation policy that may cause traffic interruptions. See [Known Issue 465834046](https://docs.cloud.google.com/apigee/docs/release/known-issues.md.txt#465834046) for a workaround.** **^(10)^ Support for OpenShift 4.19, 4.20, 4.21, \& 4.22 available with Apigee hybrid version 1.15.2 and newer.** **^(11)^ Support for OpenShift 4.19, 4.20, 4.21, \& 4.22 available with Apigee hybrid version 1.14.4 and newer.**** ||||||

> [!NOTE]
> **Note:** Hybrid installations are not currently supported on Autopilot clusters.

### Pull the Apigee Helm charts.

Apigee hybrid charts are hosted in [Google Artifact Registry](https://docs.cloud.google.com/artifact-registry):

`oci://us-docker.pkg.dev/apigee-release/apigee-hybrid-helm-charts`


Using the `pull` command, copy all of the Apigee hybrid Helm
charts to your local storage with the following command:

    export CHART_REPO=oci://us-docker.pkg.dev/apigee-release/apigee-hybrid-helm-charts
    export CHART_VERSION=1.17.3
    helm pull $CHART_REPO/apigee-operator --version $CHART_VERSION --untar
    helm pull $CHART_REPO/apigee-datastore --version $CHART_VERSION --untar
    helm pull $CHART_REPO/apigee-env --version $CHART_VERSION --untar
    helm pull $CHART_REPO/apigee-ingress-manager --version $CHART_VERSION --untar
    helm pull $CHART_REPO/apigee-org --version $CHART_VERSION --untar
    helm pull $CHART_REPO/apigee-redis --version $CHART_VERSION --untar
    helm pull $CHART_REPO/apigee-telemetry --version $CHART_VERSION --untar
    helm pull $CHART_REPO/apigee-virtualhost --version $CHART_VERSION --untar

### Edit `kustomization.yaml` for a custom apigee namespace

If your Apigee namespace is not `apigee`, edit the `apigee-operator/etc/crds/default/kustomization.yaml` file and replace the `namespace` value with your Apigee namespace.

```
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namespace: APIGEE_NAMESPACE
```


If you are using `apigee` as your namespace you do not need to edit the file.
- Install the updated Apigee CRDs:

  > [!NOTE]
  > **Note:** From this step onwards, all commands should be run under the chart repo root directory.

  > [!NOTE]
  > **Note:** This is the only supported method for installing Apigee CRDs. Do not use `kubectl apply` without `-k`, do not omit `--server-side`.

  > [!NOTE]
  > **Note:** This step requires elevated cluster permissions.

  1. Use the `kubectl` dry-run feature by running
     the following command:

     ```
     kubectl apply -k  apigee-operator/etc/crds/default/ --server-side --force-conflicts --validate=false --dry-run=server
     ```
  2. After validating with the dry-run command, run the following command:

     ```
     kubectl apply -k  apigee-operator/etc/crds/default/ \
       --server-side \
       --force-conflicts \
       --validate=false
     ```
  3. Validate the installation with the `kubectl get crds` command:

     ```
     kubectl get crds | grep apigee
     ```

     Your output should look something like the following:

     ```
     apigeedatastores.apigee.cloud.google.com                    2024-08-21T14:48:30Z
     apigeedeployments.apigee.cloud.google.com                   2024-08-21T14:48:30Z
     apigeeenvironments.apigee.cloud.google.com                  2024-08-21T14:48:31Z
     apigeeissues.apigee.cloud.google.com                        2024-08-21T14:48:31Z
     apigeeorganizations.apigee.cloud.google.com                 2024-08-21T14:48:32Z
     apigeeredis.apigee.cloud.google.com                         2024-08-21T14:48:33Z
     apigeerouteconfigs.apigee.cloud.google.com                  2024-08-21T14:48:33Z
     apigeeroutes.apigee.cloud.google.com                        2024-08-21T14:48:33Z
     apigeetelemetries.apigee.cloud.google.com                   2024-08-21T14:48:34Z
     apigeevalkeys.apigee.cloud.google.com                       2024-08-21T14:48:34Z
     cassandradatareplications.apigee.cloud.google.com           2024-08-21T14:48:35Z
     ```
- Check the labels on the cluster nodes.
  By default, Apigee schedules data pods on nodes with the label
  `cloud.google.com/gke-nodepool=apigee-data` and runtime pods
  are scheduled on nodes with the label
  `cloud.google.com/gke-nodepool=apigee-runtime`. You can
  customize your node pool labels in the `overrides.yaml` file.

  For more information, see
  [Configuring dedicated node pools](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/configure-dedicated-nodes.md.txt).

### Upgrade cert-manager

> [!NOTE]
> **Note:** This procedure is optional if you are using cert-manager 1.16.3 or higher.

- Apigee hybrid v1.17 supports cert-manager releases 1.16 through 1.19. There is a change in cert-manager 1.18 that can cause an issue with your traffic. In cert-manager release 1.18, the default value of `Certificate.Spec.PrivateKey.rotationPolicy` was changed from `Never` to `Always`. For upgraded Apigee hybrid installations, this can cause an issue with your traffic. When upgrading to hybrid v1.17 from an earlier version, you must either edit your `apigee-ca` certificate to compensate for this change or keep your version of cert-manager at release 1.17.x or lower.

> [!NOTE]
> **Note:** This change affects upgrades from earlier versions of Apigee hybrid only and does not affect fresh installations of Apigee hybrid v1.17.

- Before upgrading cert-manager to 1.18 or 1.19, use the following steps procedure to edit your `apigee-ca` certificate to set the value of `Certificate.Spec.PrivateKey.rotationPolicy` to `Never`.

> [!WARNING]
> **Warning:** Performe these steps *before* upgrading cert-manager. Otherwise, you may trigger a certificate rotation.

> [!NOTE]
> **Note:** For multi-region deployments, the following change to the `apigee-ca` certificate only needs to be made in the primary region. If there is no `apigee-ca` certificate, skip this procedure for clusters in secondary regions.

  1. Check the contents of your `apigee-ca` certificate to see if `rotationPolicy` is set:

     > [!TIP]
     > **Tip:** If you are using a custom cert-manager namesspace, replace `cert-manager` with the correct namespace in the following commands.

     ```
     kubectl get certificate apigee-ca -n cert-manager -o yaml
     ```

     Look for the values under `spec.privateKey` in the output:

     ```
     ...
     spec:
       commonName: apigee-hybrid
       duration: 87600h
       isCA: true
       issuerRef:
         group: cert-manager.io
         kind: ClusterIssuer
         name: apigee-root-certificate-issuer
       privateKey:
         algorithm: ECDSA
         # Note: rotationPolicy would appear here if it is set.
         size: 256
       secretName: apigee-ca
     ...
     ```
  2. If `rotationPolicy` is not set or if it is set to `Always`, edit the `apigee-ca` certificate to set the value of `rotationPolicy` to `Never`:
     1. Perform a dry run first:

        ```
        kubectl patch Certificate \
          --dry-run=server \
          -n cert-manager \
          --type=json \
          -p='[{"op": "replace", "path": "/spec/privateKey/rotationPolicy", "value": "Never"}]' \
          -o=yaml \
          apigee-ca
        ```
     2. Patch the certificate:

        ```
        kubectl patch Certificate \
          -n cert-manager \
          --type=json \
          -p='[{"op": "replace", "path": "/spec/privateKey/rotationPolicy", "value": "Never"}]' \
          -o=yaml \
          apigee-ca
        ```
  3. Verify that the value of `rotationPolicy` is now set to `Never`:

     ```
     kubectl get certificate apigee-ca -n cert-manager -o yaml
     ```

     The output should look similar to the following:

     ```
     ...
     spec:
       commonName: apigee-hybrid
       duration: 87600h
       isCA: true
       issuerRef:
         group: cert-manager.io
         kind: ClusterIssuer
         name: apigee-root-certificate-issuer
       privateKey:
         algorithm: ECDSA
         rotationPolicy: Never
         size: 256
       secretName: apigee-ca
     ...
     ```
  4. Upgrade cert-manager. The following command will download and install cert-manager v1.19.2:

     ```
     kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.19.2/cert-manager.yaml
     ```

     See [Supported platforms and versions: cert-manager](https://docs.cloud.google.com/apigee/docs/hybrid/supported-platforms.md.txt#cert-manager) for a list of supported versions.
- See:
  - [Known issue 465834046](https://docs.cloud.google.com/apigee/docs/release/known-issues.md.txt#465834046)
  - [cert-manager Release 1.18: The default value of `Certificate.Spec.PrivateKey.rotationPolicy` is now `Always`](https://cert-manager.io/docs/releases/release-notes/release-notes-1.18/#the-default-value-of-certificatespecprivatekeyrotationPolicy-is-now-always)

## Install the hybrid 1.17.3 runtime

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

> [!NOTE]
> This upgrade procedure assumes you are using the same namespace and service accounts for the upgraded installation. If you are making any configuration changes, be sure to reflect those changes in your overrides file before installing the Helm charts.

> [!NOTE]
> **Note:** Before executing any of the Helm upgrade/install commands, use the Helm dry-run feature by adding `--dry-run` at the end of the command. See `helm -h` to list supported commands, options, and usage.

  1. If you have not, navigate into your `APIGEE_HELM_CHARTS_HOME` directory. Run the following commands from that directory.
  2. Upgrade the Apigee Operator/Controller:

     > [!NOTE]
     > **Note:** This step requires elevated cluster permissions. Run `helm -h` or `helm upgrade -h` for details.

     Dry run:

     ```
     helm upgrade operator apigee-operator/ \
       --install \
       --namespace APIGEE_NAMESPACE \
       -f OVERRIDES_FILE \
       --dry-run=server
     ```

     Upgrade the chart:

     ```
     helm upgrade operator apigee-operator/ \
       --install \
       --namespace APIGEE_NAMESPACE \
       -f OVERRIDES_FILE
     ```

     Verify Apigee Operator installation:

     ```
     helm ls -n APIGEE_NAMESPACE
     ```

     ```
     NAME       NAMESPACE       REVISION   UPDATED                                STATUS     CHART                   APP VERSION
     operator   apigee   3          2024-08-21 00:42:44.492009 -0800 PST   deployed   apigee-operator-1.17.3   1.17.3
     ```

     Verify it is up and running by checking its availability:

     ```
     kubectl -n APIGEE_NAMESPACE get deploy apigee-controller-manager
     ```

     ```
     NAME                        READY   UP-TO-DATE   AVAILABLE   AGE
     apigee-controller-manager   1/1     1            1           7d20h
     ```
  3. Upgrade the Apigee datastore: Dry run:

     ```
     helm upgrade datastore apigee-datastore/ \
       --install \
       --namespace APIGEE_NAMESPACE \
       -f OVERRIDES_FILE \
       --dry-run=server
     ```

     Upgrade the chart:

     ```
     helm upgrade datastore apigee-datastore/ \
       --install \
       --namespace APIGEE_NAMESPACE \
       -f OVERRIDES_FILE
     ```

     Verify `apigeedatastore` is up and running by checking its state:

     ```
     kubectl -n APIGEE_NAMESPACE get apigeedatastore default
     ```

     ```
     NAME      STATE       AGE
     default   running    2d
     ```
  4. Upgrade Apigee telemetry: Dry run:

     ```
     helm upgrade telemetry apigee-telemetry/ \
       --install \
       --namespace APIGEE_NAMESPACE \
       -f OVERRIDES_FILE \
       --dry-run=server
     ```

     Upgrade the chart:

     ```
     helm upgrade telemetry apigee-telemetry/ \
       --install \
       --namespace APIGEE_NAMESPACE \
       -f OVERRIDES_FILE
     ```

     Verify it is up and running by checking its state:

     ```
     kubectl -n APIGEE_NAMESPACE get apigeetelemetry apigee-telemetry
     ```

     ```
     NAME               STATE     AGE
     apigee-telemetry   running   2d
     ```
  5. Upgrade Apigee Redis: Dry run:

     ```
     helm upgrade redis apigee-redis/ \
       --install \
       --namespace APIGEE_NAMESPACE \
       -f OVERRIDES_FILE \
       --dry-run=server
     ```

     Upgrade the chart:

     ```
     helm upgrade redis apigee-redis/ \
       --install \
       --namespace APIGEE_NAMESPACE \
       -f OVERRIDES_FILE
     ```

     Verify it is up and running by checking its state:

     ```
     kubectl -n APIGEE_NAMESPACE get apigeeredis default
     ```

     ```
     NAME      STATE     AGE
     default   running   2d
     ```
  6. Upgrade Apigee ingress manager: Dry run:

     ```
     helm upgrade ingress-manager apigee-ingress-manager/ \
       --install \
       --namespace APIGEE_NAMESPACE \
       -f OVERRIDES_FILE \
       --dry-run=server
     ```

     Upgrade the chart:

     ```
     helm upgrade ingress-manager apigee-ingress-manager/ \
       --install \
       --namespace APIGEE_NAMESPACE \
       -f OVERRIDES_FILE
     ```

     Verify it is up and running by checking its availability:

     ```
     kubectl -n APIGEE_NAMESPACE get deployment apigee-ingressgateway-manager
     ```

     ```
     NAME                            READY   UP-TO-DATE   AVAILABLE   AGE
     apigee-ingressgateway-manager   2/2     2            2           2d
     ```
  7. Upgrade the Apigee organization: Dry run:

     ```
     helm upgrade ORG_NAME apigee-org/ \
       --install \
       --namespace APIGEE_NAMESPACE \
       -f OVERRIDES_FILE \
       --dry-run=server
     ```

     Upgrade the chart:

     ```
     helm upgrade ORG_NAME apigee-org/ \
       --install \
       --namespace APIGEE_NAMESPACE \
       -f OVERRIDES_FILE
     ```

     Verify it is up and running by checking the state of the respective org:

     ```
     kubectl -n APIGEE_NAMESPACE get apigeeorg
     ```

     ```
     NAME                      STATE     AGE
     apigee-my-org-my-env      running   2d
     ```

     > [!NOTE]
     > **Note** : If the upgrade command fails with the error `Forbidden: state: releasing`, the existing components are still in releasing status. You can wait for the current update to complete and then retry. Check release status with the following command:
     >
     > ```
     > kubectl get org -n APIGEE_NAMESPACE
     > ```

  8. Upgrade the environment. You must install one environment at a time. Specify the environment with `--set env=`<var translate="no">ENV_NAME</var>.

     Dry run:

     ```
     helm upgrade ENV_RELEASE_NAME apigee-env/ \
       --install \
       --namespace APIGEE_NAMESPACE \
       --set env=ENV_NAME \
       -f OVERRIDES_FILE \
       --dry-run=server
     ```
     - <var translate="no">ENV_RELEASE_NAME</var> is a name used to keep track of installation and upgrades of the `apigee-env` chart. This name must be unique from the other Helm release names in your installation. Usually this is the same as `ENV_NAME`. However, if your environment has the same name as your environment group, you must use different release names for the environment and environment group, for example `dev-env-release` and `dev-envgroup-release`. For more information on releases in Helm, see [Three big concepts](https://helm.sh/docs/intro/using_helm/#three-big-concepts) in the Helm documentation.
     - <var translate="no">ENV_NAME</var> is the name of the environment you are upgrading.
     - <var translate="no">OVERRIDES_FILE</var> is your new overrides file for v.1.17.3

     Upgrade the chart:

     ```
     helm upgrade ENV_RELEASE_NAME apigee-env/ \
       --install \
       --namespace APIGEE_NAMESPACE \
       --set env=ENV_NAME \
       -f OVERRIDES_FILE
     ```

     Verify it is up and running by checking the state of the respective env:

     ```
     kubectl -n APIGEE_NAMESPACE get apigeeenv
     ```

     ```
     NAME                          STATE       AGE   GATEWAYTYPE
     apigee-my-org-my-env          running     2d
     ```

  > [!NOTE]
  > **Note** : If the upgrade command fails with the error `Forbidden: state: releasing`, the existing components are still in releasing status. You can wait for the current update to complete and then retry. Check release status with the following command:
  >
  > ```
  > kubectl get env -n APIGEE_NAMESPACE
  > ```

  9. Upgrade the environment groups (`virtualhosts`).
     1. You must upgrade one environment group (virtualhost) at a time. Specify the environment group with `--set envgroup=`<var translate="no">ENV_GROUP_NAME</var>. Repeat the following commands for each environment group mentioned in the overrides.yaml file:

        Dry run:

        ```
        helm upgrade ENV_GROUP_RELEASE_NAME apigee-virtualhost/ \
          --install \
          --namespace APIGEE_NAMESPACE \
          --set envgroup=ENV_GROUP_NAME \
          -f OVERRIDES_FILE \
          --dry-run=server
        ```

        <var translate="no">ENV_GROUP_RELEASE_NAME</var> is the name with which you previously installed the
        `apigee-virtualhost` chart. It is
        usually <var translate="no">ENV_GROUP_NAME</var>.

        Upgrade the chart:

        ```
        helm upgrade ENV_GROUP_RELEASE_NAME apigee-virtualhost/ \
          --install \
          --namespace APIGEE_NAMESPACE \
          --set envgroup=ENV_GROUP_NAME \
          -f OVERRIDES_FILE
        ```

        > [!NOTE]
        > **Note:** <var translate="no">ENV_GROUP_RELEASE_NAME</var> must be unique within the `apigee` namespace.
        >
        >
        > For example, if you have an *environment* named `prod` and
        > an *environment group* named `prod`, set the value of <var translate="no">ENV_GROUP_RELEASE_NAME</var> to something unique, like `prod-envgroup`.

     2. Check the state of the ApigeeRoute (AR). Installing the `virtualhosts`
        creates ApigeeRouteConfig (ARC) which internally creates
        ApigeeRoute (AR) once the Apigee watcher pulls environment group-related
        details from the control plane. Therefore, check that the corresponding
        AR's state is running:

        ```
        kubectl -n APIGEE_NAMESPACE get arc
        ```

        ```
        NAME                                STATE   AGE
        apigee-org1-dev-egroup                       2d
        ```

        ```
        kubectl -n APIGEE_NAMESPACE get ar
        ```

        ```
        NAME                                        STATE     AGE
        apigee-org1-dev-egroup-123abc               running   2d
        ```

> [!TIP]
> **Congratulations!** You have upgraded to Apigee hybrid version 1.17.3. To test your upgrade, call a proxy against the new installation. For an example, see [Part 3, Step 2: Deploy an API proxy](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/install-deploy-proxy.md.txt) in the Apigee hybrid 1.17 installation guide.

## Rolling back to a previous version

- To roll back to the previous version, use the older chart version to roll back the upgrade process in the reverse order. Start with `apigee-virtualhost` and work your way back to `apigee-operator`, and then revert the CRDs.

> [!TIP]
> **Tip:** If you know the last release version, you can use the `helm rollback` command rather than the `helm upgrade` command described below.

  1. Revert the charts. The following commands assume you are using the charts from the previous version (v1.16.x).
     1. Run the following command for each environment group:

        ```
        helm upgrade ENV_GROUP_RELEASE_NAME apigee-virtualhost/ \
          --install \
          --namespace APIGEE_NAMESPACE \
          --atomic \
          --set envgroup=ENV_GROUP_NAME \
          -f 1.16_OVERRIDES_FILE
        ```
     2. Run the following command for each environment:

        ```
        helm upgrade ENV_RELEASE_NAME apigee-env/ \
          --install \
          --namespace APIGEE_NAMESPACE \
          --atomic \
          --set env=ENV_NAME \
          -f 1.16_OVERRIDES_FILE
        ```
     3. `apigee-org`:

        ```
        helm upgrade ORG_NAME apigee-org/ \
          --install \
          --namespace APIGEE_NAMESPACE \
          --atomic \
          -f 1.16_OVERRIDES_FILE
        ```
     4. `apigee-ingress-manager`:

        ```
        helm upgrade ingress-manager apigee-ingress-manager/ \
          --install \
          --namespace APIGEE_NAMESPACE \
          --atomic \
          -f 1.16_OVERRIDES_FILE
        ```
     5. `apigee-redis`:

        ```
        helm upgrade redis apigee-redis/ \
          --install \
          --namespace APIGEE_NAMESPACE \
          --atomic \
          -f 1.16_OVERRIDES_FILE
        ```
     6. `apigee-telemetry`:

        ```
        helm upgrade telemetry apigee-telemetry/ \
          --install \
          --namespace APIGEE_NAMESPACE \
          --atomic \
          -f 1.16_OVERRIDES_FILE
        ```
     7. `apigee-datastore`:

        ```
        helm upgrade datastore apigee-datastore/ \
          --install \
          --namespace APIGEE_NAMESPACE \
          --atomic \
          -f 1.16_OVERRIDES_FILE
        ```
     8. `apigee-operator`:

        ```
        helm upgrade operator apigee-operator/ \
          --install \
          --namespace APIGEE_NAMESPACE \
          --atomic \
          -f 1.16_OVERRIDES_FILE
        ```
  2. If you're rolling back to version 1.16, remove the conversion webhook from the `apigeedatastores`, `apigeeredis`, and `apigeevalkeys` CRDs. The version 1.17 CRDs add a conversion webhook to these CRDs, and the version 1.16 CRDs don't have one. If you skip this step, the next step fails with the error `spec.conversion.strategy: Required value`. To remove the conversion webhook, run the following commands:

         kubectl patch crd apigeedatastores.apigee.cloud.google.com --type=merge \
           -p '{"spec":{"conversion":{"strategy":"None","webhook":null}}}'
         kubectl patch crd apigeeredis.apigee.cloud.google.com --type=merge \
           -p '{"spec":{"conversion":{"strategy":"None","webhook":null}}}'
         kubectl patch crd apigeevalkeys.apigee.cloud.google.com --type=merge \
           -p '{"spec":{"conversion":{"strategy":"None","webhook":null}}}'

  3. Revert the CRDs by reinstalling the older CRDs.

     ```
     kubectl apply -k apigee-operator/etc/crds/default/ \
       --server-side \
       --force-conflicts \
       --validate=false
     ```