About

Overview

The Itential Automation Gateway (previously known as Itential Ansible Manager) is a stand-alone user interface that acts as a gateway to popular network automation tools such as Ansible®, an open source platform from Red Hat® that manages machines over the SSH protocol. Ansible is a popular choice for IT automation, configuration management and provisioning because of its extensive library of connectivity helpers and its approachable "scripting language". Unfortunately many tools such as Ansible lack out of the box support for programmable interfaces and tend to have very abstract concepts of inventory. Automation Gateway (AG) aims to solve these constraints by providing a simple REST API and a standardized inventory concept.

This guide introduces the Automation Gateway along with its installation and configuration instructions. It will also provide information on how to enhance and decorate an existing schema for content such as an Ansible Module/Role/Playbook, Nornir Module, Terraform Module, or even your own custom scripts. Finally, you will discover how to interact with API definitions through an interactive API documentation UI.

Key Features

Automation Gateway is a robust, standalone application that runs as its own REST-ful process. It has many different feature sets, or integrations, which can be used to manage a wide range of devices.

Automation Gateway

As a network automation solution, Automation Gateway:

• Enables connectivity and interactivity with an extremely wide range of devices.
• Leverages multiple libraries and execution styles from pure Python to Ansible Runner to shell scripting.
• Returns discovered elements as JSON-Schema models which can be enhanced to handle user inputs.
• Secures access via presentation of user/password credentials.
• Natively supports the HTTP protocol and HTTPS via proxy for client/server communication.
• Supports multiple inventory systems (Ansible, Nornir, etc) and sources (internal or external) for managing devices.
• Provides a stateless server and has no requirements on redundancy roles.

Automation Gateway integrates with the following automation tools:

• Ansible
• Nornir
• Netmiko
• Terraform
• Custom Scripts

Functional attributes regarding each automation tool are highlighted in the lists below.

Ansible

• Discover and execute the network family of Ansible modules.
• Discover and execute Ansible certified roles.
• Discover and execute any Ansible playbooks.
• Discover and execute any Ansible Collections.
• Install Ansible Galaxy Collections.
• Enable intelligent Ansible module/role/playbook decorations to specify and validate the required input parameters.
• Access and update Ansible hosts (inventory).

Nornir

• Discover and execute user provided Nornir modules.
• Enable intelligent Nornir module decorations to specify and validate the required input parameters.
• Access Nornir configuration and hosts (inventory).

Netmiko

• Establish connections with a wide range of Netmiko-supported devices.
• Execute the send_command function to gather data from devices.
• Execute the send_config_set function to configure devices.

Terraform

• Discover and execute user provided Terraform modules.
• Enable intelligent Terraform module decorations to specify and validate the required input parameters.
• Execute Terraform actions such as Initialize, Plan, Apply, Destroy, Validate.

Custom Scripts

• Discover and execute user provided scripts in the user defined scripting environment (shell, Python, etc).
• Enable intelligent script decorations to specify and validate the required input parameters.

Ansible Primer

While certainly full featured, the architecture, terms, and concepts associated with Ansible are relatively common in the Python network automation space.

Architecture

In the diagram below, the Ansible automation engine has a direct interaction with the users who write playbooks to execute the Ansible Automation engine. It also interacts with cloud services and a Configuration Management Database (CMDB).

