hypershift:preflight

Verify all prerequisites for HyperShift cluster provisioning before running setup or creating clusters.

When to Use

• Before first-time HyperShift setup
• Troubleshooting failed cluster creation
• Verifying environment after changes
• User asks "check hypershift prereqs" or "why won't cluster create"

Quick Check

# Run all pre-flight checks
./.github/scripts/hypershift/preflight-check.sh

What It Checks

1. Tools for Setup

• jq - JSON processor
• aws - AWS CLI
• oc - OpenShift CLI

2. Tools for Cluster Creation

• hcp - HyperShift CLI (optional, installed by local-setup.sh)
• ansible-playbook - Ansible automation
• ansible-galaxy - Ansible collection manager

3. AWS Authentication

• AWS credentials configured
• Identity accessible

4. AWS IAM Permissions

• Can create IAM policies
• Can create IAM roles
• Not using CI credentials (needs admin for setup)

5. OpenShift Authentication

• Logged into management cluster
• Server accessible

6. OpenShift Permissions

• Can create ClusterRoles
• Can create ClusterRoleBindings
• Can read secrets in openshift-config namespace

7. HyperShift Installation

• HyperShift CRD exists on management cluster

8. HyperShift Operator OIDC

• Operator has OIDC S3 configuration
• Required for AWS hosted clusters

9. Pull Secret

• Can access pull secret in openshift-config
• Pull secret is valid JSON
• Registry count verified

10. Base Domain

• Auto-detects from ingress config
• Falls back to existing hosted clusters

11. Route53 Hosted Zone

• Public hosted zone exists for base domain
• Required for DNS resolution

Expected Output (Success)

╔════════════════════════════════════════════════════════════════╗
║           HyperShift CI Pre-flight Check                       ║
╚════════════════════════════════════════════════════════════════╝

→ Checking tools for setup...
✓ jq: jq-1.7.1
✓ aws: aws-cli/2.x.x
✓ oc: Client Version: 4.x.x

→ Checking tools for cluster creation...
✓ hcp: v4.x.x
✓ ansible-playbook: ansible-playbook 2.x.x
✓ ansible-galaxy: available

→ Checking AWS authentication...
✓ AWS authenticated: arn:aws:iam::xxx:user/xxx

→ Checking AWS IAM permissions for setup...
✓ AWS identity: arn:aws:iam::xxx:user/xxx
✓ AWS IAM: Can create policies
✓ AWS IAM: Can create roles

→ Checking OpenShift authentication...
✓ OpenShift authenticated: xxx @ https://xxx

→ Checking OpenShift permissions...
✓ Can create ClusterRoles
✓ Can create ClusterRoleBindings
✓ Can read secrets in openshift-config namespace

→ Checking HyperShift installation...
✓ HyperShift CRD found - HyperShift is installed

→ Checking HyperShift operator OIDC configuration...
✓ HyperShift operator has OIDC S3 configured

→ Checking pull secret accessibility...
✓ Pull secret valid (5 registries configured)

→ Checking base domain discovery...
✓ Base domain: octo-emerging.redhataicoe.com

→ Checking Route53 public hosted zone...
✓ Route53 public hosted zone found

╔════════════════════════════════════════════════════════════════╗
║  All checks passed! Ready to run setup script.                 ║
╚════════════════════════════════════════════════════════════════╝

Common Errors and Fixes

Missing Tools

# Install jq
brew install jq  # macOS
sudo apt install jq  # Ubuntu

# Install AWS CLI
# https://aws.amazon.com/cli/

# Install oc
# https://mirror.openshift.com/pub/openshift-v4/clients/ocp/

# Install ansible
pip install ansible-core

AWS Not Authenticated

# Configure AWS credentials
aws configure

# Or set environment variables
export AWS_ACCESS_KEY_ID="xxx"
export AWS_SECRET_ACCESS_KEY="xxx"
export AWS_REGION="us-east-1"

Using CI Credentials Instead of Admin

# Error: Logged in as CI user. Setup requires IAM admin.

# Fix: Unset CI credentials
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY

# Use your admin profile
aws configure list

OpenShift Not Logged In

# Login to management cluster
oc login https://api.<management-cluster>:6443

# Verify
oc whoami
oc whoami --show-server

HyperShift Not Installed

Error: HyperShift CRD not found.

This means the management cluster doesn't have HyperShift installed. Contact cluster admin or use a different management cluster.

HyperShift Operator Missing OIDC

Error: HyperShift operator MISSING OIDC S3 configuration!

The operator was upgraded and lost OIDC config. Follow the fix instructions in the preflight output (requires cluster-admin).

No Public Route53 Zone

Error: No PUBLIC Route53 hosted zone found for xxx

HyperShift requires a public hosted zone for DNS. Either:

1. Create a public hosted zone in Route53
2. Update BASE_DOMAIN in .env file to match an existing zone

Manual Checks

Check AWS Identity

aws sts get-caller-identity

Check OpenShift Permissions

oc auth can-i create clusterroles
oc auth can-i create clusterrolebindings
oc auth can-i get secrets -n openshift-config

Check HyperShift CRD

oc get crd hostedclusters.hypershift.openshift.io

Check Operator OIDC Args

oc get deployment operator -n hypershift \
    -o jsonpath='{.spec.template.spec.containers[0].args}' | tr ',' '\n' | grep oidc

Check Route53 Zones

aws route53 list-hosted-zones \
    --query "HostedZones[?Config.PrivateZone==\`false\`].Name" \
    --output table

Next Steps After Preflight

If all checks pass:

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

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

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

Related Skills

• hypershift:setup: Setup local environment
• hypershift:cluster: Create and destroy clusters
• hypershift:quotas: Check AWS quotas

Related Documentation

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