Using decorators

This guide describes how decorators can be used within IAG5 to limit the inputs that can be passed into a service that is executed using the run command.

Decorations in Playbooks

To best understand decorators, let's consider an Ansible Playbook service called simple-ansible that utilizes the following playbook.

---
- name: A Simple Hello World Example
  hosts: localhost
  gather_facts: no
  tasks:
    - name: Just Say Hello
      debug:
        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 Decorations

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 will limit the available inputs to be a key of caller with values of documentation or learner.

{
  "$id": "root",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "caller": {
      "type": "string",
      "enum": ["documentation", "learner"]
    }
  },
  "required": [
    "caller"
  ],
  "additionalProperties": false
}

Creating a Decorator Resource

First, save the JSON schema above as a file. You can simply call it simple-deco.json.

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

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

Creating a Decoration Service

Once the decorator resource is created, create a service that utilizes it. See the syntax below to create an Ansible Playbook Service with your new 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 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

Decoration Success

Next, when you pass in a value for caller and run the Ansible playbook service, you will see the playbook succeeds.

iagctl run 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 will receive an error.

iagctl run 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 will return.

iagctl run 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 the following related operations, see the Command Reference.

• iagctl create decorator

• iagctl get decorators

• iagctl describe decorator

• iagctl delete decorator