Embedded Ansible & Playbooks

Relevant source files

The following files were used as context for generating this wiki page:

• app/models/manageiq/providers/embedded_ansible/automation_manager/configuration_script_source.rb
• lib/ansible/runner.rb
• lib/ansible/content.rb
• app/models/manageiq/providers/embedded_ansible/automation_manager/playbook.rb
• spec/models/manageiq/providers/embedded_ansible/automation_manager/configuration_script_source_spec.rb
• spec/models/manageiq/providers/ansible_playbook_workflow_spec.rb
• app/models/miq_ae_method.rb

Embedded Ansible provides an integrated automation engine within ManageIQ, allowing users to run Ansible playbooks and roles directly from the platform. It leverages a Git-based repository system to manage automation content and an internal Ansible::Runner module to interface with the ansible-runner CLI tool. This integration supports various automation workflows, including provisioning, configuration management, and complex orchestration via the Automate engine.

The system is architected around "Repositories" (represented as ConfigurationScriptSource) which synchronize playbooks from Git, and "Playbooks" (payloads), which are executable units. Automation can be triggered synchronously, asynchronously, or via the ManageIQ queue system.

Sources: app/models/manageiq/providers/embedded_ansible/automation_manager/configuration_script_source.rb:2-5, lib/ansible/runner.rb:10-25, app/models/miq_ae_method.rb:25-27

Core Components and Architecture

Configuration Script Source (Repositories)

The ConfigurationScriptSource class manages the lifecycle of an "Embedded Ansible Project." It connects to a Git repository, tracks branches, and synchronizes YAML files identified as playbooks.

• Sync Logic: The sync method updates the local Git repository, iterates through the worktree, and identifies valid playbooks. It handles ansible-vault encrypted files by marking them as encrypted without reading the plaintext content.
• Validation: A file is considered a valid playbook if it has a .yml or .yaml extension and contains keywords like hosts, include, or import_playbook, or starts with the $ANSIBLE_VAULT header.
• Excluded Directories: The system ignores files within roles, tasks, group_vars, and host_vars directories to ensure only executable playbooks are registered as payloads.

Sources: app/models/manageiq/providers/embedded_ansible/automation_manager/configuration_script_source.rb:20-60, app/models/manageiq/providers/embedded_ansible/automation_manager/configuration_script_source.rb:85-115

Ansible Runner Integration

The Ansible::Runner class serves as the interface between ManageIQ and the ansible-runner executable. It handles the preparation of temporary directories, inventory generation, and credential injection.

Playbook Execution Workflow

Execution is managed through the AnsiblePlaybookWorkflow. This state machine handles the asynchronous nature of Ansible jobs.

State	Description
waiting_to_start	Initial state of the job.
pre_execute	Checks out the Git repository to a temporary directory.
execute	Launches the ansible-runner via CLI.
poll_runner	Monitors the process and checks for timeouts.
post_execute	Finalizes data and performs cleanup.

Sources: spec/models/manageiq/providers/ansible_playbook_workflow_spec.rb:15-80

Technical Implementation Details

Ansible Runner Execution Methods

The Ansible::Runner module provides multiple entry points for automation execution, supporting both playbooks and direct role execution.

Method	Type	Purpose
run	Sync	Runs a playbook and waits for completion.
run_async	Async	Starts a playbook and returns a ResponseAsync object.
run_queue	Queued	Enqueues a run task in the generic worker queue.
run_role	Sync	Executes a specific Ansible role directly.

Sources: lib/ansible/runner.rb:15-90

Git Repository Synchronization

The synchronization process ensures that the ManageIQ database reflects the current state of the external Git repository.

Content Management

The Ansible::Content class manages external dependencies. It includes logic to fetch roles from Ansible Galaxy using a requirements.yml file found within the roles directory of a project.

• Plugin Content: Plugins can provide their own Ansible content. The system can consolidate this content into a single directory (content/ansible_consolidated) for use by the runner.
• Galaxy Integration: The fetch_galaxy_roles method uses AwesomeSpawn to run ansible-galaxy install with specific roles and requirements paths.

Sources: lib/ansible/content.rb:10-30, lib/ansible/content.rb:40-50

Automation Engine Integration

Embedded Ansible is integrated into the Automate engine via MiqAeMethod. This allows Ansible playbooks to be used as automation methods alongside Ruby and Perl scripts.

• Location Types: Supported locations include playbook, ansible_job_template, and ansible_workflow_template.
• Credential Handling: Credentials (authentications) are injected into the environment by the Ansible::Runner during execution. The playbook.run method allows passing extra_vars, which are decrypted before being passed to the runner.

Sources: app/models/miq_ae_method.rb:25-27, spec/models/manageiq/providers/embedded_ansible/automation_manager/playbook_spec.rb:75-85

Summary

Embedded Ansible & Playbooks provide a robust framework for Git-based automation within ManageIQ. By utilizing ansible-runner, the system decouples the main application logic from the execution environment while maintaining tight integration through state machines and the Automate engine. The design emphasizes security (via ansible-vault support and credential injection) and scalability (via asynchronous and queued execution models).

Sources: app/models/manageiq/providers/embedded_ansible/automation_manager/configuration_script_source.rb, lib/ansible/runner.rb, spec/models/manageiq/providers/ansible_playbook_workflow_spec.rb