Configuration¶

Bespin is configured via a YAML file that contains Bespin configuration, environment specific configuration, and stack specific configuration.

Layout¶

The layout of your directory is configured by default to look something like:

root/
  bespin.yml
  <stack>.json
  <stack2>.yaml

  <environment1>/
    <stack>-params.json
    <stack2>-params.yaml

  <environment2>/
    <stack>-params.json
    <stack2>-params.yaml

So say you have two stacks, one called app and one called dns, along with only one environment called dev:

root/
  bespin.yml
  app.json
  dns.json

  dev/
    app-params.json
    dns-params.json

and your bespin.yml would look something like:

---

environments:
  dev:
    account_id: 0123456789
    vars:
      variable1: value1

stacks:
  app:
    <options>

  dns:
    <options>

Where <options> are the options for that stack.

Note

The location of the stack template file is configured by the stack_json or stack_yaml option. The location of the params file is configured by the params_json or params_yaml option. Alternatively parameters can be specified inline (inside bespin.yml) using params_yaml.

Bespin¶

assume_role = (optional) string

An iam role to assume into before doing any amazon requests.

The iam role can also be set via the ASSUME_ROLE environment variable.

This behaviour can be disabled by setting the NO_ASSUME_ROLE environment variable to any value.

chosen_artifact = (default=”“) string

The value of the –artifact option. This is used to mean several things via the tasks

chosen_stack = (default=”“) string

The stack to pass into the task

chosen_task = (default=”list_tasks”) string

The task to execute

config = file

Holds a file object to the specified Bespin configuration file

configuration = any

The root of the configuration

dry_run = (default=False) boolean

Don’t run any destructive or modification amazon requests

environment = (optional) string

The environment in the configuration to use.

When a stack is created the stack configuration is merged with the configuration for this environment.

extra = (default=”“) string

Holds extra arguments after a – when executed from the command line

extra_imports = [ [string, string] , … ]

Any extra files to import before searching for the chosen task

flat = (default=False) boolean

Used by the Show task to show the stacks as a flat list. Set by --flat

no_assume_role = (default=False) boolean

Boolean saying if we should assume role or not

Stack¶

alerting_systems = (optional) { string : <options> }

Configuration about alerting systems for downtime_options

endpoint = (required) string

Endpoint of the system

name = “{_key_name_1}”

The name of this system

type = string_choice

The type of this system

verify_ssl = (default=True) boolean

Boolean saying whether to verify ssl

artifact_retention_after_deployment = (default=False) boolean

Delete old artifacts after this deployment is done

artifacts = { string : <options> }

Options for building artifacts used by the stack

archive_format = (default=”tar”) string_choice

The archive file format to use on the artifact (tar, zip)

cleanup_prefix = (optional) string

The prefix to use when finding artifacts to clean up

commands = [ <options> , … ]

Commands that need to be run to generate content for the artifact

compression_type = string_choice

The compression to use on the artifact

files = [ <options> , … ]

Any files to add into the artifact

For example:

files:
  - content: "{__stack__.vars.version}"
    path: /artifacts/app/VERSION.txt

history_length = integer

The number of artifacts to keep in s3

Note

These only get purged if the stack has artifact_retention_after_deployment set to true or if the clean_old_artifacts task is run

not_created_here = (default=False) boolean

Boolean saying if this artifact is created elsewhere

paths = [ [string, string] , … ]

Paths to copy from disk into the artifact

upload_to = string

S3 path to upload the artifact to

auto_scaling_group_name = (optional) string

The name of the auto scaling group used in the stack

bespin = any

The Bespin object

build_after = [ string, … ]

A list of stacks that should be built after this one is buildt

build_env = [ [string, (string_or_int_as_string )] , … ]

A list of environment variables that are necessary when building artifacts

build_first = [ string, … ]

A list of stacks that should be built before this one is built

build_timeout = (default=1200) integer

A timeout for waiting for a build to happen

command = (optional) string

Used by the command_on_instances task as the command to run on the instances

confirm_deployment = (optional) <options>

Options for confirming a deployment

auto_scaling_group_name = (optional) string

The name of the auto scaling group that has the instances to be checked

deploys_s3_path = (optional) [ [string, (integer )] , … ]

A list of s3 paths that we expect to be created as part of the deployment

sns_confirmation = (optional) <options>

