Software and services generally need to be operated when they’re being run in a live environment. For example: we may need to run backups, scale a service, or add a user account. Many of these operational tasks can be automated, which is great, but what’s harder is keeping the configuration for these tasks up to date and testing and promoting them through environments.
Escape solves this problem by making operational tasks, Errands, part of the deployment of a package. Errands are regular scripts defined in the Escape Plan, and when deployed have access to all the deployment’s input and output variables. This means that the operational task is always in sync with the deployment it operates against, and that it can be run in different environments.
Errands are defined in the Escape Plan like this:
name: my-database version: 0.0.@ deploy: deploy_database.sh inputs: - host - username - password outputs: - database_url errands: backup: description: Backup the database. script: backup.sh
backup.sh script has access to input and output variables; ie. the
$OUTPUT_database_url will all be set.
You can also define additional inputs that are only needed for the task at hand and not relevant to the release itself:
name: my-database version: 0.0.@ deploy: deploy_database.sh inputs: - id: host - id: username - id: password errands: backup: description: Backup the database. script: backup.sh inputs: - id: destination_bucket default: "s3://little-backup-bucket"
The inputs section works exactly the same as it does for the inputs section on the package, so in other words you can set defaults, types, use the scripting language, etc. See here for all the options.
We can list the errands on a deployment using the errands list command. We will need to pass it the deployment name, and optionally the environment (default is “dev”):
escape errands list --deployment my-deployment --environment ci
Running an errand can be done using the errands run command, surprisingly enough. Once again we pass in the deployment name and environment, but this time we also add the errand in question:
escape errands run --deployment my-deployment --environment ci backup
If the errand has input variables defined on it we can pass those in as well:
escape errands run --deployment my-deployment --environment ci backup \ -v destination_bucket=s3://my-giant-backup-bucket
The previous commands are pretty simple, but when you’re developing a new errand their behaviour is slightly limiting, because these commands only work on packages that have already been released. This means that if we were to be developing a new errand and we’d want to list and run it to make sure it works we would have to release and deploy the package first.
To avoid this we can also pass the
--local flag. This will make Escape read
the errands from the local Escape Plan, instead of trying to fetch them from the
escape errands list --local
To run an errand from the Escape Plan we do still need a deployment, otherwise the errand has nothing to run against. We don’t necessarily need to deploy an already released package however; we can deploy from our Escape Plan as well, which fits the development process a bit better. What’s important is that the errand gets access to the right state, otherwise the inputs and outputs won’t match.
Once the deployment is there we can keep rerunning the
escape errands run
escape run deploy --deployment my-deployment escape errands run --deployment my-deployment --local backup
Note: it’s currently not possible to write tests for Errands that run as part of the release process, but you can trigger the errands from your “test” and “smoke” scripts.