ansible-role-kubernetes and the case for configuring kubeadm through a file

One role, two roles, depending on the machine

This is an Ansible role that installs Kubernetes on Linux, and the first thing it asks you to decide is what kind of machine each target is.

The variable that does it is kubernetes_role:

kubernetes_role: control_plane

Whether the particular server will serve as a Kubernetes control_plane, which is the default, or as a node. The control plane will have kubeadm init run on it to initialize the entire K8s control plane, while nodes will have kubeadm join run on them to join the control plane. So one role covers both the bootstrap of a cluster and the addition of members to it, and the difference is a single string.

The prerequisites are a compatible container runtime, with the recommended role for CRI installation given as geerlingguy.containerd. That recommendation is a real constraint on how you use the role, since a CRI has to exist before Kubernetes can be installed on top of it, and this role does not install one for you.

The packages themselves are configured as a list:

kubernetes_packages:
  - name: kubelet
    state: present
  - name: kubectl
    state: present
  - name: kubeadm
    state: present
  - name: kubernetes-cni
    state: present

You can either provide a list of package names, or set name and state to have more control over whether the package is present, absent, latest, and so on. The version is pinned separately, twice, for two different distributions:

kubernetes_version: '1.32'
kubernetes_version_rhel_package: '1.32'

The plain kubernetes_version is used to pin an apt package version on Debian, and as the Kubernetes version passed into the kubeadm init command. The rhel_package variable must be a specific Kubernetes release and is used to pin the version on Red Hat and CentOS servers.

The config file path is the recommended route

The role's central design decision is the one that shapes everything else, and it is stated as recommended.

With this role, kubeadm init will be run with --config pointing at a file, and the path is:

kubernetes_kubeadm_kubelet_config_file_path: '/etc/kubernetes/kubeadm-kubelet-config.yaml'

The path is the value of the file argument, and if the directory does not exist the role will create it.

The role then parses a set of variables as options for that file, and the documentation links to the kubelet integration and the kubeadm config file reference for the syntax. The skeleton, meaning the apiVersion and kind fields, is created by the role, so you should not define them within the variables. The template that does it is named in the documentation as templates/kubeadm-kubelet-config.j2.

There are four configuration sections, and each one is a variable tree that maps onto a named part of the kubeadm config. The init configuration:

kubernetes_config_init_configuration:
  localAPIEndpoint:
    advertiseAddress: "{{ kubernetes_apiserver_advertise_address | default(ansible_default_ipv4.address, true) }}"

The cluster configuration:

kubernetes_config_cluster_configuration:
  networking:
    podSubnet: "{{ kubernetes_pod_network.cidr }}"
  kubernetesVersion: "{{ kubernetes_version_kubeadm }}"

The kubelet configuration:

kubernetes_config_kubelet_configuration:
  cgroupDriver: systemd

And the kube-proxy configuration, which is empty by default:

kubernetes_config_kube_proxy_configuration: {}

The kubelet section is the one with a dependency worth noticing. The documentation says the recommended cgroupDriver depends on your container runtime, and that when using the role with Docker instead of containerd this value should be changed to cgroupfs. Getting that wrong produces a cluster whose nodes come up but fail to run containers correctly, which is a miserable thing to debug.

The deprecated flags are still there, and that is the point

Alongside the recommended config file route, the role keeps the older command line variables, and it is honest about their status.

The kubelet extra arguments are:

kubernetes_kubelet_extra_args: ""
kubernetes_kubelet_extra_args_config_file: /etc/default/kubelet

The description gives two concrete uses, allowing kubelet to start up even if swap is enabled on the server with the fail-swap-on flag set to false, and specifying the node IP advertised by kubelet with a node-ip value templated from the host. Then the note: this option is deprecated, please use kubernetes_config_kubelet_configuration instead. Elsewhere the documentation says the same about the kubelet configuration approach, that it is the recommended way and that most command-line options are deprecated.

The other two deprecated variables are for the bootstrap commands:

kubernetes_kubeadm_init_extra_opts: ""

for extra arguments to kubeadm init during control plane initialization, with the example of specifying extra Subject Alternative Names for the API server certificate, and:

kubernetes_join_command_extra_opts: ""

for extra arguments passed to the generated kubeadm join command during node initialization, with the example of ignoring certain preflight errors like swap being enabled.

Keeping these is a deliberate choice for existing users rather than an oversight, and the documentation is explicit that the config file variables are what new setups should use.

