iTranslated by AI
Creating Ansible AWX Resources with Terraform
As of the time of writing this article, there is no official AWX or community-managed Terraform provider, but you can create a certain amount of AWX resources using the following AWX provider.
Although it is a personally owned repository, the total number of downloads is around 190k, so it seems that there are quite a few users.
However, many of the descriptions for resources and data are marked as TBD, so for any unclear parameters, you will need to refer to the Tower API reference as needed.
We will verify whether the resources required to execute an Ansible playbook in AWX can be created using the above Terraform provider.
Preparation
For verification, we will build AWX on a k8s cluster using the AWX Operator. However, if you just want to check the behavior, AWX built with Docker should not be a problem either.
The operator can be installed using a Helm chart, but at the time of verification, the following documentation was not being displayed.
Also, it seems that the Helm repository URL was changed in a very recent version.
At the time of verification, the operator could be installed with the following URL:
helm repo add awx-operator https://ansible-community.github.io/awx-operator-helm/
helm repo update
helm install -n awx --create-namespace awx-operator awx-operator/awx-operator
After the operator pod starts, you can build AWX by creating an AWX custom resource. Basically, the default settings are fine, but if the playbook used in later verification is stored in a self-hosted Gitlab using self-signed certificates, certificate verification will fail when cloning from the repository. Therefore, refer to Trusting a Custom Certificate Authority to import your own CA certificate into AWX.
First, save the custom CA certificate (ca.crt) in a secret.
kubectl create secret generic awx-custom-certs \
--from-file=bundle-ca.crt=./ca.crt
Create an AWX resource that uses this.
---
apiVersion: awx.ansible.com/v1beta1
kind: AWX
metadata:
name: awx
namespace: awx
spec:
service_type: nodeport
bundle_cacert_secret: awx-custom-certs
This will create AWX-related pods. The configuration consists of task as the AWX main body, web as the web UI, and postgres as the database.
$ k get pod
NAME READY STATUS RESTARTS AGE
awx-migration-24.6.1-mmmgb 0/1 Completed 0 44h
awx-operator-controller-manager-748c67f659-949wr 2/2 Running 0 44h
awx-postgres-15-0 1/1 Running 0 44h
awx-task-7dfdc4cff6-brdck 4/4 Running 0 44h
awx-web-6b89978556-2z2dg 3/3 Running 0 44h
You can access the web UI and execute APIs from the awx-service created at the same time.
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
awx-operator-controller-manager-metrics-service ClusterIP 10.96.35.57 <none> 8443/TCP 45h
awx-postgres-15 ClusterIP None <none> 5432/TCP 44h
awx-service NodePort 10.98.47.230 <none> 80:31301/TCP 44h
The username for the initial user is admin, and the password can be retrieved from the secret.
kubectl get secret awx-admin-password -o jsonpath="{.data.password}" | base64 --decode ; echo
You can execute various APIs against the above service at /api/v2/.
$ curl -Ssu "admin:password" http://10.98.47.230/api/v2/ | yq -P
ping: /api/v2/ping/
instances: /api/v2/instances/
instance_groups: /api/v2/instance_groups/
receptor_addresses: /api/v2/receptor_addresses/
config: /api/v2/config/
settings: /api/v2/settings/
...
Creating AWX Resources
Now that the AWX setup is complete, we will create resources using Terraform starting from a clean state. As a simple example, we will register an Ansible playbook and inventory stored in a self-hosted GitLab repository to AWX so they can be executed from within AWX.
Specifically, we will consider a use case where an Ansible playbook is executed to create and save a Postgres backup. Our goal is to build an environment where this is automatically executed periodically from AWX.
The file structure on the GitLab repository is as follows, which we will refer to later:
.
├── README.md
├── ansible.cfg
├── inventory.yml
├── remote_copy_backup.yml
├── remote_create_backup.yml
├── requirements.txt
├── requirements.yml
Specifying the Connection Destination
The host URL for the connection is specified in hostname within the provider.
For authentication, you can use either username/password or a token. Since there is only an admin user immediately after setup, we will authenticate using the username/password.
terraform {
required_providers {
awx = {
source = "denouche/awx"
version = "0.27.0"
}
}
}
provider "awx" {
hostname = "http://[ip or domain]:[port]"
username = "admin"
password = "xxx"
}
organization
Organizations can be managed using awx_organization. By default, a Default org exists. While it is recommended to create organizations appropriately when managing large-scale resources, we will use Default as is for this verification.
data "awx_organization" "default_org" {
name = "Default"
}
credentials
Since Ansible usually connects to target nodes via SSH, we register SSH authentication information as a credential.
SSH key
In AWX, the SSH private key and username are saved together in a credential type called machine. The awx_credential_machine resource corresponds to this, and it can be created by specifying the private key content in ssh_key_data. There are various ways to pass the private key content, but for simplicity here, we will read and pass a private key located locally using the file function.
resource "awx_credential_machine" "id-rsa-ubuntu" {
name = "id-rsa-ubuntu"
username = "ubuntu"
organization_id = data.awx_organization.default_org.id
ssh_key_data = file("./id_rsa")
}
project
A project corresponds to the Git repository where playbooks are stored (although other sources can also be specified). In this verification, we will specify the following parameters to reference a playbook stored on GitLab.
- scm_type: git
- scm_url: URL of the Git repository
- scm_branch: Name of the branch to reference
resource "awx_project" "postgres-backup" {
name = "postgres-backup-project"
scm_type = "git"
scm_url = "https://gitlab.ops.com/backup/postgres_backup"
scm_branch = "main"
scm_update_on_launch = true
scm_clean = true
organization_id = data.awx_organization.default_org.id
}
Basically, 1 repo = 1 project, so if you reference multiple Git repositories, you create a project for each.
Inventory
When running ansible-playbook locally, you store information such as target hosts and variables in an inventory, but in AWX, you can manage this information centrally with an inventory resource.
While you can specify host information directly when creating the resource, if an inventory file already exists in a Git repository, you can use the inventory_source resource to import its content into an inventory resource.
When importing content via inventory_source, you only need to specify a name in the awx_inventory resource.
resource "awx_inventory" "postgres-backup" {
name = "postgres-backup"
organization_id = data.awx_organization.default_org.id
}
Next, to import the inventory from a Git repository, you create a project to reference the repository where the inventory exists. In this verification, since the inventory exists within the repository of the project created above, we will skip its creation.
Finally, associate the project and inventory using the awx_inventory_source resource. In source_path, describe the inventory file to be imported from the Git repository using a path relative to the root directory. Here, we will import inventory.yml located directly under the root directory.
resource "awx_inventory_source" "postgres-backup" {
name = "postgres-backup-source"
inventory_id = awx_inventory.postgres-backup.id
source = "scm"
source_project_id = awx_project.postgres-backup.id
source_path = "inventory.yml"
}
After running terraform apply, the inventory is created, and the specified inventory source is added to the "Sources" tab. It is automatically synced with the Git repository when running a job that uses the inventory, but it does not seem to sync automatically at the time of creation.

