awetomate/itential-iag-sdk

Lightweight SDK to simplify interacting with the Itential automation gateway API.

itential-iag-sdk

Lightweight SDK to simplify the process of interacting with the Itential Automation Gateway API.

This is an beta release. Please ensure the package works as expected in your environment before using it in production as there may still be bugs. This package uses Pydantic models to validate the input parameters for each API call.

This package was written for Itential Automation Gateway 2023.1.

Getting Started

Make sure you have a supported version of Python installed and then create and activate a virtual environment:

python -m venv venv

source /venv/bin/activate

You can install the iag_sdk from Pypi as follows:

pip install iag-sdk

Or you can install it from source as follows:

git clone https://github.com/awetomate/itential-iag-sdk.git
cd itential-iag-sdk
python -m pip install -r requirements.txt
python -m pip install -e .

Usage

from iag_sdk import Iag

username = "admin@itential"
password = "your_password"
host = "your_server"

iag = Iag(host=host, username=username, password=password, verify=False)

iag.accounts.get_account(name="admin@itential")
#{'email': 'admin@itential.com', 'firstname': None, 'lastname': None, 'username': 'admin@itential'}

iag_sdk uses the following default values. You can overwrite any of them during instantiation:

class Iag(ClientBase):
    def __init__(
        self,
        host: str,
        username: str,
        password: str,
        base_url: Optional[str] = "/api/v2.0",
        protocol: Optional[str] = "http",
        port: Optional[Union[int, str]] = 8083,
        verify: Optional[bool] = True,
    ) -> None:

The iag_sdk methods are grouped in the same manner as in Itential's API documentation. I.e. all API calls related to collections are available under iag.collections. and all API calls related to (Ansible) devices are available under iag.devices.

Examples

# get the server status
iag.system.get_status()

# list the first 10 Ansible devices that have 'SW' in their hostname
iag.devices.get_devices(limit=10, filter='contains({"name": "SW"})')

# get a specific Ansible device
iag.devices.get_device(name="device1")

# check the state for a specific Ansible device
iag.devices.get_device_state(name="device1")

Work with Ansible collections:

# list all collections
iag.collections.get_collections()

# get one collection
iag.collections.get_collection(collection_name="cisco.asa")

# get modules for a specific collection
iag.collections.get_modules(collection_name="cisco.asa")

# refresh collections / perform a collection discovery
iag.collections.refresh()

Work with Netmiko:

# IAG native
iag.netmiko.execute_send_command_native(
    host="device1", 
    command_string="show version"
)

# legacy
iag.netmiko.execute_send_command_legacy(
    host="device1", 
    commands=["show version"], 
    device_type="cisco_ftd", 
    username="your_username", 
    password="your_password", 
    port=22
)

The all-purpose 'query' method

The iag_sdk includes a generic 'query' method that can be used for every Itential automation gateway API call. In fact, all the other methods ultimately use the generic 'query' method to send calls to AG.

The query method by default sends GET requests without any data or parameters. However, you can use the 'query' method to send get, delete, post, put, and patch requests by changing the 'method' argument. You can also send data by various means (params, data, jsonbody).

The generic 'query' method potentially could come in handy to overcome differences in the API between automation gateway versions. If any of the existing methods don't work with your AG version, try the generic 'query' method as a fallback.

The 'query' method takes the following arguments:

argument	description
endpoint	Itential IAG API endpoint. E.g. /devices.
method	Optional. API method: get (default),post,put,patch,delete.
data	Optional. A dictionary to send as the body.
jsonbody	Optional. A JSON object to send as the body.
params	Optional. A dictionary to send as URL parameters.

Basic GET call using 'query'

# get the server status
iag.query("/status")
# or to be more explicit
iag.query("/status", method="get")

# get a specific collection
collection_name = "cisco.asa"
iag.query(f"collections/{collection_name}")
# or define the endpoint statically
iag.query("collections/cisco.asa")

# list the first 10 Ansible devices that have 'SW' in their hostname
iag.query("/devices", params={"limit": 10, "filter": 'contains({"name":"SW"})'})

Basic POST call using 'query'

iag.query("/collections/refresh", method="post")

iag.query("/netmiko/send_command/execute", method="post", jsonbody={"host": "networkdevice", "command_string": "show version"})

List of all modules and methods

accounts

methods	description
add_account	Add a new user account.
confirm_eula	Confirm EULA for account.
delete_account	Delete a user account.
get_account	Get information for a user account.
get_accounts	Get a list of user accounts.
update_account	Update details of a user account.
update_password	Update user login credentials.

collections

methods	description
add_collection	Install an Ansible collection from a Galaxy server or from a tarball.
delete_module_schema	Remove a schema for a module in the Ansible collection.
delete_role_schema	Remove a schema for a role in the Ansible collection.
execute_module	Execute a module contained within the Ansible collection.
execute_role	Execute a role which is contained within the Ansible collection.
get_collection	Get details for an Ansible collection.
get_collections	Get list of installed Ansible collections.
get_module	Get details for a module in the Ansible collection.
get_module_history	Get execution log events for an Ansible collection module.
get_module_schema	Get the schema for a module in the Ansible collection.
get_modules	Get module list for an Ansible collection.
get_role	Get details for a role in the Ansible collection.
get_role_history	Get execution log events for an Ansible collection role.
get_role_schema	Get the schema for a role in the Ansible collection.
get_roles	Get role list for an Ansible collection.
refresh	Perform Ansible collection discovery and update internal cache.
update_module_schema	Update/Insert a schema document for module in the Ansible collection.
update_role_schema	Update/Insert a schema document for role in the Ansible collection.

config

methods	description
get_config	Fetch config value from AG server database.
update_config	Update config to AG server database.

devices

methods	description
add_device	Add a new device to Ansible inventory.
delete_device	Delete a device from Ansible inventory.
get_device	Get information for an Ansible device.
get_device_state	Get the connectivity state for an Ansible device.
get_device_variable	Get the value of a connection variable for an Ansible device.
get_device_variables	Get the connection variables for an Ansible device.
get_devices	Get a list of Ansible devices.
update_device	Merge or replace the variables for a device in the Ansible inventory.

groups

methods	description
add_group	Add a new Ansible device group.
add_group_children	Add new child groups to an Ansible device group.
add_group_devices	Add new devices to an Ansible device group.
delete_group	Delete an Ansible device group.
delete_group_child	Delete a child group from an Ansible device group.
delete_group_device	Delete a device from an Ansible device group.
get_group	Get information for an Ansible device group.
get_group_children	Get a list of child groups for an Ansible device group.
get_group_devices	Get the devices for an Ansible device group.
get_group_variable	Get the contents of a variable for an Ansible device group.
get_group_variables	Get the variables for an Ansible device group.
get_groups	Get a list of Ansible device groups.
update_group	Update the variables in an Ansbile device group.

http_requests

methods	description
execute_request	Send an HTTP/1.1 request to an inventory device.
get_request_history	Get execution log events for an HTTP request.
get_request_schema	Get the json schema for http_requests' request endpoint.

inventory

methods	description
add_http_requests_device	Create a device in the http_requests inventory.
add_netconf_device	Create a device in the netconf inventory.
add_netmiko_device	Create a device in the netmiko inventory
delete_http_requests_device	Delete a device from the http_requests inventory.
delete_netconf_device	Delete a device from the netconf inventory.
delete_netmiko_device	Delete a device from the netmiko inventory.
get_http_requests_device	Get information for a device in the http_requests inventory.
get_http_requests_device_group	Get information for a device group in the http_requests inventory.
get_http_requests_device_group_children	Get a list of child groups in the http_requests inventory device group.
get_http_requests_device_group_devices	Get a list of devices in the http_requests inventory device group.
get_http_requests_device_groups	Get a list of device groups in http_requests inventory.
get_http_requests_devices	Get a list of devices in the http_requests inventory.
get_netconf_device	Get information for a device in the netconf inventory.
get_netconf_device_group	Get information for a device group in the netconf inventory.
get_netconf_device_group_children	Get a list of child groups in the netconf inventory device group.
get_netconf_device_group_devices	Get a list of devices in the netconf inventory device group.
get_netconf_device_groups	Get a list of device groups in netconf inventory.
get_netconf_devices	Get a list of devices in the netconf inventory.
get_netmiko_device	Get information for a device in the netmiko inventory.
get_netmiko_device_group	Get information for a device group in the netmiko inventory.
get_netmiko_device_group_children	Get a list of child groups in the netmiko inventory device group.
get_netmiko_device_group_devices	Get a list of devices in the netmiko inventory device group.
get_netmiko_device_groups	Get a list of device groups in netmiko inventory.
get_netmiko_devices	Get a list of devices in the netmiko inventory.
refresh	Perform external inventory discovery and update internal cache.
update_http_requests_device	Update a device in the http_requests inventory.
update_netconf_device	Update variables for a device in the netconf inventory.
update_netmiko_device	Update a device in the netmiko inventory.

ldap

methods	description
test_bind	test LDAP connection

modules

methods	description
delete_module_schema	Remove an Ansible module schema.
execute_module	Execute an Ansible module.
get_module	Get information for an Ansible module.
get_module_history	Get execution log events for an Ansible module.
get_module_schema	Get the schema for an Ansible module.
get_modules	Get a list of Ansible modules.
refresh	Perform Ansible module discovery and update internal cache.
update_module_schema	Update/Insert an Ansible module schema document.

netconf

netconf
execute_get_config	Retrieve configuration from a device using the NETCONF protocol
execute_rpc	Execute proprietary operations on a device using the NETCONF protocol.
execute_set_config	Configure a device using the NETCONF protocol
get_history	Get execution log events for Netconf command.