The CNI choice is a one-way door in this role

Pod networking is the choice in this role that has the clearest warning attached to it, and the warning is worth reading before anything else.

The pod network is configured as a single block with the three supported options and their ranges:

kubernetes_pod_network:
  # Flannel CNI.
  cni: 'flannel'
  cidr: '10.244.0.0/16'
  #
  # Calico CNI.
  # cni: 'calico'
  # cidr: '192.168.0.0/16'
  #
  # Weave CNI.
  # cni: 'weave'
  # cidr: '192.168.0.0/16'

Flannel is the default and the only one enabled out of the box, with Calico and Weave present as commented alternatives. The instruction is to choose only one for your cluster, and then the reason: converting between them is not done automatically and could result in broken networking, so if you need to switch from one to another it should be done outside of this role.

That is a real limitation and a sensible one to state. A CNI migration touches every node's on-disk state, so a role that silently rewrote the configuration would be doing something dangerous, and the documentation chooses to tell you the migration is not its job.

There is one more cluster-level setting that decides whether the control plane runs workloads:

kubernetes_allow_pods_on_control_plane: true

This controls whether the taint that denies pods from being deployed to the Kubernetes control plane is removed. For a single-node cluster the documentation says this should definitely be true, and for anything else you set it to false if you want a dedicated control plane that does not run other pods.

The repository structure, and the release tag that lags the code

The repository is laid out the way Ansible roles are, and that structure is worth naming because it tells you where to look.

There is a defaults/ directory holding the variables and their defaults, vars/ for other variables, tasks/ for the task files, handlers/ for handlers, templates/ for the Jinja templates including the one that builds the kubeadm config, meta/ for role metadata, molecule/ for the test scenarios, and a vars/ area with the apt repository settings. There is a .ansible-lint configuration and a .yamllint configuration, both of which say the project is linted rather than merely written, and a CI workflow that runs on every change.

The primary language recorded for the repository is Jinja, which is a reasonable marker for a role whose main output is templated configuration files.

The release history is where the picture gets complicated. The only listed release is 4.0.2, dated 2020-03-19, which means the published role in Ansible Galaxy is many years behind the code in the repository. The last push to the repository was on 2026-09-08, so the code is being worked on.

The apt repository settings are also worth reading, because they are how the packages get installed at all:

kubernetes_apt_release_channel: "stable"
kubernetes_apt_repository: "https://pkgs.k8s.io/core:/{{ kubernetes_apt_release_channel }}:/v{{ kubernetes_version }}/deb/"

That is the official Kubernetes package repository, addressed by release channel and version, which is the correct source for the pinned packages the role installs.

Where this role is the wrong choice

The first case is a team that does not already run Ansible. The role assumes an existing playbook structure, an inventory and a set of group variables, and it is a component rather than a project. Adopting it to install one cluster means adopting Ansible too.

The second is a managed control plane. Everything here is about bootstrapping nodes with kubeadm, and a team using a hosted Kubernetes service has no use for any of it.

The third is a cluster lifecycle beyond installation. The role installs and joins. It does not upgrade a cluster, it does not manage add-ons, it does not rotate certificates, and it does not tell you whether the cluster is healthy. A team that wants those things wants a different set of tooling, and pairing this role with a good deployment tool is usually the honest answer.

The fourth is the network choice, and this one is the sharpest. Because switching CNI is explicitly outside the role, a team that picks the wrong network on the first run has a manual migration ahead of it. The default of Flannel is reasonable, but it is a default, not a recommendation, and the documentation does not pretend otherwise.

A last practical note. The Galaxy release being from 2020 while the repository is current means you have to decide whether to install the published version or to point at the repository, and that decision should be made deliberately rather than by default.

Editorial conclusion

ansible-role-kubernetes suits a team that already runs Ansible and wants Kubernetes nodes built reproducibly, because the role pins the package version, drives kubeadm through a documented config file, and keeps the command line variables only for backward compatibility. It does not suit a team that wants a hosted control plane, and it does not suit someone who expects the role to manage the cluster after bootstrap, since it installs rather than operates. Before you use it, read the CNI section, because switching pod networks is explicitly not done by this role, and note that the last push was on 2026-09-08 while the newest listed release is 4.0.2 from 2020-03-19.

Frequently asked questions

Official sources

1. geerlingguy/ansible-role-kubernetes on GitHub
2. License: MIT
3. Project website
4. README
5. Releases