# lablabs/ansible-role-rke2 architecture

> Architecture diagram of the GitHub repository lablabs/ansible-role-rke2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lablabs/ansible-role-rke2
- Repository: https://github.com/lablabs/ansible-role-rke2

## Overview

##### Project type and purpose
- This is an open-source Ansible Role named “ansible-role-rke2” whose purpose is to automate the installation and configuration of RKE2 Kubernetes clusters in various modes (single node, multi-node cluster, HA cluster, air-gapped).
- The README confirms that it deploys the RKE2 control plane (masters/servers) and agents (workers), configures HA using Keepalived or Kube-VIP, and supports rolling upgrades, CIS benchmarking, custom manifests, etc.

##### File structure
- Top-level CI and governance:
- .github/ (workflows for CI, linting, release drafting, issue/PR templates)
- molecule/ (integration tests in scenarios: cluster, default, ha_cluster, ha_cluster_kubevip)
- requirements.yml, .pre-commit-config.yaml
- Role implementation:
- defaults/main.yml – default variables and feature flags
- vars/main.yml – supplementary variables
- tasks/main.yml + sub-tasks (rke2, cis, ha, rolling_restart, summary, etc.)
- handlers/main.yml – handler definitions for service restarts or notifications
- templates/ – Jinja2 templates for config.yaml, registries.yaml, keepalived, kube-vip manifests, shell checks
- meta/main.yml & argument_specs.yml – role metadata and parameter specs
- Molecule scenarios invoke the role with different inventories and converge/verify steps.

