Runbooks

A runbook is a task defined once and run from a form. The form asks only for the inputs the task needs, such as a node group or a service name. Nobody types raw Salt commands to run it.

To open runbooks: choose Automation > Runbooks.

Run a runbook#

1. Find the runbook card and choose Run….
2. Fill in the form. Each field shows its default.
3. Choose Run now as your name.
4. Follow the run under Recent runs. Open log to see each machine's result as it finishes and a closing line such as "result: 48 of 50 machine(s) succeeded; failed: web-07, web-12". Ansible playbook runs end with Ansible's own PLAY RECAP.

What happens when you run it:

• Gardience checks that your role allows the runbook's Salt function on every target node. Your rights are read at sign-in.
• If the target node group is outside its change window, or any target node belongs to a group whose window is closed, the whole run is held until the window opens. The run's status is "held".
• Nodes that do not answer a quick check are held as offline and run when they reconnect. The run goes ahead on the nodes that answered.
• Locked nodes are skipped, and the log says so.
• Read-only runbooks, such as Health check, are never held.

The job runs under Gardience's automation identity, and the audit log records you as the person who asked. A run ends as success, failed or held.

To run a runbook on a timetable, choose Schedule… on its card. See Schedules.

Built-in runbooks#

A hidden built-in runbook, Run an uploaded Ansible playbook, runs playbooks uploaded with the gdn command line. It does not appear on this page. See Ansible playbooks.

Built-in runbooks cannot be deleted. They are updated with each Gardience release.

Inputs#

Every input is checked before anything runs:

• A required input cannot be empty.
• A select input must be one of its listed options.
• A nodegroup input must name an existing node group.
• A number input must be a whole number.
• A text input must match the runbook's allowed pattern. If the runbook does not set one, letters, digits, spaces and the characters _ . , : @ / + = - are allowed, up to 200 characters.

An input that fails a check stops the run with a message that names the field.

Create a custom runbook#

Only Gardience admins can create or delete runbooks.

1. On Automation > Runbooks, go to New runbook.

2. Fill in the fields:

   • Name: what people see on the card. Saving a runbook with the same name replaces the earlier one.
   • Salt function: the function to run, written as module.function, for example service.restart.
   • Description: what it does and when to use it.
   • Arguments: the function's arguments, separated by commas. Write {{field}} to insert a form value, for example {{service}}.
   • Target: who it runs on. The default {{nodegroup}} uses the node group picked in the form.
   • Target type: nodegroup, glob, list or compound.

   • Form fields: one field per line, in this format:

     Copy

     name | label | type | options | default

     The type is text, select or nodegroup. For select, list the options separated by commas.

3. Choose Save runbook. The page reloads with the new runbook card.

Example: a runbook that restarts IIS on a chosen group.

Name:          Restart IIS on web servers
Salt function: service.restart
Arguments:     {{service}}
Target:        {{nodegroup}}
Target type:   nodegroup
Form fields:
nodegroup | Node group | nodegroup | | Windows
service | Service name | text | | W3SVC

To delete a custom runbook, choose Delete on its card. Any schedule that runs it is turned off. Saving a runbook is recorded in the audit log.

Run a runbook from the command line#

The gdn command line can list and run runbooks with an API key that has the Operate scope:

./gdn runbooks
./gdn runbook restart-service -e nodegroup=Windows -e service=Spooler

If the key requires approval, the run waits for a second person in Automation > Workflows and approvals.

Related#

• Workflows and approvals
• Schedules
• Held work
• Ansible playbooks