Runway Config File

Top-Level Configuration

class runway.config.Config(deployments, future=None, ignore_git_branch=False, runway_version=None, tests=None, variables=None)[source]

The Runway config file is where all options are defined.

It contains definitions for deployments, tests, and some global options that impact core functionality.

The Runway config file can have two possible names, runway.yml or runway.yaml. It must be stored at the root of the directory containing all modules to be deployed.

Example

---
# See full syntax at https://github.com/onicagroup/runway
ignore_git_branch: true
runway_version: ">=1.11, <2.0"
tests:
  - name: example
    type: script
    args:
      commands:
        - echo "Hello world"
deployments:
  - modules:
      - path: my-modules.cfn
    regions:
      - us-east-1
Keyword Arguments
  • deployments (List[Dict[str, Any]]) – A list of deployments that are processed in the order they are defined.

  • future (Dict[str, bool]) – Enable future functionality before it is made standard in the next major release.

  • ignore_git_branch (bool) – Disable git branch lookup when using environment folders, non-git VCS, or defining the DEPLOY_ENVIRONMENT environment variable before execution. Note that defining DEPLOY_ENVIRONMENT will automatically ignore the git branch.

  • runway_version (Optional[str]) – Specify a version of Runway required to run use this configuration. The value of this field is PEP 440 compliant.

  • tests (Optional[List[Dict[str, Any]]]) – A list of tests that are processed in the order they are defined.

  • variables (Optional[Dict[str, Any]]) – A map that defines the location of a variables file and/or the variables themselves.

New in version 1.11.0: The runway_version option.

Lookup Resolution

Keyword / Directive

Support

deployments

No direct support. See Deployment for details on support within a deploymet definition.

future

None

ignore_git_branch

None

runway_version

None

tests

No direct support. See Test for details on support within a test definition.

variables

None

References

Deployment

class runway.config.DeploymentDefinition(deployment)[source]

A deployment defines modules and options that affect the modules.

Deployments are processed during a deploy/destroy/plan action. If the processing of one deployment fails, the action will end.

During a deploy/destroy action, the user has the option to select which deployment will run unless the CI environment variable is set, the --tag <tag>... cli option was provided, or only one deployment is defined.

Example

deployments:
  - modules:  # minimum requirements for a deployment
      # "./" can alternatively be used for the module name to indicate
      # the current directory
      - my-module.cfn
    regions:
      - us-east-1
  - name: detailed-deployment  # optional
    modules:
      - path: my-other-modules.cfn
        type: cloudformation
    regions:
      - us-east-1
    environments:
      prod: 111111111111/us-east-1
      dev:
        - 222222222222/us-east-1
        - 333333333333/us-east-1
      lab: true
    account_id: ${var account_ids}  # optional
    assume_role: ${var assume_role}  # optional
    parameters:  # optional
        region: ${env AWS_REGION}
        image_id: ${var image_id.${env DEPLOY_ENVIRONMENT}}
    env_vars:  # optional environment variable overrides
        AWS_PROFILE: ${var aws_profile.${env DEPLOY_ENVIRONMENT}::default=default}
        APP_PATH: ${var app_path.${env DEPLOY_ENVIRONMENT}}
