HyperShift Pre-flight Check Skill
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
bash
# 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)
code
╔════════════════════════════════════════════════════════════════╗ ║ 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
bash
# 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
bash
# 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
bash
# 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
bash
# Login to management cluster oc login https://api.<management-cluster>:6443 # Verify oc whoami oc whoami --show-server
HyperShift Not Installed
code
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
code
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
code
Error: No PUBLIC Route53 hosted zone found for xxx
HyperShift requires a public hosted zone for DNS. Either:
- •Create a public hosted zone in Route53
- •Update BASE_DOMAIN in .env file to match an existing zone
Manual Checks
Check AWS Identity
bash
aws sts get-caller-identity
Check OpenShift Permissions
bash
oc auth can-i create clusterroles oc auth can-i create clusterrolebindings oc auth can-i get secrets -n openshift-config
Check HyperShift CRD
bash
oc get crd hostedclusters.hypershift.openshift.io
Check Operator OIDC Args
bash
oc get deployment operator -n hypershift \
-o jsonpath='{.spec.template.spec.containers[0].args}' | tr ',' '\n' | grep oidc
Check Route53 Zones
bash
aws route53 list-hosted-zones \
--query "HostedZones[?Config.PrivateZone==\`false\`].Name" \
--output table
Next Steps After Preflight
If all checks pass:
bash
# 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