# kubernetes-sigs/kubespray architecture

> Architecture diagram of the GitHub repository kubernetes-sigs/kubespray, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kubernetes-sigs/kubespray
- Repository: https://github.com/kubernetes-sigs/kubespray

## Overview

Kubespray is an Ansible-based system for provisioning and operating production Kubernetes clusters across cloud and bare-metal environments. The principal workflow starts with an operator’s inventory and the `cluster.yml` playbook, then prepares hosts and installs Kubernetes, its container runtime, etcd, and a selected network plugin; optional cluster applications and storage integrations extend the result. The graph also includes documented operations and sampled inventory, certificate, and component-hash utilities. Several role-to-role deployment links are described only at the product level in the README, so unsampled internal call relationships are not asserted.

Main entry points: [`cluster.yml`](https://github.com/kubernetes-sigs/kubespray/blob/master/cluster.yml) (Cluster playbook), [`inventory`](https://github.com/kubernetes-sigs/kubespray/tree/master/inventory) (Ansible inventory), [`roles/kubernetes/control-plane`](https://github.com/kubernetes-sigs/kubespray/tree/master/roles/kubernetes/control-plane) (Control plane), [`roles/kubernetes/control-plane/files/k8s-certs-renew.py`](https://github.com/kubernetes-sigs/kubespray/blob/master/roles/kubernetes/control-plane/files/k8s-certs-renew.py) (Certificate renewal)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_deployment["Cluster deployment"]
  node_inventory["Ansible inventory"]
  node_playbook["Cluster playbook<br/>[cluster.yml]"]
end

subgraph group_platform["Host and Kubernetes"]
  node_bootstrap["OS bootstrap"]
  node_preinstall["Host preparation"]
  node_runtime["Container engines"]
  node_etcd["etcd"]
  node_kubeadm["Kubernetes setup"]
  node_controlplane["Control plane"]
  node_kubenode["Kubernetes nodes"]
end

subgraph group_extensions["Cluster extensions"]
  node_network["Network plugins"]
  node_apps["Cluster applications"]
  node_storage["Storage integrations"]
end

subgraph group_operations["Cluster operations"]
  node_upgrade["Cluster upgrades"]
  node_nodeops["Node operations"]
  node_recovery["Control-plane recovery"]
  node_cert_renew["Certificate renewal<br/>[k8s-certs-renew.py]"]
end

subgraph group_utilities["Inventory and utilities"]
  node_terraform_inventory["Terraform inventory<br/>[terraform.py]"]
  node_aws_inventory["AWS inventory"]
  node_kube_module["Kubernetes module<br/>[kube.py]"]
  node_hash_download["Hash updater<br/>[download.py]"]
  node_component_metadata["Component metadata<br/>[components.py]"]
end

node_operator(("Cluster operator"))

node_operator -->|"provides hosts"| node_inventory
node_operator -->|"runs playbook"| node_playbook
node_inventory -->|"selects hosts"| node_playbook
node_playbook -.->|"provisions hosts"| node_bootstrap
node_playbook -.->|"prepares hosts"| node_preinstall
node_playbook -.->|"sets up runtime"| node_runtime
node_playbook -.->|"deploys etcd"| node_etcd
node_playbook -.->|"installs Kubernetes"| node_kubeadm
node_playbook -.->|"configures control plane"| node_controlplane
node_playbook -.->|"configures nodes"| node_kubenode
node_playbook -->|"selects network"| node_network
node_playbook -.->|"deploys applications"| node_apps
node_playbook -.->|"enables storage"| node_storage
node_operator -->|"runs upgrades"| node_upgrade
node_operator -->|"manages nodes"| node_nodeops
node_operator -.->|"recovers cluster"| node_recovery
node_terraform_inventory -.->|"generates host data"| node_inventory
node_aws_inventory -.->|"generates host data"| node_inventory
node_kube_module -.->|"manages resources"| node_operator
node_cert_renew -->|"renews certificates"| node_controlplane
node_hash_download -->|"reads metadata"| node_component_metadata

click node_inventory "https://github.com/kubernetes-sigs/kubespray/tree/master/inventory"
click node_playbook "https://github.com/kubernetes-sigs/kubespray/blob/master/cluster.yml"
click node_bootstrap "https://github.com/kubernetes-sigs/kubespray/tree/master/roles/bootstrap_os"
click node_preinstall "https://github.com/kubernetes-sigs/kubespray/tree/master/roles/kubernetes/preinstall"
click node_runtime "https://github.com/kubernetes-sigs/kubespray/tree/master/roles/container-engine"
click node_etcd "https://github.com/kubernetes-sigs/kubespray/tree/master/roles/etcd"
click node_kubeadm "https://github.com/kubernetes-sigs/kubespray/tree/master/roles/kubernetes/kubeadm"
click node_controlplane "https://github.com/kubernetes-sigs/kubespray/tree/master/roles/kubernetes/control-plane"
click node_kubenode "https://github.com/kubernetes-sigs/kubespray/tree/master/roles/kubernetes/node"
click node_network "https://github.com/kubernetes-sigs/kubespray/tree/master/roles/network_plugin"
click node_apps "https://github.com/kubernetes-sigs/kubespray/tree/master/roles/kubernetes-apps"
click node_storage "https://github.com/kubernetes-sigs/kubespray/tree/master/roles/kubernetes-apps/csi_driver"
click node_upgrade "https://github.com/kubernetes-sigs/kubespray/tree/master/roles/upgrade"
click node_nodeops "https://github.com/kubernetes-sigs/kubespray/tree/master/roles/remove_node"
click node_recovery "https://github.com/kubernetes-sigs/kubespray/tree/master/roles/recover_control_plane"
click node_terraform_inventory "https://github.com/kubernetes-sigs/kubespray/blob/master/contrib/terraform/terraform.py"
click node_aws_inventory "https://github.com/kubernetes-sigs/kubespray/blob/master/contrib/aws_inventory/kubespray-aws-inventory.py"
click node_kube_module "https://github.com/kubernetes-sigs/kubespray/blob/master/plugins/modules/kube.py"
click node_cert_renew "https://github.com/kubernetes-sigs/kubespray/blob/master/roles/kubernetes/control-plane/files/k8s-certs-renew.py"
click node_hash_download "https://github.com/kubernetes-sigs/kubespray/blob/master/scripts/component_hash_update/src/component_hash_update/download.py"
click node_component_metadata "https://github.com/kubernetes-sigs/kubespray/blob/master/scripts/component_hash_update/src/component_hash_update/components.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_inventory,node_playbook toneBlue
class node_bootstrap,node_preinstall,node_runtime,node_etcd,node_kubeadm,node_controlplane,node_kubenode toneAmber
class node_network,node_apps,node_storage toneMint
class node_upgrade,node_nodeops,node_recovery,node_cert_renew toneRose
class node_terraform_inventory,node_aws_inventory,node_kube_module,node_hash_download,node_component_metadata,node_operator toneIndigo
```

## Components

### Cluster deployment

- [Ansible inventory](https://github.com/kubernetes-sigs/kubespray/tree/master/inventory): `inventory`
- [Cluster playbook](https://github.com/kubernetes-sigs/kubespray/blob/master/cluster.yml): `cluster.yml`

### Host and Kubernetes

- [OS bootstrap](https://github.com/kubernetes-sigs/kubespray/tree/master/roles/bootstrap_os): `roles/bootstrap_os`
- [Host preparation](https://github.com/kubernetes-sigs/kubespray/tree/master/roles/kubernetes/preinstall): `roles/kubernetes/preinstall`
- [Container engines](https://github.com/kubernetes-sigs/kubespray/tree/master/roles/container-engine): `roles/container-engine`
- [etcd](https://github.com/kubernetes-sigs/kubespray/tree/master/roles/etcd): `roles/etcd`
- [Kubernetes setup](https://github.com/kubernetes-sigs/kubespray/tree/master/roles/kubernetes/kubeadm): `roles/kubernetes/kubeadm`
- [Control plane](https://github.com/kubernetes-sigs/kubespray/tree/master/roles/kubernetes/control-plane): `roles/kubernetes/control-plane`
- [Kubernetes nodes](https://github.com/kubernetes-sigs/kubespray/tree/master/roles/kubernetes/node): `roles/kubernetes/node`

### Cluster extensions

- [Network plugins](https://github.com/kubernetes-sigs/kubespray/tree/master/roles/network_plugin): `roles/network_plugin`
- [Cluster applications](https://github.com/kubernetes-sigs/kubespray/tree/master/roles/kubernetes-apps): `roles/kubernetes-apps`
- [Storage integrations](https://github.com/kubernetes-sigs/kubespray/tree/master/roles/kubernetes-apps/csi_driver): `roles/kubernetes-apps/csi_driver`

### Cluster operations

- [Cluster upgrades](https://github.com/kubernetes-sigs/kubespray/tree/master/roles/upgrade): `roles/upgrade`
- [Node operations](https://github.com/kubernetes-sigs/kubespray/tree/master/roles/remove_node): `roles/remove_node`
- [Control-plane recovery](https://github.com/kubernetes-sigs/kubespray/tree/master/roles/recover_control_plane): `roles/recover_control_plane`
- [Certificate renewal](https://github.com/kubernetes-sigs/kubespray/blob/master/roles/kubernetes/control-plane/files/k8s-certs-renew.py): `roles/kubernetes/control-plane/files/k8s-certs-renew.py`

### Inventory and utilities

- [Terraform inventory](https://github.com/kubernetes-sigs/kubespray/blob/master/contrib/terraform/terraform.py): `contrib/terraform/terraform.py`
- [AWS inventory](https://github.com/kubernetes-sigs/kubespray/blob/master/contrib/aws_inventory/kubespray-aws-inventory.py): `contrib/aws_inventory/kubespray-aws-inventory.py`
- [Kubernetes module](https://github.com/kubernetes-sigs/kubespray/blob/master/plugins/modules/kube.py): `plugins/modules/kube.py`
- [Hash updater](https://github.com/kubernetes-sigs/kubespray/blob/master/scripts/component_hash_update/src/component_hash_update/download.py): `scripts/component_hash_update/src/component_hash_update/download.py`
- [Component metadata](https://github.com/kubernetes-sigs/kubespray/blob/master/scripts/component_hash_update/src/component_hash_update/components.py): `scripts/component_hash_update/src/component_hash_update/components.py`

### Other components

- **Cluster operator**

## Connections

- Cluster operator → Ansible inventory: provides hosts (evidence: `README.md`)
- Cluster operator → Cluster playbook: runs playbook (evidence: `README.md`)
- Ansible inventory → Cluster playbook: selects hosts (evidence: `README.md`)
- Cluster playbook → OS bootstrap: provisions hosts
- Cluster playbook → Host preparation: prepares hosts
- Cluster playbook → Container engines: sets up runtime
- Cluster playbook → etcd: deploys etcd
- Cluster playbook → Kubernetes setup: installs Kubernetes
- Cluster playbook → Control plane: configures control plane
- Cluster playbook → Kubernetes nodes: configures nodes
- Cluster playbook → Network plugins: selects network (evidence: `README.md`)
- Cluster playbook → Cluster applications: deploys applications
- Cluster playbook → Storage integrations: enables storage
- Cluster operator → Cluster upgrades: runs upgrades (evidence: `README.md`)
- Cluster operator → Node operations: manages nodes (evidence: `README.md`)
- Cluster operator → Control-plane recovery: recovers cluster
- Terraform inventory → Ansible inventory: generates host data
- AWS inventory → Ansible inventory: generates host data
- Kubernetes module → Cluster operator: manages resources
- Certificate renewal → Control plane: renews certificates (evidence: `roles/kubernetes/control-plane/files/k8s-certs-renew.py`)
- Hash updater → Component metadata: reads metadata (evidence: `scripts/component_hash_update/src/component_hash_update/download.py`)