Keyword Arguments
  • account_alias (Optional[Dict[str, str]]) – A mapping of $environment: $alias that, if provided, is used to verify the currently assumed role or credentials.

  • account_id (Optional[Dict[str, Union[str, int]]]) – A mapping of $environment: $id that, if provided, is used to verify the currently assumed role or credentials.

  • assume_role (Optional[Dict[str, Union[str, Dict[str, str]]]]) – A mapping of $environment: $role or $environment: {arn: $role, duration: $int} to assume a role when processing a deployment. arn: $role can be used to apply the same role to all environment. post_deploy_env_revert: true can also be provided to revert credentials after processing.

  • environments (Optional[Dict[str, Dict[str, Any]]]) – Optional mapping of environment names to a booleon value used to explicitly enable or disable in an environment. This can be used when an environment specific variables file and parameters are not needed to force a module to enable anyway or, explicitly skip a module even if a file or parameters are found. The mapping can also have a string (or list of strings) value of $ACCOUNT_ID/$REGION to lock an environment to specific regions in a specific accounts. If it matches, it will act as an explicit enable.

  • env_vars (Optional[Dict[str, Dict[str, Any]]]) – A mapping of OS environment variable overrides to apply when processing modules in the deployment. Can be defined per environment or for all environments by omiting the environment name.

  • modules (Optional[List[Dict[str, Any]]]) – A list of modules to be processed in the order they are defined.

  • module_options (Optional[Dict[str, Any]]) – Options that are shared among all modules in the deployment.

  • name (str) – Name of the deployment. Used to more easily identify where different deployments begin/end in the logs.

  • type (str) – The type of module we are deploying. By default Runway will first check to see if you explicitly specify the module type, after that it will check to see if a valid module extension exists on the directory, and finally it will attempt to autodetect the type of module. Valid values are: serverless, terraform, cdk, kubernetes, cloudformation, static.

  • regions (List[str]) – AWS region names where modules will be deployed/destroyed. Can optionally define as a map with parallel as the key and a list of regions as the value. See parallel_regions for more info.

  • parallel_regions – Can be defined in place of regions.parallel[]. This will cause all modules in the deployment to be executed in all provided regions in parallel (at the same time). Only takes effect when the CI environment variable is set, enabling non-interactive mode, as prompts will not be able to be presented. If CI is not set, the regions will be processed one at a time. This can be used in tandom with parallel modules. assume_role.post_deploy_env_revert will always be true when run in parallel.

  • parameters (Optional(Dict[str, Any])) – Module level parameters that are akin to a CloudFormation parameter in functionality. These can be used to pass variable values to your modules in place of a .env/.tfenv/environment config file. Through the use of Lookups, the value can differ per deploy environment, region, etc.

Lookup Resolution

Important

Due to how a deployment is processed, values are resolved twice. Once before processing and once during processing. Because of this, the keywords/directives that are resolved before processing will not have access to values set during process like AWS_REGION, AWS_DEFAULT_REGION, and DEPLOY_ENVIRONMENT for the pre-processing resolution but, if they are resolved again during processing, these will be available. To avoide errors during the first resolution due to the value not existing, provide a default value for the Lookup.

Keyword / Directive

Support

account_alias

env lookup (AWS_REGION and AWS_DEFAULT_REGION will not have been set by Runway yet), var lookup

account_id

env lookup (AWS_REGION and AWS_DEFAULT_REGION will not have been set by Runway yet), var lookup

assume_role

env lookup (AWS_REGION and AWS_DEFAULT_REGION will not have been set by Runway yet), var lookup

environments

env lookup, var lookup

env_vars

env lookup (AWS_REGION, DEPLOY_ENVIRONMENT, and AWS_DEFAULT_REGION will not have been set by Runway during pre-process resolution. provide a default value to avoide errors.), var lookup

modules

No direct support. See module for details on support within a module definition.

module_options

env lookup, var lookup

name

None

regions

env lookup (AWS_REGION and AWS_DEFAULT_REGION will not have been set by Runway yet), var lookup

parallel_regions

env lookup (AWS_REGION and AWS_DEFAULT_REGION will not have been set by Runway yet), var lookup

parameters

env lookup, var lookup

References

Future

Toggles to opt-in to future, potentially backward compatibility breaking functionality before it is made standard in the next major release.

Availability of these toggles will be removed at each major release as the functionality will then be made standard.

strict_environments (bool)

When enabled, handling of environments for Deployment and Module definitions is changed to prevent processing of modules when the current environment is not defined in the Runway config file.

If environments is defined and the current deploy environment is not in the definition, the module will be skipped. If environments is not defined, the module will be processed. This does not mean that action will be taken but that the type of the module will then determine if action will be taken.

Example

future:
  strict_environments: true

deployments:
  - environments:
      prod:
        - 111111111111/us-east-1
        - 111111111111/us-west-2
      dev:
        - 222222222222
    modules:
      - path: sampleapp-01.cfn
      - path: sampleapp-02.cfn
        environments:
          dev: 222222222222/us-east-1
          feature/something-new: true
    regions: &regions
      - ca-central-1
      - us-east-1
      - us-west-2
  - modules:
      - path: sampleapp-03.cfn
      - path: sampleapp-04.cfn
        environments:
          dev-ca:
            - ca-cental-1
    regions: *regions

Given the above Runway configuration file, the following will occur for each module:

sampleapp-01.cfn

Processed if:

  • environment is prod and AWS account ID is 111111111111 and region is (us-east-1 or us-west-2)

  • environment is dev and AWS account ID is 222222222222 and region is anything

All other combinations will result in the module being skipped.

sampleapp-02.cfn

Processed if:

  • environment is prod and AWS account ID is 111111111111 and region is (us-east-1 or us-west-2)

  • environment is dev and AWS account ID is 222222222222 and region is us-east-1

  • environment is feature/something-new and AWS account ID is anything and region is anything

All other combinations will result in the module being skipped.

sampleapp-03.cfn

Processed if:

  • environment is anything and AWS account ID is anything and region is anything

sampleapp-04.cfn

Processed if:

  • environment is dev-ca and AWS account ID is anything and region is ca-central-1

All other combinations will result in the module being skipped.

New in version 1.9.0.

Module

class runway.config.ModuleDefinition(name, path, class_path=None, type_str=None, environments=None, parameters=None, env_vars=None, options=None, tags=None, child_modules=None)[source]

A module defines the directory to be processed and applicable options.

It can consist of CloudFormation (using CFNgin), Terraform, Serverless Framework, AWS CDK, Kubernetes, or a Static Site. It is recommended to place the appropriate extension on each directory for identification (but it is not required). See Repo Structure for examples of a module directory structure.

Suffix/Extension

IaC Tool/Framework

.cdk

AWS CDK

.cfn

CloudFormation

.sls

Serverless Framework

.tf

Terraform

.k8s

Kubernetes

.web

Static Site

A module is only deployed if there is a corresponding environment file present or parameters are provided. This can take the form of either a file in the module folder or the parameters option being defined. The naming format varies per-module type. See Module Configurations for acceptable environment file name formats.

Modules can be defined as a string or a mapping. The minimum requirement for a module is a string that is equal to the name of the module directory. Providing a string is the same as providing a value for path in a mapping definition.

Example

deployments:
  - modules:
      - my-module.cfn  # this
      - path: my-module.cfn  # is the same as this

Using a map to define a module provides the ability to specify per-module options, parameters, environment variables,tags, and even a custom class for processing the module. The options that can be used with each module vary. For detailed information about module-specific options, see Module Configurations.

Example

deployments:
  - modules:
      - name: my-module
        path: my-module.tf
        environments:
          prod: 111111111111/us-east-1
          dev:
            - 222222222222/us-east-1
            - 333333333333/us-east-1
          lab: true
        parameters:
          image_id: ${var image_id.${env DEPLOY_ENVIRONMENT}}
        tags:
          - app:example
          - my-tag
        options:
          terraform_backend_config:
            region: us-east-1
          terraform_backend_cfn_outputs:
            bucket: StackName::OutputName
            dynamodb_table: StackName::OutputName

One special map keyword, parallel, indicates a list of child modules that will be executed in parallel (simultaneously) if the CI environment variable is set.

Example

In this example, backend.tf will be deployed followed by the services that will be utilizing it. The services will be deployed in parallel. After the services have completed, frontend.tf will be deployed.

deployments:
  - modules:
    - backend.tf
    - parallel:
      - servicea.cfn  # any normal module option can be used here
      - path: serviceb.cfn
      - path: servicec.cfn
        parameters:
          count: ${var count.${env DEPLOY_ENVIRONMENT}}
    - frontend.tf
