Imported from tomevault-io/tomes (openshift-eng--ai-helpers/skills/hcp-create-aws/SKILL.md). Install upstream with npx skills add tomevault-io/tomes --skill hcp-create-aws. Copyright stays with the author.

HyperShift AWS Provider

This skill provides implementation guidance for creating HyperShift clusters on AWS, handling AWS-specific requirements including STS credentials, IAM roles, VPC configuration, and regional best practices.

When to Use This Skill

This skill is automatically invoked by the /hcp:generate aws command to guide the AWS provider cluster creation process.

Prerequisites

• AWS CLI configured with appropriate credentials
• HyperShift operator installed and configured
• STS credentials file for the target AWS account
• IAM role with required permissions for HyperShift
• Pull secret for accessing OpenShift images

AWS Provider Overview

AWS Provider Peculiarities

• Requires AWS credentials (STS): Must have valid STS credentials file
• Region selection affects availability zones: Different regions have different AZ availability
• Instance types vary by region: Not all instance types available in all regions
• VPC CIDR must not conflict: Must not overlap with existing infrastructure
• IAM roles: Can be auto-created or use pre-existing roles

Common AWS Configurations

Development Environment:

• Single replica control plane (cost-effective)
• m5.large instances (balanced performance/cost)
• 2 availability zones (basic redundancy)
• Basic networking (public endpoints)

Production Environment:

• Highly available control plane
• m5.xlarge+ instances (better performance)
• 3+ availability zones (high availability)
• Custom VPC configuration
• KMS encryption enabled

Cost-Optimized Environment:

• Single NAT gateway
• Smaller instance types
• Minimal replicas
• Spot instances (where applicable)

Implementation Steps

Step 1: Analyze Cluster Description

Parse the natural language description for AWS-specific requirements:

Environment Type Detection:

• Development: "dev", "development", "testing", "demo", "sandbox"
• Production: "prod", "production", "critical", "enterprise"
• Cost-Optimized: "cheap", "cost", "minimal", "budget", "demo"

Performance Indicators:

• High Performance: "performance", "fast", "high-compute", "intensive"
• Standard: Default moderate configuration
• Minimal: "small", "minimal", "basic", "simple"

Security/Compliance:

• FIPS: "fips", "compliance", "security", "regulated"
• Private: "private", "isolated", "secure", "internal"

Special Requirements:

• Multi-AZ: "highly available", "ha", "multi-zone", "resilient"
• Single-AZ: "single zone", "simple", "minimal"

Step 2: Apply AWS Provider Defaults

Required Parameters:

• --region: AWS region (default: us-east-1)
• --pull-secret: Path to pull secret file
• --release-image: OpenShift release image
• --sts-creds: REQUIRED - Path to STS credentials file
• --role-arn: REQUIRED - ARN of the IAM role to assume
• --base-domain: REQUIRED - Base domain for the cluster

Smart Defaults by Environment:

Development Environment:

--instance-type m5.large
--node-pool-replicas 2
--control-plane-availability-policy SingleReplica
--endpoint-access Public
--root-volume-size 120
--zones auto-select 2 zones based on region

Production Environment:

--instance-type m5.xlarge
--node-pool-replicas 3
--control-plane-availability-policy HighlyAvailable
--endpoint-access PublicAndPrivate
--root-volume-size 120
--auto-repair true
--zones auto-select 3+ zones based on region

Cost-Optimized Environment:

--instance-type m5.large
--node-pool-replicas 2
--control-plane-availability-policy SingleReplica
--endpoint-access Public
--root-volume-size 120
--zones auto-select 2 zones (minimal redundancy)

Step 3: Interactive Parameter Collection

Required Information Collection:

1. Cluster Name

   🔹 **Cluster Name**: What would you like to name your cluster?
      - Must be DNS-compatible (lowercase, hyphens allowed)
      - Used for AWS resource naming
      - Example: dev-cluster, prod-app, demo-env
   

2. AWS Region

   🔹 **AWS Region**: Which AWS region should host your cluster?
      - Consider latency to your users
      - Verify desired instance types are available
      - [Press Enter for default: us-east-1]
   
      Popular regions:
      - us-east-1 (N. Virginia) - Largest service availability
      - us-west-2 (Oregon) - West coast, latest services
      - eu-west-1 (Ireland) - Europe
      - ap-southeast-1 (Singapore) - Asia Pacific
   

