{"id":18797211,"url":"https://github.com/mozebaltyk/rkub","last_synced_at":"2025-04-13T16:31:59.404Z","repository":{"id":215176725,"uuid":"722517010","full_name":"MozeBaltyk/Rkub","owner":"MozeBaltyk","description":"Ansible Collection to deploy a RKE2 cluster with Rancher, Longhorn and Neuvector in Airgap mode..","archived":false,"fork":false,"pushed_at":"2024-10-31T14:42:19.000Z","size":536,"stargazers_count":7,"open_issues_count":10,"forks_count":0,"subscribers_count":1,"default_branch":"develop","last_synced_at":"2024-10-31T15:33:46.155Z","etag":null,"topics":["ansible","kubernetes","longhorn","neuvector","rancher","rke2"],"latest_commit_sha":null,"homepage":"https://mozebaltyk.github.io/","language":"HCL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MozeBaltyk.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-11-23T10:16:39.000Z","updated_at":"2024-10-16T05:55:54.000Z","dependencies_parsed_at":null,"dependency_job_id":"e5588794-c348-406d-b93e-767ece749b43","html_url":"https://github.com/MozeBaltyk/Rkub","commit_stats":null,"previous_names":["mozebaltyk/rkub"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MozeBaltyk%2FRkub","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MozeBaltyk%2FRkub/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MozeBaltyk%2FRkub/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MozeBaltyk%2FRkub/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MozeBaltyk","download_url":"https://codeload.github.com/MozeBaltyk/Rkub/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223597067,"owners_count":17170872,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansible","kubernetes","longhorn","neuvector","rancher","rke2"],"created_at":"2024-11-07T22:07:28.958Z","updated_at":"2025-04-13T16:31:59.397Z","avatar_url":"https://github.com/MozeBaltyk.png","language":"HCL","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 style=\"text-align: center;\"\u003e\u003ccode\u003e Ansible Collection - Rkub  \u003c/code\u003e\u003c/h1\u003e\n\nAnsible Collection to deploy and test Rancher stacks (RKE2, Rancher, Longhorn and Neuvector).\n\n[![Releases](https://img.shields.io/github/release/MozeBaltyk/rkub)](https://github.com/MozeBaltyk/rkub/releases)\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-green.svg)](https://opensource.org/licenses/Apache-2.0/)\n[![Stage airgap](https://github.com/MozeBaltyk/Rkub/actions/workflows/stage_airgap.yml/badge.svg)](https://github.com/MozeBaltyk/Rkub/actions/workflows/stage_airgap.yml)\n[![Stage online](https://github.com/MozeBaltyk/Rkub/actions/workflows/stage_online.yml/badge.svg)](https://github.com/MozeBaltyk/Rkub/actions/workflows/stage_online.yml)\n\n## Description\n\nThis Ansible collection will install in airgap environnement RKE2 (one controler and several workers, currently no HA):\n\n\u003c!-- Autogenerated --\u003e\n**Ansible Collection Rkub 1.0.5 include:**\n\n- [RKE2 1.31.4](https://docs.rke2.io) - Security focused Kubernetes\n\n- [Kube-vip 0.8.7](https://kube-vip.io/) - Virtual IP and load balancer\n\n- [Cert-manager 1.16.2](https://cert-manager.io/docs/) - Certificate manager\n\n- [Rancher 2.9.2](https://www.suse.com/products/suse-rancher/) - Multi-Cluster Kubernetes Management\n\n- [Longhorn 1.7.2](https://longhorn.io) - Unified storage layer\n\n- [Neuvector 2.8.3](https://neuvector.com/) - Kubernetes Security Platform\n\u003c!-- END --\u003e\n\nThis Project is mainly inspired from [Clemenko/rke_airgap_install](https://github.com/clemenko/rke_airgap_install/) but Shell scripting brings limitations. So Let's rewrite it in Ansible which comes with below benefices:\n\n- Idempotency: can be relaunch multiple time.\n\n- User agnostic: can be launch by any user (with sudo rights).\n\n- OS agnositc: can be launch on any Linux systems (at least for the package build, for the install part, it depends on your participation 😸)\n\nAdd-on from this Ansible collection:\n\n- Some flexibility about path with the possibility to build and install on a choosen path.\n\n- Admin user (by default 'kuberoot') on first controller node with some admin tools (k9s, helm and kubectl).\n\n- Import kubeconfig on Ansible controller host and add it to kubecm if present (to be able to admin rke2 cluster from localhost).\n\n- Nerdctl as complement of containerd to handle oci-archive.\n\n- Uninstall playbook to cleanup (and maybe reinstall if needed).\n\n- Ansible Collection Released, so possibilty to get back to older versions.\n\n- Quickstart script to triggers an RKE2 cluster in Digital Ocean and delete it once required.\n\n## Use Case\n\nCurrently only install:\n\n- on Rocky8\n\n- airgap or online install\n\n- tarball or rpm method\n\n- Defined versions or versions from [Stable channels](https://update.rke2.io/v1-release/channels)\n\n- CNI: Canal or Cilium\n\n- Digital Ocean\n\n- Standalone or x Masters / x Workers\n\nBut the target would be to handle all the usecase below:\n\n| OS     | Versions                    | Method         | CNI    | Providers       |  Cluster Arch         | Extra Install   |\n|--------|-----------------------------|----------------|--------|-----------------|-----------------------|-----------------|\n| Rocky8 | Defined in this collection  | airgap tarball | Canal  | Digital Ocean   | Standalone            | Kubevip         |\n| Rocky9 | Stable channels             | airgap rpm     | Cilium | AWS             | One Master, x Workers | Longhorn        |\n|        | Custom                      | online tarball |        | Azure           | 3 Masters, x Workers  | Rancher         |\n|        |                             | online rpm     |        | KVM             |                       | Neuvector       |\n\n## Prerequisites\n\n- Linux Host as a package builder (can be a VM or your WSL). Count 10G of free space in the build directory of your package builder.\n\n- An Ansible Controler, can be the same host for ansible and for building package, at your convenience...\n\n- A minimum of 2 hosts RHEL-like (2 vCPU and 8G of RAM) for the cluster RKE2 with 80G at least on target directory.\n\n## Quickstart\n\nAs prerequisities, you will need a Digital Ocean accompte and set your `Token` and a `Spaces key` in Digital Ocean's API tabs. You can use my referrals links below, it helps a lot:\n\n\u003ca href=\"https://www.digitalocean.com/?refcode=fb9479b3dbef\u0026utm_campaign=Referral_Invite\u0026utm_medium=Referral_Program\u0026utm_source=badge\"\u003e\u003cimg src=\"https://web-platforms.sfo2.cdn.digitaloceanspaces.com/WWW/Badge%203.svg\" alt=\"DigitalOcean Referral Badge\" /\u003e\u003c/a\u003e\n\nThen perform those followings steps:\n\n- Clone the main branch of this project to a machine with an internet access:\n      `git clone -b main https://github.com/MozeBaltyk/Rkub.git`\n\n- Execute `make prerequis` to install all prerequisites defined in meta directory.\n\n- Export vars and Execute as below:\n\n```bash\nexport DO_PAT=\"xxxxxxxxxx\"\nexport AWS_ACCESS_KEY_ID=\"xxxxxxxxxxxx\"\nexport AWS_SECRET_ACCESS_KEY=\"xxxxxxxxxxx\"\nexport WORKERS=2 # Default 0\nexport MASTERS=3 # Default 1\n\n# Create RKE2 cluster\nmake quickstart\n\n# Other components\nmake longhorn\nmake rancher\nmake neuvector\n\n# Delete RKE2 cluster\nmake cleanup\n```\n\nNB: Quickstart is meant to deploy in DO a quick RKE2 cluster for testing purpose, and without taking into account airgap problematics.\nAirgap actions are adressed in below procedure.\n\n## Global Usage\n\n1. From an host with internet accces \n\n- Install this collection: `ansible-galaxy collection install mozebaltyk.rkub`\n\n- Clone this repository: `git clone -b main https://github.com/MozeBaltyk/Rkub.git`\n\n- Install prerequisites: `cd Rkub \u0026\u0026 make prerequis`\n\n2. Preparatory steps for a normal ansible controller:\n\n- Create some SSH keys and deploy it on target hosts.\n\n- Define an ansible.cfg\n\n- Define an inventory (example in `./plugins/inventory/hosts.yml`).\n\nthen use it...\n\n3. Build your package by running (works on Debian-like or Redhat-like and targets localhost).\nThis step concern only an airgap install. If targeted servers have an internet access then skip and go to step 5:\n\n```sh\nansible-playbook mozebaltyk.rkub.build.yml                    # All arguments below are not mandatory\n-e \"dir_build=$HOME/rkub\"                                     # Directory where to upload everything (count 10G)\n-e \"package_name=rkub.zst\"                                    # Name of the package, by default rkub.zst\n-e \"archive=true\"                                             # Archive tar.zst true or false (default value \"true\")\n-e \"stable=false\"                                             # Stable channels or take version as defined in Rkub collection (default value \"false\")\n-e \"method=tarball\"                                           # Method for install, value possible \"tarball\" or \"rpm\" (default value \"tarball\")\n-e \"el=9\"                                                     # RHEL version (take default value from localhost if OS is different from RedHat-like take value \"8\")\n-e \"all=false\"                                                # Add all components kubevip,longhorn,rancher,neuvector (default value \"false\")\n-e \"kubevip=true longhorn=true rancher=true neuvector=true\"   # Add extras components to package (default value from var 'all')\n-u admin -Kk                                                  # Other Ansible Arguments (like -vvv)\n```\n\n4. Push your package to first controler:\n\n```sh\nansible-playbook mozebaltyk.rkub.upload.yml        # All arguments below are not mandatory\n-e \"package_path=/home/me/rkub.zst\"                # Will be prompt if not given in the command\n-e \"dir_target=/opt/rkub\"                          # Directory where to sync and unarchive (by default /opt/rkub, count 30G available)\n-u admin -Kk                                       # Other Ansible Arguments (like -vvv)\n```\n\n5. Deploy Hauler services:\n\n```sh\nansible-playbook mozebaltyk.rkub.hauler.yml        # All arguments below are not mandatory\n-e \"dir_target=/opt/rkub\"                          # Directory where to find package untar with previous playbook\n-u admin -Kk                                       # Other Ansible Arguments (like -vvv)\n```\n\n6. Start installation:\n\n```sh\nansible-playbook mozebaltyk.rkub.install.yml       # All arguments below are not mandatory\n-e domain=\"example.com\"                            # By default take the host domain from master server\n-e \"method=tarball\"                                # Method for install, value possible \"tarball\" or \"rpm\" (default value \"tarball\")\n-e \"airgap=true\"                                   # if servers have internet access then set airgap to false (default value \"true\")\n  -e \"stable=false\"                                # if airgap false then choose btw Stable channels or version from this collection. (default value \"false\")\n-u admin -Kk                                       # Other Ansible Arguments (like -vvv)\n```\n\n7. Deploy Rancher:\n\n```sh\nansible-playbook mozebaltyk.rkub.rancher.yml       # All arguments below are not mandatory\n-e domain=\"example.com\"                            # Domain use for ingress, by default take the host domain from master server\n-e password=\"BootStrapAllTheThings\"                # Default password is \"BootStrapAllTheThings\"\n-u admin -Kk                                       # Other Ansible Arguments (like -vvv)\n```\n\n8. Deploy Longhorn:\n\n```sh\nansible-playbook mozebaltyk.rkub.longhorn.yml      # All arguments below are not mandatory\n-e domain=\"example.com\"                            # Domain use for ingress, by default take the host domain from master server\n-e datapath=\"/data/longhorn\"                       # Longhorn Path for PVC (default \"/data/longhorn\").\n                                                   # The best is to have a dedicated LVM filesystem for this one.\n-u admin -Kk                                       # Other Ansible Arguments (like -vvv)\n```\n\n9. Deploy Neuvector\n\n```sh\nansible-playbook mozebaltyk.rkub.neuvector.yml     # All arguments below are not mandatory\n-e domain=\"example.com\"                            # Domain use for ingress, by default take the host domain from master server\n-u admin -Kk                                       # Other Ansible Arguments (like -vvv)\n```\n\n## Ansible collection in Container\n\n1. This is a custom script which imitate Execution-Environement:\n\n- `make ee-container` will load an UBI-8 image and execute inside `make prerequis`\n\n- `make ee-exec` Run image with collection and package zst mounted inside. Launch playbook or make command as described above.\n\nAll prerequisites are set in folder `meta` and `meta/execution-environment.yml`. So it's possible to use ansible-builder (though not tested yet).\n\n## TLDR; few interesting details\n\nI favored the tarball installation since it's the most compact and install rely on a archive tar.zst which stay on all nodes.\nThe rpm install is much straight forward and a bit faster but match only system with RPM (so mainly Redhat-like) and require a registry.\nSo because of this point, the rpm method with the rke2 stable channel is used for the quickstart install.\n\n**build** have for purpose to create a tar.zst with following content using hauler tool:\n\n```bash\nrkub\n├── airgap_hauler.yaml    # yaml listing all resources\n├── hauler                # hauler binary\n└── store                 # hauler store made from above yaml and hauler command\n    ├── blobs\n    │   └── sha256\n    │       ├── 024f2ae6c3625583f0e10ab4d68e4b8947b55d085c88e34c0bd916944ed05add\n    └── index.json\n```\n\nIt will store and build package regarding:\n\n- Chosen install method for rke2 (tarbal or rpm)\n- Chosen components (kube-vip, longhorn, rancher, neuvector)\n- Chosen channels stable or versions defined in this collection\n\n**upload** push the big monster packages (around 7G) and unarchive on first node on chosen targeted path.\n\n**hauler** (by default on first controller but could be on dedicated server)\n\n- deploy a registry as systemd service and make it available on port 5000 using hauler.\n- deploy a fileserver as systemd service and make it available on port 8080 using hauler.\n\n**install** RKE2 (currently only one master) with:\n\n- Install rke2 with tarball method by default or rpm method if given in argument.\n- An admin user (by default `kuberoot`) on first master with some administation tools like `k9s` `kubectl` or `helm`.\n- Nerdctl as complement to containerd and allow oci-archive.\n- Firewalld settings if firewalld running.\n- Selinux rpm if selinux enabled.\n- Fetch and add kubeconfig to ansible controller in directory ./kube (and add to kubecm if present).\n\n**deploy** keeping this order, *Rancher*, *Longhorn*, *Neuvector*\n\n- Those are simple playbooks which deploy with helm charts either in airgap or online mode.\n- It use the default ingress from RKE2 *Nginx-ingress* in https (currently Self-sign certificate)\n- *Rancher* need *Certmanager*, So it deploy first Certmanager\n\n## Roadmap\n\nMilestones:\n\n* More install customization and options\n\n* HA masters with kubevip\n\n* Allow several providers (currently only DO)\n\n# Acknowledgements\n\n## Special thanks to 📢\n\n* Clemenko, for the idea [Clemenko/rke_airgap_install](https://github.com/clemenko/rke_airgap_install/).\n\n## References\n\n- [Clemenko/rke_airgap_install](https://github.com/clemenko/rke_airgap_install/)\n\n- [rancherfederal/RKE2-ansible](https://github.com/rancherfederal/rke2-ansible)\n\n- [lablabs/ansible-role-rke2](https://github.com/lablabs/ansible-role-rke2)\n\n- [rancher/RKE2](https://github.com/rancher/rke2)\n\n- [rancher/quickstart](https://github.com/rancher/quickstart)\n\n## Repo Activity\n\n![Alt](https://repobeats.axiom.co/api/embed/2664e49768529526895630ae70e2a366a70de78f.svg \"Repobeats analytics image\")\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmozebaltyk%2Frkub","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmozebaltyk%2Frkub","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmozebaltyk%2Frkub/lists"}