build-cpo-image

name	Build CPO Image
description	Build and push control-plane-operator container image. Auto-applies when testing CPO changes that require deploying to a live cluster.

Build Control-Plane-Operator Image

This skill enables building and pushing custom control-plane-operator (CPO) images for testing changes in a live HyperShift environment.

When to Use This Skill

This skill automatically applies when:

• You've made changes to code in control-plane-operator/
• You need to test CPO changes against a live cluster
• The user asks to build/push a CPO image
• You need to iterate on CPO fixes with e2e tests

Prerequisites

Source the environment file before using this skill:

source dev/claude-env.sh

Image Registry Configuration

Environment variables from dev/claude-env.sh:

Variable	Description
CPO_IMAGE_REPO	Container registry for CPO images
RUNTIME	Container runtime (podman/docker)

Building the CPO Image

Step 1: Generate a Unique Tag

Use a tag that identifies the change (branch name, feature, or timestamp):

# Option 1: Use branch name
TAG=$(git rev-parse --abbrev-ref HEAD | tr '/' '-')

# Option 2: Use short commit hash
TAG=$(git rev-parse --short HEAD)

# Option 3: Use descriptive name + number for iterations
TAG="feature-name-1"

Step 2: Build the Image

The CPO image uses Dockerfile.control-plane:

$RUNTIME build -f Dockerfile.control-plane --platform linux/amd64 -t $CPO_IMAGE_REPO:$TAG .

Note: The build runs make control-plane-operator and make control-plane-pki-operator inside the container, so you don't need to pre-build locally.

Step 3: Push the Image

$RUNTIME push $CPO_IMAGE_REPO:$TAG

Quick One-Liner

Build and push in one command:

TAG="my-fix-1" && $RUNTIME build -f Dockerfile.control-plane --platform linux/amd64 -t $CPO_IMAGE_REPO:$TAG . && $RUNTIME push $CPO_IMAGE_REPO:$TAG

Iteration Workflow

When iterating on CPO fixes:

1. Make code changes in control-plane-operator/
2. Build and push image with incremented tag (e.g., fix-1, fix-2, fix-3)
3. Run e2e test with new image
4. Analyze results
5. Repeat until test passes

What Gets Built

The Dockerfile.control-plane builds:

• control-plane-operator binary
• control-plane-pki-operator binary

Both are included in the final image.

Image Labels

The CPO image includes important capability labels that HyperShift uses:

• io.openshift.hypershift.control-plane-operator-subcommands=true
• io.openshift.hypershift.control-plane-operator.v2-isdefault=true
• Various other feature capability labels

Troubleshooting

Build Fails

• Check that vendored dependencies are up to date: go mod vendor
• Ensure code compiles locally: make control-plane-operator

Push Fails

• Verify registry login: $RUNTIME login quay.io
• Check repository permissions

Image Not Used by Cluster

• Verify the image tag is correct in e2e flags
• Check that the image was pushed successfully
• Ensure the cluster can pull from the registry (public or authenticated)