cilium-kubernetes

This Ansible role installs the Cilium network on a Kubernetes cluster. It uses the official Helm chart to manage the installation. Currently, it supports installing, upgrading, and removing the Cilium deployment.

Versions

Each release is tagged, following semantic versioning. I recommend using the latest tagged version. The master branch is for development, while tags indicate stable releases. For example, a tag 13.0.0+1.15.3 means it's version 13.0.0 of the role, containing Cilium chart version 1.15.3. Changes in the role will increase the version before the +, while changes to the Cilium chart version will increase the version after the +.

Requirements

You need to have Helm 3 installed on the host running ansible-playbook or on the delegated host (using cilium_delegate_to variable). You can:

• Use your system's package manager if it includes helm (for Archlinux: sudo pacman -S helm).
• Use one of the Ansible Helm roles (e.g., helm, which installs if you run ansible-galaxy role install -vr requirements.yml).
• Download the binary directly from Helm releases and place it in /usr/local/bin/.

Make sure you have a properly set up KUBECONFIG file (usually at ${HOME}/.kube/config). If kubectl works with your cluster, you should be good to go.

You'll also need to install the Ansible kubernetes.core collection using the collections.yml file included in this role: ansible-galaxy install -r collections.yml.

And, of course, you need a Kubernetes Cluster. ;-)

Installation

• Download directly from GitHub (navigate to the Ansible roles directory before cloning): git clone https://github.com/githubixx/ansible-role-cilium-kubernetes.git githubixx.cilium_kubernetes

• Use ansible-galaxy to directly download from Ansible Galaxy: ansible-galaxy install role githubixx.cilium_kubernetes

• Create a requirements.yml file with the following content to download the role from GitHub and install it with ansible-galaxy role install -r requirements.yml (change version as needed):

---
roles:
  - name: githubixx.cilium_kubernetes
    src: https://github.com/githubixx/ansible-role-cilium-kubernetes.git
    version: 13.0.0+1.15.3

Changelog

Change history:

For full details, check the CHANGELOG.md.

Recent changes:

13.0.0+1.15.3

Breaking

• Changes in templates/cilium_values_default.yml.j2:
  • Added kubeProxyReplacement, nodePort, and socketLB (needed for BPF masquerade with NodePort).

Update

• Upgraded to Cilium v1.15.3.

Molecule

• Replaced Vagrant generic/ubuntu2204 boxes with alvistack/ubuntu-22.04.

12.0.0+1.15.0

• Upgraded to Cilium v1.15.0.
• Refactored Molecule setup.
• Introduced cilium_chart_values_directory variable.

Role Variables

# Helm chart version
cilium_chart_version: "1.15.3"

# Helm chart name
cilium_chart_name: "cilium"

# Helm chart URL
cilium_chart_url: "https://helm.cilium.io/"

# Kubernetes namespace for Cilium resources
cilium_namespace: "cilium"

# Directory for Helm chart values file
cilium_chart_values_directory: "/tmp/cilium/helm"

# etcd settings
cilium_etcd_enabled: "true"
cilium_etcd_interface: "eth0"
cilium_etcd_client_port: 2379
cilium_etcd_nodes_group: "k8s_etcd"
cilium_etcd_secrets_name: "cilium-etcd-secrets"
cilium_etcd_cert_directory: "{{ '~/k8s/certs' | expanduser }}"
cilium_etcd_cafile: "ca-etcd.pem"
cilium_etcd_certfile: "cert-cilium.pem"
cilium_etcd_keyfile: "cert-cilium-key.pem"

# Delegate tasks to a different host if needed
cilium_delegate_to: 127.0.0.1

# Show executed Helm commands in logs
cilium_helm_show_commands: false

# Output directory for rendered template
cilium_template_output_directory: "{{ '~/cilium/template' | expanduser }}"

Usage

First, check templates/cilium_values_default.yml.j2 for the values/settings for the Cilium Helm chart. The default settings use a TLS-enabled etcd cluster. If you have a self-hosted Kubernetes cluster, you might already have an etcd cluster running. My Ansible roles can help set up this etcd cluster with certificates.

You can adjust settings in templates/cilium_values_default.yml.j2. To use your own values, create a values.yml.j2 or values.yaml.j2 in the directory defined by cilium_chart_values_directory.

After setting up the values file and checking defaults/main.yml, you can install the role. Most tasks run locally by default, but you can delegate tasks using the cilium_delegate_to variable.

To render the resources YAML file, use the following command (replace k8s.yml with your playbook name):

ansible-playbook --tags=role-cilium-kubernetes k8s.yml

To change the output directory for the YAML file, specify cilium_template_output_directory:

ansible-playbook --tags=role-cilium-kubernetes --extra-vars cilium_template_output_directory="/tmp/cilium" k8s.yml

To see Helm command logs, add --extra-vars cilium_helm_show_commands=true.

To install Cilium after verifying the output is correct:

ansible-playbook --tags=role-cilium-kubernetes --extra-vars cilium_action=install k8s.yml

Check if everything was deployed with standard kubectl commands, like:

kubectl -n <cilium_namespace> get pods -o wide

To upgrade Cilium, use:

ansible-playbook --tags=role-cilium-kubernetes --extra-vars cilium_action=upgrade k8s.yml

If an upgrade fails, you can roll back to a previous version by changing the cilium_chart_version variable. However, please refer to the Cilium documentation for guidelines on rollbacks.

To delete Cilium completely:

ansible-playbook --tags=role-cilium-kubernetes --extra-vars cilium_action=delete k8s.yml

If no CNI plugins are configured, be aware that you might receive CNI errors from kubelet on the worker nodes after deletion.

Example Playbook

Example 1 (without role tag):

- hosts: k8s_worker
  roles:
    - githubixx.cilium_kubernetes

Example 2 (assign tag to role):

- hosts: k8s_worker
  roles:
    - role: githubixx.cilium_kubernetes
      tags: role-cilium-kubernetes

Testing

This role includes a test setup using Molecule, libvirt (vagrant-libvirt), and QEMU/KVM. For setup details, see my blog Testing Ansible roles with Molecule, libvirt (vagrant-libvirt) and QEMU/KVM.

To create a template of the resources:

molecule converge

To install Cilium:

molecule converge -- --extra-vars cilium_action=install

To upgrade Cilium:

molecule converge -- --extra-vars cilium_action=upgrade

To delete Cilium:

molecule converge -- --extra-vars cilium_action=delete

To run tests, use the following (add -v for more output):

molecule verify

To clean up, run:

molecule destroy

License

GNU GENERAL PUBLIC LICENSE Version 3

Author Information

http://www.tauceti.blog