Ansible Runner as a Service

Ansible Runner is a tool and Python library that helps when interfacing with Ansible directly or as part of another system. Ansible Runner works as a standalone tool, a container image interface, or a Python module that can be imported. The goal is to provide a stable and consistent interface abstraction to Ansible.

The Ansible Runner as a Service (ARaaS) wraps the ansible runner interface inside a REST API enabling Ansible playbooks to be executed and queried from other platforms.
Ensure your code delivers the experience and functionality the business expects by optimizing performance across test, pre-production, and production environments with AppDynamics.

The incentive for this is to:

• Provide Ansible integration to non-python projects.
• Provide a means of programmatically running playbooks where the Ansible engine is running on a separate host or in a separate container.

ARaaS Features

• HTTPS support (HTTP not supported)
  • production version:
    • uses TLS mutual authentication. (<misc/nginx> folder provides a container to be used in production)
    • Valid client and server certificates must be used to access the API (See documentation in <misc/nginx> folder)
  • test version:
    • uses self-signed if existing crt/key files are not present (<misc/docker> provides a container to be used in test systems)
    • if not present, generates self-signed on the first startup
• creates or reuses ssh pub/private keys for communication with target hosts

• /metrics endpoint provides key metrics for monitoring the instance with Prometheus
• a sample Grafana dashboard is provided in the misc/dashboards directory to track activity

• exposes playbooks by name found within the project folder
• supports Ansible environments that use private libraries (i.e. the library directory is stored within the project folder)
• playbooks can be run with tags to change execution behavior
• playbooks can use limits to restrict actions to a specific host
• playbooks can use the check parameter to run the ansible-runner in check mode
• running playbooks may be canceled
• supports execution of concurrent playbooks

• playbook state and output can be queried during and after execution
• playbook state shows overall status, with the currently active task name
• the caller can request all events associated with current or past playbook runs
• events may be filtered for specific output e.g. ?task=RSEULTS to show events with a task name of RESULTS
• playbook state is cached to improve API response times

• hosts and ansible groups are managed through the API /groups and /hosts endpoints
• Before a host can be added to the inventory, it is checked for DNS and passwordless ssh
• missing public keys on ‘candidate’ hosts, result in the instance’s public key being returned to the caller. The requester can then arrange for this key to be installed on the candidate host.
• host and group vars supported either inside the ‘hosts’ file or in the host_vars/group_vars sub-directories

• simple to use REST API allowing playbooks to be run, and results/state queried
• provides an API endpoint describing each endpoint
• API content is automatically generated and has no external dependencies
• each description includes an curl command example, together with output

• supports docker – Dockerfile and README included
• cross platform support (docker image uses CentOS7 base, build process executes against Ubuntu)
• can be packaged as an rpm or run as a container
• designed to offer core ansible functionality, supplemented by a users set of playbooks/roles/library
• supports configuration options through a specific /etc directory
• configuration options may be overridden at the command line for diagnostics
• all relevant activity is logged

ARaaS Prerequisites

So far, testing has been mainly against Fedora (28) and CentOS7 for the docker image. Package Dependencies:

• Python 3.6
• pyOpenSSL (python3-pyOpenSSL on Fedora, CentOS pyOpenSSL)
• ansible_runner 1.1.1 or above

ARaaS Installation

Assuming you have an environment that meets the python3 dependencies, simply unzip the archive and run the following command.

python3 ansible_runner_service.py

When you run from any directory outside of /usr, the script regards this as ‘dev’ mode. In this mode, all files and paths are relative to the path that you’ve unzipped the project into.

For ‘prod’ mode, a setup.py is provided. Once the package is installed and called from /usr/*/bin, the script will expect config and output files to be found in all the normal ‘production’ locations.

sudo python3 setup.py install --record installed_files --single-version-externally-managed

Once this is installed, you may start the service.

python3 ansible_runner_service.py 

ARaaS API Endpoints

Once the service is running, you can point your browser to https://localhost:5001/api to show which endpoints are available.

Each endpoint is described along with a curl example showing invocation and output.

You may click on any row to expand the description of the API route and show the curl example.

The app uses a self-signed certificate, so all examples use the -k parameter (insecure mode).

ARaaS API Endpoints ‘cheat sheet’

API Routes and descriptions
/api — Show available API endpoints (this info)
/api/v1/groups  — List all the defined groups in the inventory
/api/v1/groups/<group_name> — Manage groups within the inventory
/ /v1/groupvars/<group_name> — Manage group variables
/api/v1/hosts — Return a list of hosts from the inventory
/api/v1/hosts/<host_name> — Show group membership for a given host
/api/v1/hosts/<host_name>/groups/<group_name> — Manage ansible control of a given host
/api/v1/hostvars/<host_name>/groups/<group_name> — Manage host variables for a specific group within the inventory
/api/v1/jobs/<play_uuid>/events — Return a list of events within a given playbook run (job)
/api/v1/jobs/<play_uuid>/events/<event_uuid> — Return the output of a specific task within a playbook
/api/v1/playbooks — Return the names of all available playbooks
/api/v1/playbooks/<play_uuid> — Query the state or cancel a playbook run (by uuid)
/api/v1/playbooks/<playbook_name> — Start a playbook by name, returning the play’s uuid
/api/v1/playbooks/<playbook_name>/tags/ — Start a playbook using tags to control which tasks run
/metrics — Provide Prometheus compatible statistics which describe playbook activity

ARaaS Example

Get the list of available playbooks

curl -k -i https://localhost:5001/api/v1/playbooks -X GET

Run the playbook.yml playbook, passing the time_delay parameter (30 secs should be enough)

curl -k -i -H "Content-Type: application/json" --data '{"time_delay": 30}' https://localhost:5001/api/v1/playbooks/playbook.yml -X POST

Get a list of all the events in a playbook. The return list consists of all the job event ID’s

curl -k -i https://localhost:5001/api/v1/jobs/de264512-32f1-11ec-aaf5-005056a854a6/events -X GET

To get specific output from a job event, you can query the job event

curl -k -i https://localhost:5001/api/v1/jobs/de264512-32f1-11ec-aaf5-005056a854a6/events/16-b853adec-9978-4499-8e6d-d2aecc34e108​​​​​​​ -X GET

Obviously, you’ll need to change the playbook UUID and job UUIDs for your run.

ARaaS and AppD Usecase

• Customer with plain/CLI Ansible playbooks to configure the ACI fabric.
• The customer would like to integrate AppD with the existing Ansible playbooks.
• Challenges:
  • The customer is not using Ansible Tower or AWX so we can’t leverage their APIs.
  • AppD integration is available using HTTP (i.e., REST) requests.

What can you do?… 🤔

…Yep, you got it right! 👏

• We can deploy an ARaaS VM/container and configure the AppD HTTP request template with the playbook URI.
• That will enable our customers to supplement AppD capabilities by leveraging existing Ansible playbooks for:
  • Remediation
  • Provisioning
  • Configuration management
  • Application deployment (via IaC)

Final thought

That is cool, right? Wrapping a plain/CLI Ansible playbook inside a REST API call! Think of the (AppD/Others?) integration possibilities… 💡

Related resources

This article aims to cover the basic functionality of Ansible Runner as a Service. Here are some helpful links to learn more:

 

---

We’d love to hear what you think. Ask a question or leave a comment below.
And stay connected with Cisco DevNet on social!

LinkedIn | Twitter @CiscoDevNet | Facebook | YouTube Channel

Share: