Skip to content

Config

Jump to bottom
Shaun Remekie edited this page Jan 6, 2020 · 22 revisions

Qaz uses a main config.yml file as its source-of-truth. The file tells it what stacks it controls and the values to pass to those stacks.

All configuration examples on this page are written using YAML syntax, however, Qaz also supports configuration files written in JSON & HCL.

Below we have a basic Qaz config.

region: "eu-west-1"

project: "daidokoro"

global:

stacks:

  # Vpc stack
  VPC:
    source:
    profile: lab
    cf:
      cidr: 10.10.0.0/16

Note: Config files do not need to be named config.yml Qaz will look for this ( or config.yaml) filename by default if no config is specified. When config is named differently, you can specify the config file using the -c --config flags. More on this below...

Keywords:

Qaz utilises special keywords for defining additional functionality.

--

region

Defines the Region to deploy stacks. This option can be set globally (outside of stacks) or per-stack.

Global Example:

project: myproject
region: eu-west-1

stacks:
  # your stacks here

Per-Stack Example:

stacks:
  vpc:
    region: eu-west-1

  dev:
    region: us-east-1

Note: Stacks per-stack regions override global regions.

--

global

Values defined under Global are accessible across all stacks. This feature was added for uniformity sake rather than necessity. Qaz uses a single config file, all values defined under any stack are accessible to all.

--

gen_time & deploy_time

The gen_time & deploy_time keywords control the delimiters used within the Template. That is, you are able to set the delimiter used when templating. By default Gen-time parsing will use {{ }} or Deploy-Time << >> but these can be overridden if needed.

Example:

# Delimiters are specified using ':' to separate left & right
gen_time: "#{:}"
deploy_time: "@{:}"

--

Stacks

All stacks are defined under the stacks Keyword. Further to this, there are keywords used to specify additional functionality/properties for each stack

Example:

stacks:
  vpc:
    source:
    profile:
    region:
    depends_on:
    parameters:
    notification-arns:
    policy:
    role:
    timeout:
    tags:
    cf:

--

source

The source keyword is one of the more powerful functions of Qaz. It supports various methods of retrieving templates and configuration files Further more, this method can be mixed and matched, meaning, you can use all the source methods within a single project or configuration file.

Supported sources:

  • HTTP(s)
  • Lambda
  • S3
  • Local Relative or Explicit file paths

Example:

stacks:
  vpc1:
    # specified source via http(s)
    source: http://mytemplate.json

  vpc2:
    # specified source via s3
    source: s3://mytemplate.json

  vpc3:
    # specified source via Lambda -
    source: lambda:{"your":"json_event"}@function_name

  vpc4:
    # specified source via filepath
    source: path/to/template.json

--

profile

Allows a particular AWS CLI Config profile to be selected for each stack, that is, each stack can be deployed using different credentials, this can allow for simultaneous cross-account or cross-region deployments.

Example:

For this example, here's my aws config:

[profile prod]
aws_secret_access_key = "oxoxoxoxoxoxoxoxoxoxoxooxoxo"
aws_access_key_id = "oxoxoxoxoxoxoxoxoxo"
region = "eu-west-1"

[profile lab]
aws_secret_access_key = "oxoxoxoxoxoxoxoxoxoxoxooxoxo"
aws_access_key_id = "oxoxoxoxoxoxoxoxoxo"
region = "eu-west-1"

Credentials for both prod & lab are defined in my aws config file, each are for a different aws accounts.

stacks:
  vpcLab:
    # specifies the lab profile in my AWS config file
    profile: lab
    # sp
    cf:
      cidr: 10.0.0.0/16

  vpcProd:
    # specifies the lab profile in my AWS config file
    profile: prod

The above will deploy both VPC stacks to different accounts based on the credentials in the specified profile.

Credentials can also be for same account but specify different regions, in this way, Qaz is also able to deploy cross-region. To accomplish this, simply leave the region keyword blank, Qaz will deploy the stack using the region specified in the profile. Note, that one or the other must be specified, profile or region keyword.

Read more on AWS Config & Credential files here

--

parameters

Stack parameters to pass when deploying can be listed under this keyword. Read more on AWS Cloudformation Stack Parameters See Here

Example:

stackname:
  parameters:
    - password: password123

--

depends_on

Use this keyword to define a dependency chain by listing stack dependencies. With this keyword, you can explicitly say one stack relies on another or several others.

Example:

elb-stack:
  depends_on:
    - vpc-stack
    - securitygroup-stack

--

policy

The policy keyword is used to set the stack update policy when deploying a stack. If this value is empty or not set, then the stack is created without an update policy.

Example:

stacks:
  vpc:
    # stack policy - url or raw json can be specified here
    policy: https://s3-eu-west-1.amazonaws.com/daidokoro-dev/policies/stack.json

--

tags

The tags keyword is used to specify stack tags. These are tags that are applied to all resources created within a stack. Note that there is a hard limit of 10 stack tags per stack.

Example:

stacks:
  vpc:
    tags:
      - justify: reasons
      - data: node
      - name: maybe

    source: vpc.yaml
    cf:
      cidr: 10.20.10.0/16

timeout

Sometimes it may be necessary to set a hard timeout for a stack deploy/creation, the timeout keyword will do the trick. All stack deployments that exceed the specified timeout will be marked as failed. Note that timeouts are specified in minutes.

stacks:
  vpc:
    timeout: 1
    source: vpc.yaml

region

As previously mentioned, region allows you to set the region the stack will be deployed to.

notification-arns

This keyword allows users to set SNS ARNs for sending stack notifications.

Example:

stacks:
  vpc:
    source: <your source>

    # Add your SNS ARNs
    notification-arns:
      - arn:aws:sns:eu-west-1:012345678910:uchiha
    cf:
      cidr: 10.10.0.0/16

cf

All Cloudformation values are defined under this keyword. There is no limitation on how values should be structured as long as they adhere to the config syntax being used, i.e YAML, JSON or HCL.

Example:

stacks:
  vpc-stack:
    cf:
      cidr: 10.10.0.0/16
      subnets:
        - 10.10.10.0/24

--

Passing Config via CLI

Qaz uses the -c or --config flags to specify config. Any of the following can be used to specify config:

  • http(s) endpoint
  • s3 endpoint
  • AWS Lambda
  • explicit or relative paths

Examples:

Let's say have a config file called my.cnf. To deploy a stack(s) using this config to Qaz, i'd run the following command:

$ qaz deploy vpc -c path/to/my.cnf

Note, if no config file is specified, Qaz will first check the environment variable QAZ_CONFIG, if this is undefined, then qaz will default to config.yml in the current working directory.

To retrieve configuration using Lambda, S3 or HTTP(s):

$ qaz deploy vpc -c s3://my.cnf

$ qaz deploy vpc -c https://myspecial-endpoint.com/my.cnf

$ qaz deploy vpc -c lambda:{"your":"event_json"}@function_name

The -c & --config flags have the same functionality across all commands that require configuration to be specified.

--

See here for more examples of Qaz config files

Clone this wiki locally