Runway Config File

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 the modules to be deployed.

Top-Level Configuration

deployments: List[deployment]

A list of deployments that will be processed in the order they are defined. See Deployment for detailed information about defining this value.

Example

deployments:
  - name: example
    modules:
      - sampleapp-01.cfn
      - path: sampleapp-02.cfn
    regions:
      - us-east-1
ignore_git_branch: bool = false

Optionally exclude the git branch name when determining the current deploy environment.

This can be useful when using the directory name or environment variable to set the deploy environment to ensure the correct value is used.

Example

ignore_git_branch: true

Note

The existence of DEPLOY_ENVIRONMENT in the environment will automatically ignore the git branch.

runway_version: str = ">=1.10.0"

Define the versions of Runway that can be used with this configuration file.

The value should be a PEP 440 compliant version specifier set.

Example

greater than or equal to 1.14.0
runway_version: ">=1.14.0"
explicit version
runway_version: "==14.0.0"
greater than or equal to 1.14.0 but less than 2.0.0
runway_version: ">=1.14.0,<2.0.0"  # or ~=1.14.0

New in version 1.11.0.

tests: Optional[List[test]] = []

List of Runway test definitions that are executed with the test command command. See Test for detailed information about defining this value.

Example

tests:
  - name: Hello World
    type: script
    args:
      commands:
        - echo "Hello World"
variables: Optional[Dict[str, Any]] = {}

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 YAML file. Variables can be consumed in the config file by using the var lookup in any field 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.

Important

The variables and the variables file cannot contain lookups. If there is a lookup string in either of these locations, they will not be resolved.

Example

deployments:
  - modules:
      - path: sampleapp.cfn
    env_vars: ${var env_vars}  # exists in example-file.yml
    parameters:
      namespace: ${var namespace}-${env DEPLOY_ENVIRONMENT}
    regions: ${var regions.${env DEPLOY_ENVIRONMENT}}

variables:
  file_path: example-file.yml
  namespace: example
  regions:
    dev:
      - us-east-1
      - us-west-2
variables.file_path: Optional[str]

Explicit path to a variables file that will be loaded and merged with the variables defined here.

Example

variables:
  file_path: some-file.yml
variables.sys_path: Optional[str] = ./

Directory to use as the root of a relative variables.file_path. If not provided, the current working directory is used.

Example

variables:
  sys_path: ./../variables

Deployment

class deployment

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 (--ci cli option) is set, the --tag <tag>... cli option was provided, or only one deployment is defined.

Lookup Support

Important

Due to how a deployment is processed, some values are resolved twice. Once before processing and once during processing.

Because of this, the fields that are resolved before processing begins will not have access to values set during processing like AWS_REGION, AWS_DEFAULT_REGION, and DEPLOY_ENVIRONMENT for the pre-processing resolution which can result in a FailedLookup error. To avoid errors during the first resolution due to the value not existing, provide a default value for the Lookup.

The values mentioned will be set before the second resolution when processing begins. This ensures that the correct values are passed to the module.

Impacted fields are marked with an asterisk (*).

The following fields support lookups:

account_alias: Optional[str] = None

An AWS account alias use to verify the currently assumed role or credentials. Verification is performed by listing the account’s alias and comparing the result to what is defined. This requires the credentials being used to have iam:ListAccountAliases permissions.

Example

using a literal value
deployments:
  - account_alias: example-dev
using a lookup
deployments:
  - account_alias: example-${env DEPLOY_ENVIRONMENT}
  - account_alias: ${var account_alias.${env DEPLOY_ENVIRONMENT}}

variables:
  account_alias:
    dev: example-dev

Changed in version 2.0.0: No longer accepts a typing.Dict.

account_id: Optional[str] = None

An AWS account ID use to verify the currently assumed role or credentials. Verification is performed by getting the caller identity. This does not required any added permissions as it is allowed by default. However, it does require that sts:GetCallerIdentity is not explicitly denied.

Example

using a literal value
deployments:
  - account_id: 123456789012
using a lookup
deployments:
  - account_id: ${var account_id.${env DEPLOY_ENVIRONMENT}}

variables:
  account_id:
    dev: 123456789012

Changed in version 2.0.0: No longer accepts a typing.Dict.

assume_role: Optional[assume_role_definition, str] = {}

Assume an AWS IAM role when processing the deployment. The credentials being used prior to assuming the role must to iam:AssumeRole permissions for the role provided.

Example

using a literal value
deployments:
  - assume_role: arn:aws:iam::123456789012:role/name
using a lookup in a detailed definition
deployments:
  - assume_role:
      arn: ${var assume_role.${env DEPLOY_ENVIRONMENT}}
      post_deploy_env_revert: True

variables:
  assume_role:
    dev:
      arn:aws:iam::123456789012:role/name

Changed in version 2.0.0: No longer accepts a typing.Dict defining a value per deploy environment.

class assume_role_definition
arn: str

The ARN of the AWS IAM role to be assumed.

duration: int = 3600

The duration, in seconds, of the session.

post_deploy_env_revert: bool = false

Revert the credentials stored in environment variables to what they were prior to execution after the deployment finished processing.

session_name: str = runway

An identifier for the assumed role session.

env_vars: Optional[Dict[str, Union[List[str], str]]] = {}

Additional variables to add to the environment when processing the deployment.

Anything defined here is merged with the value of module.env_vars.

Example

using a lookup as the value
deployments:
  - env_vars:
      NAME: value
      KUBECONFIG:
        - .kube
        - ${env DEPLOY_ENVIRONMENT}
        - config
using a lookup in the value
deployments:
  - env_vars: ${var env_vars.${env DEPLOY_ENVIRONMENT}}

variables:
  env_vars:
    dev:
      NAME: value

Changed in version 2.0.0: No longer accepts a typing.Dict defining a value per deploy environment. The entire value of the field is used for all environments.

environments: Optional[Dict[str, Union[bool, List[str], str]]] = {}

Explicitly enable/disable the deployment for a specific deploy environment, AWS Account ID, and AWS Region combination. Can also be set as a static boolean value.

Anything defined here is merged with the value of module.environments.

Example

deployments:
  - environments:
      dev: True
      test: 123456789012
      qa: us-east-1
      prod:
        - 123456789012/ca-central-1
        - us-west-2
        - 234567890123
using a lookup as the value
deployments:
  - environments: ${var environments}

variables:
  environments:
    dev: True

Changed in version 1.4.0: Now acts as an explicit toggle for deploying modules to a set AWS Account/AWS Region. For passing values to a module, deployment.parameters/module.parameters should be used instead.

Changed in version 2.0.0: If defined and the current deploy environment is missing from the definition, processing will be skipped.

modules: List[Union[module, str]]

A list of modules to process as part of a deployment.

Example

deployments:
  - modules:
      - sampleapp-01.cfn
      - path: sampleapp-02.cfn
module_options: Optional[Union[Dict[str, Any], str]] = {}

Options that are passed directly to the modules within this deployment.

Anything defined here is merged with the value of module.options.

Example

deployments:
  - module_options:
      example: value
using a lookup as the value
deployments:
  - module_options:
      example: ${var example}

variables:
  example: value
using a lookup in the value
deployments:
  - module_options: ${var parameters}

variables:
  parameters:
    example: value
name: Optional[str] = None

The name of the deployment to be displayed in logs and the interactive selection menu.

Example

deployments:
  - name: networking
parallel_regions: Optional[Union[List[str], str]] = []

A list of AWS Regions to process asynchronously.

Only one of parallel_regions or regions can be defined.

Asynchronous deployment only takes effect when running non-interactively. Otherwise processing will occur synchronously.

assume_role.post_deploy_env_revert will always be true when run in parallel.

Can be used in tandem with module.parallel.

Example

using a lookup as the value
deployments:
  - parallel_regions:
      - us-east-1
      - us-west-2
      - ${var third_region.${env DEPLOY_ENVIRONMENT}}

variables:
  third_region:
    dev: ca-central-1
using a lookup in the value
deployments:
    - parallel_regions: ${var regions.${env DEPLOY_ENVIRONMENT}}

  variables:
    regions:
      - us-east-1
      - us-west-2

New in version 1.3.0.

parameters: Optional[Union[Dict[str, Any], str]] = {}

Used to pass variable values to modules in place of an environment configuration file.

Anything defined here is merged with the value of module.parameters.

Example

using a lookup as the value
deployments:
  - parameters:
      namespace: example-${env DEPLOY_ENVIRONMENT}
using a lookup in the value
deployments:
  - parameters: ${var parameters.${env DEPLOY_ENVIRONMENT}}

variables:
  parameters:
    dev:
      namespace: example-dev

