---

name: kcli-cluster-deployment description: Guides deployment and management of Kubernetes clusters with kcli. Use when deploying OpenShift, k3s, kubeadm, or other Kubernetes distributions.

kcli Cluster Deployment

Supported Cluster Types

Basic Cluster Commands

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

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

Key Parameters

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

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

kubeadm Deployment

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

Key Parameters

Copydomain: 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

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

Key Parameters

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

RKE2 Deployment

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

Key Parameters

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

HyperShift (Hosted Control Planes)

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

Key Parameters

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

MicroShift Deployment

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

Key Parameters

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

Cluster Directory Structure

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

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

Scaling Operations

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

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

Copykcli -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)

Copycloud_lb: true
cloud_dns: true
cloud_storage: true