Runbooks Management
Relevant source files
The following files were used as context for generating this wiki page:
Runbooks Management is a core feature of the Hoop project designed to automate operational tasks by sourcing executable scripts directly from Git repositories. These runbooks are treated as templates, allowing users to provide dynamic parameters at execution time while maintaining strict access control through rules that bind specific runbooks to authorized connections and user groups.
The system supports a variety of protocols (SSH, HTTPS) for Git integration and provides a sophisticated template engine. This engine parses script files to generate UI metadata, ensuring that required inputs are validated before a runbook is dispatched to a remote agent for execution.
Sources: gateway/api/runbooks/runbooksV2.go:500-530, client/cmd/runbooks/runbooks.go:50-70, common/runbooks/templates.go
System Architecture
The Runbooks Management system operates as a bridge between Git providers and the Hoop gateway. The gateway acts as the orchestrator, responsible for repository synchronization, template parsing, and permission enforcement.
Component Relationship
The following diagram illustrates how Runbooks interact with other project components:
This architecture ensures that scripts are always version-controlled in Git while the Gateway provides a secure execution layer.
Sources: gateway/api/runbooks/runbooksV2.go, gateway/api/runbooks/helpers.go:30-80
Runbook Templates and Parsing
Runbooks are script files (e.g., .sh, .py, .sql) containing Go-style template placeholders. The common/runbooks package implements a specialized parser that extracts metadata from these placeholders to define the required input for the runbook.
Template Metadata Attributes
A template placeholder like {{ .account_id | description "Account ID" | required }} is parsed into a metadata object. Supported attributes include:
| Attribute | Description | Data Type |
|---|---|---|
type | The input field type (text, select, file, etc.) | string |
required | Whether the parameter is mandatory | boolean |
description | Help text for the UI | string |
default | Default value if none provided | string |
options | List of values for 'select' type | string array |
order | Positioning in the UI | integer |
Sources: common/runbooks/templates.go:90-135, gateway/api/openapi/openapiv3.json:Runbook
Parsing Logic Flow
Runbook Rules and Permissions
Access control for runbooks is managed through RunbookRules. These rules define which user groups can execute specific runbooks against designated connections.
Rule Evaluation
The gateway evaluates rules by checking intersections between:
- The user's assigned groups.
- The target connection name.
- The runbook file path and repository.
If no rules exist for an organization, runbooks are accessible to all by default (subject to standard connection permissions). If rules are present, they act as an explicit allow-list.
Execution Pipeline
The execution of a runbook involves cloning the repository (if not cached), parsing the template with provided parameters, and creating a session for execution.
Execution Steps
- Request Validation: The API validates the correlation ID, metadata, and user permissions.
- Repository Fetch: The gateway checks the in-memory cache (5-minute TTL). If missing/expired, it clones the repository.
- Template Execution: The template is rendered using the provided
Parameters. - Session Creation: A new session is persisted in the database with the
originset torunbooks. - Agent Dispatch: The final script is sent to the remote agent via the client execution service.
Sources: gateway/api/runbooks/runbooksV2.go:280-450, gateway/api/runbooks/helpers.go:15-30
CLI Management
The Hoop CLI provides subcommands for managing the lifecycle of runbooks without using the web interface.
Key CLI Commands
| Command | Purpose | Usage Example |
|---|---|---|
lint | Validates runbook syntax and parameters locally | hoop runbooks lint ./file.runbook.sh |
list | Lists available runbooks across all repos | hoop runbooks list --role my-db |
create | Commits a new runbook file to a git repo | hoop runbooks create --path ops/task.runbook.sh --content-file script.sh |
Sources: client/cmd/runbooks/runbooks.go:40-150
Configuration Data Model
The configuration stores credentials and endpoint information for one or more Git repositories per organization.
Repository Configuration Schema
Summary
Runbooks Management in Hoop provides a robust framework for Git-ops based automation. By combining Go template flexibility with centralized security rules, it allows organizations to standardize operational tasks. The system's use of in-memory caching for Git objects and strict validation via its template engine ensures both performance and safety during execution.