rework documentation, change github link, replace deprecated variables

PyratLabs · Dec 16, 2020 · e25edbe · e25edbe
1 parent a067a97
commit e25edbe
Show file tree

Hide file tree

Showing 9 changed files with 80 additions and 50 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -14,6 +14,20 @@
 ---
 -->
 
+## 2020-12-16, v2.2.1
+
+### Notable changes
+
+  - Re-working documentation
+  - Updated GitHub link, org changed from Rancher to k3s-io.
+  - Replace deprecated `play_hosts` variable.
+
+### Breaking changes
+
+  - Moving git branch from `master` to `main`.
+
+---
+
 ## 2020-12-12, v2.2.0
 
 ### Notable changes

diff --git a/README.md b/README.md
@@ -67,45 +67,40 @@ mostly be configuring k3s by configuration files using the `k3s_server` and
 See "_Server (Control Plane) Configuration_" and "_Agent (Worker) Configuraion_"
 below.
 
-### Group/Cluster Variables
+### Global/Cluster Variables
 
 Below are variables that are set against all of the play hosts for environment
 consistency. These are generally cluster-level configuration.
 
-| Variable                         | Description                                                                     | Default Value                           |
-|----------------------------------|---------------------------------------------------------------------------------|-----------------------------------------|
-| `k3s_state`                      | State of k3s: installed, started, stopped, downloaded, uninstalled, validated.  | installed                               |
-| `k3s_release_version`            | Use a specific version of k3s, eg. `v0.2.0`. Specify `false` for stable.        | `false`                                 |
-| `k3s_config_file`                | Location of the k3s configuration file.                                         | `/etc/rancher/k3s/config.yaml`          |
-| `k3s_build_cluster`              | When multiple `play_hosts` are available, attempt to cluster. Read notes below. | `true`                                  |
-| `k3s_control_node_address` 	     | Use a specific control node address. IP or FQDN.                                | NULL                                    |
-| `k3s_github_url`                 | Set the GitHub URL to install k3s from.                                         | https://github.com/rancher/k3s          |
-| `k3s_skip_validation`            | Skip all tasks that validate configuration.                                     | `false`                                 |
-| `k3s_install_dir`                | Installation directory for k3s.                                                 | `/usr/local/bin`                        |
-| `k3s_install_hard_links`         | Install using hard links rather than symbolic links.                            | `false`                                 |
-| `k3s_server_manifests_templates` | A list of Auto-Deploying Manifests Templates.                                   | []                                      |
-| `k3s_use_experimental`           | Allow the use of experimental features in k3s.                                  | `false`                                 |
-| `k3s_use_unsupported_config`     | Allow the use of unsupported configurations in k3s.                             | `false`                                 |
-| `k3s_etcd_datastore`             | Enable etcd embedded datastore (read notes below).                              | `false`                                 |
-| `k3s_debug`                      | Enable debug logging on the k3s service.                                        | `false`                                 |
-
-### Ansible Controller Configuration Variables
-
-The below variables are used to change the way the role executes in Ansible,
-particularly with regards to privilege escalation.
-
-| Variable                         | Description                                                         | Default Value |
-|----------------------------------|---------------------------------------------------------------------|---------------|
-| `k3s_become_for_all`             | Escalate user privileges for all tasks. Overrides all of the below. | `false`       |
-| `k3s_become_for_systemd`         | Escalate user privileges for systemd tasks.                         | NULL          |
-| `k3s_become_for_install_dir`     | Escalate user privileges for creating installation directories.     | NULL          |
-| `k3s_become_for_usr_local_bin`   | Escalate user privileges for writing to `/usr/local/bin`.           | NULL          |
-| `k3s_become_for_data_dir`        | Escalate user privileges for creating data directory.               | NULL          |
-| `k3s_become_for_package_install` | Escalate user privileges for installing k3s.                        | NULL          |
-| `k3s_become_for_kubectl`         | Escalate user privileges for running `kubectl`.                     | NULL          |
-| `k3s_become_for_uninstall`       | Escalate user privileges for uninstalling k3s.                      | NULL          |
-
-### Server (Control Plane) Configuration
+| Variable                         | Description                                                                     | Default Value                  |
+|----------------------------------|---------------------------------------------------------------------------------|--------------------------------|
+| `k3s_state`                      | State of k3s: installed, started, stopped, downloaded, uninstalled, validated.  | installed                      |
+| `k3s_release_version`            | Use a specific version of k3s, eg. `v0.2.0`. Specify `false` for stable.        | `false`                        |
+| `k3s_config_file`                | Location of the k3s configuration file.                                         | `/etc/rancher/k3s/config.yaml` |
+| `k3s_build_cluster`              | When multiple play hosts are available, attempt to cluster. Read notes below.   | `true`                         |
+| `k3s_control_node_address`       | Use a specific control node address. IP or FQDN.                                | NULL                           |
+| `k3s_github_url`                 | Set the GitHub URL to install k3s from.                                         | https://github.com/k3s-io/k3s  |
+| `k3s_skip_validation`            | Skip all tasks that validate configuration.                                     | `false`                        |
+| `k3s_install_dir`                | Installation directory for k3s.                                                 | `/usr/local/bin`               |
+| `k3s_install_hard_links`         | Install using hard links rather than symbolic links.                            | `false`                        |
+| `k3s_server_manifests_templates` | A list of Auto-Deploying Manifests Templates.                                   | []                             |
+| `k3s_use_experimental`           | Allow the use of experimental features in k3s.                                  | `false`                        |
+| `k3s_use_unsupported_config`     | Allow the use of unsupported configurations in k3s.                             | `false`                        |
+| `k3s_etcd_datastore`             | Enable etcd embedded datastore (read notes below).                              | `false`                        |
+| `k3s_debug`                      | Enable debug logging on the k3s service.                                        | `false`                        |
+
+### Group/Host Variables
+
+Below are variables that are set against individual or groups of play hosts.
+Typically you'd set these at group level for the control plane or worker nodes.
+
+| Variable           | Description                                                       | Default Value                                     |
+|--------------------|-------------------------------------------------------------------|---------------------------------------------------|
+| `k3s_control_node` | Specify if a host (or host group) are part of the control plane.  | `false` (role will automatically delegate a node) |
+| `k3s_server`       | Server (control plane) configuration, see notes below.            | `{}`                                              |
+| `k3s_agent`        | Agent (worker) configuration, see notes below.                    | `{}`                                              |
+
+#### Server (Control Plane) Configuration
 
 The control plane is configured with the `k3s_server` dict variable. Please
 refer to the below documentation for configuration options:
