Skip to content

Commit ddbfa4f

Browse files
NavidSassanNavidSassan
committed
docs(roles): rewrite all role READMEs to new standard format
1 parent 560eb7b commit ddbfa4f

153 files changed

Lines changed: 12813 additions & 2407 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1919

2020
### Changed
2121

22+
* **all roles**: Rewrite all role READMEs to use the new standard format: replace markdown tables with bullet lists for tags and variables, convert HTML/blockquote subkeys to expanded indented format, standardize terminology (`Bool` not `Boolean`, `Mandatory` not `Required`)
2223
* **role:opensearch**: Rewrite README with step-by-step cluster setup guide, single-node section, post-installation steps, and improved variable documentation
2324
* **role:elasticsearch**: Improve README with single-node section and clearer explanation of the manual certificate approach for cluster setup
2425
* **COMPATIBILITY**: Add missing `crypto_policy` RHEL 10 entry

‎roles/acme_sh/README.md‎

Lines changed: 85 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ SSLCertificateKeyFile /etc/pki/tls/private/www.example.com.key
1010
SSLCertificateChainFile /etc/pki/tls/certs/www.example.com-chain.crt
1111
```
1212

13+
1314
## Mandatory Requirements
1415

1516
* Install `openssl`. This can be done using the [linuxfabrik.lfops.apps](https://github.com/Linuxfabrik/lfops/tree/main/roles/apps) role.
@@ -30,19 +31,53 @@ If you use the [acme.sh Playbook](https://github.com/Linuxfabrik/lfops/blob/main
3031

3132
## Tags
3233

33-
| Tag | What it does | Reload / Restart |
34-
| --- | ------------ | ---------------- |
35-
| `acme_sh` | Installs acme.sh and issues certificates | - |
36-
| `acme_sh:certificates` | Issues certificates | - |
37-
| `acme_sh:state` | Manages the state of the weekly acme.sh timer | - |
34+
`acme_sh`
35+
36+
* Installs acme.sh and issues certificates.
37+
* Triggers: none.
38+
39+
`acme_sh:certificates`
40+
41+
* Issues certificates.
42+
* Triggers: none.
43+
44+
`acme_sh:state`
45+
46+
* Manages the state of the weekly acme.sh timer.
47+
* Triggers: none.
3848

3949

4050
## Mandatory Role Variables
4151

42-
| Variable | Description |
43-
| -------- | ----------- |
44-
| `acme_sh__account_email` | Email address for the Let's encrypt account. This address will receive expiry emails. |
45-
| `acme_sh__certificates` | List of certificates that should be issued. Subkeys: <ul><li>`name`: Mandatory, string. Domain of the certificate.</li><li>`alternative_names`: Optional, list. Subject Alternative Names (SAN) for the certificate. Defaults to unset.</li><li>`reload_cmd`: Optional, string. Command to execute after issue/renew to reload the server. Defaults to `systemctl reload httpd`.</li></ul> |
52+
`acme_sh__account_email`
53+
54+
* Email address for the Let's encrypt account. This address will receive expiry emails.
55+
* Type: String.
56+
* Default: none
57+
58+
`acme_sh__certificates`
59+
60+
* List of certificates that should be issued.
61+
* Type: List of dictionaries.
62+
* Default: none
63+
* Subkeys:
64+
65+
* `name`:
66+
67+
* Mandatory. Domain of the certificate.
68+
* Type: String.
69+
70+
* `alternative_names`:
71+
72+
* Optional. Subject Alternative Names (SAN) for the certificate.
73+
* Type: List.
74+
* Default: unset
75+
76+
* `reload_cmd`:
77+
78+
* Optional. Command to execute after issue/renew to reload the server.
79+
* Type: String.
80+
* Default: `'systemctl reload httpd'`
4681

4782
Example:
4883
```yaml
@@ -59,15 +94,47 @@ acme_sh__certificates:
5994
6095
## Optional Role Variables
6196
62-
| Variable | Description | Default Value |
63-
| -------- | ----------- | ------------- |
64-
| `acme_sh__deploy_to_host` | The host which the issued certificates should be deployed to. | unset |
65-
| `acme_sh__deploy_to_host_hook` | The deployment hook which should be used to deploy the certificates to the deploy host. | `ssh` |
66-
| `acme_sh__deploy_to_host_reload_cmd` | The reload command which should be executed on the deploy host after the certificates were deployed to the deploy host. | `reload_cmd` subkey of the `acme_sh__certificates` item, or `systemctl reload httpd` |
67-
| `acme_sh__deploy_to_host_user` | The remote user account which should be used to deploy the certificates to the deploy host. | `root` |
68-
| `acme_sh__key_length` | Key length in bits of the certificates to issue. | `4096` |
69-
| `acme_sh__reload_cmd` | The reload command which should be executed on the local host after the certificates were installed. | `reload_cmd` subkey of the `acme_sh__certificates` item, or `systemctl reload httpd` |
70-
| `acme_sh__timer_enabled` | Enables or disables the weekly acme.sh timer, analogous to `systemctl enable/disable --now`. | `true` |
97+
`acme_sh__deploy_to_host`
98+
99+
* The host which the issued certificates should be deployed to.
100+
* Type: String.
101+
* Default: unset
102+
103+
`acme_sh__deploy_to_host_hook`
104+
105+
* The deployment hook which should be used to deploy the certificates to the deploy host.
106+
* Type: String.
107+
* Default: `'ssh'`
108+
109+
`acme_sh__deploy_to_host_reload_cmd`
110+
111+
* The reload command which should be executed on the deploy host after the certificates were deployed to the deploy host.
112+
* Type: String.
113+
* Default: `reload_cmd` subkey of the `acme_sh__certificates` item, or `'systemctl reload httpd'`
114+
115+
`acme_sh__deploy_to_host_user`
116+
117+
* The remote user account which should be used to deploy the certificates to the deploy host.
118+
* Type: String.
119+
* Default: `'root'`
120+
121+
`acme_sh__key_length`
122+
123+
* Key length in bits of the certificates to issue.
124+
* Type: Number.
125+
* Default: `4096`
126+
127+
`acme_sh__reload_cmd`
128+
129+
* The reload command which should be executed on the local host after the certificates were installed.
130+
* Type: String.
131+
* Default: `reload_cmd` subkey of the `acme_sh__certificates` item, or `'systemctl reload httpd'`
132+
133+
`acme_sh__timer_enabled`
134+
135+
* Enables or disables the weekly acme.sh timer, analogous to `systemctl enable/disable --now`.
136+
* Type: Bool.
137+
* Default: `true`
71138

