Stack Configurations

Config File Structure

The configuration file is a YAML document. Like a play in an Ansible playbook, the outermost data structure is a YAML mapping.

Like Python, blocks/sections/stanzas in a Bang config file are visually defined by indentation level. Each top-level section name is a key in the outermost mapping structure.

There are some reserved Top-Level Keys that have special meaning in Bang and there is an implicit, broader grouping of these top-level keys/sections. The broader groups are:

Any string that is a valid YAML identifier and is not a reserved top-level key is available for use as a custom configuration scope. It is up to the user to avoid name collisions between keys, especially between reserved keys and custom configuration scope keys.

Top-Level Keys

General Stack Properties

The attributes in this section apply to the entire stack.

The following top-level section names are reserved:

name
This is the unique stack name. E.g. myblog-prod, myblog-staging, monitoring, etc...
version
The overall stack version. A stack may be made up of many components each with their own release cycle and versioning scheme. This version could be used as the umbrella version for an entire product/project release.
logging
Contains configuration values for Bang’s logging.
deployer_credentials
See bang.providers.hpcloud.HPCloud.authenticate()
playbooks
A list of playbook filenames to execute.

Stack Resource Definitions

These configuration stanzas describe the building blocks for a project. Examples of stack resources include:

  • Cloud resources

    • Virtual servers
    • Load balancers
    • Firewalls and/or security groups
    • Object storage
    • Block storage
    • Message queues
    • Managed databases
  • Traditional server room/data center resources

    • Physical or virtual servers
    • Load balancers
    • Firewalls

Users can use Bang to manage stacks that span across traditional and cloud boundaries. For example, a single stack might comprise:

  • Legacy database servers in a datacenter
  • Web application servers in an OpenStack public cloud
  • Message queues and object storage from AWS (i.e. SQS)

Every stack resource key maps to a dictionary for that particular resource type, where the keys are resource names. Each value of the dictionary is a key-value map of attributes. Most attributes are specific to the type of resource being deployed.

Every cloud resource definition must contain a provider key whose value is the name of a Bang-supported cloud provider.

Server definitions that do not contain a provider key are assumed to be already provisioned. Instead of a set of cloud server attributes, these definitions merely contain hostname values and the appropriate configuration scopes.

The reserved stack resource keys are described below:

queues
E.g. SQS
buckets
E.g. S3, OpenStack Swift
databases
E.g. RDS, OpenStack RedDwarf
server_security_groups
E.g. EC2 and OpenStack Nova security groups
servers
E.g. EC2, OpenStack Nova, VPS virtual machines.
load_balancers:
E.g. ElasticLoadBalancer, HP cloud LBaaS

Configuration Scopes

Any top-level section name that is not specified above as a reserved key in General Stack Properties or in Stack Resource Definitions, is parsed and categorized as a custom configuration scope.

Any configuration scope names that are added to a server’s config_scopes list, make those values available to Ansible playbooks as vars.

Configuration scopes typically define attributes for applications and middleware in the stack. For example, a media transcoding web service might have the following config scopes:

apache:
  preforks: 4
  modules:
  - rewrite
  - wsgi

my_web_frontend:
  version: '1.2.0'
  log_level: WARN

my_transcoder_app:
  version: '1.1.5'
  log_level: INFO
  src_types:
  - h.264+aac
  - theora+vorbis

The key names and the values are arbitrary and defined solely by the user.