Chapter 1. Terraform integration

Procedure

1. Log in to Ansible Automation Platform.
2. From the navigation panel, select Automation Execution Infrastructure Credentials, and then select Create credential.
3. From the Credential type list, select the HCP Terraform credential type.
4. In the Token field, enter the Terraform API token.
5. (Optional) Edit the Description field and select the TF organization from the Organization list.
6. Click Save credential. You are ready to use the credential in a job template.

Procedure

1. Log in to Ansible Automation Platform.
2. From the navigation panel, select Automation Execution Infrastructure Credential Types.
3. Click Create credential type. The Create Credential Type page opens and displays the Details tab.
4. For the Credential Type, enter a name.

5. In the Input configuration field, enter the following YAML parameter and values:

   fields:
      - id: token
        type: string
        label: token
        secret: true

6. In the Injector configuration field, enter the following configuration.

   • For Terraform Enterprise, the hostname is the location where you have deployed TFE:

     env:
       TF_TOKEN_<hostname>:  ‘{{ token }}’

   • For HCP Terraform, use:

     env:
       TF_TOKEN_app_terraform_io:   ‘{{ token }}’

7. To save your configuration, click Create Credential Type again. The new credential type is created.
8. To create an instance of your new credential type, select Automation Execution Infrastructure Credentials page, and select Create credential.
9. From the Credential type, select the name of the credential type you created earlier.
10. In the Token field, enter the Terraform API token.
11. (Optional) Edit the Description and select the TF organization from the Organization list.
12. Click Save credential.

Procedure

1. From the navigation panel, select Automation Execution Infrastructure Execution Environments.

2. Click Create execution environment.

   
3. For Name, enter a name for your Ansible Automation Platform execution environment.
4. For Image, enter the repository link to the image for your pre-existing execution environment.
5. Click Create execution environment. Your newly added execution environment is ready to be used in a job template.

Procedure

1. From the navigation panel, select Automation Execution Templates.
2. Select Create template > Create Job Template.
3. From the Execution Environment list, select the environment you created.
4. From the Credentials list, select the credentials instance you created previously. If you do not see the credentials, click Browse to see more options in the list.
5. Enter any additional information for the required fields.
6. Click Create job template.
7. Click Launch template.
8. To launch the job, click Next and Finish. The job output shows that the job has run.

Procedure

1. Replicate your automation tasks from the cloud.terraform modules.

   Example

   - name: Create configuration version with auto_queue_runs to false
     hashicorp.terraform.configuration_version:
      workspace_id: ws-1234
      configuration_files_path: "/usr/home/tf"
      auto_queue_runs: false
      tf_validate_certs: true
      poll_interval: 3
      poll_timeout: 15
      state: present

2. Configure the following required parameters:

   • workspace_id or workspace + organization: The workspace ID or the workspace name and organization where the configuration version will be created and the file will be uploaded (for state: present).

   • configuration_files_path: The path where the required Terraform Enterprise or HCP Terraform files will be uploaded to create a configuration version (for state: present). The module accepts two file types for configuration_files_path:

     • Directory: Any folder containing Terraform Enterprise or HCP Terraform files. The module auto-creates the .tar.gz file from all contents recursively.
     • .tar.gz Archive: Pre-compressed gzip tarball. The module validates TAR format and gzip compression.

   • configuration_version_id: The configuration version ID that will be archived (state: archived). This action deletes the associated uploaded .tar.gz file. Note the following:

     • Only uploaded versions that were created using the API or CLI, have no active runs, and are not the current version for any workspace can be archived.
     • When the configuration_version_id is unspecified, Terraform Enterprise or HCP Terraform selects the latest approved configuration_version_id in the workspace.
   • auto_queue_runs: Determines if Terraform Enterprise or HCP Terraform automatically starts a run after the configuration upload (true by default) or requires manual initiation (false).
3. Set additional optional parameters as needed.

Procedure

1. Create a run module.

   Example

   - name: Create a destroy run with auto_apply
     hashicorp.terraform.run:
     workspace_id: ws-1234
     run_message: "destroy vpc"
     state: "present"
     tf_token: <your token>
     is_destroy: true
     auto_apply: true
     target_addrs:
       - "aws_vpc.vpc1"
       - "aws_vpc.vpc2"
     poll: true
     poll_interval: 10
     poll_timeout: 30

2. Configure the following required parameters:

   • workspace_id or workspace + organization: The workspace ID or the workspace name and organization where the configuration version will be created and the file will be uploaded (for state: present).
   • run_id: The unique identifier of the run to apply, cancel, or discard operations.
   • tf_token: The Terraform API authentication token. If this value is not set, the TF_TOKEN environment variable is used.

3. (Optional) Configure the built-in polling options that determine the wait period for Terraform Enterprise or HCP Terraform operations to complete:

   • poll: true: (Default) Checks the run status every poll_interval seconds (default: 5s) until completion or poll_timeout (default: 25s) is reached, returning the final status.
   • poll: false: Returns immediately after initiating the run without waiting.
4. Set additional optional parameters as needed.

Procedure

1. To prevent errors when running playbooks against TFE or HCP Terraform, do the following actions before running a playbook:

   1. Confirm that the Terraform version in the execution environment is the same as the version stated in TFE or HCP Terraform.

   2. Perform an initialization in TFE or HCP Terraform:

      terraform init

   3. If you have a local state file in your execution environment, delete the local state file.
   4. Get a token from HCP Terraform or Terraform Enterprise, which you will use to create the credential in a later step. Ensure the token has the necessary permissions based on the team or user token to execute the desired capabilities in the playbook.
   5. Remove the backend config and files from your playbook definition.

   6. Add the workspace within the default setting in your TF config or an environment variable if you want to define the workspace outside updating the playbook itself.

      Note

      You can add the workspace to your playbook to scale your workspace utilization.

2. From the Ansible Automation Platform user interface:

   1. Create a credential.
   2. Build an execution environment in Ansible Automation Platform.
   3. Create and launch a job template.

3. (Optional) After the migration is completed and verified, you can run the additional modules and plugins from the collection in your execution environment:

   • Plan Stash module
   • Terraform module
   • Output plugin
   • Output lookup plugin
   • State inventory plugin

Procedure

1. Define the aap_job_launch action in your *.tf file.

2. Add a lifecycle job block to define which action will be invoked during the proper lifecycle event trigger.

   Example

1. (Required) Change the job template name and the inventory name in this example to your corresponding variables.
2. (Optional) You can set owners to the Red Hat RHEL image ID so that the latest image is used each time the job runs.
3. (Optional) Set additional parameters as needed. For example, you can set wait_for_completion to true, then Terraform will wait until this job is created and reaches any final state before continuing. You can also set wait_for_completion_timeout_seconds to control the timeout limit.
4. Update and commit the Terraform code.
5. Execute the Terraform plan and apply it.