create decorator

Create a new decorator

Synopsis

Create

The command will create a decorator in torero's data store. Decorators can be attached to services when they are created and allow us to validate any data that is passed into a service when executed via the run command.

Decorators utilize JSON Schema to actually perform input validation. Consider a torero service that takes in two inputs: interface and device_type. We can create the following JSON schema document to validate those inputs

{
  "$id": "root",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "interface": {
      "type": "string",
      "description": "The interface to update"
    },
    "device_type": {
      "type": "string",
      "description": "The type of device",
      "enum": ["ios", "eos", "nxos"]
    }
  },
  "required": [
    "interface",
    "device_type",
    "password"
  ],
  "additionalProperties": false
}

Later, when we create a new service, our decorator can be specified. The decorator can then validate that both interface and device_type were correctly passed in using the --set flag at runtime like shown below.

>_ torero run service pythonscript example-service-with-deco \
--set interface=1/1/1 \
--set device_type=eos

If any issues are found with the incoming data, they will be reported back to the user as an error.

Specifying Properties

Each input to your service will exist within the properties object of the JSON Schema document. Pay special attention to the following fields and how they are used within torero.

type - This is the type of data that you are passing into your service. Can be one of the following - string, number, integer, object, array, boolean, null

enum - Denotes a limited set of values that will be accepted.

Many other validations can be performed and are available on JSON Schema's website: https://json-schema.org/draft/2020-12/json-schema-validation.

Specifying Secrets

You can specify that a secret from torero's secret store should be injected into a service when executed using the custom annotations x-itential-secret-type and x-itential-secret-target. A decorator that requests a value called password would resemble what is shown below.

{
  "$id": "root",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "password": {
      "type": "string",
      "x-itential-secret-type": "env",
      "x-itential-secret-target": "ENV_VAR_NAME"
    }
  },
  "required": [
    "password"
  ],
  "additionalProperties": false
}

The value that is given for password will be the name of the secret in torero's secret store. x-itential-secret-type must be set to env as it denotes that the password will be injected into the service as an environment variable when executed. Environment variables are currently the only secret type available. x-itential-secret-target denotes that the name of the environment variable to be injected when the service is executed.

You would specify the value for the password using the --set flag at runtime as you normally would. E.g.

>_ torero run service pythonscript service-with-secret-deco \
--set password=name-of-secret-in-secret-store

For more information on creating secrets see torero create secret -h

torero create decorator <decorator-name> --schema <string> [flags]

Examples

Create A Decorator Via a JSON Schema File

Consider a JSON Schema document called my_decorator.json. We can create a decorator based off of this file using the syntax shown below.

>_ torero create decorator my-decorator \
--schema @my_decorator.json

A schema file formatted in JSON would be typical, but YAML formatting is also accepted.

Create A Decorator Via Direct JSON

We can also create a decorator by specifying the contents of a JSON Schema document directly into the CLI. Only JSON is accepted here.

>_ torero create decorator my-decorator \
--schema '{"$id":"root","$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"interface":{"type":"string"}}}'

Options

      --description string   A brief description of the decorator
  -h, --help                 help for decorator
      --schema string        The schema of the decorator. This can be inline json or can reference a file by
                             prefixing '@'.
      --tag stringArray      Metadata tag(s) to associate with the decorator

Options inherited from parent commands

      --config string   Specify the path to the configuration file
      --raw             Displays the result of the command in its raw format
      --verbose         Enable verbose output