diff options
Diffstat (limited to 'collections-debian-merged/ansible_collections/awx/awx/README.md')
| -rw-r--r-- | collections-debian-merged/ansible_collections/awx/awx/README.md | 135 |
1 files changed, 135 insertions, 0 deletions
diff --git a/collections-debian-merged/ansible_collections/awx/awx/README.md b/collections-debian-merged/ansible_collections/awx/awx/README.md new file mode 100644 index 00000000..47b517c6 --- /dev/null +++ b/collections-debian-merged/ansible_collections/awx/awx/README.md @@ -0,0 +1,135 @@ +# AWX Ansible Collection + +[comment]: # (*******************************************************) +[comment]: # (* *) +[comment]: # (* WARNING *) +[comment]: # (* *) +[comment]: # (* This file is templated and not to be *) +[comment]: # (* edited directly! Instead modify: *) +[comment]: # (* tools/roles/template_galaxy/templates/README.md.j2 *) +[comment]: # (* *) +[comment]: # (* Changes to the base README.md file are refreshed *) +[comment]: # (* upon build of the collection *) +[comment]: # (*******************************************************) + +This Ansible collection allows for easy interaction with an AWX server via Ansible playbooks. + +This source for this collection lives in the `awx_collection` folder inside of the +AWX source. +The previous home for this collection was inside the folder [lib/ansible/modules/web_infrastructure/ansible_tower](https://github.com/ansible/ansible/tree/stable-2.9/lib/ansible/modules/web_infrastructure/ansible_tower) in the Ansible repo, +as well as other places for the inventory plugin, module utils, and +doc fragment. + +## Building and Installing + +This collection templates the `galaxy.yml` file it uses. +Run `make build_collection` from the root folder of the AWX source tree. +This will create the `tar.gz` file inside the `awx_collection` folder +with the current AWX version, for example: `awx_collection/awx-awx-9.2.0.tar.gz`. + +Installing the `tar.gz` involves no special instructions. + +## Running + +Non-deprecated modules in this collection have no Python requirements, but +may require the official [AWX CLI](https://docs.ansible.com/ansible-tower/latest/html/towercli/index.html) +in the future. The `DOCUMENTATION` for each module will report this. + +You can specify authentication by a combination of either: + + - host, username, password + - host, OAuth2 token + +The OAuth2 token is the preferred method. You can obtain a token via the +AWX CLI [login](https://docs.ansible.com/ansible-tower/latest/html/towercli/reference.html#awx-login) +command. + +These can be specified via (from highest to lowest precedence): + + - direct module parameters + - environment variables (most useful when running against localhost) + - a config file path specified by the `tower_config_file` parameter + - a config file at `~/.tower_cli.cfg` + - a config file at `/etc/tower/tower_cli.cfg` + +Config file syntax looks like this: + +``` +[general] +host = https://localhost:8043 +verify_ssl = true +oauth_token = LEdCpKVKc4znzffcpQL5vLG8oyeku6 +``` + +## Release and Upgrade Notes + +Notable releases of the `awx.awx` collection: + + - 7.0.0 is intended to be identical to the content prior to the migration, aside from changes necessary to function as a collection. + - 11.0.0 has no non-deprecated modules that depend on the deprecated `tower-cli` [PyPI](https://pypi.org/project/ansible-tower-cli/). + - 0.0.1-devel is the version you should see if installing from source, which is intended for development and expected to be unstable. + +The following notes are changes that may require changes to playbooks: + + - 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. + - Specifying a custom certificate via the `TOWER_CERTIFICATE` environment variable no longer works. + - Type changes of variable fields: + + - `extra_vars` in the `tower_job_launch` module worked with a `list` previously, but now only works with a `dict` type + - `extra_vars` in the `tower_workflow_job_template` module worked with a `string` previously but now expects a `dict` + - When the `extra_vars` parameter is used with the `tower_job_launch` module, the launch will fail unless `ask_extra_vars` or `survey_enabled` is explicitly set to `True` on the Job Template + - The `variables` parameter in the `tower_group`, `tower_host` and `tower_inventory` modules now expects a `dict` type and no longer supports the use of `@` syntax for a file + + + - Type changes of other types of fields: + + - `inputs` or `injectors` in the `tower_credential_type` module worked with a string previously but now expects a `dict` + - `schema` in the `tower_workflow_job_template` module worked with a `string` previously but not expects a `list` of `dict`s + + - `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. + - Some return values (e.g., `credential_type`) have been removed. Use of `id` is recommended. + - `tower_job_template` no longer supports the deprecated `extra_vars_path` parameter, please use `extra_vars` with the lookup plugin to replace this functionality. + - The `notification_configuration` parameter of `tower_notification` has changed from a string to a dict. Please use the `lookup` plugin to read an existing file into a dict. + - `tower_credential` no longer supports passing a file name to ssh_key_data. + - The HipChat `notification_type` has been removed and can no longer be created using the `tower_notification` module. + +## Running Unit Tests + +Tests to verify compatibility with the most recent AWX code are in `awx_collection/test/awx`. +These can be ran by `make test_collection` in the development container. + +To run outside of the development container, or to run against +Ansible source, set up a working environment: + +``` +mkvirtualenv my_new_venv +# may need to replace psycopg2 with psycopg2-binary in requirements/requirements.txt +pip install -r requirements/requirements.txt -r requirements/requirements_dev.txt -r requirements/requirements_git.txt +make clean-api +pip install -e <path to your Ansible> +pip install -e . +pip install -e awxkit +py.test awx_collection/test/awx/ +``` + +## Running Integration Tests + +The integration tests require a virtualenv with `ansible` >= 2.9 and `tower_cli`. +The collection must first be installed, which can be done using `make install_collection`. +You also need a configuration file, as described in the running section. + +Run the tests: + +``` +# ansible-test must be run from the directory in which the collection is installed +cd ~/.ansible/collections/ansible_collections/awx/awx/ +ansible-test integration +``` + +## Licensing + +All content in this folder is licensed under the same license as Ansible, +which is the same as license that applied before the split into an +independent collection. |