Ansible Role: Kubernetes

This is an Ansible Role that helps you install Kubernetes on Linux systems.

Requirements

You need a compatible Container Runtime. For installing the Container Runtime, it's recommended to use the role: geerlingguy.containerd.

Role Variables

Here are the variables you can use, along with their default values (found in 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 that will be installed on your server. You can list package names or control their states (like present, absent, or latest).

kubernetes_version: '1.25'
kubernetes_version_rhel_package: '1.25.1'

Specify the minor version of Kubernetes to install. Use kubernetes_version for Debian systems and kubernetes_version_rhel_package for Red Hat / CentOS servers.

kubernetes_role: control_plane

Determine what role the server will play: as a control_plane (default) or a node. The control plane will be initialized with kubeadm init, while nodes will join it with kubeadm join.

Configuring kubeadm and kubelet using a config file (recommended)

This role will run kubeadm init with --config <FILE>:

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

This is the path for the config file. If it doesn't exist, the role will create it.

Below are options for the config file. Its structure is defined by Kubernetes, so don't include apiVersion or kind within the variables. (See templates/kubeadm-kubelet-config.j2).

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

Defines settings under kind: InitConfiguration.

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

Defines options under kind: ClusterConfiguration.

kubernetes_config_kubelet_configuration:
  cgroupDriver: systemd

Sets kubelet configuration during the kubeadm init process. For details, check the kubelet config file documentation.

NOTE: This method is recommended for kubelet configuration. Other command-line options may become outdated.

kubernetes_config_kube_proxy_configuration: {}

Options for kubelet's proxy configuration.

Configuring kubeadm and kubelet through command-line options

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

Extra arguments for the kubelet during startup (deprecated—use kubernetes_config_kubelet_configuration instead).

kubernetes_kubeadm_init_extra_opts: ""

Extra arguments for kubeadm init when starting the Kubernetes control plane.

kubernetes_join_command_extra_opts: ""

Extra arguments for the kubeadm join command when starting nodes.

Additional Variables

kubernetes_allow_pods_on_control_plane: true

Allows or prevents pods from being deployed on the Kubernetes control plane. Set to True for single-node clusters, otherwise set to False.

kubernetes_pod_network:
  cni: 'flannel'  # Choose one: 'flannel', 'calico', or 'weave'
  cidr: '10.244.0.0/16'

This role supports networking options for Kubernetes clusters. Choose only one option for your cluster.

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

Options for kubeadm init when starting the Kubernetes control plane.

kubernetes_apt_release_channel: "stable"
kubernetes_apt_keyring_file: "/etc/apt/keyrings/kubernetes-apt-keyring.asc"
kubernetes_apt_repository: "deb [signed-by={{ kubernetes_apt_keyring_file }}] https://pkgs.k8s.io/core:/{{ kubernetes_apt_release_channel }}:/v{{ kubernetes_version }}/deb/ /"

Apt repository settings for Kubernetes installation.

kubernetes_yum_base_url: "https://pkgs.k8s.io/core:/stable:/v{{ kubernetes_version }}/rpm/"
kubernetes_yum_gpg_key: "https://pkgs.k8s.io/core:/stable:/v{{ kubernetes_version }}/rpm/repodata/repomd.xml.key"
kubernetes_yum_gpg_check: true
kubernetes_yum_repo_gpg_check: true

Yum repository settings for Kubernetes installation.

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

Manifest file for Flannel networking in the Kubernetes cluster.

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

Manifest file for Calico networking (if using).

Dependencies

None.

Example Playbooks

Single node cluster (control-plane only)

- hosts: all

  vars:
    kubernetes_allow_pods_on_control_plane: true

  roles:
    - geerlingguy.docker
    - geerlingguy.kubernetes

Multi-node cluster (single control-plane)

Control plane settings:

kubernetes_role: "control_plane"

Node(s) settings:

kubernetes_role: "node"

Playbook example:

- hosts: all

  vars:
    kubernetes_allow_pods_on_control_plane: true

  roles:
    - geerlingguy.docker
    - geerlingguy.kubernetes

After running the playbook, log into the Kubernetes control plane and run kubectl get nodes as root to see a list of all nodes.

License

MIT / BSD

Author Information

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