Orchestrator¶
Help command
> csm-orc run --help
Usage: csm-orc run [OPTIONS] TEMPLATE
Runs the given TEMPLATE file
Commands are run as subprocess using bash -c "<command> <arguments>".
In case you are in a python venv, the venv is activated before any command is run.
╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ * TEMPLATE FILE [required] │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ OPTIONS ────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --dry-run/--no-dry-run -n Use dry-run mode │
│ ENV: DRY_RUN │
│ DEFAULT: no-dry-run │
│ --display-env/--no-display-env List all required environment variables and their documentation │
│ ENV: DISPLAY_ENVIRONMENT │
│ DEFAULT: no-display-env │
│ --gen-env-target PATH Generate a .env file with all env vars to be filed when display-env │
│ is called │
│ ENV: GENERATE_ENVIRONMENT │
│ --skip-step STEP_ID Define a list of steps to be skipped during this run │
│ ENV: CSM_SKIP_STEPS │
│ --validate-only/--no-validate-only Run only a sematic validation of the orchestrator file │
│ ENV: CSM_ORCHESTRATOR_VALIDATE_ONLY │
│ DEFAULT: no-validate-only │
│ --exit-handlers/--no-exit-handlers Run exit handlers at the end of the execution │
│ ENV: CSM_ORCHESTRATOR_USE_EXIT_HANDLERS │
│ DEFAULT: exit-handlers │
│ --web-help Open the web documentation │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Potential Issues
A known issue exists with graphical commands.
Examples¶
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://cosmotech.com/run_template.schema.json",
"title": "Run Template",
"description": "A run template description",
"type": "object",
"properties": {
"commandTemplates": {
"description": "A list of Commands Templates",
"type": "array",
"items": {
"description": "A Command Template describe a single executable with default properties",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The Id of the Command Template",
"pattern": "^\\S*$"
},
"description": {
"type": "string",
"description": "A description of the command template"
},
"command": {
"type": "string",
"description": "The root bash command necessary to execute the template"
},
"arguments": {
"type": "array",
"description": "The list of default arguments passed to the command",
"items": {
"type": "string"
}
},
"useSystemEnvironment": {
"type": "boolean",
"description": "Should the system environment be fully passed to the command ?"
},
"environment": {
"type": "object",
"description": "The default list of Environment Variables required for the command",
"patternProperties": {
".+": {
"$ref": "#/$defs/environmentVariable"
}
},
"minProperties": 1
}
},
"additionalProperties": false,
"required": [
"id",
"command"
]
}
},
"steps": {
"description": "A list of Steps descriptors",
"type": "array",
"items": {
"description": "A Step is a single instance of a Command that is scheduled to be run, can use an existing command or define its own",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The Id of the Step",
"pattern": "^\\S*$"
},
"description": {
"type": "string",
"description": "A description of the step (override command template description)"
},
"commandId": {
"type": "string",
"description": "An Id for an existing command"
},
"command": {
"type": "string",
"description": "The root bash command necessary to execute the command"
},
"arguments": {
"type": "array",
"description": "The list of arguments passed to the command (replace the default one)",
"items": {
"type": "string"
}
},
"useSystemEnvironment": {
"type": "boolean",
"description": "Should the system environment be fully passed to the command ?"
},
"environment": {
"type": "object",
"description": "The list of Environment Variables defined for the command (replace the default one)",
"patternProperties": {
".+": {
"$ref": "#/$defs/environmentVariable"
}
},
"minProperties": 1
},
"precedents": {
"type": "array",
"description": "A list of steps that have to be run before this one",
"items": {
"type": "string"
}
}
},
"additionalProperties": false,
"oneOf": [
{
"required": [
"id",
"command"
]
},
{
"required": [
"id",
"commandId"
]
}
]
}
}
},
"required": [
"steps"
],
"$defs": {
"environmentVariable": {
"type": "object",
"description": "A environment variable descriptor",
"properties": {
"defaultValue": {
"type": "string",
"description": "The default value of the required variable, if not set, the variable has to be set in the system"
},
"value": {
"type": "string",
"description": "The effective value of the required variable, will override any system value"
},
"description": {
"type": "string",
"description": "A description of the required Environment Variable for documentation reasons"
},
"optional": {
"type": "boolean",
"description": "Should the Environment Variable be required for the run of a step ?"
}
},
"additionalProperties": false
}
}
}
Example json file
simple_example.json
{
"commandTemplates": [
{
"id": "TEMPLATE_ID",
"command": "echo",
"arguments": [
"list",
"of",
"arguments",
"$ENV_VALUE"
],
"environment": {
"ENV_VALUE": {
"defaultValue": "DEFAULT",
"description": "An environment variable with a default value"
}
}
}
],
"steps": [
{
"id": "UseTemplate",
"commandId": "TEMPLATE_ID"
},
{
"id": "OverrideTemplate",
"commandId": "TEMPLATE_ID",
"arguments": [
"Added",
"arguments"
],
"environment": {
"ENV_VALUE": {
"value": "OVERRIDE",
"description": "An environment variable with a forced value"
}
},
"precedents": [
"UseTemplate"
]
},
{
"id": "NewCommand",
"command": "echo",
"arguments": [
"$NO_EXIST"
],
"environment": {
"NO_EXIST": {
"description": "An environment variable with no value"
}
},
"precedents": [
"OverrideTemplate"
]
}
]
}
Run command with json file
The following code won't run by itself because example.json requires the EnvVar NO_EXIST to be set by the system
run without complementary EnvVar
You could do the following to have it work
csm-orc run example.json
set EnvVar with export
The following works too
export NO_EXIST="This value exists"
csm-orc run example.json
run with EnvVar for run only
NO_EXIST="This value exists" csm-orc run example.json