{"id":13434764,"url":"https://github.com/PyratLabs/ansible-role-k3s","last_synced_at":"2025-03-18T01:32:01.543Z","repository":{"id":37857420,"uuid":"173498378","full_name":"PyratLabs/ansible-role-k3s","owner":"PyratLabs","description":"Ansible role for installing k3s as either a standalone server or HA cluster.","archived":false,"fork":false,"pushed_at":"2025-01-11T14:06:23.000Z","size":478,"stargazers_count":661,"open_issues_count":5,"forks_count":134,"subscribers_count":24,"default_branch":"main","last_synced_at":"2025-03-09T17:27:12.716Z","etag":null,"topics":["ansible","ansible-role","cluster","k3s","k3s-cluster","k8s","k8s-cluster","kubernetes","kubernetes-cluster","playbook","standalone-server"],"latest_commit_sha":null,"homepage":"","language":"Jinja","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PyratLabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","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":"2019-03-02T21:00:05.000Z","updated_at":"2025-02-25T21:34:29.000Z","dependencies_parsed_at":"2023-01-27T20:31:12.469Z","dependency_job_id":"cf9d7719-d3df-4546-b610-54655e71528a","html_url":"https://github.com/PyratLabs/ansible-role-k3s","commit_stats":{"total_commits":325,"total_committers":40,"mean_commits":8.125,"dds":"0.36923076923076925","last_synced_commit":"19c24bd50381d06bac105ed7e9d012d73e46bef4"},"previous_names":[],"tags_count":129,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PyratLabs%2Fansible-role-k3s","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PyratLabs%2Fansible-role-k3s/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PyratLabs%2Fansible-role-k3s/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PyratLabs%2Fansible-role-k3s/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PyratLabs","download_url":"https://codeload.github.com/PyratLabs/ansible-role-k3s/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243918542,"owners_count":20368745,"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","ansible-role","cluster","k3s","k3s-cluster","k8s","k8s-cluster","kubernetes","kubernetes-cluster","playbook","standalone-server"],"created_at":"2024-07-31T03:00:22.384Z","updated_at":"2025-03-18T01:32:01.512Z","avatar_url":"https://github.com/PyratLabs.png","language":"Jinja","funding_links":[],"categories":["HarmonyOS","Jinja","kubernetes"],"sub_categories":["Windows Manager"],"readme":"# Ansible Role: k3s (v3.x)\n\nAnsible role for installing [K3S](https://k3s.io/) (\"Lightweight\nKubernetes\") as either a standalone server or cluster.\n\n[![CI](https://github.com/PyratLabs/ansible-role-k3s/workflows/CI/badge.svg?event=push)](https://github.com/PyratLabs/ansible-role-k3s/actions?query=workflow%3ACI)\n\n## Help Wanted!\n\nHi! :wave: [@xanmanning](https://github.com/xanmanning) is looking for a new\nmaintainer to work on this Ansible role. This is because I don't have as much\nfree time any more and I no longer write Ansible regularly as part of my day\njob. If you're interested, get in touch.\n\n## Release notes\n\nPlease see [Releases](https://github.com/PyratLabs/ansible-role-k3s/releases)\nand [CHANGELOG.md](CHANGELOG.md).\n\n## Requirements\n\nThe host you're running Ansible from requires the following Python dependencies:\n\n  - `python \u003e= 3.6.0` - [See Notes below](#important-note-about-python).\n  - `ansible \u003e= 2.9.16` or `ansible-base \u003e= 2.10.4`\n\nYou can install dependencies using the requirements.txt file in this repository:\n`pip3 install -r requirements.txt`.\n\nThis role has been tested against the following Linux Distributions:\n\n  - Alpine Linux\n  - Amazon Linux 2\n  - Archlinux\n  - CentOS 8\n  - Debian 11\n  - Fedora 31\n  - Fedora 32\n  - Fedora 33\n  - openSUSE Leap 15\n  - RockyLinux 8\n  - Ubuntu 20.04 LTS\n\n:warning: The v3 releases of this role only supports `k3s \u003e= v1.19`, for\n`k3s \u003c v1.19` please consider updating or use the v1.x releases of this role.\n\nBefore upgrading, see [CHANGELOG](CHANGELOG.md) for notifications of breaking\nchanges.\n\n## Role Variables\n\nSince K3s [v1.19.1+k3s1](https://github.com/k3s-io/k3s/releases/tag/v1.19.1%2Bk3s1)\nyou can now configure K3s using a\n[configuration file](https://rancher.com/docs/k3s/latest/en/installation/install-options/#configuration-file)\nrather than environment variables or command line arguments. The v2 release of\nthis role has moved to the configuration file method rather than populating a\nsystemd unit file with command-line arguments. There may be exceptions that are\ndefined in [Global/Cluster Variables](#globalcluster-variables), however you will\nmostly be configuring k3s by configuration files using the `k3s_server` and\n`k3s_agent` variables.\n\nSee \"_Server (Control Plane) Configuration_\" and \"_Agent (Worker) Configuraion_\"\nbelow.\n\n### Global/Cluster Variables\n\nBelow are variables that are set against all of the play hosts for environment\nconsistency. These are generally cluster-level configuration.\n\n| Variable                             | Description                                                                                | Default Value                  |\n|--------------------------------------|--------------------------------------------------------------------------------------------|--------------------------------|\n| `k3s_state`                          | State of k3s: installed, started, stopped, downloaded, uninstalled, validated.             | installed                      |\n| `k3s_release_version`                | Use a specific version of k3s, eg. `v0.2.0`. Specify `false` for stable.                   | `false`                        |\n| `k3s_airgap`                         | Boolean to enable air-gapped installations                                                 | `false`                        |\n| `k3s_config_file`                    | Location of the k3s configuration file.                                                    | `/etc/rancher/k3s/config.yaml` |\n| `k3s_build_cluster`                  | When multiple play hosts are available, attempt to cluster. Read notes below.              | `true`                         |\n| `k3s_registration_address`           | Fixed registration address for nodes. IP or FQDN.                                          | NULL                           |\n| `k3s_github_url`                     | Set the GitHub URL to install k3s from.                                                    | https://github.com/k3s-io/k3s  |\n| `k3s_api_url`                        | URL for K3S updates API.                                                                   | https://update.k3s.io          |\n| `k3s_install_dir`                    | Installation directory for k3s.                                                            | `/usr/local/bin`               |\n| `k3s_install_hard_links`             | Install using hard links rather than symbolic links.                                       | `false`                        |\n| `k3s_server_config_yaml_d_files`     | A flat list of templates to supplement the `k3s_server` configuration.                     | []                             |\n| `k3s_agent_config_yaml_d_files`      | A flat list of templates to supplement the `k3s_agent` configuration.                      | []                             |\n| `k3s_server_manifests_urls`          | A list of URLs to deploy on the primary control plane. Read notes below.                   | []                             |\n| `k3s_server_manifests_templates`     | A flat list of templates to deploy on the primary control plane.                           | []                             |\n| `k3s_server_pod_manifests_urls`      | A list of URLs for installing static pod manifests on the control plane. Read notes below. | []                             |\n| `k3s_server_pod_manifests_templates` | A flat list of templates for installing static pod manifests on the control plane.         | []                             |\n| `k3s_use_experimental`               | Allow the use of experimental features in k3s.                                             | `false`                        |\n| `k3s_use_unsupported_config`         | Allow the use of unsupported configurations in k3s.                                        | `false`                        |\n| `k3s_etcd_datastore`                 | Enable etcd embedded datastore (read notes below).                                         | `false`                        |\n| `k3s_debug`                          | Enable debug logging on the k3s service.                                                   | `false`                        |\n| `k3s_registries`                     | Registries configuration file content.                                                     | `{ mirrors: {}, configs:{} }`  |\n\n### K3S Service Configuration\n\nThe below variables change how and when the systemd service unit file for K3S\nis run. Use this with caution, please refer to the [systemd documentation](https://www.freedesktop.org/software/systemd/man/systemd.unit.html#%5BUnit%5D%20Section%20Options)\nfor more information.\n\n| Variable               | Description                                                          | Default Value |\n|------------------------|----------------------------------------------------------------------|---------------|\n| `k3s_start_on_boot`    | Start k3s on boot.                                                   | `true`        |\n| `k3s_service_requires` | List of required systemd units to k3s service unit.                  | []            |\n| `k3s_service_wants`    | List of \"wanted\" systemd unit to k3s (weaker than \"requires\").       | []\\*          |\n| `k3s_service_before`   | Start k3s before a defined list of systemd units.                    | []            |\n| `k3s_service_after`    | Start k3s after a defined list of systemd units.                     | []\\*          |\n| `k3s_service_env_vars` | Dictionary of environment variables to use within systemd unit file. | {}            |\n| `k3s_service_env_file` | Location on host of a environment file to include.                   | `false`\\*\\*   |\n\n\\* The systemd unit template **always** specifies `network-online.target` for\n`wants` and `after`.\n\n\\*\\* The file must already exist on the target host, this role will not create\nnor manage the file. You can manage this file outside of the role with\npre-tasks in your Ansible playbook.\n\n### Group/Host Variables\n\nBelow are variables that are set against individual or groups of play hosts.\nTypically you'd set these at group level for the control plane or worker nodes.\n\n| Variable           | Description                                                       | Default Value                                     |\n|--------------------|-------------------------------------------------------------------|---------------------------------------------------|\n| `k3s_control_node` | Specify if a host (or host group) are part of the control plane.  | `false` (role will automatically delegate a node) |\n| `k3s_server`       | Server (control plane) configuration, see notes below.            | `{}`                                              |\n| `k3s_agent`        | Agent (worker) configuration, see notes below.                    | `{}`                                              |\n\n#### Server (Control Plane) Configuration\n\nThe control plane is configured with the `k3s_server` dict variable. Please\nrefer to the below documentation for configuration options:\n\nhttps://rancher.com/docs/k3s/latest/en/installation/install-options/server-config/\n\nThe `k3s_server` dictionary variable will contain flags from the above\n(removing the `--` prefix). Below is an example:\n\n```yaml\nk3s_server:\n  datastore-endpoint: postgres://postgres:verybadpass@database:5432/postgres?sslmode=disable\n  cluster-cidr: 172.20.0.0/16\n  flannel-backend: 'none'  # This needs to be in quotes\n  disable:\n    - traefik\n    - coredns\n```\n\nAlternatively, you can create a .yaml file and read it in to the `k3s_server`\nvariable as per the below example:\n\n```yaml\nk3s_server: \"{{ lookup('file', 'path/to/k3s_server.yml') | from_yaml }}\"\n```\n\nCheck out the [Documentation](documentation/README.md) for example\nconfiguration.\n\n#### Agent (Worker) Configuration\n\nWorkers are configured with the `k3s_agent` dict variable. Please refer to the\nbelow documentation for configuration options:\n\nhttps://rancher.com/docs/k3s/latest/en/installation/install-options/agent-config\n\nThe `k3s_agent` dictionary variable will contain flags from the above\n(removing the `--` prefix). Below is an example:\n\n```yaml\nk3s_agent:\n  with-node-id: true\n  node-label:\n    - \"foo=bar\"\n    - \"hello=world\"\n```\n\nAlternatively, you can create a .yaml file and read it in to the `k3s_agent`\nvariable as per the below example:\n\n```yaml\nk3s_agent: \"{{ lookup('file', 'path/to/k3s_agent.yml') | from_yaml }}\"\n```\n\nCheck out the [Documentation](documentation/README.md) for example\nconfiguration.\n\n### Ansible Controller Configuration Variables\n\nThe below variables are used to change the way the role executes in Ansible,\nparticularly with regards to privilege escalation.\n\n| Variable               | Description                                                    | Default Value |\n|------------------------|----------------------------------------------------------------|---------------|\n| `k3s_skip_validation`  | Skip all tasks that validate configuration.                    | `false`       |\n| `k3s_skip_env_checks`  | Skip all tasks that check environment configuration.           | `false`       |\n| `k3s_skip_post_checks` | Skip all tasks that check post execution state.                | `false`       |\n| `k3s_become`           | Escalate user privileges for tasks that need root permissions. | `false`       |\n\n#### Important note about Python\n\nFrom v3 of this role, Python 3 is required on the target system as well as on\nthe Ansible controller. This is to ensure consistent behaviour for Ansible\ntasks as Python 2 is now EOL.\n\nIf target systems have both Python 2 and Python 3 installed, it is most likely\nthat Python 2 will be selected by default. To ensure Python 3 is used on a\ntarget with both versions of Python, ensure `ansible_python_interpreter` is\nset in your inventory. Below is an example inventory:\n\n```yaml\n---\n\nk3s_cluster:\n  hosts:\n    kube-0:\n      ansible_user: ansible\n      ansible_host: 10.10.9.2\n      ansible_python_interpreter: /usr/bin/python3\n    kube-1:\n      ansible_user: ansible\n      ansible_host: 10.10.9.3\n      ansible_python_interpreter: /usr/bin/python3\n    kube-2:\n      ansible_user: ansible\n      ansible_host: 10.10.9.4\n      ansible_python_interpreter: /usr/bin/python3\n```\n\n#### Important note about `k3s_release_version`\n\nIf you do not set a `k3s_release_version` the latest version from the stable\nchannel of k3s will be installed. If you are developing against a specific\nversion of k3s you must ensure this is set in your Ansible configuration, eg:\n\n```yaml\nk3s_release_version: v1.19.3+k3s1\n```\n\nIt is also possible to install specific K3s \"Channels\", below are some\nexamples for `k3s_release_version`:\n\n```yaml\nk3s_release_version: false             # defaults to 'stable' channel\nk3s_release_version: stable            # latest 'stable' release\nk3s_release_version: testing           # latest 'testing' release\nk3s_release_version: v1.19             # latest 'v1.19' release\nk3s_release_version: v1.19.3+k3s3      # specific release\n\n# Specific commit\n# CAUTION - only used for testing - must be 40 characters\nk3s_release_version: 48ed47c4a3e420fa71c18b2ec97f13dc0659778b\n```\n\n#### Important note about `k3s_install_hard_links`\n\nIf you are using the [system-upgrade-controller](https://github.com/rancher/system-upgrade-controller)\nyou will need to use hard links rather than symbolic links as the controller\nwill not be able to follow symbolic links. This option has been added however\nis not enabled by default to avoid breaking existing installations.\n\nTo enable the use of hard links, ensure `k3s_install_hard_links` is set\nto `true`.\n\n```yaml\nk3s_install_hard_links: true\n```\n\nThe result of this can be seen by running the following in `k3s_install_dir`:\n\n`ls -larthi | grep -E 'k3s|ctr|ctl' | grep -vE \".sh$\" | sort`\n\nSymbolic Links:\n\n```text\n[root@node1 bin]# ls -larthi | grep -E 'k3s|ctr|ctl' | grep -vE \".sh$\" | sort\n3277823 -rwxr-xr-x 1 root root  52M Jul 25 12:50 k3s-v1.18.4+k3s1\n3279565 lrwxrwxrwx 1 root root   31 Jul 25 12:52 k3s -\u003e /usr/local/bin/k3s-v1.18.6+k3s1\n3279644 -rwxr-xr-x 1 root root  51M Jul 25 12:52 k3s-v1.18.6+k3s1\n3280079 lrwxrwxrwx 1 root root   31 Jul 25 12:52 ctr -\u003e /usr/local/bin/k3s-v1.18.6+k3s1\n3280080 lrwxrwxrwx 1 root root   31 Jul 25 12:52 crictl -\u003e /usr/local/bin/k3s-v1.18.6+k3s1\n3280081 lrwxrwxrwx 1 root root   31 Jul 25 12:52 kubectl -\u003e /usr/local/bin/k3s-v1.18.6+k3s1\n```\n\nHard Links:\n\n```text\n[root@node1 bin]# ls -larthi | grep -E 'k3s|ctr|ctl' | grep -vE \".sh$\" | sort\n3277823 -rwxr-xr-x 1 root root  52M Jul 25 12:50 k3s-v1.18.4+k3s1\n3279644 -rwxr-xr-x 5 root root  51M Jul 25 12:52 crictl\n3279644 -rwxr-xr-x 5 root root  51M Jul 25 12:52 ctr\n3279644 -rwxr-xr-x 5 root root  51M Jul 25 12:52 k3s\n3279644 -rwxr-xr-x 5 root root  51M Jul 25 12:52 k3s-v1.18.6+k3s1\n3279644 -rwxr-xr-x 5 root root  51M Jul 25 12:52 kubectl\n```\n\n#### Important note about `k3s_build_cluster`\n\nIf you set `k3s_build_cluster` to `false`, this role will install each play\nhost as a standalone node. An example of when you might use this would be\nwhen building a large number of standalone IoT devices running K3s. Below is a\nhypothetical situation where we are to deploy 25 Raspberry Pi devices, each a\nstandalone system and not a cluster of 25 nodes. To do this we'd use a playbook\nsimilar to the below:\n\n```yaml\n- hosts: k3s_nodes  # eg. 25 RPi's defined in our inventory.\n  vars:\n    k3s_build_cluster: false\n  roles:\n     - xanmanning.k3s\n```\n\n#### Important note about `k3s_control_node` and High Availability (HA)\n\nBy default only one host will be defined as a control node by Ansible, If you\ndo not set a host as a control node, this role will automatically delegate\nthe first play host as a control node. This is not suitable for use within\na Production workload.\n\nIf multiple hosts have `k3s_control_node` set to `true`, you must also set\n`datastore-endpoint` in `k3s_server` as the connection string to a MySQL or\nPostgreSQL database, or external Etcd cluster else the play will fail.\n\nIf using TLS, the CA, Certificate and Key need to already be available on\nthe play hosts.\n\nSee: [High Availability with an External DB](https://rancher.com/docs/k3s/latest/en/installation/ha/)\n\nIt is also possible, though not supported, to run a single K3s control node\nwith a `datastore-endpoint` defined. As this is not a typically supported\nconfiguration you will need to set `k3s_use_unsupported_config` to `true`.\n\nSince K3s v1.19.1 it is possible to use an embedded Etcd as the backend\ndatabase, and this is done by setting `k3s_etcd_datastore` to `true`.\nThe best practice for Etcd is to define at least 3 members to ensure quorum is\nestablished. In addition to this, an odd number of members is recommended to\nensure a majority in the event of a network partition. If you want to use 2\nmembers or an even number of members, please set `k3s_use_unsupported_config`\nto `true`.\n\n#### Important note about `k3s_server_manifests_urls` and `k3s_server_pod_manifests_urls`\n\nTo deploy server manifests and server pod manifests from URL, you need to\nspecify a `url` and optionally a `filename` (if none provided basename is used). Below is an example of how to deploy the\nTigera operator for Calico and kube-vip.\n\n```yaml\n---\n\nk3s_server_manifests_urls:\n  - url: https://docs.projectcalico.org/archive/v3.19/manifests/tigera-operator.yaml\n    filename: tigera-operator.yaml\n\nk3s_server_pod_manifests_urls:\n  - url: https://raw.githubusercontent.com/kube-vip/kube-vip/main/example/deploy/0.1.4.yaml\n    filename: kube-vip.yaml\n\n```\n\n#### Important note about `k3s_airgap`\n\nWhen deploying k3s in an air gapped environment you should provide the `k3s` binary in `./files/`. The binary will not be downloaded from Github and will subsequently not be verified using the provided sha256 sum, nor able to verify the version that you are running. All risks and burdens associated are assumed by the user in this scenario.\n\n## Dependencies\n\nNo dependencies on other roles.\n\n## Example Playbooks\n\nExample playbook, single control node running `testing` channel k3s:\n\n```yaml\n- hosts: k3s_nodes\n  vars:\n    k3s_release_version: testing\n  roles:\n     - role: xanmanning.k3s\n```\n\nExample playbook, Highly Available with PostgreSQL database running the latest\nstable release:\n\n```yaml\n- hosts: k3s_nodes\n  vars:\n    k3s_registration_address: loadbalancer  # Typically a load balancer.\n    k3s_server:\n      datastore-endpoint: \"postgres://postgres:verybadpass@database:5432/postgres?sslmode=disable\"\n  pre_tasks:\n    - name: Set each node to be a control node\n      ansible.builtin.set_fact:\n        k3s_control_node: true\n      when: inventory_hostname in ['node2', 'node3']\n  roles:\n    - role: xanmanning.k3s\n```\n\n## License\n\n[BSD 3-clause](LICENSE.txt)\n\n## Contributors\n\nContributions from the community are very welcome, but please read the\n[contribution guidelines](CONTRIBUTING.md) before doing so, this will help\nmake things as streamlined as possible.\n\nAlso, please check out the awesome\n[list of contributors](https://github.com/PyratLabs/ansible-role-k3s/graphs/contributors).\n\n## Author Information\n\n[Xan Manning](https://xan.manning.io/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPyratLabs%2Fansible-role-k3s","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FPyratLabs%2Fansible-role-k3s","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPyratLabs%2Fansible-role-k3s/lists"}