kubekey

KubeKey Skill

KubeKey is a lightweight Kubernetes cluster lifecycle management tool for creating, scaling and deleting clusters.

Installation

Binary Installation

# Linux/macOS - Latest version (stable)
curl -sfL https://get-kk.kubesphere.io | KK_ONLY=true sh -

# Download a specific pre-release version (e.g., v4.0.5)
# The get-kk script may not include pre-releases. Use the GitHub release directly:
curl -sfL https://github.com/kubesphere/kubekey/releases/download/v4.0.5/downloadKubekey.sh | KK_ONLY=true sh -

# China mirror (faster in China)
curl -sfL https://get-kk.kubesphere.io | KK_ONLY=true KKZONE=cn sh -

Windows: Use WSL or download from GitHub Releases

The script downloads kk binary to current directory. Move it to a directory in your $PATH:

# Move to /usr/local/bin
sudo mv kk /usr/local/bin/

# Verify
kk version

Quick Start

1. Basic Cluster Creation Flow

# Step 1: Create inventory file (defines nodes)
kk create inventory -o inventory.yaml

# Step 2: Create config file (defines software: K8s version, network, storage, etc.)
# --with-kubernetes: Specify Kubernetes version (run 'kk create config --help' to see the default)
kk create config --with-kubernetes v1.33.7 -o config.yaml

# Step 3: Create cluster
# Method 1: Use config.yaml file
kk create cluster -i inventory.yaml -c config.yaml

# Method 2: Use default config for K8s version (no config.yaml file generated)
kk create cluster -i inventory.yaml --with-kubernetes v1.33.7

kk create config Command

Generates default config.yaml with cluster software configuration (K8s version, network, storage, etc.).

Common Parameters:

Generated Config Structure:

• kubernetes: K8s version, cluster name, API Server, etc.
• cni: CNI plugin, Pod/Service CIDR
• cri: Container runtime configuration
• storage: Storage class configuration
• image_registry: Image registry configuration

kk create inventory Command

Generates default inventory.yaml file.

Parameters:

The generated inventory contains template nodes that need to be edited with actual node information.

kk create cluster Command

Creates cluster based on inventory and config.

Two methods:

1. kk create cluster -i inventory.yaml -c config.yaml - Use config file
2. kk create cluster -i inventory.yaml --with-kubernetes v1.33.7 - Use default config for K8s version (no file generated)

Common Parameters:

Inventory File

For detailed format and examples, see: references/inventory.md

Includes:

• Complete inventory examples
• SSH/local connector configuration
• Host variables (IP, labels, taints)
• Group definitions
• HA cluster multi-node examples

Complete Config Reference

For detailed configuration, see: references/config.md

Includes:

• Basic structure (cluster_require, certs, image_registry, native)
• Kubernetes configuration (apiserver, controller-manager, scheduler, kubelet, kube-proxy)
• CNI network configuration (calico, cilium, flannel, kubeovn)
• CRI container runtime configuration
• etcd configuration (internal/external)
• DNS configuration (CoreDNS, NodeLocalDNS)
• Storage class configuration (local, nfs)
• Image registry configuration (harbor, docker-registry)
• Complete configuration examples

Command Reference

Generate Config

# Generate node config (defines hosts, SSH connections, node roles, etc.) - defines cluster spec
kk create inventory -o inventory.yaml

# Generate software config (defines K8s version, network plugin, storage, etc.)
kk create config --with-kubernetes v1.33.7 -o config.yaml

Init (optional, can be merged into create cluster)

# Initialize OS environment (install dependencies, configure network, etc.)
kk init os -i inventory.yaml -c config.yaml

# Install private image registry
kk init registry -i inventory.yaml -c config.yaml

# Node precheck
kk precheck -i inventory.yaml -c config.yaml
# Can specify check items: etcd, os, network, cri, nfs
kk precheck etcd os network cri nfs -i inventory.yaml -c config.yaml

Create Cluster

# Method 1: Use config.yaml file
kk create cluster -i inventory.yaml -c config.yaml

# Method 2: Use default config for K8s version (no config.yaml file generated)
kk create cluster -i inventory.yaml --with-kubernetes v1.33.7

Add Nodes

