diff --git a/awx_collection/README.md b/awx_collection/README.md index 4297b1f68f..7e1022892e 100644 --- a/awx_collection/README.md +++ b/awx_collection/README.md @@ -1,7 +1,7 @@ # AWX Ansible Collection This Ansible collection allows for easy interaction with an AWX or Ansible Tower -server in Ansible playbooks. +server via Ansible playbooks. The previous home for this collection was in https://github.com/ansible/ansible inside the folder `lib/ansible/modules/web_infrastructure/ansible_tower` @@ -14,34 +14,33 @@ The release 7.0.0 of the `awx.awx` collection is intended to be identical to the content prior to the migration, aside from changes necessary to have it function as a collection. -The following notes are changes that may require changes to playbooks. +The following notes are changes that may require changes to playbooks: - Specifying `inputs` or `injectors` as strings in the - `tower_credential_type` module is no longer supported. Provide as dictionaries instead. + `tower_credential_type` module is no longer supported. Provide them as dictionaries instead. - When a project is created, it will wait for the update/sync to finish by default; this can be turned off with the `wait` parameter, if desired. - Creating a "scan" type job template is no longer supported. - `extra_vars` in the `tower_job_launch` module worked with a list previously, but is now configured to work solely in a `dict` format. - When the `extra_vars` parameter is used with the `tower_job_launch` module, the Job Template launch will fail unless `add_extra_vars` or `survey_enabled` is explicitly set to `True` on the Job Template. - - tower_group used to also service inventory sources, this functionality has been removed from this module; instead use tower_inventory_source. - - Specified tower_config file used to handle k=v pairs on a single line. This is no longer supported. You may a file formatted in: yaml, json or ini only. - - The `variables` parameter in the `tower_group` and `tower_host` modules are now in `dict` format and no longer - supports the use of the `C(@)` syntax (for an external vars file). + - `tower_group` used to also service inventory sources, but this functionality has been removed from this module; use `tower_inventory_source` instead. + - Specified `tower_config` file used to handle `k=v` pairs on a single line; this is no longer supported. Please use a file formatted as `yaml`, `json` or `ini` only. + - The `variables` parameter in the `tower_group`, `tower_host` and `tower_inventory` modules are now in `dict` format and no longer supports the use of the `C(@)` syntax (for an external `vars` file). + - Some return values (e.g., `credential_type`) have been removed. Use of `id` is recommended. ## Running -To use this collection, the "old" tower-cli needs to be installed +To use this collection, the "old" `tower-cli` needs to be installed in the virtual environment where the collection runs. You can install it from [PyPI](https://pypi.org/project/ansible-tower-cli/). -To use this collection in AWX, you should create a custom virtual environment -to install the requirement into. NOTE: running locally, you will also need -to set the job template extra_vars to include `ansible_python_interpreter` -to be the python in that virtual environment. +To use this collection in AWX, you should create a custom virtual environment into which to install the requirements. NOTE: running locally, you will also need +to set the job template `extra_vars` to include `ansible_python_interpreter` +to be the Python in that virtual environment. ## Running Tests Tests to verify compatibility with the most recent AWX code are -in `awx_collection/test/awx`. These tests require that python packages +in `awx_collection/test/awx`. These tests require that Python packages are available for all of `awx`, `ansible`, `tower_cli`, and the collection itself. @@ -49,7 +48,7 @@ itself. The target `make prepare_collection_venv` will prepare some requirements in the `awx_collection_test_venv` folder so that `make test_collection` can -be ran to actually run the tests. A single test can be ran via: +be executed to actually run the tests. A single test can be run via: ``` make test_collection COLLECTION_TEST_DIRS=awx_collection/test/awx/test_organization.py @@ -57,9 +56,9 @@ make test_collection COLLECTION_TEST_DIRS=awx_collection/test/awx/test_organizat ### Manually -As a faster alternative if you do not want to use the container, or -run against Ansible or tower-cli source, it is possible to set up a -working environment yourself. +As a faster alternative (if you do not want to use the container), or to +run against Ansible or `tower-cli` source, it is possible to set up a +working environment yourself: ``` mkvirtualenv my_new_venv diff --git a/awx_collection/plugins/modules/tower_credential_type.py b/awx_collection/plugins/modules/tower_credential_type.py index f3655841b3..7d73250e6f 100644 --- a/awx_collection/plugins/modules/tower_credential_type.py +++ b/awx_collection/plugins/modules/tower_credential_type.py @@ -69,6 +69,7 @@ options: - The Tower OAuth token to use. required: False type: str + version_added: "3.7" extends_documentation_fragment: awx.awx.auth ''' diff --git a/awx_collection/plugins/modules/tower_group.py b/awx_collection/plugins/modules/tower_group.py index 5a34607265..a4d3bb18b0 100644 --- a/awx_collection/plugins/modules/tower_group.py +++ b/awx_collection/plugins/modules/tower_group.py @@ -33,6 +33,7 @@ options: - A new name for this group (for renaming) required: False type: str + version_added: "3.7" description: description: - The description to use for the group. @@ -57,6 +58,7 @@ options: - The Tower OAuth token to use. required: False type: str + version_added: "3.7" extends_documentation_fragment: awx.awx.auth ''' @@ -80,7 +82,7 @@ def main(): argument_spec = dict( name=dict(required=True), new_name=dict(required=False), - description=dict(), + description=dict(required=False), inventory=dict(required=True), variables=dict(type='dict', required=False), state=dict(choices=['present', 'absent'], default='present'), diff --git a/awx_collection/plugins/modules/tower_host.py b/awx_collection/plugins/modules/tower_host.py index a0d9a3e350..2a2096ab97 100644 --- a/awx_collection/plugins/modules/tower_host.py +++ b/awx_collection/plugins/modules/tower_host.py @@ -33,6 +33,7 @@ options: - To use when changing a hosts's name. required: False type: str + version_added: "3.7" description: description: - The description to use for the host. @@ -62,6 +63,7 @@ options: - The Tower OAuth token to use. required: False type: str + version_added: "3.7" extends_documentation_fragment: awx.awx.auth ''' @@ -88,7 +90,7 @@ def main(): argument_spec = dict( name=dict(required=True), new_name=dict(required=False), - description=dict(default=''), + description=dict(required=False), inventory=dict(required=True), enabled=dict(type='bool', default=True), variables=dict(type='dict', required=False), diff --git a/awx_collection/plugins/modules/tower_inventory.py b/awx_collection/plugins/modules/tower_inventory.py index e0b7a4f0da..13bee6e51c 100644 --- a/awx_collection/plugins/modules/tower_inventory.py +++ b/awx_collection/plugins/modules/tower_inventory.py @@ -39,8 +39,9 @@ options: type: str variables: description: - - Inventory variables. Use C(@) to get from file. - type: str + - Inventory variables. + required: False + type: dict kind: description: - The kind field. Cannot be modified after created. @@ -64,6 +65,7 @@ options: - The Tower OAuth token to use. required: False type: str + version_added: "3.7" extends_documentation_fragment: awx.awx.auth ''' @@ -86,9 +88,9 @@ def main(): # Any additional arguments that are not fields of the item can be added here argument_spec = dict( name=dict(required=True), - description=dict(default=''), + description=dict(required=False), organization=dict(required=True), - variables=dict(default=''), + variables=dict(type='dict', required=False), kind=dict(choices=['', 'smart'], default=''), host_filter=dict(), state=dict(choices=['present', 'absent'], default='present'), diff --git a/awx_collection/plugins/modules/tower_inventory_source.py b/awx_collection/plugins/modules/tower_inventory_source.py index 4459003020..5e49435f5e 100644 --- a/awx_collection/plugins/modules/tower_inventory_source.py +++ b/awx_collection/plugins/modules/tower_inventory_source.py @@ -33,6 +33,7 @@ options: - A new name for this assets (will rename the asset) required: False type: str + version_added: "3.7" description: description: - The description to use for the inventory source. @@ -127,6 +128,7 @@ options: - The Tower OAuth token to use. required: False type: str + version_added: "3.7" extends_documentation_fragment: awx.awx.auth ''' @@ -152,7 +154,7 @@ def main(): argument_spec = dict( name=dict(required=True), new_name=dict(type='str'), - description=dict(), + description=dict(required=False), inventory=dict(required=True), # # How do we handle manual and file? Tower does not seem to be able to activate them diff --git a/awx_collection/plugins/modules/tower_job_cancel.py b/awx_collection/plugins/modules/tower_job_cancel.py index f2a5a4f560..e5cfe40f2f 100644 --- a/awx_collection/plugins/modules/tower_job_cancel.py +++ b/awx_collection/plugins/modules/tower_job_cancel.py @@ -38,6 +38,7 @@ options: - The Tower OAuth token to use. required: False type: str + version_added: "3.7" extends_documentation_fragment: awx.awx.auth ''' diff --git a/awx_collection/plugins/modules/tower_job_launch.py b/awx_collection/plugins/modules/tower_job_launch.py index 383300eba6..83ae5e58fe 100644 --- a/awx_collection/plugins/modules/tower_job_launch.py +++ b/awx_collection/plugins/modules/tower_job_launch.py @@ -64,29 +64,35 @@ options: - A specific of the SCM project to run the template on. - This is only applicable if your project allows for branch override. type: str + version_added: "3.7" skip_tags: description: - Specific tags to skip from the playbook. type: list elements: str + version_added: "3.7" verbosity: description: - Verbosity level for this job run type: int choices: [ 0, 1, 2, 3, 4, 5 ] + version_added: "3.7" diff_mode: description: - Show the changes made by Ansible tasks where supported type: bool + version_added: "3.7" credential_passwords: description: - Passwords for credentials which are set to prompt on launch type: dict + version_added: "3.7" tower_oauthtoken: description: - The Tower OAuth token to use. required: False type: str + version_added: "3.7" extends_documentation_fragment: awx.awx.auth ''' diff --git a/awx_collection/plugins/modules/tower_job_list.py b/awx_collection/plugins/modules/tower_job_list.py index 76fd03955d..f1a41fe884 100644 --- a/awx_collection/plugins/modules/tower_job_list.py +++ b/awx_collection/plugins/modules/tower_job_list.py @@ -46,6 +46,7 @@ options: - The Tower OAuth token to use. required: False type: str + version_added: "3.7" extends_documentation_fragment: awx.awx.auth ''' diff --git a/awx_collection/plugins/modules/tower_license.py b/awx_collection/plugins/modules/tower_license.py index cdc2f23fae..f075cd457c 100644 --- a/awx_collection/plugins/modules/tower_license.py +++ b/awx_collection/plugins/modules/tower_license.py @@ -27,16 +27,19 @@ options: - The contents of the license file required: True type: dict + version_added: "3.7" eula_accepted: description: - Whether or not the EULA is accepted. required: True type: bool + version_added: "3.7" tower_oauthtoken: description: - The Tower OAuth token to use. required: False type: str + version_added: "3.7" extends_documentation_fragment: awx.awx.auth ''' diff --git a/awx_collection/plugins/modules/tower_organization.py b/awx_collection/plugins/modules/tower_organization.py index 2b0e4e925f..351bf0a7ff 100644 --- a/awx_collection/plugins/modules/tower_organization.py +++ b/awx_collection/plugins/modules/tower_organization.py @@ -45,6 +45,7 @@ options: default: "0" type: int required: False + version_added: "3.7" state: description: - Desired state of the resource. @@ -56,6 +57,7 @@ options: - The Tower OAuth token to use. required: False type: str + version_added: "3.7" extends_documentation_fragment: awx.awx.auth ''' diff --git a/awx_collection/plugins/modules/tower_project.py b/awx_collection/plugins/modules/tower_project.py index 6db62f3292..c52ffd867d 100644 --- a/awx_collection/plugins/modules/tower_project.py +++ b/awx_collection/plugins/modules/tower_project.py @@ -56,6 +56,7 @@ options: - The refspec to use for the SCM resource. type: str default: '' + version_added: "3.7" scm_credential: description: - Name of the credential to use with this SCM resource. @@ -86,6 +87,7 @@ options: description: - Allow changing the SCM branch or revision in a job template that uses this project. type: bool + version_added: "3.7" job_timeout: version_added: "2.8" description: @@ -123,6 +125,7 @@ options: - The Tower OAuth token to use. required: False type: str + version_added: "3.7" extends_documentation_fragment: awx.awx.auth ''' @@ -175,7 +178,7 @@ def main(): # Any additional arguments that are not fields of the item can be added here argument_spec = dict( name=dict(required=True), - description=dict(required=False, default=''), + description=dict(required=False), scm_type=dict(required=False, choices=['manual', 'git', 'hg', 'svn', 'insights'], default='manual'), scm_url=dict(required=False), local_path=dict(required=False), diff --git a/awx_collection/plugins/modules/tower_receive.py b/awx_collection/plugins/modules/tower_receive.py index dfe6f4b08c..c343db4aec 100644 --- a/awx_collection/plugins/modules/tower_receive.py +++ b/awx_collection/plugins/modules/tower_receive.py @@ -162,6 +162,8 @@ def main(): module = TowerModule(argument_spec=argument_spec, supports_check_mode=False) + module.deprecate(msg="This module is being moved to a different collection. Instead of awx.awx it will be migrated into awx.tower_cli", version="3.7") + if not HAS_TOWER_CLI: module.fail_json(msg='ansible-tower-cli required for this module') diff --git a/awx_collection/plugins/modules/tower_role.py b/awx_collection/plugins/modules/tower_role.py index 38fb5ff203..759e27bce5 100644 --- a/awx_collection/plugins/modules/tower_role.py +++ b/awx_collection/plugins/modules/tower_role.py @@ -141,6 +141,8 @@ def main(): module = TowerModule(argument_spec=argument_spec, supports_check_mode=True) + module.deprecate(msg="This module is being moved to a different collection. Instead of awx.awx it will be migrated into awx.tower_cli", version="3.7") + role_type = module.params.pop('role') state = module.params.pop('state') diff --git a/awx_collection/plugins/modules/tower_send.py b/awx_collection/plugins/modules/tower_send.py index 2deb763e45..dca252cc8b 100644 --- a/awx_collection/plugins/modules/tower_send.py +++ b/awx_collection/plugins/modules/tower_send.py @@ -106,6 +106,8 @@ def main(): module = TowerModule(argument_spec=argument_spec, supports_check_mode=False) + module.deprecate(msg="This module is being moved to a different collection. Instead of awx.awx it will be migrated into awx.tower_cli", version="3.7") + if not HAS_TOWER_CLI: module.fail_json(msg='ansible-tower-cli required for this module') diff --git a/awx_collection/plugins/modules/tower_settings.py b/awx_collection/plugins/modules/tower_settings.py index 67c88bd80a..d242ea2bbb 100644 --- a/awx_collection/plugins/modules/tower_settings.py +++ b/awx_collection/plugins/modules/tower_settings.py @@ -38,11 +38,13 @@ options: - A data structure to be sent into the settings endpoint required: False type: dict + version_added: "3.7" tower_oauthtoken: description: - The Tower OAuth token to use. required: False type: str + version_added: "3.7" extends_documentation_fragment: awx.awx.auth ''' diff --git a/awx_collection/plugins/modules/tower_team.py b/awx_collection/plugins/modules/tower_team.py index 4838923c81..599b745c30 100644 --- a/awx_collection/plugins/modules/tower_team.py +++ b/awx_collection/plugins/modules/tower_team.py @@ -33,9 +33,11 @@ options: - To use when changing a team's name. required: False type: str + version_added: "3.7" description: description: - The description to use for the team. + required: False type: str organization: description: @@ -53,6 +55,7 @@ options: - The Tower OAuth token to use. required: False type: str + version_added: "3.7" extends_documentation_fragment: awx.awx.auth ''' @@ -75,7 +78,7 @@ def main(): argument_spec = dict( name=dict(required=True), new_name=dict(required=False), - description=dict(), + description=dict(required=False), organization=dict(required=True), state=dict(choices=['present', 'absent'], default='present'), ) diff --git a/awx_collection/plugins/modules/tower_user.py b/awx_collection/plugins/modules/tower_user.py index acbdf75891..8c7c05edd0 100644 --- a/awx_collection/plugins/modules/tower_user.py +++ b/awx_collection/plugins/modules/tower_user.py @@ -66,6 +66,7 @@ options: - The Tower OAuth token to use. required: False type: str + version_added: "3.7" extends_documentation_fragment: awx.awx.auth ''' diff --git a/awx_collection/tests/sanity/ignore-2.10.txt b/awx_collection/tests/sanity/ignore-2.10.txt deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/awx_collection/tests/sanity/ignore-2.9.txt b/awx_collection/tests/sanity/ignore-2.9.txt deleted file mode 100644 index e69de29bb2..0000000000