Component	Description
Inventory	Inventory files are simple text files which describe servers, IP Addresses or DNS Names grouped by names. The inventory file can list individual hosts or user-defined groups of hosts.
API	APIs in Ansible are used as transport for Cloud services, public or private.
Modules	Modules are executed directly on remote hosts through playbooks. The modules can control system resources (i.e., services, packages, or files), or execute system commands, by acting on system files, installing packages or making API calls to the service network.
Plugins	Plugins augment Ansible’s core functionality and allows users to execute Ansible tasks. Ansible comes with built-in plugins; however, users are able to develop their own.
Networking	Ansible can be used to automate different networks. Ansible uses a simple, agentless automation framework. It uses a data model (a playbook or role) that is separate from the Ansible automation engine that easily spans different network hardware.
Hosts	The hosts in the Ansible architecture are just node systems which are getting automated by Ansible. It can be any kind of machine – Windows, Linux, Red Hat etc.
Playbooks	Playbooks are simple files written in YAML format which describes the tasks to be executed by Ansible. Playbooks can declare configurations and orchestrate the steps of any manual ordered process, even if it contains jump statements. They can launch tasks synchronously or asynchronously.
CMDB	The Configuration Management Database (CMDB) is a repository that acts as a data warehouse for IT installations. It holds data relating to a collection of IT assets (commonly referred to as configuration items (CI).
Cloud	A network of remote servers hosted on the Internet to store, manage, and process data, rather than a local server. You can launch your resources and instances on cloud and connect to your servers.

Concepts and Terminology

Below is a brief primer on Ansible concepts which will help you understand Ansible and its role in Automation Gateway.

Playbooks

• Playbooks are expressed in YAML format, a simple syntax for Ansible’s configuration, deployment, and orchestration infrastructure.
• They can describe a policy you want your remote systems to enforce, or a set of steps in a general IT process.
• A Playbook can be composed of one or more ‘plays’ in a list. A play is provisioning executed from start to finish. In simple words, execution of a playbook is called a play.
• The goal of a play is to map a group of hosts to some well-defined roles, represented by "tasks".

Inventory

• Inventory files are text files which describe the connectivity details and other variables related to your servers, IP Addresses, or DNS Names.
• The inventory file can list individual hosts or user-defined groups of hosts, and it can be specified in multiple formats (ini, json, yaml, etc.).
• Dynamic Inventories can get data from dynamic sources, including cloud sources, such as OpenStack, AWS, DigitalOcean, Google, OpenShift.

Roles

• Roles are units of organization in Ansible that serve as the primary mechanism for breaking a playbook into multiple files, which makes them easier to reuse.
• Roles are ways of automatically loading certain vars_files, tasks, and handlers based on a known file structure. Grouping content by roles also allows easy sharing of roles with other users.
• Roles can be shared and pulled from Ansible Galaxy, GitHub, etc.

Collections

• A collection is a bundle of Ansible content which acts as an extension to the product.
• In general, a collection consists of roles, modules and other plugins that extend Ansible's functionality.
• Collections can be as large as enabling connectivity to new, unsupported devices, or as small as a forked bugfix of a problematic module.
• A user may consume or share collections by interacting with Ansible Galaxy, GitHub, etc.

Tasks

• At a basic level, a task is a the way a user creates "Ansible functions", such as supplying parameters to an Ansible module.
• Tasks are generally used to execute a module with specific arguments; however, there are other more advanced cases for using tasks which are related to plugins and importing other content.
• Each play contains a list of tasks. Tasks are executed in order, one at a time, against all machines matched by the host pattern, before moving on to the next task.

Handlers

• Handlers usually contain targets for notify directives, and are almost always associated with services (i.e., restart or stop).
• In Ansible, a handler is similar to a task, but it runs only if it was notified by a task. A task will fire the notification if Ansible recognizes that the task has changed the state of the system. Handlers will not run if not triggered by a task.
• Several tasks may trigger the same handler and it will run only once. Logically, even if several tasks modify a configuration file and trigger the same handler, the service will only run once and apply all configuration changes.

Variables

• Ansible Variables (vars) are standard key-value pairs which can be simple scalar values (integers, booleans, strings) or complex values (dictionaries/hashes, lists) that can be declared or used across multiple forms of content (e.g., modules, playbooks, etc.).
• In this sense, vars are declared values, not values that are gathered or inferred from the remote system’s current state.

Modules

• Ansible Modules are roughly equivalent to code functions that intend to do one thing well, such as collecting or setting something on a remote device.
• Many Ansible modules strive to be "idempotent" which means that running the module any number of times should result in the same singular outcome. However, depending on the equipment, module and your inputs, this is by no means always true.