diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index e2908921..5cc0a60b 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -68,6 +68,11 @@ "name": "must-gather", "source": "./plugins/must-gather", "description": "A plugin to analyze and report on must-gather data" + }, + { + "name": "hcp", + "source": "./plugins/hcp", + "description": "Generate HyperShift cluster creation commands via hcp CLI from natural language descriptions" } ] } \ No newline at end of file diff --git a/PLUGINS.md b/PLUGINS.md index f51f1306..44647934 100644 --- a/PLUGINS.md +++ b/PLUGINS.md @@ -6,6 +6,7 @@ This document lists all available Claude Code plugins and their commands in the - [Ci](#ci-plugin) - [Doc](#doc-plugin) - [Git](#git-plugin) +- [Hcp](#hcp-plugin) - [Hello World](#hello-world-plugin) - [Jira](#jira-plugin) - [Must Gather](#must-gather-plugin) @@ -60,6 +61,15 @@ Git workflow automation and utilities See [plugins/git/README.md](plugins/git/README.md) for detailed documentation. +### Hcp Plugin + +Generate HyperShift cluster creation commands via hcp CLI from natural language descriptions + +**Commands:** +- **`/hcp:generate` ` `** - Generate ready-to-execute hypershift cluster creation commands from natural language descriptions + +See [plugins/hcp/README.md](plugins/hcp/README.md) for detailed documentation. + ### Hello World Plugin A hello world plugin diff --git a/docs/data.json b/docs/data.json index b84b267b..64ce6c9e 100644 --- a/docs/data.json +++ b/docs/data.json @@ -445,6 +445,52 @@ } ], "has_readme": true + }, + { + "name": "hcp", + "description": "Generate HyperShift cluster creation commands via hcp CLI from natural language descriptions", + "version": "0.0.1", + "commands": [ + { + "name": "generate", + "description": "Generate ready-to-execute hypershift cluster creation commands from natural language descriptions", + "synopsis": "/hcp:generate ", + "argument_hint": " " + } + ], + "skills": [ + { + "name": "HyperShift Agent Provider", + "id": "hcp-create-agent", + "description": "Use this skill when you need to deploy HyperShift clusters on bare metal, edge environments, or disconnected infrastructures using pre-provisioned agents" + }, + { + "name": "HyperShift AWS Provider", + "id": "hcp-create-aws", + "description": "Use this skill when you need to deploy HyperShift clusters on AWS infrastructure with proper STS credentials, IAM roles, and VPC configuration" + }, + { + "name": "HyperShift Azure Provider", + "id": "hcp-create-azure", + "description": "Use this skill when you need to deploy HyperShift clusters on Microsoft Azure with proper identity configuration and resource management" + }, + { + "name": "HyperShift KubeVirt Provider", + "id": "hcp-create-kubevirt", + "description": "Use this skill when you need to deploy HyperShift clusters on existing Kubernetes clusters using KubeVirt virtualization" + }, + { + "name": "HyperShift OpenStack Provider", + "id": "hcp-create-openstack", + "description": "Use this skill when you need to deploy HyperShift clusters on OpenStack infrastructure with proper flavor selection and network configuration" + }, + { + "name": "HyperShift PowerVS Provider", + "id": "hcp-create-powervs", + "description": "Use this skill when you need to deploy HyperShift clusters on IBM Cloud PowerVS with proper processor configuration and resource management" + } + ], + "has_readme": true } ] } \ No newline at end of file diff --git a/plugins/hcp/.claude-plugin/plugin.json b/plugins/hcp/.claude-plugin/plugin.json new file mode 100644 index 00000000..c294d864 --- /dev/null +++ b/plugins/hcp/.claude-plugin/plugin.json @@ -0,0 +1,8 @@ +{ + "name": "hcp", + "description": "Generate HyperShift cluster creation commands via hcp CLI from natural language descriptions", + "version": "0.0.1", + "author": { + "name": "github.com/openshift-eng" + } +} \ No newline at end of file diff --git a/plugins/hcp/README.md b/plugins/hcp/README.md new file mode 100644 index 00000000..9730a3dc --- /dev/null +++ b/plugins/hcp/README.md @@ -0,0 +1,142 @@ +# HCP Plugin + +The HCP plugin generates intelligent `hypershift create cluster` commands from natural language descriptions across multiple cloud providers and platforms. + +## Overview + +This plugin translates natural language descriptions into precise, ready-to-execute `hypershift create cluster` commands, applying provider-specific best practices and handling complex parameter validation automatically. The plugin **generates commands for you to run** - it does not provision clusters directly. + +## Commands + +### `/hcp:generate` + +Generate ready-to-execute hypershift cluster creation commands from natural language descriptions. + +**Usage:** +``` +/hcp:generate +``` + +**Supported Providers:** +- `aws` - Amazon Web Services +- `azure` - Microsoft Azure (self-managed control plane) +- `kubevirt` - KubeVirt on existing Kubernetes clusters +- `openstack` - OpenStack clouds +- `powervs` - IBM Cloud PowerVS +- `agent` - Bare metal and edge deployments + +**Examples:** +```bash +# AWS development cluster +/hcp:generate aws "development cluster for testing new features" + +# High-availability KubeVirt cluster +/hcp:generate kubevirt "production cluster with high availability" + +# Cost-optimized Azure cluster +/hcp:generate azure "small cluster for dev work, minimize costs" + +# Disconnected bare metal cluster +/hcp:generate agent "airgapped cluster for secure environment" +``` + +## Key Features + +- **Multi-Provider Support**: Works with AWS, Azure, KubeVirt, OpenStack, PowerVS, and Agent providers +- **Smart Analysis**: Extracts requirements from natural language descriptions +- **Interactive Prompts**: Guides users through provider-specific configurations +- **Best Practices**: Applies provider-specific defaults and optimizations +- **Security Validation**: Ensures safe parameter handling and credential management +- **Network Conflict Prevention**: Especially critical for KubeVirt deployments + +## Provider-Specific Skills + +The plugin uses specialized skills for each provider: + +- **`hcp-create-aws`**: AWS-specific guidance including STS credentials, IAM roles, and VPC configuration +- **`hcp-create-azure`**: Azure identity configuration, resource groups, and region management +- **`hcp-create-kubevirt`**: Network conflict prevention, VM sizing, and storage class management +- **`hcp-create-openstack`**: OpenStack credentials, external networks, and flavor selection +- **`hcp-create-powervs`**: IBM Cloud integration, processor types, and resource group management +- **`hcp-create-agent`**: Bare metal deployment, agent management, and disconnected environments + +## Installation + +### From AI Helpers Marketplace + +```bash +# Add the marketplace +/plugin marketplace add openshift-eng/ai-helpers + +# Install the HCP plugin +/plugin install hcp@ai-helpers + +# Use the command +/hcp:generate aws "development cluster for API testing" +``` + +### Manual Installation (Cursor) + +```bash +# Clone the repository +mkdir -p ~/.cursor/commands +git clone git@github.com:openshift-eng/ai-helpers.git +ln -s ai-helpers ~/.cursor/commands/ai-helpers +``` + +## Common Use Cases + +### Development Environments +- Quick cluster setup for testing +- Cost-optimized configurations +- Single replica control planes + +### Production Deployments +- High-availability configurations +- Multi-zone deployments +- Auto-repair and monitoring enabled + +### Edge Computing +- Minimal resource footprints +- Disconnected/airgapped environments +- Agent-based deployments + +### Special Requirements +- FIPS compliance configurations +- IPv6 and dual-stack networking +- Custom storage and compute requirements + +## Architecture + +The plugin follows a modular architecture with: + +1. **Main Command**: `/hcp:generate` acts as an orchestrator +2. **Provider Skills**: Specialized implementation guidance for each provider +3. **Interactive Workflows**: Guided parameter collection and validation +4. **Smart Defaults**: Environment-specific best practices + +This design ensures: +- **Single Source of Truth**: Each provider's knowledge lives in one place +- **Extensibility**: Easy to add new providers or update existing ones +- **Maintainability**: Clear separation of concerns between providers + +## Contributing + +To add support for a new provider: + +1. Create a new skill directory: `plugins/hcp/skills/hcp-create-/` +2. Implement the `SKILL.md` file following the established pattern +3. Update the main command to invoke the new skill +4. Test the implementation and add examples + +See existing skills as reference implementations. + +## Support + +- **Issues**: [GitHub Issues](https://github.com/openshift-eng/ai-helpers/issues) +- **Documentation**: [HyperShift Documentation](https://hypershift.openshift.io/) +- **Skills**: View individual skill files in `plugins/hcp/skills/` + +## License + +This plugin is part of the AI Helpers project and follows the same licensing terms. \ No newline at end of file diff --git a/plugins/hcp/commands/generate.md b/plugins/hcp/commands/generate.md new file mode 100644 index 00000000..12dcd9f4 --- /dev/null +++ b/plugins/hcp/commands/generate.md @@ -0,0 +1,357 @@ +--- +description: Generate ready-to-execute hypershift cluster creation commands from natural language descriptions +argument-hint: +--- + +## Name +hcp:generate + +## Synopsis +``` +/hcp:generate +``` + +## Description +The `hcp:generate` command translates natural language descriptions into precise, ready-to-execute `hypershift create cluster` commands. It supports multiple cloud providers and platforms, each with their specific requirements and best practices. + +**Important**: This command **generates commands for you to run** - it does not provision clusters directly. + +This command is particularly useful for: +- Generating complete, copy-paste-ready hypershift commands with proper parameters +- Applying provider-specific best practices and configurations automatically +- Handling complex parameter validation and smart defaults +- Providing interactive prompts for missing critical information +- Learning proper hypershift command syntax and options + +## Key Features + +- **Multi-Provider Support** - AWS, Azure, KubeVirt, OpenStack, PowerVS, and Agent providers +- **Smart Analysis** - Extracts platform, configuration, and requirements from natural language +- **Interactive Prompts** - Asks for missing critical information with helpful guidance +- **Provider Expertise** - Applies platform-specific best practices and configurations +- **Security Validation** - Ensures safe parameter handling and credential management +- **Namespace Management** - Implements best practices for cluster isolation + +## Implementation + +The `hcp:generate` command runs in multiple phases: + +### 🎯 Phase 1: Load Provider-Specific Implementation Guidance + +Invoke the appropriate skill based on provider using the Skill tool: + +- **Provider: `aws`** → Invoke `hcp-create-aws` skill + - Loads AWS-specific requirements and configurations + - Provides STS credentials handling + - Offers region and availability zone guidance + - Handles IAM roles and VPC configuration + +- **Provider: `azure`** → Invoke `hcp-create-azure` skill + - Loads Azure-specific requirements (self-managed control plane only) + - Provides resource group and location guidance + - Handles identity configuration options + - Manages virtual network integration + +- **Provider: `kubevirt`** → Invoke `hcp-create-kubevirt` skill + - Loads KubeVirt-specific network conflict prevention + - Provides virtual machine configuration guidance + - Handles storage class requirements + - Manages IPv4/IPv6 CIDR validation + +- **Provider: `openstack`** → Invoke `hcp-create-openstack` skill + - Loads OpenStack-specific requirements + - Provides floating IP network guidance + - Handles flavor selection and custom images + - Manages network topology configuration + +- **Provider: `powervs`** → Invoke `hcp-create-powervs` skill + - Loads PowerVS/IBM Cloud specific requirements + - Provides region and zone guidance + - Handles IBM Cloud API key configuration + - Manages processor and memory specifications + +- **Provider: `agent`** → Invoke `hcp-create-agent` skill + - Loads bare metal and edge deployment guidance + - Provides pre-provisioned agent requirements + - Handles manual network configuration + - Manages disconnected environment setup + +### 📝 Phase 2: Parse Arguments & Detect Context + +Parse command arguments: +- **Required:** `provider`, `cluster-description` +- Parse natural language description for: + - Environment type (development, production, disconnected) + - Special requirements (FIPS, architecture, storage) + - Resource constraints (cost-optimization, performance) + - Network requirements + +### ⚙️ Phase 3: Apply Provider-Specific Defaults and Validation + +**Universal requirements (applied to ALL clusters):** +- **Namespace strategy:** Generate unique namespace based on cluster name (`{cluster-name}-ns`) +- **Security validation:** Scan for credentials or sensitive data +- **Release image:** Always include `--release-image` with proper version + +**Provider-specific validation:** +- Network conflict prevention (especially KubeVirt) +- Credential requirements validation +- Region/zone availability checks +- Resource limit validation + +### 💬 Phase 4: Interactive Prompts (Provider-Guided) + +Each provider skill guides the collection of missing information: + +**Common prompts for all providers:** +- Cluster name (if not specified) +- Pull secret path +- OpenShift version/release image +- Base domain (where applicable) + +**Provider-specific prompts:** +- AWS: STS credentials, IAM role ARN, region selection +- Azure: Identity configuration method, resource group name +- KubeVirt: Management cluster network CIDRs, storage classes +- OpenStack: External network UUID, flavor selection +- PowerVS: IBM Cloud resource group, processor specifications +- Agent: Agent namespace, pre-provisioned agent details + +### 🔒 Phase 5: Security and Configuration Validation + +**Security checks:** +- Scan all inputs for credentials, API keys, or secrets +- Validate that sensitive information uses placeholder values +- Ensure proper credential file references + +**Configuration validation:** +- Verify required parameters are present +- Validate parameter combinations and dependencies +- Check for common misconfigurations + +### ✅ Phase 6: Generate Command + +Based on provider skill guidance: +- Construct complete `hypershift create cluster` command +- Apply smart defaults for optional parameters +- Include all required provider-specific flags +- Format command for copy-paste execution + +### 📤 Phase 7: Return Result + +Display to user: +- **Summary:** Brief description of what will be created +- **Generated Command:** Complete, executable command +- **Key Decisions:** Explanation of important choices made +- **Next Steps:** What to do after running the command +- **Provider-specific notes:** Any special considerations + +## Usage Examples + +1. **Create AWS development cluster**: + ``` + /hcp:generate aws "development cluster for testing new features" + ``` + → Invokes `hcp-create-aws` skill, prompts for AWS-specific details + +2. **Create production KubeVirt cluster**: + ``` + /hcp:generate kubevirt "production cluster with high availability" + ``` + → Invokes `hcp-create-kubevirt` skill, handles network conflict prevention + +3. **Create cost-optimized Azure cluster**: + ``` + /hcp:generate azure "small cluster for dev work, minimize costs" + ``` + → Invokes `hcp-create-azure` skill, applies cost optimization + +4. **Create disconnected agent cluster**: + ``` + /hcp:generate agent "airgapped cluster for secure environment" + ``` + → Invokes `hcp-create-agent` skill, handles disconnected requirements + +5. **Create FIPS-enabled OpenStack cluster**: + ``` + /hcp:generate openstack "production cluster with FIPS compliance" + ``` + → Invokes `hcp-create-openstack` skill, applies FIPS configuration + +6. **Create ARM-based PowerVS cluster**: + ``` + /hcp:generate powervs "arm64 cluster for multi-arch testing" + ``` + → Invokes `hcp-create-powervs` skill, handles ARM architecture + +## Arguments + +- **$1 – provider** *(required)* + Cloud provider or platform to use. + **Options:** `aws` | `azure` | `kubevirt` | `openstack` | `powervs` | `agent` + +- **$2 – cluster-description** *(required)* + Natural language description of the desired cluster. + Use quotes for multi-word descriptions: `"production cluster with HA"` + + **Description should include:** + - Environment type (development, production, testing) + - Special requirements (FIPS, architecture, storage) + - Resource preferences (cost-optimized, high-performance) + - Network requirements (disconnected, private) + +## Return Value + +- **Summary**: Brief description of the cluster that will be created +- **Generated Command**: Complete `hypershift create cluster` command +- **Key Decisions**: Explanation of choices made during generation +- **Next Steps**: Instructions for executing the command and post-creation tasks + +**Example output:** +``` +## Summary +Creating a development AWS hosted cluster with basic configuration. + +## Generated Command +```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 \ + --sts-creds /path/to/sts-creds.json \ + --role-arn arn:aws:iam::123456789:role/hypershift-role \ + --base-domain example.com \ + --release-image quay.io/openshift-release-dev/ocp-release:4.18.0-multi +``` + +## Key Decisions +- Used SingleReplica for development (cost-effective) +- Selected 2 zones for basic redundancy +- m5.large instances balance cost and performance for dev workloads +- **Unique namespace**: `dev-cluster-ns` for better isolation and disaster recovery + +## Next Steps +1. Ensure your pull secret file exists at the specified path +2. Verify AWS credentials are configured +3. Confirm STS credentials file is accessible +4. Run the command above to create your cluster +``` + +## Error Handling + +### Invalid Provider + +**Scenario:** User specifies unsupported provider. + +**Action:** +``` +Invalid provider "gcp". Supported providers: aws, azure, kubevirt, openstack, powervs, agent + +Did you mean "aws"? +``` + +### Missing Description + +**Scenario:** User doesn't provide cluster description. + +**Action:** +``` +Cluster description is required. Please describe what kind of cluster you want. + +Examples: +- "development cluster for testing" +- "production cluster with high availability" +- "cost-optimized cluster for demos" + +Usage: /hcp:generate aws "development cluster for testing" +``` + +### Ambiguous Requirements + +**Scenario:** Description is too vague or contradictory. + +**Action:** +``` +The description "fast and cheap cluster" has conflicting requirements. + +Let me help clarify: +1. Performance-optimized (higher costs, better resources) +2. Cost-optimized (lower costs, minimal resources) +3. Balanced (moderate costs and performance) + +Which approach do you prefer? +``` + +### Provider-Specific Errors + +**Scenario:** Provider-specific validation fails. + +**Action:** +- Forward to appropriate skill for specialized error handling +- Provide provider-specific guidance and solutions +- Offer alternative configurations when possible + +## Best Practices + +1. **Be descriptive:** Include environment type, requirements, and constraints +2. **Specify architecture:** Mention if you need ARM64 or specific architectures +3. **Include network needs:** Specify if disconnected or special networking required +4. **Mention compliance:** Include FIPS, security, or regulatory requirements +5. **Consider costs:** Specify if cost optimization is important +6. **Plan for growth:** Mention if cluster needs to scale or handle specific workloads + +## Anti-Patterns to Avoid + +❌ **Vague descriptions** +``` +/hcp:generate aws "cluster" +``` +✅ Be specific: "development cluster for API testing with minimal resources" + +❌ **Conflicting requirements** +``` +/hcp:generate aws "high-performance cluster but very cheap" +``` +✅ Be realistic: "balanced cluster optimizing for cost while maintaining decent performance" + +❌ **Provider mismatches** +``` +/hcp:generate azure "cluster for my on-premises lab" +``` +✅ Use appropriate provider: "kubevirt cluster for my on-premises lab" + +## See Also + +- `hypershift create cluster --help` - Official hypershift CLI documentation +- Provider-specific skills: + - `hcp-create-aws` - AWS-specific guidance + - `hcp-create-azure` - Azure-specific guidance + - `hcp-create-kubevirt` - KubeVirt-specific guidance + - `hcp-create-openstack` - OpenStack-specific guidance + - `hcp-create-powervs` - PowerVS-specific guidance + - `hcp-create-agent` - Agent provider guidance + +## Skills Reference + +The following skills are automatically invoked by this command based on provider: + +**Provider-specific skills:** +- **hcp-create-aws** - AWS provider implementation details +- **hcp-create-azure** - Azure provider implementation details +- **hcp-create-kubevirt** - KubeVirt provider implementation details +- **hcp-create-openstack** - OpenStack provider implementation details +- **hcp-create-powervs** - PowerVS provider implementation details +- **hcp-create-agent** - Agent provider implementation details + +To view skill details: +```bash +ls plugins/hypershift/skills/ +cat plugins/hypershift/skills/hcp-create-aws/SKILL.md +cat plugins/hypershift/skills/hcp-create-kubevirt/SKILL.md +# ... etc for other providers +``` \ No newline at end of file diff --git a/plugins/hcp/skills/hcp-create-agent/SKILL.md b/plugins/hcp/skills/hcp-create-agent/SKILL.md new file mode 100644 index 00000000..a0f3c921 --- /dev/null +++ b/plugins/hcp/skills/hcp-create-agent/SKILL.md @@ -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 + +Verify agent status: + kubectl describe agents -n + +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 \ + --namespace -ns \ + --agent-namespace \ + --pull-secret \ + --release-image \ + --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 +``` +``` + +**For All Environments:** + +``` +## Next Steps + +1. **Verify agents are available:** + kubectl get agents -n + +2. **Monitor cluster creation:** + kubectl get hostedcluster -n + kubectl get nodepool -n + +3. **Check agent assignment:** + kubectl get agents -n -o wide + +4. **Access cluster when ready:** + hypershift create kubeconfig --name --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 + +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 +``` + +## 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 \ No newline at end of file diff --git a/plugins/hcp/skills/hcp-create-aws/SKILL.md b/plugins/hcp/skills/hcp-create-aws/SKILL.md new file mode 100644 index 00000000..700b7ef4 --- /dev/null +++ b/plugins/hcp/skills/hcp-create-aws/SKILL.md @@ -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 \ + --namespace -ns \ + --region \ + --instance-type \ + --pull-secret \ + --node-pool-replicas \ + --zones \ + --control-plane-availability-policy \ + --sts-creds \ + --role-arn \ + --base-domain \ + --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 + kubectl get nodepool -n + +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 --namespace + export KUBECONFIG=-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/) \ No newline at end of file diff --git a/plugins/hcp/skills/hcp-create-azure/SKILL.md b/plugins/hcp/skills/hcp-create-azure/SKILL.md new file mode 100644 index 00000000..e53ed486 --- /dev/null +++ b/plugins/hcp/skills/hcp-create-azure/SKILL.md @@ -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/) \ No newline at end of file diff --git a/plugins/hcp/skills/hcp-create-kubevirt/SKILL.md b/plugins/hcp/skills/hcp-create-kubevirt/SKILL.md new file mode 100644 index 00000000..69da6fc3 --- /dev/null +++ b/plugins/hcp/skills/hcp-create-kubevirt/SKILL.md @@ -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 \ + --namespace -ns \ + --memory \ + --cores \ + --pull-secret \ + --release-image \ + --service-cidr \ + --cluster-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, RAM) + - Worker VMs: x ( cores, RAM) + - Total Required: cores, 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 +``` + +**For All Environments:** +``` +## Next Steps + +1. **Monitor cluster creation:** + kubectl get hostedcluster -n + kubectl get nodepool -n + +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 --namespace + export KUBECONFIG=-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) \ No newline at end of file diff --git a/plugins/hcp/skills/hcp-create-openstack/SKILL.md b/plugins/hcp/skills/hcp-create-openstack/SKILL.md new file mode 100644 index 00000000..a4a9b903 --- /dev/null +++ b/plugins/hcp/skills/hcp-create-openstack/SKILL.md @@ -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 \ + --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 "" 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/) \ No newline at end of file diff --git a/plugins/hcp/skills/hcp-create-powervs/SKILL.md b/plugins/hcp/skills/hcp-create-powervs/SKILL.md new file mode 100644 index 00000000..082854cf --- /dev/null +++ b/plugins/hcp/skills/hcp-create-powervs/SKILL.md @@ -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/) \ No newline at end of file