KubeKey (kk) Usage Guide. For Kubernetes cluster lifecycle management including creation, scaling and deletion.
Use this skill whenever the user mentions kubekey, kk commands, cluster setup, cluster management, adding nodes,
deleting nodes, creating inventory files, configuring clusters, installing Kubernetes, or deploying K8s.
Also use this skill when the user asks about inventory.yaml, config.yaml formats, CNI configuration, container runtime setup,
offline installation, or artifact operations. Provides detailed guidance on kk subcommand usage, config file formats, inventory structure and common workflows.
KubeKey (kk) Usage Guide. For Kubernetes cluster lifecycle management including creation, scaling and deletion.
Use this skill whenever the user mentions kubekey, kk commands, cluster setup, cluster management, adding nodes,
deleting nodes, creating inventory files, configuring clusters, installing Kubernetes, or deploying K8s.
Also use this skill when the user asks about inventory.yaml, config.yaml formats, CNI configuration, container runtime setup,
offline installation, or artifact operations. Provides detailed guidance on kk subcommand usage, config file formats, inventory structure and common workflows.
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 -
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:
Identify the goal: Determine if they want to create, scale, delete or configure a cluster.
Check prerequisites: Ask for node information (IPs, SSH credentials, roles) if creating or scaling a cluster.
Guide step by step: Direct them to generate templates first (kk create inventory/config), edit files, then execute.
Point to references: For specific config options (CNI, CRI, storage), direct them to references/config.md.
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:
Field
Description
Example
Node Name
Unique identifier
node1, master1, worker1
IP Address
Node network address
192.168.1.10
SSH Port
Default 22
22
SSH User
Login username
root
Auth Method
Password or private key path
password: "xxx" or private_key: ~/.ssh/id_rsa
Node Role
control_plane/worker/etcd
Choose based on requirements
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
SSH connection failed: Check SSH configuration in inventory
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
