Executable Service

This guide demonstrates the basic concepts around creating and executing an executable service within torero. Executable services allow you to run any arbitrary executable file (shell scripts, binaries, compiled programs, etc.) through torero's service management system.

Prerequisites

Before creating an executable service, you need an executable object that points to the binary or interpreter used to run your executable. Review the Executable Object guide to understand how to create executable objects.

Create

torero create service executable will create an executable service. A more detailed guide of all creation options is available there but this guide should help get you started.

The command shown below creates an executable service called backup-script. We are leveraging a repository called scripts-repo and an executable object called bash that would have been previously configured.

>_ torero create service executable backup-script \
--executable-object bash \
--repository scripts-repo \
--filename backup.sh

It is important to understand the structure of the repository and how the flags relate to it.

scripts-repo (git repo)

├── README.md
├── network-scripts
│   └── configure.sh
├── backup.sh
└── deploy.sh

We specified that we want to use scripts-repo via the --repository flag.

Our script backup.sh exists at the root of the repository, which we specified using the --filename flag.

If your executable exists in a subdirectory, you would use the --working-dir flag. For example, to use configure.sh from the network-scripts directory:

>_ torero create service executable network-config \
--executable-object bash \
--repository scripts-repo \
--working-dir network-scripts \
--filename configure.sh

---

Verify Creation

We can view details about the previously created executable service by running the describe service command.

>_ torero describe service backup-script

Output:

Name:              backup-script
Repo Name:         scripts-repo
Working Dir:
File Name:         backup.sh
Decorator:
Arg Format:        --{{.Key}} {{.Value}}
Description:
Tags:
Secrets:
Executable Object: bash

---

Execution

Executing an executable service is straightforward using the run service executable command.

Consider a simple shell script that accepts command-line arguments:

#!/bin/bash

echo "arg1: $1"
echo "arg2: $2"

You can execute this service and pass arguments using the --set flag:

>_ torero run service executable backup-script \
--set target=/data \
--set destination=/backups/data.tar.gz

Output:

Start Time:   2024-01-01T12:00:00Z
End Time:     2024-01-01T12:00:02Z
Elapsed Time: 2.145s
Return Code:  0
Stdout:
arg1: --target
arg2: /data

Stderr:

When you run this command with the --set flags, torero will execute your script with the arguments formatted according to the --arg-format specified during service creation (see the next section for details).

---

Argument Formatting

One of the most powerful features of executable services is the ability to customize how arguments are passed to your executable using the --arg-format flag during service creation.

Default Format

By default, arguments are passed in the format --{{.Key}} {{.Value}}, which means:

>_ torero run service executable my-script --set device=router1 --set port=22

Will execute:

/path/to/executable --device router1 --port 22

Custom Formats

You can customize the argument format to match your executable's expected input:

KEY=VALUE Format

>_ torero create service executable env-setup \
--executable-object bash \
--repository scripts-repo \
--filename setup.sh \
--arg-format "{{.Key}}={{.Value}}"

Running with --set NAME=value --set PORT=8080 will execute:

/bin/bash setup.sh NAME=value PORT=8080

Single Dash Format

>_ torero create service executable legacy-tool \
--executable-object custom-binary \
--repository tools-repo \
--filename process.sh \
--arg-format "-{{.Key}} {{.Value}}"

Running with --set input=data.txt will execute:

/opt/bin/custom-binary -input data.txt

---

Secrets

Secrets can be injected into executable services as environment variables. This is useful for passing sensitive information like API tokens, passwords, or keys without hardcoding them in your scripts.

First, create a secret in torero's secret store:

>_ torero create secret api-token --value "secret-token-value"

Then reference it when creating your service:

>_ torero create service executable api-caller \
--executable-object bash \
--repository scripts-repo \
--filename call-api.sh \
--secret name=api-token,type=env,target=API_TOKEN

Your script can then access the secret as an environment variable:

#!/bin/bash
# call-api.sh

API_ENDPOINT="$1"

curl -H "Authorization: Bearer $API_TOKEN" "$API_ENDPOINT"

You can also inject secrets at runtime using the --set-secret flag:

>_ torero run service executable api-caller \
--set endpoint=https://api.example.com/data \
--set-secret name=api-token,type=env,target=API_TOKEN

---

Complete Example

Let's walk through a complete example of creating and running an executable service.

1. Create the Executable Object

>_ torero create executable-object bash --exec-command /bin/bash

2. Create the Service

>_ torero create service executable deployment-script \
--executable-object bash \
--repository automation-repo \
--working-dir deployment-scripts \
--filename deploy.sh \
--description "Automated deployment script" \
--tag deployment \
--tag production

3. Run the Service

>_ torero run service executable deployment-script \
--set environment=production \
--set version=v2.1.0 \
--set region=us-east-1

The script will receive these arguments formatted according to the service's --arg-format setting.

---

Decorators

It is possible to put restrictions around the inputs that are accepted by an executable service by utilizing decorators. Decorators allow you to:

• Define required and optional input parameters
• Specify parameter types (string, integer, boolean, etc.)
• Add validation rules for inputs
• Provide descriptions and help text for each parameter

For more information on decorators, please refer to this guide.

To use a decorator with an executable service:

>_ torero create service executable my-service \
--executable-object bash \
--repository scripts-repo \
--filename script.sh \
--decorator my-decorator

Users can then view the expected inputs using the --use flag:

>_ torero run service executable my-service --use

---

CLI Reference

Executable Service Create

Executable Service Run

Services Get

Service Describe

Service Delete

Executable Object Documentation