Validate and limit service inputs with decorators

This topic describes how you can use decorators within IAG to limit the inputs passed into a service that you execute using the iagctl run service command.

A decorator defines the inputs a service expects: which parameters it accepts, what type they must be, and which are required. When a user runs a service through a workflow, the decorator validates that the correct inputs were provided before execution begins. A single decorator can be shared across multiple services that accept the same inputs, reducing duplication. Think of a decorator as a form definition that you attach to one or more services.

Decorators in playbooks

To best understand decorators, consider an Ansible Playbook service called simple-ansible that uses the following playbook.

1 ---
2 - name: A Simple Hello World Example
3   hosts: localhost
4   gather_facts: no
5   tasks:
6     - name: Just Say Hello
7       debug:
8         msg: "Hello Mr. gateway this is from '{{ caller }}'"

Notice that the example playbook takes in a single variable called caller. When running the service, you can use the --set flag to pass a value for caller to the playbook.

$ iagctl run ansible-playbook simple-ansible --set caller=documentation

JSON Schema in decorators

Suppose that you want to limit the types of inputs that can pass to the playbook using the --set flag. Decorators allow you to limit the available parameters by using defined JSON Schema standards.

Consider the example JSON Schema shown below that limits the available inputs to a key of caller with values of documentation or learner.

1 {
2   "$id": "root",
3   "$schema": "http://json-schema.org/draft-07/schema#",
4   "type": "object",
5   "properties": {
6     "caller": {
7       "type": "string",
8       "enum": ["documentation", "learner"]
9     }
10   },
11   "required": [
12     "caller"
13   ],
14   "additionalProperties": false
15 }

You can explore all available options within JSON Schema by referencing the official spec.

Create a decorator resource

First, save the JSON schema above as a file called simple-deco.json.

Next, create a decorator resource called simple-deco within IAG using the json schema file that you created in the previous step.

$ iagctl create decorator simple-deco --schema @./simple-deco.json

Create a gateway service with decorators

Once you create the decorator resource, create a service that uses it. The following example creates an Ansible Playbook service with the simple-deco decorator.

$ iagctl create ansible-playbook ansible-with-deco --repository gateway-resources --working-dir ansibleplaybook --playbook hello-world.yml --decorator simple-deco

$ Output:
$ 
$ Successfully created the Ansible playbook(s)
$ Name:        ansible-with-deco
$ Repo Name:   gateway-resources
$ Working Dir: ansibleplaybook
$ Playbook(s): hello-world.yml
$ Decorator:   simple-deco
$ Description:
$ Tags:
$ Runtime Arguments:

Set the --use flag when using the service run command to get basic, high-level information about the decorator.

$ iagctl run service ansible-playbook ansible-with-deco --use

$ Output:
$ 
$ Decoration Usage:
$ -----------------------------
$ The following keys can be set on the command line via the set command.
$ 
$ +----------+--------+-------------+--------------------+
$ |   NAME   |  TYPE  | DESCRIPTION |      EXAMPLE       |
$ +----------+--------+-------------+--------------------+
$ | caller** | string |             | --set caller=value |
$ +----------+--------+-------------+--------------------+
$ 
$ ** is Required

Successful decoration

When you pass in a valid value for caller and run the Ansible playbook service, the playbook succeeds.

$ iagctl run service ansible-playbook ansible-with-deco --set caller=documentation

Decoration error

If you try to pass in a value for caller that is not documentation or learner, you receive an error.

$ iagctl run service ansible-playbook ansible-with-deco --set caller=someWrongInput

$ Output:
$ 
$ Error: failed to run ansible playbook 'ansible-with-deco': decoration errors have been encountered: should be one of ["documentation", "learner"] /caller

Additionally, if you try to set any value for a key that is not caller, an error returns.

$ iagctl run service ansible-playbook ansible-with-deco --set caller=documentation --set someBadKey=value

$ Output:
$ 
$ Error: failed to run ansible playbook 'ansible-with-deco': decoration errors have been encountered: extra input found someBadKey

Learn more

For more information on decorator operations, see the following iagctl CLI commands: