From afc4dc2456c57c325d3d0d447e1da0b743a6fa8c Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Wed, 8 Jan 2025 19:37:55 +0100 Subject: [PATCH] Use multiple YAML documents for inventory plugin examples (#9551) * Use multiple YAML documents for inventory plugin examples. * Add ignore.txt entries. * Delete no longer needed ignore.txt files. * Fix typo. Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --------- Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> (cherry picked from commit 3f7ea607664397e130d6c3f00c99b5874b9172af) --- plugins/inventory/gitlab_runners.py | 2 ++ plugins/inventory/iocage.py | 5 +++++ plugins/inventory/linode.py | 5 +++++ plugins/inventory/lxd.py | 3 +++ plugins/inventory/nmap.py | 4 +++- plugins/inventory/proxmox.py | 5 +++++ plugins/inventory/scaleway.py | 3 +++ plugins/inventory/virtualbox.py | 15 ++++++++------- tests/sanity/ignore-2.13.txt | 14 -------------- tests/sanity/ignore-2.13.txt.license | 3 --- tests/sanity/ignore-2.14.txt | 16 ---------------- tests/sanity/ignore-2.14.txt.license | 3 --- tests/sanity/ignore-2.15.txt | 8 ++++++++ tests/sanity/ignore-2.16.txt | 8 ++++++++ 14 files changed, 50 insertions(+), 44 deletions(-) delete mode 100644 tests/sanity/ignore-2.13.txt delete mode 100644 tests/sanity/ignore-2.13.txt.license delete mode 100644 tests/sanity/ignore-2.14.txt delete mode 100644 tests/sanity/ignore-2.14.txt.license diff --git a/plugins/inventory/gitlab_runners.py b/plugins/inventory/gitlab_runners.py index 9a467905dd2..cd6f40169a8 100644 --- a/plugins/inventory/gitlab_runners.py +++ b/plugins/inventory/gitlab_runners.py @@ -58,10 +58,12 @@ ''' EXAMPLES = ''' +--- # gitlab_runners.yml plugin: community.general.gitlab_runners host: https://gitlab.com +--- # Example using constructed features to create groups and set ansible_host plugin: community.general.gitlab_runners host: https://gitlab.com diff --git a/plugins/inventory/iocage.py b/plugins/inventory/iocage.py index 5dc18b47100..f30ec02dd42 100644 --- a/plugins/inventory/iocage.py +++ b/plugins/inventory/iocage.py @@ -70,14 +70,17 @@ ''' EXAMPLES = ''' +--- # file name must end with iocage.yaml or iocage.yml plugin: community.general.iocage host: 10.1.0.73 user: admin +--- # user is not required if iocage is running on localhost (default) plugin: community.general.iocage +--- # run cryptography without legacy algorithms plugin: community.general.iocage host: 10.1.0.73 @@ -85,6 +88,7 @@ env: CRYPTOGRAPHY_OPENSSL_NO_LEGACY: 1 +--- # enable cache plugin: community.general.iocage host: 10.1.0.73 @@ -93,6 +97,7 @@ CRYPTOGRAPHY_OPENSSL_NO_LEGACY: 1 cache: true +--- # see inventory plugin ansible.builtin.constructed plugin: community.general.iocage host: 10.1.0.73 diff --git a/plugins/inventory/linode.py b/plugins/inventory/linode.py index 46f2faeacea..2419ef31976 100644 --- a/plugins/inventory/linode.py +++ b/plugins/inventory/linode.py @@ -79,15 +79,18 @@ ''' EXAMPLES = r''' +--- # Minimal example. `LINODE_ACCESS_TOKEN` is exposed in environment. plugin: community.general.linode +--- # You can use Jinja to template the access token. plugin: community.general.linode access_token: "{{ lookup('ini', 'token', section='your_username', file='~/.config/linode-cli') }}" # For older Ansible versions, you need to write this as: # access_token: "{{ lookup('ini', 'token section=your_username file=~/.config/linode-cli') }}" +--- # Example with regions, types, groups and access token plugin: community.general.linode access_token: foobar @@ -96,6 +99,7 @@ types: - g5-standard-2 +--- # Example with keyed_groups, groups, and compose plugin: community.general.linode access_token: foobar @@ -114,6 +118,7 @@ ansible_ssh_host: ipv4[0] ansible_port: 2222 +--- # Example where control traffic limited to internal network plugin: community.general.linode access_token: foobar diff --git a/plugins/inventory/lxd.py b/plugins/inventory/lxd.py index d7b942c1f78..81229186b87 100644 --- a/plugins/inventory/lxd.py +++ b/plugins/inventory/lxd.py @@ -108,15 +108,18 @@ ''' EXAMPLES = ''' +--- # simple lxd.yml plugin: community.general.lxd url: unix:/var/snap/lxd/common/lxd/unix.socket +--- # simple lxd.yml including filter plugin: community.general.lxd url: unix:/var/snap/lxd/common/lxd/unix.socket state: RUNNING +--- # simple lxd.yml including virtual machines and containers plugin: community.general.lxd url: unix:/var/snap/lxd/common/lxd/unix.socket diff --git a/plugins/inventory/nmap.py b/plugins/inventory/nmap.py index f40f33b972e..5dacd28e953 100644 --- a/plugins/inventory/nmap.py +++ b/plugins/inventory/nmap.py @@ -97,18 +97,20 @@ - 'TODO: add OS fingerprinting' ''' EXAMPLES = ''' +--- # inventory.config file in YAML format plugin: community.general.nmap strict: false address: 192.168.0.0/24 - +--- # a sudo nmap scan to fully use nmap scan power. plugin: community.general.nmap sudo: true strict: false address: 192.168.0.0/24 +--- # an nmap scan specifying ports and classifying results to an inventory group plugin: community.general.nmap address: 192.168.0.0/24 diff --git a/plugins/inventory/proxmox.py b/plugins/inventory/proxmox.py index cf25efc58c8..2d65657d67a 100644 --- a/plugins/inventory/proxmox.py +++ b/plugins/inventory/proxmox.py @@ -138,6 +138,7 @@ ''' EXAMPLES = ''' +--- # Minimal example which will not gather additional facts for QEMU/LXC guests # By not specifying a URL the plugin will attempt to connect to the controller host on port 8006 # my.proxmox.yml @@ -148,6 +149,7 @@ # an example where this is set to `false` and where ansible_host is set with `compose`. want_proxmox_nodes_ansible_host: true +--- # Instead of login with password, proxmox supports api token authentication since release 6.2. plugin: community.general.proxmox user: ci@pve @@ -164,6 +166,7 @@ 32643131386134396336623736393634373936356332623632306561356361323737313663633633 6231313333666361656537343562333337323030623732323833 +--- # More complete example demonstrating the use of 'want_facts' and the constructed options # Note that using facts returned by 'want_facts' in constructed options requires 'want_facts=true' # my.proxmox.yml @@ -186,6 +189,7 @@ # an example where this is set to `false` and where ansible_host is set with `compose`. want_proxmox_nodes_ansible_host: true +--- # Using the inventory to allow ansible to connect via the first IP address of the VM / Container # (Default is connection by name of QEMU/LXC guests) # Note: my_inv_var demonstrates how to add a string variable to every host used by the inventory. @@ -203,6 +207,7 @@ my_inv_var_2: > "my_var_2_value" +--- # Specify the url, user and password using templating # my.proxmox.yml plugin: community.general.proxmox diff --git a/plugins/inventory/scaleway.py b/plugins/inventory/scaleway.py index 9a40243ee77..e396740bca1 100644 --- a/plugins/inventory/scaleway.py +++ b/plugins/inventory/scaleway.py @@ -77,6 +77,7 @@ # scaleway_inventory.yml file in YAML format # Example command line: ansible-inventory --list -i scaleway_inventory.yml +--- # use hostname as inventory_hostname # use the private IP address to connect to the host plugin: community.general.scaleway @@ -91,6 +92,7 @@ ansible_host: private_ip state: state +--- # use hostname as inventory_hostname and public IP address to connect to the host plugin: community.general.scaleway hostnames: @@ -100,6 +102,7 @@ variables: ansible_host: public_ip.address +--- # Using static strings as variables plugin: community.general.scaleway hostnames: diff --git a/plugins/inventory/virtualbox.py b/plugins/inventory/virtualbox.py index b0545319a1c..9112518a468 100644 --- a/plugins/inventory/virtualbox.py +++ b/plugins/inventory/virtualbox.py @@ -56,15 +56,16 @@ ''' EXAMPLES = ''' +--- # file must be named vbox.yaml or vbox.yml -simple_config_file: - plugin: community.general.virtualbox - settings_password_file: /etc/virtulbox/secrets - query: - logged_in_users: /VirtualBox/GuestInfo/OS/LoggedInUsersList - compose: - ansible_connection: ('indows' in vbox_Guest_OS)|ternary('winrm', 'ssh') +plugin: community.general.virtualbox +settings_password_file: /etc/virtualbox/secrets +query: + logged_in_users: /VirtualBox/GuestInfo/OS/LoggedInUsersList +compose: + ansible_connection: ('indows' in vbox_Guest_OS)|ternary('winrm', 'ssh') +--- # add hosts (all match with minishift vm) to the group container if any of the vms are in ansible_inventory' plugin: community.general.virtualbox groups: diff --git a/tests/sanity/ignore-2.13.txt b/tests/sanity/ignore-2.13.txt deleted file mode 100644 index 6f6495dd175..00000000000 --- a/tests/sanity/ignore-2.13.txt +++ /dev/null @@ -1,14 +0,0 @@ -.azure-pipelines/scripts/publish-codecov.py replace-urlopen -plugins/callback/timestamp.py validate-modules:invalid-documentation -plugins/callback/yaml.py validate-modules:invalid-documentation -plugins/lookup/etcd.py validate-modules:invalid-documentation -plugins/lookup/etcd3.py validate-modules:invalid-documentation -plugins/modules/consul_session.py validate-modules:parameter-state-invalid-choice -plugins/modules/iptables_state.py validate-modules:undocumented-parameter # params _back and _timeout used by action plugin -plugins/modules/lxc_container.py validate-modules:use-run-command-not-popen -plugins/modules/osx_defaults.py validate-modules:parameter-state-invalid-choice -plugins/modules/parted.py validate-modules:parameter-state-invalid-choice -plugins/modules/read_csv.py validate-modules:invalid-documentation -plugins/modules/rhevm.py validate-modules:parameter-state-invalid-choice -plugins/modules/xfconf.py validate-modules:return-syntax-error -tests/unit/plugins/modules/test_gio_mime.yaml no-smart-quotes diff --git a/tests/sanity/ignore-2.13.txt.license b/tests/sanity/ignore-2.13.txt.license deleted file mode 100644 index edff8c7685d..00000000000 --- a/tests/sanity/ignore-2.13.txt.license +++ /dev/null @@ -1,3 +0,0 @@ -GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt) -SPDX-License-Identifier: GPL-3.0-or-later -SPDX-FileCopyrightText: Ansible Project diff --git a/tests/sanity/ignore-2.14.txt b/tests/sanity/ignore-2.14.txt deleted file mode 100644 index 24d75210369..00000000000 --- a/tests/sanity/ignore-2.14.txt +++ /dev/null @@ -1,16 +0,0 @@ -.azure-pipelines/scripts/publish-codecov.py replace-urlopen -plugins/callback/timestamp.py validate-modules:invalid-documentation -plugins/callback/yaml.py validate-modules:invalid-documentation -plugins/lookup/etcd.py validate-modules:invalid-documentation -plugins/lookup/etcd3.py validate-modules:invalid-documentation -plugins/modules/consul_session.py validate-modules:parameter-state-invalid-choice -plugins/modules/homectl.py import-3.11 # Uses deprecated stdlib library 'crypt' -plugins/modules/iptables_state.py validate-modules:undocumented-parameter # params _back and _timeout used by action plugin -plugins/modules/lxc_container.py validate-modules:use-run-command-not-popen -plugins/modules/osx_defaults.py validate-modules:parameter-state-invalid-choice -plugins/modules/parted.py validate-modules:parameter-state-invalid-choice -plugins/modules/read_csv.py validate-modules:invalid-documentation -plugins/modules/rhevm.py validate-modules:parameter-state-invalid-choice -plugins/modules/udm_user.py import-3.11 # Uses deprecated stdlib library 'crypt' -plugins/modules/xfconf.py validate-modules:return-syntax-error -tests/unit/plugins/modules/test_gio_mime.yaml no-smart-quotes diff --git a/tests/sanity/ignore-2.14.txt.license b/tests/sanity/ignore-2.14.txt.license deleted file mode 100644 index edff8c7685d..00000000000 --- a/tests/sanity/ignore-2.14.txt.license +++ /dev/null @@ -1,3 +0,0 @@ -GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt) -SPDX-License-Identifier: GPL-3.0-or-later -SPDX-FileCopyrightText: Ansible Project diff --git a/tests/sanity/ignore-2.15.txt b/tests/sanity/ignore-2.15.txt index f624f28e015..f042b888e81 100644 --- a/tests/sanity/ignore-2.15.txt +++ b/tests/sanity/ignore-2.15.txt @@ -1,4 +1,12 @@ .azure-pipelines/scripts/publish-codecov.py replace-urlopen +plugins/inventory/gitlab_runners.py yamllint:unparsable-with-libyaml +plugins/inventory/iocage.py yamllint:unparsable-with-libyaml +plugins/inventory/linode.py yamllint:unparsable-with-libyaml +plugins/inventory/lxd.py yamllint:unparsable-with-libyaml +plugins/inventory/nmap.py yamllint:unparsable-with-libyaml +plugins/inventory/proxmox.py yamllint:unparsable-with-libyaml +plugins/inventory/scaleway.py yamllint:unparsable-with-libyaml +plugins/inventory/virtualbox.py yamllint:unparsable-with-libyaml plugins/lookup/dependent.py validate-modules:unidiomatic-typecheck plugins/modules/consul_session.py validate-modules:parameter-state-invalid-choice plugins/modules/homectl.py import-3.11 # Uses deprecated stdlib library 'crypt' diff --git a/tests/sanity/ignore-2.16.txt b/tests/sanity/ignore-2.16.txt index 665101becfe..6f3a7f038e7 100644 --- a/tests/sanity/ignore-2.16.txt +++ b/tests/sanity/ignore-2.16.txt @@ -1,3 +1,11 @@ +plugins/inventory/gitlab_runners.py yamllint:unparsable-with-libyaml +plugins/inventory/iocage.py yamllint:unparsable-with-libyaml +plugins/inventory/linode.py yamllint:unparsable-with-libyaml +plugins/inventory/lxd.py yamllint:unparsable-with-libyaml +plugins/inventory/nmap.py yamllint:unparsable-with-libyaml +plugins/inventory/proxmox.py yamllint:unparsable-with-libyaml +plugins/inventory/scaleway.py yamllint:unparsable-with-libyaml +plugins/inventory/virtualbox.py yamllint:unparsable-with-libyaml plugins/lookup/dependent.py validate-modules:unidiomatic-typecheck plugins/modules/consul_session.py validate-modules:parameter-state-invalid-choice plugins/modules/homectl.py import-3.11 # Uses deprecated stdlib library 'crypt'