Chapter 18. Automation controller tips and tricks Use the automation controller CLI Tool Change the automation controller Admin Password Create an automation controller Admin from the commandline Set up a jump host to use with automation controller View Ansible outputs for JSON commands when using automation controller Locate and configure the Ansible configuration file View a listing of all ansible_ variables The ALLOW_JINJA_IN_EXTRA_VARS variable Configure the controllerhost hostname for notifications Launch Jobs with curl Filter instances returned by the dynamic inventory sources in automation controller Use an unreleased module from Ansible source with automation controller Connect to Windows with winrm Import existing inventory files and host/group vars into automation controller 18.1. The automation controller CLI Tool Automation controller has a full-featured command line interface. For more information on configuration and use, see the AWX Command Line Interface and the AWX manage utility section. 18.2. Change the automation controller Administrator Password During the installation process, you are prompted to enter an administrator password that is used for the admin superuser or system administrator created by automation controller. If you log in to the instance by using SSH, it tells you the default administrator password in the prompt. If you need to change this password at any point, run the following command as root on the automation controller server: awx-manage changepassword admin , enter a new password. After that, the password you have entered works as the administrator password in the web UI. To set policies at creation time for password validation using Django, see Django password policies . 18.3. Create an automation controller Administrator from the command line Occasionally you might find it helpful to create a system administrator (superuser) account from the command line. To create a superuser, run the following command as root on the automation controller server and enter the administrator information as prompted: awx-manage createsuperuser 18.4. Configuring automation controller to use jump hosts connecting to managed nodes Credentials supplied by automation controller do not flow to the jump host through ProxyCommand. They are only used for the end-node when the tunneled connection is set up. Configure a fixed user/keyfile in your SSH configuration file You can configure a fixed user/keyfile in your SSH configuration file in the ProxyCommand definition that sets up the connection through the jump host. Prerequisites Check whether all jump hosts are reachable from any node that establishes an SSH connection to the managed nodes, such as a Hybrid Controller or an Execution Node. Procedure Create an SSH configuration file /var/lib/awx .ssh/config on each node with the following details Host jumphost.example.com Hostname jumphost.example.com User <jumphostuser> Port <jumphostport> IdentityFile ~.ssh/id_rsa StrictHostKeyChecking no ProxyCommand ssh -W %h:%p jumphost.example.com The code specifies the configuration required to connect to the jump host 'jumphost.example.com' Automation controller establishes an SSH connection from each node to the managed nodes. Example values jumphost.example.com , jumphostuser , jumphostport and ~/.ssh/id_rsa must be changed according to your environment Add a Host matching block to the already created SSH configuration file /var/lib/awx/.ssh/config` on the node, for example: Host 192.0.* ... The Host 192.0.* line indicates that all hosts in that subnet use the settings defined in that block. Specifically all hosts in that subnet are accessed using the ProxyCommand setting and connect through jumphost.example.com If Host * is used to indicate that all hosts connect through the specified proxy, ensure that jumphost.example.com is excluded from that matching, for example: Host * !jumphost.example.com ... Using the Red Hat Ansible Automation Platform UI Procedure On the navigation panel, select Settings Job Click Edit and add /var/lib/awx .ssh:/home/runner/.ssh:0 to the Paths to expose isolated jobs field. Click Save to save your changes. Configuring jump hosts using Ansible Inventory variables You can also add a jump host to your automation controller instance through Inventory variables. These variables can be set at either the inventory, group, or host level. Use this method if you want to control the use of jump hosts inside automation controller using the inventory. Navigate to your inventory and in the variables field of whichever level you choose, add the following variables: ansible_user: <user_name> ansible_connection: ssh ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q <user_name>@<jump_server_name>"' 18.5. View Ansible outputs for JSON commands when using automation controller When working with automation controller, you can use the API to obtain the Ansible outputs for commands in JSON format. To view the Ansible outputs, browse to https://<controller server name>/api/v2/jobs/<job_id>/job_events/ 18.6. Locate and configure the Ansible configuration file While Ansible does not require a configuration file, OS packages often include a default one in /etc/ansible/ansible.cfg for possible customization. To use a custom ansible.cfg file, place it at the root of your project. Automation controller runs ansible-playbook from the root of the project directory, where it finds the custom ansible.cfg file. Note An ansible.cfg file anywhere else in the project is ignored. To learn which values you can use in this file, see Generating a sample ansible.cfg file in the Ansible documentation. Using the defaults are acceptable for starting out, but you can configure the default module path or connection type here, as well as other things. Automation controller overrides some ansible.cfg options. For example, automation controller stores the SSH ControlMaster sockets, the SSH agent socket, and any other per-job run items in a per-job temporary directory that is passed to the container used for job execution. 18.7. View a listing of all ansible_ variables By default, Ansible gathers "facts" about the machines under its management, accessible in Playbooks and in templates. To view all facts available about a machine, run the setup module as an ad hoc action: ansible -m setup hostname This prints out a dictionary of all facts available for that particular host. For more information, see information-discovered-from-systems-facts in the Ansible documentation. 18.8. The ALLOW_JINJA_IN_EXTRA_VARS variable Setting ALLOW_JINJA_IN_EXTRA_VARS = template only works for saved job template extra variables. Prompted variables and survey variables are excluded from the 'template'. This parameter has three values: Only On Template Definitions to allow usage of Jinja saved directly on a job template definition (the default). Never to disable all Jinja usage (recommended). Always to always allow Jinja (strongly discouraged, but an option for prior compatibility). This parameter is configurable in the Jobs Settings page of the automation controller UI. 18.9. Configuring the controllerhost hostname for notifications From the System settings page, you can replace https://controller.example.com in the Base URL of the Service field with your preferred hostname to change the notification hostname. Refreshing your automation controller license also changes the notification hostname. New installations of automation controller need not set the hostname for notifications. 18.10. Launching Jobs with curl Launching jobs with the automation controller API is simple. The following are some easy to follow examples using the curl tool. Assuming that your Job Template ID is '1', your controller IP is 192.168.42.100, and that admin and awxsecret are valid login credentials, you can create a new job this way: curl -f -k -H 'Content-Type: application/json' -XPOST \ --user admin:awxsecret \ ht p://192.168.42.100/api/v2/job_templates/1/launch/ This returns a JSON object that you can parse and use to extract the 'id' field, which is the ID of the newly created job. You can also pass extra variables to the Job Template call, as in the following example: curl -f -k -H 'Content-Type: application/json' -XPOST \ -d '{"extra_vars": "{\"foo\": \"bar\"}"}' \ --user admin:awxsecret http://192.168.42.100/api/v2/job_templates/1/launch/ Note The extra_vars parameter must be a string which contains JSON, not just a JSON dictionary. Use caution when escaping the quotes, etc. 18.11. Filtering instances returned by the dynamic inventory sources in the controller By default, the dynamic inventory sources in automation controller (such as AWS and Google) return all instances available to the cloud credentials being used. They are automatically joined into groups based on various attributes. For example, AWS instances are grouped by region, by tag name, value, and security groups. To target specific instances in your environment, write your playbooks so that they target the generated group names. For example: --- - hosts: tag_Name_webserver tasks: ... You can also use the Limit field in the Job Template settings to limit a playbook run to a certain group, groups, hosts, or a combination of them. The syntax is the same as the --limit parameter on the ansible-playbook command line. You can also create your own groups by copying the auto-generated groups into your custom groups. Make sure that the Overwrite option is disabled on your dynamic inventory source, otherwise subsequent synchronization operations delete and replace your custom groups. 18.12. Use an unreleased module from Ansible source with automation controller If there is a feature that is available in the latest Ansible core branch that you want to use with your automation controller system, making use of it in automation controller is simple. First, determine which is the updated module you want to use from the available Ansible Core Modules or Ansible Extra Modules GitHub repositories. , create a new directory, at the same directory level of your Ansible source playbooks, named /library . When this is created, copy the module you want to use and drop it into the /library directory. It is consumed first by your system modules and can be removed once you have updated the stable version with your normal package manager. 18.13. Use callback plugins with automation controller Ansible has a flexible method of handling actions during playbook runs, called callback plugins. You can use these plugins with automation controller to do things such as notify services upon playbook runs or failures, or send emails after every playbook run. For official documentation on the callback plugin architecture, see Developing plugins . Note Automation controller does not support the stdout callback plugin because Ansible only permits one, and it is already being used for streaming event data. You might also want to review some example plugins, which should be modified for site-specific purposes, such as those available at: https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/callback To use these plugins, put the callback plugin .py file into a directory called /callback_plugins alongside your playbook in your automation controller Project. Then, specify their paths (one path per line) in the Ansible Callback Plugins field of the Job settings: Note To have most callbacks shipped with Ansible applied globally, you must add them to the callback_whitelist section of your ansible.cfg . If you have custom callbacks, see Enabling callback plugins . 18.14. Connect to Windows with winrm By default, automation controller attempts to ssh to hosts. You must add the winrm connection information to the group variables to which the Windows hosts belong. To get started, edit the Windows group in which the hosts reside and place the variables in the source or edit screen for the group. To add winrm connection info: Edit the properties for the selected group by clicking on the Edit icon of the group name that contains the Windows servers. In the "variables" section, add your connection information as follows: ansible_connection: winrm When complete, save your edits. If Ansible was previously attempting an SSH connection and failed, you should re-run the job template. 18.15. Import existing inventory files and host/group vars into automation controller To import an existing static inventory and the accompanying host and group variables into automation controller, your inventory must be in a structure similar to the following: inventory/ |-- group_vars | `-- mygroup |-- host_vars | `-- myhost `-- hosts To import these hosts and vars, run the awx-manage command: awx-manage inventory_import --source=inventory/ \ --inventory-name="My Controller Inventory" If you only have a single flat file of inventory, a file called ansible-hosts, for example, import it as follows: awx-manage inventory_import --source=./ansible-hosts \ --inventory-name="My Controller Inventory" In case of conflicts or to overwrite an inventory named "My Controller Inventory", run: awx-manage inventory_import --source=inventory/ \ --inventory-name="My Controller Inventory" \ --overwrite --overwrite-vars If you receive an error, such as: ValueError: need more than 1 value to unpack Create a directory to hold the hosts file, as well as the group_vars: mkdir -p inventory-directory/group_vars Then, for each of the groups that have :vars listed, create a file called inventory-directory/group_vars/<groupname> and format the variables in YAML format. The importer then handles the conversion correctly.

