Cumulus Bundle Handler¶
The Cumulus Bundle Handle is a Python script that should reside on each server in the environment. The script is responsible for
- Downloading and extracting the correct bundles for the host
- Running pre and post deployment scripts on the host, e.g. to restart relevant services and trigger various deployment hooks
The bundles are generated via the cumulus
command (or in your build server)
and uploaded to S3. Cumulus Bundle Handler will then download the bundle when
the script is triggered (usually by a CloudFormation create
or update
).
Init scripts¶
The Cumulus Bundle Handler supports scripts to be executed:
- Before bundle extraction (good for stopping services etc)
- After bundle extraction (good for starting services)
- Both before and after extraction (typically cleaning jobs)
All init script should reside in /etc/cumulus-init.d
on Linux systems and
in C:\cumulus\init.d
on Windows systems and must be executable.
- Scripts starting with
K
(capital K) are executed before the bundle is extracted - Scripts starting with
S
(capital S) are executed after the bundle is extracted - Scripts starting with anything else than
S
orK
are executed both before and after the bundle is extracted
Configuration file¶
The configuration file for Cumulus Bundle Handler should reside on your
EC2 instances under /etc/cumulus/metadata.conf
on Linux systems and
under C:\cumulus\conf\metadata.conf
on Windows systems. It recommended
to serve it to that location using CloudFormation AWS::CloudFormation::Init.
metadata.conf
example¶
The Cumulus Bundle Handler relies on a configuration file called
metadata.conf
. Here’s an example configuration file.
[metadata]
log-level: INFO
access-key-id: <AWS_ACCESS_KEY>
secret-access-key: <AWS_SECRET_KEY>
region: eu-west-1
bundle-bucket: com.example.bundles
environment: stage
bundle-types: webserver
bundle-extraction-paths:
generic -> /etc/example
webserver -> /
version: 1.0.0-SNAPSHOT
Configuration options for metadata.conf
¶
Option | Type | Required | Comment |
---|---|---|---|
access-key-id |
String | Yes | AWS access key |
secret-access-key |
String | Yes | AWS secret access key |
region |
String | Yes | AWS region name, e.g. us-east-1 |
bucket |
String | Yes | AWS S3 bucket to fetch bundles from |
environment |
String | Yes | Environment name |
version |
String | Yes | Environment version to apply |
bundle-types |
List | Yes | Bundle names to apply to this host |
bundle-extraction-paths |
New line sep. list | No | Decide in which parent directory a bundle shall be extracted. Default is / on Linux and Mac OS X and `C:` on Windows systems. Expecting absolute paths |
log-level |
String | No | Log level for the bundle handler |
Logging¶
Cumulus Bundle Handler will log to /var/log/cumulus-bundle-handler.log
on
Linux systems and to C:\cumulus\logs\cumulus-bundle-handler.log
on Windows
systems.
This log file can be really helpful when trying to debug your deployments.