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:

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

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

1. Check HostedCluster status:

   bashCopy

   KUBECONFIG=$MGMT_KUBECONFIG kubectl get hostedcluster -n clusters
   

2. Wait for control plane to be available:

   bashCopy

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

3. Scale NodePool to add nodes:

   bashCopy

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

4. Get guest cluster kubeconfig:

   bashCopy

   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