Apigee Hybrid HTTPS Proxy Fix: Choosing the 1.16 or 1.17 Upgrade Path

Confirm the failure boundary: the management-plane tether

Google Cloud describes bug 578314600 as a failure in clusters that need an HTTP forward proxy for egress: apigee-connect-agent ignored HTTPS_PROXY and could not establish its tether to the management plane. Both 1.17.3 and 1.16.13 include the fix; the agent now uses HTTP/2 keepalive on the control-plane connection and honors HTTPS_PROXY, including proxy credentials.

This fix applies to a specific component, variable and connection path. The release notes do not say it resolves every proxy, DNS, certificate or egress problem. First check whether a failure matches this description, then use the documentation for the relevant component to investigate other paths.

Choose the patch target for your current minor version

For a current 1.17.x installation, including 1.17.2, the patch target is 1.17.3, released on October 29, 2026. Its release notes specifically warn against using 1.17.2 because of a potential regression. For a current 1.16.x installation, including 1.16.12, the patch target is 1.16.13, released on October 30, 2026. The 1.16.13 announcement also warns against using 1.16.12 because of a potential regression.

Moving from 1.16.x to 1.17.3 is a minor-version upgrade and must follow the full 1.17 preparation procedure; moving within 1.17.x to 1.17.3 is a patch upgrade on the same branch. Installations older than 1.16 must first move to 1.16; similarly, 1.15.x to 1.16.13 is a minor-version upgrade, while 1.16.x to 1.16.13 is a same-branch patch upgrade, and versions older than 1.15 must first move to 1.15.

Both targets are patch releases. Their patch images are integrated into the corresponding Helm charts and normally update when you upgrade through Helm, so manual image changes are typically unnecessary.

Check Helm, kubectl and cert-manager first

Both guides list Helm 3.14.2 or later in the general prerequisites, but the same page’s support matrix lists 3.17.0 through 3.x.x for both Hybrid 1.16 and 1.17. Check these targets against the version-specific matrix; do not rely on the lower general minimum or infer Helm 4 compatibility. kubectl must match the Kubernetes platform, and cert-manager must be supported by the selected Hybrid version.

If the upgrade also includes moving cert-manager to 1.18 or 1.19, check the certificate-rotation warning first: cert-manager 1.18 changed the default for Certificate.Spec.PrivateKey.rotationPolicy from Never to Always, which can affect traffic. Follow the selected upgrade guide's preparation for apigee-ca before upgrading cert-manager, or retain 1.17.x or an earlier version allowed by the guide.

Back up charts, Cassandra and current configuration

Before starting, back up the current version's Helm chart directory and Cassandra using the official backup and recovery procedure. Confirm that TLS certificate and key files are in the apigee-virtualhost directory specified by the guide. The upgrade assumes the same Kubernetes namespace and service accounts; do not create new Apigee environments during the upgrade, and reflect configuration changes in the matching overrides file before installing charts.

While clusters run different Hybrid versions, the guides warn that Cassandra backup and restore do not work across the mixed versions: a 1.15 backup cannot restore a 1.16 instance, and a 1.16 backup cannot restore a 1.17 instance. Plan the cluster sequence for the chosen branch; do not treat cross-version restore as a rollback method.

Include rolling restarts in the release window

An upgrade may require downtime, and upgrading the Apigee controller triggers a rolling restart of all Apigee deployments. For production, the guides recommend at least two clusters: divert production traffic to one cluster, take the cluster being upgraded offline, then repeat for each cluster. This reduces risk but does not guarantee uninterrupted service; upgrade the remaining clusters as soon as practical after starting.

When moving from 1.15.x to 1.16.13, the operator upgrade also restarts the runtime, synchronizer, MART, Envoy adapter and migration pods once in every environment. The guide says to ensure surge-pod capacity across all environments or choose a low-traffic window; this additional impact applies to the 1.15.x-to-1.16.13 migration.

Follow the version-specific procedure and rollback path

Use the official upgrade steps for the selected version and run the dry-run prescribed for each Helm or kubectl operation before applying the change. Follow that version's component order and status checks; do not combine command sequences from the 1.16 and 1.17 guides.

If rollback is needed, use the previous-version charts, matching overrides and reverse-order rollback procedure specified in the target guide. The recovery boundaries for CRDs, charts and Cassandra are version-specific. This article helps choose a version path and identify risks; it does not replace preproduction validation or a rollback drill for a particular cluster.