KubeKey Documentation

KubeKey is an open-source, lightweight task execution framework designed for flexible and rapid Kubernetes installation. It has evolved from a Kubernetes lifecycle management tool into a general-purpose task execution tool (inspired by Ansible's workflow design).

Key Features:

• Task Template Management: Supports multiple sources such as Git or local files.
• Diverse Node Connectivity: Supports local, ssh, kubernetes, and prometheus connection methods.
• Cloud-Native Automation: Supports automated batch task management in cloud-native environments.
• CNCF Conformance: KubeKey has passed the CNCF Kubernetes software conformance certification.

Dynamic variables are generated during execution and can override static variables. They include:

• gather_facts: Information gathered about the host.
• register: Output registered from a task.
• set_fact: Variables explicitly set during execution.

If multiple dynamic variables share the same name, the one defined later in the execution flow overrides the earlier one.

A KubeKey project is a collection of YAML files used to define task templates for orchestration. KubeKey follows Ansible-like conventions. A project can contain:

• playbooks: The execution entry points. A playbook defines a series of tasks or roles to be executed in a specific order.
• roles: Reusable groups of tasks.

Typical directory structure:

project/
├── playbooks/          # Optional: directory for playbook files
│   ├── playbook1.yaml
│   └── playbook2.yaml
├── playbook1.yaml      # Alternatively, place playbooks in the root
├── playbook2.yaml
└── roles/
    ├── roleName1/
    └── roleName2/

KubeKey uses two types of variables: Static variables (defined before execution) and Dynamic variables (generated during execution).

Priority Rules:

1. Dynamic variables always override Static variables.
2. For Static variables, the priority is: Global config > Inventory > Parameters defined in templates.
3. Within Inventory, the priority is: Host variables > Group variables > Global variables.
4. For Dynamic variables, later definitions override earlier ones with the same name.

The init phase prepares the environment and dependencies required for the cluster installation. It performs the following tasks:

• Software Downloads: Fetches binaries for Kubernetes, container runtimes, and network plugins.
• Helm Preparation: Acquires and validates required Helm Chart packages.
• Image Pulling: Downloads Docker images for core components and dependencies.
• Offline Packaging: If offline mode is enabled, bundles all binaries, images, and Charts into a complete offline installation package.
• Certificate Management: Generates CA and service certificates for inter-component communication.

The install phase is the core deployment stage where KubeKey configures the Kubernetes cluster. The following components can be installed:

• nfs: Installs NFS service for nodes in the nfs group.
• image_registry: Installs a registry (harbor or registry) for nodes in the image_registry group.
• etcd: Installs etcd for nodes in the etcd group.
• cri: Installs the container runtime (docker or containerd) for nodes in the k8s_cluster group.
• kubernetes_install: Installs Kubernetes for nodes in the k8s_cluster group.
• helm: Installs Helm applications and CNI plugins (supports calico, cilium, flannel, hybridnet, kubeovn, multus).

KubeKey uses a built-in playbook to manage the complete lifecycle of Kubernetes clusters. Supported lifecycle operations include:

• Cluster creation
• Cluster deletion
• Node addition
• Node removal
• Cluster upgrade

Generate a template for your cluster's node configuration using the kk create inventory command. The resulting inventory.yaml file defines how KubeKey connects to nodes and how they are grouped into roles.

./kk create inventory -o .