登录

kubespray

kubernetes-sigsApache-2.0活跃维护

用 Ansible 在裸机、AWS、GCE 等环境一键部署生产级 Kubernetes 集群，支持高可用，省去手工搭集群的繁琐。

Deploy a Production Ready Kubernetes Cluster

v2.32.0发布于 2026-09-22 04:37 UTC18,829star +6 / 7 天6,944fork同步于 2026-11-10 17:24 UTC
Kubernetes 部署Ansible高可用集群裸机部署生产级集群
对比 GitHubansibleawsbare-metalgcehacktoberfest

怎么上手

由 README 提炼，执行前请确认
原文 
docker run --rm -it --mount type=bind,source="$(pwd)"/inventory/sample,dst=/inventory --mount type=bind,source="${HOME}"/.ssh/id_rsa,dst=/root/.ssh/id_rsa quay.io/kubespray/kubespray:v2.31.0 bash
ansible-playbook -i /inventory/inventory.ini --private-key /root/.ssh/id_rsa cluster.yml
硬件要求按 README 说明

控制平面节点至少 2 GB 内存，工作节点至少 1 GB 内存；README 未提及 GPU 或显存要求，目标服务器需能访问互联网拉取镜像。

有 Docker 镜像
下载：源码 zip·GitHub Releases（安装包）本站不镜像安装包

项目说明

由 README 自动翻译提炼
没人工点评？写下你的经验

用 Ansible 在裸机或云上部署生产级高可用 Kubernetes 集群的官方工具

用 Ansible 在裸机、AWS、GCE 等环境一键部署生产级 Kubernetes 集群，支持高可用，省去手工搭集群的繁琐。

核心能力

  • 用 Ansible playbook 编排集群部署与升级
  • 支持 AWS、GCE、Azure、OpenStack、vSphere 及裸机
  • 可组合选择 calico、cilium、flannel 等网络插件
  • 支持多发行版 Linux 与 HA 控制平面
  • 内置 CI 端到端测试矩阵验证部署

容易踩的坑

运行 Ansible 的机器需装 Ansible 14（ansible-core 2.21）、Jinja 3.1+ 和 python-netaddr；目标服务器需能联网拉镜像，离线环境要额外配置；Kubespray 不管理防火墙，部署前建议自行关闭或放行。

内容由模型根据 README 生成，可能不完整或不准确，以官方文档为准。看原文 README

最近发版