3. STS Credentials

   🔹 **STS Credentials**: Path to your AWS STS credentials file?
      - Required for AWS authentication
      - Generate using: aws sts get-session-token
      - Example: /home/user/.aws/sts-creds.json
      - Format: {"AccessKeyId": "...", "SecretAccessKey": "...", "SessionToken": "..."}
   

4. IAM Role ARN

   🔹 **IAM Role ARN**: ARN of the IAM role for HyperShift?
      - Role must have required HyperShift permissions
      - Example: arn:aws:iam::123456789012:role/hypershift-operator-role
      - See: https://hypershift.openshift.io/aws-setup/
   

5. Base Domain

   🔹 **Base Domain**: What base domain should be used for cluster DNS?
      - Must be a domain you control in Route53
      - Used for cluster API and application routes
      - Example: example.com, clusters.mycompany.com
   

6. Pull Secret

   🔹 **Pull Secret**: Path to your OpenShift pull secret file?
      - Required for accessing OpenShift container images
      - Download from: https://console.redhat.com/openshift/install/pull-secret
      - Example: /home/user/pull-secret.json
   

7. OpenShift Version

   🔹 **OpenShift Version**: Which OpenShift version do you want to use?
   
      📋 **Check supported versions**: https://amd64.ocp.releases.ci.openshift.org/
   
      - Enter release image URL: quay.io/openshift-release-dev/ocp-release:X.Y.Z-multi
      - [Press Enter for default: quay.io/openshift-release-dev/ocp-release:4.18.0-multi]
   

Optional Configuration (based on description analysis):

8. Instance Type (if performance requirements detected)

   🔹 **Instance Type**: Select instance type based on your performance needs:
      - m5.large (2 vCPU, 8GB RAM) - Development, light workloads
      - m5.xlarge (4 vCPU, 16GB RAM) - Production, balanced workloads
      - m5.2xlarge (8 vCPU, 32GB RAM) - High-performance workloads
      - c5.xlarge (4 vCPU, 8GB RAM) - Compute-optimized
      - [Press Enter for default based on environment type]
   

9. Node Pool Replicas

   🔹 **Node Pool Replicas**: How many worker nodes do you need?
      - Minimum: 2 (for basic redundancy)
      - Production recommended: 3+
      - [Press Enter for default based on environment type]
   

10. Availability Zones (auto-selected, but confirmed)

    🔹 **Availability Zones**: Detected region: us-east-1
       Auto-selecting zones for optimal distribution:
       - Development: us-east-1a, us-east-1b (2 zones)
       - Production: us-east-1a, us-east-1b, us-east-1c (3 zones)
    
       Modify zone selection? [y/N]
    

Step 4: Advanced Configuration (Conditional)

For FIPS Compliance (if detected):

🔹 **FIPS Mode**: Enable FIPS mode for compliance?
   - Required for government/regulated workloads
   - May impact performance
   - [yes/no] [Press Enter for default: no]

For High-Performance Workloads:

🔹 **Root Volume Size**: Increase root volume size?
   - Default: 120GB
   - High-performance workloads: 200GB+
   - [Press Enter for default: 120]

For Production Environments:

🔹 **Auto-Repair**: Enable automatic node repair?
   - Automatically replaces unhealthy nodes
   - Recommended for production
   - [yes/no] [Press Enter for default: yes for production]

Step 5: Generate Command

Basic AWS Cluster Command:

hypershift create cluster aws \
  --name <cluster-name> \
  --namespace <cluster-name>-ns \
  --region <region> \
  --instance-type <instance-type> \
  --pull-secret <pull-secret-path> \
  --node-pool-replicas <replica-count> \
  --zones <zone-list> \
  --control-plane-availability-policy <policy> \
  --sts-creds <sts-creds-path> \
  --role-arn <role-arn> \
  --base-domain <base-domain> \
  --release-image <release-image>

Development Configuration Example:

