Use this skill when you need to deploy HyperShift clusters on existing Kubernetes clusters using KubeVirt virtualization
Inherits all available tools
Additional assets for this skill
This skill inherits all available tools. When active, it can use any tool Claude has access to.
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.
This skill is automatically invoked by the /hcp:generate kubevirt command to guide the KubeVirt provider cluster creation process.
The most important aspect of KubeVirt clusters is preventing network conflicts:
Common management cluster ranges to avoid:
Parse the natural language description for KubeVirt-specific requirements:
Environment Type Detection:
Resource Indicators:
Network Requirements:
Storage Requirements:
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:
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 imageIPv4 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::/64Smart Defaults by Environment:
Development Environment:
--memory 8Gi
--cores 2
--control-plane-availability-policy SingleReplica
--node-pool-replicas 2
Production Environment:
--memory 16Gi
--cores 4
--control-plane-availability-policy HighlyAvailable
--node-pool-replicas 3
--auto-repair true
High-Performance Environment:
--memory 32Gi
--cores 8
--control-plane-availability-policy HighlyAvailable
--node-pool-replicas 5
Required Information Collection:
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
Management Cluster Network Check (see Step 2)
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]
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
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:
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]
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]
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]
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)
Basic KubeVirt Cluster Command:
hypershift create cluster kubevirt \
--name <cluster-name> \
--namespace <cluster-name>-ns \
--memory <memory> \
--cores <cores> \
--pull-secret <pull-secret-path> \
--release-image <release-image> \
--service-cidr <service-cidr> \
--cluster-cidr <cluster-cidr> \
--machine-cidr <machine-cidr>
Development Configuration Example:
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:
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:
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:
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
Provide validation commands:
## Pre-Flight Checks
Before creating the cluster, verify your KubeVirt setup:
1. **KubeVirt Status:**
kubectl get kubevirt -A
2. **Available Storage Classes:**
kubectl get storageclass
3. **Node Resources:**
kubectl top nodes
4. **Available Memory/CPU:**
kubectl describe nodes | grep -E "(Allocatable|Allocated)"
5. **Network Configuration:**
oc get network cluster -o yaml
6. **Required Compute Resources:**
- Control Plane VMs: 3 x (<cores> cores, <memory> RAM)
- Worker VMs: <replica-count> x (<cores> cores, <memory> RAM)
- Total Required: <total-cores> cores, <total-memory> RAM
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
kubectl apply -f <rendered-manifest-files>
For All Environments:
## Next Steps
1. **Monitor cluster creation:**
kubectl get hostedcluster -n <cluster-namespace>
kubectl get nodepool -n <cluster-namespace>
2. **Check VM creation:**
kubectl get vmi -A
3. **Monitor VM startup:**
kubectl get vmi -A -w
4. **Access cluster when ready:**
hypershift create kubeconfig --name <cluster-name> --namespace <cluster-namespace>
export KUBECONFIG=<cluster-name>-kubeconfig
oc get nodes
5. **Verify network isolation:**
oc get network cluster -o yaml # Check HostedCluster networks
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]
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
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"}}}'
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
ā 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
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
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