Hypershift:cluster

HyperShift Cluster Management Skill

Create, destroy, and manage HyperShift clusters on AWS for testing.

When to Use

• Need to create a test OpenShift cluster on AWS
• Destroying a cluster after testing
• User asks "create hypershift cluster" or "destroy cluster"
• Testing Kagenti on real OpenShift (not Kind)

Prerequisites

Before creating clusters, ensure setup is complete:

# 1. Run preflight check
./.github/scripts/hypershift/preflight-check.sh

# 2. Setup credentials (first time only, requires IAM admin)
./.github/scripts/hypershift/setup-hypershift-ci-credentials.sh

# 3. Setup local tools (hcp CLI, ansible, etc.)
./.github/scripts/hypershift/local-setup.sh

Create Cluster

Quick Create (Default Suffix)

# Creates: kagenti-hypershift-custom-<username>
./.github/scripts/hypershift/create-cluster.sh

Create with Custom Suffix

# Creates: kagenti-hypershift-custom-pr529
./.github/scripts/hypershift/create-cluster.sh pr529

# Creates: kagenti-hypershift-custom-mytest
./.github/scripts/hypershift/create-cluster.sh mytest

Create with Custom Configuration

# More worker nodes and larger instances
REPLICAS=3 INSTANCE_TYPE=m5.2xlarge ./.github/scripts/hypershift/create-cluster.sh

# Specific OCP version
OCP_VERSION=4.19.5 ./.github/scripts/hypershift/create-cluster.sh

Environment Variables

Destroy Cluster

Quick Destroy

# Destroy by suffix
./.github/scripts/hypershift/destroy-cluster.sh <suffix>

# Examples:
./.github/scripts/hypershift/destroy-cluster.sh pr529
./.github/scripts/hypershift/destroy-cluster.sh ladas

Destroy by Full Name

./.github/scripts/hypershift/destroy-cluster.sh kagenti-hypershift-custom-pr529

After Cluster Creation

The create script outputs next steps. Typical workflow:

# 1. Set kubeconfig to new cluster
export KUBECONFIG=~/clusters/hcp/<cluster-name>/auth/kubeconfig

# 2. Verify cluster access
oc get nodes
oc get clusterversion

# 3. Deploy Kagenti platform
./.github/scripts/kagenti-operator/30-run-installer.sh --env ocp
./.github/scripts/kagenti-operator/41-wait-crds.sh
./.github/scripts/kagenti-operator/42-apply-pipeline-template.sh

# 4. Deploy demo agents
./.github/scripts/kagenti-operator/71-build-weather-tool.sh
./.github/scripts/kagenti-operator/72-deploy-weather-tool.sh
./.github/scripts/kagenti-operator/73-patch-weather-tool.sh
./.github/scripts/kagenti-operator/74-deploy-weather-agent.sh

# 5. Run E2E tests
export AGENT_URL="https://$(oc get route -n team1 weather-service -o jsonpath='{.spec.host}')"
export KAGENTI_CONFIG_FILE=deployments/envs/ocp_values.yaml
./.github/scripts/kagenti-operator/90-run-e2e-tests.sh

Full Test Workflow

Use the full test script for complete workflow:

# Full test: create cluster -> deploy -> test -> keep cluster
./.github/scripts/local-setup/hypershift-full-test.sh --skip-cluster-destroy

# With custom suffix
./.github/scripts/local-setup/hypershift-full-test.sh pr123 --skip-cluster-destroy

# Include cleanup after test
./.github/scripts/local-setup/hypershift-full-test.sh --include-cluster-destroy

Cluster Naming

Clusters are named: ${MANAGED_BY_TAG}-${CLUSTER_SUFFIX}

Troubleshooting

Cluster Creation Stuck

# Check HostedCluster status (use management cluster kubeconfig)
source .env.kagenti-hypershift-custom  # or .env.hypershift-ci
oc get hostedcluster -n clusters

# Check conditions
oc get hostedcluster -n clusters <cluster-name> -o jsonpath='{range .status.conditions[*]}{.type}{": "}{.status}{" - "}{.message}{"\n"}{end}'

# Check NodePool
oc get nodepool -n clusters <cluster-name>

Cluster Deletion Stuck

# Debug AWS resources
./.github/scripts/hypershift/debug-aws-hypershift.sh <cluster-name>

# Force remove finalizer (only if AWS resources are cleaned)
oc patch hostedcluster -n clusters <cluster-name> -p '{"metadata":{"finalizers":null}}' --type=merge

Control Plane Namespace Issues

# If namespace is stuck terminating
oc delete ns clusters-<cluster-name> --wait=false
oc patch ns clusters-<cluster-name> -p '{"metadata":{"finalizers":null}}' --type=merge

Check AWS Quotas

# Before creating clusters, check capacity
./.github/scripts/hypershift/check-quotas.sh

Related Skills

• hypershift:setup: Setup local environment for HyperShift
• hypershift:preflight: Run pre-flight checks
• hypershift:quotas: Check AWS quotas
• hypershift:debug: Debug AWS resources for stuck clusters

Related Documentation

• .github/scripts/local-setup/README.md - Local setup documentation
• docs/hypershift-hcp-research.md - HyperShift research and architecture