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

• API IP not reachable: Ensure api_ip is in the correct subnet

• Pull secret invalid: Verify JSON format and Red Hat subscription

• Insufficient resources: Check VM memory/CPU against requirements

• 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