diff --git a/README.md b/README.md index 061bfe0d..c296052a 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,10 @@ Every role is documented with all variables, please refer to the documentation f ## Global variables +The collection-wide `elasticstack_*` variables (release, variant, inventory host +groups, ports, package repositories, and the shared CA) are documented centrally +with the [elasticstack role](roles/elasticstack/README.md). + * `elasticstack_force_pip`: Will force installation of required Python modules via `pip`. This is useful if your package manager doesn't provide current versions of modules. (Default: `false`) See [PEP668](https://peps.python.org/pep-0668/) for more details. * `elasticstack_manage_pip`: Will install `pip` on your system. (Default: `false`) diff --git a/docs/getting-started.md b/docs/getting-started.md index 4984340b..320e757f 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -57,7 +57,7 @@ Roles Variables ----------- -Every role got its own set of variables, in addition a few variables are useable on any role. Below are all general collection vars. +Every role got its own set of variables, in addition a few variables are useable on any role. The collection-wide `elasticstack_*` variables are documented centrally with the [elasticstack role](../roles/elasticstack/README.md). Two common ones: * *elasticstack_release*: Major release version of Elastic stack to configure. (default: `7`) * *elasticstack_variant*: Variant of the stack to install. Valid values: `elastic` or `oss`. (default: `elastic`) diff --git a/roles/elasticstack/README.md b/roles/elasticstack/README.md new file mode 100644 index 00000000..e39aa897 --- /dev/null +++ b/roles/elasticstack/README.md @@ -0,0 +1,66 @@ +# Ansible Role: elasticstack + +The shared base role of the collection. Every component role (elasticsearch, +logstash, kibana, beats, repos) imports it automatically on first use, so you +normally do not call it directly. It installs the common dependencies and, above +all, defines the collection-wide `elasticstack_*` variables — the settings shared +across all roles: release and variant, the inventory host groups, ports, the +package repositories, and the stack CA. + +Set these variables once (in `group_vars`, the play, or via `-e`) and every role +picks them up. This page is the central reference for them. + +## Requirements + +You do not run this role directly — the component roles import it automatically. +It installs the shared Python libraries (`cryptography` and the `elasticsearch` +client) and packages (`openssl`, `unzip`) that the collection needs. + +## Example + +You normally set the shared variables rather than invoking the role directly: + +```yaml +# group_vars/all.yml +elasticstack_release: 8 +elasticstack_variant: elastic +elasticstack_ca_pass: "a strong secret" +``` + +The role runs automatically the first time any component role is applied to a host. + + +## Role variables + +| Variable | Type | Default | Choices | Description | +|----------|------|---------|---------|-------------| +| `elasticstack_release` | `int` | `8` | — | Major Elastic Stack release to install and configure (e.g. 7 or 8). Drives the package repository and release-dependent behaviour. | +| `elasticstack_variant` | `str` | `"elastic"` | `elastic`, `oss` | Distribution to install. "elastic" (the default) includes X-Pack; "oss" is the Apache-licensed build without X-Pack. OSS Elasticsearch and Kibana exist only up to release 7, while OSS Logstash and Beats are available on later releases too. | +| `elasticstack_version` | `str` | N/A | — | Exact package version to install (e.g. "8.8.1"). Unset by default: the collection then installs the latest, or reuses the version already present on the CA host. | +| `elasticstack_full_stack` | `bool` | `true` | — | Treat the hosts as one coordinated stack (roles read each other's hosts, share the CA and wire the connections). Set to false to run a role standalone. | +| `elasticstack_security` | `bool` | `true` | — | Enable X-Pack security across the stack. Only effective with the elastic variant. | +| `elasticstack_override_beats_tls` | `bool` | `false` | — | Override the automatically derived TLS setting for the Beats input. | +| `elasticstack_elasticsearch_group_name` | `str` | `"elasticsearch"` | — | Inventory group that holds the Elasticsearch hosts. | +| `elasticstack_logstash_group_name` | `str` | `"logstash"` | — | Inventory group that holds the Logstash hosts. | +| `elasticstack_kibana_group_name` | `str` | `"kibana"` | — | Inventory group that holds the Kibana hosts. | +| `elasticstack_elasticsearch_http_port` | `int` | `9200` | — | Elasticsearch HTTP API port. | +| `elasticstack_kibana_port` | `int` | `5601` | — | Kibana HTTP port (also used to build the public base URL). | +| `elasticstack_beats_port` | `int` | `5044` | — | Port of the Logstash Beats input that the Beats ship to. | +| `elasticstack_enable_repos` | `bool` | `true` | — | Configure the Elastic package repositories (see the repos role). | +| `elasticstack_repo_url` | `str` | `"https://artifacts.elastic.co/packages"` | — | Base URL of the Elastic package repositories. | +| `elasticstack_repo_key` | `str` | `"https://artifacts.elastic.co/GPG-KEY-elasticsearch"` | — | URL of the Elastic repository signing (GPG) key. | +| `elasticstack_rpm_workaround` | `bool` | `false` | — | Enable a workaround for importing the repository GPG key on RPM-based systems. | +| `elasticstack_ca_host` | `str` | `"{{ groups[elasticstack_elasticsearch_group_name][0] \| default('') }}"` | — | Inventory host that holds the stack CA and signs all component certificates. Defaults to the first host in the elasticsearch group. | +| `elasticstack_ca_dir` | `str` | `"/opt/es-ca"` | — | Directory on the CA host where the CA and generated certificates are stored. | +| `elasticstack_ca_name` | `str` | `"CN=Elastic Certificate Tool Autogenerated CA"` | — | Distinguished name (DN) of the generated CA. | +| `elasticstack_ca_pass` | `str` | `"PleaseChangeMe"` | — | Password protecting the CA private key. | +| `elasticstack_ca_validity_period` | `int` | `1095` | — | Number of days the generated CA is valid. | +| `elasticstack_ca_expiration_buffer` | `int` | `30` | — | Renew the CA when its remaining validity (in days) drops below this value. | +| `elasticstack_ca_will_expire_soon` | `bool` | `false` | — | Set to true to force renewal of the CA and all component certificates. Alternatively run the playbook with the renew_ca tag. | +| `elasticstack_cert_pass` | `str` | N/A | — | Common passphrase for all component certificates. Unset by default; when set, it overrides each role's individual certificate passphrase. | +| `elasticstack_initial_passwords` | `str` | `"/usr/share/elasticsearch/initial_passwords"` | — | Path on the CA host where the generated initial passwords are stored. | +| `elasticstack_no_log` | `bool` | `true` | — | Hide the output of tasks that could reveal passwords. Set to false for debugging. | +| `elasticstack_manage_pip` | `bool` | `false` | — | Install pip on the target host. | +| `elasticstack_force_pip` | `bool` | `false` | — | Force installation of the required Python modules via pip (useful when the distribution packages are too old). See PEP 668. | + + diff --git a/roles/elasticstack/defaults/main.yml b/roles/elasticstack/defaults/main.yml index 5eb2b88d..472bbff1 100644 --- a/roles/elasticstack/defaults/main.yml +++ b/roles/elasticstack/defaults/main.yml @@ -5,7 +5,7 @@ elasticstack_logstash_group_name: logstash elasticstack_kibana_group_name: kibana elasticstack_beats_port: 5044 -elasticstack_ca_host: "{{ groups[elasticstack_elasticsearch_group_name][0] }}" +elasticstack_ca_host: "{{ groups[elasticstack_elasticsearch_group_name][0] | default('') }}" elasticstack_ca_dir: /opt/es-ca elasticstack_ca_expiration_buffer: 30 elasticstack_ca_name: "CN=Elastic Certificate Tool Autogenerated CA" diff --git a/roles/elasticstack/meta/argument_specs.yml b/roles/elasticstack/meta/argument_specs.yml new file mode 100644 index 00000000..3a7a03f4 --- /dev/null +++ b/roles/elasticstack/meta/argument_specs.yml @@ -0,0 +1,189 @@ +--- +# Role argument specification for the elasticstack role. +# This is the collection's central meta/base role: it is imported once per host +# and holds the shared elasticstack_* variables that every other role uses. +# ansible-docsmith renders the README from this file, which serves as the +# collection's central documentation for the shared variables. + +argument_specs: + main: + short_description: Shared Elastic Stack setup and variables + description: + - >- + Base role of the collection, imported automatically by the component + roles. It installs shared dependencies and defines the collection-wide + elasticstack_* variables used by every role: version/variant, the + inventory host groups, ports, package repositories, and the shared CA. + author: + - NETWAYS GmbH + + options: + + # ----- Stack version & variant ----- + elasticstack_release: + type: int + default: 8 + description: >- + Major Elastic Stack release to install and configure (e.g. 7 or 8). + Drives the package repository and release-dependent behaviour. + + elasticstack_variant: + type: str + default: elastic + choices: + - elastic + - oss + description: >- + Distribution to install. "elastic" (the default) includes X-Pack; "oss" + is the Apache-licensed build without X-Pack. OSS Elasticsearch and + Kibana exist only up to release 7, while OSS Logstash and Beats are + available on later releases too. + + elasticstack_version: + type: str + description: >- + Exact package version to install (e.g. "8.8.1"). Unset by default: the + collection then installs the latest, or reuses the version already + present on the CA host. + + # ----- Deployment mode ----- + elasticstack_full_stack: + type: bool + default: true + description: >- + Treat the hosts as one coordinated stack (roles read each other's hosts, + share the CA and wire the connections). Set to false to run a role + standalone. + + elasticstack_security: + type: bool + default: true + description: Enable X-Pack security across the stack. Only effective with the elastic variant. + + elasticstack_override_beats_tls: + type: bool + default: false + description: Override the automatically derived TLS setting for the Beats input. + + # ----- Inventory host groups ----- + elasticstack_elasticsearch_group_name: + type: str + default: elasticsearch + description: Inventory group that holds the Elasticsearch hosts. + + elasticstack_logstash_group_name: + type: str + default: logstash + description: Inventory group that holds the Logstash hosts. + + elasticstack_kibana_group_name: + type: str + default: kibana + description: Inventory group that holds the Kibana hosts. + + # ----- Ports ----- + elasticstack_elasticsearch_http_port: + type: int + default: 9200 + description: Elasticsearch HTTP API port. + + elasticstack_kibana_port: + type: int + default: 5601 + description: Kibana HTTP port (also used to build the public base URL). + + elasticstack_beats_port: + type: int + default: 5044 + description: Port of the Logstash Beats input that the Beats ship to. + + # ----- Package repositories ----- + elasticstack_enable_repos: + type: bool + default: true + description: Configure the Elastic package repositories (see the repos role). + + elasticstack_repo_url: + type: str + default: https://artifacts.elastic.co/packages + description: Base URL of the Elastic package repositories. + + elasticstack_repo_key: + type: str + default: https://artifacts.elastic.co/GPG-KEY-elasticsearch + description: URL of the Elastic repository signing (GPG) key. + + elasticstack_rpm_workaround: + type: bool + default: false + description: Enable a workaround for importing the repository GPG key on RPM-based systems. + + # ----- CA & certificates (shared across the stack) ----- + elasticstack_ca_host: + type: str + default: "{{ groups[elasticstack_elasticsearch_group_name][0] | default('') }}" + description: >- + Inventory host that holds the stack CA and signs all component + certificates. Defaults to the first host in the elasticsearch group. + + elasticstack_ca_dir: + type: str + default: /opt/es-ca + description: Directory on the CA host where the CA and generated certificates are stored. + + elasticstack_ca_name: + type: str + default: CN=Elastic Certificate Tool Autogenerated CA + description: Distinguished name (DN) of the generated CA. + + elasticstack_ca_pass: + type: str + default: PleaseChangeMe + description: Password protecting the CA private key. + + elasticstack_ca_validity_period: + type: int + default: 1095 + description: Number of days the generated CA is valid. + + elasticstack_ca_expiration_buffer: + type: int + default: 30 + description: Renew the CA when its remaining validity (in days) drops below this value. + + elasticstack_ca_will_expire_soon: + type: bool + default: false + description: >- + Set to true to force renewal of the CA and all component certificates. + Alternatively run the playbook with the renew_ca tag. + + elasticstack_cert_pass: + type: str + description: >- + Common passphrase for all component certificates. Unset by default; when + set, it overrides each role's individual certificate passphrase. + + # ----- Passwords & logging ----- + elasticstack_initial_passwords: + type: str + default: /usr/share/elasticsearch/initial_passwords + description: Path on the CA host where the generated initial passwords are stored. + + elasticstack_no_log: + type: bool + default: true + description: Hide the output of tasks that could reveal passwords. Set to false for debugging. + + # ----- Python dependencies ----- + elasticstack_manage_pip: + type: bool + default: false + description: Install pip on the target host. + + elasticstack_force_pip: + type: bool + default: false + description: >- + Force installation of the required Python modules via pip (useful when + the distribution packages are too old). See PEP 668.