kcli Cluster Deployment

Supported Cluster Types

Type	Description	Module
openshift	Red Hat OpenShift (IPI/UPI)	kvirt/cluster/openshift/
okd	Community OpenShift	Same as openshift
hypershift	OpenShift Hosted Control Planes	kvirt/cluster/hypershift/
microshift	Lightweight edge OpenShift	kvirt/cluster/microshift/
generic	Generic Kubernetes (alias: kubernetes)	kvirt/cluster/kubernetes/
kubeadm	Standard Kubernetes via kubeadm	kvirt/cluster/kubeadm/
k3s	Lightweight Kubernetes	kvirt/cluster/k3s/
rke2	Rancher Kubernetes Engine 2	kvirt/cluster/rke2/
aks	Azure Kubernetes Service	kvirt/cluster/aks/
eks	Amazon Elastic Kubernetes	kvirt/cluster/eks/
gke	Google Kubernetes Engine	kvirt/cluster/gke/

Basic Cluster Commands

# Create cluster
kcli create kube <type> <clustername>

# Create with parameters
kcli create kube openshift -P ctlplanes=3 -P workers=2 mycluster

# List clusters
kcli list kube

# Get cluster info
kcli info kube mycluster

# Delete cluster
kcli delete kube mycluster

# Scale cluster
kcli scale kube <type> -P workers=5 mycluster

# Get kubeconfig
kcli get kubeconfig mycluster

OpenShift Deployment

Minimal Example

kcli create kube openshift -P pull_secret=~/pull-secret.json mycluster

Key Parameters

# Required
pull_secret: ~/pull-secret.json    # Red Hat pull secret
domain: example.com                 # Base domain

# Topology
ctlplanes: 3                        # Control plane nodes
workers: 2                          # Worker nodes
version: stable                     # OpenShift version (stable, 4.14, etc.)

# Resources
ctlplane_memory: 16384              # Control plane memory (MB)
ctlplane_numcpus: 8                 # Control plane CPUs
worker_memory: 8192                 # Worker memory
worker_numcpus: 4                   # Worker CPUs

# Networking
network: default                    # Libvirt network
api_ip: 192.168.122.253            # API VIP (auto-detected if omitted)
ingress_ip: 192.168.122.252        # Ingress VIP

Disconnected/Air-gapped

disconnected_url: registry.local:5000
disconnected_user: admin
disconnected_password: password
ca: |
  -----BEGIN CERTIFICATE-----
  ...
  -----END CERTIFICATE-----

kubeadm Deployment

kcli create kube kubeadm -P domain=k8s.local -P ctlplanes=1 -P workers=2 myk8s

Key Parameters

domain: k8s.local                   # Required domain
version: 1.29                       # Kubernetes version
ctlplanes: 1                        # Control planes (odd number for HA)
workers: 2                          # Worker count
network: default                    # Network name
api_ip: 192.168.122.250            # API endpoint (for multi-ctlplane)
image: centos9stream                # Base OS image

k3s Deployment

kcli create kube k3s -P ctlplanes=1 -P workers=2 myk3s

Key Parameters

ctlplanes: 1
workers: 2
version: latest                     # k3s version
domain: k3s.local
image: ubuntu2204

RKE2 Deployment

kcli create kube rke2 -P ctlplanes=1 -P workers=2 myrke2

Key Parameters

ctlplanes: 1
workers: 2
version: latest                     # RKE2 version
domain: rke2.local
image: ubuntu2204

HyperShift (Hosted Control Planes)

kcli create kube hypershift \
  -P pull_secret=~/pull-secret.json \
  -P nodepool_replicas=2 \
  myhypershift

Key Parameters

pull_secret: ~/pull-secret.json
management_cluster: mgmt            # Existing cluster name
nodepool_replicas: 2                # Worker node count
release_image: ...                  # Specific OCP release

MicroShift Deployment

kcli create kube microshift -P pull_secret=~/pull-secret.json mymicroshift

Key Parameters

pull_secret: ~/pull-secret.json
version: latest                     # MicroShift version
image: rhel9                        # RHEL-based image required

Cluster Directory Structure

Clusters store state in ~/.kcli/clusters/<clustername>/:

~/.kcli/clusters/mycluster/
├── kcli_parameters.yml    # Stored parameters
├── kubeconfig             # Cluster kubeconfig
├── auth/                  # Auth credentials (OpenShift)
│   ├── kubeadmin-password
│   └── kubeconfig
└── (other cluster-specific files)

Scaling Operations

# Scale workers
kcli scale kube openshift -P workers=5 mycluster

# Scale control planes (careful!)
kcli scale kube kubeadm -P ctlplanes=3 mycluster

# Add nodes with specific parameters
kcli scale kube openshift -P workers=3 -P worker_memory=16384 mycluster

Troubleshooting

Check Deployment Progress

# OpenShift: watch bootstrap
kcli ssh mycluster-bootstrap
journalctl -f -u bootkube

# kubeadm: check cluster status
export KUBECONFIG=~/.kcli/clusters/mycluster/kubeconfig
kubectl get nodes
kubectl get pods -A

Common Issues

1. API IP not reachable: Ensure api_ip is in the correct subnet
2. Pull secret invalid: Verify JSON format and Red Hat subscription
3. Insufficient resources: Check VM memory/CPU against requirements
4. DNS resolution: Ensure domain resolves or use sslip: true

Debug Mode

kcli -d create kube openshift mycluster  # Verbose output

Cloud Provider Notes

For cloud providers (AWS, GCP, Azure), kcli can:

• Auto-create load balancers (cloud_lb: true)
• Configure cloud DNS (cloud_dns: true)
• Set up cloud storage (cloud_storage: true)

cloud_lb: true
cloud_dns: true
cloud_storage: true