5 个版本v2.32.0
全部 release
  1. v2.32.0最新正式版2026-09-22 · 2026-09-22 04:37 UTC

    Highlights

    • Kubernetes 1.36 is the default minor version
    • Ansible environment moves to Ansible 12 / ansible-core 2.19, with breaking changes to conditionals and templating. See Urgent Upgrade Notes before upgrading.
    • New operating system support includes Ubuntu 26.04, openSUSE Leap 16.0, and openSUSE MicroOS with containerd.

    Urgent Upgrade Notes

    (No, really, you MUST read this before you upgrade)

    • Ansible environment (action required): Kubespray now requires ansible-core >=2.19.0,<2.20.0 and ships with Ansible 12. Before running playbooks, recreate or update the virtual environment on the Ansible control host using this release's requirements.txt. Ansible 2.19 requires conditional expressions to return booleans; -e key=value supplies strings. Pass boolean overrides as JSON (for example, -e '{"drain_nodes": true, "drain_fallback_enabled": true}') or use unquoted booleans in YAML inventory or extra-vars files (-e @vars.yml). Review custom Jinja templates in inventories and integrated playbooks for compatibility with the templating changes described in the Ansible 12 porting guide. The documentation examples have been updated accordingly. (#13468, @VannTen; #13526, @shashankvarma499)
    • Node Feature Discovery (action required): The default version is now 0.19.0. Remove node_feature_discovery_enable_nodefeature_api, node_feature_discovery_master_crd_controller, and node_feature_discovery_master_instance from inventory overrides. gRPC mode and executable hooks under source.d are no longer supported. Custom NodeFeatureRule templates must no longer use env, expandenv, or getHostByName; review and migrate affected configurations before upgrading. (#13512, @vashian)
    • Pinned Helm versions (action required): Helm now defaults to 3.22.0. Checksums for Helm 3.16.x, 3.17.x, and 3.18.x have been removed. If inventory overrides pin helm_version to one of these versions, remove the override to use the default or select an available version from the retained 3.20.x, 3.21.x, or 3.22.x series. (#13535, @guoard)
    • Cilium Gateway API: Gateway API CRDs now default to 1.6.2, meeting Cilium 1.20's minimum requirement of Gateway API 1.6.1. If you enable Cilium's Gateway API support and pin gateway_api_version below 1.6.1, update or remove that override before upgrading. Gateway API 1.6.0 and 1.6.1 checksums are also available, but 1.6.0 does not meet Cilium 1.20's Gateway API requirement. (#13534, @yankay)
    • etcd metrics discovery: The etcd-metrics Service now uses EndpointSlice instead of Endpoints to avoid duplicate metrics. If you use this Service, update scrapers that still discover Endpoints. With Prometheus Operator, set spec.serviceDiscoveryRole: EndpointSlice on the relevant ServiceMonitor or Prometheus resource, and grant Prometheus permission to get, list, and watch endpointslices in the discovery.k8s.io API group. Verify etcd scrape targets after upgrading. (#12846, @jmeza-xyz)
    • Debian 11 and macvlan: Debian 11 (Bullseye) is no longer supported; migrate to a supported operating system before upgrading. macvlan support on Debian has also been removed because it was not functional on Debian 12 or 13. macvlan is no longer tested in CI. (#13483, @VannTen)
    • Debian 13 with Docker: This combination is no longer supported or tested because Debian 13 removed apt-key, which the Docker repository setup still requires. Use containerd on Debian 13, or remain
  2. v2.31.02026-04-25 · 2026-04-25 04:58 UTC
    查看更新说明

    Urgent Upgrade Notes

    (No, really, you MUST read this before you upgrade)

    • Action required Make kubernetes v1.35 default. cgroup V1 is no longer supported upstream by default, and must be enabled with kubelet_fail_cgroup_v1: false. (#12812, @mzaian)
    • Action required Support for ingress-nginx ingress controller is removed, as the project has been retired by upstream (#12767, @jmeza-xyz)
    • Action required The Kubernetes Dashboard addon has been removed from Kubespray because the upstream project is being archived and is no longer maintained. The configuration dashboard_enabled: true is no longer supported. (#12858, @neo502721)
    • Adds automated validation role to detect removed variables at playbook start. Playbooks will abort on removed vars. Users must migrate away from the listed removed variables to avoid playbook failures. (#12942, @Srishti-j18)
    • Replace ssh_bastion_confing__name with ssh_bastion_config_name (#13046, @scolley31)

    Changes by Kind

    Feature

    • A new configuration option kubelet_static_pod_path has been added which can be used to configure path of static pod manifests OR even to disable staticPodPath setting in kubelet by setting it as empty (STIG recommendation for worker nodes) (#12433, @shaleenbathla)
    • Add Structured AuthenticationConfiguration config file support for kube-apiserver (#13035, @chadswen)
    • Add support for kube-vip BGP source selection in Kubespray by exposing kube_vip_bgp_sourceip and kube_vip_bgp_sourceif (mutually exclusive). (#13044, @Kirillov-AN)
    • Bump CNI plugins to v1.9.1. (#13198, @karimzakzouk)
    • Bump Flannel to v0.28.4. (#13199, @karimzakzouk)
    • Bump Prometheus Operator CRD to 0.88.1 (#12968, @hcc429)
    • Bump containerd default version to 2.2.3. (#13174, @yankay)
    • Cilium template apiVersion upgrade to v2 (#13095, @guoard)
    • Coredns service name can now be customized with coredns_svc_name (#12951, @VannTen)
    • Enable create_namespace option for custom_cni with helm (#13061, @guoard)
    • Increase fs.inotify.max_user_instances to 8192 by default (#13075, @rptaylor)
    • Increased StartLimitBurst to 10 for docker service to prevent cri-dockerd restart throttling (#13005, @Tushar240503)
    • Make kubernetes v1.35.4 default. (#13193, @mzaian)
    • Support for Fedora 41 (#12138, @tico88612)
    • Support for Fedora 42 (#12989, @labaq)
    • Update etcd to 3.6.8 Upgrade note: You need to update etcd to >=3.5.26 (Kubespray 2.30.0) before upgrading existing cluster (#12634, @tmurakam)
    • Updated the default Calico version to v3.31.5. (#13196, @Srishti-j18)
    • Upgrade Dockerfile base image from Ubuntu 22.04 to 24.04 (#12935, @guoard)
    • Upgrade OpenStack Cloud Controller Manager to v1.35.0 (#12972, @shuan1026)
    • Upgrade ansible from 10.7.0 to 11.13.0 (#12903, @guoard)
    • Upgrade metrics-server to v0.8.1 (#13189, @mzaian)
    • Use kubeadm:cluster-admins group for admin kubeconfig generation. (#12998, @Srishti-j18)
    • [etcd] Default version to 3.6.10 for Kubernetes 1.35. (#13190, @mzaian)
    • [runc] Default version to 1.4.2. (#13192, @mzaian)

    Design

    • Container engine are now included rather than imported, to avoid lots of always skipped tasks during playbook execution (#12946, @Tushar240503)
    • Network plugins are now included rather than imported, to avoid lots of always skipped tasks during playbook execution (#12933, @Tushar240503)

    Documentation

    • Offline files repo is expected to use original domains as top-level directories. (#12684, @bbaassssiiee)
    • Remove RHEL8 documentation (#13017, @VannTen)

    Bug or Regression

    • Add service RBAC for Calico Kubernetes datastore so Calico can monitor LoadBalancer IP allocation (#12928, @mickenordin)
    • Calico KDD CRDs are now downloaded from https://github.com/projectcalico/calico/blob/master/manifests/crds.yaml instead of the Calico tarball. (#12985, @Srishti-j18)
    • Enable metalink for openEuler repos to auto-select fastest mirror, fixing slow package installs outside China (#13094, @yankay)
    • Fix OCI CCM deployment failure c
  3. v2.26.12026-04-13 · 2026-04-13 05:18 UTC
    查看更新说明

    Changes by Kind

    Feature

    • Default to Kubernetes v1.30.6 (#11673, @robertvolkmann)
    • Bump ingress-nginx to 1.11.5 and certgen to 1.5.2 (#12081, @tico88612)
    • Default to containerd 1.7.23 (#11643, @robertvolkmann)
    • Update runc to v1.1.14 and nerdctl to 1.7.7 (#12817, @rptaylor)

    Bug or Regression

    • Always copy cert generation scripts to first etcd to pick up fixes on existing clusters (#11615, @k8s-infra-cherrypick-robot)
    • Fix: cannot stop & remove all cri containers via remove_node.yml (#11637, @k8s-infra-cherrypick-robot)
    • Fix kubecontrollersconfigurations list permission (#12038, @k8s-infra-cherrypick-robot)
    • Workaround missing etcd certs on control plane node (#12193, @k8s-infra-cherrypick-robot)
    • Move 'pretend certificates' after cert distribution (#12222, @VannTen)
    • Fix manage-offline-container-images.sh get image_id (#12315, @k8s-infra-cherrypick-robot)
    • Fix PodSecurity Admission "empty" definition handling (#12477, @k8s-infra-cherrypick-robot)

    Components

    • kubernetes v1.30.6
    • etcd v3.5.16
    • docker v26.1
    • containerd 1.7.23
    • cri-o v1.30.3
    • cni-plugins v1.2.0
    • calico v3.28.1
    • cilium v1.15.4
    • flannel v0.22.0
    • kube-ovn v1.12.21
    • kube-router v2.0.0
    • multus v3.8
    • weave v2.8.7
    • kube-vip v0.8.0
    • cert-manager v1.14.7
    • coredns v1.11.1
    • ingress-nginx v1.11.5
    • krew v0.4.4
    • argocd v2.11.0
    • helm v3.15.4
    • metallb v0.13.9
    • registry v2.8.1
    • aws-ebs-csi-plugin v0.5.0
    • azure-csi-plugin v1.10.0
    • cinder-csi-plugin v1.30.0
    • gcp-pd-csi-plugin v1.9.2
    • local-path-provisioner v0.0.24
    • local-volume-provisioner v2.5.0
    • node-feature-discovery v0.16.4
  4. v2.30.02026-01-29 · 2026-01-29 18:30 UTC
    查看更新说明

    Announcement

    Ingress NGINX is sunset. This is the final version supporting Ingress NGINX. We'll remove ingress-nginx in future versions. For more information, please see the Kubernetes blog.

    Kubernetes Dashboard is archived. This is the final version supporting Kubernetes Dashboard. We'll remove Kubernetes Dashboard in future versions. For more information, please see the announcement.

    Urgent Upgrade Notes

    (No, really, you MUST read this before you upgrade)

    • Action required containerd_discard_unpacked_layers is now applied only for containerd < 2.1 to avoid warnings with the Transfer Service used in newer versions. (#12821, @guoard)
    • Cilium k8sServiceHost and k8sServicePort are now derived from kube_apiserver_global_endpoint instead of being auto-detected, so users must ensure this endpoint is correctly set and reachable from all nodes. (#12624, @r3m8)

    Changes by Kind

    API Change

    • Removed deprecated runtime_engine and runtime_root keys from containerd configuration. (#12820, @guoard)

    Feature

    • Crio: add option pull_progress_timeout (#12555, @pedro-peter)
    • Fixed kube_vip_version variable for managing kube-vip version instead of kube_vip_image_tag (#12835, @ThisIsQasim)
    • RockyLinux 10 support (experimental) (#12355, @tico88612)
    • Support kubernetes v1.34.1 (#12549, @i-yasuda)
    • The default Openstack security groups now allow ICMPv6 for general IPv6 functionality. (#12805, @rptaylor)
    • Update kube-vip to v1.0.3 (#12815, @LawiK974)
    • Upgrade Gateway API to 1.4.0 (#12714, @tico88612)
    • Upgrade containerd/nerdctl default version to 2.2.1 (#12825, @guoard)
    • contrib/collection.sh will create and install the source as collection. (#12660, @bbaassssiiee)

    Documentation

    • Fix(cilium): prevent installation failure with unprivileged agent (#12628, @r3m8)
    • The default namespace for MetalLB resources is now metallb-system. (#12860, @kittywaresz)

    Bug or Regression

    • Action-required Adding a control plane node in first place is now explicitly unsupported, the new control plane should be placed at the end of your kube_control_plane group (#12636, @clwluvw)
    • Add a wait after control plane joining to prevent a kubeadm preflight error when upgrading the control plane configuration at the same time. (#12794, @VannTen)
    • Deployments using Calico in vxlan mode without eBPF but with localhost load balancers will now work. (#12598, @rickerc)
    • Fix Calico apiserver RBAC permissions for Kubernetes 1.33+ (#12654, @rickerc)
    • Fix Cilium loadBalancer.mode rendering in Kubespray values template. (#12701, @intojhanurag)
    • Fix RBAC for calico using the etcd datastore (#12828, @LawiK974)
    • Fix automatic certs renew with systemd timer (#12876, @VannTen)
    • Fix broken upgrade path/control plane node rotation for cluster using calico in etcd datastore mode with separate etcd. etcd_cert_dir_mode is deleted (always use 0700) (#12908, @VannTen)
    • Fix kubeadm init retry after first failure on cluster creation (#12785, @VannTen)
    • Fix(calico): Add missed rbac verb watch for hostendpoints (#12641, @jmeza-xyz)
    • Fixed an issue in the config.json.j2 template where the CRI-O registry authentication configuration could render invalid JSON when multiple crio_registry_auth entries were defined, resulting in duplicate top-level auths keys in the generated config. (#12845, @accuROAMC)
    • Removing external etcd member (not stacked with control plane) should now work without erroring out because the node is not in the kubernetes cluster (#12682, @VannTen)
    • Update CSI components image version (#12627, @xin053)
    • [feat] Setting timezone under SELinux. (#12436, @bbaassssiiee)
    • apiserver_loadbalancer_domain_name default to loadbalancer_apiserver.address
  5. v2.29.12025-12-11 · 2025-12-11 15:21 UTC
    查看更新说明

    Changes by Kind

    Bug or Regression

    • Fix Calico apiserver RBAC permissions for Kubernetes 1.33+ (#12695, @k8s-infra-cherrypick-robot)
    • Fix Cilium loadBalancer.mode rendering in Kubespray values template. (#12705, @k8s-infra-cherrypick-robot)
    • Fix(calico): Add missed rbac verb watch for hostendpoints (#12644, @k8s-infra-cherrypick-robot)
    • Removing external etcd member (not stacked with control plane) should now work without erroring out because the node is not in the kubernetes cluster (#12685, @k8s-infra-cherrypick-robot)

    Components

    • kubernetes 1.33.7
    • etcd 3.5.25
    • docker 28.3
    • containerd 2.1.5
    • cri-o 1.33.7
    • cni-plugins 1.8.0
    • calico 3.30.5
    • cilium 1.18.4
    • flannel 0.27.3
    • kube-ovn 1.12.21
    • kube-router 2.1.1
    • multus 4.2.2
    • kube-vip 0.8.0
    • cert-manager 1.15.3
    • coredns 1.12.0
    • ingress-nginx 1.13.3
    • argocd 2.14.5
    • helm 3.18.4
    • metallb 0.13.9
    • registry 2.8.1
    • aws-ebs-csi-plugin 0.5.0
    • azure-csi-plugin 1.10.0
    • cinder-csi-plugin 1.30.0
    • gcp-pd-csi-plugin 1.9.2
    • local-path-provisioner 0.0.32
    • local-volume-provisioner 2.5.0
    • node-feature-discovery 0.16.4

用户点评

登录用户的真实使用记录，可按版本和硬件筛选
共 0 条

    还没有人点评。第一个说出真实体验的人最有价值。

    README 原文

    未翻译
    在 GitHub 打开

    Deploy a Production Ready Kubernetes Cluster

    Kubernetes Logo

    If you have questions, check the documentation at kubespray.io and join us on the kubernetes slack, channel #kubespray. You can get your invite here

    • Can be deployed on AWS, GCE, Azure, OpenStack, vSphere, Oracle Cloud Infrastructure (Experimental), or Baremetal
    • Highly available cluster
    • Composable (Choice of the network plugin for instance)
    • Supports most popular Linux distributions
    • Continuous integration tests

    Quick Start

    Below are several ways to use Kubespray to deploy a Kubernetes cluster.

    Docker

    Ensure you have installed Docker then

    docker run --rm -it --mount type=bind,source="$(pwd)"/inventory/sample,dst=/inventory \
  --mount type=bind,source="${HOME}"/.ssh/id_rsa,dst=/root/.ssh/id_rsa \
  quay.io/kubespray/kubespray:v2.31.0 bash
# Inside the container you may now run the kubespray playbooks:
ansible-playbook -i /inventory/inventory.ini --private-key /root/.ssh/id_rsa cluster.yml

    Ansible

    Usage

    See Getting started

    Collection

    See here if you wish to use this repository as an Ansible collection

    Vagrant

    For Vagrant we need to install Python dependencies for provisioning tasks. Check that Python and pip are installed:

    python -V && pip -V

    If this returns the version of the software, you're good to go. If not, download and install Python from here https://www.python.org/downloads/source/

    Install Ansible according to Ansible installation guide then run the following step:

    vagrant up

    Documents

    Supported Linux Distributions

    • Flatcar Container Linux by Kinvolk
    • Debian Bookworm, Trixie
    • Ubuntu 22.04, 24.04, 26.04
    • CentOS Stream / RHEL 9, 10
    • Fedora 39, 40, 41, 42
    • Fedora CoreOS (see fcos Note)
    • openSUSE Leap 16.x/Tumbleweed/MicroOS (containerd only; see openSUSE notes)
    • Oracle Linux 9, 10
    • Alma Linux 9, 10
    • Rocky Linux 9, 10 (experimental in 10: see Rocky Linux 10 notes)
    • Kylin Linux Advanced Server V10 (experimental: see kylin linux notes)
    • Amazon Linux 2 (experimental: see amazon linux notes)
    • UOS Linux (experimental: see uos linux notes)
    • openEuler (experimental: see openEuler notes)

    Note:

    • Upstart/SysV init based OS types are not supported.
    • Kernel requirements (please read if the OS kernel version is < 4.19).

    Supported Components

    Container Runtime Notes

    • The CRI-O minor version should match the Kubernetes minor version.

    Requirements

    • Minimum required version of Kubernetes is v1.35.0

    • Ansible 14 (ansible-core 2.21), Jinja 3.1+ and python-netaddr are installed on the machine that will run Ansible commands

    • The target servers must have access to the Internet in order to pull docker images. Otherwise, additional configuration is required (See Offline Environment)

    • The target servers are configured to allow IPv4 forwarding.

    • If using IPv6 for pods and services, the target servers are configured to allow IPv6 forwarding.

    • The firewalls are not managed, you'll need to implement your own rules the way you used to. in order to avoid any issue during deployment you should disable your firewall.

    • If kubespray is run from non-root user account, correct privilege escalation method should be configured in the target servers. Then the ansible_become flag or command parameters --become or -b should be specified.

    Hardware: These limits are safeguarded by Kubespray. Actual requirements for your workload can differ. For a sizing guide go to the Building Large Clusters guide.

    • Control Plane
      • Memory: 2 GB
    • Worker Node
      • Memory: 1 GB

    Network Plugins

    You can choose among ten network plugins. (default: calico, except Vagrant uses flannel)

    • flannel: gre/vxlan (layer 2) networking.

    • Calico is a networking and network policy provider. Calico supports a flexible set of networking options designed to give you the most efficient networking across a range of situations, including non-overlay and overlay networks, with or without BGP. Calico uses the same engine to enforce network policy for hosts, pods, and (if using Istio and Envoy) applications at the service mesh layer.

    • cilium: layer 3/4 networking (as well as layer 7 to protect and secure application protocols), supports dynamic insertion of BPF bytecode into the Linux kernel to implement security services, networking and visibility logic.

    • kube-ovn: Kube-OVN integrates the OVN-based Network Virtualization with Kubernetes. It offers an advanced Container Network Fabric for Enterprises.

    • kube-router: Kube-router is a L3 CNI for Kubernetes networking aiming to provide operational simplicity and high performance: it uses IPVS to provide Kube Services Proxy (if setup to replace kube-proxy), iptables for network policies, and BGP for ods L3 networking (with optionally BGP peering with out-of-cluster BGP peers). It can also optionally advertise routes to Kubernetes cluster Pods CIDRs, ClusterIPs, ExternalIPs and LoadBalancerIPs.

    • macvlan: Macvlan is a Linux network driver. Pods have their own unique Mac and Ip address, connected directly the physical (layer 2) network.

    • multus: Multus is a meta CNI plugin that provides multiple network interface support to pods. For each interface Multus delegates CNI calls to secondary CNI plugins such as Calico, macvlan, etc.

    • custom_cni : You can specify some manifests that will be applied to the clusters to bring you own CNI and use non-supported ones by Kubespray. See tests/files/custom_cni/README.md and tests/files/custom_cni/values.yamlfor an example with a CNI provided by a Helm Chart.

    The network plugin to use is defined by the variable kube_network_plugin. There is also an option to leverage built-in cloud provider networking instead.

    Ingress Plugins

    • metallb: the MetalLB bare-metal service LoadBalancer provider.

    Community docs and resources

    Tools and projects on top of Kubespray

    CI Tests

    Build graphs

    CI/end-to-end tests sponsored by: CNCF, Equinix Metal, OVHcloud, ELASTX.

    See the test matrix for details.

    相关项目

    同分类里 star 最高的项目
    对比全部 →
    kubernetes
    kubernetes·Go

    生产级的容器编排与调度平台，用来自动化部署、扩缩容和管理跨主机的容器化应用。

    容器编排+4容器 / Kubernetes
    128976+9645kv1.37.22026-11-10 17:04 UTC
    uptime-kuma
    louislam·JavaScript

    自托管的网站与服务可用性监控面板，支持 HTTP、TCP、Ping 等多种探活方式，通过实时图表和告警通知掌握服务宕机情况。

    可用性监控+4容器 / Kubernetes
    93454+1198.7k2.5.92026-11-10 04:49 UTC
    mall
    macrozheng·Java

    基于 Spring Boot + MyBatis 的完整电商系统，含前台商城和后台管理，覆盖商品、订单、会员、促销等模块，用 Docker 容器化部署。

    电商系统+4容器 / Kubernetes
    85031+1930kv1.0.32026-09-15 02:34 UTC
    moby
    moby·Go

    构建容器化系统的开源协作项目，提供可拼装的组件，用来搭建和定制自己的容器平台，也是 Docker 的上游基础。

    容器引擎+3容器 / Kubernetes
    72363+1019kdocker-v29.9.32026-11-10 16:48 UTC