skilld
All skills
openshift avatar

/create-hc-aws

@cfb745e official
by openshiftopenshift/hypershift543 stars
576

Create a HyperShift HostedCluster on AWS for development and testing, with optional custom CPO/HO images.

Ask your Agent

Use this Skill: https://skilld.dev/gh/openshift/hypershift/create-hc-aws

This session only. Nothing lands on disk.

SKILL.md

≈30 tokens always: the name and description. ≈1.2k when used: this file.

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

  1. Check HostedCluster status:

    KUBECONFIG=$MGMT_KUBECONFIG kubectl get hostedcluster -n clusters

  2. Wait for control plane to be available:

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

  3. Scale NodePool to add nodes:

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

  4. 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

Source: SKILL.md on GitHub

Third-party checks

1 warning3mo3 checks · Risk SAFE
  • Gen Agent Trust Hub3mo

    This skill provides standard developer workflows for creating OpenShift clusters on AWS. It accesses local configuration and executes administrative commands required for cloud provisioning, which is consistent with its stated purpose.

  • Socket3mo

    No alerts

  • Snyk3mo

    Risk: MEDIUM · 1 issue

Provenance

Signed by skilld at cfb745e. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 8 months ago

Topics

  • Infrastructure
  • hypershift
  • aws
  • kubernetes
  • hostedcluster
  • openshift
  • development
  • cluster-creation

README badge

README badge for openshift/hypershift/create-hc-aws

What it does

Creates a HyperShift HostedCluster on AWS for development and testing, with support for custom control plane operator images. Targets the hypershift binary and assumes a management cluster with AWS credentials, pull secrets, and environment variables pre-configured.

Generated from the current SKILL.md.

Frequently asked

What AWS resources does this skill create?
The skill creates a VPC with public/private subnets, NAT and internet gateways, Route53 private hosted zones, OIDC provider for STS, IAM roles, and worker instance profiles. It also creates HostedCluster and NodePool resources in the management cluster.
Can I use custom CPO or HO images with this skill?
Yes. The skill supports the `--control-plane-operator-image` parameter to specify a custom CPO image, useful when testing CPO code changes.
Is this for production use?
No. The skill is explicitly for development and testing purposes only. Production use requires a different setup.
What prerequisites must be met before running this skill?
You need AWS credentials loaded, a management cluster kubeconfig set, the hypershift binary built, and a pull secret available. Source `dev/claude-env.sh` first to load required environment variables.
How do I get the kubeconfig for the created guest cluster?
After creation, extract it from the secret with: `kubectl get secret <CLUSTER_NAME>-admin-kubeconfig -n clusters -o jsonpath='{.data.kubeconfig}' | base64 -d > /tmp/guest-kubeconfig.yaml`

Generated from the current SKILL.md. These answers refresh after source changes.