netmiko

methods	description
execute_send_command_legacy	Wrapper of netmiko send_command
execute_send_command_native	IAG Native Netmiko send_command.
execute_send_config_set_legacy	Wrapper of netmiko send_config_set
execute_send_config_set_native	IAG Native Netmiko send_config_set.
get_command_schema	Get IAG Native Netmiko command schema.
get_send_command_history	Get execution log events for the Netmiko send_command.
get_send_config_set_history	Get execution log events for Netmiko send_config_set.

nornir

methods	description
delete_module_schema	Remove a Nornir module schema.
execute_module	Execute a Nornir module.
get_module	Get Nornir module information.
get_module_history	Get execution log events for a Nornir module.
get_module_schema	Get the schema for a Nornir module.
get_modules	Get a list of Nornir modules.
refresh	Perform Nornir module discovery and update internal cache.
update_module_schema	Update/Insert a Nornir module schema document.

password_reset

methods	description
reset_password	Reset password for user on the AG server.
update_change_flag	Update the password change flag to false on the AG server.
update_password	Update password for user on the AG server.
update_security_questions	Update security questions and answers for user on the AG server.
validate_password_change	Validate if password is changed in the AG server.

playbooks

methods	description
delete_playbook_schema	Remove an Ansible playbook schema.
execute_playbook	Execute an Ansible playbook.
get_playbook	Get information for an Ansible playbook.
get_playbook_schema	Get the schema for an Ansible playbook.
get_playbooks	Get a list of Ansible playbooks.
get_playook_history	Get execution log events for an Ansible playbook.
refresh	Perform Ansible playbook discovery and update internal cache.
update_playbook_schema	Update/Insert an Ansible playbook schema document.

pronghorn

methods	description
get_pronghorn	Get pronghorn.json for the AG server.

rbac

methods	description
add_group	Add a new RBAC group
add_group_roles	Add new roles to the RBAC group.
add_group_users	Add new users to the RBAC group.
delete_group	Delete an RBAC group.
delete_group_role	Delete a role from the RBAC group.
delete_group_user	Delete a user from the RBAC group.
get_group	Get information for an RBAC group.
get_group_roles	Get roles for an RBAC group.
get_group_users	Get users for an RBAC group.
get_groups	Get a list of RBAC groups.
get_role	Get information for an RBAC role.
get_roles	Get a list of RBAC roles.
get_user_groups	Get RBAC group information for a user.
get_user_roles	Get RBAC role information for a user.
update_group	Update an RBAC group.

roles

methods	description
delete_role_schema	Remove an Ansible role schema.
execute_role	Execute an Ansible role.
get_role	Get information for an Ansible role.
get_role_history	Get execution log events for an Ansible role.
get_role_schema	Get the schema for an Ansible role.
get_roles	Get a list of Ansible roles.
refresh	Perform Ansible role discovery and update internal cache.
update_role_schema	Update/Insert an Ansible role schema document.

scripts

methods	description
delete_script_schema	Remove a script schema.
execute_script	Execute a script.
get_script	Get script information.
get_script_history	Get execution log events for a script.
get_script_schema	Get the schema for a script.
get_scripts	Get a list of scripts.
refresh	Perform script discovery and update internal cache.
update_script_schema	Update/Insert a script schema document.

secrets

methods	description
add_secret	Add a new Hashicorp Vault secret.
delete_secret	Delete a Hashicorp Vault secret.
get_secret	Get a list of Hashicorp Vault secrets.
update_secret	Update a Hashicorpy Vault secret.

security_questions

methods	description
get_security_questions	Get security questions for the AG server.
get_security_questions_user	Get security questions for email id on the AG server.
validate_security_answers_user	Validate security answers for email id on the AG server.

system

methods	description
get_audit_log	Get execution history payload.
get_audit_logs	Retrieve execution audit log persisted in the database.
get_health	Determine if AG server is up and running (/poll).
get_openapi_spec	Get the current OpenAPI spec from the running instance of IAG
get_status	Get the AG server status (version, ansible version, etc).

terraforms

methods	description
delete_module_schema	Remove a Terraform module schema.
execute_terraform_apply	Apply the configuration of a Terraform module
execute_terraform_destroy	Destroy the resources of a Terraform module.
execute_terraform_init	Initialize the providers of a Terraform module.
execute_terraform_plan	Plan the execution of a Terraform module.
execute_terraform_validate	Validate the configuration of a Terraform module.
get_module	Get information on a Terraform module.
get_module_history	Get execution log events for a Terraform module.
get_module_schema	Get the schema for a Terraform module.
get_modules	Get list of Terraform modules.
refresh	Perform Terraform discovery and update internal cache.
update_module_schema	Update/Insert a Terraform schema document.

user_schema

methods	description
delete_schema	Remove a user schema.
update_schema	Update/Insert a user schema document.