Step 1: Define new node in inventory.yaml hosts section

Step 2: Add to corresponding groups

# Method 1: Add nodes directly in inventory.yaml groups
kk add nodes -i inventory.yaml -c config.yaml

# Method 2: Add nodes via command line parameters
kk add nodes -i inventory.yaml -c config.yaml --control-plane node2,node3 --worker node4,node5

Delete Nodes

kk delete nodes node1 node2 -i inventory.yaml -c config.yaml

Update Certificates

kk certs renew -i inventory.yaml -c config.yaml

Delete Cluster

kk delete cluster -i inventory.yaml -c config.yaml

Offline Installation (Artifact)

For air-gapped environments, use artifact commands to manage offline packages:

# Export artifact package containing required packages and images
kk artifact export --with-kubernetes v1.33.7 -c config.yaml

# Push artifact images to a private registry
kk artifact images -i inventory.yaml -c config.yaml --push

# Pull artifact images to local directory
kk artifact images -i inventory.yaml -c config.yaml --pull

How to Help Users

When a user asks about KubeKey or cluster operations, follow this approach:

1. Identify the goal: Determine if they want to create, scale, delete or configure a cluster.
2. Check prerequisites: Ask for node information (IPs, SSH credentials, roles) if creating or scaling a cluster.
3. Guide step by step: Direct them to generate templates first (kk create inventory/config), edit files, then execute.
4. Point to references: For specific config options (CNI, CRI, storage), direct them to references/config.md.
5. Verify with precheck: Recommend running kk precheck before cluster creation to avoid failures.

Common Workflows

Cluster Creation Process

Important: Collect node information first before starting.

Step 1: Collect Node Information

Prepare the following information:

Step 2: Generate Inventory Template

kk create inventory -o inventory.yaml

Step 3: Edit inventory.yaml

Fill in node information into inventory.yaml, refer to format in references/inventory.md.

Step 4: Generate Config

Generate config.yaml based on your desired configuration.

For specific configuration examples tailored to your Kubernetes version, CNI plugin, storage type, etc., refer to references/config.md.

# Example: Generate based on your provided configuration
kk create config --with-kubernetes v1.33.7 -o config.yaml

Step 5: Create Cluster

# Method 1: Use config.yaml file
kk create cluster -i inventory.yaml -c config.yaml

# Method 2: Use default config (no config.yaml file generated)
kk create cluster -i inventory.yaml --with-kubernetes v1.33.7

Create HA Cluster

inventory.yaml needs to contain:

• 3 etcd nodes
• 3 control plane nodes
• Multiple worker nodes

Troubleshooting

Common Issues

1. SSH connection failed: Check SSH configuration in inventory
2. Node does not meet requirements: Run kk precheck for details

Debug Mode

Use -v parameter to specify log level (klog mechanism, higher number = more verbose):

# Example: -v 5 prints debug logs
kk create cluster -i inventory.yaml -c config.yaml -v 5

macOS Compatibility

When running kk on macOS, you may encounter the following issues due to the default zsh shell and macOS sudo configuration:

1. zsh: no matches found: *.sh

Symptom: Playbook fails with glob pattern errors like:

zsh:1: no matches found: /etc/kubekey/scripts/pre_install_*.sh

Root Cause: macOS default shell is zsh, which has different glob behavior from bash.

Fix: Set SHELL to bash before running kk commands:

export SHELL=/bin/bash
kk create cluster -i inventory.yaml -c config.yaml

2. command not found: mkdir

Symptom: Commands like mkdir or rm fail on localhost with:

zsh:4: command not found: mkdir

Root Cause: macOS sudo's secure_path is /usr/local/bin by default, which does not include /bin where mkdir is located.

Fix: Update sudo secure_path to include standard directories. On macOS, visudo is at /usr/sbin/visudo:

# Edit sudoers (use full path on macOS)
sudo /usr/sbin/visudo

# Find the line:
#   Defaults    secure_path = /usr/local/bin
# Change it to:
#   Defaults    secure_path = /usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin

Note: The sudoers change takes effect immediately and persists across reboots. Revert after use if desired.

Get Help

# View help
kk --help

# View subcommand help
kk create cluster --help
kk add nodes --help

# View version
kk version