72139
Example:
73140
```yaml

‎roles/alternatives/README.md‎

Lines changed: 36 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -11,16 +11,46 @@ Hints:
1111

1212
## Tags
1313

14-
| Tag | What it does | Reload / Restart |
15-
| --- | ------------ | ---------------- |
16-
| `alternatives` | Manages alternative programs for common commands. | - |
14+
`alternatives`
15+
16+
* Manages alternative programs for common commands.
17+
* Triggers: none.
1718

1819

1920
## Mandatory Role Variables
2021

21-
| Variable | Description | Default Value |
22-
| -------- | ----------- | ------------- |
23-
| `alternatives__alternatives` | List of alternatives to remove or to deploy. Subkeys:<ul><li>`link`: String. The path to the symbolic link that should point to the real executable. This option is always required on RHEL-based distributions. On Debian-based distributions this option is required when the alternative `name` is unknown to the system.</li><li>`name`: Mandatory, string. The generic name of the link.</li><li>`path`: Optional, string. The path to the real executable that the link should point to.</li><li>`priority`: Optional, number. The priority of the alternative. If no priority is given for creation `50` is used as a fallback.</li><li>`state`: Optional, string. One of:<ul><li>`selected`: Default. Install the alternative (if not already installed), and set it as the currently selected alternative for the group.</li><li>`present`: Install the alternative (if not already installed), but do not set it as the currently selected alternative for the group.</li><li>`auto`: Install the alternative (if not already installed), and set the group to auto mode.</li><li>`absent`: Remove the alternative.</li></ul></ul> | `[]` |
22+
`alternatives__alternatives`
23+
24+
* List of alternatives to remove or to deploy.
25+
* Type: List of dictionaries.
26+
* Default: `[]`
27+
* Subkeys:
28+
29+
* `link`:
30+
31+
* The path to the symbolic link that should point to the real executable. This option is always required on RHEL-based distributions. On Debian-based distributions this option is required when the alternative `name` is unknown to the system.
32+
* Type: String.
33+
34+
* `name`:
35+
36+
* Mandatory. The generic name of the link.
37+
* Type: String.
38+
39+
* `path`:
40+
41+
* Optional. The path to the real executable that the link should point to.
42+
* Type: String.
43+
44+
* `priority`:
45+
46+
* Optional. The priority of the alternative. If no priority is given for creation `50` is used as a fallback.
47+
* Type: Number.
48+
49+
* `state`:
50+
51+
* Optional. One of: `selected` (default; install the alternative and set it as the currently selected alternative for the group), `present` (install the alternative but do not set it as the currently selected alternative for the group), `auto` (install the alternative and set the group to auto mode), `absent` (remove the alternative).
52+
* Type: String.
53+
* Default: `'selected'`
2454

2555
Example:
2656
```yaml

‎roles/ansible_init/README.md‎

Lines changed: 103 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -14,20 +14,36 @@ This role:
1414

1515
## Tags
1616

