iagctl create service python-script
Create a new Python script service.
The iagctl create service python-script command creates a Python script service in the gateway data store. You can then run the service with the iagctl run command. For more information, see Create gateway services.
Consider a Python script in a repository called example-repo with the following directory layout:
To create a service from the script in the interface-scripts directory, specify the repository with --repository, the subdirectory with --working-dir, and the script file with --filename.
Prerequisites
Before you create a Python script service, you need a repository that contains your script.
Syntax
Specify either --filename or --pyproj-script, but not both.
Usage notes
Dependencies
Gateway installs your script’s dependencies into a virtual environment and runs the script within that environment. By default, Gateway looks for a requirements.txt file in the --working-dir.
To use a different requirements file, specify its path relative to the --working-dir with the --req-file flag. The path must point to either a requirements.txt file or a pyproject.toml file, and it can point to a subdirectory of the working directory.
To change the default requirements file for all Python script services on a gateway, set the GATEWAY_PYTHON_SCRIPT_REQUIREMENTS_FILE configuration variable. The --req-file flag overrides this default. If a service uses --pyproj-script or --pyproj-optional-deps without --req-file, Gateway reads the requirements file path from this variable.
Projects that use pyproject.toml
Gateway 5.1+If your script is packaged as a Python project with a pyproject.toml file, Gateway can install the project and its dependencies, then run an entry point that the project defines. Use the following flags:
--req-file <path>: The path to thepyproject.tomlfile, relative to the--working-dir. Gateway installs the dependencies listed in the[project]table’sdependencieskey. If you don’t set this flag, Gateway uses the value ofGATEWAY_PYTHON_SCRIPT_REQUIREMENTS_FILE.--pyproj-script <script-name>: Runs the named entry point from the[project.scripts]table.--pyproj-optional-deps <group>: Also installs an optional dependency group from the[project.optional-dependencies]table. To install more than one group, repeat the flag.
Set --req-file explicitly on each service that uses pyproject.toml, instead of relying on the GATEWAY_PYTHON_SCRIPT_REQUIREMENTS_FILE default. This ensures Gateway reads the correct file even if the gateway’s default changes.
When you run the service, Gateway creates a virtual environment, runs pip3 install in it to install the project and its dependencies, then runs the entry point from the virtual environment:
You can’t use --pyproj-script and --filename in the same command. If you specify both, Gateway rejects the command and returns an error.
Gateway doesn’t check the project’s requires-python value itself. Instead, pip enforces it against the virtual environment’s Python interpreter.
Services that use pyproject.toml support the same features as other Python script services. Runtime arguments that you pass with --set reach the entry point in the same --key=value format, and decorators, file-backed properties, environment variables, secrets, and dependency registries all work the same way.
The [build-system] table is optional, and Gateway doesn’t restrict which build backend a project uses.
For a complete example, see Create a service from a pyproject.toml project.
Environment variables
Use the --env flag to set environment variables that the gateway applies at runtime. Specify each variable as a key=value pair.
Decorators
You can attach a decorator to the service for input validation at runtime with the --decorator flag. For more information, see iagctl create decorator.
If a property’s value is too large to pass safely as a CLI argument, mark it as file-backed in the decorator schema so Gateway writes it to a temporary file and passes your script an environment variable instead. For more information, see Pass large values as files in Python script services.
File-backed properties are supported for Python script services only.
Secrets
Use the --secret flag to inject a secret from the gateway secret store into the service at runtime. The flag’s value has three comma-separated parts:
name: The name of the secret in the gateway secret store.type: The type of injection. Onlyenv, which injects the secret as an environment variable, is currently available.target: The name of the environment variable that receives the secret.
For example, --secret name=my-secret,type=env,target=PASSWORD. For more information, see Inject secrets into services.
Dependency registries
Use the --registry flag to pull the service’s dependencies from a specific PyPI registry when the service runs. For more information, see Configure dependency registries.
Python interpreter
Use the --executable-object flag to run the script with a specific Python interpreter on execution nodes. The flag takes the name of an executable object resource. For more information, see Use executable objects with gateway services.
Runtime arguments
For information on how Python scripts read arguments passed at runtime, see iagctl run service python-script.
Examples
Create a basic Python script service
The following example creates a service called my-python-service where the script main.py is at the root of the my-repo repository:
Create a Python script service with all options
The following example creates a service that specifies a working directory, a decorator, environment variables, a secret, and metadata:
Create a Python script service that uses a secret
The following example creates a service that injects a secret called my-secret from the gateway secret store into an environment variable called PASSWORD:
Create a service from a pyproject.toml project
Consider a repository called pyproject-repo with the following directory layout:
The pyproject.toml file defines one required dependency, an optional dependency group called networking-deps, and an entry point called some-script:
The following example creates a service called simple-toml that installs the required dependencies and the networking-deps group, then runs the some-script entry point:
When you run the service, Gateway builds a virtual environment that contains requests and netmiko, builds the project with setuptools, and runs /path/to/venv/bin/some-script.