From 07fa9b51875ece72d6fd1a40bae6cb50991000d9 Mon Sep 17 00:00:00 2001 From: Alicia Cozine <879121+acozine@users.noreply.github.com> Date: Wed, 23 Oct 2019 10:05:12 -0500 Subject: [PATCH] Backport/2.9/docs (#63814) * Replaced old DSC links that given 404 (#63556) Replace DSC links that returned "not found" with updated, working links. (cherry picked from commit f638f29e445b4e9e51d348ad0414c88cbaf67925) * Fix example in pip module documentation (#63462) (cherry picked from commit d8b9f9fb4f1d08693a6bcb724c66add7f265c8b5) * Update vmware ansible modules requirements section (#62797) Update vSphere Automation Python SDK to the requirement section Signed-off-by: Jobin George Signed-off-by: Abhijeet Kasurde (cherry picked from commit 8a77f17dea7f479e755af64347fada0db0c90121) * Typo usersername should be username (#63671) (cherry picked from commit 2ef4ac140435f02c6cb2f55b09b2844dc078522a) * Update description for firstmatch option (#62896) Fixes issue https://github.com/ansible/ansible/issues/62862. The edit makes the description for the `firstmatch` option clearer. The `firstmatch` option was introduced by PR https://github.com/ansible/ansible/pull/33825 (cherry picked from commit aeb0dde7ccb0b7ac34623241835cc876067b8c86) * Update win_regmerge.py (#63633) s/windows/Windows/ in title (cherry picked from commit 4326165be56c1bc990d0e9eaef951227b0e94687) * Example incorrect: server_url is required argument (#63670) The example "Delete GitLab Group" does not work - requires server_url parameter. This likely applies to all Examples, so this change proposes at least putting in the required parameter in the examples. In future we can remove the soon-to-be deprecated server_url parameter. (cherry picked from commit b02467961a5d9357d48ea2d955bc4de69308a16c) * doc: win_user: fix typo in the description of the groups modifyer (#63743) (cherry picked from commit 6046386dba6ed3ce5328cda56bc27ca168b29d4b) * Update AWS dev guide to recommend module_defaults and point to CI policy repo (#63589) (cherry picked from commit 9cda5819b95200b7ce3585e3171a5606cb715cec) * Add example for port range to win_firewall_rule_module (#63269) (cherry picked from commit 2e81b813ddfdd0b37c0d5fad34ec061c6f0eb079) * added a link to install instruction of OpenSSH (#63548) (cherry picked from commit cfe2beae46722c6e36188ba1691e3d58a3547dc3) --- .../rst/dev_guide/platforms/aws_guidelines.rst | 14 ++++++-------- .../vmware_scenarios/vmware_intro.rst | 10 ++++++++++ docs/docsite/rst/user_guide/windows_dsc.rst | 8 ++++---- docs/docsite/rst/user_guide/windows_faq.rst | 2 +- lib/ansible/modules/files/lineinfile.py | 2 +- lib/ansible/modules/packaging/language/pip.py | 6 +++--- lib/ansible/modules/source_control/gitlab_group.py | 10 +++++----- lib/ansible/modules/windows/win_firewall_rule.py | 9 +++++++++ lib/ansible/modules/windows/win_regmerge.py | 2 +- lib/ansible/modules/windows/win_user.py | 2 +- 10 files changed, 41 insertions(+), 24 deletions(-) diff --git a/docs/docsite/rst/dev_guide/platforms/aws_guidelines.rst b/docs/docsite/rst/dev_guide/platforms/aws_guidelines.rst index c0d706ade07..43e46dd1dd0 100644 --- a/docs/docsite/rst/dev_guide/platforms/aws_guidelines.rst +++ b/docs/docsite/rst/dev_guide/platforms/aws_guidelines.rst @@ -639,14 +639,14 @@ to your test in the following variables: * `aws_secret_key` * `security_token` -So all invocations of AWS modules in the test should set these parameters. To avoid duplication these -for every call, it's preferable to use `YAML Anchors `_. For example: +So all invocations of AWS modules in the test should set these parameters. To avoid duplicating these +for every call, it's preferable to use :ref:`module_defaults `. For example: .. code-block:: yaml - name: set connection information for all tasks - set_fact: - aws_connection_info: &aws_connection_info + module_defaults: + group/aws: aws_access_key: "{{ aws_access_key }}" aws_secret_key: "{{ aws_secret_key }}" security_token: "{{ security_token }}" @@ -656,12 +656,10 @@ for every call, it's preferable to use `YAML Anchors `_. To start from the least permissive IAM policy: @@ -711,7 +709,7 @@ To start from the least permissive IAM policy: 3) Add the action or resource that caused the failure to `an IAM policy `_. Wait a few minutes for your policy to update. 4) Run the tests again with this policy attached to your user or role. 5) If the tests still fail at the same place with the same error you will need to troubleshoot (see tips below). If the first test passes, repeat steps 2 and 3 for the next error. Repeat the process until the tests pass with a restrictive policy. -6) Share the minimum policy in a comment on your PR. +6) Open a pull request proposing the minimum required policy to the `testing policies `_. Troubleshooting IAM policies ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_intro.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_intro.rst index 911d63fcdbf..7006e66514e 100644 --- a/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_intro.rst +++ b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_intro.rst @@ -23,7 +23,17 @@ and vCenter infrastructure. You can install pyVmomi using pip: $ pip install pyvmomi +Ansible VMware modules leveraging latest vSphere(6.0+) features are using `vSphere Automation Python SDK `_. The vSphere Automation Python SDK also has client libraries, documentation, and sample code for VMware Cloud on AWS Console APIs, NSX VMware Cloud on AWS integration APIs, VMware Cloud on AWS site recovery APIs, NSX-T APIs. +You can install vSphere Automation Python SDK using pip: + +.. code-block:: bash + + $ pip install --upgrade git+https://github.com/vmware/vsphere-automation-sdk-python.git + +Note: + Installing vSphere Automation Python SDK also installs ``pyvmomi``. A separate installation of ``pyvmomi`` is not required. + vmware_guest module =================== diff --git a/docs/docsite/rst/user_guide/windows_dsc.rst b/docs/docsite/rst/user_guide/windows_dsc.rst index a78f09b8eb3..b8f1b41feeb 100644 --- a/docs/docsite/rst/user_guide/windows_dsc.rst +++ b/docs/docsite/rst/user_guide/windows_dsc.rst @@ -12,7 +12,7 @@ is the same as Ansible, it is just executed in a different manner. Since Ansible 2.4, the ``win_dsc`` module has been added and can be used to leverage existing DSC resources when interacting with a Windows host. -More details on DSC can be viewed at `DSC Overview `_. +More details on DSC can be viewed at `DSC Overview `_. Host Requirements ````````````````` @@ -27,7 +27,7 @@ Why Use DSC? ```````````` DSC and Ansible modules have a common goal which is to define and ensure the state of a resource. Because of -this, resources like the DSC `File resource `_ +this, resources like the DSC `File resource `_ and Ansible ``win_file`` can be used to achieve the same result. Deciding which to use depends on the scenario. @@ -59,9 +59,9 @@ How to Use DSC? ``````````````` The ``win_dsc`` module takes in a free-form of options so that it changes according to the resource it is managing. A list of built in resources can be -found at `resources `_. +found at `resources `_. -Using the `Registry `_ +Using the `Registry `_ resource as an example, this is the DSC definition as documented by Microsoft: .. code-block:: powershell diff --git a/docs/docsite/rst/user_guide/windows_faq.rst b/docs/docsite/rst/user_guide/windows_faq.rst index 6f2b5112911..5c9da043bc4 100644 --- a/docs/docsite/rst/user_guide/windows_faq.rst +++ b/docs/docsite/rst/user_guide/windows_faq.rst @@ -169,7 +169,7 @@ to manage Windows hosts. To connect to Windows hosts over SSH, you must install fork that is in development with Microsoft on the Windows host(s). While most of the basics should work with SSH, ``Win32-OpenSSH`` is rapidly changing, with new features added and bugs -fixed in every release. It is highly recommend you install the latest release +fixed in every release. It is highly recommend you `install `_ the latest release of ``Win32-OpenSSH`` from the GitHub Releases page when using it with Ansible on Windows hosts. diff --git a/lib/ansible/modules/files/lineinfile.py b/lib/ansible/modules/files/lineinfile.py index 86bc44e4f2e..b22d48960a2 100644 --- a/lib/ansible/modules/files/lineinfile.py +++ b/lib/ansible/modules/files/lineinfile.py @@ -116,7 +116,7 @@ options: firstmatch: description: - Used with C(insertafter) or C(insertbefore). - - If set, C(insertafter) and C(insertbefore) find a first line has regular expression matches. + - If set, C(insertafter) and C(insertbefore) will work with the first line that matches the given regular expression. type: bool default: no version_added: "2.5" diff --git a/lib/ansible/modules/packaging/language/pip.py b/lib/ansible/modules/packaging/language/pip.py index bc06b39afe0..598722a58b0 100644 --- a/lib/ansible/modules/packaging/language/pip.py +++ b/lib/ansible/modules/packaging/language/pip.py @@ -97,7 +97,7 @@ options: description: - The explicit executable or pathname for the pip executable, if different from the Ansible Python interpreter. For - example C(pip-3.3), if there are both Python 2.7 and 3.3 installations + example C(pip3.3), if there are both Python 2.7 and 3.3 installations in the system and you want to run pip for the Python 3.3 installation. - Mutually exclusive with I(virtualenv) (added in 2.1). - Does not affect the Ansible Python interpreter. @@ -212,10 +212,10 @@ EXAMPLES = ''' requirements: /my_app/requirements.txt extra_args: "--no-index --find-links=file:///my_downloaded_packages_dir" -# Install (Bottle) for Python 3.3 specifically,using the 'pip-3.3' executable. +# Install (Bottle) for Python 3.3 specifically,using the 'pip3.3' executable. - pip: name: bottle - executable: pip-3.3 + executable: pip3.3 # Install (Bottle), forcing reinstallation if it's already installed - pip: diff --git a/lib/ansible/modules/source_control/gitlab_group.py b/lib/ansible/modules/source_control/gitlab_group.py index 8203db7a338..975acf4b385 100644 --- a/lib/ansible/modules/source_control/gitlab_group.py +++ b/lib/ansible/modules/source_control/gitlab_group.py @@ -88,7 +88,7 @@ options: EXAMPLES = ''' - name: "Delete GitLab Group" gitlab_group: - api_url: https://gitlab.example.com/ + server_url: https://gitlab.example.com/ api_token: "{{ access_token }}" validate_certs: False name: my_first_group @@ -96,9 +96,9 @@ EXAMPLES = ''' - name: "Create GitLab Group" gitlab_group: - api_url: https://gitlab.example.com/ + server_url: https://gitlab.example.com/ validate_certs: True - api_usersername: dj-wasabi + api_username: dj-wasabi api_password: "MySecretPassword" name: my_first_group path: my_first_group @@ -107,9 +107,9 @@ EXAMPLES = ''' # The group will by created at https://gitlab.dj-wasabi.local/super_parent/parent/my_first_group - name: "Create GitLab SubGroup" gitlab_group: - api_url: https://gitlab.example.com/ + server_url: https://gitlab.example.com/ validate_certs: True - api_usersername: dj-wasabi + api_username: dj-wasabi api_password: "MySecretPassword" name: my_first_group path: my_first_group diff --git a/lib/ansible/modules/windows/win_firewall_rule.py b/lib/ansible/modules/windows/win_firewall_rule.py index 52e4c6e41b8..d55d99d1547 100644 --- a/lib/ansible/modules/windows/win_firewall_rule.py +++ b/lib/ansible/modules/windows/win_firewall_rule.py @@ -144,4 +144,13 @@ EXAMPLES = r''' protocol: tcp state: present enabled: yes +- name: Firewall rule to allow port range + win_firewall_rule: + name: Sample port range + localport: 5000-5010 + action: allow + direction: in + protocol: tcp + state: present + enabled: yes ''' diff --git a/lib/ansible/modules/windows/win_regmerge.py b/lib/ansible/modules/windows/win_regmerge.py index 98d7b6cc635..1b5596f9454 100644 --- a/lib/ansible/modules/windows/win_regmerge.py +++ b/lib/ansible/modules/windows/win_regmerge.py @@ -15,7 +15,7 @@ DOCUMENTATION = r''' --- module: win_regmerge version_added: "2.1" -short_description: Merges the contents of a registry file into the windows registry +short_description: Merges the contents of a registry file into the Windows registry description: - Wraps the reg.exe command to import the contents of a registry file. - Suitable for use with registry files created using M(win_template). diff --git a/lib/ansible/modules/windows/win_user.py b/lib/ansible/modules/windows/win_user.py index 7cca668972a..5fc0633d06b 100644 --- a/lib/ansible/modules/windows/win_user.py +++ b/lib/ansible/modules/windows/win_user.py @@ -78,7 +78,7 @@ options: version_added: "1.9" groups: description: - - Adds or removes the user from this comma-separated lis of groups, + - Adds or removes the user from this comma-separated list of groups, depending on the value of I(groups_action). - When I(groups_action) is C(replace) and I(groups) is set to the empty string ('groups='), the user is removed from all groups.