CAPI Provider Image Overrides

Overview

HyperShift uses Cluster API (CAPI) providers to manage infrastructure for hosted clusters. The CAPI provider images used in the hosted control plane are resolved through a layered override mechanism. This document describes how CAPI provider images are selected, which platforms have overrides, and a backward compatibility pinning mechanism active on specific release branches.

Image Resolution Priority

For each platform, the CAPI provider image is resolved in the following order (lowest to highest priority):

1. Payload image -- from the hosted cluster's OCP release payload (via platform.go GetPlatform())
2. Environment variable override -- from the HyperShift operator's own image references (set via support/images/envvars.go), meaning the image version is determined by the HyperShift operator, not the hosted cluster's payload
3. Annotation override -- explicit per-HostedCluster annotation (always wins)

When multiple sources are present, the highest-priority source takes effect. If no override is set, the image falls back to the next lower priority level.

Per-Platform Behavior

The table below includes the core CAPI manager (cluster-capi-controllers) and all per-platform CAPI providers. The core manager is separate from the platform-specific providers -- it runs the shared CAPI controller logic, while each platform provider handles infrastructure-specific operations.

How Environment Variable Overrides Work

The environment variables listed above (e.g. IMAGE_AZURE_CAPI_PROVIDER) are set on the HyperShift operator Deployment by the installation tooling. They are populated from the HyperShift operator's own image references file (support/images/envvars.go), which maps OCP release payload image names to environment variables.

In all standard installation methods -- including MCE (Multicluster Engine) and the hypershift install CLI -- these env vars are set automatically. When an env var is present, it takes precedence over the payload image. The practical effect is that the CAPI provider version is determined by the HyperShift operator version, not the hosted cluster's OCP payload version.

Backward Compatibility: CAPI v1beta2 Image Pinning

Background

Starting with OCP 4.21, the upstream CAPI v1.11 bump introduced the v1beta2 API version. Since HyperShift did not support CAPI v1beta2 until 5.0, a backward compatibility mechanism pins specific CAPI images to their 4.20.10 equivalents (which ship CAPI v1.10 / v1beta1 only) for releases 4.21 and 4.22.

Separately, on main and release-5.0+ (where HyperShift compiles against CAPI v1.11+), hosted clusters running OCP below 4.19 ship a CAPI controller that writes status via v1beta1. The v1beta1→v1beta2 conversion webhook drops the status.phase field, leaving it permanently empty. To fix this, the core CAPI manager image is pinned to a known-good OCP 4.22 build that writes status through v1beta2 natively.

Implementation

The pinning is implemented in support/backwardcompat/backwardcompat.go via the GetBackwardCompatibleCAPIImage() function. The behaviour depends on the branch and the hosted cluster's payload version:

• release-4.21 / release-4.22 -- for payload version >= 4.21.0, the function extracts the CAPI images from a pinned 4.20.10 release instead of the hosted cluster's own payload.
• main / release-5.0+ -- for payload version < 4.19.0, the function returns a pinned OCP 4.22 cluster-capi-controllers image. For versions >= 4.19.0 it returns an empty string and the standard image resolution priority applies.

In both cases an explicit hypershift.openshift.io/capi-manager-image annotation on the HostedCluster takes priority over the pinned image.

Pinned images:

# release-4.21 / release-4.22 -- 4.20.10-multi release payload
quay.io/openshift-release-dev/ocp-release@sha256:7f183e9b5610a2c9f9aabfd5906b418adfbe659f441b019933426a19bf6a5962

# main / release-5.0+ -- cluster-capi-controllers component image from OCP 4.22
quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:c5c3e36db897fae332284e1a681044cd6997a70e8cb9059f810385352e7575ac

The OCP 4.22 component digest is stored directly in the function to avoid needing a pull-secret lookup or release payload extraction at reconciliation time.

Affected Components

On release-4.21 / release-4.22, the pinning applies to these three components:

• cluster-capi-controllers (core CAPI manager) -- overridden in hostedcluster_controller.go
• aws-cluster-api-controllers (CAPA) -- overridden in platform.go
• azure-cluster-api-controllers (CAPZ) -- overridden in platform.go

On main / release-5.0+, only the core CAPI manager (cluster-capi-controllers) is pinned. Per-platform CAPI providers are not affected.

The following platforms are not affected by pinning on any branch: PowerVS, OpenStack, GCP, KubeVirt, Agent.

Branch Status

Introducing PRs

• OCPBUGS-74247: CAPI image overrides aware of registry config -- initial implementation (merged to main)
• OCPBUGS-86295: CAPI image overrides aware of registry config -- backport to release-4.21
• OCPBUGS-123171: CAPI manager pinning below 4.19 to fix phase conversion -- OCP 4.22 CAPI manager pinning for payloads < 4.19

Known Issues

In disconnected environments, pinned images are not part of the hosted cluster payload's image-references, so oc-mirror does not discover them automatically:

• On release-4.21/4.22: users must manually mirror the 4.20.10 release. Tracked under OCPBUGS-74263 and OCPBUGS-86056.
• On main/5.0+: users must manually mirror the OCP 4.22 cluster-capi-controllers image listed above. Tracked under OCPBUGS-123171.

Related Files

• support/backwardcompat/backwardcompat.go -- backward compatibility image pinning
• hypershift-operator/controllers/hostedcluster/internal/platform/platform.go -- GetPlatform() payload image lookup
• hypershift-operator/controllers/hostedcluster/internal/platform/{aws,azure,gcp,kubevirt,agent,openstack,powervs}/ -- per-platform CAPIProviderDeploymentSpec()
• support/images/envvars.go -- env var to payload image name mapping
• hypershift-operator/controllers/hostedcluster/hostedcluster_controller.go -- CAPI manager image override