Keyword Arguments
  • name (str) – Name of the module. Used to more easily identify where different modules begin/end in the logs.

  • path (str) – Path to the module relative to the Runway config file. This cannot be higher than the Runway config file. See Path for detailed usage.

  • class_path (Optional[str]) – Path to custom Runway module class. Also used for static site deployments. See Module Configurations for detailed usage.

  • type_str (Optional[str]) – Alias for type of module to use Module Configurations for detailed usage.

  • environments (Optional[Dict[str, Dict[str, Any]]]) – Optional mapping of environment names to a booleon value used to explicitly deploy or not deploy in an environment. This can be used when an environment specific variables file and parameters are not needed to force a module to deploy anyway or, explicitly skip a module even if a file or parameters are found. The mapping can also have a string (or list of strings) value of $ACCOUNT_ID/$REGION to lock an environment to specific regions in a specific accounts. If it matches, it will act as an explicit deploy.

  • env_vars (Optional[Dict[str, Dict[str, Any]]]) – A mapping of OS environment variable overrides to apply when processing modules in the deployment. Can be defined per environment or for all environments by omiting the environment name. Takes precedence over values set at the deployment-level.

  • options (Optional[Dict[str, Any]]) – Module-specific options. See Module Configurations for detailed usage. Takes precedence over values set at the deployment-level.

  • parameters (Optional(Dict[str, Any])) – Module level parameters that are akin to a CloudFormation parameter in functionality. These can be used to pass variable values to your modules in place of a .env/.tfenv/environment config file. Through the use of Lookups, the value can differ per deploy environment, region, etc.

  • tags (Optional[Dict[str, str]]) – Module tags used to select which modules to process using CLI arguments. (--tag <tag>...)

  • child_modules (Optional[List[Union[str, Dict[str, Any]]]]) – Child modules that can be executed in parallel

Lookup Resolution

Keyword / Directive

Support

name

None

path

env lookup, var lookup

class_path

env lookup, var lookup

environments

env lookup, var lookup

env_vars

env lookup, var lookup

options

env lookup, var lookup

parameters

env lookup, var lookup

tags

None

References

Path

Runway configuration path settings object.

Path is responsible for parsing the path property of a Runway configuration. It then can determine if the path specified is locally sourced or remotely sourced through a service such as Git or S3.

Local path variables are defined relative to the root project folder. The value for this cannot be higher than the Runway config file, it must be at the runway file itself or in a sub directory.

Example

deployments:
- modules:
    - path: my/local/module.cfn
    - my/local/module.cfn # same as above
    - ./ # module is in the root

When the path is remote, Runway is responsible for fetching the resource and returning the location of it’s cached path. The information for retrieving those sources can be controlled via runway rather than manually retrieving each one.

Example

deployments:
- modules:
    - path: git::git://github.com/your_handle/your_repo.git//my-module.cfn

The path structure is based on the encoding found in Terraform modules.

The values parsed from the string are as follows:

source

Determine if the source is local or remote. The initial prefix is used to determine this separated by :: in the string. A path is considered local if it contains no source type value.

Example

deployments:
    - modules:
        # source is `git`
        - path: git::git://github.com/foo/bar.git

uri

The uniform resource identifier when targetting a remote resource. This instructs runway on where to retrieve your module.

Example

deployments:
    - modules:
        # uri is `git://github.com/foo/bar.git`
        - path: git::git://github.com/foo/bar.git

location

The relative location of the module files from the root directory. This value is specified as a path after the uri separated by //

Example

deployments:
    - modules:
        # location is `my/path`
        - path: git::git://github.com/foo/bar.git//my/path

options

The remaining options that are passed along to the Source. This is specified in the path following the ? separator. Multiple option keys and values can be specified with the & as the separator. Each remote source can have different options for retrieval, please make sure to review individual source types to get more information on properly formatting.

Example

deployments:
    - modules:
        # options are `foo=bar&ba=bop`
        - path: git::git://github.com/foo/bar.git//my/path?foo=bar&baz=bop

