From 9495b9f25a0d692de93a8d2398be89eeb9379275 Mon Sep 17 00:00:00 2001 From: Jonas L Date: Thu, 21 Dec 2023 17:49:24 +0100 Subject: [PATCH] docs: improve hcloud inventory documentation (#434) ##### SUMMARY - Re add some examples that were removed during a dep upgrade. - Improve link to other reference (plugins/modules/options) - Remove duplicate docs. --- plugins/inventory/hcloud.py | 34 ++++++++++++++++++++++------------ tests/sanity/ignore-2.13.txt | 1 + tests/sanity/ignore-2.14.txt | 1 + tests/sanity/ignore-2.15.txt | 1 + tests/sanity/ignore-2.16.txt | 1 + 5 files changed, 26 insertions(+), 12 deletions(-) create mode 100644 tests/sanity/ignore-2.15.txt create mode 100644 tests/sanity/ignore-2.16.txt diff --git a/plugins/inventory/hcloud.py b/plugins/inventory/hcloud.py index ec6d8061..44934227 100644 --- a/plugins/inventory/hcloud.py +++ b/plugins/inventory/hcloud.py @@ -3,7 +3,7 @@ from __future__ import annotations -DOCUMENTATION = r""" +DOCUMENTATION = """ name: hcloud short_description: Ansible dynamic inventory plugin for the Hetzner Cloud. @@ -24,16 +24,15 @@ options: plugin: - description: Mark this as an C(hetzner.hcloud.hcloud) inventory instance. + description: Mark this as an P(hetzner.hcloud.hcloud#inventory) inventory instance. required: true choices: [hcloud, hetzner.hcloud.hcloud] api_token: description: - The API Token for the Hetzner Cloud. - - You can also set this option by using the C(HCLOUD_TOKEN) environment variable. type: str - required: false # TODO: Mark as required once I(api_token_env) is removed. + required: false # TODO: Mark as required once 'api_token_env' is removed. aliases: [token] env: - name: HCLOUD_TOKEN @@ -47,11 +46,10 @@ why: The option is adding too much complexity, while the alternatives are preferred. collection_name: hetzner.hcloud version: 3.0.0 - alternatives: Use the ``{{ lookup('ansible.builtin.env', 'YOUR_ENV_VAR') }}`` lookup instead. + alternatives: Use the P(ansible.builtin.env#lookup) lookup plugin instead. api_endpoint: description: - The API Endpoint for the Hetzner Cloud. - - You can also set this option by using the C(HCLOUD_ENDPOINT) environment variable. type: str default: https://api.hetzner.cloud/v1 env: @@ -64,10 +62,10 @@ required: false connect_with: description: | - Connect to the server using the value from this field. This sets the `ansible_host` + Connect to the server using the value from this field. This sets the C(ansible_host) variable to the value indicated, if that value is available. If you need further customization, like falling back to private ipv4 if the server has no public ipv4, - you can use `compose` top-level key. + you can use O(compose) top-level key. default: public_ipv4 type: str choices: @@ -124,8 +122,18 @@ version_added: 2.5.0 """ -EXAMPLES = r""" -plugin: hcloud +EXAMPLES = """ +# Minimal example. 'HCLOUD_TOKEN' is exposed in environment. +plugin: hetzner.hcloud.hcloud + +--- +# Example with templated token, e.g. provided through extra vars. +plugin: hetzner.hcloud.hcloud +api_token: "{{ _vault_hetzner_cloud_token }}" + +--- +# Example with locations, types, status +plugin: hetzner.hcloud.hcloud locations: - nbg1 types: @@ -133,9 +141,11 @@ status: - running +--- # Group by a location with prefix e.g. "hcloud_location_nbg1" # and image_os_flavor without prefix and separator e.g. "ubuntu" # and status with prefix e.g. "server_status_running" +plugin: hetzner.hcloud.hcloud keyed_groups: - key: location prefix: hcloud_location @@ -238,7 +248,7 @@ def _configure_hcloud_client(self): api_token_env = self.get_option("api_token_env") if api_token_env != "HCLOUD_TOKEN": self.display.deprecated( - "The 'api_token_env' option is deprecated, please use the `HCLOUD_TOKEN` " + "The 'api_token_env' option is deprecated, please use the 'HCLOUD_TOKEN' " "environment variable or use the 'ansible.builtin.env' lookup instead.", version="3.0.0", collection_name="hetzner.hcloud", @@ -360,7 +370,7 @@ def _build_inventory_server(self, server: Server) -> InventoryServer: server_dict["ansible_host"] = self._get_server_ansible_host(server) except AnsibleError as exception: # Log warning that for this host can not be connected to, using the - # method specified in `connect_with`. Users might use `compose` to + # method specified in 'connect_with'. Users might use 'compose' to # override the connection method, or implement custom logic, so we # do not need to abort if nothing matched. self.display.v(f"[hcloud] {exception}", server.name) diff --git a/tests/sanity/ignore-2.13.txt b/tests/sanity/ignore-2.13.txt index 176c4260..23dcfbc2 100644 --- a/tests/sanity/ignore-2.13.txt +++ b/tests/sanity/ignore-2.13.txt @@ -1,5 +1,6 @@ plugins/inventory/hcloud.py validate-modules:illegal-future-imports plugins/inventory/hcloud.py validate-modules:import-before-documentation +plugins/inventory/hcloud.py yamllint:unparsable-with-libyaml # bug in ansible-test - https://github.com/ansible/ansible/issues/82353 plugins/modules/certificate_info.py validate-modules:illegal-future-imports plugins/modules/certificate_info.py validate-modules:import-before-documentation plugins/modules/certificate.py validate-modules:illegal-future-imports diff --git a/tests/sanity/ignore-2.14.txt b/tests/sanity/ignore-2.14.txt index c0315363..95982f35 100644 --- a/tests/sanity/ignore-2.14.txt +++ b/tests/sanity/ignore-2.14.txt @@ -1,4 +1,5 @@ plugins/inventory/hcloud.py validate-modules:illegal-future-imports +plugins/inventory/hcloud.py yamllint:unparsable-with-libyaml # bug in ansible-test - https://github.com/ansible/ansible/issues/82353 plugins/modules/certificate_info.py validate-modules:illegal-future-imports plugins/modules/certificate_info.py validate-modules:import-before-documentation plugins/modules/certificate.py validate-modules:illegal-future-imports diff --git a/tests/sanity/ignore-2.15.txt b/tests/sanity/ignore-2.15.txt new file mode 100644 index 00000000..d6cabf4c --- /dev/null +++ b/tests/sanity/ignore-2.15.txt @@ -0,0 +1 @@ +plugins/inventory/hcloud.py yamllint:unparsable-with-libyaml # bug in ansible-test - https://github.com/ansible/ansible/issues/82353 diff --git a/tests/sanity/ignore-2.16.txt b/tests/sanity/ignore-2.16.txt new file mode 100644 index 00000000..d6cabf4c --- /dev/null +++ b/tests/sanity/ignore-2.16.txt @@ -0,0 +1 @@ +plugins/inventory/hcloud.py yamllint:unparsable-with-libyaml # bug in ansible-test - https://github.com/ansible/ansible/issues/82353