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 or K 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.

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
    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


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.