26.40. tower

The following documentation is for tower content package at version v0.0.0.

The tower plugin adds the ability to register a machine with AWX / Tower, delete a machine from AWX / Tower, and invoke job templates against a machine.

The plugin provides stages and tasks to help facilitate these actions.

The plugin is a RackN license plugin and your DRP license will need to have the tower plugin enabled.

26.40.1. Setup

To use this plugin, load the plugin_provider into the DRP endpoint. Once loaded, create a plugin with the tower/url, tower/login, and tower/password parameters. These will be used to connect to the AWX / Tower system.

26.40.2. Operations

There are three operations that can be done through the stages/tasks. These can be sequenced by workflows to have the desired staging.

26.40.2.1. tower-register

The tower-register stage registers the host with AWX / Tower. The machine will need the required tower/inventory parameter. This parameter defines the inventory the host should be created in.

Additionally, the tower/group parameter can be added to place the host into the inventory sub-group.

As part of the registeration, additional ssh-keys can be put in place to allow AWX / Tower to access the system. The following parameters enable these keys:

  • tower/ssh-keys - A map of keys to add to the system.
  • tower/ssh-keys-path - The file to put the keys in.
  • tower/ssh-keys-path-userid - The userid to use for the ssh key file.
  • tower/ssh-keys-path-groupid - The groupid to use for the ssh key file.

26.40.2.2. tower-delete

The tower-delete stage deletes the host from AWX / Tower.

26.40.2.3. tower-invoke

The tower-invoke stage runs a job template on the host from AWX / Tower.

The following parameters can be specifed to alter the behavior.

  • tower/job-template - Required string parameter that specifies the job template to execute.
  • tower/job-timeout - Numeric parameter that specifies the number of seconds to wait for the job to complete.
  • tower/extra-var - A Map of values to add to the machine during the job execution.

The task will block until the job is complete, errors, or times out. All the results are reflected into the job log for that task.

26.40.3. params

The content package provides the following params.

26.40.3.1. tower/job-timeout

AWX / Tower Job Timeout defines the number of seconds to wait for the job specified in an invoke call to complete.

26.40.3.2. tower/login

The account to use to login into AWX / Tower.

This is a plugin parameter.

26.40.3.3. tower/ssh-keys

This map is used to put ssh public keys in place the toker-key-path

The key of the map is a arbritary name and the value is the ssh public key for that name.

This is used with the tower/ssh-keys-path-userid, tower/ssh-keys-path, and tower/ssh-keys-path-groupid parameters.

The set of parameters is used to create additional ssh keys that AWX / Tower can use to access the system beyond the normal root ssh keys.

The userid and groupid parameters define the user and group for the files. The ssh-keys-path parameter defines the path to the key file (including filename). The ssh-keys parameter defines the set of keys to put in place.

26.40.3.4. tower/ssh-keys-path-groupid

This parameter specifies the groupid to use for the AWX / Tower ssh keys.

This is used with the tower/ssh-keys, tower/ssh-keys-path, and tower/ssh-keys-path-userid parameters.

The set of parameters is used to create additional ssh keys that AWX / Tower can use to access the system beyond the normal root ssh keys.

The userid and groupid parameters define the user and group for the files. The ssh-keys-path parameter defines the path to the key file (including filename). The ssh-keys parameter defines the set of keys to put in place.

26.40.3.5. tower/url

This parameter specifies the URL to access the AWX / Tower deployment.

26.40.3.6. tower/group

The AWX / Tower group for the machine. This can be left empty (as the default).

When the machine is register, this group, if specified, is applied to the host.

26.40.3.7. tower/job-template

AWX / Tower Job Template specifies the job template to execute on an invoke call.

This needs to be specified on a stage or machine through a profile.

26.40.3.8. tower/job-id

Once tower-invoke is called, the Job ID from the call is stored on the machine.

This Job ID is used by the tasks to validate that the job is running or complete.

This is used to determine if reboots have occured and if a new job is needed or not.

26.40.3.9. tower/password

This parameter specifies the password of the AWX / Tower Login account.

This is a plugin parameter.

26.40.3.10. tower/ssh-keys-path

This parameter specifies the path (including filename) to place the AWX / Tower ssh-keys.

This is used with the tower/ssh-keys-path-userid, tower/ssh-keys-path, and tower/ssh-keys-path-groupid parameters.

The set of parameters is used to create additional ssh keys that AWX / Tower can use to access the system beyond the normal root ssh keys.

The userid and groupid parameters define the user and group for the files. The ssh-keys-path parameter defines the path to the key file (including filename). The ssh-keys parameter defines the set of keys to put in place.

26.40.3.11. tower/ssh-keys-path-userid

This parameter specifies the userid to use for the AWX / Tower ssh keys.

This is used with the tower/ssh-keys, tower/ssh-keys-path, and tower/ssh-keys-path-groupid parameters.

The set of parameters is used to create additional ssh keys that AWX / Tower can use to access the system beyond the normal root ssh keys.

The userid and groupid parameters define the user and group for the files. The ssh-keys-path parameter defines the path to the key file (including filename). The ssh-keys parameter defines the set of keys to put in place.

26.40.3.12. tower/extra-vars

This parameter defines an untype object that gets passed to AWX / Tower as the extra-vars field of a job template request. The object can any valid JSON or YAML.

An example yaml format:

var1: "string"
var2: 33
var3:
  - arr-item1
  - arr-item2
var4:
  mapfield1: "string"
  mapfield2: true

26.40.3.13. tower/inventory

The AWX / Tower Inventory to apply to the Host during registration.

26.40.4. stages

The content package provides the following stages.

26.40.4.1. tower-delete

This stage will delete a machine from AWX / Tower.

26.40.4.2. tower-invoke

This stage will invoke an AWX/ Tower Job Template against a machine. The specific job template is specified by the tower/job-template parameter.

26.40.4.3. tower-register

This stage will register the machine with an AWX / Tower deployment.

The inventory for the machine is specified by the tower/inventory parameter. Optionally, a group may be added as well with the tower/group parameter.

26.40.5. tasks

The content package provides the following tasks.

26.40.5.1. tower-delete

This task will delete a machine from AWX / Tower. The task works for linux, darwin, and windows OSes.

26.40.5.2. tower-invoke

This task will invoke a job template on a machine from AWX / Tower. The task works for linux, darwin, and windows OSes.

26.40.5.3. tower-register

This will register a machine in AWX / Tower. The machine will be in the inventory specified by tower/inventory. Optionally, the tower/group can be added to the machine and the machine will be added to that group as well.

The task works for linux, darwin, and windows OSes.