runway.config module¶

Runway config file module.

class runway.config.ConfigComponent(**kwargs)[source]¶

Bases: runway.util.MutableMap

Base class for Runway config components.

SUPPORTS_VARIABLES¶: A list of directives that support the use of variable.

PRE_PROCESS_VARIABLES¶: A list of directives that support the use of variables and needs to be resolved before the component is processed.

Initialize class.

Provided kwargs are added to the object as attributes.

Example

SUPPORTS_VARIABLES = ['env_vars', 'environments', 'parameters']

PRE_PROCESS_VARIABLES = []

property data¶

Sanitized output of __dict__ with properties added.

Removes anything that starts with _.

property env_vars¶: Access the value of an attribute that supports variables.

property environments¶: Access the value of an attribute that supports variables.

property parameters¶: Access the value of an attribute that supports variables.

get(key, default=None)[source]¶: Implement evaluation of get.

resolve(context, variables=None, pre_process=False)[source]¶

Resolve attributes that support variables.

Parameters

context – The current context object.
variables – Object containing variables passed to Runway.
pre_process – Only resolve the variables that are required before the component is processed. If this is False, all variables will be resolved. This is useful to prevent errors when variables cannot be resolved because the values are not populated until processing has begun.

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]¶

Bases: runway.config.ConfigComponent

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

`AWS CDK`_
`CloudFormation`_
`Serverless Framework`_
`CFNgin`_
`Troposphere`_
`Terraform`_
`Kubernetes`_
Static Site
Module Configurations - detailed module options
Repo Structure - examples of directory structure
deploy
destroy
plan

SUPPORTS_VARIABLES = ['class_path', 'env_vars', 'environments', 'options', 'parameters', 'path']¶

property class_path¶: Access the value of an attribute that supports variables.

property menu_entry¶: Return menu entry representation of this module.

property options¶: Access the value of an attribute that supports variables.

property path¶: Access the value of an attribute that supports variables.

classmethod from_list(modules)[source]¶: Instantiate ModuleDefinition from a list.

class runway.config.FutureDefinition(strict_environments=False, **kwargs)[source]¶

Bases: runway.util.MutableMap

Opt-in to future functionality before the next major release.

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

Lookups are not supported as these values should be static.

Instantiate class.

Keyword Arguments: strict_environments (bool) – Wether to enable strict environments.

enabled¶

Decorator for creating cached properties.

A property that is only computed once per instance and then replaces itself with an ordinary attribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/fa7733e075da0d790d809aa3d2f53071897e6f76

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

Bases: runway.config.ConfigComponent

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

SUPPORTS_VARIABLES = ['account_alias', 'account_id', 'assume_role', 'env_vars', 'environments', 'module_options', 'regions', 'parallel_regions', 'parameters']¶

PRE_PROCESS_VARIABLES = ['account_alias', 'account_id', 'assume_role', 'env_vars', 'regions']¶

property account_alias¶: Access the value of an attribute that supports variables.

property account_id¶: Access the value of an attribute that supports variables.

property assume_role¶: Access the value of an attribute that supports variables.

property menu_entry¶: Return menu entry representation of this deployment.

property module_options¶: Access the value of an attribute that supports variables.

property regions¶: Access the value of an attribute that supports variables.

property parallel_regions¶: Access the value of an attribute that supports variables.

reverse()[source]¶: Reverse the order of modules and regions.

classmethod from_list(deployments)[source]¶: Instantiate DeploymentDefinitions from a list.

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

Bases: runway.config.ConfigComponent

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

Build-in Test Types - Supported test types and their arguments
test command

SUPPORTS_VARIABLES = ['args', 'required']¶

property args¶: Access the value of an attribute that supports variables.

property required¶: Access the value of an attribute that supports variables.

classmethod from_list(tests)[source]¶: Instantiate TestDefinitions from a list.

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

Bases: runway.util.MutableMap

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.

default_names = ['runway.variables.yml', 'runway.variables.yaml']¶

classmethod find_file(file_path=None, sys_path=None)[source]¶

Find a Runway variables file.

Parameters

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.

Returns

Verified path to a file.

Raises

TypeError – file_path or sys_path is not a string.

classmethod load(**kwargs)[source]¶: Load variables.

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

Bases: runway.config.ConfigComponent

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

accepted_names = ['runway.yml', 'runway.yaml']¶

classmethod load_from_file(config_path)[source]¶: Load config file into a Config object.

classmethod find_config_file(config_dir=None)[source]¶: Find the Runway config file.