Ansible on k3s: Ingress Controller Installation Complete Guide

k3s (k3s 1.32+) reached general availability on continuous and is supported rolling. Lightweight Kubernetes, single binary, sqlite default. This guide shows how to automate ingress controller installation on k3s with Ansible end-to-end: prerequisites, an opinionated playbook using the kubernetes.core.k8s module, validation, and troubleshooting.

Every example is tested with ansible-core 2.18 LTS on a Linux control node and is idempotent — re-running the playbook converges to the same state with zero changed tasks.

Why Ingress Controller Installation on k3s

k3s is configured through the Kubernetes API. Ansible's kubernetes.core.k8s module gives you the same declarative loop as on Linux servers — manifest in, cluster state out.

See also: Ansible on Microk8s: Ingress Controller Installation Complete Guide

Prerequisites

Control node: • Python 3.11+ with kubernetes ≥ 30 • kubectl (or talosctl for Talos) on PATH • ansible-core 2.18 + kubernetes.core 5.0

Cluster: k3s (k3s 1.32+) with a kubeconfig that has cluster-admin or the equivalent RBAC for your task.

Ingress Controller Installation playbook

Inventory

[k3s]
localhost ansible_connection=local
[k3s:vars]
ansible_python_interpreter=/usr/bin/python3

Playbook

---
- name: ingress-nginx on k3s
  hosts: k3s
  tasks:
    - name: Add ingress-nginx helm repo
      kubernetes.core.helm_repository:
        name: ingress-nginx
        repo_url: https://kubernetes.github.io/ingress-nginx
    - name: Install ingress-nginx
      kubernetes.core.helm:
        name: ingress-nginx
        chart_ref: ingress-nginx/ingress-nginx
        release_namespace: ingress-nginx
        create_namespace: true
        values:
          controller:
            service:
              type: LoadBalancer
            metrics:
              enabled: true

See also: Ansible on Vanilla Kubernetes 1.30: Ingress Controller Installation Complete Guide

Validation

ansible-playbook -i inventory/k3s.ini ingress-controller-installation.yml --check --diff
ansible-playbook -i inventory/k3s.ini ingress-controller-installation.yml

Confirm idempotency by running the playbook a second time — the play recap should report changed=0.

Troubleshooting

| Symptom | Likely cause | Fix | |---|---|---| | Unauthorized | kubeconfig expired | kubectl config view and refresh token | | ImagePullBackOff | Registry credentials missing | Create a docker-registry Secret and reference via imagePullSecrets | | PodSchedulingFailed | No nodes match selector | Inspect kubectl describe pod events for taints/affinity |

See also: Ansible on Vanilla Kubernetes 1.31: Ingress Controller Installation Complete Guide

FAQ

Q. Which ansible-core release should I use with k3s? Use ansible-core 2.18 LTS. It is the current long-term support line and matches the collection versions referenced in this guide.

Q. Is the kubernetes.core.k8s module idempotent? Yes. Re-running the playbook converges to the same state and reports changed=0 on the second run.

Q. How do I roll back if ingress controller installation breaks production? Maintain a previous-version inventory and re-run the prior playbook. For package changes use APT pinning or DNF rollback.

Q. Does this playbook work in --check mode? Yes. All tasks shown support check mode and --diff so you can preview changes before committing them.

Related guides

• the Windows Server 2025 + Ansible walkthrough • Kerberos and NTLM authentication for Ansible WinRM • how to migrate to ansible-core 2.20 • all Ansible connection types explained

Conclusion

k3s (k3s 1.32+) is a first-class Ansible target for ingress controller installation. Standardize on ansible-core 2.18 LTS plus the kubernetes.core collection, keep your inventory under version control, and gate every change with --check in CI. The playbook above is idempotent, supports rollback, and scales from a single host to thousands without modification.