Running a manual sync will import the content of the specified inventory.yml, automatically adding groups, hosts, variables, etc., defined within the file.

Job template
To execute a playbook in the Git repository specified in the project, you create an awx_job_template job template.
Basically, 1 playbook corresponds to 1 job_template.
resource "awx_job_template" "postgres-backup-1" {
name = "postgres-backup-upload"
job_type = "run"
inventory_id = awx_inventory.postgres-backup.id
project_id = awx_project.postgres-backup.id
playbook = "remote_create_backup.yml"
become_enabled = false
}
SSH authentication credentials for the target node when executing the playbook are associated using awx_job_template_credential.
resource "awx_job_template_credential" "postgres-backup-1" {
job_template_id = awx_job_template.postgres-backup-1.id
credential_id = awx_credential_machine.id-rsa-ubuntu.id
}
Note that an Error: Unable to create JobTemplate might occur when creating a project and a job template simultaneously.
│ Error: Unable to create JobTemplate
│
│ with awx_job_template.postgres-backup-1,
│ on main.tf line 67, in resource "awx_job_template" "postgres-backup-1":
│ 67: resource "awx_job_template" "postgres-backup-1" {
│
│ JobTemplate with name postgres-backup-uploda in the project id 30, failed to create Errors:
│ - playbook: [Playbook not found for project.]
When creating a job template with a project configured, AWX appears to perform a process of retrieving information from the specified Git repository and then fetching the playbooks within that repository. It seems the timing for the Terraform provider to wait for this process is a bit inconsistent, causing it to attempt to create the job template before the playbook retrieval process is complete, resulting in the Playbook not found for project error.
In this case, waiting a short while and running terraform apply again will resolve the error.
Job workflow template
To execute multiple job templates as a series of workflows, you use job workflow templates.
First, create a job template to be executed after the postgres-backup-1 template created above, as follows:
resource "awx_job_template" "postgres-backup-2" {
name = "postgres-backup-download"
job_type = "run"
inventory_id = awx_inventory.postgres-backup.id
project_id = awx_project.postgres-backup.id
playbook = "remote_copy_backup.yml"
become_enabled = false
}
While you can visually describe job dependencies when creating a workflow from the web UI, when creating via the API or Terraform, you describe job execution relationships using resources like awx_workflow_job_template_node. First, define a workflow template with awx_workflow_job_template, and then specify a node to execute the first job template within it using awx_workflow_job_template_node.
- workflow_job_template_id: Specify the ID of the workflow template.
- unified_job_template_id: Specify the ID of the job template to be executed first in the workflow.
resource "awx_workflow_job_template" "postgres-backup-workflow" {
name = "postgres-backup-workflow"
organization_id = data.awx_organization.default_org.id
inventory_id = awx_inventory.postgres-backup.id
}
resource "awx_workflow_job_template_node" "upload" {
workflow_job_template_id = awx_workflow_job_template.postgres-backup-workflow.id
unified_job_template_id = awx_job_template.postgres-backup-1.id
inventory_id = awx_inventory.postgres-backup.id
identifier = "postgres-backup-upload"
}
Next, define an awx_workflow_job_template_node_success resource to execute another job when the above job succeeds. By specifying the above node ID in workflow_job_template_node_id, you control which job this job template follows.
resource "awx_workflow_job_template_node_success" "copy" {
workflow_job_template_id = awx_workflow_job_template.postgres-backup-workflow.id
unified_job_template_id = awx_job_template.postgres-backup-2.id
workflow_job_template_node_id = awx_workflow_job_template_node.upload.id
inventory_id = awx_inventory.postgres-backup.id
identifier = "postgres-backup-copy"
}
In this case, a condition is specified to execute another job template upon successful completion; however, you can use workflow_job_template_node_failure for execution upon failure, or workflow_job_template_node_always to always execute regardless of success or failure.
After deploying this and checking the UI, you can see that a workflow template has been created that executes two job templates in series as expected.

Scheduled Execution
Job templates and workflow job templates can be executed periodically like a cron job by setting up a schedule.
awx_schedule corresponds to this. For example, if you want to periodically execute the workflow created above every 6 hours, you can specify it as follows:
resource "awx_workflow_job_template_schedule" "postgres-backup" {
workflow_job_template_id = awx_workflow_job_template.postgres-backup-workflow.id
name = "postgres-backup-schedule"
rrule = "DTSTART:20240822T000000Z RRULE:INTERVAL=6;FREQ=HOURLY"
unified_job_template_id = awx_workflow_job_template.postgres-backup-workflow.id
}
The schedule interval and other settings are specified in the rrule parameter.
Refer to the Tower API Reference for several examples.
POST requests to this resource must include a proper rrule value following
a particular format and conforming to subset of allowed rules.
The following lists the expected format and details of our rrules:
DTSTART is required and must follow the following format: DTSTART:YYYYMMDDTHHMMSSZ
DTSTART is expected to be in UTC
INTERVAL is required
SECONDLY is not supported
TZID is not supported
RRULE must precede the rule statements
BYDAY is supported but not BYDAY with a numerical prefix
BYYEARDAY and BYWEEKNO are not supported
Only one rrule statement per schedule is supported
COUNT must be < 1000
Here are some example rrules:
"DTSTART:20500331T055000Z RRULE:FREQ=MINUTELY;INTERVAL=10;COUNT=5"
"DTSTART:20240331T075000Z RRULE:FREQ=DAILY;INTERVAL=1;COUNT=1"
"DTSTART:20140331T075000Z RRULE:FREQ=MINUTELY;INTERVAL=1;UNTIL=20230401T075000Z"
"DTSTART:20140331T075000Z RRULE:FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,WE,FR"
"DTSTART:20140331T075000Z RRULE:FREQ=WEEKLY;INTERVAL=5;BYDAY=MO"
"DTSTART:20140331T075000Z RRULE:FREQ=MONTHLY;INTERVAL=1;BYMONTHDAY=6"
"DTSTART:20140331T075000Z RRULE:FREQ=MONTHLY;INTERVAL=1;BYSETPOS=4;BYDAY=SU"
"DTSTART:20140331T075000Z RRULE:FREQ=MONTHLY;INTERVAL=1;BYSETPOS=-1;BYDAY=MO,TU,WE,TH,FR"
"DTSTART:20140331T075000Z RRULE:FREQ=MONTHLY;INTERVAL=1;BYSETPOS=-1;BYDAY=MO,TU,WE,TH,FR,SA,SU"
"DTSTART:20140331T075000Z RRULE:FREQ=YEARLY;INTERVAL=1;BYMONTH=4;BYMONTHDAY=1"
"DTSTART:20140331T075000Z RRULE:FREQ=YEARLY;INTERVAL=1;BYSETPOS=-1;BYMONTH=8;BYDAY=SU"
"DTSTART:20140331T075000Z RRULE:FREQ=WEEKLY;INTERVAL=1;UNTIL=20230401T075000Z;BYDAY=MO,WE,FR"
"DTSTART:20140331T075000Z RRULE:FREQ=HOURLY;INTERVAL=1;UNTIL=20230610T075000Z"
After deploying, you can confirm that the execution is scheduled every 6 hours.

Slack Notification
I want to be notified on Slack when the workflow succeeds, so I will also create notification resources. In the API, you can set up notifications for job templates or workflows, but since the Terraform provider currently only seems to have awx_job_template_notification_... resources, I will set up the notification on the job template that runs at the end of the workflow to determine the success or failure of the workflow.
To send Slack notifications, create a notification template with notification_type: slack using awx_notification_template. Prior configuration such as setting up an app on Slack and installing it to a channel is required.
resource "awx_notification_template" "job-workflow-notification" {
name = "job-workflow-notification"
notification_type = "slack"
organization_id = data.awx_organization.default_org.id
notification_configuration = file("./slack.json")
}
Settings such as the destination channel are specified in JSON format in notification_configuration. For the token, specify the Bot User OAuth Token (a string starting with xoxb-).
{
"channels": [
"#ansible-awx"
],
"token": "xoxb-xxx",
"hex_color": "#2EFF2E"
}
To associate the created notification template with a job template, configure awx_job_template_notification_template_success. While success notifies Slack upon job completion, there are also started resources for notifications at job start and failed resources for notifications upon failure.
resource "awx_job_template_notification_template_success" "success" {
job_template_id = awx_job_template.postgres-backup-2.id
notification_template_id = awx_notification_template.job-workflow-notification.id
}
Once created, you can confirm that the notification template created above is set in the Notifications tab of the job template.

When the workflow is executed and succeeds, a message like the following will be sent to Slack.

The default message is somewhat plain, but you can change the content and format of the message by customizing the notification template settings. For details, refer to 23.5. Create custom notifications.
Additionally, the domain name in the message is set to towerhost by default, but it can be changed in 23.7. Configure the towerhost hostname for notifications.
Summary
We have confirmed that it is possible to use a Terraform provider to build a configuration that periodically executes a backup creation playbook stored in a GitLab repository on AWX and notifies Slack of the execution results.
There are still many AWX resources that are not yet supported and areas where the documentation is lacking, so there will be times when you need to refer to the API reference or create resources using the API or the Ansible AWX collection. While it is not currently possible to manage all resources, if you are familiar with Terraform, it seems convenient to be able to manage them via IaC (though I feel there might not be that many opportunities to manage AWX resources with Terraform to begin with).
Discussion