---
menu:
  learn:
    parent: Validated patterns frameworks
title: Using the Controller Configuration collection 
weight: 25
aliases: /ocp-framework/agof/config-controller/
---

:toc:
:imagesdir: /images
:_content-type: ASSEMBLY
include::modules/comm-attributes.adoc[]

== Overview of the Ansible GitOps Framework (AGOF) Installation Process

The Ansible GitOps Framework (AGOF) is a powerful solution designed to automate the deployment and configuration of Ansible Automation Platform (AAP) environments using link:https://opengitops.dev/[GitOps principles]. It leverages Ansible to manage infrastructure and application provisioning in a declarative, version-controlled way. AGOF provides a structured approach to setting up cloud infrastructure, installing AAP components, and handing over control to the AAP Controller for ongoing automation and management. An overview of the steps involved in configuring a basic minimal demo application are listed here:

=== 1. Pre-Init Environment (Bootstrap Ansible)

* *Ansible Configuration*: The environment is initialized by generating an `ansible.cfg` file, which is configured with Automation Hub and public Galaxy endpoints. This process includes vault configuration to inject the Automation Hub token and install required Ansible collections from `requirements.yml`.
* *Optional Image Build*: Images are created using Red Hat Image Builder to produce AMIs, which include `cloud-init`, activation keys, and organization details. These images can be reused in future installations.

=== 2. Infrastructure Building (AWS Only)

* *AWS Setup*: The framework sets up AWS infrastructure, including VPC, subnets, and security groups, using predefined roles. It also manages Route53 DNS entries for VMs.
* *VM Deployment*: Virtual machines are provisioned on EC2 with persistent hostnames and updates to `/etc/hosts` for AWS nodes. DNS entries are updated when IPs change after VM reboots.

=== 3. Handover to Ansible Controller

* *Controller Setup*: The Ansible Automation Platform (AAP) Controller and optionally the Automation Hub are installed and configured. Entitlements are managed through a manifest, and execution environments and collections are downloaded and prepared.
* *GitOps Mode*: After configuration, AGOF transitions to GitOps mode. Git commits made by the controller to the repositories manage all environment changes, ensuring declarative and automated infrastructure management from this point onward.

== Controller configuration collection

An AGOF pattern, for example, https://github.com/mhjacks/agof_demo_config is primarily an IaC (infrastructure as code) artifact designed to be used with the `controller_configuration` collections. 

The AGOF (Ansible GitOps Framework) repository  https://github.com/validatedpatterns/agof contains the code and tools needed to set up a new Ansible Automation Platform (AAP) instance. This setup is automated, using Infrastructure as Code (IaC) practices. It also includes some specific preferences to make it easier for others to publicly share and manage this type of infrastructure setup.

This approach ensures the automation controller configuration is version-controlled, dynamic, and reproducible. This method enables deployment automation with minimal manual intervention, which is useful for managing multiple controller instances or different environments in a CI/CD pipeline.

For example, for the AGOF minimal configuration demo the file https://github.com/mhjacks/agof_demo_config/blob/main/controller_config.yml is used with Ansible's Controller Configuration Collection, allowing the automation and management of Red Hat Ansible Automation Controller (formerly known as Ansible Tower). 

[source,yaml]
----
# vim: ft=yaml.ansible
---
orgname_vault: 'Demo Organization'

controller_username_vault: 'admin'
controller_password_vault: '{{ admin_password }}'

controller_username: '{{ controller_username_vault }}'
controller_password: '{{ controller_password_vault }}'

agof_demo_project_name: 'Ansible GitOps Framework Minimal Demo'

controller_validate_certs: false

controller_configuration_async_retries: 30

controller_settings: []

controller_projects:
  - name: Demo Project
    state: absent

  - name: '{{ agof_demo_project_name }}'
    organization: "{{ orgname_vault }}"
    scm_branch: main
    scm_clean: "no"
    scm_delete_on_update: "no"
    scm_type: git
    scm_update_on_launch: "yes"
    scm_url: 'https://github.com/validatedpatterns-demos/agof_minimal_demo.git'

controller_organizations:
  - name: '{{ orgname_vault }}'

controller_inventories:
  - name: 'AGOF Demo Inventory'
    organization: '{{ orgname_vault }}'

controller_inventory_sources:
  - name: 'AGOF Demo Inventory Source'
    inventory: 'AGOF Demo Inventory'
    credential: 'ec2_ssh_credential'
    overwrite: true
    overwrite_vars: true
    update_on_launch: true
    source: scm
    source_project: '{{ agof_demo_project_name }}'
    source_path: 'inventory'

controller_credential_types: []

controller_templates:
  - name: Demo Job Template
    state: absent

  - name: Ping Playbook
    organization: "{{ orgname_vault }}"
    project: '{{ agof_demo_project_name }}'
    job_type: run
    playbook: 'ansible/playbooks/ping.yml'
    inventory: "AGOF Demo Inventory"
    credentials:
      - ec2_ssh_credential

controller_schedules:
  - name: Ping Playbook
    organization: "{{ orgname_vault }}"
    unified_job_template: Ping Playbook
    rrule: DTSTART:20191219T130500Z RRULE:FREQ=MINUTELY;INTERVAL=120