Git

Git remote resources can be used as modules for your Runway project. Below is an example of git remote path.

Example

deployments:
    - modules:
        - git::git://github.com/foo/bar.git//my/path?branch=develop

The path is broken down into the following attributes:

git: The type of remote resource being retrieved, in this case git

::: Logical separator of the type from the rest of the path string

git://github.com/foo/bar.git: The protocol and URI address of the git repository

// (optional): Logical separator of the URI from the remaining path string

my/path (optional): The relative path from the root of the repo where the module is housed

? (optional): Logical separator of the path from the options

branch=develop (optional): The options to be passed. The Git module accepts three different types of options: commit, tag, or branch. These respectively point the repository at the reference id specified.

Type

Runway configuration type settings object.

The type property of a Runway configuration can be used to explicitly specify what module type you are intending to deploy.

Runway determines the type of module you are trying to deploy in 3 different ways. First, it will check for the type property as described here, next it will look for a suffix as described in Module Definition, and finally it will attempt to autodetect your module type by scanning the files of the project. If none of those settings produces a valid result an error will occur. The following are valid explicit types:

Type

IaC Tool/Framework

cdk

AWS CDK

cloudformation

CloudFormation

serverless

Serverless Framework

terraform

Terraform

kubernetes

Kubernetes

static

Static Site

Even when specifying a module type the module structure needs to be conducive with that type of project. If the files contained within don’t match the type then an error will occur.

Test

class runway.config.TestDefinition(name, test_type, args=None, required=True)[source]

Tests can be defined as part of the Runway config file.

This is to remove the need for complex Makefiles or scripts to initiate test runners. Simply define all tests for a project in the Runway config file and use the runway test command to execute them.

Example

tests:
  - name: my-test
    type: script
    required: false
    args:
      commands:
        - echo "Hello World!"
Keyword Arguments
  • name (str) – Name of the test. Used to more easily identify where different tests begin/end in the logs.

  • type (str) – The type of test to run. See Build-in Test Types for supported test types.

  • args (Optional[Dict[str, Any]]) – Arguments to be passed to the test. Supported arguments vary by test type. See Build-in Test Types for the list of arguments supported by each test type.

  • required (bool) – If false, testing will continue if the test fails. (default: true)

Lookup Resolution

Note

Runway does not set AWS_REGION or AWS_DEFAULT_REGION environment variables. If the DEPLOY_ENVIRONMENT environment variable is not manually set, it will always be test and is not determined from the branch or directory.

Keyword / Directive

Support

args

env lookup, var lookup

required

env lookup, var lookup

References

Variables

class runway.config.VariablesDefinition(file_path=None, sys_path=None, **kwargs)[source]

A variable definitions for the Runway config file.

Runway variables are used to fill values that could change based on any number of circumstances. They can also be used to simplify the Runway config file by pulling lengthy definitions into another file. Variables can be used in the config file by providing the var lookup to any keyword/directive that supports Lookups.

By default, Runway will look for and load a runway.variables.yml or runway.variables.yaml file that is in the same directory as the Runway config file. The file path and name of the file can optionally be defined in the config file. If the file path is explicitly provided and the file can’t be found, an error will be raised.

Variables can also be defined in the Runway config file directly. This can either be in place of a dedicated variables file, extend an existing file, or override values from the file.

Lookup Resolution

Runway lookup resolution is not supported within the variables definition block or variables file. Attempts to use Runway Lookups within the variables definition block or variables file will result in the literal value being processed.

Example

variables:
  sys_path: ./  # defaults to the current directory
  file_path: secrets.yaml
  # define additional variables or override those in the variables file
  another_var: some_value
deployments:
  - modules:
      - ${var sampleapp.definition}
    regions: ${var sampleapp.regions}
Keyword Arguments
  • file_path – Explicit path to a variables file. If it cannot be found Runway will exit.

  • sys_path – Directory to base relative paths off of.

Sample

runway.yml

