gh-openshift-eng-ai-helpers-plugins-hcp/commands/generate.md

---
description: Generate ready-to-execute hypershift cluster creation commands from natural language descriptions
argument-hint: <provider> <cluster-description>
---

## Name
hcp:generate

## Synopsis
```
/hcp:generate <provider> <cluster-description>
```

## 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
```