zhongwei/gh-openshift-eng-ai-helpers-plugins-hcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:45:56 +08:00
commit 9fc59ddec1
11 changed files with 3200 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

509
skills/hcp-create-agent/SKILL.md Normal file
View File

@@ -0,0 +1,509 @@
---
name: HyperShift Agent Provider
description: Use this skill when you need to deploy HyperShift clusters on bare metal, edge environments, or disconnected infrastructures using pre-provisioned agents
---
# HyperShift Agent Provider
This skill provides implementation guidance for creating HyperShift clusters using the Agent provider, which is designed for bare metal and edge deployments where pre-provisioned agents are available.
## When to Use This Skill
This skill is automatically invoked by the `/hcp:generate agent` command to guide the Agent provider cluster creation process.
## Prerequisites
- HyperShift operator installed and configured
- Pre-provisioned agents available in a Kubernetes namespace
- Pull secret for accessing OpenShift images
- Understanding of the target deployment environment
## Agent Provider Overview
### What is the Agent Provider?
The Agent provider:
- Designed for bare metal and edge deployments
- Requires pre-provisioned agents (nodes registered in advance)
- No cloud provider automation - manual network configuration required
- Suitable for disconnected/airgapped environments
- Direct control over hardware and network configuration
### Common Use Cases
- **Edge Computing**: Remote locations with limited connectivity
- **Bare Metal**: On-premises hardware without cloud automation
- **Disconnected Environments**: Airgapped environments with security requirements
- **Custom Hardware**: Specialized hardware configurations
- **Regulatory Compliance**: Environments requiring specific data locality
## Implementation Steps
### Step 1: Analyze Cluster Description
Parse the natural language description for Agent-specific requirements:
**Environment Type Detection:**
- **Edge**: "edge", "remote", "limited connectivity", "small footprint"
- **Bare Metal**: "bare metal", "on-premises", "physical hardware", "custom hardware"
- **Disconnected**: "airgapped", "disconnected", "offline", "secure environment"
**Resource Indicators:**
- **Minimal**: "small", "edge", "minimal resources", "single node"
- **Standard**: "production", "multi-node", "high availability"
**Special Requirements:**
- **FIPS**: "fips", "compliance", "security"
- **Custom Storage**: "local storage", "storage class", "persistent volumes"
- **Network Isolation**: "isolated", "private network", "custom networking"
### Step 2: Apply Agent Provider Defaults
**Required Parameters:**
- `--agent-namespace`: Namespace where agents are located
- `--pull-secret`: Path to pull secret file
- `--release-image`: OpenShift release image
- `--base-domain`: Base domain for the cluster (prompt user if not in description)
**Smart Defaults by Environment:**
**Edge Environment:**
```bash
--control-plane-availability-policy SingleReplica
--node-pool-replicas 1
--arch amd64 # or arm64 if specified
```
**Bare Metal Environment:**
```bash
--control-plane-availability-policy HighlyAvailable
--node-pool-replicas 3
--auto-repair true
```
**Disconnected Environment:**
```bash
--render # Always render for review
--image-content-sources /path/to/image-content-sources.yaml
--additional-trust-bundle /path/to/ca-bundle.pem
```
### 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)
- Will be used for resource naming
- Example: edge-lab-01, production-cluster
```
2. **Agent Namespace**
```
🔹 **Agent Namespace**: In which namespace are your agents located?
- This should be the namespace where you registered your agents
- Example: default, agent-system, cluster-agents
- [Press Enter for default: default]
```
3. **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
```
4. **Base Domain** (if not specified in description)
```
🔹 **Base Domain**: What base domain should be used for cluster DNS?
- This will be used for cluster API and application routes
- Example: example.com, lab.internal, edge.local
```
5. **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):**
6. **Architecture** (if detected)
```
🔹 **Architecture**: Detected ARM architecture mention. Confirm architecture:
- amd64 (x86_64)
- arm64 (aarch64)
- [Press Enter for default: amd64]
```
7. **FIPS Mode** (if compliance mentioned)
```
🔹 **FIPS Mode**: Enable FIPS mode for compliance?
- Required for certain regulatory environments
- May impact performance
- [yes/no] [Press Enter for default: no]
```
### Step 4: Disconnected Environment Handling
If disconnected/airgapped environment is detected:
**Additional Required Information:**
1. **Mirror Registry**
```
🔹 **Mirror Registry**: What is your mirror registry domain?
- This registry should contain mirrored OpenShift images
- Example: registry.example.com:5000
```
2. **Image Content Sources**
```
🔹 **Image Content Sources**: Path to image content sources file?
- Required for mapping official images to mirror registry
- Example: /path/to/image-content-sources.yaml
```
3. **Additional Trust Bundle** (optional)
```
🔹 **Additional Trust Bundle**: Path to custom CA bundle? (Optional)
- Required if mirror registry uses custom certificates
- Example: /path/to/ca-bundle.pem
- [Press Enter to skip]
```
**Always Use --render for Disconnected:**
- Include `--render` flag to generate manifests for review
- Provide post-generation instructions for required manifest modifications
### Step 5: Agent Availability Validation
**Provide Agent Check Commands:**
```
Before creating the cluster, verify your agents are available:
Check agents in namespace:
kubectl get agents -n <agent-namespace>
Verify agent status:
kubectl describe agents -n <agent-namespace>
Ensure agents are:
- In "Available" state
- Not bound to other clusters
- Meet minimum resource requirements
```
### Step 6: Generate Command
**Basic Agent Cluster Command:**
```bash
hypershift create cluster agent \
--name <cluster-name> \
--namespace <cluster-name>-ns \
--agent-namespace <agent-namespace> \
--pull-secret <pull-secret-path> \
--release-image <release-image> \
--base-domain <base-domain>
```
**With Environment-Specific Flags:**
**Edge/Minimal Configuration:**
```bash
hypershift create cluster agent \
--name edge-cluster \
--namespace edge-cluster-ns \
--agent-namespace default \
--pull-secret /path/to/pull-secret.json \
--release-image quay.io/openshift-release-dev/ocp-release:4.18.0-multi \
--base-domain edge.local \
--control-plane-availability-policy SingleReplica \
--node-pool-replicas 1
```
**Production/HA Configuration:**
```bash
hypershift create cluster agent \
--name production-cluster \
--namespace production-cluster-ns \
--agent-namespace agent-system \
--pull-secret /path/to/pull-secret.json \
--release-image quay.io/openshift-release-dev/ocp-release:4.18.0-multi \
--base-domain example.com \
--control-plane-availability-policy HighlyAvailable \
--node-pool-replicas 3 \
--auto-repair
```
**Disconnected Configuration:**
```bash
hypershift create cluster agent \
--name secure-cluster \
--namespace secure-cluster-ns \
--agent-namespace agent-system \
--pull-secret /path/to/pull-secret.json \
--release-image quay.io/openshift-release-dev/ocp-release:4.18.0-multi \
--base-domain internal.example.com \
--image-content-sources /path/to/image-content-sources.yaml \
--additional-trust-bundle /path/to/ca-bundle.pem \
--render
```
**FIPS-Enabled Configuration:**
```bash
hypershift create cluster agent \
--name compliance-cluster \
--namespace compliance-cluster-ns \
--agent-namespace agent-system \
--pull-secret /path/to/pull-secret.json \
--release-image quay.io/openshift-release-dev/ocp-release:4.18.0-multi \
--base-domain secure.example.com \
--fips
```
### Step 7: Post-Generation Instructions
**For Disconnected Environments:**
Provide additional configuration needed after cluster creation:
```
## Post-Creation Configuration (Disconnected)
After running the command above (with --render), you'll need to modify the generated manifests:
1. **Add ImageContentSources to HostedCluster:**
```yaml
spec:
imageContentSources:
- source: quay.io/openshift-release-dev/ocp-v4.0-art-dev
mirrors:
- registry.example.com:5000/openshift/release
- source: quay.io/openshift-release-dev/ocp-release
mirrors:
- registry.example.com:5000/openshift/release-images
- source: registry.redhat.io/multicluster-engine
mirrors:
- registry.example.com:5000/openshift/multicluster-engine
```
2. **Disable Default OperatorHub Sources:**
```yaml
spec:
configuration:
operatorhub:
disableAllDefaultSources: true
```
3. **Apply the manifests:**
```bash
kubectl apply -f <rendered-manifest-files>
```
```
**For All Environments:**
```
## Next Steps
1. **Verify agents are available:**
kubectl get agents -n <agent-namespace>
2. **Monitor cluster creation:**
kubectl get hostedcluster -n <cluster-namespace>
kubectl get nodepool -n <cluster-namespace>
3. **Check agent assignment:**
kubectl get agents -n <agent-namespace> -o wide
4. **Access cluster when ready:**
hypershift create kubeconfig --name <cluster-name> --namespace <cluster-namespace>
```
## Error Handling
### No Agents Available
**Scenario:** No agents found in specified namespace.
**Action:**
```
No agents found in namespace "default".
Please ensure:
1. Agents are properly registered
2. Agents are in "Available" state
3. Correct namespace specified
Check agents:
kubectl get agents -A
Register new agents using the agent-based installer or manual process.
```
### Insufficient Agents
**Scenario:** Not enough agents for requested replicas.
**Action:**
```
Only 2 agents available, but you requested 3 node replicas.
Options:
1. Reduce node-pool-replicas to 2
2. Register additional agents
3. Use SingleReplica control plane (reduces total requirement)
Would you like me to adjust the configuration?
```
### Agent Already Bound
**Scenario:** Agents are already assigned to another cluster.
**Action:**
```
Some agents are already bound to other clusters.
Available agents: 1
Bound agents: 2
Check agent status:
kubectl describe agents -n <namespace>
Free up agents by deleting unused clusters or register new agents.
```
### Disconnected Image Access
**Scenario:** Can't access release images in disconnected environment.
**Action:**
```
Release image access failed. In disconnected environments:
1. Ensure mirror registry contains required images
2. Verify image-content-sources file mapping
3. Check custom CA bundle configuration
4. Validate network connectivity to mirror registry
Mirror required images using:
oc adm release mirror --to <mirror-registry>
```
## Best Practices
### Agent Management
1. **Pre-provision agents:** Register agents before cluster creation
2. **Agent naming:** Use descriptive names for easier management
3. **Resource allocation:** Ensure agents meet minimum requirements
4. **Health monitoring:** Monitor agent status regularly
### Network Configuration
1. **DNS planning:** Ensure proper DNS resolution for base domain
2. **Load balancing:** Configure external load balancer for API access
3. **Ingress:** Plan for application ingress and routing
4. **Firewall:** Configure appropriate firewall rules
### Security
1. **Pull secret security:** Protect pull secret files
2. **FIPS compliance:** Enable FIPS for regulated environments
3. **Certificate management:** Plan for custom certificate authorities
4. **Network isolation:** Implement appropriate network segmentation
### Disconnected Deployments
1. **Mirror planning:** Pre-mirror all required images
2. **Catalog management:** Prepare custom operator catalogs
3. **Certificate management:** Plan for custom CA bundles
4. **Registry security:** Secure mirror registry access
## Anti-Patterns to Avoid
❌ **Assuming cloud automation**
```
"Create cluster with autoscaling"
```
✅ Agent provider requires manual agent provisioning
❌ **Insufficient agent planning**
```
Not checking agent availability before cluster creation
```
✅ Always verify sufficient agents are available
❌ **Ignoring disconnected requirements**
```
Using public image references in airgapped environment
```
✅ Properly configure image content sources and mirror registry
❌ **Inadequate resource planning**
```
Using minimal agents for production workloads
```
✅ Size agents appropriately for expected workloads
## Example Workflows
### Edge Deployment
```
Input: "small edge cluster for remote office monitoring"
Analysis:
- Environment: Edge
- Scale: Minimal
- Use case: Monitoring
Generated Command:
hypershift create cluster agent \
--name edge-monitoring \
--namespace edge-monitoring-ns \
--agent-namespace default \
--pull-secret /path/to/pull-secret.json \
--release-image quay.io/openshift-release-dev/ocp-release:4.18.0-multi \
--base-domain edge.local \
--control-plane-availability-policy SingleReplica \
--node-pool-replicas 1
```
### Secure Data Center
```
Input: "airgapped production cluster for financial data processing"
Analysis:
- Environment: Disconnected/Secure
- Scale: Production
- Use case: Financial (compliance required)
Generated Command:
hypershift create cluster agent \
--name financial-prod \
--namespace financial-prod-ns \
--agent-namespace secure-agents \
--pull-secret /path/to/pull-secret.json \
--release-image quay.io/openshift-release-dev/ocp-release:4.18.0-multi \
--base-domain secure.financial.internal \
--image-content-sources /path/to/image-content-sources.yaml \
--additional-trust-bundle /path/to/ca-bundle.pem \
--fips \
--render
```
## See Also
- Agent-based OpenShift Installation Documentation
- HyperShift Agent Provider Documentation
- OpenShift Disconnected Installation Guide
- Agent-based Installer Documentation

