hypershiftsetup

name: hypershift:setup description: Setup local environment for HyperShift testing. Installs hcp CLI, ansible collections, and configures credentials.

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:

AWS CLI: Configured with admin credentials
OpenShift CLI (oc): Installed and logged into management cluster
Ansible: pip install ansible-core
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

Loads credentials from .env.kagenti-hypershift-custom or .env.hypershift-ci
Installs hcp CLI from OpenShift console to ~/.local/bin
Clones hypershift-automation repository (Ladas fork with additional-tags support)
Installs ansible collections: kubernetes.core, amazon.aws, community.general
Installs Python dependencies: boto3, botocore, kubernetes, openshift
Saves pull secret to ~/.pullsecret.json
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.kagenti-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.kagenti-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="kagenti-hypershift-custom"
export BASE_DOMAIN="octo-emerging.redhataicoe.com"
export HCP_ROLE_NAME="kagenti-hypershift-custom-hcp-role"

# Management cluster access
export KUBECONFIG="$HOME/.kube/kagenti-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.kagenti-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.kagenti-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