Using the App

This document describes common use-cases and scenarios for this App.

Common Workflows

Multiple Ansible Controllers

If your organization uses multiple Ansible AWX/AAP instances, you can create multiple Ansible Controller objects in Nautobot, each pointing to a different AWX/AAP instance. This allows you to manage and run jobs from multiple Ansible controllers directly from Nautobot.

Additionally, if you have different teams or projects with differing permissions, you can create separate Ansible Controller objects for each team or project. This way, you can access and run projects from both teams on the same Nautobot instance while maintaining proper access controls.

AWX Supports role-based access control (RBAC) for users. Ensure that the user account associated with each Ansible Controller in Nautobot has the appropriate permissions to access the job templates you want to run.

To enable this setup, you must follow the steps outlined in the Getting Started guide for each Ansible Controller you wish to add, as demonstrated by this two-controller example:

1. Ensure that each AWX/AAP instance is set up and accessible from Nautobot with appropriate access to their Templates.
2. Create secrets for each user's credentials.
3. Create a secrets group for each user.
4. Create an external integration for each user.
5. Create an Ansible Controller for each AWX/AAP instance, using the appropriate external integration.
6. Refresh job templates for each Ansible Controller.

After completing these steps, you will see job templates from both AWX/AAP instances available in Nautobot. The job templates that show up under each Ansible Controller will correspond to the permissions of the user associated with each controller.

Permissions	Templates

Note

In these shared scenarios, you can customize whether all Ansible controller jobs in Nautobot share a Nautobot task queue or have their own dedicated queues. This only affects the monitoring jobs running directly inside Nautobot, the Ansible jobs themselves are still run via their own execution environments as defined in AWX/AAP.

See the task queues guide for more information on setting up Celery queues.

Running Jobs with Surveys

To run jobs that include surveys, simply enable surveys on the job template in AWX/AAP. When you run the job from Nautobot, any survey questions defined in AWX/AAP will be automatically mirrored in Nautobot, allowing you to fill them out directly in the Nautobot job interface. Below are examples of survey types and how they appear in Nautobot:

Survey Examples

Basic Server Setup

AWX/AAP Survey:

Nautobot Job Form:

Database Configuration

AWX/AAP Survey:

Nautobot Job Form:

Full Network Verification

AWX/AAP Survey:

Nautobot Job Form:

Field Mapping

AWX survey questions correlate to Nautobot Job Variables (JobVar). The table below shows the mapping between the Ansible Survey Spec and Nautobot Job Variable types:

AWX Type	Nautobot Var	Notes
text	StringVar	-
textarea	TextVar	-
password	Skipped	-
integer	IntegerVar	AWX validates min_value / max_value.
float	FloatVar	Custom Var leveraging FloatField from Django Forms with min_value / max_value validation.
multiplechoice	ChoiceVar	Choices rendered exactly as in AWX.
multiselect	MultiChoiceVar	-
boolean	BooleanVar	-
unknown	JSONVar	Safe fallback.

Removing Job Templates from Nautobot

If you have imported a job template that you no longer wish to have in Nautobot, you can remove it by simply clicking the inline actions next to the job template in the Ansible Controller's Job Templates pane and selecting "Remove from Nautobot". This will delete the job template from Nautobot, but it will remain in AWX/AAP.

Keeping Templates in Sync

When you sync job templates from AWX to Nautobot, Nautobot will mirror the job template's metadata asynchronously, including names, descriptions, and survey questions. However, any changes made to the job template in AWX after the initial sync may not be automatically reflected in Nautobot. To update the job template in Nautobot with the latest changes from AWX, you will need to either:

1. Refresh the job template: Navigate to the Ansible controller's details page, click the green button on the top right that says "Refresh Job Templates".

2. Run the job from Nautobot: Select the job template you wish to update and click the run (play) button. This will re-import the job template from AWX, updating any changes made since the last sync and giving you the most up-to-date version of the survey questions and metadata.

3. Scheduled refreshes: Optionally, you can schedule the system job “Refresh job templates from Ansible” on a recurring schedule. This is typically not necessary, unless you have very frequent changes in AWX.

Troubleshooting Template Sync Issues

If you are trying to refresh job templates but are not seeing the templates you are looking for, double check the permissions of the AWX user associated with the Ansible controller. If the user lacks access to the template on AWX, it will not be visible in Nautobot. Nautobot can only import templates that the ansible controller’s associated AWX user has access to.

Job Buttons, Scheduling, and Approvals

Importing your jobs into Nautobot allows you to take advantage of Nautobot's job conveniences. You can add job buttons to device or other object pages to allow users to run jobs directly from those pages. You can also schedule jobs to run at specific times or intervals, and you can require approval for jobs before they are executed. Job hooks allow you to trigger jobs using external events. For more information on these features, see the Nautobot documentation on Job Features.