569
skills/hcp-create-aws/SKILL.md Normal file
View File

@@ -0,0 +1,569 @@
---
name: HyperShift AWS Provider
description: Use this skill when you need to deploy HyperShift clusters on AWS infrastructure with proper STS credentials, IAM roles, and VPC configuration
---
# 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:**
```bash
--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:**
```bash
--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:**
```bash
--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:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
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](https://hypershift.openshift.io/aws-setup/)
- [AWS IAM Roles for HyperShift](https://hypershift.openshift.io/aws-setup/#_prerequisites)
- [AWS CLI Configuration Guide](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html)
- [OpenShift on AWS Best Practices](https://docs.openshift.com/container-platform/latest/installing/installing_aws/)

130
skills/hcp-create-azure/SKILL.md Normal file
View File

@@ -0,0 +1,130 @@
---
name: HyperShift Azure Provider
description: Use this skill when you need to deploy HyperShift clusters on Microsoft Azure with proper identity configuration and resource management
---
# HyperShift Azure Provider
This skill provides implementation guidance for creating HyperShift clusters on Azure, focusing on self-managed control plane configuration, resource group management, and Azure identity integration.
## When to Use This Skill
This skill is automatically invoked by the `/hcp:generate azure` command to guide the Azure provider cluster creation process.
## Prerequisites
- Azure CLI configured with appropriate credentials
- Azure subscription with sufficient quotas
- HyperShift operator installed and configured
- Pull secret for accessing OpenShift images
## Azure Provider Overview
### Azure Provider Peculiarities
- **Self-managed control plane only:** For ARO HCP use ARO CLI instead
- **Resource groups:** Auto-created during cluster creation
- **Limited region availability:** Not all Azure regions support all features
- **Azure identity required:** Service principal or managed identity configuration
- **Virtual network integration:** Requires proper VNet configuration
- **Control plane runs on Azure VMs:** Managed by HyperShift operator
### Identity Configuration Options
Choose one of three identity methods:
1. **Managed + Data Plane Identities:** Use `--managed-identities-file` AND `--data-plane-identities-file`
2. **Workload Identities:** Use `--workload-identities-file`
3. **OIDC Integration:** Use `--oidc-issuer-url`
## Implementation Steps
### Step 1: Parse Environment Requirements
**Environment Detection:**
- **Development:** "dev", "testing", "demo" → Standard_D4s_v3, SingleReplica
- **Production:** "prod", "enterprise" → Standard_D8s_v3+, HighlyAvailable
### Step 2: Interactive Parameter Collection
**Required Parameters:**
1. **Cluster Name & Location**
```
🔹 **Cluster Name**: What would you like to name your cluster?
🔹 **Azure Location**: Which Azure region? [default: eastus]
```
2. **Identity Configuration Method**
```
🔹 **Identity Method**: Choose Azure identity configuration:
1. Managed + Data Plane Identities (recommended)
2. Workload Identities
3. OIDC Integration
```
3. **Resource Group Configuration**
```
🔹 **Resource Group**: Name for the resource group?
[default: {cluster-name}-rg]
```
### Step 3: Generate Command
**Development Configuration:**
```bash
hypershift create cluster azure \
--name dev-cluster \
--namespace dev-cluster-ns \
--location eastus \
--pull-secret /path/to/pull-secret.json \
--release-image quay.io/openshift-release-dev/ocp-release:4.18.0-multi \
--resource-group-name dev-cluster-rg \
--base-domain example.com \
--managed-identities-file /path/to/managed-identities.json \
--data-plane-identities-file /path/to/data-plane-identities.json
```
**Production Configuration:**
```bash
hypershift create cluster azure \
--name production-cluster \
--namespace production-cluster-ns \
--location eastus \
--pull-secret /path/to/pull-secret.json \
--release-image quay.io/openshift-release-dev/ocp-release:4.18.0-multi \
--resource-group-name production-cluster-rg \
--base-domain clusters.company.com \
--managed-identities-file /path/to/managed-identities.json \
--data-plane-identities-file /path/to/data-plane-identities.json \
--control-plane-availability-policy HighlyAvailable
```
## Error Handling
### Identity Configuration Issues
```
Azure identity files not found or invalid.
Required files for managed identity method:
1. managed-identities.json
2. data-plane-identities.json
Generate using Azure CLI:
az identity create --name hypershift-managed-identity
```
### Resource Group Conflicts
```
Resource group "cluster-rg" already exists.
Options:
1. Use existing resource group (ensure proper permissions)
2. Choose different name
3. Delete existing resource group (if safe)
```
## See Also
- [HyperShift Azure Provider Documentation](https://hypershift.openshift.io/how-to/azure/)
- [Azure Resource Manager Documentation](https://docs.microsoft.com/en-us/azure/azure-resource-manager/)

595
skills/hcp-create-kubevirt/SKILL.md Normal file
View File

@@ -0,0 +1,595 @@
---
name: HyperShift KubeVirt Provider
description: Use this skill when you need to deploy HyperShift clusters on existing Kubernetes clusters using KubeVirt virtualization
---
# HyperShift KubeVirt Provider
This skill provides implementation guidance for creating HyperShift clusters using the KubeVirt provider, which runs on existing Kubernetes clusters with special attention to network conflict prevention and virtual machine management.
## When to Use This Skill
This skill is automatically invoked by the `/hcp:generate kubevirt` command to guide the KubeVirt provider cluster creation process.
## Prerequisites
- Kubernetes cluster with KubeVirt installed and configured
- Sufficient compute resources on the host cluster
- Storage classes configured for VM disks
- HyperShift operator installed
- Pull secret for accessing OpenShift images
## KubeVirt Provider Overview
### KubeVirt Provider Peculiarities
- **Runs on existing Kubernetes cluster:** Host cluster provides compute resources
- **CRITICAL Network Isolation:** Management cluster network cannot conflict with HostedCluster network
- **Storage Requirements:** Requires storage classes for VM disks and persistent volumes
- **Virtual Machine Templates:** Uses VM-based nodes instead of bare metal
- **IPv6 Support:** Full IPv6 support available
- **Disconnected Capable:** Can run in airgapped environments
- **Resource Planning:** Requires sufficient compute resources on host cluster
### Network Conflict Prevention (CRITICAL)
The most important aspect of KubeVirt clusters is preventing network conflicts:
- **Service/Cluster/Machine CIDRs must not overlap with management cluster**
- **Default CIDRs are designed to avoid common management cluster ranges**
- **Always check management cluster CIDRs before setting HostedCluster CIDRs**
**Common management cluster ranges to avoid:**
- 10.128.0.0/14 (common OCP default)
- 10.0.0.0/16 (common private range)
- 192.168.0.0/16 (common private range)
## Implementation Steps
### Step 1: Analyze Cluster Description
Parse the natural language description for KubeVirt-specific requirements:
**Environment Type Detection:**
- **Development**: "dev", "development", "testing", "lab", "demo"
- **Production**: "prod", "production", "critical", "enterprise"
- **Disconnected**: "airgapped", "disconnected", "offline", "air-gapped"
**Resource Indicators:**
- **High Performance**: "performance", "fast", "high-compute", "intensive"
- **Standard**: Default moderate configuration
- **Minimal**: "small", "minimal", "basic", "edge"
**Network Requirements:**
- **IPv6**: "ipv6", "dual-stack", "ipv6-only"
- **Isolated**: "isolated", "private", "secure"
**Storage Requirements:**
- **Local Storage**: "local", "local storage", "hostpath"
- **Replicated**: "replicated", "distributed", "ceph", "longhorn"
### Step 2: Management Cluster Network Discovery
**CRITICAL FIRST STEP:** Always check management cluster networks to prevent conflicts.
**Prompt for management cluster information:**
```
🔹 **Management Cluster Networks**: To avoid conflicts, please run this command on your management cluster:
`oc get network cluster -o yaml`
From the output, what are the serviceNetwork and clusterNetwork CIDRs?
- serviceNetwork CIDR: [e.g., 172.30.0.0/16]
- clusterNetwork CIDR: [e.g., 10.128.0.0/14]
- [Press Enter if you don't know - I'll use safe defaults]
```
**If user provides management cluster CIDRs:**
- Validate they don't overlap with our proposed defaults
- Adjust HostedCluster CIDRs if conflicts detected
- Document the conflict avoidance in the output
### Step 3: Apply KubeVirt Provider Defaults
**Required Parameters:**
- `--memory`: Memory allocation for VMs (default: 8Gi)
- `--cores`: CPU cores for VMs (default: 2)
- `--pull-secret`: Path to pull secret file
- `--release-image`: OpenShift release image
**IPv4 Non-Conflicting Defaults:**
- `--service-cidr`: 172.30.0.0/16 (avoids common 10.x ranges)
- `--cluster-cidr`: 10.132.0.0/14 (avoids common 10.128.x range)
- `--machine-cidr`: 192.168.126.0/24 (avoids common 192.168.1.x range)
**IPv6 Non-Conflicting Defaults:**
- `--service-cidr`: fd02::/112
- `--cluster-cidr`: fd01::/48
- `--machine-cidr`: fd03::/64
**Smart Defaults by Environment:**
**Development Environment:**
```bash
--memory 8Gi
--cores 2
--control-plane-availability-policy SingleReplica
--node-pool-replicas 2
```
**Production Environment:**
```bash
--memory 16Gi
--cores 4
--control-plane-availability-policy HighlyAvailable
--node-pool-replicas 3
--auto-repair true
```
**High-Performance Environment:**
```bash
--memory 32Gi
--cores 8
--control-plane-availability-policy HighlyAvailable
--node-pool-replicas 5
```
### Step 4: 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 VM and resource naming
- Example: dev-cluster, prod-app, test-env
```
2. **Management Cluster Network Check** (see Step 2)
3. **VM Resource Configuration**
```
🔹 **VM Memory**: How much memory should each VM have?
- Development: 8Gi (minimum recommended)
- Production: 16Gi+ (better performance)
- High-performance: 32Gi+ (intensive workloads)
- [Press Enter for default based on environment]
```
```
🔹 **VM CPU Cores**: How many CPU cores should each VM have?
- Development: 2 cores (minimum recommended)
- Production: 4+ cores (better performance)
- High-performance: 8+ cores (intensive workloads)
- [Press Enter for default based on environment]
```
4. **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
```
5. **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:**
6. **IPv6 Support** (if detected)
```
🔹 **IPv6 Configuration**: Detected IPv6 requirement. Configure network stack:
- ipv4: IPv4 only (default)
- ipv6: IPv6 only
- dual: Dual-stack (IPv4 + IPv6)
- [Press Enter for default: ipv4]
```
7. **Storage Class**
```
🔹 **Storage Class**: Which storage class should be used for VM disks?
- List available storage classes on your cluster:
kubectl get storageclass
- [Press Enter to use cluster default]
```
8. **Node Count**
```
🔹 **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]
```
### Step 5: Network CIDR Validation
**If management cluster CIDRs provided, validate conflicts:**
```
## Network Conflict Check
Management cluster networks:
- Service Network: 172.30.0.0/16
- Cluster Network: 10.128.0.0/14
HostedCluster networks (checking for conflicts):
✅ Service CIDR: 172.30.0.0/16 (safe - different range)
❌ Cluster CIDR: 10.132.0.0/14 (CONFLICT with 10.128.0.0/14)
✅ Machine CIDR: 192.168.126.0/24 (safe)
Adjusting Cluster CIDR to avoid conflict:
New Cluster CIDR: 10.140.0.0/14
```
**If no management cluster info provided, use safe defaults:**
```
## Network Configuration (Safe Defaults)
Using safe default CIDRs that avoid common management cluster ranges:
- Service CIDR: 172.30.0.0/16 (avoids 10.x ranges)
- Cluster CIDR: 10.132.0.0/14 (avoids common 10.128.x)
- Machine CIDR: 192.168.126.0/24 (avoids common 192.168.1.x)
```
### Step 6: Generate Command
**Basic KubeVirt Cluster Command:**
```bash
hypershift create cluster kubevirt \
--name <cluster-name> \
--namespace <cluster-name>-ns \
--memory <memory> \
--cores <cores> \
--pull-secret <pull-secret-path> \
--release-image <release-image> \
--service-cidr <service-cidr> \
--cluster-cidr <cluster-cidr> \
--machine-cidr <machine-cidr>
```
**Development Configuration Example:**
```bash
hypershift create cluster kubevirt \
--name dev-cluster \
--namespace dev-cluster-ns \
--memory 8Gi \
--cores 2 \
--pull-secret /path/to/pull-secret.json \
--release-image quay.io/openshift-release-dev/ocp-release:4.18.0-multi \
--service-cidr 172.30.0.0/16 \
--cluster-cidr 10.132.0.0/14 \
--machine-cidr 192.168.126.0/24 \
--control-plane-availability-policy SingleReplica \
--node-pool-replicas 2
```
**Production Configuration Example:**
```bash
hypershift create cluster kubevirt \
--name production-cluster \
--namespace production-cluster-ns \
--memory 16Gi \
--cores 4 \
--pull-secret /path/to/pull-secret.json \
--release-image quay.io/openshift-release-dev/ocp-release:4.18.0-multi \
--service-cidr 172.30.0.0/16 \
--cluster-cidr 10.132.0.0/14 \
--machine-cidr 192.168.126.0/24 \
--control-plane-availability-policy HighlyAvailable \
--node-pool-replicas 3 \
--auto-repair
```
**IPv6 Configuration Example:**
```bash
hypershift create cluster kubevirt \
--name ipv6-cluster \
--namespace ipv6-cluster-ns \
--memory 16Gi \
--cores 4 \
--pull-secret /path/to/pull-secret.json \
--release-image quay.io/openshift-release-dev/ocp-release:4.18.0-multi \
--service-cidr fd02::/112 \
--cluster-cidr fd01::/48 \
--machine-cidr fd03::/64
```
**Disconnected Configuration Example:**
```bash
hypershift create cluster kubevirt \
--name airgapped-cluster \
--namespace airgapped-cluster-ns \
--memory 16Gi \
--cores 4 \
--pull-secret /path/to/pull-secret.json \
--release-image quay.io/openshift-release-dev/ocp-release:4.18.0-multi \
--service-cidr 172.30.0.0/16 \
--cluster-cidr 10.132.0.0/14 \
--machine-cidr 192.168.126.0/24 \
--image-content-sources /path/to/image-content-sources.yaml \
--additional-trust-bundle /path/to/ca-bundle.pem \
--render
```
### Step 7: Pre-Flight Validation
**Provide validation commands:**
```
## Pre-Flight Checks
Before creating the cluster, verify your KubeVirt setup:
1. **KubeVirt Status:**
kubectl get kubevirt -A
2. **Available Storage Classes:**
kubectl get storageclass
3. **Node Resources:**
kubectl top nodes
4. **Available Memory/CPU:**
kubectl describe nodes | grep -E "(Allocatable|Allocated)"
5. **Network Configuration:**
oc get network cluster -o yaml
6. **Required Compute Resources:**
- Control Plane VMs: 3 x (<cores> cores, <memory> RAM)
- Worker VMs: <replica-count> x (<cores> cores, <memory> RAM)
- Total Required: <total-cores> cores, <total-memory> RAM
```
### Step 8: Post-Generation Instructions
**For Disconnected Environments:**
```
## Post-Creation Configuration (Disconnected)
After running the command above (with --render), you'll need to modify the generated manifests:
1. **Add ImageContentSources to HostedCluster:**
```yaml
spec:
imageContentSources:
- source: quay.io/openshift-release-dev/ocp-v4.0-art-dev
mirrors:
- registry.example.com:5000/openshift/release
- source: quay.io/openshift-release-dev/ocp-release
mirrors:
- registry.example.com:5000/openshift/release-images
```
2. **Apply the manifests:**
```bash
kubectl apply -f <rendered-manifest-files>
```
**For All Environments:**
```
## Next Steps
1. **Monitor cluster creation:**
kubectl get hostedcluster -n <cluster-namespace>
kubectl get nodepool -n <cluster-namespace>
2. **Check VM creation:**
kubectl get vmi -A
3. **Monitor VM startup:**
kubectl get vmi -A -w
4. **Access cluster when ready:**
hypershift create kubeconfig --name <cluster-name> --namespace <cluster-namespace>
export KUBECONFIG=<cluster-name>-kubeconfig
oc get nodes
5. **Verify network isolation:**
oc get network cluster -o yaml # Check HostedCluster networks
```
## Error Handling
### Network CIDR Conflicts
**Scenario:** HostedCluster CIDRs conflict with management cluster.
**Action:**
```
CIDR conflict detected:
- Management cluster: 10.128.0.0/14
- HostedCluster (proposed): 10.132.0.0/14
- Overlap detected!
Suggested alternative CIDRs:
- Service CIDR: 172.30.0.0/16 (safe)
- Cluster CIDR: 10.140.0.0/14 (avoids conflict)
- Machine CIDR: 192.168.126.0/24 (safe)
Update command with new CIDRs? [y/N]
```
### Insufficient Resources
**Scenario:** Host cluster lacks sufficient resources for VMs.
**Action:**
```
Insufficient resources on host cluster:
Required:
- CPU: 24 cores (3 control plane + 6 workers @ 4 cores each)
- Memory: 144Gi (3 control plane + 6 workers @ 16Gi each)
Available:
- CPU: 16 cores
- Memory: 96Gi
Suggestions:
1. Reduce VM resources (--memory 8Gi --cores 2)
2. Reduce worker count (--node-pool-replicas 2)
3. Use SingleReplica control plane
4. Add more nodes to host cluster
```
### Storage Class Issues
**Scenario:** No suitable storage class available.
**Action:**
```
No default storage class found. Available storage classes:
NAME PROVISIONER
local-path rancher.io/local-path
ceph-rbd kubernetes.io/rbd
Specify storage class in NodePool configuration:
storageClassName: local-path
Or set a default storage class:
kubectl patch storageclass local-path -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'
```
### KubeVirt Not Ready
**Scenario:** KubeVirt is not properly installed or configured.
**Action:**
```
KubeVirt is not ready:
Check KubeVirt status:
kubectl get kubevirt -A
kubectl get pods -n kubevirt
Install KubeVirt if missing:
kubectl apply -f https://github.com/kubevirt/kubevirt/releases/download/v1.0.0/kubevirt-operator.yaml
kubectl apply -f https://github.com/kubevirt/kubevirt/releases/download/v1.0.0/kubevirt-cr.yaml
Verify installation:
kubectl wait kv kubevirt --for condition=Available -n kubevirt --timeout=300s
```
## Best Practices
### Resource Planning
1. **Right-size VMs:** Don't over-provision for development environments
2. **Monitor resource usage:** Keep track of host cluster resource consumption
3. **Plan for growth:** Ensure host cluster can accommodate scaling
4. **Storage planning:** Use appropriate storage classes for performance needs
### Network Management
1. **Always check management cluster CIDRs:** Prevent network conflicts
2. **Document network design:** Keep records of CIDR allocations
3. **Plan for multiple clusters:** Reserve CIDR ranges for future clusters
4. **IPv6 considerations:** Plan dual-stack if needed
### Security
1. **Network isolation:** Ensure proper network segmentation
2. **Storage security:** Use encrypted storage where required
3. **Image security:** Use trusted image registries
4. **RBAC:** Implement proper role-based access control
### Performance
1. **VM sizing:** Balance resource allocation with performance needs
2. **Storage performance:** Use high-performance storage for production
3. **Network performance:** Consider SR-IOV for high-throughput workloads
4. **CPU pinning:** Consider CPU pinning for performance-critical workloads
## Anti-Patterns to Avoid
❌ **Ignoring network conflicts**
```
Using default CIDRs without checking management cluster
```
✅ Always check management cluster networks first
❌ **Under-provisioning VMs**
```
--memory 4Gi --cores 1 # Too small for OpenShift
```
✅ Use minimum 8Gi memory and 2 cores
❌ **Over-provisioning for development**
```
--memory 64Gi --cores 16 --node-pool-replicas 10 # Excessive for dev
```
✅ Use appropriate sizing for environment
❌ **Conflicting CIDR ranges**
```
Using 10.128.0.0/14 when management cluster uses 10.128.0.0/14
```
✅ Use non-overlapping CIDR ranges
## Example Workflows
### Development Lab
```
Input: "small kubevirt cluster for development testing"
Management cluster check:
- Service: 172.30.0.0/16
- Cluster: 10.128.0.0/14
Analysis:
- Environment: Development
- Scale: Small
- Network: Avoid 10.128.x range
Generated Command:
hypershift create cluster kubevirt \
--name dev-lab \
--namespace dev-lab-ns \
--memory 8Gi \
--cores 2 \
--service-cidr 172.31.0.0/16 \
--cluster-cidr 10.132.0.0/14 \
--machine-cidr 192.168.126.0/24 \
--control-plane-availability-policy SingleReplica \
--node-pool-replicas 2
```
### Production Environment
```
Input: "high-performance kubevirt cluster for production workloads"
Analysis:
- Environment: Production
- Performance: High priority
- Availability: HA required
Generated Command:
hypershift create cluster kubevirt \
--name prod-workloads \
--namespace prod-workloads-ns \
--memory 32Gi \
--cores 8 \
--service-cidr 172.30.0.0/16 \
--cluster-cidr 10.132.0.0/14 \
--machine-cidr 192.168.126.0/24 \
--control-plane-availability-policy HighlyAvailable \
--node-pool-replicas 5 \
--auto-repair
```
## See Also
- [KubeVirt Documentation](https://kubevirt.io/user-guide/)
- [HyperShift KubeVirt Provider Guide](https://hypershift.openshift.io/how-to/kubevirt/)
- [OpenShift Virtualization](https://docs.openshift.com/container-platform/latest/virt/about-virt.html)
- [Network Configuration Best Practices](https://docs.openshift.com/container-platform/latest/networking/understanding-networking.html)

99
skills/hcp-create-openstack/SKILL.md Normal file
View File

@@ -0,0 +1,99 @@
---
name: HyperShift OpenStack Provider
description: Use this skill when you need to deploy HyperShift clusters on OpenStack infrastructure with proper flavor selection and network configuration
---
# HyperShift OpenStack Provider
This skill provides implementation guidance for creating HyperShift clusters on OpenStack, handling OpenStack-specific requirements including credentials, networking, and flavor selection.
## When to Use This Skill
This skill is automatically invoked by the `/hcp:generate openstack` command to guide the OpenStack provider cluster creation process.
## Prerequisites
- OpenStack CLI configured with appropriate credentials
- OpenStack project with sufficient quotas
- External network configured for floating IPs
- HyperShift operator installed and configured
## OpenStack Provider Overview
### OpenStack Provider Peculiarities
- **Requires OpenStack credentials:** Must have valid clouds.yaml or environment variables
- **Floating IP networks needed:** External network access for cluster API
- **Flavor selection critical:** Instance flavors affect performance and cost
- **Custom images may be required:** RHCOS images for worker nodes
- **Network topology affects routing:** Proper network configuration essential
## Implementation Steps
### Step 1: Interactive Parameter Collection
**Required Parameters:**
1. **OpenStack Credentials**
```
🔹 **OpenStack Credentials**: Path to OpenStack credentials file?
- Usually clouds.yaml format
- Example: /home/user/.config/openstack/clouds.yaml
```
2. **External Network**
```
🔹 **External Network ID**: OpenStack external network UUID?
- Required for floating IP allocation
- Find with: openstack network list --external
```
3. **Flavor Selection**
```
🔹 **Node Flavor**: Choose instance flavor:
- m1.large (4 vCPU, 8GB RAM) - Standard workloads
- m1.xlarge (8 vCPU, 16GB RAM) - Performance workloads
- [default: m1.large]
```
### Step 2: Generate Command
**Standard Configuration:**
```bash
hypershift create cluster openstack \
--name openstack-cluster \
--namespace openstack-cluster-ns \
--openstack-credentials-file /path/to/clouds.yaml \
--openstack-external-network-id <external-network-uuid> \
--openstack-node-flavor m1.large \
--base-domain example.com \
--pull-secret /path/to/pull-secret.json \
--release-image quay.io/openshift-release-dev/ocp-release:4.18.0-multi
```
## Error Handling
### External Network Not Found
```
External network with ID "<uuid>" not found.
List available external networks:
openstack network list --external
Ensure network has proper routing configuration.
```
### Flavor Not Available
```
Flavor "m1.large" not available in this OpenStack deployment.
List available flavors:
openstack flavor list
Choose appropriate flavor for your workload requirements.
```
## See Also
- [OpenStack Documentation](https://docs.openstack.org/)
- [HyperShift OpenStack Provider](https://hypershift.openshift.io/how-to/openstack/)

146
skills/hcp-create-powervs/SKILL.md Normal file
View File

@@ -0,0 +1,146 @@
---
name: HyperShift PowerVS Provider
description: Use this skill when you need to deploy HyperShift clusters on IBM Cloud PowerVS with proper processor configuration and resource management
---
# HyperShift PowerVS Provider
This skill provides implementation guidance for creating HyperShift clusters on IBM Cloud PowerVS, handling PowerVS-specific requirements including IBM Cloud API keys, processor types, and resource group management.
## When to Use This Skill
This skill is automatically invoked by the `/hcp:generate powervs` command to guide the PowerVS provider cluster creation process.
## Prerequisites
- IBM Cloud CLI configured with API key
- PowerVS service instance configured
- IBM Cloud resource group access
- HyperShift operator installed and configured
## PowerVS Provider Overview
### PowerVS Provider Peculiarities
- **IBM Cloud specific:** Requires IBM Cloud API key and resource group
- **Different regions have different capabilities:** Service availability varies by region
- **Limited instance types:** Fewer processor types compared to other clouds
- **Network setup complex:** Requires careful network planning
- **Processor type selection:** Shared, dedicated, or capped options
## Implementation Steps
### Step 1: Interactive Parameter Collection
**Required Parameters:**
1. **IBM Cloud Authentication**
```
🔹 **IBM Cloud API Key**: Configure IBM Cloud authentication
- Set IBMCLOUD_API_KEY environment variable, OR
- Provide IBMCLOUD_CREDENTIALS file path
```
2. **Resource Group**
```
🔹 **Resource Group**: IBM Cloud resource group name?
- Must exist in your IBM Cloud account
- Example: default, hypershift-rg
```
3. **Region Configuration**
```
🔹 **Region**: IBM Cloud region?
[default: us-south]
🔹 **Zone**: Availability zone?
[default: us-south]
```
4. **Processor Configuration**
```
🔹 **Memory**: Memory allocation per instance?
[default: 32GB]
🔹 **Processors**: Number of processors?
[default: 0.5]
🔹 **Processor Type**: Processor type?
- shared (default) - Shared processor pool
- dedicated - Dedicated processors
- capped - Capped shared processors
```
### Step 2: Generate Command
**Standard Configuration:**
```bash
hypershift create cluster powervs \
--name powervs-cluster \
--namespace powervs-cluster-ns \
--region us-south \
--zone us-south \
--resource-group default \
--base-domain example.com \
--pull-secret /path/to/pull-secret.json \
--release-image quay.io/openshift-release-dev/ocp-release:4.18.0-multi \
--memory 32GB \
--processors 0.5 \
--proc-type shared \
--sys-type s922 \
--vpc-region us-south
```
**High-Performance Configuration:**
```bash
hypershift create cluster powervs \
--name powervs-prod \
--namespace powervs-prod-ns \
--region us-south \
--zone us-south \
--resource-group production-rg \
--base-domain clusters.company.com \
--pull-secret /path/to/pull-secret.json \
--release-image quay.io/openshift-release-dev/ocp-release:4.18.0-multi \
--memory 64GB \
--processors 2.0 \
--proc-type dedicated \
--sys-type s922 \
--vpc-region us-south
```
## Error Handling
### API Key Issues
```
IBM Cloud API key not configured or invalid.
Configure authentication:
export IBMCLOUD_API_KEY="your-api-key"
Or verify existing configuration:
ibmcloud auth list
```
### Resource Group Not Found
```
Resource group "hypershift-rg" not found.
List available resource groups:
ibmcloud resource groups
Create new resource group:
ibmcloud resource group-create hypershift-rg
```
### Region/Zone Issues
```
Zone "us-south-3" not available for PowerVS.
Available zones in us-south:
ibmcloud pi service-list
Choose appropriate zone for your region.
```
## See Also
- [IBM Cloud PowerVS Documentation](https://cloud.ibm.com/docs/power-iaas)
- [HyperShift PowerVS Provider](https://hypershift.openshift.io/how-to/powervs/)