https://github.com/ansible/terraform-provider-aap
Terraform Provider for Ansible Automation Platform
https://github.com/ansible/terraform-provider-aap
Last synced: 4 months ago
JSON representation
Terraform Provider for Ansible Automation Platform
- Host: GitHub
- URL: https://github.com/ansible/terraform-provider-aap
- Owner: ansible
- License: gpl-3.0
- Created: 2023-10-09T15:30:06.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-08-13T15:40:01.000Z (4 months ago)
- Last Synced: 2025-08-13T17:39:20.313Z (4 months ago)
- Language: Go
- Homepage: https://registry.terraform.io/providers/ansible/aap/latest
- Size: 9.28 MB
- Stars: 36
- Watchers: 12
- Forks: 24
- Open Issues: 19
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.rst
- License: LICENSE
Awesome Lists containing this project
README
# Terraform Provider for Ansible Automation Platform (AAP)
The AAP Provider allows Terraform to manage AAP resources. It provides a means of executing automation jobs on infrastructure provisioned by Terraform, leveraging the AAP API to manage inventories and launch jobs.
The provider can be found on [the Terraform registry](https://registry.terraform.io/providers/ansible/aap/latest).
## Requirements
- install Go: [official installation guide](https://go.dev/doc/install)
- install Terraform: [official installation guide](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli)
- install AWX: [official installation guide](https://github.com/ansible/awx/blob/devel/INSTALL.md)
## Installation for Local Development
Run `make build`. This will build a `terraform-provider-aap` binary in the top level of the project. To get Terraform to use this binary, configure the [development overrides](https://developer.hashicorp.com/terraform/cli/config/config-file#development-overrides-for-provider-developers) for the provider installation. The easiest way to do this will be to create a config file with the following contents:
```
provider_installation {
dev_overrides {
"ansible/aap" = "/path/to/project/root"
}
direct {}
}
```
The `/path/to/project/root` should point to the location where you have cloned this repo, where the `terraform-provider-aap` binary will be built. You can then set the `TF_CLI_CONFIG_FILE` environment variable to point to this config file, and Terraform will use the provider binary you just built.
## Testing
### Linters
You will need to install [golangci-lint](https://golangci-lint.run/usage/install/) to run linters.
Run `make lint`
### Unit tests
Run `make test`
### Acceptance tests
Acceptance tests apply test terraform configurations to a running AAP instance and make changes to resources in that instance, use with caution!
To run acceptance tests locally, start a local AAP instance following the [docker-compose instructions for local AWX development](https://github.com/ansible/awx/blob/devel/tools/docker-compose/README.md). Create an admin user for the AAP instance and save the credentials to these environment variables:
Create an admin user for the AAP instance and set the following environment variables:
```bash
export AAP_USERNAME=
export AAP_PASSWORD=
export AAP_INSECURE_SKIP_VERIFY=true
export AAP_HOST= # "http://localhost:9080" or "https://localhost:8043"
```
In order to run the acceptance tests for the job resource, you must have templates for job and worklow already in your AAP instance. The templates must be set to require an inventory on launch and the Workflow Template must be named "Demo Workflow Job Template". Then associate the Workflow Template with the "Default" organization.
Export the IDs of these job templates:
```bash
export AAP_TEST_JOB_TEMPLATE_ID=
export AAP_TEST_WORKFLOW_JOB_TEMPLATE_ID=
```
The inventory resource test requires the AAP instance to have a second organization with the name `Non-Default` and export that ID:
```bash
export AAP_TEST_ORGANIZATION_ID=
```
The Workflow Job Template resource test requires the AAP instance to have an inventory named "Inventory For Workflow" and then a Workflow Job Template named "Workflow with Inventory". Follow the below steps to get the data in AAP setup:
1. Create inventory `Inventory For Workflow` on Default organization - make note of the ID for the Inventory
2. Create a Workflow Job Template called `Workflow with Inventory` - make note of the ID of the Workflow Job Template.
- Assign organization to `Default`
- Assign `Inventory For Workflow`
- Make sure `Prompt on launch` **is not checked** for the inventory
- Make sure `Prompt on launch` **is checked** for `Extra variables`
- Add a default step and save
Export the following environment variables using the IDs from above:
```bash
export AAP_TEST_WORKFLOW_INVENTORY_ID=
export AAP_TEST_INVENTORY_FOR_WF_ID=
```
The Host resource test requires the AAP instance to have a Job Template that sleeps for a handful of seconds.
We recommend using the `sleep.yml` playbook from the [ansible/test-playbooks](https://github.com/ansible/test-playbooks)
repository, configured to sleep for 15 seconds.
Export the IDs of this job template:
```bash
export AAP_TEST_JOB_FOR_HOST_RETRY_ID=
```
AAP 2.4 version note - If you are running the tests against an AAP 2.4 version instance, set the description for Default Organization to `The default organization for Ansible Automation Platform`
Then you can run acceptance tests with `make testacc`.
**WARNING**: running acceptance tests for the job resource will launch several jobs for the specified job template. Strongly recommended that you create a "check" type job template for testing to ensure the launched jobs do not deploy any actual infrastructure.
## Examples
The [examples](./examples/) subdirectory contains usage examples for this provider.
## Release notes
See the [generated changelog](https://github.com/ansible/terraform-provider-aap/tree/main/CHANGELOG.rst).
## Releasing
To release a new version of the provider:
1. Run `make generatedocs` to format the example files and regenerate docs using terraform-plugin-docs [tfplugindocs installation guide](https://github.com/hashicorp/terraform-plugin-docs?tab=readme-ov-file#installation).
2. Run `antsibull-changelog release --version ` to release a new version of the project.
3. Commit changes
4. Push a new tag (this should trigger an automated release process to the Terraform Registry). The tag version *must* start with "v", for example, v1.2.3.
5. Verify the new version is published at https://registry.terraform.io/providers/ansible/aap/latest
## Supported Platforms
1. Linux AMD64 and ARM64
2. Darwin AMD64 and ARM64
## Licensing
GNU General Public License v3.0. See [LICENSE](/LICENSE) for full text.