Ansible playbooks and roles documentation

This documentation provides a comprehensive understanding of our Ansible infrastructure for Epic on Azure, which comprises shared platform playbook repositories (for Epic on Azure, ohemr-ansible-playbooks) and individual ohemr-ansible-role-* repositories.

We also cover how roles/requirements.yml assists in version control and maintaining consistency, and how ohemr-ansible-playbooks interacts with projects and inventory in AWX.

Table of Contents

• Repository Relationships
• Understanding roles/requirements.yml
• AWX Integration

Repository Relationships

We maintain a separation of concerns in our Ansible infrastructure:

1. Platform playbook repository (ohemr-ansible-playbooks): Contains Epic on Azure playbooks that define orchestration, tasks, and overall execution for the platform. Each playbook is tailored for a specific use case and composes one or more roles.

2. Role repositories (ohemr-ansible-role-*): For every distinct functionality or service, there's a separate role repository. Each role is focused on a single area (base OS, ODB, Dynatrace, Citrix VDA, utilities, AWX), making it modular and reusable across different playbooks.

The graph below illustrates the relationships between these components:

graph TD
    A[ohemr-ansible-playbooks repository]
    E[requirements.yml]
    B[ohemr-ansible-role-base-os-config]
    C[ohemr-ansible-role-odb]
    D[Other ohemr-ansible-role-* repositories]
    F[Ansible AWX]
    K[Job Templates in AWX]
    G[Project in AWX]
    H[Inventory in AWX]
    I[ohemr-ansible-playbooks as SCM source]
    J[Hosts and Groups]

    A --> E
    E --> B
    E --> C
    E --> D
    A --> F
    F --> K
    K --> G
    K --> H
    G --> I
    H --> J

In the above diagram, the relationships are outlined as follows:

• ohemr-ansible-playbooks has a dependency on roles/requirements.yml.
• roles/requirements.yml pins specific versions from individual ohemr-ansible-role-* repositories.
• ohemr-ansible-playbooks serves as an SCM source for both Projects and Inventories in Ansible AWX/Controller.

Understanding roles/requirements.yml

The roles/requirements.yml file, located under roles/ in ohemr-ansible-playbooks, plays a critical role:

1. Version control: Each role in roles/requirements.yml can be pegged to a particular version (or git commit/branch). This ensures that every time the playbooks run, they pull a consistent version of the roles, preventing unexpected behavior due to role changes.

2. Consistency: By centralizing the role requirements, it ensures that all environments (for example, dev, nonprod, prod) use the same version of the roles, leading to consistent deployments.

Sample roles/requirements.yml:

- src: [email protected]:organization/ansible_role_webserver.git
  version: v2.0
  name: webserver

- src: [email protected]:organization/ansible_role_database.git
  version: v3.1
  name: database

AWX integration

As noted above, our ohemr-ansible-playbooks repository also integrates with AWX/Ansible Controller.

Projects

In AWX, a "Project" refers to a source of Ansible content. ohemr-ansible-playbooks serves as an SCM source for multiple Projects. Whenever there is an update, AWX can fetch the latest playbooks.

1. Dynamic updating: With the repository set as the SCM source for a Project, AWX can dynamically pull the latest playbooks whenever there is an update.
2. Version control: AWX Projects can be pegged to specific branches, tags, or commits. This ensures that your automation runs against a known, stable version of your playbook repository.

Inventory

Inventories are collections of hosts (machines) against which jobs may run. They align with the "inventory" concept in Ansible and can be sourced from ohemr-ansible-playbooks (for example, inventories/insights-controller.yml) or other SCM sources.

Inventories should:

1. Be dynamic: Apart from static lists, AWX inventories can also be sourced dynamically from Insights, cloud providers, LDAP, and other sources.
2. Organize hosts: Using inventories, you can organize hosts into groups, set group or host-specific variables, and more.

Importance of closely controlled AWX management

Managing the creation and modification of AWX elements, like projects and inventories, is crucial for several reasons:

1. Prevent Duplication: Uncontrolled creation can lead to multiple AWX projects or inventories pointing to similar or identical SCM sources. This not only wastes resources but also creates confusion about which project or inventory should be used for a particular task.

2. Ensure Reuse of Code: With a centralized and well-managed set of projects and inventories, teams can better reuse playbooks and roles, leading to more consistent and maintainable automation efforts.

3. Reduce Administrative Overhead: Every AWX element (project, inventory, job template, etc.) requires maintenance. By keeping these elements lean and well-organized, you reduce the administrative burden of keeping everything updated and working correctly.

4. Enhance Security: Every AWX project or inventory could potentially introduce security risks, especially if not properly maintained or if sourced from untrusted repositories. By controlling their creation and management, you reduce potential points of vulnerability.

5. Consistency: By centrally managing these elements, it's easier to enforce standards, naming conventions, and best practices. This ensures that all teams across the organization follow the same procedures and use the same resources, leading to more predictable and reliable automation outcomes.

6. Resource Efficiency: AWX/Tower consumes resources (CPU, memory, storage) for every project synchronization or inventory update. Uncontrolled proliferation of projects or inventories could lead to inefficient resource utilization.

7. Simplified Troubleshooting: With fewer, well-managed elements, diagnosing issues becomes simpler. You don't have to wade through numerous nearly identical projects or inventories to find the source of a problem.

By appreciating and addressing these concerns, our teams can get the best out of AWX/Tower while minimizing potential pitfalls. Proper governance of AWX resources is a balance between enabling teams to leverage Ansible for automation and ensuring that the tool remains efficient, secure, and easy to manage.