From 5bcc1b6855a19c4396d65dda2448dc04e8963df8 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Thu, 12 Sep 2019 15:47:25 -0400 Subject: [PATCH] [backport][docs] Backportapalooza docs #2 (#62104) * docs: Update apt_key.py, add requirements of gpg (#61552) (cherry picked from commit 5d7d4a93c850a8b40d44fa380327b3c4b1aed7e0) * Proposals aren't really used much, delete reference from docs (#61800) (cherry picked from commit 41055b5dc828af80189d7e77e3bf75ee30a201a7) * Update gitlab_hooks docs (#61837) (cherry picked from commit 223dab99ea0075c96bf5bd049d2a140de5b4a285) * Unify ios_logging and eos_logging documentation with accepted options (#61777) (cherry picked from commit cc9adf7f1ae819db13c77ee99da824be8b762ec5) * don't set default:None in documentation when there is no default (#61111), otherwise "None" will be rendered as a string on docsite (cherry picked from commit 1aca1f86b6037def60bf7460c0c702fe7fdd21ac) * Update mso_schema_template_deploy.py (#61849), correct module name in examples (cherry picked from commit 394a05108dc79efc8d917fa0febbfcf721e94b61) * Update hashi_vault.py documentation with kv V2 example (#61221) (cherry picked from commit 70f501d5c88884496ff65b6301c5f4bfd18e1192) --- .../community/reporting_bugs_and_features.rst | 2 -- .../database/influxdb/influxdb_user.py | 1 - .../monitoring/zabbix/zabbix_screen.py | 2 -- .../network/aci/mso_schema_template_deploy.py | 4 +-- .../modules/network/eos/eos_logging.py | 6 ++--- .../modules/network/ios/ios_logging.py | 5 ++-- lib/ansible/modules/packaging/os/apt_key.py | 2 ++ .../modules/source_control/gitlab_hook.py | 25 ++++++++++--------- lib/ansible/plugins/lookup/consul_kv.py | 2 -- lib/ansible/plugins/lookup/hashi_vault.py | 8 +++++- lib/ansible/plugins/lookup/onepassword.py | 4 --- lib/ansible/plugins/lookup/onepassword_raw.py | 4 --- lib/ansible/plugins/lookup/password.py | 1 - lib/ansible/plugins/lookup/url.py | 2 -- test/sanity/ignore.txt | 1 - 15 files changed, 29 insertions(+), 40 deletions(-) diff --git a/docs/docsite/rst/community/reporting_bugs_and_features.rst b/docs/docsite/rst/community/reporting_bugs_and_features.rst index ee9fe3e8939..bcd222b998b 100644 --- a/docs/docsite/rst/community/reporting_bugs_and_features.rst +++ b/docs/docsite/rst/community/reporting_bugs_and_features.rst @@ -37,5 +37,3 @@ Requesting a feature ==================== The best way to get a feature into Ansible is to :ref:`submit a pull request `. - -The next best way of getting a feature into Ansible is to submit a proposal through the `Ansible proposal process `_. diff --git a/lib/ansible/modules/database/influxdb/influxdb_user.py b/lib/ansible/modules/database/influxdb/influxdb_user.py index d8f8f67601d..ed0728cbfa0 100644 --- a/lib/ansible/modules/database/influxdb/influxdb_user.py +++ b/lib/ansible/modules/database/influxdb/influxdb_user.py @@ -49,7 +49,6 @@ options: "database" and "privilege" keys. - If this argument is not provided, the current grants will be left alone. If an empty list is provided, all grants for the user will be removed. - default: None version_added: 2.8 extends_documentation_fragment: influxdb ''' diff --git a/lib/ansible/modules/monitoring/zabbix/zabbix_screen.py b/lib/ansible/modules/monitoring/zabbix/zabbix_screen.py index a234fbfd842..96f837da285 100644 --- a/lib/ansible/modules/monitoring/zabbix/zabbix_screen.py +++ b/lib/ansible/modules/monitoring/zabbix/zabbix_screen.py @@ -64,12 +64,10 @@ options: description: - Graph width will be set in graph settings. type: int - default: None graph_height: description: - Graph height will be set in graph settings. type: int - default: None graphs_in_row: description: - Limit columns of a screen and make multiple rows. diff --git a/lib/ansible/modules/network/aci/mso_schema_template_deploy.py b/lib/ansible/modules/network/aci/mso_schema_template_deploy.py index 7bd30f6e1c6..476fff0a135 100644 --- a/lib/ansible/modules/network/aci/mso_schema_template_deploy.py +++ b/lib/ansible/modules/network/aci/mso_schema_template_deploy.py @@ -51,7 +51,7 @@ extends_documentation_fragment: mso EXAMPLES = r''' - name: Deploy a schema template - mso_schema_template: + mso_schema_template_deploy: host: mso_host username: admin password: SomeSecretPassword @@ -61,7 +61,7 @@ EXAMPLES = r''' delegate_to: localhost - name: Undeploy a schema template - mso_schema_template: + mso_schema_template_deploy: host: mso_host username: admin password: SomeSecretPassword diff --git a/lib/ansible/modules/network/eos/eos_logging.py b/lib/ansible/modules/network/eos/eos_logging.py index 39e45b4e884..8fc7289f904 100644 --- a/lib/ansible/modules/network/eos/eos_logging.py +++ b/lib/ansible/modules/network/eos/eos_logging.py @@ -24,11 +24,11 @@ options: dest: description: - Destination of the logs. - choices: ['on', 'host', console', 'monitor', 'buffered'] + choices: ['on', 'host', 'console', 'monitor', 'buffered'] name: description: - - If value of C(dest) is I(host) C(name) should be specified, - which indicates hostname or IP address. + - The hostname or IP address of the destination. + - Required when I(dest=host). size: description: - Size of buffer. The acceptable value is in range from 10 to diff --git a/lib/ansible/modules/network/ios/ios_logging.py b/lib/ansible/modules/network/ios/ios_logging.py index 902c7bf2bdd..557ca9fb280 100644 --- a/lib/ansible/modules/network/ios/ios_logging.py +++ b/lib/ansible/modules/network/ios/ios_logging.py @@ -41,9 +41,8 @@ options: choices: ['on', 'host', 'console', 'monitor', 'buffered', 'trap'] name: description: - - If value of C(dest) is I(file) it indicates file-name, - for I(user) it indicates username and for I(host) indicates - the host name to be notified. + - The hostname or IP address of the destination. + - Required when I(dest=host). size: description: - Size of buffer. The acceptable value is in range from 4096 to diff --git a/lib/ansible/modules/packaging/os/apt_key.py b/lib/ansible/modules/packaging/os/apt_key.py index b5af75f8a64..425193a5a54 100644 --- a/lib/ansible/modules/packaging/os/apt_key.py +++ b/lib/ansible/modules/packaging/os/apt_key.py @@ -29,6 +29,8 @@ notes: To generate a full-fingerprint imported key: C(apt-key adv --list-public-keys --with-fingerprint --with-colons)." - If you specify both the key id and the URL with C(state=present), the task can verify or add the key as needed. - Adding a new key requires an apt cache update (e.g. using the apt module's update_cache option) +requirements: + - gpg options: id: description: diff --git a/lib/ansible/modules/source_control/gitlab_hook.py b/lib/ansible/modules/source_control/gitlab_hook.py index 39ed08c8071..a1ff274b559 100644 --- a/lib/ansible/modules/source_control/gitlab_hook.py +++ b/lib/ansible/modules/source_control/gitlab_hook.py @@ -40,7 +40,7 @@ options: - access_token project: description: - - Id or Full path of the project in the form of group/name + - Id or Full path of the project in the form of group/name. required: true type: str hook_url: @@ -50,54 +50,55 @@ options: type: str state: description: - - When C(present) the hook will be updated to match the input or created if it doesn't exist. When C(absent) it will be deleted if it exists. + - When C(present) the hook will be updated to match the input or created if it doesn't exist. + - When C(absent) hook will be deleted if it exists. required: true default: present type: str choices: [ "present", "absent" ] push_events: description: - - Trigger hook on push events + - Trigger hook on push events. type: bool default: yes issues_events: description: - - Trigger hook on issues events + - Trigger hook on issues events. type: bool default: no merge_requests_events: description: - - Trigger hook on merge requests events + - Trigger hook on merge requests events. type: bool default: no tag_push_events: description: - - Trigger hook on tag push events + - Trigger hook on tag push events. type: bool default: no note_events: description: - - Trigger hook on note events + - Trigger hook on note events or when someone adds a comment. type: bool default: no job_events: description: - - Trigger hook on job events + - Trigger hook on job events. type: bool default: no pipeline_events: description: - - Trigger hook on pipeline events + - Trigger hook on pipeline events. type: bool default: no wiki_page_events: description: - - Trigger hook on wiki events + - Trigger hook on wiki events. type: bool default: no hook_validate_certs: description: - - Whether GitLab will do SSL verification when triggering the hook + - Whether GitLab will do SSL verification when triggering the hook. type: bool default: no aliases: [ enable_ssl_verification ] @@ -105,7 +106,7 @@ options: description: - Secret token to validate hook messages at the receiver. - If this is present it will always result in a change as it cannot be retrieved from GitLab. - - Will show up in the X-GitLab-Token HTTP request header + - Will show up in the X-GitLab-Token HTTP request header. required: false type: str ''' diff --git a/lib/ansible/plugins/lookup/consul_kv.py b/lib/ansible/plugins/lookup/consul_kv.py index 9e5e4d8e624..50da99fe255 100644 --- a/lib/ansible/plugins/lookup/consul_kv.py +++ b/lib/ansible/plugins/lookup/consul_kv.py @@ -32,7 +32,6 @@ DOCUMENTATION = """ description: - If the key has a value with the specified index then this is returned allowing access to historical values. datacenter: - default: None description: - Retrieve the key from a consul datatacenter other than the default for the consul host. version_added: "2.9" @@ -71,7 +70,6 @@ DOCUMENTATION = """ key: validate_certs version_added: "2.8" client_cert: - default: None description: The client cert to verify the ssl connection. env: - name: ANSIBLE_CONSUL_CLIENT_CERT diff --git a/lib/ansible/plugins/lookup/hashi_vault.py b/lib/ansible/plugins/lookup/hashi_vault.py index 6d98051e550..473872d4ada 100644 --- a/lib/ansible/plugins/lookup/hashi_vault.py +++ b/lib/ansible/plugins/lookup/hashi_vault.py @@ -64,7 +64,6 @@ DOCUMENTATION = """ namespace: version_added: "2.8" description: namespace where secrets reside. requires HVAC 0.7.0+ and Vault 0.11+. - default: None """ EXAMPLES = """ @@ -98,6 +97,13 @@ EXAMPLES = """ - name: Return all secrets from a path in a namespace debug: msg: "{{ lookup('hashi_vault', 'secret=secret/hello token=c975b780-d1be-8016-866b-01d0f9b688a5 url=http://myvault:8200 namespace=teama/admins')}}" + +# to work with kv v2 (vault api - for kv v2 - GET method requires that PATH should be "secret/data/:path") +- name: Return all kv v2 secrets from a path + debug: + msg: "{{ lookup('hashi_vault', 'secret=secret/data/hello token=my_vault_token url=http://myvault_url:8200') }}" + + """ RETURN = """ diff --git a/lib/ansible/plugins/lookup/onepassword.py b/lib/ansible/plugins/lookup/onepassword.py index e927d794d93..ea03a424504 100644 --- a/lib/ansible/plugins/lookup/onepassword.py +++ b/lib/ansible/plugins/lookup/onepassword.py @@ -34,15 +34,12 @@ DOCUMENTATION = """ default: 'password' master_password: description: The password used to unlock the specified vault. - default: None version_added: '2.7' aliases: ['vault_password'] section: description: Item section containing the field to retrieve (case-insensitive). If absent will return first match from any section. - default: None subdomain: description: The 1Password subdomain to authenticate against. - default: None version_added: '2.7' username: description: The username used to sign in. @@ -52,7 +49,6 @@ DOCUMENTATION = """ version_added: '2.7' vault: description: Vault containing the item to retrieve (case-insensitive). If absent will search all vaults. - default: None notes: - This lookup will use an existing 1Password session if one exists. If not, and you have already performed an initial sign in (meaning C(~/.op/config exists)), then only the C(master_password) is required. diff --git a/lib/ansible/plugins/lookup/onepassword_raw.py b/lib/ansible/plugins/lookup/onepassword_raw.py index a6824c34d0d..9f918111804 100644 --- a/lib/ansible/plugins/lookup/onepassword_raw.py +++ b/lib/ansible/plugins/lookup/onepassword_raw.py @@ -29,15 +29,12 @@ DOCUMENTATION = """ required: True master_password: description: The password used to unlock the specified vault. - default: None version_added: '2.7' aliases: ['vault_password'] section: description: Item section containing the field to retrieve (case-insensitive). If absent will return first match from any section. - default: None subdomain: description: The 1Password subdomain to authenticate against. - default: None version_added: '2.7' username: description: The username used to sign in. @@ -47,7 +44,6 @@ DOCUMENTATION = """ version_added: '2.7' vault: description: Vault containing the item to retrieve (case-insensitive). If absent will search all vaults. - default: None notes: - This lookup will use an existing 1Password session if one exists. If not, and you have already performed an initial sign in (meaning C(~/.op/config exists)), then only the C(master_password) is required. diff --git a/lib/ansible/plugins/lookup/password.py b/lib/ansible/plugins/lookup/password.py index c4c347431bf..3ebe120be9e 100644 --- a/lib/ansible/plugins/lookup/password.py +++ b/lib/ansible/plugins/lookup/password.py @@ -33,7 +33,6 @@ DOCUMENTATION = """ - Note that the password is always stored as plain text, only the returning password is encrypted. - Encrypt also forces saving the salt value for idempotence. - Note that before 2.6 this option was incorrectly labeled as a boolean for a long time. - default: None chars: version_added: "1.4" description: diff --git a/lib/ansible/plugins/lookup/url.py b/lib/ansible/plugins/lookup/url.py index 59830d9f106..2ee59adf250 100644 --- a/lib/ansible/plugins/lookup/url.py +++ b/lib/ansible/plugins/lookup/url.py @@ -29,12 +29,10 @@ options: username: description: Username to use for HTTP authentication. type: string - default: None version_added: "2.8" password: description: Password to use for HTTP authentication. type: string - default: None version_added: "2.8" headers: description: HTTP request headers diff --git a/test/sanity/ignore.txt b/test/sanity/ignore.txt index c30bab4416f..24d31f0d8e3 100644 --- a/test/sanity/ignore.txt +++ b/test/sanity/ignore.txt @@ -2405,7 +2405,6 @@ lib/ansible/modules/monitoring/zabbix/zabbix_map.py validate-modules:parameter-t lib/ansible/modules/monitoring/zabbix/zabbix_map.py validate-modules:doc-missing-type lib/ansible/modules/monitoring/zabbix/zabbix_proxy.py validate-modules:parameter-type-not-in-doc lib/ansible/modules/monitoring/zabbix/zabbix_proxy.py validate-modules:doc-missing-type -lib/ansible/modules/monitoring/zabbix/zabbix_screen.py validate-modules:doc-default-incompatible-type lib/ansible/modules/monitoring/zabbix/zabbix_template.py validate-modules:parameter-type-not-in-doc lib/ansible/modules/monitoring/zabbix/zabbix_template.py validate-modules:doc-missing-type lib/ansible/modules/net_tools/basics/get_url.py validate-modules:parameter-type-not-in-doc