Getting Started with the App¶
This document provides a step-by-step tutorial on how to use the Ansible Automation App to set up, sync, and run Ansible job templates from Nautobot.
Summary of Steps¶
| Step | Description |
|---|---|
| Step 1 | Ensure you have an Ansible AWX/AAP instance set up and accessible from your Nautobot instance. |
| Step 2 | From Nautobot, install the Ansible Automation App. |
| Step 3 | Create an Ansible Controller object pointing to your AWX/AAP instance (with a Secrets Group for credentials). |
| Step 4 | Run Refresh job templates from Ansible Controller. |
| Step 5 | Navigate to Jobs → Jobs, pick a template, fill the mirrored survey form, and click Run. |
Step 1: Prepare your Ansible Instance¶
The Ansible Automation App communicates with your Ansible AWX/AAP via API requests. Before you can use the Ansible Automation App, ensure that you have an Ansible instance (AWX/AAP) set up with an API endpoint that is accessible from your Nautobot instance.
Additionally, ensure that you have a way of authenticating to a user on your Ansible instance. This can be done using either a username/password combination or an authentication token created in AWX/AAP.
Important
Make sure that the credentials you plan to use in Nautobot have the necessary permissions to access and run the job templates that you want Nautobot to run. If you connect using an account with insufficient permissions, you might not see the jobs that you expect.
There are several ways to give users access to job templates in Ansible AWX/AAP. To learn more about Ansible permissions and best practices, please refer to the official Ansible docs for the controller you are using.
Finally, create the job templates in AWX/AAP that you want Nautobot to be able to run. These templates can include surveys, which can be filled out from within Nautobot on job execution.
Step 2: Install the Ansible Automation App¶
Follow the instructions in the Installation Guide to install the Ansible Automation App in your Nautobot instance.
Step 3: Add an Ansible Controller¶
To connect Nautobot to your Ansible AWX/AAP instance, you must create an Ansible Controller in Nautobot. This is a configuration object representing your Ansible AWX/AAP instance. The following subsections will guide you through this process. In short, you must create secrets for your credentials, bundle them into a secrets group, create an external integration, and, finally, add the Ansible Controller itself.
Add Credentials as Secrets¶
Navigate to the Secrets → Secrets page.
Create new secrets for each credential needed to connect to your Ansible controller. For more information about secrets, see the Nautobot Secrets guide.
Create Secrets Group¶
Go to the Secrets → Secrets Groups menu.
Create a new secrets group for your Ansible controller by clicking Add Secrets Group. In the creation dialog that appears, add the secrets you created previously. For each secret, make sure to set the access type to "REST" and set the secret types appropriately (username, password, or token). If using a username and password, both are required. If using a token, only a token is required. For more information about secrets groups, see the Nautobot Secrets Groups guide.
Examples¶
Add External Integration¶
External integrations allow for Nautobot to connect to external systems like Ansible AWX/AAP. To add an external integration for your Ansible controller, navigate to Extensibility → Automation → External Integrations on the left-hand navigation pane.
Next, click Add External Integration to create an integration with Ansible. Provide a name and the necessary connection details, including the URL of your Ansible AWX/AAP instance and the secrets group you created previously. For additional information about settings, see the External Integrations documentation.
Add Ansible Controller¶
Navigate to the Jobs → Ansible Controllers menu and click Add Ansible Controller.
For the "External Integration" field, use the external integration created above. Fill out the rest of the form as needed, then click Create.
Step 4: Sync Job Templates¶
After creating the Ansible controller, it is necessary to sync the job templates from your Ansible AWX/AAP instance to Nautobot. This will make the job templates available for use within Nautobot. To do this, navigate to the Ansible controller you just created under the Jobs → Ansible Controllers menu. This will take you to the details page for the controller.
Above the "Job Templates" pane, click the green Refresh Job Templates button. This will bring up a dialog showing the available job templates in your Ansible AWX/AAP instance.
Select the job templates you want to sync and click Import.
Your selected jobs will now appear on the right-hand side of the "JOB TEMPLATES" panel and in the main Nautobot Jobs list.
Past job runs and results will also be imported automatically, limited by your CHANGELOG_RETENTION setting (for example, if your changelog retention is 30, you will see the last 30 days of job results.)
Enable each job manually by clicking the edit (pencil) icon next to each job template. In the "edit" dialog that appears, check box for "Enabled" to make the template runnable.
Repeat this step for each job template you want to enable.
Enabling Imported Jobs
By default, imported job templates are disabled to prevent accidental execution. You must manually enable each job template you wish to run from Nautobot.
Step 5: Run Jobs¶
Now that you have synced your job templates, you can run them directly from Nautobot. Navigate to the Jobs → Jobs menu to see the list of available jobs, including the Ansible job templates you synced. Click the play button next to the job you want to execute.
You can also find and run the jobs directly from the Ansible Controller in the Jobs → Ansible Controllers → Your Controller Name → Job Templates pane.
After clicking the play (run) button, you will be taken to a confirmation screen. If you added surveys to the job template in AWX/AAP, you will see a form to fill out the survey questions. Fill out the form and click Run Job Now to execute the job.
On submission, a "Job Result" panel will appear, including the full timestamped job output (downloadable) in both HTML and plain-text formats, as formatted by Ansible at runtime. You can also view a detailed breakdown of the Ansible output in the Job Logs table, which can be filtered and searched as needed.
Click to view an example log history table for a completed job
To view past job runs, navigate to the Jobs → Job Results menu. Here you can view the history of all recent job runs, including those executed directly in AWX/AAP as well as those run from Nautobot.
With this setup complete, you can run simple Ansible jobs directly from Nautobot. Navigate to the Jobs → Jobs menu to see the list of available jobs, including the Ansible job templates you synced. For more advanced usage, see the Using the App section.