Python Service

This topic demonstrates the basic procedures for creating and executing a Python script service in Itential Automation Gateway (IAG).

Prerequisites

Before you begin, ensure you have:

• A Git repository containing the Python script
• Familiarity with the iagctl create repository command

Create a Python service

Use the command iagctl create service python-script to create a Python script service.

The following example creates a Python script service in IAG called simple-python that uses a previously configured repository called gateway-resources. Specify the source repository in your create command using the --repository flag.

iagctl create service python-script simple-python --repository gateway-resources --working-dir pythonscripts --filename main.py

The gateway-resources repository has the following structure:

├── README.md
├── ansibleplaybooks
├── pythonscripts
│   ├── main.py
│   └── requirements.txt
└── opentofuplans

The Python script exists in a directory called pythonscripts, which is specified in the create command using the --working-dir flag.

Inside the pythonscripts directory there is a script called main.py. You can specify the script in your create command using the --filename flag.

If your Python script requires external libraries, place a requirements.txt file within the working directory. IAG automatically manages the dependencies.

Verify Python script service

You can view details about the Python script service you created by running the describe command. For more information, see iagctl describe.

iagctl describe service simple-python

Output:

Name:        simple-python
Repo Name:   gateway-resources
Working Dir: pythonscripts
FileName:    main.py
Decorator:   
Description: 
Tags:

Execute Python script

You can execute a Python script service in IAG using the iagctl run service python-script command.

Review the contents of main.py in the Python script:

# main.py
from netmiko import ConnectHandler
import argparse

def main():
    parser = argparse.ArgumentParser(description="Netmiko Command Service")
    parser.add_argument('--command', required=True, help="Command to run")
    parser.add_argument('--host', required=True, help="Host to connect to")
    args = parser.parse_args()
    # YOUR EXECUTION CODE GOES BELOW THIS LINE    

    cisco1 = {
        "device_type": "cisco_ios",
        "host": args.host
    }
    with ConnectHandler(**cisco1) as net_connect:
        output = net_connect.send_command(args.command)
    
    print(output)

if __name__ == "__main__":
    main()

This script requires the netmiko library. You specify this in the requirements.txt file located in the working-dir when creating the service.

netmiko==4.3.0

When you execute a Python script using the run python-script command, IAG automatically looks for the requirements.txt file in the working directory that you specified during the creation of the service.

Then, IAG creates a virtual environment with all the dependencies specified in requirements.txt and executes the script within that virtual environment. This allows for easy management of Python dependencies.

The Python script takes in two inputs: command and host. They can be specified using the --set flag.

iagctl run service python-script simple-python --set host=10.0.0.1 --set command="show version"

Output:

Start Time:   2024-01-01T12:00:00Z
End Time:     2024-01-01T12:00:01Z
Elapsed Time: 1.372672s
Return Code: 0
================================================================================
                           System Version Information
================================================================================

...truncated for document

Stderr:

IAG takes the key=values defined in the --set flag and passes them to the Python service.

For this example, the following command is run by IAG on the backend:

<python-executable> main.py --host=10.0.0.1 --command="show version"

Create a basic script with inputs

The most important part of working with a Python script is how to get arguments into the script. A key integration between IAG and a Python service is the ability to read key=value from the command line.

Every Python script that you write should include something that looks like the Python code below. Use this basic example to get started with accepting input arguments:

# main.py
import argparse


def main():
    parser = argparse.ArgumentParser(description="iagctl example")
    parser.add_argument('--name', required=True, help="Name to greet")
    args = parser.parse_args()
    name = args.name
    # YOUR EXECUTION CODE GOES BELOW THIS LINE    

    print(f"Hello, {name}")

if __name__ == "__main__":
    main()

Use pyproject.toml

You can use pyproject.toml files to manage dependencies and build projects. Consider the following
repository layout:

pyproject-repo (git repo)
├── README.md
├── pyproj-example
│   ├── pyproject.toml
│   └── src
│       ├── __init__.py
└──     └── __main__.py

And the following pyproject.toml file:

[build-system]
requires = ["setuptools", "setuptools-scm"]
build-backend = "setuptools.build_meta"

[project]
name = "pyproj-example"
version = "1.0.0"
dependencies = [
  "requests",
]

[project.optional-dependencies]
networking-deps = ["netmiko"]

[project.scripts]
some-script = "src.__main__:main"

[tool.setuptools]
packages = ["src"]

The create service python-script command supports the following flags to specify how it should handle your pyproject.toml file:

• --req-file: The path to the requirements file. This could also be a path deeper than the --working-dir
• --pyproj-script: Defines the script to execute as would be defined in the pyproject.toml
• --pyproj-optional-deps: Specifies optional dependencies defined in the pyproject.toml to install before executing

Given the example above, you can run the following command to create a service that uses pyproject.toml
to install the required dependencies, install the optional dependencies of networking-deps, and build and execute the some-script script at runtime.

iagctl create service python-script simple-toml --repository pyproject-repo --working-dir pyproj-example --pyproj-script some-script  --req-file pyproject.toml --pyproj-optional-deps networking-deps

When you execute this script, IAG builds a virtual environment with both the required dependencies and optional networking-deps dependencies. IAG also builds the some-script scriptusing the build system defined in the pyproject.toml. In this case, it's setup-tools. Finally, IAG executes the script on the CLI with syntax similar to what is shown below:

/path/to/venv/bin/some-script

Learn more

For more information on the following related operations, see the Command Reference.

• iagctl create service python-script

• iagctl run service python-script

• iagctl get services

• iagctl describe service

• iagctl delete service