hypershift create cluster aws \
  --name dev-cluster \
  --namespace dev-cluster-ns \
  --region us-east-1 \
  --instance-type m5.large \
  --pull-secret /path/to/pull-secret.json \
  --node-pool-replicas 2 \
  --zones us-east-1a,us-east-1b \
  --control-plane-availability-policy SingleReplica \
  --endpoint-access Public \
  --root-volume-size 120 \
  --sts-creds /path/to/sts-creds.json \
  --role-arn arn:aws:iam::123456789012:role/hypershift-role \
  --base-domain example.com \
  --release-image quay.io/openshift-release-dev/ocp-release:4.18.0-multi

Production Configuration Example:

hypershift create cluster aws \
  --name production-cluster \
  --namespace production-cluster-ns \
  --region us-west-2 \
  --instance-type m5.xlarge \
  --pull-secret /path/to/pull-secret.json \
  --node-pool-replicas 3 \
  --zones us-west-2a,us-west-2b,us-west-2c \
  --control-plane-availability-policy HighlyAvailable \
  --endpoint-access PublicAndPrivate \
  --root-volume-size 120 \
  --auto-repair \
  --sts-creds /path/to/sts-creds.json \
  --role-arn arn:aws:iam::123456789012:role/hypershift-prod-role \
  --base-domain clusters.company.com \
  --release-image quay.io/openshift-release-dev/ocp-release:4.18.0-multi

FIPS-Enabled Configuration:

hypershift create cluster aws \
  --name compliance-cluster \
  --namespace compliance-cluster-ns \
  --region us-gov-east-1 \
  --instance-type m5.xlarge \
  --pull-secret /path/to/pull-secret.json \
  --node-pool-replicas 3 \
  --zones us-gov-east-1a,us-gov-east-1b,us-gov-east-1c \
  --control-plane-availability-policy HighlyAvailable \
  --fips \
  --sts-creds /path/to/sts-creds.json \
  --role-arn arn:aws-us-gov:iam::123456789012:role/hypershift-fips-role \
  --base-domain secure.gov.example.com \
  --release-image quay.io/openshift-release-dev/ocp-release:4.18.0-multi

Step 6: Pre-Flight Validation

Provide validation commands:

## Pre-Flight Checks

Before creating the cluster, verify your setup:

1. **AWS Credentials:**
   aws sts get-caller-identity

2. **STS Credentials File:**
   cat /path/to/sts-creds.json | jq .

3. **IAM Role Access:**
   aws iam get-role --role-name hypershift-role

4. **Route53 Domain:**
   aws route53 list-hosted-zones --query "HostedZones[?Name=='example.com.']"

5. **Region Availability:**
   aws ec2 describe-availability-zones --region us-east-1

6. **Instance Type Availability:**
   aws ec2 describe-instance-type-offerings --location-type availability-zone --filters Name=instance-type,Values=m5.large --region us-east-1

Step 7: Post-Generation Instructions

Next Steps:

## Next Steps

1. **Verify prerequisites are met:**
   - AWS credentials configured
   - STS credentials file exists and is valid
   - IAM role has required permissions
   - Base domain exists in Route53

2. **Run the generated command:**
   Copy and paste the command above

3. **Monitor cluster creation:**
   kubectl get hostedcluster -n <cluster-namespace>
   kubectl get nodepool -n <cluster-namespace>

4. **Check AWS resources:**
   - EC2 instances in AWS console
   - Load balancers created
   - VPC and networking resources

5. **Access cluster when ready:**
   hypershift create kubeconfig --name <cluster-name> --namespace <cluster-namespace>
   export KUBECONFIG=<cluster-name>-kubeconfig
   oc get nodes

Error Handling

Invalid AWS Credentials

Scenario: AWS credentials are invalid or expired.

Action:

AWS credentials validation failed.

Please check:
1. AWS CLI configuration: aws configure list
2. STS credentials file validity
3. IAM permissions

Regenerate STS credentials:
  aws sts get-session-token --duration-seconds 3600

IAM Role Not Found

Scenario: Specified IAM role doesn't exist or can't be assumed.

Action:

IAM role "arn:aws:iam::123456789012:role/hypershift-role" not found or inaccessible.