Commands:
awx-manage changepassword admin
awx-manage createsuperuser
Host jumphost.example.com Hostname jumphost.example.com User <jumphostuser> Port <jumphostport> IdentityFile ~.ssh/id_rsa StrictHostKeyChecking no ProxyCommand ssh -W %h:%p jumphost.example.com
Host 192.0.*
Host * !jumphost.example.com
ansible_user: <user_name> ansible_connection: ssh ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q <user_name>@<jump_server_name>"'
ansible -m setup hostname
curl -f -k -H 'Content-Type: application/json' -XPOST --user admin:awxsecret ht p://192.168.42.100/api/v2/job_templates/1/launch/
curl -f -k -H 'Content-Type: application/json' -XPOST -d '{"extra_vars": "{\"foo\": \"bar\"}"}' --user admin:awxsecret http://192.168.42.100/api/v2/job_templates/1/launch/
--- - hosts: tag_Name_webserver tasks:
inventory/ |-- group_vars | `-- mygroup |-- host_vars | `-- myhost `-- hosts
awx-manage inventory_import --source=inventory/ --inventory-name="My Controller Inventory"
awx-manage inventory_import --source=./ansible-hosts --inventory-name="My Controller Inventory"
awx-manage inventory_import --source=inventory/ --inventory-name="My Controller Inventory" --overwrite --overwrite-vars
ValueError: need more than 1 value to unpack
mkdir -p inventory-directory/group_vars