Chapter 10. Configuration consistency across multi Ansible Automation Platform deployments

10.1. Why configuration as code?

Traditionally, when we think about having consistency across multiple Ansible Automation Platform deployment sites, we think of using database replication to copy the data from one Ansible Automation Platform environment and importing that data to another Ansible Automation Platform site.

This could be done with scripts, specialized software, manual export of the database followed by an import the Ansible Automation Platform database to the new site, or even running custom Ansible playbooks that do something similar.

While there are many different methods, typically, these methods have cons associated with them.

For example, database replication requires investments in storage infrastructure and concurrency could be hard to achieve without the right expertise.

10.2. What is configuration as code?

Configuration as code is defined as the practice of managing configuration files in a repository. In the case of Ansible Automation Platform, these configuration files establish the settings we wish to apply across our Ansible Automation Platform environments.

By storing and managing Ansible Automation Platform configuration files as code, we can:

  • standardize the settings being applied to all our Ansible Automation Platform environments
  • inherit the benefits of version control of our configurations
  • easily scale additional Ansible Automation Platform deployments to use the same configuration settings
  • easily track changes of the configuration settings making fixing issues easier

While configuration as code provides numerous benefits and best practices that can be applied across an Ansible Automation Platform environment, in order to streamline and automate the delivery of the configurations to our multiple Ansible Automation Platform sites automatically, immediately and consistently, we must pair our configuration as code solution with Git webhooks.

10.3. What are Git webhooks?

Git webhooks are defined as a method for notifications to be delivered to an external web server whenever certain actions occur on a repository or organization.

For example, when a repository is updated, this could trigger an event that could trigger CI builds, deploy an environment, or in our case, update configurations to our Ansible Automation Platform environments.

With the solution of configuration as code and Git webhooks, we can setup a Ansible Automation Platform work flow that immediately updates all of our Ansible Automation Platform sites simultaneously with the exact configurations across all the platforms.

In effect, removing the overhead of having to maintain database backups or enable an expensive database replication solution while achieving the pros of those solutions.

With this methodology in mind, the following sections focus on how an admin can take advantage of configuration as code to ensure consistency across multiple Ansible Automation Platform environments using Git webhooks.

10.4. Working with webhooks

A webhook provides the ability to execute specified commands between apps over the web. Ansible automation controller currently provides webhook integration with GitHub and GitLab. This reference environment describes the procedure for setting up a webhook in automation controller using GitHub.

10.4.1. GitHub webhook setup

Automation controller has the ability to run jobs based on a triggered webhook event. The following provides the step-by-step for that setup.

Create a GitHub personal access token

  1. Generate a personal access token (PAT) for use with automation controller.

    1. In the profile settings of your GitHub account, click Settings.

    2. Below the Personal settings, click Developer Settings.

      webhooks create webhook github settings
    3. In the Developer settings, click Personal access tokens.
    4. From the Personal access tokens screen, click Generate new token button.
    5. When prompted, enter your GitHub account password to continue.
    6. In the Note field, enter a brief description about what this PAT will be used for.
    7. In the Expiration drop down, select No expiration.

    8. In the Scope fields, automation controller webhook only needs repo scope access, with the exception of invites. For information about other scopes, click the link right above the table to access the docs.

      scopes

    9. Click the Generate Token button at the bottom of the page.

      Warning

      Once the token is generated, make sure you copy the PAT, as it will be used by Ansible Automation Platform automation controller cluster in a later step. You will not be able to access this token again in GitHub.

Create a GitHub repository

Once we have our PAT in place, the next step is to create a Git repository that will be triggered by our GitHub webhooks when changes are made to the repository.

Since the focus is to be able to easily update or modify our automation controller configurations, this reference environment takes advantage of an Ansible collection named redhat_cop.controller_configuration.

This Ansible collection allows for easy interaction with Ansible controller servers via Ansible roles using the controller collection modules.

With the help of this collection, we can use these pre-existing roles to modify or update our automation controller environments across all our sites.

Note