New in version 1.4.0.

regions: Optional[Union[Dict[str, Union[List[str], str], List[str], str]] = []

A list of AWS Regions to process this deployment in.

Only one of parallel_regions or regions can be defined.

Can be used to define asynchronous processing similar to parallel_regions.

Example

synchronous
deployments:
  - regions:
      - us-east-1
      - us-west-2
asynchronous
deployments:
  - regions:
      parallel:
        - us-east-1
        - us-west-2
        - ${var third_region.${env DEPLOY_ENVIRONMENT}}

variables:
  third_region:
    dev: ca-central-1
using a lookup in the value
deployments:
    - regions: ${var regions.${env DEPLOY_ENVIRONMENT}}

  variables:
    regions:
      - us-east-1
      - us-west-2

Module

class module

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

It can consist of CloudFormation, 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

.k8s

Kubernetes

.sls

Serverless Framework

.tf

Terraform

.web

Static Site

A module is only deployed if there is a corresponding environment file present, it is explicitly enabled via deployment.environments/module.environments, or deployment.parameters/module.parameters is defined. The naming format of an environment file 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.

Using a mapping to define a module provides the ability to specify all the fields listed here.

Lookup Support

The following fields support lookups:

class_path: Optional[str] = null

Note

Most users will never need to use this. It is only used for custom module type handlers.

Import path to a custom Runway module handler class. See Module Configurations for detailed usage.

Example

deployments:
  - modules:
    - class_path: runway.module.cloudformation.CloudFormation
env_vars: Optional[Dict[str, Union[List[str], str]]] = {}

Additional variables to add to the environment when processing the deployment.

Anything defined here is merged with the value of deployment.env_vars. Values defined here take precedence.

Example

using a lookup as the value
deployments:
  - modules:
    - env_vars:
        NAME: VALUE
        KUBECONFIG:
          - .kube
          - ${env DEPLOY_ENVIRONMENT}
          - config
using a lookup in the value
deployments:
  - modules:
      - env_vars: ${var env_vars.${env DEPLOY_ENVIRONMENT}}

variables:
  env_vars:
    dev:
      NAME: value

Changed in version 2.0.0: No longer accepts a typing.Dict defining a value per deploy environment. The entire value of the field is used for all environments.

environments: Optional[Dict[str, Union[bool, List[str], str]]] = {}

Explicitly enable/disable the deployment for a specific deploy environment, AWS Account ID, and AWS Region combination. Can also be set as a static boolean value.

Anything defined here is merged with the value of deployment.environments. Values defined here take precedence.

Example

deployments:
  - modules:
    - environments:
      dev: True
      test: 123456789012
      qa: us-east-1
      prod:
        - 123456789012/ca-central-1
        - us-west-2
        - 234567890123
using a lookup as the value
deployments:
  - modules:
    - environments: ${var environments}

variables:
  environments:
    dev: True

Changed in version 1.4.0: Now acts as an explicit toggle for deploying modules to a set AWS Account/AWS Region. For passing values to a module, deployment.parameters/module.parameters should be used instead.

Changed in version 2.0.0: If defined and the current deploy environment is missing from the definition, processing will be skipped.

name: Optional[str]

The name of the module to be displayed in logs and the interactive selection menu.

If a name is not provided, the path value is used.

Example

deployments:
  - modules:
    - name: networking
options: Optional[Union[Dict[str, Any], str]] = {}

Options that are passed directly to the module type handler class.

The options that can be used with each module vary. For detailed information about options for each type of module, see Module Configurations.

Anything defined here is merged with the value of deployment.module_options. Values defined here take precedence.

Example

deployments:
  - module:
    - options:
        example: value
using a lookup as the value
deployments:
  - module:
    - options:
        example: ${var example}

variables:
  example: value
using a lookup in the value
deployments:
  - module:
    - options: ${var parameters}

variables:
  parameters:
    example: value
parallel: Optional[List[module]] = []

List of module definitions that can be executed asynchronously.

Incompatible with class_path, path, and type.

Asynchronous deployment only takes effect when running non-interactively. Otherwise processing will occur synchronously.

Example

deployments:
  - modules:
    - parallel:
      - path: sampleapp-01.cfn
      - path: sampleapp-02.cfn
parameters: Optional[Union[Dict[str, Any], str]] = {}

Used to pass variable values to modules in place of an environment configuration file.

Anything defined here is merged with the value of deployment.parameters. Values defined here take precedence.

Example

using a lookup as the value
deployments:
  - modules:
    - parameters:
        namespace: example-${env DEPLOY_ENVIRONMENT}
using a lookup in the value
deployments:
  - modules:
    - parameters: ${var parameters.${env DEPLOY_ENVIRONMENT}}

variables:
  parameters:
    dev:
      namespace: example-dev

New in version 1.4.0.

path: Optional[Union[str, Path]]

Directory (relative to the Runway config file) containing IaC. The directory can either be on the local file system or a network accessible location.

See path for more detailed information.

Example

using a lookup
deployments:
  - modules:
    - path: sampleapp-${env DEPLOY_ENVIRONMENT}.cfn

New in version 1.4.0.

tags: Optional[List[str]] = []

A list of strings to categorize the module which can be used with the CLI to quickly select a group of modules.

This field is only used by the --tag CLI option.

Example

deployments:
  - modules:
    - tags:
      - app:sampleapp
      - type:network
type: Optional[str]

Explicitly define the type of IaC contained within the directory. This can be useful when Runway fails to automatically determine the correct module type.

Accepted Values

  • cdk

  • cloudformation

  • kubernetes

  • serverless

  • terraform

  • static

Example

deployments:
  - modules:
    - type: static

New in version 1.4.0.

path

path can either be defined as a local path relative to the Runway config file or a network accessible (remote) location.

When the value is identified as a remote location, Runway is responsible for retrieving resources from the location and caching them locally for processing. This allows the remote resources to be handled automatically by Runway rather than needing to manually retrieve them or employ another mechanism to retrieve them.

Remote Location Syntax

The syntax is based on that of Terraform module sources.

${source}::${uri}//${location}?${arguments}
source

Combined with the following :: separator, it is used to identify the location as remote. The value determines how Runway with handle retrieving resources from the remote location.

uri

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

location

An optional location within the remote location (assessed after the resources have been retrieve) relative to the root of the retrieve resources.

This field is preceded by a //. If not defining a location, this separator does not need to be provided.

arguments

An optional ampersand (&) delimited list of key=value pairs that are unique to each remote location source. These are used to provide granular control over how Runway retrieves resources from the remote location.

This field is preceded by a ?. If not defining a location, this separator does not need to be provided.

Remote Location Sources

Git Repository

Runway can retrieve a git repository to process modules contained within it. Below is an example of using a module in a git repository as well as a breakdown of the values being provided to each field.

deployments:
    - modules:
        # ${source}::${uri}//${location}?${arguments}
        - path: git::git://github.com/foo/bar.git//my/path?branch=develop

Field

Value

Description

source

git

The type of remote location source.

uri

git://github.com/foo/bar.git

The protocol and URI address of the git repository.

location

my/path

The relative path from the root of the repo where
the module is located. (optional)

arguments

branch=develop

After cloning the repository, checkout the develop
branch. (optional)

Arguments

branch

Name of a branch to checkout after cloning the git repository.

Only one of branch, commit, or tag can be defined. If none are defined, HEAD is used.

commit

After cloning the git repository, reset HEAD to the given commit hash.

Only one of branch, commit, or tag can be defined. If none are defined, HEAD is used.

tag

After cloning the git repository, reset HEAD to the given tag.

Only one of branch, commit, or tag can be defined. If none are defined, HEAD is used.


Test

class test

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 test command to execute them.

Lookup Support

Note

Runway does not set AWS_REGION or AWS_DEFAULT_REGION environment variables when using the test command.

The following fields support lookups:

args: Optional[Union[Dict[str, Any], str]] = {}

Arguments to be passed to the test. Supported arguments vary by test type. See Build-in Test Types for the arguments supported by each test type.

Example

tests:
  - args:
      commands:
        - echo "Hello world"
name: Optional[str]

Name of the test. Used to more easily identify where different tests begin/end in the logs and to identify which tests failed.

Example

tests:
  - name: example-test
required: bool = false

Whether the test must pass for subsequent tests to be run. If false, testing will continue if the test fails.

If the test fails, the test command will always return a non-zero exit code regardless of this value.

Example

using a literal value
tests:
  - required: false
using a lookup
tests:
  - required: ${var test.required}

variables:
  test:
    required: false
type: str

The type of test to run.

Accepted Values

Example

tests:
  - type: script