Decorators

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

To best understand decorators, let's first 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. torero this is from '{{ caller }}'"⏎

We notice that our particular playbook takes in a single variable called caller. When running the service we can use the --set flag to pass a value for caller to the playbook.

>_ torero run ansible-playbook simple-ansible --set caller=documentation

Suppose that we wanted to limit the types of inputs we can pass to the playbook using the --set flag. Decorators allow us to limit the available parameters using the JSON Schema standard. 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
}

First, we would want to save our JSON schema as a file. We'll call it simple-deco.json.

Next, we will create the decorator resource called simple-deco within torero using our new file as shown below.

>_ torero create decorator simple-deco --schema @./simple-deco.json

Now that we have a decorator resource created, we can create a service that utilizes it. See the syntax below that would create an Ansible Playbook Service with our new simple-deco decorator.

>_ torero create service ansible-playbook ansible-with-deco --repository torero-resources --working-dir ansibleplaybook --playbook hello-world.yml --decorator simple-deco

Output:

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

We can get some basic, high level information about the decorator with the --use flag when using any service's run command.

>_ torero 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

Now, we can pass in a value for caller when running the Ansible playbook service as we normally would and see the playbook succeed.

>_ torero run ansible-playbook ansible-with-deco --set caller=documentation

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

>_ torero 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 we try to set any value for a key, that is not caller, we also receive an error

>_ torero 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

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

---

CLI Reference

Decorator Create

Decorators Get

Decorator Describe

Decorator Delete