Ansible Role: Kubernetes

This is an Ansible Role that sets up Kubernetes on Linux machines.

Requirements

You need a compatible Container Runtime. It is recommended to use the role for installing geerlingguy.containerd.

Role Variables

Here is a list of available variables with their default values (refer to defaults/main.yml):

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

These are the Kubernetes packages to be installed on the server. You can define a list of package names or specify name and state for more control over package status (e.g., present, absent, latest).

kubernetes_version: '1.25'
kubernetes_version_rhel_package: '1.25.1'

This specifies the minor version of Kubernetes to install. The kubernetes_version is used to fix an apt package version on Debian and in the kubeadm init command (see kubernetes_version_kubeadm). The kubernetes_version_rhel_package must be a specific release for Red Hat / CentOS.

kubernetes_role: control_plane

This variable specifies if the server acts as a Kubernetes control_plane (default) or node. The control plane runs kubeadm init to initialize, while node runs kubeadm join to connect to the control plane.

Configuring kubeadm and kubelet with a config file (recommended)

This role runs kubeadm init with --config <FILE>.

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

This sets the path for <FILE>. If the directory does not exist, it will be created.

The options defined in the file are parsed and should follow the syntax outlined in kubelet-integration and kubeadm-config-file. The role will create the basic structure (apiVersion, kind) of the config file, so don’t define those within the variables. (Refer to templates/kubeadm-kubelet-config.j2).

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

This sets options under kind: InitConfiguration, including kubernetes_apiserver_advertise_address for compatibility with older role versions.

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

Options under kind: ClusterConfiguration, maintaining compatibility with older role versions.

kubernetes_config_kubelet_configuration:
  cgroupDriver: systemd

These options configure kubelet on any nodes during the kubeadm init process. Check the kubelet config file for syntax options.

Note: This is the recommended way to configure kubelet, as many command-line options are deprecated. Depending on your Container Runtime, you may need to set cgroupDriver to cgroupfs if using Docker instead of containerd.

kubernetes_config_kube_proxy_configuration: {}

This allows you to set kubelet's proxy configuration in the KubeProxyConfiguration section.

Configuring kubeadm and kubelet through command-line options

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

Extra arguments for kubelet during startup (deprecated). Use kubernetes_config_kubelet_configuration instead.

kubernetes_kubeadm_init_extra_opts: ""

Extra arguments for kubeadm init when setting up Kubernetes.

kubernetes_join_command_extra_opts: ""

Extra arguments for the generated kubeadm join command when adding nodes.

Additional variables

kubernetes_allow_pods_on_control_plane: true

This decides whether to let pods be deployed to the control plane. Set to True for single-node clusters; otherwise, set to False for a dedicated control plane.

kubernetes_pod_network:
  cni: 'flannel'
  cidr: '10.244.0.0/16'

This role supports flannel, calico, or weave for pod networking. Choose one option; switching between them must be done manually.

kubernetes_apiserver_advertise_address: ''
kubernetes_version_kubeadm: 'stable-{{ kubernetes_version }}'
kubernetes_ignore_preflight_errors: 'all'

Options passed to kubeadm init for setting up the control plane. If left empty, kubernetes_apiserver_advertise_address defaults to ansible_default_ipv4.address.

kubernetes_apt_release_channel: main
kubernetes_apt_repository: "deb http://apt.kubernetes.io/ kubernetes-xenial {{ kubernetes_apt_release_channel }}"
kubernetes_apt_ignore_key_error: false

Apt repository settings for Kubernetes installation.

kubernetes_yum_arch: x86_64
kubernetes_yum_base_url: "https://packages.cloud.google.com/yum/repos/kubernetes-el7-{{ kubernetes_yum_arch }}"
kubernetes_yum_gpg_key:
  - https://packages.cloud.google.com/yum/doc/yum-key.gpg
  - https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg
kubernetes_yum_gpg_check: true
kubernetes_yum_repo_gpg_check: true

Yum repository settings for Kubernetes installation. Adjust the kubernetes_yum_gpg_key if needed for your environment.

kubernetes_flannel_manifest_file: https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml

Flannel manifest to apply to the cluster for networking. You can use your own file if custom configuration is needed.

kubernetes_calico_manifest_file: https://projectcalico.docs.tigera.io/manifests/calico.yaml

Calico manifest to apply to the cluster (if using Calico).

Dependencies

None.

Example Playbooks

Single node (control-plane-only) cluster

- hosts: all

  vars:
    kubernetes_allow_pods_on_control_plane: true

  roles:
    - geerlingguy.docker
    - geerlingguy.kubernetes

Cluster with multiple nodes (single control-plane)

Control plane variables:

kubernetes_role: "control_plane"

Node variables:

kubernetes_role: "node"

Playbook:

- hosts: all

  vars:
    kubernetes_allow_pods_on_control_plane: true

  roles:
    - geerlingguy.docker
    - geerlingguy.kubernetes

Then, log into the Kubernetes control plane, run kubectl get nodes as root, and you should see all the servers listed.

License

MIT / BSD

Author Information

This role was created in 2018 by Jeff Geerling, author of Ansible for DevOps.