build-ho-image

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

Build HyperShift-Operator Image

This skill enables building and pushing custom hypershift-operator (HO) 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 hypershift-operator/
• You need to test HO changes against a live cluster
• The user asks to build/push a HO image
• You need to iterate on HO 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
HO_IMAGE_REPO	Container registry for HO images
RUNTIME	Container runtime (podman/docker)

Building the HO 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 HO image uses the main Dockerfile:

$RUNTIME build -f Dockerfile --platform linux/amd64 -t $HO_IMAGE_REPO:$TAG .

Note: The build runs make hypershift, make hypershift-operator, make karpenter-operator, and make product-cli inside the container.

Step 3: Push the Image

$RUNTIME push $HO_IMAGE_REPO:$TAG

Quick One-Liner

Build and push in one command:

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

Iteration Workflow

When iterating on HO fixes:

1. Make code changes in hypershift-operator/
2. Build and push image with incremented tag (e.g., fix-1, fix-2, fix-3)
3. Reinstall HyperShift with new image
4. Run e2e test or manual validation
5. Analyze results
6. Repeat until test passes

What Gets Built

The main Dockerfile builds:

• hypershift CLI binary
• hypershift-no-cgo binary
• hypershift-operator binary
• karpenter-operator binary
• hcp (product CLI) binary

All are included in the final image.

Troubleshooting

Build Fails

• Check that vendored dependencies are up to date: go mod vendor
• Ensure code compiles locally: make hypershift-operator
• Check for API generation issues: make api

Push Fails

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

Operator Not Running After Install

• Check operator logs: kubectl logs -n hypershift deployment/operator
• Verify image pull succeeded: kubectl describe pod -n hypershift -l app=operator
• Ensure cluster can pull from registry

Changes Not Reflected

• Make sure you're using the correct image tag
• Check if old pods are still running: kubectl get pods -n hypershift
• Force rollout: kubectl rollout restart deployment/operator -n hypershift