Cumulus¶
Cumulus (cumulus
) is used for software bundling and for managing
CloudFormation deployments.
Cumulus configuration¶
Example cumulus.conf
¶
All configuration is read form /etc/cumulus.conf
, ~/.cumulus.conf
and
./cumulus.conf
in order. You can also specify a custom configuration file
using --config
.
Below is a full example configuration:
[general]
log-level: info
[environment: stage]
access-key-id: <AWS ACCESS KEY>
secret-access-key: <AWS SECRET KEY>
bucket: se.skymill.bundles
region: eu-west-1
stacks: full
bundles: webserver, database, app
version: 1.0.0-SNAPSHOT
pre-deploy-hook: /path/to/script
post-deploy-hook: echo "Yay" > ~/test.log
stack-name-prefix: myproject
#stack-name-suffix: myproject
[stack: full]
template: /Users/sebastian/tmp/hosts/webserver.json
disable-rollback: true
#timeout-in-minutes: 10
parameters:
version = 1.1.0,
test tag = my test value
key = value
tags:
project = Example project
[bundle: webserver]
pre-bundle-hook: git clone git://git.example.com/my.git
post-bundle-hook: rm -rf my
paths:
/Users/sebastian/tmp/hosts/webserver
/Users/sebastian/tmp/code/wordpress
[bundle: database]
pre-bundle-hook: /path/to/script
paths: /Users/sebastian/tmp/hosts/database
path-rewrites:
/wordpress -> /var/www/wordpress
/nginx -> /etc/nginx
[bundle: app]
pre-built-bundle: /Users/sebastian/build/app.zip
Section: general
¶
The configuration options here modify the behavior of Cumulus features that are not environment or stack specific.
Option | Type | Required | Comment |
---|---|---|---|
log-level |
String | No | Log level (one of: debug , info , warning and error ) |
include |
CommaSeparatedList | No | List of config files to include |
Section: environment
¶
The following configuration options are available under [environment: env_name]
. The env_name
is the identifier for the environment.
Option | Type | Required | Comment |
---|---|---|---|
access-key-id |
String | Yes | AWS access key |
secret-access-key |
String | Yes | AWS secret access key |
bucket |
String | Yes | AWS S3 bucket to store bundles in |
region |
String | Yes | AWS region name, e.g. us-east-1 |
stacks |
List | Yes | List of stack names to deploy |
bundles |
List | Yes | List of bundles to build and upload |
version |
String | Yes | Environment version number |
pre-deploy-hook |
String | No | Command to execute before deployment |
post-deploy-hook |
String | No | Command to execute after deployment |
stack-name-prefix |
String | No | Prepend a prefix to the stack name |
stack-name-suffix |
String | No | Append a suffix to the stack name |
Section: stack
¶
Options for the [stack: stack_name]
configuration section.
Option | Type | Required | Comment |
---|---|---|---|
template |
String | Yes | Path to local CloudFormation JSON file |
disable-rollback |
Boolean | No | Should CloudFormation rollbacks be disabled? Default: false |
timeout-in-minutes |
Int | No | Set a CloudFormation creation timeout |
parameters |
Line sep. string | Yes | Parameters to send to the CloudFormation template. Should be on the form key = value . Each parameter is separated by a new line. |
tags |
Line sep. string | No | CloudFormation tags to add to the stack |
Section: bundle
¶
Options for the [bundle: bundle_name]
configuration section.
Option | Type | Required | Comment |
---|---|---|---|
pre-bundle-hook |
String | No | Command to execute before bundling |
post-bundle-hook |
String | No | Command to execute after bundling |
paths |
Line sep. string | Yes | Paths to include in the bundle. Each path should be declared on a new line. |
path-rewrites |
Line sep. string | No | Replace parts of the paths. Will make a string replace before bundling. Format: /example/path/ -> / (will replace /example/path/ will be replaced by / ) |
pre-build-bundle |
String | No | Path to a pre-built bundle. This option will make the paths redundant. |
Command line options¶
Below is a listing of the cumulus
command line options.
usage: cumulus [-h] [-e ENVIRONMENT] [-s STACKS] [--version VERSION]
[--parameters PARAMETERS] [--config CONFIG] [--cumulus-version]
[--force] [--bundle] [--deploy] [--deploy-without-bundling]
[--redeploy] [--events] [--list] [--outputs]
[--validate-templates] [--undeploy]
Cumulus cloud management tool
optional arguments:
-h, --help show this help message and exit
General options:
-e ENVIRONMENT, --environment ENVIRONMENT
Environment to use
-s STACKS, --stacks STACKS
Comma separated list of stacks to deploy. Default
behavior is to deploy all stacks for an environment
--version VERSION Environment version number. Overrides the version
value from the configuration file
--parameters PARAMETERS
CloudFormation parameters. On the form: stack_name:par
ameter_name=value,stack_name=parameter_name=value
--config CONFIG Path to configuration file. Can be a comma separated
list of files.
--cumulus-version Print cumulus version number
--force Skip any safety questions
Actions:
--bundle Build and upload bundles to AWS S3
--deploy Bundle and deploy all stacks in the environment
--deploy-without-bundling
Deploy all stacks in the environment, without bundling
first
--redeploy Undeploy and deploy the stack(s). Implies bundling.
--events List events for the stack
--list List stacks for each environment
--outputs Show output for all stacks
--validate-templates Validate all templates for the environment
--undeploy Undeploy (delete) all stacks in the environment. Use
--force to skip the safety question.
Stack naming¶
CloudFormation stacks must have a unique name. Cumulus will therefore combine the environment name and the stack name from the configuration. The pattern is <environment>-<stack_name>
. So, if your environment is called production
and your stack is webservers
then your CloudFormation stack will be named production-webservers
.
You can also optionally add a prefix or suffix to the stack name using the stack-name-prefix
and/or stack-name-suffix
options.
Deploying an environment¶
To deploy (create or update) an environment run the following:
cumulus --environment production --deploy
python cumulus
If you only want to deploy a certain stack, use the --stacks
option.
Undeploying (deleting) an environment¶
If you want to remove a whole environment, you’ll undeploy it by running:
cumulus --environment production --undeploy
python cumulus
Note on environment specific configuration¶
Cumulus supports environment specific configuration, if you are using
cumulus
to create your bundles. This is useful if you have one
httpd.conf
for production purposes and another for testing. To have files
that should only be included in specific environments, prefix them with
__cumulus-environment__filename.
So for example: __cumulus-production__nginx.conf is the nginx.conf for the production environment.