The redhat_cop.controller_configuration collection is a community project and officially not supported by Red Hat.

  1. In GitHub, create a new repository.

    1. Ensure to select the appropriate Owner and provide a Repository name.

      1. This reference environment uses the repository name aap_refarch.
    2. Provide an optional description to describe your repository.

    3. Set your repository to public or private.

      1. This reference environment sets the repository to Public.
    4. Initialize the repository with an Add a README file.
  2. Click on the create repository button.

Within the newly created GitHub repository, three files are created.

  • playbook.yml - A playbook with all the appropriate roles to update or modify our automation controller.
  • requirements.yml - A requirements.yml file with all the collections required to run the playbook.
  • group_vars/all.yml - An all.yml file containing all the variables we wish to modify for a specific configuration (role).

The purpose of these three files is to provide a method that when the group_vars/all.yml is modified and updated to the repository, this will kick off a job template within our Ansible Automation Platform automation controller cluster to make the appropriate change or update.

Note

A sample of these three files can be found within the Appendix C, Supplemental section of this guide or https://github.com/ansible/aap_refarch

Setting up resource credentials within Ansible Automation Platform automation controller cluster

Prior to using our repository as configuration as code, setup the appropriate credential resources within our Ansible Automation Platform sites.

This ensures that as new projects, work flows and job templates are created, we can easily attach those credentials to those resources.

The following steps show how to create our two required credentials.

One credential associated with the GitHub (PAT) token we created previously.

The other credential associated with the Ansible Automation Platform site that will get updated. Each Ansible Automation Platform site will get updated by its own environment, e.g. site1 gets updated by site1.

On each Ansible Automation Platform site:

  1. Login to your Ansible Automation Platform automation controller dashboard

  2. Under Resources→ Credentials click the blue Add button.

    1. Provide a Name, e.g. GitHub PAT
    2. Select GitHub Personal Access Token as the Credential Type .
    3. Within Type Details, add the secret using the previously generated token from GitHub.

  3. Click Save.

    Note

    Make note of the name of this credential, as it will be used in the job template that posts back to GitHub.

With the GitHub PAT credential set, create a second credential for the the existing Ansible Automation Platform environment.

  1. Under Resources→ Credentials click the blue Add button.

    1. Provide a Name, e.g. AAP_Site1
    2. Provide Red Hat Ansible Automation Platform as the Credential Type .

    3. Within Type Details, add the appropriate details

      1. Red Hat Ansible Automation Platform, e.g. controlplane-cluster.site1.example.com
      2. Username, e.g. admin
      3. Password, e.g. redhat
    4. If the SSL certificate is signed, ensure to select Verify SSL within Options.
  2. Click Save.

Repeat this section on Ansible Automation Platform site two.

Note

controlplane-cluster.site1.example.com is used as this reference environment takes advantage of a load balancer. Setup of a load balancer is out of scope for this reference environment.

Creating the configuration as code project

The purpose of the configuration as code project is to create a work flow that contains a job template that automatically runs every time an update to the configuration as code repository takes place.

This ensures that as you make changes such as setting variables, the Git repository playbook runs the appropriate roles for the numerous automation controller configurations.

This section creates a project, work flow and job template to achieve the above.

Within your Ansible Automation Platform site one dashboard,

  1. Under Resources→ Projects click the blue Add button.
  2. Provide a Name, e.g. Configuration as Code Project
  3. Select Default as the Organization
  4. Select Default execution environment as the Execution Environment
  5. Select Git as the Source Control Credential Type

  6. Within Type Details,

    1. Add the Source Control URL (your GitHub repository)

  7. Within Options

    1. Select Clean, Delete, Update Revision on Launch
  8. Click Save.

Next, create a work flow template.

  1. Under Resources→ Templates click the blue Add → Add workflow template.
  2. Provide a Name, e.g. Configuration as Code Workflow

  3. Within Options, checkmark Enable Webhook.

    1. Within Webhook details, select GitHub as the Webhook Service.
    2. Within Webhook details, select your GitHub PAT token previously created as the Webhook Credential, e.g. GitHub PAT
  4. Click Save.
  5. Within the Please click the Start button to begin window, click the Save at the top right corner.
  6. Copy the Webhook URL and the Webhook Key as they will be used later.

Repeat the above process on Ansible Automation Platform site two.

Enabling GitHub Webhooks for the Repository