Please verify:
1. Role exists: aws iam get-role --role-name hypershift-role
2. Role has required permissions
3. Trust relationship allows your account to assume the role

See HyperShift AWS setup guide: https://hypershift.openshift.io/aws-setup/

Region/Zone Issues

Scenario: Instance type not available in selected region/zones.

Action:

Instance type "m5.large" not available in zone "us-east-1f".

Checking alternative zones in us-east-1:
✅ us-east-1a (available)
✅ us-east-1b (available)
❌ us-east-1f (not available)

Suggested zones: us-east-1a,us-east-1b

Would you like me to update the command?

Route53 Domain Issues

Scenario: Base domain not found in Route53 or not accessible.

Action:

Base domain "example.com" not found in Route53.

Please ensure:
1. Domain exists in Route53: aws route53 list-hosted-zones
2. Account has access to the hosted zone
3. Domain spelling is correct

Alternative: Use a subdomain you control (e.g., clusters.mydomain.com)

Resource Limits

Scenario: AWS account limits would be exceeded.

Action:

AWS service limits may be exceeded:
- EC2 instances: Current: 18/20, Requested: 5 more
- Elastic IPs: Current: 4/5, Requested: 2 more

Consider:
1. Request limit increases via AWS Support
2. Choose smaller instance types
3. Reduce node count
4. Clean up unused resources

Best Practices

Cost Optimization

1. Right-size instances: Don't over-provision for development
2. Use Spot instances: Where appropriate for non-critical workloads
3. Monitor resource usage: Regularly review AWS costs
4. Clean up unused clusters: Delete development clusters when not needed

Security

1. Least privilege IAM: Use minimal required permissions
2. STS credentials: Use short-lived credentials when possible
3. Private networking: Use PrivateAndPublic endpoints for production
4. KMS encryption: Enable for sensitive workloads

High Availability

1. Multi-AZ deployment: Use 3+ availability zones for production
2. Instance distribution: Spread nodes across zones
3. Auto-repair: Enable for automatic recovery
4. Monitoring: Set up CloudWatch monitoring

Network Planning

1. VPC design: Plan CIDR ranges carefully
2. Subnet strategy: Use public/private subnet design
3. Load balancer: Configure appropriate load balancer types
4. DNS: Ensure proper Route53 configuration

Anti-Patterns to Avoid

❌ Using root AWS credentials

Never use root account credentials for HyperShift

✅ Use IAM roles and STS credentials

❌ Single availability zone for production

--zones us-east-1a  # Single point of failure

✅ Use multiple zones: --zones us-east-1a,us-east-1b,us-east-1c

❌ Over-provisioning for development

--instance-type m5.8xlarge --node-pool-replicas 10  # Expensive for dev

✅ Use appropriate sizing: --instance-type m5.large --node-pool-replicas 2

❌ Ignoring region-specific limitations

Choosing regions without checking instance type availability

✅ Verify instance types and services are available in target region

Example Workflows

Startup Development Environment

Input: "cheap AWS cluster for testing our new microservice"

Analysis:
- Environment: Development
- Cost focus: High priority
- Scale: Minimal

Generated Command:
hypershift create cluster aws \
  --name dev-microservice \
  --namespace dev-microservice-ns \
  --region us-east-1 \
  --instance-type m5.large \
  --node-pool-replicas 2 \
  --control-plane-availability-policy SingleReplica \
  --endpoint-access Public

Enterprise Production

Input: "highly available AWS production cluster for customer-facing applications"

Analysis:
- Environment: Production
- Availability: High priority
- Scale: Enterprise

Generated Command:
hypershift create cluster aws \
  --name prod-customer-apps \
  --namespace prod-customer-apps-ns \
  --region us-west-2 \
  --instance-type m5.xlarge \
  --node-pool-replicas 5 \
  --zones us-west-2a,us-west-2b,us-west-2c \
  --control-plane-availability-policy HighlyAvailable \
  --endpoint-access PublicAndPrivate \
  --auto-repair

See Also

• HyperShift AWS Provider Documentation
• AWS IAM Roles for HyperShift
• AWS CLI Configuration Guide
• OpenShift on AWS Best Practices

Converted and distributed by TomeVault — claim your Tome and manage your conversions.