Check an sqs queue for messages our Running instances produced

deployment_queue = (required) string

The sqs queue to check for messages

timeout = (default=300) integer

Stop waiting after this amount of time

version_message = (required) string

The expected version that indicates successful deployment

url_checker = (optional) <options>

Check an endpoint on our instances for a particular version message

check_url = (required) string

The path of the url to hit

endpoint = (required) delayed

The domain of the url to hit

expect = (required) string

The value we expect for a successful deployment

timeout_after = (default=600) integer

Stop waiting after this many seconds

zero_instances_is_ok = (default=False) boolean

Don’t do deployment confirmation if the scaling group has no instances

dns = (optional) dns

Dns options

downtimer_options = (optional) { valid_string(valid_alerting_system) : <options> }

Downtime options for the downtime and undowntime tasks

hosts = [ string, … ]

A list of globs of hosts to downtime

env = [ [string, (string_or_int_as_string )] , … ]

A list of environment variables that are necessary for this deployment

environment = “{environment}”

The name of the environment to deploy to

ignore_deps = (default=False) boolean

Don’t build any dependency stacks

key_name = “{_key_name_1}”

The original key of this stack in the configuration[‘stacks’]

name = (default=”{_key_name_1}”) string

The name of this stack

netscaler = (optional) <options>

Netscaler declaration

configuration = (optional) { string : { string : netscaler_config } }

Configuration to put into the netscaler

configuration_password = (optional) string

The password for configuration syncing

configuration_username = (optional) string

The username for configuration syncing

dry_run = to_boolean

Whether this is a dry run or not

host = (required) string

The address of the netscaler

nitro_api_version = (default=”v1”) string

Defaults to v1

password = delayed

The password

syncable_environments = (optional) [ valid_environment, … ]

List of environments that may be synced

username = (required) string

The username

verify_ssl = (default=True) boolean

Whether to verify ssl connections

newrelic = (optional) <options>

Newrelic declaration

account_id = (required) string

The account id

api_key = (required) string

The api key to newrelic

application_id = (required) string

The application id

deployed_version = (required) string

Deployed version

env = [ [string, (string_or_int_as_string )] , … ]

Required environment variables

notify_stackdriver = (default=False) boolean

Whether to notify stackdriver about deploying the cloudformation

params_json = valid_params_json

The path to a json file for the parameters used by the cloudformation stack

params_yaml = valid_params_yaml

Either a dictionary of parameters to use in the stack, or path to a yaml file with the dictionary of parameters

role_name = string

The IAM role that cloudformation assumes to create the stack

scaling_options = <options>

Options for the scale_instances command

highest_min = (default=2) integer

No description

instance_count_limit = (default=10) integer

No description

sensitive_params = (default=[‘Password’]) [ string, … ]

Used to hide sensitive values during build

skip_update_if_equivalent = [ [delayed, delayed] , … ]

A list of two variable definitions. If they resolve to the same value, then don’t deploy

ssh = (optional) <options>

Options for ssh’ing into instances

address = (optional) string

The address to use to get into the single instance if instance is specified

auto_scaling_group_name = (optional) string

The logical id of the auto scaling group that has the instances of interest

bastion = (optional) string

The bastion jumpbox to use to get to the instances

bastion_key_location = (optional) string

The place where the bastion key may be downloaded from

bastion_key_path = (default=”{config_root}/{environment}/bastion_ssh_key.pem”) string

The location on disk of the bastion ssh key

bastion_user = (required) string

The user to ssh into the bastion as

instance = (optional) [ string, … ]

The Logical id of the instance in the template to ssh into

instance_key_location = (optional) string

The place where the instance key may be downloaded from

instance_key_path = (default=”{config_root}/{environment}/ssh_key.pem”) string

The location on disk of the instance ssh key

storage_host = (optional) string

The host for the storage of the ssh key

storage_type = (default=”url”) string_choice

The storage type for the ssh keys

user = (required) string

The user to ssh into the instances as

stack_json = valid_stack_json

The path to a json file for the cloudformation stack definition

stack_name = (default=”{_key_name_1}”) string

The name given to the deployed cloudformation stack

Note that this may include environment variables as defined by the stack_name_env option:

stack_name: "rerun-{{RELEASE_VERSION}}"
stack_name_env:
    - RELEASE_VERSION

