HyperShift Local Setup Skill

Setup the local development environment for HyperShift cluster provisioning.

When to Use

• First time setting up HyperShift testing
• After reinstalling tools or machine
• Missing hcp CLI or ansible collections
• User asks "setup hypershift" or "configure hypershift"

Prerequisites

Before running setup:

1. AWS CLI: Configured with admin credentials
2. OpenShift CLI (oc): Installed and logged into management cluster
3. Ansible: pip install ansible-core
4. Credentials file: Created by setup-hypershift-ci-credentials.sh

Quick Setup Workflow

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

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

# 3. Setup local tools
./.github/scripts/hypershift/local-setup.sh

What local-setup.sh Does

1. Loads credentials from .env.rossoctl-hypershift-custom or .env.hypershift-ci
2. Installs hcp CLI from OpenShift console to ~/.local/bin
3. Clones hypershift-automation repository (Ladas fork with additional-tags support)
4. Installs ansible collections: kubernetes.core, amazon.aws, community.general
5. Installs Python dependencies: boto3, botocore, kubernetes, openshift
6. Saves pull secret to ~/.pullsecret.json
7. Verifies kubeconfig for management cluster

Running local-setup.sh

# Run the setup script
./.github/scripts/hypershift/local-setup.sh

Expected output:

✓ Loaded credentials from .env.rossoctl-hypershift-custom
✓ hcp CLI installed to ~/.local/bin
✓ Cloned to .../hypershift-automation
✓ Ansible collections installed
✓ Python dependencies installed
✓ Pull secret saved to ~/.pullsecret.json
✓ Management kubeconfig verified

After Setup

# Create your first cluster
./.github/scripts/hypershift/create-cluster.sh

# Or run full test workflow
./.github/scripts/local-setup/hypershift-full-test.sh --skip-cluster-destroy

Manual Steps

Install hcp CLI Manually

If automatic download fails:

# 1. Get the console downloads URL
oc get consoleclidownloads hcp-cli-download -o jsonpath='{.spec.links}'

# 2. Download from OpenShift console
# Go to: ? → Command Line Tools → Download hcp CLI

# 3. Extract to ~/.local/bin
tar -xzf hcp-*.tar.gz && mv hcp ~/.local/bin/
chmod +x ~/.local/bin/hcp

# 4. Add to PATH (add to ~/.zshrc or ~/.bashrc)
export PATH="$HOME/.local/bin:$PATH"

Install Ansible Collections Manually

ansible-galaxy collection install kubernetes.core amazon.aws community.general --force-with-deps
pip install boto3 botocore kubernetes openshift PyYAML

Clone hypershift-automation Manually

cd ..
git clone -b add-additional-tags-support https://github.com/Ladas/hypershift-automation.git

Credentials File Structure

The setup creates .env.rossoctl-hypershift-custom (or .env.hypershift-ci):

# AWS credentials (scoped to MANAGED_BY_TAG)
export AWS_ACCESS_KEY_ID="..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_REGION="us-east-1"

# Cluster configuration
export MANAGED_BY_TAG="rossoctl-hypershift-custom"
export BASE_DOMAIN="octo-emerging.redhataicoe.com"
export HCP_ROLE_NAME="rossoctl-hypershift-custom-hcp-role"

# Management cluster access
export KUBECONFIG="$HOME/.kube/rossoctl-hypershift-ci-mgmt.kubeconfig"

# Pull secret (for accessing Red Hat registries)
export PULL_SECRET='{"auths":{...}}'

Verify Setup

# Check hcp CLI
hcp version

# Check ansible
ansible-playbook --version
ansible-galaxy collection list | grep -E "kubernetes|amazon|community"

# Check AWS credentials
aws sts get-caller-identity

# Check management cluster access
source .env.rossoctl-hypershift-custom
oc get hostedclusters -n clusters

Troubleshooting

hcp CLI Not Found

# Add ~/.local/bin to PATH
export PATH="$HOME/.local/bin:$PATH"

# Check if installed
ls -la ~/.local/bin/hcp

Ansible Collection Errors

# Reinstall collections
ansible-galaxy collection install kubernetes.core amazon.aws community.general --force

hypershift-automation Not Found

# Check sibling directory
ls -la ../hypershift-automation

# Re-run setup
./.github/scripts/hypershift/local-setup.sh

AWS Credentials Invalid

# Verify credentials work
source .env.rossoctl-hypershift-custom
aws sts get-caller-identity

# If using wrong credentials (e.g., CI instead of admin)
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY

Management Cluster Access Denied

# Re-login to management cluster
oc login <management-cluster-url>

# Re-run credentials setup
./.github/scripts/hypershift/setup-hypershift-ci-credentials.sh

Related Skills

• hypershift:preflight: Run full pre-flight checks
• hypershift:cluster: Create and destroy clusters
• hypershift:quotas: Check AWS quotas

Related Documentation

• .github/scripts/local-setup/README.md - Local setup documentation