With our Ansible Automation Platform Workflow template created and our GitHub repository with the required files in place, the next step is to enable webhooks for our repository, e.g. aap_refarch.

  1. At the homepage of your GitHub repository, select the Settings tab.

  2. Within the Settings tab, select Webhooks.

    webhooks option
  3. Within the Webhooks section, select the Add webhook button.
  4. Enter the Payload URL (Webhook URL of the workflow).
  5. Change the Content type drop down to application/json.
  6. Enter the Secret (Webhook key of the workflow).

  7. Leave the defaults to use push events, and click the button Add webhook.

    Warning

    By default, GitHub verifies SSL certificates when delivering payloads. If your automation controller SSL certificates are not signed, ensure to disableSSL verfication.

Repeat the above process on Ansible Automation Platform site two.

Creating the configuration as code job template

The job template to be created for our configuration as code project runs the playbook.yml file automatically every time an update to the Git repository takes places.

This ensures as configuration changes are desired, we can use the Ansible Automation Platform controller API to make those changes appropriately. When we combine the same methodology across all our Ansible Automation Platform sites, all the changes become global across the configured sites.

  1. Under Resources→ Templates click the blue Add → Add job template.
  2. Provide a Name, e.g. Configuration as Code Job
  3. Select Run as the Job Type
  4. Select Demo Inventory as the Inventory
  5. Select Configuration as Code Project as the Project
  6. Select Default execution environment as the Execution Environment
  7. Select playbook.yml as the Playbook
  8. Select Credentials and switch the category from Machine to Red Hat Ansible Automation Platform
  9. Select the appropriate credential for the Ansible Automation Platform site, e.g. AAP_Site1
  10. Within Options, select Enable webhook.
  11. Select GitHub as the Webhook Service.
  12. Select your GitHub PAT token previously created as the Webhook Credential, e.g. GitHub PAT
  13. Click Save.

Repeat the above process on Ansible Automation Platform site two.

Updating the created Configuration as Code Workflow

Previously, the Configuration as Code workflow was created. The purpose of this workflow is to ensure that the Configuration as Code Project is always in sync and that the Configuration as Code Job runs the configuration as code playbook whenever changes are made to the repository.

  1. Under Resources→ Templates, select your template. e.g Configuration as Code Workflow
  2. Within the Details section, select the Visualizer tab and click the green Start.
  3. For Node Type select Project Sync and select the appropriate project, e.g. Configuration as Code Project and click Save.
  4. Hover over the Configuration as Code Project and select the plus "+" symbol.
  5. Within the Add Node window, select Always as to when this node should be executed and click Next.
  6. Select the Configuration as Code Job as the Node Type and click Save.
  7. Once brought back to the Visualizer, select the Save button at the top right corner.

Verifying Configuration as Code setup

With many of the roles already included in the redhat_cop.controller_configuration, a simple method to verify if everything is working as expected is to create a user by updating the group_vars/all.yml file with the appropriate yaml.

If we wanted to create a user, we would take a closer look at the users role documentation to further see all the variables at our disposable.

After further review, we notice creating a non-admin user, named John would look as follows:

group_vars/all.yml

---
controller_user_accounts:
  - user: "john"
    is_superuser: false
    password: "redhat"

Once the group_vars/all.yml file is updated with the above and pushed to the Git repository, a job within Ansible Automation Platform automation controller should start.

This can be verified by selecting Jobs under the Views section within the automation controller dashboard. The job in reference should have the number of the job followed by the job name. For this reference environment, you’d see something similar to 8-Configuration as Code Job with the TypePlaybook Run

jobs

Once the job is complete, it will have a status of Successful.

Logging out as admin and relogging in as the user john with the password redhat should confirm that the job was successful.

If you followed this entire chapter and set the webhooks appropriately for each Ansible Automation Platform site, you will notice that the user john was created simultaneously by the corresponding Ansible Automation Platform platform.

While this example is a simplified one, many of the configurations (roles) that allow for the configuration of Ansible Automation Platform automation controller are provided within the redhat_cop.controller_configuration.

Additional examples may be found at: Example configs.

While the Ansible collection has many of the key roles you’ll ever need, you are not limited to only what can be found within this Ansible collection. New roles can be implemented or created by your organization to further enhance your capabilities.