@@ -136,7 +131,7 @@ k3s_server: "{{ lookup('file', 'path/to/k3s_server.yml') | from_yaml }}"
 Check out the [Documentation](documentation/README.md) for example
 configuration.
 
-### Agent (Worker) Configuration
+#### Agent (Worker) Configuration
 
 Workers are configured with the `k3s_agent` dict variable. Please refer to the
 below documentation for configuration options:
@@ -164,6 +159,23 @@ k3s_agent: "{{ lookup('file', 'path/to/k3s_agent.yml') | from_yaml }}"
 Check out the [Documentation](documentation/README.md) for example
 configuration.
 
+### Ansible Controller Configuration Variables
+
+The below variables are used to change the way the role executes in Ansible,
+particularly with regards to privilege escalation.
+
+| Variable                         | Description                                                         | Default Value |
+|----------------------------------|---------------------------------------------------------------------|---------------|
+| `k3s_become_for_all`             | Escalate user privileges for all tasks. Overrides all of the below. | `false`       |
+| `k3s_become_for_systemd`         | Escalate user privileges for systemd tasks.                         | NULL          |
+| `k3s_become_for_install_dir`     | Escalate user privileges for creating installation directories.     | NULL          |
+| `k3s_become_for_manifests_dir`   | Escalate user privileges for creating manifests directory.          | NULL          |
+| `k3s_become_for_usr_local_bin`   | Escalate user privileges for writing to `/usr/local/bin`.           | NULL          |
+| `k3s_become_for_data_dir`        | Escalate user privileges for creating data directory.               | NULL          |
+| `k3s_become_for_package_install` | Escalate user privileges for installing k3s.                        | NULL          |
+| `k3s_become_for_kubectl`         | Escalate user privileges for running `kubectl`.                     | NULL          |
+| `k3s_become_for_uninstall`       | Escalate user privileges for uninstalling k3s.                      | NULL          |
+
 #### Important note about `k3s_release_version`
 
 If you do not set a `k3s_release_version` the latest version from the stable

