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 *
account_id *
assume_role *
env_vars *
environments
module_options
parallel_regions *
parameters
regions *

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
env_vars
environments
options
parameters
path

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:

test.args
test.required

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