---
# Order that tests will be run. Test execution is triggered with the
# 'runway test' command. Testing will fail and exit if any of the
# individual tests fail unless they are marked with 'required: false'.
# Please see the doc section dedicated to tests for more details.

tests:
  - name: test-names-are-optional
    type: script  # there are a few built in test types
    args:  # each test has their own set of arguments they can accept
      commands:
        - echo "Beginning a test..."
        - cd app.sls && npm test && cd ..
        - echo "Test complete!"
  - name: unimportant-test
    type: cfn-lint
    required: false  # tests will still pass if this fails
  - type: yamllint  # not all tests accept arguments

# Order that modules will be deployed. A module will be skipped if a
# corresponding environment file is not present or "enabled" is false.
# E.g., for cfn modules, if
# 1) a dev-us-west-2.env file is not in the 'app.cfn' folder when running
#    a dev deployment of 'app' to us-west-2,
# and
# 2) "enabled" is false under the deployment or module
#
# then it will be skipped.

deployments:
  - modules:
      - myapp.cfn
    regions:
      - us-west-2

  - name: terraformapp  # deployments can optionally have names
    modules:
      - myapp.tf
    regions:
      - us-east-1
    assume_role:  # optional
      # When running multiple deployments, post_deploy_env_revert can be used
      # to revert the AWS credentials in the environment to their previous
      # values
      # post_deploy_env_revert: true
      arn: ${var assume_role.${env DEPLOY_ENVIRONMENT}}
      # duration: 7200

    # Parameters (e.g. values for CFN .env file, TF .tfvars) can
    # be provided at the deployment level -- the options will be applied to
    # every module
    parameters:
      region: ${env AWS_REGION}
      image_id: ${var image_id.${env DEPLOY_ENVIRONMENT}}

    # AWS account alias can be provided to have Runway verify the current
    # assumed role / credentials match the necessary account
    account_alias: ${var account_alias.${env DEPLOY_ENVIRONMENT}}  # optional

    # AWS account id can be provided to have Runway verify the current
    # assumed role / credentials match the necessary account
    account_id: ${var account_id.${env DEPLOY_ENVIRONMENT}}  # optional

    # env_vars set OS environment variables for the module (not logical
    # environment values like those in a CFN .env or TF .tfvars file).
    # They should generally not be used (they are provided for use with
    # tools that absolutely require it, like Terraform's
    # TF_PLUGIN_CACHE_DIR option)
    env_vars:  # optional environment variable overrides
      AWS_PROFILE: ${var envvars.profile.${env DEPLOY_ENVIRONMENT}}
      APP_PATH: ${var envvars.app_path}
      ANOTHER_VAR: foo

  # Start of another deployment
  - modules:
      - path: myapp.cfn
        # Parameters (e.g. values for CFN .env file, TF .tfvars) can
        # be provided for a single module (replacing or supplementing the
        # use of environment/tfvars/etc files in the module)
        parameters:
          region: ${env AWS_REGION}
          image_id: ${var image_id.${env DEPLOY_ENVIRONMENT}}
        tags:  # Modules can optionally have tags.
          # This is a list of strings that can be "targeted"
          # by passing arguments to the deploy/destroy command.
          - some-string
          - app:example
          - tier:web
          - owner:onica
          # example: `runway deploy --tag app:example --tag tier:web`
          #   This would select any modules with BOTH app:example AND tier:web
    regions:
      - us-west-2

# If using environment folders instead of git branches, git branch lookup can
# be disabled entirely (see "Repo Structure")
# ignore_git_branch: true

runway.variables.yml

account_alias:
  dev: my_dev_account
  prod: my_dev_account
account_id:
  dev: 123456789012
  prod: 345678901234
assume_role:
  dev: arn:aws:iam::account-id1:role/role-name
  prod: arn:aws:iam::account-id2:role/role-name
image_id:
  dev: ami-abc123
envvars:
  profile:
    dev: foo
    prod: bar
  app_path:
    - myapp.tf
    - foo