DEV Community

Guilherme Diniz
Guilherme Diniz

Posted on

Automating RKE2 and Rancher Deployments with Ansible

#devops #kubernetes #rancher #rke2

Modern infrastructure management is all about automation. The more we can replace manual steps with reliable, repeatable code, the easier it becomes to scale and maintain complex environments. One of the most powerful tools for this task is Ansible.

In this post, I’ll explain what Ansible is, why it matters, and how I’ve used it to automate the deployment of RKE2 (Rancher Kubernetes Engine 2) and Rancher, creating a reproducible and streamlined setup.

What is Ansible?

Ansible is an open-source automation tool that allows you to manage systems, deploy applications, and orchestrate IT environments using simple, human-readable configuration files called playbooks.

Some key concepts:

  • Agentless: Unlike many configuration management tools, Ansible does not require any agent running on target nodes. It connects via SSH.
  • Idempotency: Running the same playbook multiple times will always bring the system to the desired state, without introducing unwanted changes.
  • Infrastructure as Code (IaC): Your infrastructure configuration is stored in version control, making it transparent, shareable, and auditable.

What the Project Does

The repository ansible-rke-rancher provides Ansible playbooks to:

1. Provision RKE2 (Kubernetes)

  • Automates installation of the RKE2 components across master and worker nodes.
  • Handles the cluster configuration and setup consistently.

2. Deploy Rancher

  • Installs Rancher, a popular Kubernetes management platform, on top of the cluster.
  • Simplifies cluster lifecycle management with a centralized UI and APIs.

3. Infrastructure Automation

  • Uses Ansible inventory to define your nodes (masters and workers).
  • Runs repeatable tasks for installing dependencies, configuring users, and setting up the environment.

In short, the project takes what would normally be a complex, error-prone set of manual steps and turns it into a single automated workflow.

Why This Matters

Deploying Kubernetes manually can be time-consuming and difficult, especially if you need consistency across multiple environments (e.g., dev, staging, and production). By leveraging Ansible:

  • You gain repeatability — the same playbook works across environments.
  • You improve scalability — adding new nodes or clusters is easier.
  • You reduce human error — no more missed configuration steps.

Get Started

You can explore the project here:
👉 GitHub: ansible-rke-rancher

The repository includes playbooks and instructions to help you quickly bootstrap a Rancher-managed RKE2 cluster using Ansible.

What the repo is / goals

  • It’s an Ansible playbook set to configure an RKE2 cluster and install Rancher on it using a custom root CA.
  • Tested on EL-family Linux distros (Rocky Linux 9 etc.)
  • Presumes some prerequisites: public SSH keys in hosts, Internet connectivity, that a custom CA is already set up, etc.

So the basic idea is: you point Ansible at some hosts (masters + workers), it sets up RKE2 cluster, then installs Rancher with TLS (with your own certs), to give you a usable Kubernetes + Rancher deployment in an automated, repeatable way.

Core structure: inventory, playbooks, roles

Here are the main parts of the repo (and what they do):

inventory/hosts.yml Defines the nodes: IPs, hostnames, roles (masters / workers) over which Ansible will run.

playbook/ Contains two main playbooks: one for initializing / building the cluster (init-cluster.yml) and one for installing Rancher (install-rancher.yml) after the cluster is up.

ansible.cfg Configuration for Ansible – SSH settings, privilege escalation, etc.

requirements.yml Declares any Ansible roles / collections needed (external dependencies)

Within the playbooks, there are roles that divide up the work. According to the README, the RKE2 related work is divided into these roles:_ Init, Principal, Masters, Agents_.

What the roles do

Here’s what each role is responsible for (based on the README and code):

  • Init
    Runs on all hosts. Prepares the base environment so the RKE2 cluster can function. Tasks include: configuring firewall (firewalld), kernel modules, updating packages, ensuring things needed generally are in place. These tasks ensure consistency and that preconditions are met.

  • Principal
    The “principal master” node is like the first control-plane node. This node gets some extra services installed (beyond what other masters get), because Rancher + RKE2 needs a control-plane to bootstrap from.

  • Masters
    All other master nodes (i.e. not the principal one) or nodes you later add as masters. They will join the cluster, obtaining necessary tokens (node-token etc.) from the principal node. Their configuration is done so that they are control-plane nodes.

  • Agents
    The worker nodes. They join the cluster as agents (workers). They get the node token, and the necessary configuration to communicate with the cluster. (GitHub)

After RKE2 cluster is up (i.e. masters + agents are configured), there’s a separate playbook to install Rancher:

  • install-rancher.yml This playbook takes care of installing Rancher on top of the RKE2 cluster. It uses certificates from a certs/tls-rancher folder: you supply a CA, internal CA, additional CA trust, the Rancher TLS key/cert, etc. (GitHub)

Variables / configuration

Key configuration aspects you can control, via variables / inventory, include:

  • Which hosts are masters vs workers. The inventory file allows specifying which hosts are in each group.
  • Which host is the “principal master”. The role “Principal” is used for that specific host. This is needed for bootstrapping.
  • TLS certs: you bring your own certificate authority root, and your own TLS certs for Rancher’s HTTPS endpoint. The playbook expects them in certain paths.
  • OS distribution is expected to be RHEL/Oracle/SUSE/Alma/Rocky‐Linux etc.

Sequence / workflow

Here’s the order in which things happen, roughly:

  1. Define your hosts in inventory/hosts.yml. Specify which hosts are masters, which are workers. Also mark one host as principal/master (probably via group vars).
  2. Make sure prerequisites are met: SSH access, custom CA, certs in place, OS versions, etc.
  3. Run the cluster init: 
ansible-playbook -i inventory/hosts.yml playbook/init-cluster.yml
Enter fullscreen mode Exit fullscreen mode
  • This runs the Init role on all hosts
  • On principal: runs Principal role
  • On other masters: Masters
  • On agents/workers: Agents

That sets up RKE2, ensures control-plane, etc.

  1. Once the cluster is up, prepare the certs for Rancher: in certs/tls-rancher you have CA root, internal CA, etc.
  2. Then run: 
ansible-playbook -i inventory/hosts.yml playbook/install-rancher.yml
Enter fullscreen mode Exit fullscreen mode

This installs Rancher on the cluster, using the TLS certificates you provided, integrating with the custom CA where needed.

Final Thoughts

Infrastructure automation is not just a convenience — it’s a necessity for modern DevOps and cloud-native teams. With tools like Ansible, we can codify best practices, enforce consistency, and focus more on delivering value instead of fighting configuration drift.

This project is a step toward that goal: automating Kubernetes cluster provisioning and Rancher deployment with Ansible.

If you’re interested in Kubernetes, Rancher, or Ansible, I encourage you to check out the repo, try it out, and even contribute!

Via Guilherme Diniz

Top comments (0)