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
chosen_stack = (default=”“) string
chosen_task = (default=”list_tasks”) string
config = file
configuration = any
dry_run = (default=False) boolean
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
extra_imports = [ [string, string] , … ]
flat = (default=False) boolean
Show
task to show the stacks as a flat list. Set by --flat
no_assume_role = (default=False) boolean
Stack¶
alerting_systems = (optional) { string : <options> }
endpoint = (required) string
name = “{_key_name_1}”
type = string_choice
verify_ssl = (default=True) boolean
artifact_retention_after_deployment = (default=False) boolean
artifacts = { string : <options> }
archive_format = (default=”tar”) string_choice
cleanup_prefix = (optional) string
commands = [ <options> , … ]
compression_type = string_choice
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
paths = [ [string, string] , … ]
upload_to = string
auto_scaling_group_name = (optional) string
bespin = any
build_after = [ string, … ]
build_env = [ [string, (string_or_int_as_string )] , … ]
build_first = [ string, … ]
build_timeout = (default=1200) integer
command = (optional) string
command_on_instances
task as the command to run on the instancesconfirm_deployment = (optional) <options>
auto_scaling_group_name = (optional) string
deploys_s3_path = (optional) [ [string, (integer )] , … ]
sns_confirmation = (optional) <options>
deployment_queue = (required) string
timeout = (default=300) integer
version_message = (required) string
url_checker = (optional) <options>
check_url = (required) string
endpoint = (required) delayed
expect = (required) string
timeout_after = (default=600) integer
zero_instances_is_ok = (default=False) boolean
dns = (optional) dns
downtimer_options = (optional) { valid_string(valid_alerting_system) : <options> }
hosts = [ string, … ]
env = [ [string, (string_or_int_as_string )] , … ]
environment = “{environment}”
ignore_deps = (default=False) boolean
key_name = “{_key_name_1}”
name = (default=”{_key_name_1}”) string
netscaler = (optional) <options>
configuration = (optional) { string : { string : netscaler_config } }
configuration_password = (optional) string
configuration_username = (optional) string
dry_run = to_boolean
host = (required) string
nitro_api_version = (default=”v1”) string
password = delayed
syncable_environments = (optional) [ valid_environment, … ]
username = (required) string
verify_ssl = (default=True) boolean
newrelic = (optional) <options>
account_id = (required) string
api_key = (required) string
application_id = (required) string
deployed_version = (required) string
env = [ [string, (string_or_int_as_string )] , … ]
notify_stackdriver = (default=False) boolean
params_json = valid_params_json
params_yaml = valid_params_yaml
role_name = string
scaling_options = <options>
highest_min = (default=2) integer
instance_count_limit = (default=10) integer
sensitive_params = (default=[‘Password’]) [ string, … ]
skip_update_if_equivalent = [ [delayed, delayed] , … ]
ssh = (optional) <options>
address = (optional) string
instance
is specifiedauto_scaling_group_name = (optional) string
bastion = (optional) string
bastion_key_location = (optional) string
bastion_key_path = (default=”{config_root}/{environment}/bastion_ssh_key.pem”) string
bastion_user = (required) string
instance = (optional) [ string, … ]
instance_key_location = (optional) string
instance_key_path = (default=”{config_root}/{environment}/ssh_key.pem”) string
storage_host = (optional) string
storage_type = (default=”url”) string_choice
user = (required) string
stack_json = valid_stack_json
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 )] , … ]
stack_policy = valid_policy_json
stack_yaml = valid_stack_yaml
stackdriver = (optional) <options>
api_key = (required) string
deployment_version = (default=”<version>”) string
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
vars = delayed
Environment¶
account_id = (required) ( valid_string(regex(\d+)) or integer)
region = (default=”ap-southeast-2”) string
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
Password¶
bespin = “{bespin}”
crypto_text = (required) string
encryption_context = (optional) dictionary
grant_tokens = (optional) [ string, … ]
KMSMasterKey = (required) string
name = “{_key_name_1}”
vars = dictionary
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.