diff --git a/defaults/main.yml b/defaults/main.yml
@@ -15,13 +15,13 @@ k3s_release_version: false
 # Loction of the k3s configuration file
 k3s_config_file: /etc/rancher/k3s/config.yaml
 
-# When multiple play_hosts are present, attempt to cluster the nodes.
+# When multiple ansible_play_hosts_all are present, attempt to cluster the nodes.
 # Using false will create multiple standalone nodes.
 # (default: true)
 k3s_build_cluster: true
 
 # URL for GitHub project
-k3s_github_url: https://github.com/rancher/k3s
+k3s_github_url: https://github.com/k3s-io/k3s
 
 # Skip all tasks that validate configuration
 k3s_skip_validation: false
@@ -71,6 +71,7 @@ k3s_agent: {}
 k3s_become_for_all: false
 k3s_become_for_systemd: null
 k3s_become_for_install_dir: null
+k3s_become_for_manifests_dir: null
 k3s_become_for_usr_local_bin: null
 k3s_become_for_data_dir: null
 k3s_become_for_package_install: null

diff --git a/meta/main.yml b/meta/main.yml
@@ -5,6 +5,7 @@ galaxy_info:
   author: Xan Manning
   description: Ansible role for installing k3s as either a standalone server or HA cluster
   company: Pyrat Ltd.
+  github_branch: main
 
   # If the issue tracker for your role is not on github, uncomment the
   # next line and provide a value

diff --git a/tasks/build/configure-k3s-cluster.yml b/tasks/build/configure-k3s-cluster.yml
@@ -64,7 +64,7 @@
     enabled: true
   register: ensure_secondary_controllers_started
   until: ensure_secondary_controllers_started is succeeded
-  retries: "{{ play_hosts | length }}"
+  retries: "{{ ansible_play_hosts_all | length }}"
   delay: 5
   when: k3s_control_node and not k3s_primary_control_node
   become: "{{ k3s_become_for_systemd | ternary(true, false, k3s_become_for_all) }}"

diff --git a/tasks/build/preconfigure-k3s-auto-deploying-manifests.yml b/tasks/build/preconfigure-k3s-auto-deploying-manifests.yml
@@ -6,6 +6,7 @@
     path: "{{ k3s_server_manifests_dir }}"
     mode: 0755
   when: k3s_server_manifests_templates | length > 0
+  become: "{{ k3s_become_for_manifests_dir | ternary(true, false, k3s_become_for_all) }}"
 
 # https://rancher.com/docs/k3s/latest/en/advanced/#auto-deploying-manifests
 - name: Ensure Auto-Deploying Manifests are copied to controllers
@@ -14,3 +15,4 @@
     dest: "{{ k3s_server_manifests_dir }}/{{ item | basename | replace('.j2','') }}"
     mode: 0644
   loop: "{{ k3s_server_manifests_templates }}"
+  become: "{{ k3s_become_for_manifests_dir | ternary(true, false, k3s_become_for_all) }}"
diff --git a/tasks/build/preconfigure-k3s.yml b/tasks/build/preconfigure-k3s.yml
@@ -3,7 +3,7 @@
 - name: Ensure k3s_build_cluster is false if running against a single node.
   set_fact:
     k3s_build_cluster: false