demo_ssh_key_file: '~/{{ ec2_name_prefix }}/{{ ec2_name_prefix }}-private.pem'

controller_credentials:
  - name: ec2_ssh_credential
    description: "EC2 SSH credential"
    organization: '{{ orgname_vault }}'
    credential_type: Machine
    inputs:
      username: 'ec2-user'
      ssh_key_data: "{{ lookup('file', demo_ssh_key_file) }}"
      become_method: sudo

controller_launch_jobs:
  - name: Ping Playbook
    organization: "{{ orgname_vault }}"
----

This file automates the creation, updating, or deletion of Ansible Controller objects (organizations, projects, inventories, credentials, templates, schedules). Sensitive information like passwords and keys are pulled dynamically from vaults, ensuring they are not hardcoded in the configuration. 

A Git repository manages the project’s inventory and playbooks, allowing for continuous integration and delivery (CI/CD) practices. AAP automatically schedules recurring playbook executions, eliminating the need for manual job triggers.

== Key sections and parameters 

This section describes the parameters associated with the Ansible GitOps Framework minimal configuration demo. 

=== Vault variables

*`orgname_vault: 'Demo Organization'`*:: 
This specifies the organization name stored in a vault for security purposes.

*`controller_username_vault: 'admin'`*:: 
This is the Ansible Controller's username stored in a vault.

*`controller_password_vault: '{{ admin_password }}'`*:: 
The initial admin password that AAP is configured with to allow the controller_username to log in. This particular password is not retrieved from a vault.

=== Dynamic variables

*`controller_username: '{{ controller_username_vault }}'`*:: 
The Ansible Controller username is retrieved from the vault variable.

*`controller_password: '{{ controller_password_vault }}'`*:: 
The password is dynamically fetched from the vault.

=== Project configuration
Projects are git repositories that can contain inventories and collections (and collections can contain playbooks). 

*`agof_demo_project_name: 'Ansible GitOps Framework Minimal Demo'`*:: 
This variable holds the name of the project being managed in the controller.

*`controller_projects`*:: 
Two projects are defined:
  * One with the name *'Demo Project'*, marked for deletion (`state: absent`).
  * The other is the actual project that will be created, associated with the Git repository hosted on GitHub.

For more information see, link:https://github.com/redhat-cop/controller_configuration/blob/devel/roles/projects/README.md[controller_configuration.projects].

=== Organizations

Organizations represent a logical grouping for managing resources such as projects and inventories.

*`controller_organizations`*:: 
Ensures that the organization, defined in `orgname_vault`, exists within the controller. For more information see, link:https://github.com/redhat-cop/controller_configuration/blob/devel/roles/organizations/README.md[controller_configuration.organizations].

=== Inventory and inventory sources

*`controller_inventories`*:: 
Defines an inventory called *'AGOF Demo Inventory'* under the *'Demo Organization'*. For more information see, link:https://github.com/redhat-cop/controller_configuration/blob/devel/roles/inventories/README.md[controller_configuration.inventories].


*`controller_inventory_sources`*:: 
Configures an inventory source tied to the Git project. The inventory is pulled from source control management (SCM) and associated with credentials for SSH access (`ec2_ssh_credential`). For more information see, link:https://github.com/redhat-cop/controller_configuration/blob/devel/roles/inventory_sources/README.md[controller_configuration.inventory_sources].

=== Job templates

Job Templates define a specific playbook run, associating it with inventories, credentials, and other settings.

*`controller_templates`*:: 
Two job templates are managed:
  * One named *'Demo Job Template'*, marked for deletion.
  * The other, *'Ping Playbook'*, is tied to a specific playbook (`ping.yml`), inventory, and project, and will use the defined credentials for execution.

For more information see, link:https://github.com/redhat-cop/controller_configuration/blob/devel/roles/job_templates/README.md[controller_configuration.job_templates].

=== Job scheduling

*`controller_schedules`*:: 
Configures a recurring job schedule to run the *'Ping Playbook'* template every 120 minutes. The schedule uses an iCal `RRULE` format. For more information see, link:https://github.com/redhat-cop/controller_configuration/blob/devel/roles/schedules/README.md[controller_configuration.schedules].

=== Credentials

Credentials store authentication details for accessing external systems like clouds, networks, and SCMs. 

*`controller_credentials`*:: 
A credential named *'ec2_ssh_credential'* is created with SSH access to the EC2 instances using the private key stored at the path specified in `demo_ssh_key_file`. For more information see, link:https://github.com/redhat-cop/controller_configuration/blob/devel/roles/credentials/README.md[controller_configuration.credentials].

=== Job Launching

*`controller_launch_jobs`*:: 
Automatically launches the *'Ping Playbook'* job template within the organization defined in `orgname_vault`. For more information see, link:https://github.com/redhat-cop/controller_configuration/blob/devel/roles/job_launch/README.md[controller_configuration.job_launch].

For more information about the controller configuration see:  

* link:https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.4/html-single/automation_controller_administration_guide/index[Red Hat Automation Controller Admin Guide]

* link:https://github.com/redhat-cop/controller_configuration[Red Hat Communities of Practice Controller Configuration Collection]

* link:https://galaxy.ansible.com/ui/repo/published/infra/controller_configuration/docs/[Galaxy Red Hat Communities of Practice Controller Configuration Collection documentation]