stack_name_env = [ [string, (string_or_int_as_string )] , … ]

A list of environment variables that are necessary for creating the stack name

stack_policy = valid_policy_json

The path to a json file for the cloudformation stack policy

stack_yaml = valid_stack_yaml

The path to a yaml file for the cloudformation stack definition

stackdriver = (optional) <options>

Stackdriver options used for giving events to stackdriver

api_key = (required) string

The api key used to gain access to stackdriver

deployment_version = (default=”<version>”) string

The version being deployed

suspend_actions = (default=False) boolean

Suspend Scheduled Actions for the stack before deploying, and resume Scheduled actions after finished deploying.

This uses the auto_scaling_group_name attribute to determine what autoscaling group to suspend and resume

tags = { valid_string(regex(^.{0,127}$)) : string }

A dictionary specifying the tags to apply to the stack

Cloudformation will apply these tags to all created resources

termination_protection = (default=False) boolean

Whether to enable termination protection for the stack

vars = delayed

A dictionary of variable definitions that may be referred to in other parts of the configuration

Environment¶

account_id = (required) ( valid_string(regex(\d+)) or integer)

AWS account id for this environment

region = (default=”ap-southeast-2”) string

AWS region name for this environment

tags = { valid_string(regex(^.{0,127}$)) : string }

A dictionary specifying the tags to apply to the stack

Cloudformation will apply these tags to all created resources

vars = dictionary

A dictionary of variable definitions that may be referred to in other parts of the configuration

Password¶

bespin = “{bespin}”

The bespin object

crypto_text = (required) string

The encrypted version of the password

encryption_context = (optional) dictionary

Any encryption context

grant_tokens = (optional) [ string, … ]

List of any grant tokens

KMSMasterKey = (required) string

The kms master key id

name = “{_key_name_1}”

The name of the password

vars = dictionary

Extra variables

Formatter¶

Configuration values may reference other parts of the config using ‘replacement fields’ surrounded by curly braces {}. Nested values can be referenced using dot notation, eg: {foo.bar.quax}. If you need to include a brace character in the literal text, it can be escaped by doubling: {{ and }}.

Available fields:

environment

Current environment name as a string

region

Current environment’s region

environments.<env_name>.*

Environment mappings.

Environment fields includes:

account_id: Environment AWS account id
region: Environment AWS region

stacks.<stack_name>.*

Stack mappings. See Stack spec for more detail.

tags.*

Tags mapping

vars.*

Vars mapping

Within a stack, bespin also defines the following aliases:

__stack_name__: Current stack name as a string.
__stack__: Current stack mapping (ie: stacks.__stack_name__). See Stack spec for more detail.
__environment__: Current environment mapping (ie: environments.environment).

In addition to configuration fields, bespin defines the following special values:

config_root

Directory of the main configuration file (ie: dirname of --bespin-config)

:config_dir

(advanced) (python2.7+ or python3 required)

Directory of the configuration file where the value was defined. See bespin.extra_files.

_key_name_X

(advanced)

Refers to the key’s content X positions up from the current value, indexed from zero. For example, the following would result in “example vars test”:

stacks:
  test:
    vars:
      example: "{_key_name_0} {_key_name_1} {_key_name_2}"

Fields may also declare a formatter by suffixing the field with a colon : and the name of the formatter to use. Available formatters include:

:env

Formats environment variables suitable to be used in shell. {USER:env} would produce ${USER}.

:date

Return a string representing the current datetime (datetime.datetime.now()) formatted by strftime. See Python strftime for available format codes. eg: {%Y:date} would result in the current year (eg: “2017”)

:underscored

Converts ‘-‘ to ‘_’.

:count

Returns the total number of elements in a list or CommaDelimitedList variable as a string.

The total number of elements in a CommaDelimitedList should be one more than the total number of commas. This implementation marries Cloudformation Parameters CommaDelimitedList’s implementation. Examples:

vars:
  one: "1"        # {one:count} == "1"
  two: "1,2"      # {two:count} == "2"
  three: "1,2,3"  # {three:count} == "3"
  empty: ""       # {empty:count} == "1"
  space: " "      # {space:count} == "1"
  comma: ","      # {comma:count} == "2"

Note

The formatter does not support nested values (eg: {a.{foo}.c}). See Stacks for details on using variable formatting (ie: XXX_MYVAR_XXX) instead.