-  when: play_hosts | length < 2
+  when: ansible_play_hosts_all | length < 2
         and k3s_control_node_address is not defined
 
 - name: Ensure k3s control node fact is set
@@ -16,12 +16,12 @@
     k3s_primary_control_node: "{{ 'false' if k3s_build_cluster else 'true' }}"
   when: k3s_primary_control_node is not defined
 
-- name: Ensure a k3s control node is defined if none are found in play_hosts
+- name: Ensure a k3s control node is defined if none are found in ansible_play_hosts_all
   block:
     - name: Set the control host
       set_fact:
         k3s_control_node: true
-      when: inventory_hostname == play_hosts[0]
+      when: inventory_hostname == ansible_play_hosts_all[0]
   when: true not in (hostvars | json_query('*.k3s_control_node'))
         and k3s_build_cluster is defined and k3s_build_cluster
 
@@ -30,9 +30,9 @@
     k3s_controller_count: "{{ k3s_controller_count + [ item ] }}"
   when: hostvars[item].k3s_control_node is defined
         and hostvars[item].k3s_control_node
-  loop: "{{ play_hosts }}"
+  loop: "{{ ansible_play_hosts_all }}"
 
-- name: Ensure a primary k3s control node is defined if multiple are found in play_hosts
+- name: Ensure a primary k3s control node is defined if multiple are found in ansible_play_hosts_all
   set_fact:
     k3s_primary_control_node: true
   when: k3s_controller_count is defined
@@ -54,7 +54,7 @@
     create: true
     regexp: "^{{ item }} @@@ {{ hostvars[item].ansible_host | default(hostvars[item].ansible_fqdn) }}"
     mode: 0600
-  loop: "{{ play_hosts }}"
+  loop: "{{ ansible_play_hosts_all }}"
   check_mode: false
   when: hostvars[item].k3s_control_node is defined
 

diff --git a/tasks/teardown/drain-and-remove-nodes.yml b/tasks/teardown/drain-and-remove-nodes.yml
@@ -25,7 +25,7 @@
       when: item in kubectl_get_nodes_result.stdout
             and hostvars[item].k3s_state is defined
             and hostvars[item].k3s_state == 'uninstalled'
-      loop: "{{ play_hosts }}"
+      loop: "{{ ansible_play_hosts_all }}"
       become: "{{ k3s_become_for_kubectl | ternary(true, false, k3s_become_for_all) }}"
 
     - name: Ensure uninstalled nodes are removed
@@ -35,7 +35,7 @@
       when: item in kubectl_get_nodes_result.stdout
             and hostvars[item].k3s_state is defined
             and hostvars[item].k3s_state == 'uninstalled'
-      loop: "{{ play_hosts }}"
+      loop: "{{ ansible_play_hosts_all }}"
       become: "{{ k3s_become_for_kubectl | ternary(true, false, k3s_become_for_all) }}"
 
   when: k3s_check_kubectl.stat.exists is defined

diff --git a/tasks/validate/issue-data.yml b/tasks/validate/issue-data.yml
@@ -47,11 +47,11 @@
       # End ANSIBLE ROLES
 
       # Begin PLAY HOSTS
-      {{ play_hosts | to_json }}
+      {{ ansible_play_hosts_all | to_json }}
       # End PLAY HOSTS
 
       # Begin K3S ROLE CONFIG
-      {% for host in play_hosts %}
+      {% for host in ansible_play_hosts_all %}
       ## {{ host }}
       {% for config_key in hostvars[host] | to_json | from_json | json_query('keys(@)[?starts_with(@, `k3s_`)]') %}
       {{ config_key }}: {{ hostvars[host][config_key] | to_json }}
@@ -61,7 +61,7 @@
       # End K3S ROLE CONFIG
 
       # Begin K3S RUNTIME CONFIG
-      {% for host in play_hosts %}
+      {% for host in ansible_play_hosts_all %}
       ## {{ host }}
       {{ hostvars[host].k3s_runtime_config }}
       {% endfor %}