diff --git a/.github/workflows/test_role_repos.yml b/.github/workflows/test_role_repos.yml index c9747027..50527099 100644 --- a/.github/workflows/test_role_repos.yml +++ b/.github/workflows/test_role_repos.yml @@ -14,6 +14,7 @@ on: pull_request: paths: - 'roles/repos/**' + - '!roles/repos/**/*.md' - '.github/workflows/test_role_repos.yml' - 'molecule/repos_**' diff --git a/README.md b/README.md index f4252d72..4615e139 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ Every role is documented with all variables, please refer to the documentation f * [Elasticsearch](docs/role-elasticsearch.md) * [Kibana](docs/role-kibana.md) * [Logstash](roles/logstash/README.md) -* [Repos](docs/role-repos.md) +* [Repos](roles/repos/README.md) ## Modules documentation diff --git a/docs/getting-started.md b/docs/getting-started.md index dc49fb40..b43d83c1 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -51,7 +51,7 @@ Roles * [Elasticsearch](role-elasticsearch.md) * [Kibana](role-kibana.md) * [Logstash](../roles/logstash/README.md) -* [Repos](role-repos.md) +* [Repos](../roles/repos/README.md) Variables diff --git a/docs/role-repos.md b/docs/role-repos.md index a47e62ce..bce0c25a 100644 --- a/docs/role-repos.md +++ b/docs/role-repos.md @@ -1,43 +1,5 @@ -Elastic Repos -========= +# Repos role -![Test Role repos](https://github.com/netways/ansible-collection-elasticstack/actions/workflows/test_role_repos.yml/badge.svg) +The Repos role documentation now lives with the role itself: -The role adds Elastic repositories to the package manager. It's main use is in connection with other roles that provide installation and configuration of the Elastic Stack. - -Requirements ------------- - -* You need `gpg` to be installed because packages / repositories are digitally signed and verified. -* Debian and Ubuntu hosts need to have `apt-transport-https` installed to deal with Elastics repositories. -* Ubuntu hosts also need to have `gpg-agent` installed. -* For SuSE hosts you need the Ansible collection `community.general` on your Ansible controller. - -Role Variables --------------- - -* *elasticstack_release*: Major release version of Elastic stack to configure. (default: `7`). `7` and `8` are supported. -* *elasticstack_variant*: Variant of the stack to install. Valid values: `elastic` or `oss`. (default: `elastic`). -* *elasticstack_enable_repos*: Enable repositories after creating them. (default: `true`) Only works on RPM based distributions! - -Please note that no `oss` versions are available for Elastic Stack later than `7`. This role will fail if you try to install them. - -Usage --------- - -Upgrades -======== - -If you want to be able to update your operating system without worrying about accidentally upgrading Elastic Stack, set `elasticstack_enable_repos` to `false`. The roles in this collection will enable the repository in case they need it. Keep in mind that this will only work on rpm based distributions. - -Example playbook -================ - -``` - - hosts: all - become: yes - collections: - - netways.elasticstack - roles: - - repos -``` +**➜ [roles/repos/README.md](../roles/repos/README.md)** diff --git a/roles/repos/README.md b/roles/repos/README.md new file mode 100644 index 00000000..fcbeb99f --- /dev/null +++ b/roles/repos/README.md @@ -0,0 +1,42 @@ +# Ansible Role: Repos + +Adds the Elastic package repositories to the target host so the other roles can +install Elastic Stack packages. It supports apt (Debian/Ubuntu), yum (RedHat) and +zypper (SUSE), for both the standard Elastic and the OSS variant. + +Its main use is together with the other roles of this collection, which expect +the Elastic repositories to be present. + +## Requirements + +* The `community.general` collection — only needed on SUSE hosts, where the role + uses the `zypper` modules. +* Network access from the target host to the Elastic repository URL. + +The role installs the required signing tools (`gpg`/`gnupg`) itself. + +## Example + +```yaml +- name: Configure Elastic repositories + hosts: all + collections: + - netways.elasticstack + roles: + - repos +``` + + +## Role variables + +No variables are defined for this role. + + + +## Shared variables + +This role is configured through the collection-wide `elasticstack_*` variables — +mainly `elasticstack_release`, `elasticstack_variant`, `elasticstack_enable_repos`, +`elasticstack_repo_url`, `elasticstack_repo_key` and `elasticstack_rpm_workaround`. +They are documented centrally with the +[elasticsearch role](../../docs/role-elasticsearch.md). diff --git a/roles/repos/meta/argument_specs.yml b/roles/repos/meta/argument_specs.yml new file mode 100644 index 00000000..e0b9a8f8 --- /dev/null +++ b/roles/repos/meta/argument_specs.yml @@ -0,0 +1,20 @@ +--- +# Role argument specification for the repos role. +# This is the single source of truth for the role's variables: Ansible validates +# the supplied values against it at role start, and ansible-docsmith renders the +# README variable reference from it. +# +# This role has no role-specific variables. It is configured entirely through the +# shared elasticstack_* variables, which are documented centrally with the +# elasticstack role. + +argument_specs: + main: + short_description: Configure the Elastic package repositories + description: + - >- + Adds the Elastic package repositories (apt, yum or zypper) to the target + host so the other roles can install Elastic Stack packages. + - Supports the standard Elastic and the OSS variant. + author: + - NETWAYS GmbH