create-hc-aws - SKILL.md Agent Skill

name: Create HC AWS description: "Create a HyperShift HostedCluster on AWS for development and testing, with optional custom CPO/HO images."

Create HostedCluster

This skill creates a HyperShift HostedCluster on AWS for development and testing purposes. The clusters created are intended for local development workflows, not for production use.

When to Use This Skill

Use this skill when:

You need to create a dev/test HostedCluster for manual verification
You want to test HyperShift features against a live cluster
You need a HostedCluster with custom CPO or HO images
You are iterating on code changes and need a cluster to validate them

Prerequisites

Source the environment file before using this skill:

source dev/claude-env.sh

Additional requirements:

AWS credentials loaded (source $AWS_CREDS_SOURCE)
KUBECONFIG pointing to management cluster ($MGMT_KUBECONFIG)
hypershift binary built (./bin/hypershift or run make hypershift)
Pull secret available ($PULL_SECRET)

Environment Configuration

Environment variables from dev/claude-env.sh:

Variable	Description
`AWS_CREDENTIALS`	Path to AWS credentials file
`AWS_CREDS_SOURCE`	Script to source AWS env vars
`BASE_DOMAIN`	Base DNS domain for clusters
`PULL_SECRET`	Path to pull secret file
`AWS_REGION`	AWS region
`MGMT_KUBECONFIG`	Path to management cluster kubeconfig
`CPO_IMAGE_REPO`	Custom CPO image repository

Basic Command

source $AWS_CREDS_SOURCE && \
KUBECONFIG=$MGMT_KUBECONFIG \
./bin/hypershift create cluster aws \
  --name <CLUSTER_NAME> \
  --namespace clusters \
  --base-domain $BASE_DOMAIN \
  --aws-creds $AWS_CREDENTIALS \
  --pull-secret $PULL_SECRET \
  --region $AWS_REGION \
  --release-image quay.io/openshift-release-dev/ocp-release:4.21.0-multi \
  --node-pool-replicas 2

Common Parameters

Parameter	Description	Default
`--name`	Name of the HostedCluster	Required
`--namespace`	Namespace for the HostedCluster	`clusters`
`--base-domain`	Base DNS domain	`$BASE_DOMAIN`
`--aws-creds`	Path to AWS credentials file	`$AWS_CREDENTIALS`
`--pull-secret`	Path to pull secret file	`$PULL_SECRET`
`--region`	AWS region	`$AWS_REGION`
`--release-image`	OCP release image	Latest 4.21.0 multi-arch
`--node-pool-replicas`	Initial node count	`0` (add nodes later)
`--control-plane-operator-image`	Custom CPO image	Optional

With Custom CPO Image

When testing CPO changes, add the custom image:

source $AWS_CREDS_SOURCE && \
KUBECONFIG=$MGMT_KUBECONFIG \
./bin/hypershift create cluster aws \
  --name my-test-cluster \
  --namespace clusters \
  --base-domain $BASE_DOMAIN \
  --aws-creds $AWS_CREDENTIALS \
  --pull-secret $PULL_SECRET \
  --region $AWS_REGION \
  --release-image quay.io/openshift-release-dev/ocp-release:4.21.0-multi \
  --node-pool-replicas 2 \
  --control-plane-operator-image $CPO_IMAGE_REPO:YOUR_TAG

What Gets Created

The command creates:

AWS VPC with public and private subnets
NAT gateway and internet gateway
Route tables
Private hosted zones (Route53)
OIDC provider for STS
IAM roles for control plane components
Worker instance profile
HostedCluster and NodePool resources

Post-Creation Steps

Check HostedCluster status:

KUBECONFIG=$MGMT_KUBECONFIG kubectl get hostedcluster -n clusters

Wait for control plane to be available:

KUBECONFIG=$MGMT_KUBECONFIG kubectl wait --for=condition=Available \
  hostedcluster/<CLUSTER_NAME> -n clusters --timeout=10m

Scale NodePool to add nodes:

KUBECONFIG=$MGMT_KUBECONFIG kubectl scale nodepool <NODEPOOL_NAME> \
  -n clusters --replicas=1

Get guest cluster kubeconfig:

KUBECONFIG=$MGMT_KUBECONFIG kubectl get secret <CLUSTER_NAME>-admin-kubeconfig \
  -n clusters -o jsonpath='{.data.kubeconfig}' | base64 -d > /tmp/guest-kubeconfig.yaml

Cleanup

Use the dev:destroy-hc-aws skill or run:

source $AWS_CREDS_SOURCE && \
KUBECONFIG=$MGMT_KUBECONFIG \
./bin/hypershift destroy cluster aws \
  --name <CLUSTER_NAME> \
  --namespace clusters \
  --aws-creds $AWS_CREDENTIALS \
  --region $AWS_REGION

Troubleshooting

Cluster Creation Fails

Check AWS credentials are valid
Verify base domain exists in Route53
Ensure OIDC S3 bucket is accessible

Control Plane Not Available

Check HCP pods: kubectl get pods -n clusters-<CLUSTER_NAME>
Check HCP conditions: kubectl get hcp -n clusters-<CLUSTER_NAME> -o yaml

Nodes Not Joining

Check machines: kubectl get machines -n clusters-<CLUSTER_NAME>
Check NodePool conditions: kubectl get nodepool -n clusters -o yaml