17-
| Tag | What it does | Reload / Restart |
18-
| --- | ------------ | ---------------- |
19-
| `ansible_init` | * Update ansible_init (ansinv) itself<br> * Update ../lfops<br> * Load repo list<br> * Clone the inventories<br> * Install ansible collections | - |
20-
| `ansible_init:collections` | Install ansible collections | - |
21-
| `ansible_init:command` | Load repo list | - |
17+
`ansible_init`
18+
19+
* Update ansible_init (ansinv) itself.
20+
* Update ../lfops.
21+
* Load repo list.
22+
* Clone the inventories.
23+
* Install ansible collections.
24+
* Triggers: none.
25+
26+
`ansible_init:collections`
27+
28+
* Install ansible collections.
29+
* Triggers: none.
30+
31+
`ansible_init:command`
32+
33+
* Load repo list.
34+
* Triggers: none.
2235

2336

2437
## Mandatory Role Variables
2538

26-
| Variable | Description |
27-
| -------- | ----------- |
28-
| `ansible_init__url` | URL of the ansinv repo. |
39+
`ansible_init__url`
40+
41+
* URL of the ansinv repo.
42+
* Type: String.
43+
* Default: none
2944

3045
Example:
46+
3147
```yaml
3248
# mandatory
3349
ansible_init__url: 'git@example.com:my-ansinv.git'
@@ -36,15 +52,87 @@ ansible_init__url: 'git@example.com:my-ansinv.git'
3652
3753
## Optional Role Variables
3854
39-
| Variable | Description | Default Value |
40-
| -------- | ----------- | ------------- |
41-
| `ansible_init__ansible_collections` | List of dictionaries of Ansible collections to install. Subkeys: <br> * `name`: Mandatory, string. Name of the collection. <br> * `type`. Optional. Defaults to `collection`. One of `collection`, `role`, or `both`. | `[]` |
42-
| `ansible_init__inventories` | List of dictionaries of inventories to clone. Subkeys: <br> * `name`: Mandatory, string. Name of the inventory. Will be used as the folder name. <br> * `url`: Mandatory, string. Git, SSH, or HTTP(S) protocol address of the repository. <br> * `version`: Optional, string. Defaults to `'main'`. Git version to checkout. | `[]` |
43-
| `ansible_init__lfops_url` | URL of the LFOps repo. Either `'git@github.com:Linuxfabrik/lfops.git'` for development purposes, or `'https://github.com/Linuxfabrik/lfops.git'` for general access. | `'https://github.com/Linuxfabrik/lfops.git'` |
44-
| `ansible_init__roles` | List of dictionaries of roles to clone. Subkeys: <br> * `name`: Mandatory, string. Name of the role. Will be used as the folder name. <br> * `url`: Mandatory, string. Git, SSH, or HTTP(S) protocol address of the repository. <br> * `version`: Optional, string. Defaults to `'main'`. Git version to checkout. | `[]` |
45-
| `ansible_init__version` | Git version of the ansinv repo to checkout. | `'main'` |
55+
`ansible_init__ansible_collections`
56+
57+
* List of dictionaries of Ansible collections to install.
58+
* Subkeys:
59+
60+
* `name`:
61+
62+
* Mandatory. Name of the collection.
63+
* Type: String.
64+
65+
* `type`:
66+
67+
* Optional. One of `collection`, `role`, or `both`.
68+
* Type: String.
69+
* Default: `'collection'`
70+
71+
* Type: List of dictionaries.
72+
* Default: `[]`
73+
74+
`ansible_init__inventories`
75+
76+
* List of dictionaries of inventories to clone.
77+
* Subkeys:
78+
79+
* `name`:
80+
81+
* Mandatory. Name of the inventory. Will be used as the folder name.
82+
* Type: String.
83+
84+
* `url`:
85+
86+
* Mandatory. Git, SSH, or HTTP(S) protocol address of the repository.
87+
* Type: String.
88+
89+
* `version`:
90+
91+
* Optional. Git version to checkout.
92+
* Type: String.
93+
* Default: `'main'`
94+
95+
* Type: List of dictionaries.
96+
* Default: `[]`
97+
98+
`ansible_init__lfops_url`
99+
100+
* URL of the LFOps repo. Either `'git@github.com:Linuxfabrik/lfops.git'` for development purposes, or `'https://github.com/Linuxfabrik/lfops.git'` for general access.
101+
* Type: String.
102+
* Default: `'https://github.com/Linuxfabrik/lfops.git'`
103+
104+
`ansible_init__roles`
105+
106+
* List of dictionaries of roles to clone.
107+
* Subkeys:
108+
109+
* `name`:
110+
111+
* Mandatory. Name of the role. Will be used as the folder name.
112+
* Type: String.
113+
114+
* `url`:
115+
116+
* Mandatory. Git, SSH, or HTTP(S) protocol address of the repository.
117+
* Type: String.
118+
119+
* `version`:
120+
121+
* Optional. Git version to checkout.
122+
* Type: String.
123+
* Default: `'main'`
124+
125+
* Type: List of dictionaries.
126+
* Default: `[]`
127+
128+
`ansible_init__version`
129+
130+
* Git version of the ansinv repo to checkout.
131+
* Type: String.
132+
* Default: `'main'`
46133

47134
Example:
135+
48136
```yaml
49137
# optional
50138
ansible_init__ansible_collections:

0 commit comments

Comments
 (0)