##### Key architecture insights from README
- The role uses inventory groups (masters, workers, children of k8s_cluster) to determine node type.
- It installs RKE2 via tarball, applies tokens, sets up networking, CNI, optional load-balancer with keepalived or kube-vip.
- Supports air-gap via artifact download/copy/exists, snapshots/restore, custom manifests, taints, proxies, etc.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Controller Layer
    subgraph "Ansible Controller" 
        direction TB
        Controller["Ansible Controller"]:::controller
        Inventory["Inventory & Group_vars"]:::controller
        Controller --> Inventory
    end

    %% Role Modules
    subgraph "ansible-role-rke2 Role" 
        direction TB
        Defaults["Defaults & Feature Flags"]:::role
        Vars["Supplementary Variables"]:::role
        TasksDispatcher["Task Dispatcher"]:::role
        Templates["Jinja2 Templates"]:::role
        Handlers["Service Handlers"]:::role
        Meta["Role Metadata & Parameter Specs"]:::role

        Controller --> TasksDispatcher
        Inventory --> Defaults
        Inventory --> Vars
        TasksDispatcher --> Defaults
        TasksDispatcher --> Vars
        TasksDispatcher --> Templates
        Templates --> Defaults
        Templates --> Vars
        TasksDispatcher --> Handlers
        TasksDispatcher --> Meta
    end

    %% Task Modules
    subgraph "Task Modules" 
        direction TB
        RKE2["RKE2 Installation & Configuration"]:::role
        FirstInit["First Server Initialization"]:::role
        Restore["First Server Restore"]:::role
        JoinLogic["Remaining Nodes Join Logic"]:::role
        ActiveDiscovery["Active Server Discovery"]:::role
        Kubeconfig["Kubeconfig Download"]:::role
        Ingress["Ingress-Nginx Setup"]:::role
        Keepalived["HA with Keepalived"]:::role
        KubeVIP["HA with Kube-VIP"]:::role
        CIS["CIS Benchmarking Checks"]:::role
        ChangeConfig["Configuration Changes"]:::role
        RollingUpgrade["Rolling Upgrade Handler"]:::role
        Summary["Summary Reporting"]:::role

        TasksDispatcher --> RKE2
        TasksDispatcher --> FirstInit
        TasksDispatcher --> Restore
        TasksDispatcher --> JoinLogic
        TasksDispatcher --> ActiveDiscovery
        TasksDispatcher --> Kubeconfig
        TasksDispatcher --> Ingress
        TasksDispatcher --> Keepalived
        TasksDispatcher --> KubeVIP
        TasksDispatcher --> CIS
        TasksDispatcher --> ChangeConfig
        TasksDispatcher --> RollingUpgrade
        TasksDispatcher --> Summary

        RKE2 -->|"notify"| Handlers
        ChangeConfig -->|"notify"| Handlers
        RollingUpgrade -->|"notify"| Handlers
    end

    %% Templates Detailed
    subgraph "Templates" 
        direction TB
        ConfigYAML["config.yaml.j2"]:::role
        Registries["registries.yaml.j2"]:::role
        KubeletCfg["kubelet-config.yaml.j2"]:::role
        EnvFile["rke2_environment.j2"]:::role
        CheckAPIServer["check_apiserver.sh.j2"]:::role
        CheckServer["check_rke2server.sh.j2"]:::role
        IngressTemplate["ingress-nginx-config.yml.j2"]:::role
        KeepalivedTpl["keepalived.conf.j2"]:::role
        KubeVIPTpl["kube-vip templates"]:::role

        Templates --> ConfigYAML
        Templates --> Registries
        Templates --> KubeletCfg
        Templates --> EnvFile
        Templates --> CheckAPIServer
        Templates --> CheckServer
        Ingress --> IngressTemplate
        Keepalived --> KeepalivedTpl
        KubeVIP --> KubeVIPTpl
    end

    %% Target Nodes
    subgraph "Target Nodes" 
        direction TB
        Masters["Masters Group"]:::target
        Workers["Workers Group"]:::target
        Controller -->|SSH| Masters
        Controller -->|SSH| Workers
        RKE2 --> Masters
        JoinLogic --> Workers
        CIS --> Masters
        CIS --> Workers
    end

    %% External Services
    subgraph "External Services" 
        direction TB
        KeepalivedSvc["Keepalived VIP"]:::external
        KubeVIPSvc["Kube-VIP"]:::external
        Registry["Container Registry / Artifacts"]:::external
        Masters --> KeepalivedSvc
        Masters --> KubeVIPSvc
        RKE2 --> Registry
    end

    %% CI/CD & Testing
    subgraph "CI/CD & Testing" 
        direction TB
        GitHubActions["GitHub Actions Workflows"]:::ci
        Molecule["Molecule Integration Tests"]:::ci
        GitHubActions --> Molecule
        Molecule --> Controller
    end

    %% Click Events
    click Defaults "https://github.com/lablabs/ansible-role-rke2/blob/main/defaults/main.yml"
    click Vars "https://github.com/lablabs/ansible-role-rke2/blob/main/vars/main.yml"
    click TasksDispatcher "https://github.com/lablabs/ansible-role-rke2/blob/main/tasks/main.yml"
    click RKE2 "https://github.com/lablabs/ansible-role-rke2/blob/main/tasks/rke2.yml"
    click FirstInit "https://github.com/lablabs/ansible-role-rke2/blob/main/tasks/first_server.yml"
    click Restore "https://github.com/lablabs/ansible-role-rke2/blob/main/tasks/first_server_restore.yml"
    click JoinLogic "https://github.com/lablabs/ansible-role-rke2/blob/main/tasks/remaining_nodes.yml"
    click ActiveDiscovery "https://github.com/lablabs/ansible-role-rke2/blob/main/tasks/find_active_server.yml"
    click Kubeconfig "https://github.com/lablabs/ansible-role-rke2/blob/main/tasks/download_kubeconfig.yaml"
    click Ingress "https://github.com/lablabs/ansible-role-rke2/blob/main/tasks/ingress-nginx.yml"
    click Keepalived "https://github.com/lablabs/ansible-role-rke2/blob/main/tasks/keepalived.yml"
    click KubeVIP "https://github.com/lablabs/ansible-role-rke2/blob/main/tasks/kubevip.yml"
    click CIS "https://github.com/lablabs/ansible-role-rke2/blob/main/tasks/cis.yml"
    click ChangeConfig "https://github.com/lablabs/ansible-role-rke2/blob/main/tasks/change_config.yml"
    click RollingUpgrade "https://github.com/lablabs/ansible-role-rke2/blob/main/tasks/rolling_restart.yml"
    click Summary "https://github.com/lablabs/ansible-role-rke2/blob/main/tasks/summary.yml"
    click Handlers "https://github.com/lablabs/ansible-role-rke2/blob/main/handlers/main.yml"
    click ConfigYAML "https://github.com/lablabs/ansible-role-rke2/blob/main/templates/config.yaml.j2"
    click Registries "https://github.com/lablabs/ansible-role-rke2/blob/main/templates/registries.yaml.j2"
    click KubeletCfg "https://github.com/lablabs/ansible-role-rke2/blob/main/templates/kubelet-config.yaml.j2"
    click EnvFile "https://github.com/lablabs/ansible-role-rke2/blob/main/templates/rke2_environment.j2"
    click CheckAPIServer "https://github.com/lablabs/ansible-role-rke2/blob/main/templates/check_apiserver.sh.j2"
    click CheckServer "https://github.com/lablabs/ansible-role-rke2/blob/main/templates/check_rke2server.sh.j2"
    click IngressTemplate "https://github.com/lablabs/ansible-role-rke2/blob/main/templates/ingress-nginx-config.yml.j2"
    click KeepalivedTpl "https://github.com/lablabs/ansible-role-rke2/blob/main/templates/keepalived.conf.j2"
    click KubeVIPTpl "https://github.com/lablabs/ansible-role-rke2/tree/main/templates/kube-vip/"
    click Meta "https://github.com/lablabs/ansible-role-rke2/blob/main/meta/main.yml"
    click Meta "https://github.com/lablabs/ansible-role-rke2/blob/main/meta/argument_specs.yml"
    click Molecule "https://github.com/lablabs/ansible-role-rke2/tree/main/molecule/default/"
    click Molecule "https://github.com/lablabs/ansible-role-rke2/tree/main/molecule/cluster/"
    click Molecule "https://github.com/lablabs/ansible-role-rke2/tree/main/molecule/ha_cluster/"
    click Molecule "https://github.com/lablabs/ansible-role-rke2/tree/main/molecule/ha_cluster_kubevip/"
    click GitHubActions "https://github.com/lablabs/ansible-role-rke2/blob/main/.github/workflows/ci.yml"
    click GitHubActions "https://github.com/lablabs/ansible-role-rke2/blob/main/.github/workflows/lint.yml"
    click GitHubActions "https://github.com/lablabs/ansible-role-rke2/blob/main/.github/workflows/galaxy.yml"
    click GitHubActions "https://github.com/lablabs/ansible-role-rke2/blob/main/.github/workflows/pre-commit.yml"
    click GitHubActions "https://github.com/lablabs/ansible-role-rke2/blob/main/.github/workflows/release-drafter.yml"

    %% Styles
    classDef controller fill:#A0C4FF,stroke:#333,stroke-width:1px;
    classDef role fill:#C8E6C9,stroke:#333,stroke-width:1px;
    classDef target fill:#FFDAB9,stroke:#333,stroke-width:1px;
    classDef external fill:#E1BEE7,stroke:#333,stroke-width:1px;
    classDef ci fill:#CFD8DC,stroke:#333,stroke-width:1px;
```
