# Hypershiftpreflight > Run pre-flight checks for HyperShift CI. Verifies tools, AWS auth, OpenShift permissions, and configuration. Use when this capability is needed. - Skill: `tomevault-io/hypershiftpreflight` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/hypershiftpreflight` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/hypershiftpreflight/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/hypershiftpreflight --- # 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) ``` ╔════════════════════════════════════════════════════════════════╗ ║ 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.: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 ```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 --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/kagenti) — claim your Tome and manage your conversions.