runway Documentation
Release 1.18.3
Onica Group
Jun 04, 2021
RUNWAY
1 Installation 3
1.1 cURL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 npm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3 pip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.4 Why Version Lock Per-Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2 Getting Started Guide 7
2.1 Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.2 Deploying Your First Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.3 Deleting Your First Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.4 Execution Without A TTY (non-interactive) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3 Quickstart Guides 11
3.1 CloudFormation Quickstart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.2 Conduit (Serverless & CloudFront) Quickstart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.3 Other Ways to Use Runway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.4 Private Static Site (Auth@Edge) Quickstart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4 Commands 27
4.1 deploy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.2 destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
4.3 dismantle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
4.4 envvars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
4.5 docs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
4.6 gen-sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
4.7 init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.8 kbenv install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.9 kbenv run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
4.10 plan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
4.11 preflight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
4.12 run-aws . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
4.13 run-python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
4.14 run-stacker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.15 takeoff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.16 taxi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
4.17 test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
4.18 tfenv install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
4.19 tfenv run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.20 whichenv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
i
5 Runway Config File 43
5.1 Top-Level Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
5.2 Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
5.3 Future . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
5.4 Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
5.5 Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
5.6 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
5.7 Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
6 Lookups 59
6.1 Lookup Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
6.2 Built-in Lookups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
7 Defining Tests 65
7.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
7.2 Built-in Test Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
8 Repo Structure 69
8.1 Git Branches as Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
8.2 Directories as Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
8.3 Directories as Environments with a Single Module . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
9 Module Configuration 71
9.1 AWS Cloud Development Kit (CDK) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
9.2 CloudFormation & Troposphere . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
9.3 Kubernetes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
9.4 Serverless Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
9.5 Static Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
9.6 Terraform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
10 Indices and tables 367
Python Module Index 369
Index 371
ii
runway Documentation, Release 1.18.3
Runway is a lightweight wrapper around infrastructure deployment (e.g. CloudFormation, Terraform, Serverless) &
linting (e.g. yamllint) tools to ease management of per-environment configs & deployment.
Very simple configuration to:
• Perform automatic linting/verification
• Ensure deployments are only performed when an environment config is present
• Define an IAM role to assume for each deployment
• Wrangle Terraform backend/workspace configs w/ per-environment tfvars
• Avoid long-term tool lock-in
– Runway is a simple wrapper around standard tools. It simply helps to avoid convoluted Makefiles / CI jobs
RUNWAY 1
runway Documentation, Release 1.18.3
2 RUNWAY
CHAPTER
ONE
INSTALLATION
To enable Runway to conform to our users’ varying use cases, we have made it available via three different install
methods - cURL, npm, and pip.
1.1 cURL
Arguably the easiest way to install Runway is by using curl. Use one of the endpoints below to download a single-
binary executable version of Runway based on your operating system.
Operating System Endpoint
Linux https://oni.ca/runway/latest/linux
macOS https://oni.ca/runway/latest/osx
Windows https://oni.ca/runway/latest/windows
$ curl -L https://oni.ca/runway/latest/osx -o runway
Note: To install a specific version of Runway, you can replace latest with a version number.
Usage
To use the single-binary, run it directly as shown below. Please note that after download, you may need to adjust the
permissions before it can be executed. (eg. macOS/Ubuntu:chmod +x runway)
$ ./runway deploy
Suggested use: CloudFormation or Terraform projects
3
runway Documentation, Release 1.18.3
1.2 npm
Runway is published on npm as @onica/runway. It currently contains binaries to support macOS, Ubuntu, and
Windows.
While Runway can be installed globally like any other npm package, we strongly recommend using it per-project as a
dev dependency. See Why Version Lock Per-Project for more info regarding this suggestion.
$ npm i -D @onica/runway
Usage
$ npx runway deploy
Suggested use: Serverless or AWS CDK projects
1.3 pip
Runway runs on Python 2.7 and Python 3.5+.
Runway is hosted on PyPI as the package named runway. It can be installed like any other Python package, but
we instead strongly recommend using it per-project with pipenv. See Why Version Lock Per-Project for more info
regarding this suggestion.
Suggested use: Python projects
1.3.1 Version Locking with Pipenv
In your project’s directory, execute pipenv install runway. This will:
1. Update (creating if missing) a Pipfile file with your project’s Runway dependency
2. Create a Python virtual environment (hidden in your user profile folder) dedicated to your project, with Runway
installed in it
3. Update (creating if missing) a Pipfile.lock file containing the exact versions/crypto-hashes of Runway
(and dependencies) installed in your python virtual environment
Now Runway can be used in the project via pipenv run runway ... (e.g. pipenv run runway
takeoff).
To ensure future users of the project use the same version of Runway, direct them (e.g. via a Makefile) to invoke it via
pipenv sync; pipenv run Runway ... – this will ensure the version in their virtual environment is kept
in sync with the project’s lock file.
4 Chapter 1. Installation
runway Documentation, Release 1.18.3
1.3.2 Troubleshooting
Pipenv Not Found
If pipenv isn’t available after installation (via pip install --user pipenv, see the python-setup guide.
1.4 Why Version Lock Per-Project
Locking the version of Runway per-project will allow you to:
• Specify the version(s) of Runway compatible with your deployments config
• Ensure Runway executions are performed with the same version (regardless of where/when they occur – avoids
the dreaded “works on my machine”)
1.4. Why Version Lock Per-Project 5
runway Documentation, Release 1.18.3
6 Chapter 1. Installation
CHAPTER
TWO
GETTING STARTED GUIDE
2.1 Basic Concepts
Welcome to Runway! To get a basic understanding of Runway, we have listed out the key concepts below that you
will need to get started with deploying your first module.
2.1.1 Runway Config File
The Runway config file is usually stored at the root of a project repo. It defines the modules that will be managed by
Runway.
2.1.2 Deployment
A deployment contains a list of modules and options for all the modules in the deployment. A Runway config file can
contain multiple deployments and a deployment can contain multiple modules.
2.1.3 Module
A module is a directory containing a single infrastructure-as-code tool configuration of an application, a component,
or some infrastructure (eg. a set of CloudFormation templates). It is defined in a deployment by path. Modules can
also contain granular options that only pertain to it.
2.1.4 Environment
Environments are used for selecting the options/variables/parameters to be used with each modules. They can be de-
fined by the name of a directory (if its not a git repo), git branch, or environment variable (DEPLOY_ENVIRONMENT).
Standard environments would be something like prod, dev, and test.
No matter how the environment is determined, the name is made available to be consumed by your modules as the
DEPLOY_ENVIRONMENT environment variable.
7
runway Documentation, Release 1.18.3
2.2 Deploying Your First Module
1. Create a directory for our project and change directory into the new directory.
# macOS example
$ mkdir sample-project
$ cd sample-project
2. Initialize the the new directory as a git repo and checkout branch ENV-dev. This will give us an environment of
dev.
# macOS example
$ git init
$ git checkout -b ENV-dev
3. Download Runway using curl. Be sure to use the endpoint that corresponds to your operating system. Then,
change the downloaded file’s permissions to allow execution.
# macOS example
$ curl -L https://oni.ca/runway/latest/osx -o runway
$ chmod +x runway
4. Use Runway to generate a sample module using the gen-sample command. This will give us a preformatted
module that is ready to be deployed after we change a few variables. To read more about the directory structure,
see Repo Structure.
$ ./runway gen-sample cfn
5. To finish configuring our CloudFormation module , lets open the dev-us-east-1.env file that was created
in sampleapp.cfn/. Here is where we will define values for our stacks that will be deployed as part of the
dev environment in the us-east-1 region. Replace the place holder values in this file with your own information.
It is important that the cfngin_bucket_name value is globally unique for this example as it will be used to
create a new S3 bucket.
namespace: onica-dev
customer: onica
environment: dev
region: us-east-1
# The CFNgin bucket is used for CFN template uploads to AWS
cfngin_bucket_name: cfngin-onica-us-east-1
6. With the module ready to deploy, now we need to create our Runway config file. Do to this, use the init command
to generate a sample file at the root of the project repo.
$ ./runway init
runway.yml contents
---
# See full syntax at https://docs.onica.com/projects/runway/en/latest/
deployments:
- modules:
- nameofmyfirstmodulefolder
- nameofmysecondmodulefolder
# - etc...
regions:
- us-east-1
8 Chapter 2. Getting Started Guide
runway Documentation, Release 1.18.3
7. Now, we need to modify the runway.yml file that was just created to tell it where the module is located that
we want it to deploy and what regions it will be deployed to. Each module type has their own configuration
options which are described in more detail in the Module Configurations section but, for this example we are
only concerned with the CloudFormation module configuration.
The end result should like this:
---
# See full syntax at https://docs.onica.com/projects/runway/en/latest/
deployments:
- modules:
- sampleapp.cfn
regions:
- us-east-1
8. Before we deploy, it is always a good idea to know how the module will impact the currently deployed in-
frastructure in your AWS account. This is less of a concern for net-new infrastructure as it is when making
modifications. But, for this example, lets run the plan command to see what is about to happen.
$ ./runway plan
9. We are finally ready to deploy! Use the deploy command to deploy our module.
$ ./runway deploy
We have only scratched the surface with what is possible in this example. Proceed below to find out how to delete the
module we just deployed or, review the pages linked throughout this section to learn more about what we have done
to this point before continuing.
2.3 Deleting Your First Module
From the root of the project directory we created in Deploying Your First Module we only need to run the destroy
command to remove what we have deployed.
$ ./runway destroy
2.4 Execution Without A TTY (non-interactive)
Runway allows you to set an environment variable to allow execution without a TTY or if STDIN is closed. This
allows users to execute Runway deployments in their CI/CD infrastructure as code deployment systems avoiding the
EOF when reading a line error message. In order to execute runway without a TTY, set the CI environment
variable before your runway [deploy|destroy] execution.
Important: Executing Runway in this way will cause Runway to perform updates in your environment without
prompt. Use with caution.
2.3. Deleting Your First Module 9
runway Documentation, Release 1.18.3
10 Chapter 2. Getting Started Guide
CHAPTER
THREE
QUICKSTART GUIDES
3.1 CloudFormation Quickstart
1. Prepare the project directory. See Repo Structure for more details.
mkdir my-app
cd my-app
git init
git checkout -b ENV-dev
2. Download/install Runway. Here we are showing the curl option. To see other available install methods, see
Installation.
macOS
$ curl -L https://oni.ca/runway/latest/osx -o runway
$ chmod +x runway
Ubuntu
$ curl -L https://oni.ca/runway/latest/linux -o runway
$ chmod +x runway
Windows
> iwr -Uri oni.ca/runway/latest/windows -OutFile runway.exe
3. Use Runway to generate a sample CloudFormation module, edit the values in the environment file, and create a
Runway config file to use the module.
11
runway Documentation, Release 1.18.3
macOS/Linux
$ runway gen-sample cfn
$ sed -i -e "s/CUSTOMERNAMEHERE/mydemo/g; s/ENVIRONMENTNAMEHERE/dev/g; s/stacker-/
˓→stacker-$(uuidgen|tr "[:upper:]" "[:lower:]")-/g" sampleapp.cfn/dev-us-east-1.
˓→env
$ cat <<EOF >> runway.yml
---
# Full syntax at https://github.com/onicagroup/runway
deployments:
- modules:
- sampleapp.cfn
regions:
- us-east-1
EOF
Windows
$ runway gen-sample cfn
$ (Get-Content sampleapp.cfn\dev-us-east-1.env).replace('CUSTOMERNAMEHERE',
˓→'mydemo') | Set-Content sampleapp.cfn\dev-us-east-1.env
$ (Get-Content sampleapp.cfn\dev-us-east-1.env).replace('ENVIRONMENTNAMEHERE',
˓→'dev') | Set-Content sampleapp.cfn\dev-us-east-1.env
$ (Get-Content sampleapp.cfn\dev-us-east-1.env).replace('stacker-', 'stacker-' +
˓→[guid]::NewGuid() + '-') | Set-Content sampleapp.cfn\dev-us-east-1.env
$ $RunwayTemplate = @"
---
# Full syntax at https://github.com/onicagroup/runway
deployments:
- modules:
- sampleapp.cfn
regions:
- us-east-1
"@
$RunwayTemplate | Out-File -FilePath runway.yml -Encoding ASCII
4. Deploy the stack.
$ runway deploy
Now our stack is available at mydemo-dev-sampleapp, e.g.: aws cloudformation
describe-stack-resources --region us-east-1 --stack-name mydemo-dev-sampleapp
3.2 Conduit (Serverless & CloudFront) Quickstart
3.2.1 Deploying the Conduit Web App
The Medium.com-clone “RealWorld” demo app named Conduit provides a simple demonstration of using Runway to
deploy a Serverless Framework backend with an Angular frontend.
12 Chapter 3. Quickstart Guides
runway Documentation, Release 1.18.3
3.2.2 Prerequisites
• An AWS account, and configured terminal environment for interacting with it with an admin role.
• The following installed tools:
– npm
– yarn
– git (Available out of the box on macOS)
3.2.3 Setup
1. Prepare the project directory. See Repo Structure for more details.
mkdir conduit
cd conduit
git init
git checkout -b ENV-dev
2. Download/install Runway. Here we are showing the curl option. To see other available install methods, see
Installation.
macOS
curl -L https://oni.ca/runway/latest/osx -o runway
chmod +x runway
Ubuntu
curl -L https://oni.ca/runway/latest/linux -o runway
chmod +x runway
Windows
iwr -Uri oni.ca/runway/latest/windows -OutFile runway.exe
3. Download the source files.
macOS/Linux
curl -O https://codeload.github.com/anishkny/realworld-dynamodb-lambda/zip/v1.0.0
unzip v1.0.0
rm v1.0.0
mv realworld-dynamodb-lambda-1.0.0 backend
cd backend
sed -i '/package-lock\.json/d' .gitignore
echo '.dynamodb' >> .gitignore
npm install
cd ..
(continues on next page)
3.2. Conduit (Serverless & CloudFront) Quickstart 13
runway Documentation, Release 1.18.3
(continued from previous page)
curl -O https://codeload.github.com/gothinkster/angular-realworld-example-app/zip/
˓→35a66d144d8def340278cd55080d5c745714aca4
unzip 35a66d144d8def340278cd55080d5c745714aca4
rm 35a66d144d8def340278cd55080d5c745714aca4
mv angular-realworld-example-app-35a66d144d8def340278cd55080d5c745714aca4 frontend
cd frontend
mkdir scripts
cd scripts && { curl -O https://raw.githubusercontent.com/onicagroup/runway/
˓→master/quickstarts/conduit/build.js ; cd -; }
sed -i 's/^\s
*
"build":\s.
*
$/ "build": "node scripts\/build",/' package.json
sed -i 's/^\s
*
"rxjs":\s.
*
$/ "rxjs": "~6.3.3",/' package.json
npm install
curl -O https://raw.githubusercontent.com/onicagroup/runway/master/quickstarts/
˓→conduit/update_env_endpoint.py
cd ..
curl -O https://raw.githubusercontent.com/onicagroup/runway/master/quickstarts/
˓→conduit/runway.yml
Windows
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
Invoke-WebRequest https://codeload.github.com/anishkny/realworld-dynamodb-lambda/
˓→zip/v1.0.0 -OutFile v1.0.0.zip
Expand-Archive v1.0.0.zip .
Remove-Item v1.0.0.zip -Force
Rename-Item realworld-dynamodb-lambda-1.0.0 backend
cd backend
(gc .\.gitignore -raw).Replace("package-lock.json`n", "") | sc .\.gitignore
".dynamodb`r`n" | Out-File .\.gitignore -Append -Encoding UTF8
$(gc .\package.json) -replace "dynamodb install .
*
$", "dynamodb install`"" | Out-
˓→File .\package.json -Force -Encoding UTF8
npm install
cd ..
Invoke-WebRequest https://codeload.github.com/gothinkster/angular-realworld-
˓→example-app/zip/35a66d144d8def340278cd55080d5c745714aca4 -OutFile
˓→35a66d144d8def340278cd55080d5c745714aca4.zip
Expand-Archive 35a66d144d8def340278cd55080d5c745714aca4.zip .
Remove-Item 35a66d144d8def340278cd55080d5c745714aca4.zip -Force
Rename-Item angular-realworld-example-app-
˓→35a66d144d8def340278cd55080d5c745714aca4 frontend
cd frontend
(gc .\package.json -raw).Replace("`"rxjs`": `"^6.2.1`"", "`"rxjs`": `"~6.3.3`"")
˓→| sc .\package.json
mkdir scripts
Invoke-WebRequest https://raw.githubusercontent.com/onicagroup/runway/master/
˓→quickstarts/conduit/build.js -OutFile scripts/build.js
$(gc .\package.json) -replace "^\s
*
`"build`":\s.
*
$", " `"build`": `"node
˓→scripts/build`"," | Out-File .\package.json -Force -Encoding UTF8
npm install
Invoke-WebRequest https://raw.githubusercontent.com/onicagroup/runway/master/
˓→quickstarts/conduit/update_env_endpoint.py -OutFile update_env_endpoint.py
cd ..
Invoke-WebRequest https://raw.githubusercontent.com/onicagroup/runway/master/
˓→quickstarts/conduit/Pipfile -OutFile Pipfile
Invoke-WebRequest https://raw.githubusercontent.com/onicagroup/runway/master/
˓→quickstarts/conduit/runway.yml -OutFile runway.yml
(continues on next page)
14 Chapter 3. Quickstart Guides
runway Documentation, Release 1.18.3
(continued from previous page)
3.2.4 Deploying
Execute pipenv run runway deploy, enter all (to deploy the backend followed by the frontend). Deploy-
ment will take some time (mostly waiting for the CloudFront distribution to stabilize).
The CloudFront domain at which the site can be reached will be displayed near the last lines of output once deployment
is complete, e.g.:
staticsite: sync & CF invalidation of E17B5JWPMTX5Z8 (domain ddy1q4je03d7u.
cloudfront.net) complete
3.2.5 Teardown
Execute pipenv run runway destroy, enter all.
The backend DynamoDB tables will still be retained after the destroy is complete. They must be deleted separately:
On macOS/Linux:
for i in realworld-dev-articles realworld-dev-comments realworld-dev-users; do aws
˓→dynamodb delete-table --region us-east-1 --table-name $i; done
On Windows:
foreach($table in @("realworld-dev-articles", "realworld-dev-comments", "realworld-
˓→dev-users"))
{
CMD /C "pipenv run aws dynamodb delete-table --region us-east-1 --table-name $table"
}
3.2.6 Next Steps / Additional Notes
The serverless-plugin-export-endpoints plugin is a good alternative to the custom update_env_endpoint.py script de-
ployed above to update the environment file.
3.2.7 Permissions
The specific IAM permissions required to manage the resources in this demo are as follows
# CloudFormation
- cloudformation:CreateStack
- cloudformation:DeleteStack
- cloudformation:CreateChangeSet
- cloudformation:DescribeChangeSet
- cloudformation:DeleteChangeSet
- cloudformation:DescribeStackResource
- cloudformation:DescribeStackResources
- cloudformation:DescribeStacks
- cloudformation:DescribeStackEvents
- cloudformation:GetTemplate
(continues on next page)
3.2. Conduit (Serverless & CloudFront) Quickstart 15
runway Documentation, Release 1.18.3
(continued from previous page)
- cloudformation:UpdateStack
- cloudformation:ExecuteChangeSet
- cloudformation:ValidateTemplate
# Serverless
- apigateway:GET
- apigateway:DELETE
- apigateway:POST
- apigateway:PUT
- lambda:AddPermission
- lambda:CreateAlias
- lambda:CreateFunction
- lambda:DeleteAlias
- lambda:DeleteFunction
- lambda:GetFunction
- lambda:GetFunctionConfiguration
- lambda:ListVersionsByFunction
- lambda:PublishVersion
- lambda:UpdateAlias
- lambda:UpdateFunctionCode
- lambda:UpdateFunctionConfiguration
- iam:CreateRole
- iam:DeleteRole
- iam:DeleteRolePolicy
- iam:GetRole
- iam:PassRole
- iam:PutRolePolicy
- logs:CreateLogGroup
- logs:DeleteLogGroup
- logs:DescribeLogGroups
- s3:CreateBucket
- s3:DeleteBucket
- s3:DeleteBucketPolicy
- s3:DeleteObject
- s3:DeleteObjectVersion
- s3:GetObjectVersion
- s3:ListBucket
- s3:ListBucketVersions
- s3:PutBucketVersioning
- s3:PutBucketPolicy
- s3:PutLifecycleConfiguration
# Frontend
- cloudfront:CreateCloudFrontOriginAccessIdentity
- cloudfront:CreateDistribution
- cloudfront:CreateInvalidation
- cloudfront:DeleteCloudFrontOriginAccessIdentity
- cloudfront:DeleteDistribution
- cloudfront:GetCloudFrontOriginAccessIdentity
- cloudfront:GetCloudFrontOriginAccessIdentityConfig
- cloudfront:GetDistribution
- cloudfront:GetDistributionConfig
- cloudfront:GetInvalidation
- cloudfront:ListDistributions
- cloudfront:TagResource
- cloudfront:UntagResource
- cloudfront:UpdateCloudFrontOriginAccessIdentity
- cloudfront:UpdateDistribution
- s3:DeleteBucketWebsite
(continues on next page)
16 Chapter 3. Quickstart Guides
runway Documentation, Release 1.18.3
(continued from previous page)
- s3:GetBucketAcl
- s3:GetObject
- s3:PutBucketAcl
- s3:GetBucketWebsite
- s3:PutBucketWebsite
- s3:PutObject
- ssm:GetParameter
- ssm:PutParameter
# Backend
- dynamodb:CreateTable
- dynamodb:DeleteTable
- dynamodb:DescribeTable
- dynamodb:TagResource
- dynamodb:UntagResource
- dynamodb:UpdateTable
3.3 Other Ways to Use Runway
While we recommend using one of the install methods outlined in the Installation section, we realize that these may
not be an option for some so we have provided a CloudFormation template for spinning up a deploy environment in
AWS and a Docker image/Dockerfile that can be used to run Runway.
3.3.1 CloudFormation
This CloudFormation template is probably the easiest and quickest way to go from “zero to Runway” as it allows for
using an IAM Role eliminate the need to configure API keys. The template will deploy your preference of Linux or
Windows Runway host. Windows Runway host includes vsCode, which some users may find easier for manipulating
Runway config files.
3.3.2 Docker
Docker users can build their own Docker image to run a local Runway container or modify this Dockerfile to build a
Runway image to suit specific needs.
3.4 Private Static Site (Auth@Edge) Quickstart
3.4.1 Deploying the Private Static Site
The Runway built-in sample generation of a basic React app will be used as a simple demonstration of creating an
authentication backed single page application.
3.3. Other Ways to Use Runway 17
runway Documentation, Release 1.18.3
3.4.2 Prerequisites
• An AWS account, and configured terminal environment for interacting with it with an admin role.
• The following installed tools:
– npm
– git (Available out of the box on macOS)
3.4.3 Setup
Project Setup
1. Download/install Runway. Here we are showing the curl option. To see other available install methods, see
Installation.
macOS
curl -L https://oni.ca/runway/latest/osx -o runway
chmod +x runway
Ubuntu
curl -L https://oni.ca/runway/latest/linux -o runway
chmod +x runway
Windows
iwr -Uri oni.ca/runway/latest/windows -OutFile runway.exe
2. From a directory of your choosing run the following to generate a sample React project:
pipenv run runway gen-sample static-react
3. A new folder will be created entitled static-react. If you’d like your project to have a different name feel
free to change it at this time:
mv static-react my-static-site
4. Change directories into the new project folder and prepare the project directory. See Repo Structure for more
details.
cd my-static-site
git init
git checkout -b ENV-dev
18 Chapter 3. Quickstart Guides
runway Documentation, Release 1.18.3
User Pool Setup
1. The default runway.yml document that is provided with gen-sample static-react is a good baseline
document for deploying a standard static single page application without the need of authentication. In this
example we’ll be leveraging Auth@Edge to provide protection to our application, not allowing anyone to
view or download site resources without first authenticating. To accomplish this we need to create a Cognito
UserPool. Login to your AWS Console and search for cognito.
2. Click Manage User Pools
3. Click Create a user pool
3.4. Private Static Site (Auth@Edge) Quickstart 19
runway Documentation, Release 1.18.3
4. You will be asked to provide a name for your User Pool. For our example we will be using a default Cognito
User Pool, but you can Step through settings to customize your pool if you so choose. After entering
your Pool name click the Review defaults button.
5. Review all the settings are accurate prior to clicking Create pool.
20 Chapter 3. Quickstart Guides
runway Documentation, Release 1.18.3
6. Next let’s create a test user to verify our authentication functionality after deployment. Click the Users and
groups list link.
7. Click Create user
8. In the form provided give a valid email address for the Username (Required) and Email entries. Ensure
3.4. Private Static Site (Auth@Edge) Quickstart 21
runway Documentation, Release 1.18.3
Send an invitation to this new user? is checked so you can receive the temporary password to
access the site. Click the Create user button.
9. Check the email address provided, you should receive a notification email from Cognito with the username and
password that will need to be used for initial authentication.
10. Now we need to retrieve the ARN for the User Pool we just created and add it to the deployments ->
modules -> environments -> dev section of our runway.yml document. Click the General
Settings list link to retrieve the ARN.
22 Chapter 3. Quickstart Guides
runway Documentation, Release 1.18.3
staticsite_user_pool_arn: YOUR_USER_POOL_ARN
Domain Aliases with ACM Certificate
1. In this example we are going to be using an alias custom domain name to identify the CloudFront Distribution.
This series of steps is optional, a domain will still be provided with the Distribution if you choose not to use
a custom domain. This guide assumes that you have already purchased and registered a custom domain and
created and validated an ACM certficate.
2. The ARN of the ACM certificate is required when providing an alias domain name. From the search bar of
the AWS console locate certificate manager. In this screen dropdown the details of your issued and
validated certificate and locate the ARN.
3. Create two entries in the runway.yml configuration file under the deployments -> modules ->
environments -> dev heading. One for the alias we’re looking to provide, and the other for it’s ARN:
staticsite_aliases: YOUR_CUSTOM_DOMAIN_NAMES_COMMA_SEPARATED
staticsite_acmcert_arn: YOUR_ACM_ARN
3.4. Private Static Site (Auth@Edge) Quickstart 23
runway Documentation, Release 1.18.3
Cleanup
1. By default the gen-sample static-react sample runway.yaml document comes with
staticsite_cf_disable: true added. Due to the nature of the authorization a Distribution is
required. Remove this line from your config file.
3.4.4 Deploying
Execute pipenv run runway deploy, enter y. Deployment will take some time (mostly waiting for the Cloud-
Front distribution to stabilize).
The CloudFront domain at which the site can be reached will be displayed near the last lines of output once deployment
is complete, e.g.:
staticsite: sync & CF invalidation of E17B5JWPMTX5Z8 (domain ddy1q4je03d7u.
cloudfront.net) complete
Since we’re using a custom domain alias the Distribution will also be accessible by that domain.
3.4.5 Accessing and Authorizing
Authorizing
1. From your browser enter either the CloudFront Distribution domain or the alias you provided. You will be
greeted with the Cognito login screen. Enter the username and temporary password you received in step 9 of
User Pool Setup:
24 Chapter 3. Quickstart Guides
runway Documentation, Release 1.18.3
2. You will be asked to change your password based on the validation requirements you specified when creating
the User Pool. Once you have satisified the requirements click Send
3. You will be greeted with the default React App home page:
3.4. Private Static Site (Auth@Edge) Quickstart 25
runway Documentation, Release 1.18.3
Sign-Out
1. By default a /sign-out path is provided to sign out of Cognito.
3.4.6 Teardown
Execute pipenv run runway destroy, enter y.
26 Chapter 3. Quickstart Guides
CHAPTER
FOUR
COMMANDS
4.1 deploy
Used to deploy modules with Runway.
When this command is used, the following will take place:
1. The deploy environment will be determined from one of the following (in order of precedence):
• -e, --deploy-environment option
• DEPLOY_ENVIRONMENT environment variable
• git branch (unless ignore_git_branch is enabled in the Runway Config File)
• directory
2. The deployment(s) and module(s) to deploy will be selected. This will occur in one of three ways:
• (default) Runway will prompt the user to make selections manually
• if --tag is provided, all modules containing all tags will be selected
• if Runway is run non-interactively, all deployments and modules will be selected
3. Runway will iterate through all of the selected deployments and modules, deploying them in the order defined.
Usage
$ runway deploy [OPTIONS]
Options
--ci Run in non-interactive mode.
--debug Supply once to display Runway debug logs.
Supply twice to display all debug logs.
-e, --deploy-environment <env-name>
Manually specify the name of the deploy environment.
--no-color Disable color in Runway's logs.
--tag <tag>... Select modules by tag or tags.
This option can be specified more than once to
build a list of tags that are treated as "AND".
(e.g. "--tag <tag1> --tag <tag2>" would select
all modules with BOTH tags).
--verbose Display Runway verbose logs.
27
runway Documentation, Release 1.18.3
Example
$ runway deploy
$ runway deploy --ci --deploy-environment example
$ runway deploy --tag tag1 --tag tag2
4.2 destroy
Used to destroy modules with Runway.
Danger: Use extreme caution when run non-interactively or using --tag <tag>.... You will not be
prompted before deletion. All modules (or those selected by tag) will be irrecoverably deleted.
When this command is used, the following will take place:
1. The deploy environment will be determined from one of the following (in order of precedence):
• -e, --deploy-environment option
• DEPLOY_ENVIRONMENT environment variable
• git branch (unless ignore_git_branch is enabled in the Runway Config File)
• directory
2. The deployment(s) and module(s) to deploy will be selected. This will occur in one of three ways:
• (default) Runway will prompt the user to make selections manually
• if --tag is provided, all modules containing all tags will be selected
• if Runway is run non-interactively, all deployments and modules will be selected
3. Runway will iterate through all of the selected deployments and modules, destroying them in reverse of the
order defined.
Usage
$ runway destroy [OPTIONS]
Options
--ci Run in non-interactive mode.
--debug Supply once to display Runway debug logs.
Supply twice to display all debug logs.
-e, --deploy-environment <env-name>
Manually specify the name of the deploy environment.
--no-color Disable color in Runway's logs.
--tag <tag>... Select modules by tag or tags.
This option can be specified more than once to
build a list of tags that are treated as "AND".
(continues on next page)
28 Chapter 4. Commands
runway Documentation, Release 1.18.3
(continued from previous page)
(e.g. "--tag <tag1> --tag <tag2>" would select
all modules with BOTH tags).
--verbose Display Runway verbose logs.
Example
$ runway destroy
$ runway destroy --ci --deploy-environment example
$ runway destroy --tag tag1 --tag tag2
4.3 dismantle
Alias of destroy.
Usage
$ runway dismantle [OPTIONS]
Options
--ci Run in non-interactive mode.
--debug Supply once to display Runway debug logs.
Supply twice to display all debug logs.
-e, --deploy-environment <env-name>
Manually specify the name of the deploy environment.
--no-color Disable color in Runway's logs.
--tag <tag>... Select modules by tag or tags.
This option can be specified more than once to
build a list of tags that are treated as "AND".
(e.g. "--tag <tag1> --tag <tag2>" would select
all modules with BOTH tags).
--verbose Display Runway verbose logs.
Example
$ runway dismantle
$ runway dismantle --ci --deploy-environment example
$ runway dismantle --tag tag1 --tag tag2
4.3. dismantle 29
runway Documentation, Release 1.18.3
4.4 envvars
Output env_vars defined in the Runway Config File.
OS environment variables can be set in the Runway Config File for different deploy environments (e.g. dev & prod
KUBECONFIG values). This command allows access to these values for use outside of Runway.
Note: Only outputs env_vars defined in deployments, not modules.
Usage
$ runway envvars [OPTIONS]
Options
--debug Supply once to display Runway debug logs.
Supply twice to display all debug logs.
-e, --deploy-environment <env-name>
Manually specify the name of the deploy environment.
--no-color Disable color in Runway's logs.
--verbose Display Runway verbose logs.
Example
$ runway envvars
$ eval "$(runway envvars)"
$ runway envvars --deploy-environment example
4.5 docs
Open the Runway documentation web site using the default web browser.
Usage
$ runway docs [OPTIONS]
30 Chapter 4. Commands
runway Documentation, Release 1.18.3
Options
--debug Supply once to display Runway debug logs.
Supply twice to display all debug logs.
--no-color Disable color in Runway's logs.
--verbose Display Runway verbose logs.
Example
$ runway docs
4.6 gen-sample
Generate a sample Runway module directory or project.
The sample is created in the current directory. If a directory already exists with the name Runway tries to use, the
sample will not be created.
Available Samples
Name Description
cdk-csharp AWS Cloud Development Kit (CDK) using C#
cdk-py AWS Cloud Development Kit (CDK) using Python
cdk-tsc AWS Cloud Development Kit (CDK) using TypeScript
cfn CloudFormation stack with S3 bucket & DDB table (perfect for storing Terraform backend
state)
cfngin Troposphere identical to the cfn sample but written in Python
k8s-cfn-repo Kubernetes EKS cluster & sample app using CloudFormation
k8s-tf-repo Kubernetes EKS cluster & sample app using Terraform
k8s-flux-repo
`Kubernetes + Flux`_ module EKS cluster & Flux app using Terraform
sls-py Serverless Framework module using Python
sls-tsc Serverless Framework using TypeScript
static-angular Static Site using Angular
static-react Static Site using React
tf Terraform
Usage
$ runway gen-sample [OPTIONS] <sample>
4.6. gen-sample 31
runway Documentation, Release 1.18.3
Options
--debug Supply once to display Runway debug logs.
Supply twice to display all debug logs.
--no-color Disable color in Runway's logs.
--verbose Display Runway verbose logs.
Example
$ runway gen-sample cfngin
$ runway gen-sample static-react
4.7 init
Creates a sample Runway Config File in the current directory.
Usage
$ runway init [OPTIONS]
Options
--debug Supply once to display Runway debug logs.
Supply twice to display all debug logs.
--no-color Disable color in Runway's logs.
--verbose Display Runway verbose logs.
Example
$ runway init
$ runway init --debug
4.8 kbenv install
Install the specified version of kubectl (e.g. v1.14.0).
If no version is specified, Runway will attempt to find and read a .kubectl-version file in the current directory
(see Version Management for more details). If this file doesn’t exist, nothing will be installed.
Compatible with alexppg/kbenv.
32 Chapter 4. Commands
runway Documentation, Release 1.18.3
Usage
$ runway kbenv install [OPTIONS] [<version>]
Options
--debug Supply once to display Runway debug logs.
Supply twice to display all debug logs.
--no-color Disable color in Runway's logs.
--verbose Display Runway verbose logs.
Example
$ runway kbenv install
$ runway kbenv install v1.14.0
4.9 kbenv run
Run a kubectl command.
Uses the version of kubectl specified in the .kubectl-version file in the current directory (see Version Manage-
ment for more details).
Important: When using options shared with Runway, -- must be placed before the kubectl command.
Usage
$ runway kbenv run [OPTIONS] [<version>]
Options
--debug Supply once to display Runway debug logs.
Supply twice to display all debug logs.
--no-color Disable color in Runway's logs.
--verbose Display Runway verbose logs.
4.9. kbenv run 33
runway Documentation, Release 1.18.3
Example
$ runway kbenv run version --client
$ runway kbenv run -- --help
4.10 plan
Determine what infrastructure changes will occur during the next deploy.
Note: Currently only supported for AWS Cloud Development Kit (CDK), CloudFormation & Troposphere, and Ter-
raform.
When this command is used, the following will take place:
1. The deploy environment will be determined from one of the following (in order of precedence):
• -e, --deploy-environment option
• DEPLOY_ENVIRONMENT environment variable
• git branch (unless ignore_git_branch is enabled in the Runway Config File)
• directory
2. The deployment(s) and module(s) to deploy will be selected. This will occur in one of three ways:
• (default) Runway will prompt the user to make selections manually
• if --tag is provided, all modules containing all tags will be selected
• if Runway is run non-interactively, all deployments and modules will be selected
3. Runway will iterate through all of the selected deployments and modules, attempting to determine the changes
will occur during the next deploy.
Usage
$ runway plan [OPTIONS]
Options
--ci Run in non-interactive mode.
--debug Supply once to display Runway debug logs.
Supply twice to display all debug logs.
-e, --deploy-environment <env-name>
Manually specify the name of the deploy environment.
--no-color Disable color in Runway's logs.
--tag <tag>... Select modules by tag or tags.
This option can be specified more than once to
build a list of tags that are treated as "AND".
(e.g. "--tag <tag1> --tag <tag2>" would select
all modules with BOTH tags).
--verbose Display Runway verbose logs.
34 Chapter 4. Commands
runway Documentation, Release 1.18.3
Example
$ runway plan
$ runway plan --ci --deploy-environment example
$ runway plan --tag tag1 --tag tag2
4.11 preflight
Alias of test.
Usage
$ runway preflight [OPTIONS]
Options
--debug Supply once to display Runway debug logs.
Supply twice to display all debug logs.
-e, --deploy-environment <env-name>
Manually specify the name of the deploy environment.
--no-color Disable color in Runway's logs.
--verbose Display Runway verbose logs.
Example
$ runway preflight
4.12 run-aws
Execute awscli commands using the version bundled with Runway.
This command gives access to the awscli when it might not otherwise be installed (e.g. when using a binary release of
Runway).
Important: When using options shared with Runway, -- must be placed before the awscli command.
4.11. preflight 35
runway Documentation, Release 1.18.3
Usage
$ runway run-aws [OPTIONS] <args>
Options
--debug Supply once to display Runway debug logs.
Supply twice to display all debug logs.
--no-color Disable color in Runway's logs.
--verbose Display Runway verbose logs.
Example
$ runway run-aws sts get-caller-identity
$ runway run-aws -- --version
4.13 run-python
Execute a python script using a bundled copy of python.
This command can execute actions using python without requiring python to be installed on a system. This is only
applicable when installing a binary release of Runway (not installed from PyPi). When installed from PyPI, the current
interpreter is used.
Usage
$ runway run-python [OPTIONS] <filename>
Options
--debug Supply once to display Runway debug logs.
Supply twice to display all debug logs.
--no-color Disable color in Runway's logs.
--verbose Display Runway verbose logs.
Example
$ runway run-python my_script.py
36 Chapter 4. Commands
runway Documentation, Release 1.18.3
4.14 run-stacker
Execute the “shimmed” Stacker aka Runway CFNgin.
This command allows direct access to Runway’s CloudFormation management tool.
Deprecated since version 1.5.0.
Important: When using options shared with Runway, -- must be placed before the Stacker command.
Usage
$ runway run-stacker [OPTIONS] <args>
Options
--debug Supply once to display Runway debug logs.
Supply twice to display all debug logs.
--no-color Disable color in Runway's logs.
--verbose Display Runway verbose logs.
Example
$ runway run-stacker build cfngin_config.yml
$ runway run-stacker -- info --help
4.15 takeoff
Alias of deploy
Usage
$ runway takeoff [OPTIONS]
Options
--ci Run in non-interactive mode.
--debug Supply once to display Runway debug logs.
Supply twice to display all debug logs.
-e, --deploy-environment <env-name>
Manually specify the name of the deploy environment.
--no-color Disable color in Runway's logs.
--tag <tag>... Select modules by tag or tags.
(continues on next page)
4.14. run-stacker 37
runway Documentation, Release 1.18.3
(continued from previous page)
This option can be specified more than once to
build a list of tags that are treated as "AND".
(e.g. "--tag <tag1> --tag <tag2>" would select
all modules with BOTH tags).
--verbose Display Runway verbose logs.
Example
$ runway takeoff
$ runway takeoff --ci --deploy-environment example
$ runway takeoff --tag tag1 --tag tag2
4.16 taxi
Alias of plan.
Usage
$ runway taxi [OPTIONS]
Options
--ci Run in non-interactive mode.
--debug Supply once to display Runway debug logs.
Supply twice to display all debug logs.
-e, --deploy-environment <env-name>
Manually specify the name of the deploy environment.
--no-color Disable color in Runway's logs.
--tag <tag>... Select modules by tag or tags.
This option can be specified more than once to
build a list of tags that are treated as "AND".
(e.g. "--tag <tag1> --tag <tag2>" would select
all modules with BOTH tags).
--verbose Display Runway verbose logs.
Example
$ runway taxi
$ runway taxi --ci --deploy-environment example
$ runway taxi --tag tag1 --tag tag2
38 Chapter 4. Commands
runway Documentation, Release 1.18.3
4.17 test
Execute tests as defined in the Runway Config File.
If one of the tests fail, the command will exit immediately unless the required option is set to false for the failing
test. If it is not required, the next test will be executed. If any tests fail, the command with exit with a non-zero exit
code.
Usage
$ runway test [OPTIONS]
Options
--debug Supply once to display Runway debug logs.
Supply twice to display all debug logs.
-e, --deploy-environment <env-name>
Manually specify the name of the deploy environment.
--no-color Disable color in Runway's logs.
--verbose Display Runway verbose logs.
Example
$ runway test
4.18 tfenv install
Install the specified version of Terraform (e.g. 0.12.0).
If no version is specified, Runway will attempt to find and read a .terraform-version file in the current directory
(see Version Management for more details). If this file doesn’t exist, nothing will be installed.
Usage
$ runway tfenv install [OPTIONS] [<version>]
Options
--debug Supply once to display Runway debug logs.
Supply twice to display all debug logs.
--no-color Disable color in Runway's logs.
--verbose Display Runway verbose logs.
4.17. test 39
runway Documentation, Release 1.18.3
Example
$ runway tfenv install 0.12.0
4.19 tfenv run
Run a Terraform command.
Uses the version of Terraform specified in the .terraform-version file in the current directory (see Version
Management for more details).
Important: When using options shared with Runway, -- must be placed before the Terraform command.
Usage
$ runway tfenv run [OPTIONS] <args>
Options
--debug Supply once to display Runway debug logs.
Supply twice to display all debug logs.
--no-color Disable color in Runway's logs.
--verbose Display Runway verbose logs.
Example
$ runway tfenv run --version
$ runway tfenv run -- --help
4.20 whichenv
Print the current deploy environment name to stdout.
When run, the deploy environment will be determined from one of the following (in order of precedence):
• DEPLOY_ENVIRONMENT environment variable
• git branch (unless ignore_git_branch is enabled in the Runway Config File)
• directory
40 Chapter 4. Commands
runway Documentation, Release 1.18.3
Usage
$ runway whichenv [OPTIONS]
Options
--debug Supply once to display Runway debug logs.
Supply twice to display all debug logs.
--no-color Disable color in Runway's logs.
--verbose Display Runway verbose logs.
Example
$ runway whichenv
4.20. whichenv 41
runway Documentation, Release 1.18.3
42 Chapter 4. Commands
CHAPTER
FIVE
RUNWAY CONFIG FILE
5.1 Top-Level Configuration
class runway.config.Config(deployments, future=None, ignore_git_branch=False, run-
way_version=None, tests=None, variables=None)
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 pro-
cessed 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 be-
fore execution. Note that defining DEPLOY_ENVIRONMENT will automatically ignore the
git branch.
43
runway Documentation, Release 1.18.3
• 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
• https://www.python.org/dev/peps/pep-0440/#version-specifiers
• deployment
• test
5.2 Deployment
class runway.config.DeploymentDefinition(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 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
(continues on next page)
44 Chapter 5. Runway Config File
runway Documentation, Release 1.18.3
(continued from previous page)
- 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 map-
ping 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 $AC-
COUNT_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 en-
vironment 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 pro-
cessed 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.
5.2. Deployment 45
runway Documentation, Release 1.18.3
• 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 re-
gions 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 paral-
lel.
• 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 process-
ing and once during processing. Because of this, the keywords/directives that are resolved before process-
ing 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_aliasenv lookup (AWS_REGION and AWS_DEFAULT_REGION will not have been set by Runway
yet), var lookup
account_idenv lookup (AWS_REGION and AWS_DEFAULT_REGION will not have been set by Runway
yet), var lookup
assume_roleenv lookup (AWS_REGION and AWS_DEFAULT_REGION will not have been set by Runway
yet), var lookup
environmentsenv 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_optionsenv 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_regionsenv lookup (AWS_REGION and AWS_DEFAULT_REGION will not have been set by Runway
yet), var lookup
parametersenv lookup, var lookup
46 Chapter 5. Runway Config File
runway Documentation, Release 1.18.3
References
• module
• deploy
• destroy
• plan
5.3 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:
5.3. Future 47
runway Documentation, Release 1.18.3
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.
5.4 Module
class runway.config.ModuleDefinition(name, path, class_path=None, type_str=None, environ-
ments=None, parameters=None, env_vars=None, op-
tions=None, tags=None, child_modules=None)
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.
48 Chapter 5. Runway Config File
runway Documentation, Release 1.18.3
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 (simul-
taneously) 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
5.4. Module 49
runway Documentation, Release 1.18.3
• 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 map-
ping 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 $AC-
COUNT_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 en-
vironment 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
50 Chapter 5. Runway Config File
runway Documentation, Release 1.18.3
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
5.4.1 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.
5.4. Module 51
runway Documentation, Release 1.18.3
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
52 Chapter 5. Runway Config File
runway Documentation, Release 1.18.3
options
The remaining options that are passed along to the Source. This is specified in the path following the ? separator. Mul-
tiple 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.
5.4.2 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:
5.4. Module 53
runway Documentation, Release 1.18.3
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.
5.5 Test
class runway.config.TestDefinition(name, test_type, args=None, required=True)
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. Sup-
ported arguments vary by test type. See Build-in Test Types for the list of arguments sup-
ported 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 de-
termined from the branch or directory.
54 Chapter 5. Runway Config File
runway Documentation, Release 1.18.3
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
5.6 Variables
class runway.config.VariablesDefinition(file_path=None, sys_path=None, **kwargs)
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.
5.6. Variables 55
runway Documentation, Release 1.18.3
5.7 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:
(continues on next page)
56 Chapter 5. Runway Config File
runway Documentation, Release 1.18.3
(continued from previous page)
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
5.7. Sample 57
runway Documentation, Release 1.18.3
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
58 Chapter 5. Runway Config File
CHAPTER
SIX
LOOKUPS
Runway Lookups allow the use of variables within the Runway config file. These variables can then be passed along
to deployments, modules and tests.
The syntax for a lookup is ${<lookup-name> <query>::<arg-key>=<arg-value>}
Component Description
${ Signifies the opening of the lookup.
<lookup-name>The name of the lookup you wish to use (e.g. env). This signifies the source of the data to be
retrieved by the lookup.
The separator between lookup name a query.
<query> The value the lookup will be looking for. (e.g. AWS_REGION) | When using a lookup on a
dictionary/mapping, like for the var lookup, you can get nested values by providing the full path
to the value. (e.g. ami.dev}
:: The separator between a query and optional arguments.
<arg-key>=<arg-value>An argument passed to a lookup. Multiple arguments can be passed to a lookup by separating
them with a comma (,). Arguments are optional. Supported arguments depend on the lookup
being used.
Lookups can be nested (e.g. ${var ami_id.${var AWS_REGION}}).
Lookups can’t resolve other lookups. For example, if i use ${var region} in my Runway config file to resolve
the region from my variables file, the value in the variables file can’t be ${env AWS_REGION}. Well, it can but
it will resolve to the literal value provided, not an AWS region like you may expect.
6.1 Lookup Arguments
Arguments can be passed to Lookups to effect how they function.
To provide arguments to a Lookup, use a double-colon (::) after the query. Each argument is then defined as a key
and value seperated with equals (=) and the arguments theselves are seperated with a comma (,). The arguments can
have an optional space after the comma and before the next key to make them easier to read but this is not required.
The value of all arguments are read as strings.
59
runway Documentation, Release 1.18.3
Example
${var my_query::default=true, transform=bool}
${env MY_QUERY::default=1,transform=bool}
Each Lookup may have their own, specific arguments that it uses to modify its functionality or the value it returns.
There is also a common set of arguments that all Lookups accept.
6.1.1 Common Lookup Arguments
default (Any) If the Lookup is unable to find a value for the provided query, this value will be returned instead of
raising an exception.
get (Optional[str]) Can be used on a dictionary type object to retrieve a specific piece of data. This is executed after
the optional load step.
indent (Optional[int]) Number of spaces to use per indent level when transforming a dictionary type object to a
string.
load (Optional[str]) Load the data to be processed by a Lookup using a specific parser. This is the first action taking
on the data after it has been retrieved from its source. The data must be in a format that is supported by the
parser in order for it to be used.
json Loads a JSON seralizable string into a dictionary like object.
troposphere Loads the properties of a subclass of troposphere.BaseAWSObject into a dictionary.
yaml Loads a YAML seralizable string into a dictionary like object.
region (Optional[str]) AWS region used when creating a boto3.Session to retrieve data. If not provided, the
region currently being processed will be used. This can be specified to always get data from one region regardless
of region is being deployed to.
transform (Optional[str]) Transform the data that will be returned by a Lookup into a different data type. This is the
last action taking on the data before it is returned. Supports the following:
str Converts any value to a string. The original data type determines the end result.
list, set, and tuple will become a comma delimited list
dict and anything else will become an escaped JSON string.
bool Converts a string or boolean value into a boolean.
Example
deployments:
- parameters:
some_variable: ${var some_value::default=my_value}
comma_list: ${var my_list::default=undefined, transform=str}
60 Chapter 6. Lookups
runway Documentation, Release 1.18.3
6.2 Built-in Lookups
6.2.1 cfn
Important: The Stack must exist in CloudFormation before the module using this Lookup begins processing to
successfully get a value. This means that the Stack must have been deployed by another module, run before the one
using this Lookup, or it must have been created external to Runway.
Retrieve a value from CloudFormation Stack Outputs.
The query syntax for this lookup is <stack-name>.<output-name>. When specifying the output name, be sure
to use the Logical ID of the output; not the Export.Name.
If the Lookup is unable to find a CloudFormation Stack Output matching the provided query, the default value is
returned or an exception is raised to show why the value could be be resolved (e.g. Stack does not exist or output does
not exist on the Stack).
See also:
https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/outputs-section-structure.html
Arguments
This Lookup supports all Common Lookup Arguments.
Example
Listing 1: Runway config
deployments:
- modules:
path: sampleapp.tf
options:
terraform_backend_config:
bucket: ${cfn common-tf-state.TerraformStateBucketName::region=us-east-1}
dynamodb_table: ${cfn common-tf-state.TerraformStateTableName::region=us-
˓→east-1}
region: us-east-1
6.2. Built-in Lookups 61
runway Documentation, Release 1.18.3
Listing 2: CFNgin config
stacks:
my-stack:
variables:
SomeParameter: ${cfn AnotherStack.OutputName}
6.2.2 ecr
Retrieve a value from AWS Elastic Container Registry (ECR).
This Lookup only supports very specific queries.
Supported Queries
login-password
Get a password to login to ECR registry.
The returned value can be passed to the login command of the container client of your preference, such as the Docker
CFNgin hook. After you have authenticated to an Amazon ECR registry with this Lookup, you can use the client to
push and pull images from that registry as long as your IAM principal has access to do so until the token expires. The
authorization token is valid for 12 hours.
Arguments
This Lookup does not support any arguments.
Example
Listing 3: runway.yml
deployments:
- modules:
- path: example.cfn
parameters:
ecr_password: ${ecr login-password}
...
Listing 4: cfngin.yml
pre_build:
- path: runway.cfngin.hooks.docker.login
args:
password: ${ecr login-password}
...
62 Chapter 6. Lookups
runway Documentation, Release 1.18.3
6.2.3 env
Retrieve a value from an environment variable.
The value is retrieved from a copy of the current environment variables that is saved to the context object. These envi-
ronment variables are manipulated at runtime by Runway to fill in additional values such as DEPLOY_ENVIRONMENT
and AWS_REGION to match the current execution.
Note: DEPLOY_ENVIRONMENT and AWS_REGION can only be resolved during the processing of a module. To
ensure no error occurs when trying to resolve one of these in a Deployment definition, provide a default value.
If the Lookup is unable to find an environment variable matching the provided query, the default value is returned or a
ValueError is raised if a default value was not provided.
Arguments
This Lookup supports all Common Lookup Arguments but, the folling have limited or no effect:
• region
Example
deployment:
- modules:
- path: sampleapp.cfn
parameters:
creator: ${env USER}
env_vars:
ENVIRONMENT: ${env DEPLOY_ENVIRONMENT::default=default}
6.2.4 ssm
Retrieve a value from SSM Parameter Store.
If the Lookup is unable to find an SSM Parameter matching the provided query, the default value is returned or
ParameterNotFound is raised if a default value is not provided.
Parameters of type SecureString are automatically decrypted.
Parameters of type StringList are returned as a list.
Arguments
This Lookup supports all Common Lookup Arguments.
6.2. Built-in Lookups 63
runway Documentation, Release 1.18.3
Example
deployment:
- modules:
- path: sampleapp.cfn
parameters:
secret_value: ${ssm /example/secret}
conf_file: ${ssm /example/config/json::load=json, get=value}
toggle: ${ssm toggle::load=yaml, get=val, transform=bool}
env_vars:
SOME_VARIABLE: ${ssm /example/param::region=us-east-1}
DEFAULT_VARIABLE: ${ssm /example/default::default=default}
6.2.5 var
Retrieve a variable from the variables file or definition.
If the Lookup is unable to find an defined variable matching the provided query, the default value is returned or a
ValueError is raised if a default value was not provided.
Nested values can be used by providing the full path to the value but, it will not select a list element.
The returned value can contain any YAML support data type (dictionaries/mappings/hashes, lists/arrays/sequences,
strings, numbers, and booleon).
Arguments
This Lookup supports all Common Lookup Arguments but, the folling have limited or no effect:
• region
Example
deployment:
- modules:
- path: sampleapp.cfn
parameters:
ami_id: ${var ami_id.${env AWS_REGION}}
env_vars:
SOME_VARIABLE: ${var some_variable::default=default}
64 Chapter 6. Lookups
CHAPTER
SEVEN
DEFINING TESTS
7.1 Overview
Tests can be defined in the runway config file to test your modules in any way you desire before deploying. They are
run by using the runway test command. Tests are run in the order they are defined.
Example:
tests:
- name: example-test
type: script
args:
commands:
- echo "Success!"
7.1.1 Test Failures
The default behavior if a tests fails is to continue running the rest of the tests and return a non-zero exit code at the
end. This behavior can modified to allow testing to continue by adding required: true to the test definition.
This will terminate execution if test fails and no further tests will be run.
Example
tests:
- name: hello-world
type: script
required: true
args:
commands:
- echo "Hello World!" && exit 1
65
runway Documentation, Release 1.18.3
7.2 Built-in Test Types
7.2.1 cfn-lint
Source: https://github.com/aws-cloudformation/cfn-python-lint
Validate CloudFormation yaml/json templates against the CloudFormation spec and additional checks.
Includes checking valid values for resource properties and best practices.
In order to use this test, there must be a .cfnlintrc file in the same directory as the Runway config file.
Example:
tests:
- name: cfn-lint-example
type: cfn-lint
7.2.2 script
Executes a list of provided commands. Each command is run in its own subprocess.
Commands are passed into the test using the commands argument.
Example:
tests:
- name: hello-world
type: script
args:
commands:
- echo "Hello World!"
7.2.3 yamllint
Source: https://github.com/adrienverge/yamllint
A linter for YAML files. yamllint does not only check for syntax validity, but for weirdnesses like key
repetition and cosmetic problems such as lines length, trailing spaces, indentation, etc.
A .yamllint file can be placed at in the same directory as the Runway config file to customize the linter or, the
Runway provided template will be used.
66 Chapter 7. Defining Tests
runway Documentation, Release 1.18.3
Example:
tests:
- name: yamllint-example
type: yamllint
7.2. Built-in Test Types 67
runway Documentation, Release 1.18.3
68 Chapter 7. Defining Tests
CHAPTER
EIGHT
REPO STRUCTURE
Projects deployed via Runway can be structured in a few ways; some examples follow:
8.1 Git Branches as Environments
This example shows two modules using environment git branches (these same files would be present in each environ-
ment branch, with changes to any environment promoted through branches):
.
myapp.cfn
dev-us-west-2.env
prod-us-west-2.env
myapp.yaml
templates
foo.json
myapp.tf
backend.tfvars
dev-us-east-1.tfvars
prod-us-east-1.tfvars
main.tf
runway.yml
8.2 Directories as Environments
The same two modules from the above Git Branches as Environments structure can instead be stored in a normal
single-branch git repo. Each directory correlates with an environment (dev and prod in this example).
Environment changes are done by copying the environments’ contents between each other. E.g., promotion from dev
to prod could be as simple as diff -u dev/ prod/ followed by rsync -r --delete dev/ prod/
Enabling that automated promotion is one of the reasons this example below has prod config files in the dev folder and
vice versa. When promotions between environments are more hand managed, this is not technically required:
.
dev
myapp.cfn
dev-us-west-2.env
| prod-us-west-2.env
myapp.yaml
templates
(continues on next page)
69
runway Documentation, Release 1.18.3
(continued from previous page)
myapp_cf_template.json
myapp.tf
backend.tfvars
dev-us-east-1.tfvars
| prod-us-east-1.tfvars
main.tf
runway.yml
prod
myapp.cfn
dev-us-west-2.env
prod-us-west-2.env
myapp.yaml
templates
myapp_cf_template.json
myapp.tf
backend.tfvars
dev-us-east-1.tfvars
prod-us-east-1.tfvars
main.tf
runway.yml
8.3 Directories as Environments with a Single Module
Another sample repo structure, showing environment folders containing a single CloudFormation modules at their
root (using the ignore_git_branch Runway config file option and a single declared module of ./ to merge the
Environment & Module folders).
See the Directories as Environments example above for more information on why this shows prod config files in the
dev folder and vice versa:
.
dev
dev-us-west-2.env
prod-us-west-2.env
myapp.yaml
runway.yml
templates
myapp_cf_template.json
prod
dev-us-west-2.env
prod-us-west-2.env
myapp.yaml
runway.yml
templates
myapp_cf_template.json
70 Chapter 8. Repo Structure
CHAPTER
NINE
MODULE CONFIGURATION
9.1 AWS Cloud Development Kit (CDK)
The CDK module type is deployed using the AWS Cloud Development Kit (CDK). Runway uses system installed npm
to install the CDK per-module. This means that the CDK must be included as a dev dependency in the package.json
of the module.
• Configuration
• Directory Structure
• Advanced Features
9.1.1 Configuration
Standard CDK rules apply but, we have some added prerequisites, recommendations, and caveats.
Prerequisites
• npm installed on the system
• CDK must be a dev dependency of the module (e.g. npm install --save-dev aws-cdk)
We strongly recommend you commit the package-lock.json that is generated after running npm install.
Environments
Unlike some other module types, CDK does not have file that can be used to configure an environment. It can only be
configured using the environments option of a deployment and/or module (see Runway Config File for details).
Runway Config
Top-level
---
deployments:
- modules:
- path: mycdkmodule.cdl
environments:
dev: true
(continues on next page)
71
runway Documentation, Release 1.18.3
(continued from previous page)
prod: true
- modules:
- path: myothercdkmodule.cdk
environments:
dev: true
prod: true
In Module Directory
---
environments:
dev: true
prod: true
9.1.2 Directory Structure
Example directory structures for a CDK module.
C# Example
.
add-project.hook.d.ts
cdk.json
package.json
package-lock.json
src
HelloCdk
HelloCdk.csproj
HelloConstruct.cs
HelloStack.cs
Program.cs
HelloCdk.sln
Python Example
.
Pipfile
Pipfile.lock
app.py
cdk.json
hello
__init__.py
hello_construct.py
hello_stack.py
package.json
package-lock.json
72 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
TypeScript Example
.
bin
sample.ts
cdk.json
lib
sample-stack.ts
package.json
package.json
tsconfig.json
9.1.3 Advanced Features
Advanced features and detailed information for using CDK with Runway.
Build Steps
Build steps (e.g. for compiling TypeScript) can be specified in the module options. These steps will be run before each
diff, deploy, or destroy.
Example
---
deployments:
- modules:
- path: mycdkmodule.cdk
environments:
dev: true
options:
build_steps:
- npx tsc
Disabling NPM CI
At the start of each module execution, Runway will execute npm ci to ensure the CDK is installed in the project
(so Runway can execute it via npx cdk. This can be disabled (e.g. for use when the node_modules directory is
pre-compiled) via the skip_npm_ci module option:
Example
---
deployments:
- modules:
- path: mycdkmodule.cdk
options:
skip_npm_ci: true
9.1. AWS Cloud Development Kit (CDK) 73
runway Documentation, Release 1.18.3
9.2 CloudFormation & Troposphere
The CloudFormation module type is deployed using Runway’s CloudFormation engine (CFNgin). It is able to de-
ploy raw CloudFormation templates (JSON & YAML) and Troposphere templates that are written in the form of a
Blueprints.
• Configuration
• Directory Structure
• Advanced Features
9.2.1 Configuration
In addition to the Runway Config File, there are two files that can be used for configuration:
• a YAML configuration file [REQUIRED]
• a key/value environment file
runway.yml
Example
deployments:
- modules:
- path: sampleapp.cfn
type: cloudformation # not required; implied from ".cfn" directory extension
environments:
dev: true
parameters:
namespace: example-${env DEPLOY_ENVIRONMENT}
cfngin_bucket: example-${env DEPLOY_ENVIRONMENT}-${env AWS_REGION}
regions:
- us-east-1
Options
CloudFormation modules do not have any module-specific options.
Parameters
Runway can pass Parameters to a CloudFormation module in place of or in addition to an environment file. When
Parameters are passed to the module, the data type is retained (e.g. array, boolean, mapping).
A typical usage pattern would be to use Runway Lookups in combination with Parameters to pass deploy environment
and/or region specific values to the module from the Runway Config File.
74 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Example
deployments:
- modules:
- sampleapp-01.cfn
- path: sampleapp-02.cfn
parameters:
instance_count: ${var instance_count.${env DEPLOY_ENVIRONMENT}}
parameters:
image_id: ${var image_id.%{env AWS_REGION}}
Common Parameters
Runway automatically makes the following commonly used Parameters available to CloudFormation modules.
Note: If these parameter names are already being explicitly defined in the Runway Config File or environment file.
The value provided will be used over that which would be automatically added.
environment (str) Taken from the DEPLOY_ENVIRONMENT environment variable. This will the be current deploy
environment.
region (str) Taken from the AWS_REGION environment variable. This will be the current region being processed.
CFNgin Config File
Runway’s CFNgin makes use of a YAML formatted config file to define the different CloudFormation stacks that make
up a given environment.
The configuration file has a loose definition, with only a few top-level keywords. Other than those keywords, you can
define your own top-level keys to make use of other YAML features like anchors & references to avoid duplicating
config. (See YAML anchors & references for details)
Top Level Keywords
Namespace
You can provide a namespace to create all stacks within. The namespace will be used as a prefix for the name of
any stack that Runway’s CFNgin creates.
In addition, this value will be used to create an S3 bucket that Runway’s CFNgin will use to upload and store all
CloudFormation templates.
In general, this is paired with the concept of Environments to create a namespace per environment.
namespace: ${namespace}
9.2. CloudFormation & Troposphere 75
runway Documentation, Release 1.18.3
Namespace Delimiter
By default, Runway’s CFNgin will use - as a delimiter between your namespace and the declared stack name to build
the actual CloudFormation stack name that gets created. Since child resources of your stacks will, by default, use a
portion of your stack name in the auto-generated resource names, the first characters of your fully-qualified stack name
potentially convey valuable information to someone glancing at resource names. If you prefer to not use a delimiter,
you can pass the namespace_delimiter top-level keyword in the config as an empty string.
See the CloudFormation API Reference for allowed stack name characters
S3 Bucket
Runway’s CFNgin, by default, pushes your CloudFormation templates into an S3 bucket and points CloudForma-
tion at the template in that bucket when launching or updating your stacks. By default it uses a bucket named
stacker-${namespace}, where the namespace is the namespace provided the config.
If you want to change this, provide the cfngin_bucket top-level keyword in the config.
The bucket will be created in the same region that the stacks will be launched in. If you want to change this, or if you
already have an existing bucket in a different region, you can set the cfngin_bucket_region to the region where
you want to create the bucket.
If you want CFNgin to upload templates directly to CloudFormation, instead of first uploading to S3, you can set
cfngin_bucket to an empty string. However, note that template size is greatly limited when uploading directly.
See the CloudFormation Limits Reference.
Persistent Graph
Each time Runway’s CFNgin is run, it creates a dependency graph of Stacks. This is used to determine the order in
which to execute them. This graph can be persisted between runs to track the removal of Stacks the config file.
When a stack is present in the persistent graph but not in the graph constructed from the config file, CFNgin will delete
the stack from CloudFormation. This takes effect during both build and destroy actions.
To enable persistent graph, set persistent_graph_key to a unique value that will be used to construct the path to the
persistent graph object in S3. This object is stored in the CFNgin S3 Bucket which is also used for CloudFormation
templates. The fully qualified path to the object will look like the below.
s3://${cfngin_bucket}/${namespace}/persistent_graphs/${namespace}/${persistent_graph_
˓→key}.json
Note: It is recommended to enable versioning on the CFNgin S3 Bucket when using persistent graph to have a backup
version in the event something unintended happens. A warning will be logged if this is not enabled.
If CFNgin creates an S3 Bucket for you when persistent graph is enabled, it will be created with versioning enabled.
Important: When choosing a value for persistent_graph_key, it is vital to ensure the value is unique for the
namespace being used. If the key is a duplicate, stacks that are not intended to be destroyed will be destroyed.
When executing an action that will be modifying the persistent graph (build or destroy), the S3 object is “locked”.
The lock is a tag applied to the object at the start of one of these actions. The tag-key is cfngin_lock_code and the
tag-value is UUID generated each time a command is run. In order for Runway’s CFNgin to lock a persistent graph
76 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
object, the tag must not be present on the object. For Runway’s CFNgin to act on the graph (modify or unlock) the
value of the tag must match the UUID of the current CFNgin session. If the object is locked or the code does not
match, an error will be raised and no action will be taken. This prevents two parties from acting on the same persistent
graph object concurrently which would create a race condition.
Note: A persistent graph object can be unlocked manually by removing the cfngin_lock_code tag from it. This
should be done with caution as it will cause any active sessions to raise an error.
Persistent Graph Example
config.yml
namespace: example
cfngin_bucket: cfngin-bucket
persistent_graph_key: my_graph # .json - will be appended if not provided
stacks:
first_stack:
...
new_stack:
...
s3://cfngin-bucket/persistent_graphs/example/my_graph.json
{
"first_stack": [],
"removed_stack": [
"first_stack"
]
}
Result
Given the above config file and persistent graph, when running runway deploy, the following will occur.
1. The {"Key": "cfngin_lock_code", "Value": "123456"} tag is applied to s3://cfngin-
bucket/persistent_graphs/example/my_graph.json to lock it to the current session.
2. removed_stack is deleted from CloudFormation and deleted from the persistent graph object in S3.
3. first_stack is updated in CloudFormation and updated in the persistent graph object in S3 (incase dependencies
change).
4. new_stack is created in CloudFormation and added to the persistent graph object in S3.
5. The {"Key": "cfngin_lock_code", "Value": "123456"} tag is removed from s3://cfngin-
bucket/persistent_graphs/example/my_graph.json to unlock it for use in other sessions.
9.2. CloudFormation & Troposphere 77
runway Documentation, Release 1.18.3
Module Paths
When setting the classpath for Blueprints/hooks, it is sometimes desirable to load modules from outside the default
sys.path (e.g., to include modules inside the same repo as config files).
Adding a path (e.g. ./) to the sys_path top-level keyword will allow modules from that path location to be used.
Service Role
By default Runway’s CFNgin doesn’t specify a service role when executing changes to CloudFormation stacks. If
you would prefer that it do so, you can set service_role to be the ARN of the role that CFNgin should use when
executing CloudFormation changes.
This is the equivalent of setting RoleARN on a call to the following CloudFormation api calls: CreateStack,
UpdateStack, CreateChangeSet.
See the AWS documentation for AWS CloudFormation Service Roles.
Remote Packages
The package_sources top-level keyword can be used to define remote sources for Blueprints (e.g., retrieving
src/runway/blueprints on github at tag v1.3.7).
The only required key for a git repository config is uri, but branch, tag, & commit can also be specified.
package_sources:
git:
- uri: [email protected]:onicagroup/runway.git
- uri: [email protected]:onicagroup/runway.git
tag: 1.0.0
paths:
- src/runway/blueprints
- uri: [email protected]:contoso/webapp.git
branch: staging
- uri: [email protected]:contoso/foo.git
commit: 12345678
If no specific commit or tag is specified for a repo, the remote repository will be checked for newer commits on every
execution of CFNgin.
For .tar.gz & zip archives on s3, specify a bucket & key.
package_sources:
s3:
- bucket: mycfngins3bucket
key: archives/blueprints-v1.zip
paths:
- blueprints
- bucket: anothers3bucket
key: public/public-blueprints-v2.tar.gz
requester_pays: true
- bucket: yetanothers3bucket
key: sallys-blueprints-v1.tar.gz
# use_latest defaults to true - will update local copy if the
# last modified date on S3 changes
use_latest: false
78 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Local directories can also be specified.
package_sources:
local:
- source: ../vpc
Use the paths option when subdirectories of the repo/archive/directory should be added to CFNgins’s sys.path.
Cloned repos/archives will be cached between builds; the cache location defaults to ~/.runway_cache but can be
manually specified via the cfngin_cache_dir top-level keyword.
Remote Configs
Configuration YAMLs from remote configs can also be used by specifying a list of configs in the repo to use.
package_sources:
git:
- uri: [email protected]:acmecorp/cfngin_blueprints.git
configs:
- vpc.yaml
In this example, the configuration in vpc.yaml will be merged into the running current configuration, with the
current configuration’s values taking priority over the values in vpc.yaml.
Dictionary Stack Names & Hook Paths
To allow remote configs to be selectively overridden, stack names & hook paths are defined as dictionaries.
pre_build:
my_route53_hook:
path: runway.cfngin.hooks.route53.create_domain:
required: true
enabled: true
args:
domain: mydomain.com
stacks:
vpc-example:
class_path: cfngin_blueprints.vpc.VPC
locked: false
enabled: true
bastion-example:
class_path: cfngin_blueprints.bastion.Bastion
locked: false
enabled: true
9.2. CloudFormation & Troposphere 79
runway Documentation, Release 1.18.3
Pre & Post Hooks
Many actions allow for pre & post hooks. These are python functions/methods that are executed before, and after the
action is taken for the entire config. Hooks can be enabled or disabled, per hook. Only the following actions allow
pre/post hooks:
• build (keywords: pre_build, post_build)
• destroy (keywords: pre_destroy, post_destroy)
There are a few reasons to use these, though the most common is if you want better control over the naming of a
resource than what CloudFormation allows.
The keyword is a dictionary with the following keys:
path: the python import path to the hook.
data_key: If set, and the hook returns data (a dictionary), the results will be stored in the context.hook_data
with the data_key as its key.
required: Whether to stop execution if the hook fails.
enabled: Whether to execute the hook every CFNgin run. Default: True. This is a bool that grants you the ability to
execute a hook per environment when combined with a variable pulled from an environment file.
args: A dictionary of arguments to pass to the hook with support for lookups. Note that lookups that change the order
of execution, like output, can only be used in a post hook but hooks like rxref are able to be used with
either pre or post hooks.
An example using the create_domain hook for creating a route53 domain before the build action:
pre_build:
create_my_domain:
path: runway.cfngin.hooks.route53.create_domain
required: true
enabled: true
args:
domain: mydomain.com
An example of a hook using the create_domain_bool variable from the environment file to determine if the hook
should run. Set create_domain_bool: true or create_domain_bool: false in the environment
file to determine if the hook should run in the environment CFNgin is running against:
pre_build:
create_my_domain:
path: runway.cfngin.hooks.route53.create_domain
required: true
enabled: ${create_domain_bool}
args:
domain: mydomain.com
An example of a custom hooks using various lookups in it’s arguments:
pre_build:
custom_hook1:
path: path.to.hook1.entry_point
args:
ami: ${ami [<region>@]owners:self,888888888888,amazon name_regex:server[0-9]+
˓→architecture:i386}
user_data: ${file parameterized-64:file://some/path}
(continues on next page)
80 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
(continued from previous page)
db_endpoint: ${rxref some-stack::Endpoint}
subnet: ${xref some-stack::Subnet}
db_creds: ${ssm MyDBUser::region=us-east-1}
custom_hook2:
path: path.to.hook.entry_point
args:
bucket: ${dynamodb us-east-1:TestTable@TestKey:TestVal.BucketName}
bucket_region: ${envvar AWS_REGION} # this variable is set by Runway
files:
- ${file plain:file://some/path}
post_build:
custom_hook3:
path: path.to.hook3.entry_point
args:
nlb: ${output nlb-stack::Nlb} # output can only be used as a post hook
Tags
CloudFormation supports arbitrary key-value pair tags. All stack-level, including automatically created tags, are
propagated to resources that AWS CloudFormation supports. See AWS CloudFormation Resource Tags Type for more
details. If no tags are specified, the cfngin_namespace tag is applied to your stack with the value of namespace
as the tag value.
If you prefer to apply a custom set of tags, specify the top-level keyword tags as a map.
Example:
tags:
"hello": world
"my_tag:with_colons_in_key": ${dynamic_tag_value_from_my_env}
simple_tag: simple value
If you prefer to have no tags applied to your stacks (versus the default tags that CFNgin applies), specify an empty
map for the top-level keyword.
tags: {}
Mappings
Mappings are dictionaries that are provided as Mappings to each CloudFormation stack that CFNgin produces.
These can be useful for providing things like different AMIs for different instance types in different regions.
mappings:
AmiMap:
us-east-1:
NAT: ami-ad227cc4
ubuntu1404: ami-74e27e1c
bastion: ami-74e27e1c
us-west-2:
NAT: ami-290f4119
(continues on next page)
9.2. CloudFormation & Troposphere 81
runway Documentation, Release 1.18.3
(continued from previous page)
ubuntu1404: ami-5189a661
bastion: ami-5189a661
These can be used in each Blueprints/stack as usual.
Lookups
Lookups allow you to create custom methods which take a value and are resolved at build time. The resolved values
are passed to the Blueprints before it is rendered. For more information, see the Lookups documentation.
CFNgin provides some common Lookups, but it is sometimes useful to have your own custom lookup that doesn’t get
shipped with Runway. You can register your own lookups by defining a lookups key.
lookups:
custom: path.to.lookup.handler
The key name for the lookup will be used as the type name when registering the lookup. The value should be the path
to a valid lookup handler.
You can then use these within your config.
conf_value: ${custom some-input-here}
Stacks
This is the core part of the config - this is where you define each of the stacks that will be deployed in the environment.
The top-level keyword stacks is populated with a dictionary, each representing a single stack to be built.
They key used in the dictionary of stacks is used as the logical name of the stack. The value here must be unique
within the config. If no stack_name is provided, the value here will be used for the name of the CloudFormation
stack.
A stack has the following keys:
class_path (Optional[str]) The python class path to the Blueprints to be used. Specify this or template_path for
the stack.
description (Optional[str]) A short description to apply to the stack. This overwrites any description
provided in the Blueprints. See: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/
template-description-structure.html
enabled (Optional[bool]) If set to false, the stack is disabled, and will not be built or updated. This can allow you
to disable stacks in different environments. (default: true)
in_progress_behavior (Optional[str]) If provided, specifies the behavior for when a stack is in
CREATE_IN_PROGRESS or UPDATE_IN_PROGRESS. By default, CFNgin will raise an exception if
the stack is in an IN_PROGRESS state. You can set this option to wait and CFNgin will wait for the previous
update to complete before attempting to update the stack.
locked (Optional[bool]) If set to true, the stack is locked and will not be updated unless the stack is passed to
CFNgin via the --force flag. This is useful for risky stacks that you don’t want to take the risk of allowing
CloudFormation to update, but still want to make sure get launched when the environment is first created. When
locked, it’s not necessary to specify a class_path or template_path. (default: false)
82 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
protected (Optional[bool]) When running an update in non-interactive mode, if a stack has protected: true
and would get changed, CFNgin will switch to interactive mode for that stack, allowing you to approve/skip the
change. (default: false)
required_by (Optional[List[str]]) A list of other stacks or targets that require this stack. It’s an inverse to
requires.
requires (Optional[List[str]]) A list of other stacks this stack requires. This is for explicit dependencies - you do not
need to set this if you refer to another stack in a Parameter, so this is rarely necessary.
stack_name (Optional[str]) If provided, this will be used as the name of the CloudFormation stack. Unlike name,
the value doesn’t need to be unique within the config, since you could have multiple stacks with the same name,
but in different regions or accounts. (note: the namespace from the environment will be prepended to this)
stack_policy_path (Optional[str]) If provided, specifies the path to a JSON formatted stack policy that will be ap-
plied when the CloudFormation stack is created and updated. You can use stack policies to prevent Cloud-
Formation from making updates to protected resources (e.g. databases). See: https://docs.aws.amazon.com/
AWSCloudFormation/latest/UserGuide/protect-stack-resources.html
tags (Optional[Dict[str, str]]) A dictionary of CloudFormation tags to apply to this stack. This will be combined
with the global tags, but these tags will take precedence.
template_path (Optional[str]) Path to raw CloudFormation template (JSON or YAML). Specify this or
class_path for the stack. Path can be specified relative to the current working directory (e.g. templates
stored alongside the Config), or relative to a directory in the python sys.path (i.e. for loading templates
retrieved via packages_sources).
termination_protection (Optional[bool]) If true, the stack will be protected from termination by CloudFormation.
Any attempts to destroy the stack (using Runway, the AWS Console, AWS API, etc) will be prevented unless
manually disabled. When updating a stack and the value has been changed to false, termination protection
will be disabled. (default: false)
variables (Optional[Dict[str, str]]) A dictionary of Variables to pass into the Blueprints when rendering the Cloud-
Formation template. Variables can be any valid YAML data structure.
Stacks Example
Here’s an example used to create a VPC:
stacks:
- name: vpc-example
class_path: blueprints.vpc.VPC
locked: false
enabled: true
variables:
InstanceType: t2.small
SshKeyName: default
ImageName: NAT
AZCount: 2
PublicSubnets:
- 10.128.0.0/24
- 10.128.1.0/24
- 10.128.2.0/24
- 10.128.3.0/24
PrivateSubnets:
- 10.128.8.0/22
- 10.128.12.0/22
- 10.128.16.0/22
(continues on next page)
9.2. CloudFormation & Troposphere 83
runway Documentation, Release 1.18.3
(continued from previous page)
- 10.128.20.0/22
CidrBlock: 10.128.0.0/16
Custom Log Formats
By default, Runway’s CFNgin uses the following log_formats:
log_formats:
info: "[%(asctime)s] %(message)s"
color: "[%(asctime)s] \033[%(color)sm%(message)s\033[39m"
debug: "[%(asctime)s] %(levelname)s %(threadName)s %(name)s:%(lineno)d(
˓→%(funcName)s): %(message)s"
You may optionally provide custom log_formats. In this example, we add the environment name to each log line.
log_formats:
info: "[%(asctime)s] ${environment} %(message)s"
color: "[%(asctime)s] ${environment} \033[%(color)sm%(message)s\033[39m"
You may use any of the standard Python logging module format attributes when building your log_formats.
Variables
Variables are values that will be passed into a Blueprints before it is rendered. Variables can be any valid YAML data
structure and can leverage Lookups to expand values at build time.
The following concepts make working with variables within large templates easier:
YAML anchors & references
If you have a common set of variables that you need to pass around in many places, it can be annoying to have to copy
and paste them in multiple places. Instead, using a feature of YAML known as anchors & references, you can define
common values in a single place and then refer to them with a simple syntax.
For example, say you pass a common domain name to each of your stacks, each of them taking it as a Variable. Rather
than having to enter the domain into each stack (and hopefully not typo’ing any of them) you could do the following:
domain_name: &domain mydomain.com
Now you have an anchor called domain that you can use in place of any value in the config to provide the value
mydomain.com. You use the anchor with a reference.
stacks:
- name: vpc
class_path: blueprints.vpc.VPC
variables:
DomainName:
*
domain
Even more powerful is the ability to anchor entire dictionaries, and then reference them in another dictionary, effec-
tively providing it with default values.
84 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
common_variables: &common_variables
DomainName: mydomain.com
InstanceType: m3.medium
AMI: ami-12345abc
Now, rather than having to provide each of those variables to every stack that could use them, you can just do this
instead.
stacks:
- name: vpc
class_path: blueprints.vpc.VPC
variables:
<< :
*
common_variables
InstanceType: c4.xlarge # override the InstanceType in this stack
Using Outputs as Variables
Since Runway’s CFNgin encourages the breaking up of your CloudFormation stacks into entirely separate stacks,
sometimes you’ll need to pass values from one stack to another. The way this is handled in CFNgin is by having one
stack provide Outputs for all the values that another stack may need, and then using those as the inputs for another
stack’s Variables. CFNgin makes this easier for you by providing a syntax for Variables that will cause CFNgin to
automatically look up the values of Outputs from another stack in its config. To do so, use the following format for
the Variable on the target stack.
MyParameter: ${output OtherStack::OutputName}
Since referencing Outputs from stacks is the most common use case, output is the default lookup type. For more
information see Lookups.
In this example config - when building things inside a VPC, you will need to pass the VpcId of the VPC that you want
the resources to be located in. If the vpc stack provides an Output called VpcId, you can reference it easily.
domain_name: my_domain &domain
stacks:
- name: vpc
class_path: blueprints.vpc.VPC
variables:
DomainName:
*
domain
- name: webservers
class_path: blueprints.asg.AutoscalingGroup
variables:
DomainName:
*
domain
VpcId: ${output vpc::VpcId} # gets the VpcId Output from the vpc stack
Note: Doing this creates an implicit dependency from the webservers stack to the vpc stack, which will cause CFNgin
to submit the vpc stack, and then wait until it is complete until it submits the webservers stack.
9.2. CloudFormation & Troposphere 85
runway Documentation, Release 1.18.3
Environment File
When using Runway’s CFNgin, you can optionally provide an “environment” file. The CFNgin config file will be
interpolated as a string.Template using the key/value pairs from the environment file. The format of the file is a single
key/value per line, separated by a colon (:).
File Naming
Environment files must follow a specific naming format in order to be recognized by Runway. The files must also be
stored at the root of the module’s directory.
<DEPLOY_ENVIRONMENT>-<AWS_REGION>.env The typical naming format that will be used for these files
specifies the name of the DEPLOY_ENVIRONMENT and AWS_REGION in which to use the file.
<DEPLOY_ENVIRONMENT>.env The region can optionally be omitted to apply a single file to all regions.
Files following both naming schemes may be used. The file with the most specific name takes precedence. Values
passed in as parameters from the Runway Config File take precedence over those provided in an environment file.
Usage
A pretty common use case is to have separate environments that you want to look mostly the same, though with
some slight modifications. For example, you might want a production and a staging environment. The production
environment likely needs more instances, and often those instances will be of a larger instance type. Environments
allow you to use your existing CFNgin config, but provide different values based on the environment file chosen.
Example
vpcID: vpc-12345678
Provided the key/value vpcID above, you will now be able to use this in your configs for the specific environment
you are deploying into. They act as keys that can be used in your config file, providing a sort of templating ability.
This allows you to change the values of your config based on the environment you are in. For example, if you have a
webserver stack, and you need to provide it a variable for the instance size it should use, you would have something
like this in your config file.
stacks:
- name: webservers
class_path: blueprints.asg.AutoscalingGroup
variables:
InstanceType: m3.medium
But what if you needed more CPU in your production environment, but not in your staging? Without Environments,
you’d need a separate config for each. With environments, you can simply define two different environment files with
the appropriate InstanceType in each, and then use the key in the environment files in your config.
# in the file: stage.env
web_instance_type: m3.medium
# in the file: prod.env
web_instance_type: c4.xlarge
# in your config file:
(continues on next page)
86 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
(continued from previous page)
stacks:
- name: webservers
class_path: blueprints.asg.AutoscalingGroup
variables:
InstanceType: ${web_instance_type}
9.2.2 Directory Structure
Example directory structures for a CloudFormation module.
Blueprints
Important: Blueprints must be importable by python. (e.g. directory contains __init__.py)
.
Pipfile
Pipfile.lock
runway.variables.yml
runway.yml
sampleapp.cfn
blueprints
__init__.py
my_blueprint.py
dev-us-east-1.env
cfngin.yml
Cloudformation Templates
Important: CloudFormation templates can’t be stored in the root of the module directory. They must be in a
subdirectory or external to the module.
.
Pipfile
Pipfile.lock
runway.variables.yml
runway.yml
sampleapp.cfn
templates
template-01.yml
template-02.json
dev-us-east-1.env
01-cfngin.yml
02-cfngin.yml
9.2. CloudFormation & Troposphere 87
runway Documentation, Release 1.18.3
9.2.3 Advanced Features
Advanced features and detailed information for using Runway’s CFNgin for CloudFormation modules.
Blueprints
Blueprints are python classes that dynamically build CloudFormation templates. Where you would specify a raw
Cloudformation template in a stack using the template_path key, you instead specify a Blueprint python file
using the class_path key.
Traditionally Blueprints are built using troposphere, but that is not absolutely necessary.
Making your own should be easy, and you can take a lot of examples from Runway blueprints. In the end, all that
is required is that the Blueprint is a subclass of runway.cfngin.blueprints.base and it have the following
methods:
# Initializes the Blueprint
def __init__(self, name, context, mappings=None):
# Updates self.template to create the actual template
def create_template(self):
# Returns a tuple: (version, rendered_template)
def render_template(self):
Variables
A Blueprint can define a VARIABLES property that defines the variables it accepts from the Config Variables.
VARIABLES should be a dictionary of <variable name>: <variable definition>. The variable defi-
nition should be a dictionary which supports the following optional keys:
type: The type for the variable value. This can either be a native python type or one of the Variable Types.
default: The default value that should be used for the variable if none is provided in the config.
description: A string that describes the purpose of the variable.
validator: An optional function that can do custom validation of the variable. A validator function should take a
single argument, the value being validated, and should return the value if validation is successful. If there is an
issue validating the value, an exception (ValueError, TypeError, etc) should be raised by the function.
no_echo: Only valid for variables whose type subclasses CFNType. Whether to mask the parameter value whenever
anyone makes a call that describes the stack. If you set the value to true, the parameter value is masked with
asterisks (*).
allowed_values: Only valid for variables whose type subclasses CFNType. The set of values that should be allowed
for the CloudFormation Parameter.
allowed_pattern: Only valid for variables whose type subclasses CFNType. A regular expression that represents the
patterns you want to allow for the CloudFormation Parameter.
max_length: Only valid for variables whose type subclasses CFNType. The maximum length of the value for the
CloudFormation Parameter.
min_length: Only valid for variables whose type subclasses CFNType. The minimum length of the value for the
CloudFormation Parameter.
88 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
max_value: Only valid for variables whose type subclasses CFNType. The max value for the CloudFormation
Parameter.
min_value: Only valid for variables whose type subclasses CFNType. The min value for the CloudFormation Pa-
rameter.
constraint_description: Only valid for variables whose type subclasses CFNType. A string that explains the con-
straint when the constraint is violated for the CloudFormation Parameter.
Variable Types
Any native python type can be specified as the type for a variable. You can also use the following custom types:
TroposphereType
The TroposphereType can be used to generate resources for use in the Blueprint directly from user-specified
configuration. Which case applies depends on what type was chosen, and how it would be normally used in the
Blueprint (and CloudFormation in general).
Resource Types
When type is a Resource Type, the value specified by the user in the configuration file must be a dictionary, but with
two possible structures.
When many is disabled, the top-level dictionary keys correspond to parameters of the type constructor. The key-
value pairs will be used directly, and one object will be created and stored in the variable.
When many is enabled, the top-level dictionary keys are resource titles, and the corresponding values are themselves
dictionaries, to be used as parameters for creating each of multiple type objects. A list of those objects will be stored
in the variable.
Property Types
When type is a Property Type the value specified by the user in the configuration file must be a dictionary or a list of
dictionaries.
When many is disabled, the top-level dictionary keys correspond to parameters of the type constructor. The key-
value pairs will be used directly, and one object will be created and stored in the variable.
When many is enabled, a list of dictionaries is expected. For each element, one corresponding call will be made to
the type constructor, and all the objects produced will be stored (also as a list) in the variable.
Optional variables
In either case, when optional is enabled, the variable may have no value assigned, or be explicitly assigned a null
value. When that happens the variable’s final value will be None.
9.2. CloudFormation & Troposphere 89
runway Documentation, Release 1.18.3
Example
Below is an annotated example:
from runway.cfngin.blueprints.base import Blueprint
from runway.cfngin.blueprints.variables.types import TroposphereType
from troposphere import s3, sns
class Buckets(Blueprint):
VARIABLES = {
# Specify that Buckets will be a list of s3.Bucket types.
# This means the config should a dictionary of dictionaries
# which will be converted into troposphere buckets.
"Buckets": {
"type": TroposphereType(s3.Bucket, many=True),
"description": "S3 Buckets to create.",
},
# Specify that only a single bucket can be passed.
"SingleBucket": {
"type": TroposphereType(s3.Bucket),
"description": "A single S3 bucket",
},
# Specify that Subscriptions will be a list of sns.Subscription types.
# Note: sns.Subscription is the property type, not the standalone
# sns.SubscriptionResource.
"Subscriptions": {
"type": TroposphereType(sns.Subscription, many=True),
"description": "Multiple SNS subscription designations"
},
# Specify that only a single subscription can be passed, and that it
# is made optional.
"SingleOptionalSubscription": {
"type": TroposphereType(sns.Subscription, optional=True),
"description": "A single, optional SNS subscription designation"
}
}
def create_template(self):
t = self.template
variables = self.get_variables()
# The Troposphere s3 buckets have already been created when we
# access variables["Buckets"], we just need to add them as
# resources to the template.
[t.add_resource(bucket) for bucket in variables["Buckets"]]
# Add the single bucket to the template. You can use
# `Ref(single_bucket)` to pass CloudFormation references to the
# bucket just as you would with any other Troposphere type.
# single_bucket = variables["SingleBucket"]
t.add_resource(single_bucket)
subscriptions = variables["Subscriptions"]
optional_subscription = variables["SingleOptionalSubscription"]
# Handle it in some special way...
if optional_subscription is not None:
(continues on next page)
90 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
(continued from previous page)
subscriptions.append(optional_subscription)
t.add_resource(sns.Topic(
TopicName="one-test",
Subscriptions=))
t.add_resource(sns.Topic(
TopicName="another-test",
Subscriptions=subscriptions))
A sample config for the above:
stacks:
- name: buckets
class_path: path.to.above.Buckets
variables:
Buckets:
# resource name (title) that will be added to CloudFormation.
FirstBucket:
# name of the s3 bucket
BucketName: my-first-bucket
SecondBucket:
BucketName: my-second-bucket
SingleBucket:
# resource name (title) that will be added to CloudFormation.
MySingleBucket:
BucketName: my-single-bucket
Subscriptions:
- Endpoint: one-lambda
Protocol: lambda
- Endpoint: another-lambda
Protocol: lambda
# The following could be omitted entirely
SingleOptionalSubscription:
Endpoint: a-third-lambda
Protocol: lambda
CFNType
The CFNType can be used to signal that a variable should be submitted to CloudFormation as a Parameter in-
stead of only available to the Blueprint when rendering. This is useful if you want to leverage AWS- Spe-
cific Parameter types (e.g. List<AWS::EC2::Image::Id>) or Systems Manager Parameter Store values (e.g.
AWS::SSM::Parameter::Value<String>). See runway.cfngin.blueprints.variables.types
for available subclasses of the CFNType.
9.2. CloudFormation & Troposphere 91
runway Documentation, Release 1.18.3
Example
Below is an annotated example:
from runway.cfngin.blueprints.base import Blueprint
from runway.cfngin.blueprints.variables.types import (
CFNString,
EC2AvailabilityZoneNameList,
)
class SampleBlueprint(Blueprint):
VARIABLES = {
"String": {
"type": str,
"description": "Simple string variable",
},
"List": {
"type": list,
"description": "Simple list variable",
},
"CloudFormationString": {
"type": CFNString,
"description": "A variable which will create a CloudFormation Parameter
˓→of type String",
},
"CloudFormationSpecificType": {
"type": EC2AvailabilityZoneNameList,
"description": "A variable which will create a CloudFormation Parameter
˓→of type List<AWS::EC2::AvailabilityZone::Name>"
},
}
def create_template(self):
t = self.template
# `get_variables` returns a dictionary of <variable name>: <variablevalue>.
# For the subclasses of `CFNType`, the values are
# instances of `CFNParameter` which have a `ref` helper property
# which will return a troposphere `Ref` to the parameter name.
variables = self.get_variables()
t.add_output(Output("StringOutput", variables["String"]))
# variables["List"] is a native list
for index, value in enumerate(variables["List"]):
t.add_output(Output("ListOutput:{}".format(index), value))
# `CFNParameter` values (which wrap variables with a `type`
# that is a `CFNType` subclass) can be converted to troposphere
# `Ref` objects with the `ref` property
t.add_output(Output("CloudFormationStringOutput",
variables["CloudFormationString"].ref))
t.add_output(Output("CloudFormationSpecificTypeOutput",
variables["CloudFormationSpecificType"].ref))
92 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Utilizing Stack name within your Blueprint
Sometimes your Blueprint might want to utilize the already existing stack name within your Blueprint. Runway’s
CFNgin provides access to both the fully qualified stack name matching what’s shown in the CloudFormation console,
in addition to the stacks short name you have set in your YAML config.
Referencing Fully Qualified Stack name
The fully qualified name is a combination of the CFNgin namespace + the short name (what you set as name
in your YAML config file). If your CFNgin namespace is CFNginIsCool and the stacks short name is
myAwesomeEC2Instance, the fully qualified name would be:
CFNginIsCool-myAwesomeEC2Instance
To use this in your Blueprint, you can get the name from context using self.context.get_fqn(self.name).
Referencing the Stack short name
The Stack short name is the name you specified for the stack within your YAML config. It does not include the names-
pace. If your CFNgin namespace is CFNginIsCool and the stacks short name is myAwesomeEC2Instance, the
short name would be:
myAwesomeEC2Instance
To use this in your Blueprint, you can get the name from self.name: self.name
Example
Below is an annotated example creating a security group:
# we are importing Ref to allow for CFN References in the EC2 resource. Tags
# will be used to set the Name tag
from troposphere import Ref, ec2, Tags
from runway.cfngin.blueprints.base import Blueprint
# CFNString is imported to allow for stand alone stack use
from runway.cfngin.blueprints.variables.types import CFNString
class SampleBlueprint(Blueprint):
# VpcId set here to allow for Blueprint to be reused
VARIABLES = {
"VpcId": {
"type": CFNString,
"description": "The VPC to create the Security group in",
}
}
def create_template(self):
template = self.template
# Assigning the variables to a variable
variables = self.get_variables()
(continues on next page)
9.2. CloudFormation & Troposphere 93
runway Documentation, Release 1.18.3
(continued from previous page)
# now adding a SecurityGroup resource named `SecurityGroup` to the CFN template
template.add_resource(
ec2.SecurityGroup(
"SecurityGroup",
# Referencing the VpcId set as the variable
VpcId=variables['VpcId'].ref,
# Setting the group description as the fully qualified name
GroupDescription=self.context.get_fqn(self.name),
# setting the Name tag to be the stack short name
Tags=Tags(
Name=self.name
)
)
)
Testing Blueprints
When writing your own Blueprints its useful to write tests for them in order to make sure they behave the way you
expect they would, especially if there is any complex logic inside.
To this end, a sub-class of the unittest.TestCase class has been provided: runway.cfngin.blueprints.
testutil.BlueprintTestCase. You use it like the regular TestCase class, but it comes with an addition
assertion: assertRenderedBlueprint. This assertion takes a Blueprint object and renders it, then compares it
to an expected output, usually in tests/fixtures/blueprints.
Yaml (CFNgin) format tests
In order to wrap the BlueprintTestCase tests in a format similar to CFNgin’s stack format, the
YamlDirTestGenerator class is provided. When subclassed in a directory, it will search for yaml files in that
directory with certain structure and execute a test case for it. As an example:
---
namespace: test
stacks:
- name: test_stack
class_path: cfngin_blueprints.s3.Buckets
variables:
var1: val1
When run from tests, this will create a template fixture file called test_stack.json containing the output from the
cfngin_blueprints.s3.Buckets template.
Hooks
A hook is a python function or class method that is executed before or after the action is taken. To see how to define
hooks in a config file see the Pre & Post Hooks documentation.
94 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Built-in Hooks
acm.Certificate
Requirements
• Route 53 hosted zone
– authoritative for the domain the certificate is being created for
– in the same AWS account as the certificate being created
Description
Manage a DNS validated certificate in AWS Certificate Manager.
When used in the pre_build or post_build stage this hook will create a CloudFormation stack containing a DNS
validated certificate. It will automatically create a record in Route 53 to validate the certificate and wait for the stack
to complete before returning the CertificateArn as hook data. The CloudFormation stack also outputs the ARN
of the certificate as CertificateArn so that it can be referenced from other stacks.
When used in the pre_destroy or post_destroy stage this hook will delete the validation record from Route 53 then
destroy the stack created during a deploy stage.
If the hook fails during a deploy stage (e.g. stack rolls back or Route 53 can’t be updated) all resources managed by
this hook will be destroyed. This is done to avoid orphaning resources/record sets which would cause errors during
subsequent runs. Resources effected include the CloudFormation stack it creates, ACM certificate, and Route 53
validation record.
Hook Path
runway.cfngin.hooks.acm.Certificate
Args
alt_names (Optional[List[str]]) Additional FQDNs to be included in the Subject Alternative Name extension of the
ACM certificate. For example, you can add www.example.net to a certificate for which the domain field is
www.example.com if users can reach your site by using either name.
domain (str) The fully qualified domain name (FQDN), such as www.example.com, with which you want to secure
an ACM certificate. Use an asterisk (
*
) to create a wildcard certificate that protects several sites in the same
domain. For example, *.example.com protects www.example.com, site.example.com, and images.example.com.
hosted_zone_id (str) The ID of the Route 53 Hosted Zone that contains the resource record sets that you want to
change. This must exist in the same account that the certificate will be created in.
stack_name (Optional[str]) Provide a name for the stack used to create the certificate. If not provided, the domain is
used (replacing . with -). If the is provided in a deploy stage, its needs to be provided in the matching destroy
stage.
ttl (Optional[int]) The resource record cache time to live (TTL), in seconds. (default: 300)
9.2. CloudFormation & Troposphere 95
runway Documentation, Release 1.18.3
Example
namespace: example
cfngin_bucket: ''
sys_path: ./
pre_build:
acm-cert:
path: runway.cfngin.hooks.acm.Certificate
required: true
args:
domain: www.example.com
hosted_zone_id: ${rxref example-com::HostedZone}
stack:
sampleapp:
class_path: blueprints.sampleapp.BlueprintClass
variables:
cert_arn: ${rxref www-example-com::CertificateArn}
post_destroy:
acm-cert:
path: runway.cfngin.hooks.acm.Certificate
required: true
args:
domain: www.example.com
hosted_zone_id: ${rxref example-com::HostedZone}
aws_lambda.upload_lambda_functions
Description
Build Lambda payloads from user configuration and upload them to S3.
Constructs ZIP archives containing files matching specified patterns for each function, uploads the result to Ama-
zon S3, then stores objects (of type troposphere.awslambda.Code) in the context’s hook data, ready to be
referenced in blueprints.
Configuration consists of some global options, and a dictionary of function specifications. In the specifications, each
key indicating the name of the function (used for generating names for artifacts), and the value determines what files
to include in the ZIP (see more details below).
If a requirements.txt or Pipfile/Pipfile.lock files are found at the root of the provided path, the
hook will use the appropriate method to package dependencies with your source code automatically. If you want to
explicitly use pipenv over pip, provide use_pipenv: true for the function.
Docker can be used to collect python dependencies instead of using system python to build appropriate binaries for
Lambda. This can be done by including the dockerize_pip configuration option which can have a value of true
or non-linux.
Payloads are uploaded to either a custom bucket or the CFNgin default bucket, with the key containing it’s checksum,
to allow repeated uploads to be skipped in subsequent runs.
96 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Hook Path
runway.cfngin.hooks.aws_lambda.upload_lambda_functions
Args
bucket (Optional[str]) Custom bucket to upload functions to. Omitting it will cause the default CFNgin bucket to be
used.
bucket_region (Optional[str]) The region in which the bucket should exist. If not given, the region will be either be
that of the global cfngin_bucket_region setting, or else the region in use by the provider.
prefix (Optional[str]) S3 key prefix to prepend to the uploaded zip name.
follow_symlinks (Optional[bool]) Will determine if symlinks should be followed and included with the zip artifact.
(default: False)
payload_acl (Optional[str]) The canned S3 object ACL to be applied to the uploaded payload. (default: private)
functions (Dict[str, Any]) Configurations of desired payloads to build. Keys correspond to function names, used to
derive key names for the payload. Each value should itself be a dictionary, with the following data:
docker_file (Optional[str]) Path to a local DockerFile that will be built and used for dockerize_pip. Must
provide exactly one of docker_file, docker_image, or runtime.
docker_image (Optional[str]) Custom Docker image to use with dockerize_pip. Must provide exactly
one of docker_file, docker_image, or runtime.
dockerize_pip (Optional[Union[str, bool]]) Whether to use Docker when restoring dependencies with pip.
Can be set to true/false or the special string non-linux which will only run on non Linux systems.
To use this option Docker must be installed.
exclude (Optional[Union[str, List[str]]]) Pattern or list of patterns of files to exclude from the payload. If
provided, any files that match will be ignored, regardless of whether they match an inclusion pattern.
Commonly ignored files are already excluded by default, such as .git, .svn, __pycache__,
*
.pyc,
.gitignore, etc.
include (Optional[Union[str, List[str]]]) Pattern or list of patterns of files to include in the payload. If pro-
vided, only files that match these patterns will be included in the payload.
Omitting it is equivalent to accepting all files that are not otherwise excluded.
path (str) Base directory of the Lambda function payload content. If it not an absolute path, it will be consid-
ered relative to the directory containing the CFNgin configuration file in use.
Files in this directory will be added to the payload ZIP, according to the include and exclude patterns. If
no patterns are provided, all files in this directory (respecting default exclusions) will be used.
Files are stored in the archive with path names relative to this directory. So, for example, all the files
contained directly under this directory will be added to the root of the ZIP file.
python_path (Optional[str]) Absolute path to a python interpreter to use for pip/pipenv actions. If not
provided, the current python interpreter will be used for pip and pipenv will be used from the current
$PATH.
runtime (Optional[str]) Runtime of the AWS Lambda Function being uploaded. Used with
dockerize_pip to automatically select the appropriate Docker image to use. Must provide
exactly one of docker_file, docker_image, or runtime.
use_pipenv (Optional[bool]): Will determine if pipenv will be used to generate requirements.txt from an ex-
isting Pipfile. To use this option pipenv must be installed.
9.2. CloudFormation & Troposphere 97
runway Documentation, Release 1.18.3
Example
Hook configuration
pre_build:
upload_functions:
path: runway.cfngin.hooks.aws_lambda.upload_lambda_functions
required: true
enabled: true
data_key: lambda
args:
bucket: custom-bucket
follow_symlinks: true
prefix: cloudformation-custom-resources/
payload_acl: authenticated-read
functions:
MyFunction:
path: ./lambda_functions
dockerize_pip: non-linux
use_pipenv: true
runtime: python3.8
include:
- '
*
.py'
- '
*
.txt'
exclude:
- '
*
.pyc'
- test/
Blueprint Usage
from troposphere.awslambda import Function
from runway.cfngin.blueprints.base import Blueprint
class LambdaBlueprint(Blueprint):
def create_template(self):
code = self.context.hook_data['lambda']['MyFunction']
self.template.add_resource(
Function(
'MyFunction',
Code=code,
Handler='my_function.handler',
Role='...',
Runtime='python2.7'
)
)
98 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
build_staticsite.build
Description
Build static site. Used by the staticsite module type.
Hook Path
runway.hooks.staticsite.build_staticsite.build
Args
See staticsite module documentation for details.
cleanup_s3.purge_bucket
Description
Delete objects in bucket. Primarily used as a pre_destroy hook before deleting an S3 bucket.
Hook Path
runway.hooks.cleanup_s3.purge_bucket
Args
bucket_name (str) Name of the S3 bucket.
bucket_output_lookup (str) Value to pass to runway.cfngin.lookups.handlers.output.
OutputLookup to retrieve an S3 bucket name.
bucket_rxref_lookup (str) Value to pass to runway.cfngin.lookups.handlers.rxref.RxrefLookup
to retrieve an S3 bucket name.
bucket_xref_lookup (str) Value to pass to runway.cfngin.lookups.handlers.xref.XrefLookup to
retrieve an S3 bucket name.
cleanup_ssm.delete_param
Description
Delete SSM parameter. Primarily used when an SSM parameter is created by a hook rather than CloudFormation.
9.2. CloudFormation & Troposphere 99
runway Documentation, Release 1.18.3
Hook Path
runway.hooks.cleanup_ssm.delete_param
Args
parameter_name (str) Name of an SSM parameter.
command.run_command
Description
Run a custom command as a hook.
Hook Path
runway.cfngin.hooks.command.run_command
Args
command (Union[str, List[str]]) Command(s) to run.
capture (bool) If enabled, capture the command’s stdout and stderr, and return them in the hook result. (default:
False)
interactive (bool) If enabled, allow the command to interact with stdin. Otherwise, stdin will be set to the null device.
(default: False)
ignore_status (bool) Don’t fail the hook if the command returns a non-zero status. (default: False)
quiet (bool) Redirect the command’s stdout and stderr to the null device, silencing all output. Should not be enabled
if capture is also enabled. (default: False)
stdin (Optional[str]) String to send to the stdin of the command. Implicitly disables interactive.
env (Optional[Dict[str, str]]) Dictionary of environment variable overrides for the command context. Will be merged
with the current environment.
**kwargs (Any) Any other arguments will be forwarded to the subprocess.Popen function. Interesting ones
include: cwd and shell.
Example
pre_build:
command_copy_environment:
path: runway.cfngin.hooks.command.run_command
required: true
enabled: true
data_key: copy_env
args:
command: ['cp', 'environment.template', 'environment']
command_git_rev_parse:
path: runway.cfngin.hooks.command.run_command
(continues on next page)
100 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
(continued from previous page)
required: true
enabled: true
data_key: get_git_commit
args:
command: ['git', 'rev-parse', 'HEAD']
cwd: ./my-git-repo
capture: true
command_npm_install:
path: runway.cfngin.hooks.command.run_command
args:
command: '`cd $PROJECT_DIR/project; npm install`'
env:
PROJECT_DIR: ./my-project
shell: true
docker
docker.image.build
Description
Docker image build hook.
Replicates the functionality of the docker image build CLI command.
Hook Path
runway.cfngin.hooks.docker.image.build
Args
docker (Optional[Dict[str, Any]]) Options for docker image build.
buildargs (Optional[Dict[str, str]]) Dict of build-time variables.
custom_context (bool) Optional if providing a path to a zip file. (default: False)
extra_hosts (Optional[Dict[str, str]]) Extra hosts to add to /etc/hosts in the building containers. Defined as a
mapping of hostmane to IP address.
forcerm (bool) Always remove intermediate containers, even after unsuccessful builds. (default: False)
isolation (Optional[str]) Isolation technology used during build.
network_mode (Optional[str]) Network mode for the run commands during build.
nocache (bool) Don’t use cache when set to True. (default: False)
platform (Optional[str]) Set platform if server is multi-platform capable. Uses format os[/arch[/
variant]].
pull (bool) Download any updates to the FROM image in the Dockerfile. (default: False)
rm (bool) Remove intermediate containers. (default: True)
squash (bool) Squash the resulting image layers into a single layer. (default: False)
9.2. CloudFormation & Troposphere 101
runway Documentation, Release 1.18.3
tag (Optional[str]) Optional name and tag to apply to the base image when it is built.
target (Optional[str]) Name of the build-stage to build in a multi-stage Dockerfile.
timeout (Optional[int]) HTTP timeout.
use_config_proxy (bool) If True and if the docker client configuration file (~/.docker/config.json
by default) contains a proxy configuration, the corresponding environment variables will be set in the
container being built. (default: False)
dockerfile (Optional[str]) Path within the build context to the Dockerfile. (default: ./Dockerfile)
ecr_repo (Optional[Dict[str, Optional[str]]]) Information describing an ECR repository. This is used to construct
the repository URL. If providing a value for this field, do not provide a value for repo.
If using a private registry, only repo_name is required. If using a public registry, repo_name and
registry_alias.
account_id (Optional[str]) AWS account ID that owns the registry being logged into. If not provided, it will
be acquired automatically if needed.
aws_region (Optional[str]) AWS region where the registry is located. If not provided, it will be acquired
automatically if needed.
registry_alias (Optional[str]) If it is a public repository, provide the alias.
repo_name (str) The name of the repository
path (Optional[str]) Path to the directory continaing the Dockerfile. (defaults to the current working directory)
repo (Optional[str]) URI of a non Docker Hub repository where the image will be stored. If providing one of the
other repo values, leave this value empty.
tags (Optional[List[str]]) List of tags to apply to the image. (default: ["latest"])
Returns
The following are values accessible with the hook_data Lookup under the data_key of docker (do not specify a
data_key for the hook, this is handled automatically).
image (DockerImage) A DockerImage object for the image that was just built.
Important: Each execution of this hook overwrites any previous values stored in this attribute. It is advices to
consume the resulting image object after it has been built, if it will be consumed by a later hook/stack.
Example
pre_build:
- path: runway.cfngin.hooks.docker.login
args:
ecr: true
password: ${ecr login-password}
- path: runway.cfngin.hooks.docker.image.build
args:
ecr_repo:
repo_name: ${cfn ${namespace}-test-ecr.Repository}
tags:
- latest
(continues on next page)
102 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
(continued from previous page)
- python3.9
- path: runway.cfngin.hooks.docker.image.push
args:
image: ${hook_data docker.image}
docker.image.push
Description
Docker image push hook.
Replicates the functionality of the docker image push CLI command.
Hook Path
runway.cfngin.hooks.docker.image.push
Args
ecr_repo (Optional[Dict[str, Optional[str]]]) Information describing an ECR repository. This is used to construct
the repository URL. If providing a value for this field, do not provide a value for image or repo.
If using a private registry, only repo_name is required. If using a public registry, repo_name and
registry_alias.
account_id (Optional[str]) AWS account ID that owns the registry being logged into. If not provided, it will
be acquired automatically if needed.
aws_region (Optional[str]) AWS region where the registry is located. If not provided, it will be acquired
automatically if needed.
registry_alias (Optional[str]) If it is a public repository, provide the alias.
repo_name (str) The name of the repository
image (Optional[DockerImage]) A DockerImage object. This can be retrieved from hook_data for a preceding
build using the hook_data Lookup.
If providing a value for this field, do not provide a value for ecr_repo or repo.
repo (Optional[str]) URI of a non Docker Hub repository where the image will be stored. If providing one of the
other repo values or image, leave this value empty.
tags (Optional[List[str]]) List of tags push. (default: ["latest"])
9.2. CloudFormation & Troposphere 103
runway Documentation, Release 1.18.3
Example
pre_build:
- path: runway.cfngin.hooks.docker.login
args:
ecr: true
password: ${ecr login-password}
- path: runway.cfngin.hooks.docker.image.build
args:
ecr_repo:
repo_name: ${cfn ${namespace}-test-ecr.Repository}
tags:
- latest
- python3.9
- path: runway.cfngin.hooks.docker.image.push
args:
image: ${hook_data docker.image}
stacks:
ecr-lambda-function:
class_path: blueprints.EcrFunction
variables:
ImageUri: ${hook_data docker.image.uri.latest}
docker.image.remove
Description
Docker image build hook.
Replicates the functionality of the docker image remove CLI command.
Hook Path
runway.cfngin.hooks.docker.image.remove
Args
ecr_repo (Optional[Dict[str, Optional[str]]]) Information describing an ECR repository. This is used to construct
the repository URL. If providing a value for this field, do not provide a value for image or repo.
If using a private registry, only repo_name is required. If using a public registry, repo_name and
registry_alias.
account_id (Optional[str]) AWS account ID that owns the registry being logged into. If not provided, it will
be acquired automatically if needed.
aws_region (Optional[str]) AWS region where the registry is located. If not provided, it will be acquired
automatically if needed.
registry_alias (Optional[str]) If it is a public repository, provide the alias.
repo_name (str) The name of the repository
force (bool) Force removal of the image. (default: False)
104 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
image (Optional[DockerImage]) A DockerImage object. If providing an Image object from `hook_data, it
will be removed from from there as well.
If providing a value for this field, do not provide a value for ecr_repo or repo.
noprune (bool) Do not delete untagged parents. (default: False)
repo (Optional[str]) URI of a non Docker Hub repository where the image is stored. If providing one of the other
repo values or image, leave this value empty.
tags (Optional[List[str]]) List of tags delete. (default: ["latest"])
Example
pre_build:
- path: runway.cfngin.hooks.docker.login
args:
ecr: true
password: ${ecr login-password}
- path: runway.cfngin.hooks.docker.image.build
args:
ecr_repo:
repo_name: ${cfn ${namespace}-test-ecr.Repository}
tags:
- latest
- python3.9
- path: runway.cfngin.hooks.docker.image.push
args:
image: ${hook_data docker.image}
tags:
- latest
- python3.9
stacks:
...
post_build:
- path: runway.cfngin.hooks.docker.image.remove
args:
image: ${hook_data docker.image}
tags:
- latest
- python3.9
docker.login
Description
Docker login hook.
Replicates the functionality of the docker login CLI command.
This hook does not modify the Docker config file. The credentials/authenticated session is stored in memory and is
deleted after processing a given CFNgin config file.
This hook can be executed as a pre or post hook. The authenticated session carries over from pre to post and to each
subsequent built-in Docker hook.
9.2. CloudFormation & Troposphere 105
runway Documentation, Release 1.18.3
Hook Path
runway.cfngin.hooks.docker.login
Args
dockercfg_path (Optional[str]) Use a custom path for the Docker config file ($HOME/.docker/config.json
if present, otherwise $HOME/.dockercfg).
ecr (Optional[Union[bool, Dict[str, Optional[str]]]]) Information describing an ECR registry. This is used to con-
struct the registry URL. If providing a value for this field, do not provide a value for registry.
If using a private registry, the value can simply be true. If using a public registry, more information is required.
account_id (Optional[str]) AWS account ID that owns the registry being logged into. If not provided, it will
be acquired automatically if needed.
alias (Optional[str]) If it is a public repository, provide the alias.
aws_region (Optional[str]) AWS region where the registry is located. If not provided, it will be acquired
automatically if needed.
email (Optional[str]) The email for the registry account.
password (str) The plaintext password.
registry (Optional[str]) URL to the registry (e.g. https://index.docker.io/v1/).
If providing a value for this field, do not provide a value for ecr.
username (str) The registry username. Defaults to AWS if supplying ecr.
Example
pre_build:
- path: runway.cfngin.hooks.docker.login
args:
ecr: true
password: ${ecr login-password}
ecr.purge_repository
Description
Purge all images from an ECR repository.
106 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Hook Path
runway.cfngin.hooks.ecr.purge_repository
Args
repository_name (str) The name of the ECR repository to purge.
Example
pre_destroy:
- path: runway.cfngin.hooks.ecr.purge_repository
args:
repository_name: example-repo
ecs.create_clusters
Description
Create ECS clusters.
Hook Path
runway.cfngin.hooks.ecs.create_clusters
Args
clusters (List[str]) Names of clusters to create.
iam.create_ecs_service_role
Description
Create ecsServiceRole, which has to be named exactly that currently.
http://docs.aws.amazon.com/AmazonECS/latest/developerguide/IAM_policies.html#service_IAM_role
Hook Path
runway.cfngin.hooks.iam.create_ecs_service_role
9.2. CloudFormation & Troposphere 107
runway Documentation, Release 1.18.3
Args
role_name (str) Name of the role to create. (default: ecsServiceRole)
iam.ensure_server_cert_exists
Description
Ensure server cert exists.
Hook Path
runway.cfngin.hooks.iam.ensure_server_cert_exists
Args
cert_name (str) Name of the certificate that should exist.
prompt (bool) Whether to prompt to upload a certificate if one does not exist. (default: True)
keypair.ensure_keypair_exists
Description
Ensure a specific keypair exists within AWS. If the key doesn’t exist, upload it.
Hook Path
runway.cfngin.hooks.keypair.ensure_keypair_exists
Args
keypair (str) Name of the key pair to create
ssm_parameter_name (Optional[str]) Path to an SSM store parameter to receive the generated private key, instead
of importing it or storing it locally.
ssm_key_id (Optional[str]) ID of a KMS key to encrypt the SSM parameter with. If omitted, the default key will be
used.
public_key_path (Optional[str]) Path to a public key file to be imported instead of generating a new key. Incompat-
ible with the SSM options, as the private key will not be available for storing.
108 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
route53.create_domain
Description
Create a domain within route53.
Hook Path
runway.cfngin.hooks.route53.create_domain
Args
domain (str) Domain name for the Route 53 hosted zone to be created.
upload_staticsite.get_distribution_data
Description
Retrieve information about the CloudFront distribution. Used by the Static Site module type.
Hook Path
runway.hooks.staticsite.upload_staticsite.get_distribution_data
Args
See Static Site module documentation for details.
upload_staticsite.sync
Description
Sync static website to S3 bucket. Used by the Static Site module type.
Hook Path
runway.hooks.staticsite.upload_staticsite.sync
9.2. CloudFormation & Troposphere 109
runway Documentation, Release 1.18.3
Args
See Static Site module documentation for details.
Writing A Custom Hook
A custom hook must be in an executable, importable python package or standalone file. The hook must be importable
using your current sys.path. This takes into account the sys_path defined in the config file as well as any paths
of package_sources.
The hook must accept a minimum of two arguments, context and provider. Aside from the required arguments,
it can have any number of additional arguments or use
**
kwargs to accept anything passed to it. The values for
these additional arguments come from the args key of the hook definition.
The hook must return True or a truthy object if it was successful. It must return False or a falsy object if it failed.
This signifies to CFNgin whether or not to halt execution if the hook is required. If dict is returned, it can
be accessed by subsequent hooks, lookups, or Blueprints from the context object. It will be stored as context.
hook_data[data_key] where data_key is the value set in the hook definition. If data_key is not provided
or the type of the returned data is not dict, it will not be added to the context object.
If using boto3 in a hook, use context.get_session() instead of creating a new session to ensure the correct
credentials are used.
"""context.get_session() example."""
from runway.cfngin.context import Context
from runway.cfngin.providers.aws.default import Provider
def do_something(context: Context, provider: Provider,
**
kwargs: str) -> None:
"""Do something."""
session = context.get_session()
s3_client = session.client('s3')
Example Hook Function
local_path/hooks/my_hook.py
"""My hook."""
from typing import Dict
from runway.cfngin.context import Context
from runway.cfngin.providers.aws.default import Provider
def do_something(context: Context,
provider: Provider,
is_failure: bool = True,
**
kwargs: str
) -> Dict[str, str]:
"""Do something."""
if is_failure:
return None
return {'result': f"You are not a failure {kwargs.get('name', 'Kevin')}."}
110 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
local_path/cfngin.yaml
namespace: example
sys_path: ./
pre_build:
my_hook_do_something:
path: hooks.my_hook.do_something
args:
is_failure: False
Example Hook Class
local_path/hooks/my_hook.py
"""My hook."""
import logging
from typing import Dict
from runway.cfngin.hooks.base import Hook
LOGGER = logging.getLogger(__name__)
class MyClass(Hook):
"""My class does a thing.
Keyword Args:
is_failure (bool): Force the hook to fail if true.
name (str): Name used in the response.
Returns:
Dict[str, str]: Response message is stored in ``result``.
Example:
.. code-block:: yaml
pre_build:
my_hook_do_something:
path: hooks.my_hook.MyClass
args:
is_failure: False
name: Karen
"""
def post_deploy(self) -> Dict[str, str]:
"""Run during the
**
post_deploy
**
stage."""
if self.args.is_failure:
return None
return {'result': f"You are not a failure {self.args.name}."}
def post_destroy(self) -> None:
"""Run during the
**
post_destroy
**
stage."""
LOGGER.error('post_destroy is not supported by this hook')
(continues on next page)
9.2. CloudFormation & Troposphere 111
runway Documentation, Release 1.18.3
(continued from previous page)
def pre_deploy(self) -> None:
"""Run during the
**
pre_deploy
**
stage."""
LOGGER.error('pre_deploy is not supported by this hook')
def pre_destroy(self) -> None:
"""Run during the
**
pre_destroy
**
stage."""
LOGGER.error('pre_destroy is not supported by this hook')
local_path/cfngin.yaml
namespace: example
sys_path: ./
pre_build:
my_hook_do_something:
path: hooks.my_hook.MyClass
args:
is_failure: False
name: Karen
Lookups
Note: Runway lookups and CFNgin lookups are not interchangeable. While they do share a similar base class and
syntax, they exist in two different registries. Runway config files can’t use CFNgin lookups just as the CFNgin config
cannot use Runway lookups.
Runway’s CFNgin provides the ability to dynamically replace values in the config via a concept called lookups. A
lookup is meant to take a value and convert it by calling out to another service or system.
A lookup is denoted in the config with the ${<lookup type> <lookup input>} syntax. If <lookup
type> isn’t provided, CFNgin will fall back to use the output lookup .
Lookups are only resolved within Variables. They can be nested in any part of a YAML data structure and within
another lookup itself.
Note: If a lookup has a non-string return value, it can be the only lookup within a value.
ie. if custom returns a list, this would raise an exception:
Variable: ${custom something}, ${output otherStack::Output}
This is valid:
Variable: ${custom something}
For example, given the following:
stacks:
- name: sg
class_path: some.stack.blueprint.Blueprint
(continues on next page)
112 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
(continued from previous page)
variables:
Roles:
- ${output otherStack::IAMRole}
Values:
Env:
Custom: ${custom ${output otherStack::Output}}
DBUrl: postgres://${output dbStack::User}@${output dbStack::HostName}
The Blueprint would have access to the following resolved variables dictionary:
# variables
{
"Roles": ["other-stack-iam-role"],
"Values": {
"Env": {
"Custom": "custom-output",
"DBUrl": "postgres://user@hostname",
},
},
}
Runway’s CFNgin includes the following lookup types:
• output lookup
• ami lookup
• ecr lookup
• cfn lookup
• custom lookup
• default lookup
• dynamodb lookup
• envvar lookup
• file lookup
• hook_data lookup
• kms lookup
• rxref lookup
• ssm lookup
• xref lookup
9.2. CloudFormation & Troposphere 113
runway Documentation, Release 1.18.3
cfn Lookup
Important: The Stack must exist in CloudFormation before the config using this Lookup begins processing
to successfully get a value. This means that it must have been deployed using another Runway module, de-
ployed from a config that is run before the one using it, deployed manually, or deployed in the same config using
required/required_by to specify a dependency between the Stacks.
Retrieve a value from CloudFormation Stack Outputs.
The query syntax for this lookup is <stack-name>.<output-name>. When specifying the output name, be sure
to use the Logical ID of the output; not the Export.Name.
If the Lookup is unable to find a CloudFormation Stack Output matching the provided query, the default value is
returned or an exception is raised to show why the value could be be resolved (e.g. Stack does not exist or output does
not exist on the Stack).
See also:
https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/outputs-section-structure.html
Arguments
This Lookup supports all Common Lookup Arguments.
Example
Listing 1: Runway config
deployments:
- modules:
path: sampleapp.tf
options:
terraform_backend_config:
bucket: ${cfn common-tf-state.TerraformStateBucketName::region=us-east-1}
dynamodb_table: ${cfn common-tf-state.TerraformStateTableName::region=us-
˓→east-1}
region: us-east-1
114 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Listing 2: CFNgin config
stacks:
my-stack:
variables:
SomeParameter: ${cfn AnotherStack.OutputName}
ecr Lookup
Retrieve a value from AWS Elastic Container Registry (ECR).
This Lookup only supports very specific queries.
Supported Queries
login-password
Get a password to login to ECR registry.
The returned value can be passed to the login command of the container client of your preference, such as the Docker
CFNgin hook. After you have authenticated to an Amazon ECR registry with this Lookup, you can use the client to
push and pull images from that registry as long as your IAM principal has access to do so until the token expires. The
authorization token is valid for 12 hours.
Arguments
This Lookup does not support any arguments.
Example
Listing 3: runway.yml
deployments:
- modules:
- path: example.cfn
parameters:
ecr_password: ${ecr login-password}
...
Listing 4: cfngin.yml
pre_build:
- path: runway.cfngin.hooks.docker.login
args:
password: ${ecr login-password}
...
9.2. CloudFormation & Troposphere 115
runway Documentation, Release 1.18.3
Output Lookup
The output lookup takes a value of the format: <stack name>::<output name> and retrieves the output
from the given stack name within the current namespace.
CFNgin treats output lookups differently than other lookups by auto adding the referenced stack in the lookup as a
requirement to the stack whose variable the output value is being passed to.
You can specify an output lookup with the following syntax:
ConfVariable: ${output someStack::SomeOutput}
default Lookup
The default lookup type will check if a value exists for the variable in the environment file, then fall back to a
default defined in the CFNgin config if the environment file doesn’t contain the variable. This allows defaults to be set
at the config file level, while granting the user the ability to override that value per environment.
Format of value:
<env_var>::<default value>
Example
Groups: ${default app_security_groups::sg-12345,sg-67890}
If app_security_groups is defined in the environment file, its defined value will be returned. Otherwise,
sg-12345,sg-67890 will be the returned value.
Note: The default lookup only supports checking if a variable is defined in an environment file. It does not support
other embedded lookups to see if they exist. Only checking variables in the environment file are supported. If you
attempt to have the default lookup perform any other lookup that fails, CFNgin will throw an exception for that lookup
and will stop your build before it gets a chance to fall back to the default in your config.
KMS Lookup
The kms lookup type decrypts its input value.
As an example, if you have a database and it has a parameter called DBPassword that you don’t want to store in
clear text in your config (maybe because you want to check it into your version control system to share with the team),
you could instead encrypt the value using kms.
For example:
# We use the aws cli to get the encrypted value for the string
# "PASSWORD" using the master key called 'myKey' in us-east-1
$ aws --region us-east-1 kms encrypt --key-id alias/myKey \
--plaintext "PASSWORD" --output text --query CiphertextBlob
CiD6bC8t2Y<...encrypted blob...>
(continues on next page)
116 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
(continued from previous page)
# With CFNgin we would reference the encrypted value like:
DBPassword: ${kms us-east-1@CiD6bC8t2Y<...encrypted blob...>}
# The above would resolve to
DBPassword: PASSWORD
This requires that the person using CFNgin has access to the master key used to encrypt the value.
It is also possible to store the encrypted blob in a file (useful if the value is large) using the file:// prefix, ie:
DockerConfig: ${kms file://dockercfg}
Note: Lookups resolve the path specified with file:// relative to the location of the config file, not where the CFNgin
command is run.
XRef Lookup
Deprecated since version 1.11.0: Replaced by cfn lookup
The xref lookup type is very similar to the output lookup type, the difference being that xref resolves output
values from stacks that aren’t contained within the current CFNgin namespace, but are existing stacks containing
outputs within the same region on the AWS account you are deploying into. xref allows you to lookup these outputs
from the stacks already on your account by specifying the stacks fully qualified name in the CloudFormation console.
Where the output type will take a stack name and use the current context to expand the fully qualified stack name
based on the namespace, xref skips this expansion because it assumes you’ve provided it with the fully qualified
stack name already. This allows you to reference output values from any CloudFormation stack in the same region.
Also, unlike the output lookup type, xref doesn’t impact stack requirements.
Example
ConfVariable: ${xref fully-qualified-stack::SomeOutput}
RXRef Lookup
The rxref lookup type is very similar to the xref lookup type, the difference being that rxref will lookup output
values from stacks that are relative to the current namespace but external to the stack, but will not resolve them. rxref
assumes the stack containing the output already exists.
Where the xref type assumes you provided a fully qualified stack name, rxref, like output expands and retrieves
the output from the given stack name within the current namespace, even if not defined in the CFNgin config you
provided it.
Because there is no requirement to keep all stacks defined within the same CFNgin YAML config, you might need
the ability to read outputs from other stacks deployed by CFNgin into your same account under the same namespace.
rxref gives you that ability. This is useful if you want to break up very large configs into smaller groupings.
Also, unlike the output lookup type, rxref doesn’t impact stack requirements.
9.2. CloudFormation & Troposphere 117
runway Documentation, Release 1.18.3
Example
# in example-us-east-1.env
namespace: MyNamespace
# in cfngin.yaml
ConfVariable: ${rxref my-stack::SomeOutput}
# the above would effectively resolve to
ConfVariable: ${xref MyNamespace-my-stack::SomeOutput}
Although possible, it is not recommended to use rxref for stacks defined within the same CFNgin YAML config.
File Lookup
The file lookup type allows the loading of arbitrary data from files on disk. The lookup additionally supports
using a codec to manipulate or wrap the file contents prior to injecting it. The parameterized-b64 codec is particu-
larly useful to allow the interpolation of CloudFormation parameters in a UserData attribute of an instance or launch
configuration.
Basic examples:
# We've written a file to /some/path:
$ echo "hello there" > /some/path
# In CFNgin we would reference the contents of this file with the following
conf_key: ${file plain:file://some/path}
# The above would resolve to
conf_key: hello there
# Or, if we used wanted a base64 encoded copy of the file data
conf_key: ${file base64:file://some/path}
# The above would resolve to
conf_key: aGVsbG8gdGhlcmUK
Supported Codecs:
• plain - Load the contents of the file untouched. This is the only codec that should be used with raw Cloudfor-
mation templates (the other codecs are intended for blueprints).
• base64 - Encode the plain text file at the given path with base64 prior to returning it
• parameterized - The same as plain, but additionally supports referencing CloudFormation parameters to create
userdata that’s supplemented with information from the template, as is commonly needed in EC2 UserData. For
example, given a template parameter of BucketName, the file could contain the following text:
#!/bin/sh
aws s3 sync s3://{{BucketName}}/somepath /somepath
and then you could use something like this in the YAML config file:
UserData: ${file parameterized:/path/to/file}
resulting in the UserData parameter being defined as:
118 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
{
"Fn::Join" : [
"",
[
"#!/bin/sh\naws s3 sync s3://",
{
"Ref" : "BucketName"
},
"/somepath /somepath"
]
]
}
• parameterized-b64 - The same as parameterized, with the results additionally wrapped in {
"Fn::Base64": ... } , which is what you actually need for EC2 UserData
When using parameterized-b64 for UserData, you should use a local parameter defined as such.
from troposphere import AWSHelperFn
"UserData": {
"type": AWSHelperFn,
"description": "Instance user data",
"default": Ref("AWS::NoValue")
}
and then assign UserData in a LaunchConfiguration or Instance to self.
get_variables()["UserData"]. Note that we use AWSHelperFn as the type because the
parameterized-b64 codec returns either a Base64 or a GenericHelperFn troposphere object.
• json - Decode the file as JSON and return the resulting object
• json-parameterized - Same as json, but applying templating rules from parameterized to every object
value. Note that object keys are not modified. Example (an external PolicyDocument):
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"some:Action"
],
"Resource": "{{MyResource}}"
}
]
}
• yaml - Decode the file as YAML and return the resulting object. All strings are returned as unicode even in
Python 2.
• yaml-parameterized - Same as json-parameterized, but using YAML.
Version: 2012-10-17
Statement:
- Effect: Allow
Action:
- "some:Action"
Resource: "{{MyResource}}"
9.2. CloudFormation & Troposphere 119
runway Documentation, Release 1.18.3
ssm
Retrieve a value from SSM Parameter Store.
If the Lookup is unable to find an SSM Parameter matching the provided query, the default value is returned or
ParameterNotFound is raised if a default value is not provided.
Parameters of type SecureString are automatically decrypted.
Parameters of type StringList are returned as a list.
Arguments
This Lookup supports all Common Lookup Arguments.
Example
deployment:
- modules:
- path: sampleapp.cfn
parameters:
secret_value: ${ssm /example/secret}
conf_file: ${ssm /example/config/json::load=json, get=value}
toggle: ${ssm toggle::load=yaml, get=val, transform=bool}
env_vars:
SOME_VARIABLE: ${ssm /example/param::region=us-east-1}
DEFAULT_VARIABLE: ${ssm /example/default::default=default}
SSM Parameter Store Lookup
Deprecated since version 1.5.0: Replaced by ssm
The ssmstore lookup type retrieves a value from the Simple Systems Manager Parameter Store.
As an example, if you have a database and it has a parameter called DBUser that you don’t want to store in clear text
in your config, you could instead store it as a SSM parameter named MyDBUser.
For example:
# We use the aws cli to store the database username
$ aws ssm put-parameter --name "MyDBUser" --type "String" \
--value "root"
# In CFNgin we would reference the value like:
DBUser: ${ssmstore us-east-1@MyDBUser}
# Which would resolve to:
DBUser: root
Encrypted values (“SecureStrings”) can also be used, which will be automatically decrypted (assuming the CFNgin
user has access to the associated KMS key). Care should be taken when using this with encrypted values (i.e. a safe
policy is to only use it with no_echo CFNString values)
The region can be omitted (e.g. DBUser: ${ssmstore MyDBUser}), in which case us-east-1 will be
assumed.
120 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
DynamoDb Lookup
The dynamodb lookup type retrieves a value from a DynamoDb table.
As an example, if you have a Dynamo Table named TestTable and it has an Item with a Primary Partition key
called TestKey and a value named BucketName , you can look it up by using CFNgin. The lookup key in this case
is TestVal
Example
# We can reference that dynamo value
BucketName: ${dynamodb us-east-1:TestTable@TestKey:TestVal.BucketName}
# Which would resolve to:
BucketName: test-bucket
You can lookup other data types by putting the data type in the lookup. Valid values are S (String), N (Number), M
(Map), L (List).
Example
ServerCount: ${dynamodb us-east-1:TestTable@TestKey:TestVal.ServerCount[N]}
This would return an int value, rather than a string
You can lookup values inside of a map.
Example
ServerCount: ${dynamodb us-east-1:TestTable@TestKey:TestVal.ServerInfo[M].
ServerCount[N]}
Shell Environment Lookup
The envvar lookup type retrieves a value from a variable in the shell’s environment.
Example:
# Set an environment variable in the current shell.
$ export DATABASE_USER=root
# In the CFNgin config we could reference the value:
DBUser: ${envvar DATABASE_USER}
# Which would resolve to:
DBUser: root
You can also get the variable name from a file, by using the file:// prefix in the lookup, like so:
DBUser: ${envvar file://dbuser_file.txt}
9.2. CloudFormation & Troposphere 121
runway Documentation, Release 1.18.3
EC2 AMI Lookup
The ami lookup is meant to search for the most recent AMI created that matches the given filters.
Valid arguments:
region OPTIONAL ONCE:
e.g. us-east-1@
owners (comma delimited) REQUIRED ONCE:
aws_account_id | amazon | self
name_regex (a regex) REQUIRED ONCE:
e.g. my-ubuntu-server-[0-9]+
executable_users (comma delimited) OPTIONAL ONCE:
aws_account_id | amazon | self
Any other arguments specified are sent as filters to the aws api For example, “architecture:x86_64” will add a filter.
Example:
# Grabs the most recently created AMI that is owned by either this account,
# amazon, or the account id 888888888888 that has a name that matches
# the regex "server[0-9]+" and has "i386" as its architecture.
# Note: The region is optional, and defaults to the current CFNgin region
ImageId: ${ami [<region>@]owners:self,888888888888,amazon name_regex:server[0-9]+
˓→architecture:i386}
Hook Data Lookup
When using hooks, you can have the hook store results in the hook_data dictionary on the context by setting
data_key in the hook config.
This lookup lets you look up values in that dictionary. A good example of this is when you use the aws_lambda hook
to upload AWS Lambda code, then need to pass that code object as the Code variable in the aws_lambda blueprint
dictionary.
122 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Arguments
This Lookup supports all Common Lookup Arguments but, the following have limited or no effect:
• region
Example
# If you set the ``data_key`` config on the aws_lambda hook to be "myfunction"
# and you name the function package "TheCode" you can get the troposphere
# awslambda.Code object with:
Code: ${hook_data myfunction.TheCode}
# If you need to pass the code location as individual strings for use in a
# CloudFormation template instead of a Blueprint, you can do so like this:
Bucket: ${hook_data myfunction.TheCode::load=troposphere, get=S3Bucket}
Key: ${hook_data myfunction.TheCode::load=troposphere, get=S3Key}
Changed in version 1.5.0: The <hook_name>::<key> syntax was deprecated with support being added for
the``key.nested_key`` syntax for access data within a dictionary.
Custom Lookup
A custom lookup may be registered within the config. For more information see Configuring Lookups.
Writing A Custom Lookup
A custom lookup must be in an executable, importable python package or standalone file. The lookup must be im-
portable using your current sys.path. This takes into account the sys_path defined in the config file as well as any
paths of package_sources.
The lookup must be a class, preferable with a base class of runway.lookups.handlers.base.
LookupHandler with a @classmethod of handle that accepts four arguments - value, context, provider,
**
kwargs. There must be only one lookup per file. The file containing the lookup class must have a TYPE_NAME
global variable with a value of the name that will be used to register the lookup.
The lookup must return a string if being used for a CloudFormation parameter.
If using boto3 in a lookup, use context.get_session() instead of creating a new session to ensure the correct
credentials are used.
"""Example lookup."""
from runway.cfngin.context import Context
from runway.cfngin.providers.base import BaseProvider
from runway.cfngin.util import read_value_from_path
from runway.lookups.handlers.base import LookupHandler
TYPE_NAME = 'mylookup'
class MylookupLookup(LookupHandler):
"""My lookup."""
(continues on next page)
9.2. CloudFormation & Troposphere 123
runway Documentation, Release 1.18.3
(continued from previous page)
@classmethod
def handle(cls,
value: str,
context: Context,
provider: BaseProvider,
**
kwargs: Any
) -> str:
"""Do something."""
query, args = cls.parse(read_value_from_path(value))
# example of using get_session for a boto3 session
session = context.get_session()
s3_client = session.client('s3')
return 'something'
Templates
CloudFormation templates can be provided via Blueprints or JSON/YAML. JSON/YAML templates are specified for
stacks via the template_path config option (see Stacks).
Jinja2 Templating
Templates with a .j2 extension will be parsed using Jinja2. The CFNgin context and mappings objects and
stack variables objects are available for use in the template:
Description: TestTemplate
Resources:
Bucket:
Type: AWS::S3::Bucket
Properties:
BucketName: {{ context.environment.foo }}-{{ variables.myparamname }}
9.2.4 Migrating from Stacker
Important: Most current uses of Runway with Stacker will continue to work. But, for imports from Stacker, Runway
will automatically redirect them to CFNgin. Because of this, you may experience errors depending on how you are
consuming the Stacker components. This “shim” will remain in place until the release of Runway 2.0.0, no sooner
then 2020-12.
124 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Blueprints
All components available in Stacker 1.7.0 are available in Runway’s CFNgin at the same path within runway.
cfngin.
Example
# what use to be this
from stacker.blueprints.base import Blueprint
from stacker.blueprints.variables.types import CFNString
# now becomes this
from runway.cfngin.blueprints.base import Blueprint
from runway.cfngin.blueprints.variables.types import CFNString
Config Files
There are some config top-level keys that have changed when used Runway’s CFNgin. Below is a table of the Stacker
key and what they have been changed to for Runway’s CFNgin
Important: The Stacker keys can still be used with Runway’s CFNgin for the time being. This will remain in place
until the release of Runway 2.0.0, no sooner then 2020-12.
Stacker Runway’s CFNgin
stacker_bucket cfngin_bucket
stacker_bucket_region cfngin_bucket_region
stacker_cache_dir cfngin_cache_dir
Build-in Hooks
All hooks available in Stacker 1.7.0 are available in Runway’s CFNgin at the same path within runway.cfngin.
Example Definition
pre_build:
what_use_to_be_this:
path: stacker.hooks.commands.run_command
args:
command: echo "Hello $USER!"
now_becomes_this:
path: runway.cfngin.hooks.commands.run_command
args:
command: echo "Hello $USER!"
See also:
CFNgin API Docs
9.2. CloudFormation & Troposphere 125
runway Documentation, Release 1.18.3
Custom Lookups
See the Custom Lookups section of the docs for detailed instructions on how lookups should be written.
Important: Stacker lookups (function and class styles) are supported for the time being. It is recommended to update
them to the Runway’s CFNgin format outlined in Custom Lookups. Support for Stacker style lookups will remain in
place until the release of Runway 2.0.0, no sooner then 2020-12.
9.3 Kubernetes
Kubernetes manifests can be deployed via Runway offering an ideal way to handle core infrastructure-layer (e.g.
shared ConfigMaps & Service Accounts) configuration of clusters by using Kustomize overlays.
• Configuration
• Directory Structure
• Examples
• Advanced Features
9.3.1 Configuration
Configuration options and parameters for Kubernetes modules.
Options
kubectl_version (Optional[str]) Specify a version of Kubectl for Runway and download and use. See Version Man-
agement for more details.
Example
options:
kubectl_version: 1.14.5
overlay_path (Optional[str]) Specify the directory containing the kustomize overlay to use.
Example
options:
overlay_path: overlays/${env DEPLOY_ENVIRONMENT}-blue
126 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Parameters
Kubernetes does not support the use of parameters at this time.
9.3.2 Directory Structure
Example directory structures for a Kubernetes module.
.
.gitignore
aws-auth-cm.k8s
base
kustomization.yaml
overlays
template
kustomization.yaml
runway.yml
service-hello-world.k8s
README.md
base
configMap.yaml
deployment.yaml
kustomization.yaml
service.yaml
overlays
prod
deployment.yaml
kustomization.yaml
template
kustomization.yaml
map.yaml
9.3.3 Examples
Example uses of the Kubernetes module
9.3. Kubernetes 127
runway Documentation, Release 1.18.3
CloudFormation EKS
To view an example using an EKS cluster deployed with CloudFormation, run runway gen-sample
k8s-cfn-repo in any directory. This will create a k8s-cfn-infrastructure/ directory in your current
working directory containing a runway.yml file, some modules that can be deployed, and a README.md that
provides instructions on how to work with the example code.
Terraform EKS
To view an example using an EKS cluster deployed with Terraform, run runway gen-sample k8s-tf-repo
in any directory. This will create a k8s-tf-infrastructure/ directory in your current working directory con-
taining a runway.yml file, some modules that can be deployed, and a README.md that provides instructions on
how to work with the example code.
9.3.4 Advanced Features
Advanced features and detailed information for using Kubernetes with Runway.
Setting KUBECONFIG Location
If using a non-default kubeconfig location, you can provide it using Runway’s option for setting environment variables.
This can be set as a relative path or an absolute one.
---
deployments:
- modules:
- path: myk8smodule
env_vars:
KUBECONFIG:
- .kube
- ${env DEPLOY_ENVIRONMENT}
- config
This would set KUBECONFIG to <path_to_runway.yml>/.kube/$DEPLOY_ENVIRONMENT/config
where $DEPLOY_ENVIRONMENT is the current Runway deploy environment.
Version Management
By specifying the version via a .kubectl-version file in your overlay directory, or a module option, Runway
will automatically download & use that version for the module. This is recommended to keep a predictable experience
when deploying your module.
Without a version specified, Runway will fallback to whatever kubectl it finds first in your PATH.
128 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
.kubectl-version
1.14.5
runway.yml
Lookups can be used to provide different versions for each deploy environment.
---
deployments:
- modules:
- path: sampleapp.k8s
options:
kubectl_version: ${var kubectl_version.${env DEPLOY_ENVIRONMENT}}
- module:
- sampleapp-01.k8s
- sampleapp-02.k8s
module_options:
kubectl_version: 1.14.5
9.4 Serverless Framework
The Serverless module type is deployed using the Serverless Framework. Runway uses system installed npm to install
Serverless per-module. This means that Serverless must be included as a dev dependency in the package.json of the
module.
• Configuration
• Directory Structure
• Advanced Features
9.4.1 Configuration
Standard Serverless Framework rules apply but, we have some added prerequisites, recommendations, and caveats.
Prerequisites
• npm installed on the system
• Serverless must be a dev dependency of the module (e.g. npm install --save-dev serverless)
We strongly recommend you commit the package-lock.json that is generated after running npm install.
9.4. Serverless Framework 129
runway Documentation, Release 1.18.3
Options
Options specific to Serverless Framework modules.
args (Optional[List[str]] List of CLI arguments/options to pass to the Serverless Framework CLI. See Specifying
Serverless CLI Arguments/Options for more details.
Example
options:
args:
- '--config'
- sls.yml
extend_serverless_yml (Optional[Dict[str, Any]]) If provided, the value of this option will be recursively merged
into the modules serverless.yml file. See Extending a Serverless Configuration File for more details.
Example
options:
extend_serverless_yml:
custom:
env:
memorySize: 512
promotezip (Optional[Dict[str, str]]) If provided, promote Serverless Framework generated zip files between envi-
ronments from a build AWS account. See Promoting Builds Through Environments for more details.
Example
options:
promotezip:
bucketname: my-build-account-bucket-name
skip_npm_ci (bool) Skip running npm ci in the module directory prior to processing the module (default: false).
See Disabling NPM CI for more details.
Example
options:
skip_npm_ci: true
130 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
serverless.yml
Refer to the Serverless Framework Documentation.
Stages
Runway’s concept of a deploy environment has a 1-to-1 mapping to Serverless’s stage. For example, if the deploy
environment is dev, Serverless will be run with --stage dev.
Each stage requires either its own variables file (even if empty for a particular stage) following a specific File Naming
scheme and/or a configured environment for the module or deployment (see Runway Config File for details).
File Naming
• env/STAGE-REGION.yml
• config-STAGE-REGION.yml
• env/STAGE.yml
• config-STAGE.yml
• env/STAGE-REGION.json
• config-STAGE-REGION.json
• env/STAGE.json
• config-STAGE.json
Runway Config
Top-level
---
deployments:
- modules:
- path: myslsmodule.sls
environments:
dev: true
prod: true
- modules:
- path: myotherslsmodule.sls
environments:
dev: true
prod: true
9.4. Serverless Framework 131
runway Documentation, Release 1.18.3
In Module Directory
---
environments:
dev: true
prod: true
9.4.2 Directory Structure
Example directory structures for a Serverless module.
Python Example
.
Pipfile
Pipfile.lock
__init__.py
_gitignore
config-dev-us-east-1.json
hello_world
__init__.py
package.json
serverless.yml
TypeScript Example
.
.gitignore
env
dev-us-east-1
jest.config.js
package.json
package-lock.json
serverless.yml
src
helloWorld.test.ts
helloWorld.ts
tsconfig.json
tslint.json
webpack.config.js
9.4.3 Advanced Features
Advanced features and detailed information for using Serverless Framework with Runway.
132 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Disabling NPM CI
At the start of each module execution, Runway will execute npm ci to ensure Serverless Framework is installed in
the project (so Runway can execute it via npx sls. This can be disabled (e.g. for use when the node_modules
directory is pre-compiled) via the skip_npm_ci module option.
Example
---
deployments:
- modules:
- path: myslsproject.sls
options:
skip_npm_ci: true
Extending a Serverless Configuration File
Runway has the ability to extend the contents of a serverless.yml file using the value of the
extend_serverless_yml option. The value of this option is recursively merged into a resolved clone of
the module’s Serverless configuration. To create this resolved clone, Runway uses “serverless print” (including args)
to resolve the module’s Serverless configuration file and output the contents to a temporary file. The temporary file is
deleted after each execution of Runway.
This functionality can be especially useful when used alongside remote module paths such as a module from a git
repository to change values on the fly without needing to modify the source for small differences in each environment.
Example
deployments:
- modules:
- path: git::git://github.com/onicagroup/example.git//sampleapp?tag=v1.0.0
options:
extend_serverless_yml:
custom:
env:
memorySize: 512
regions:
- us-east-1
Merge Logic
The two data sources are merged by iterating over their content and combining the lowest level nodes possible.
9.4. Serverless Framework 133
runway Documentation, Release 1.18.3
Example
serverless.yml
functions:
example:
handler: handler.example
runtime: python3.8
memorySize: 512
runway.yml
deployments:
- modules:
- path: sampleapp.sls
options:
extend_serverless_yml:
functions:
example:
memorySize: 1024
resources:
Resources:
ExampleResource:
Type: AWS::CloudFormation::WaitConditionHandle
regions:
- us-east-1
Result
functions:
example:
handler: handler.example
runtime: python3.8
memorySize: 1024
resources:
Resources:
ExampleResource:
Type: AWS::CloudFormation::WaitConditionHandle
Promoting Builds Through Environments
Serverless build .zips can be used between environments by setting the promotezip module option and providing
a bucket name in which to cache the builds.
The first time the Serverless module is deployed using this option, it will build/deploy as normal and cache the artifact
on S3. On subsequent deploys, Runway will used that cached artifact (finding it by comparing the module source
code).
This enables a common build account to deploy new builds in a dev/test environment, and then promote that same zip
through other environments (any of these environments can be in the same or different AWS accounts).
The CloudFormation stack deploying the zip will be re-generated on each deployment (so environment-specific val-
ues/lookups will work as normal).
134 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Example
---
deployments:
- modules:
- path: myslsproject.sls
options:
promotezip:
bucketname: my-build-account-bucket-name
Specifying Serverless CLI Arguments/Options
Runway can pass custom arguments/options to the Serverless CLI by using the args option. These will always be
placed after the default arguments/options.
The value of args must be a list of arguments/options to pass to the CLI. Each element of the argument/option should
be it’s own list item (e.g. --config sls.yml would be ['--config', 'sls.yml']).
Important: Do not provide --region <region> or --stage <stage> here, these will be provided by
Runway. Runway will also provide --no-color if stdout is not a TTY.
Runway Example
---
deployments:
- modules:
- path: sampleapp.sls
options:
args:
- '--config'
- sls.yml
regions:
- us-east-2
environments:
example: true
9.4. Serverless Framework 135
runway Documentation, Release 1.18.3
Command Equivalent
serverless deploy -r us-east-1 --stage example --config sls.yml
9.5 Static Site
This module type performs idempotent deployments of static websites. It combines CloudFormation stacks (for S3
buckets & CloudFront Distribution) with additional logic to build & sync the sites.
A start-to-finish example walkthrough is available in the Conduit quickstart.
Note: The CloudFront Distribution that is created by default can take a significant amount of time to spin up on
initial deploy (5 to 60 minutes is not abnormal). Incorporating CloudFront with a static site is a common best practice,
however, if you are working on a development project it may benefit you to add the staticsite_cf_disable parameter.
• Configuration
• Directory Structure
• Examples
• Advanced Features
9.5.1 Configuration
Configuration options and parameters for static site modules. Example uses of the options and parameters can be
found in the Examples section.
Options
build_output (Optional[str]) Overrides default directory of top-level path setting.
Example
options:
build_output: dist
build_steps (Optional[List[str]]) The steps to run during the build portion of deployment.
Example
options:
build_steps:
- npm ci
- npm run build
extra_files (Optional[List[Dict[str, Union[str, Dict[str, Any]]]]]) Specifies extra files that should be uploaded to S3
after the build.
136 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Use extra_files if you want to have a single build artifact that can be used in many environments. These
files should be excluded from source hashing and the build system. The end result is that you have a build
artifact that can be deployed in any environment and behave exactly the same.
See Extra Files for more details.
Example
options:
extra_files:
- name: config.json # yaml or other text files are supported
content: # this object will be json or yaml serialized
endpoint: ${var api_endpoint.${env DEPLOY_ENVIRONMENT}}
- name: config.any
content_type: text/yaml # Explicit content type
content:
endpoint: ${var api_endpoint.${env DEPLOY_ENVIRONMENT}}
- name: logo.png
content_type: image/png
file: logo-${env DEPLOY_ENVIRONMENT}.png # a reference to an existing file
The example above produces a file named config.json with the contents below and a logo.png file.
{
"endpoint": "<api_endpoint value>"
}
pre_build_steps (Optional[List[Dict[str, str]]]) Commands to be run before generating the hash of files.
Example
options:
pre_build_steps:
- command: npm ci
cwd: ../myothermodule # directory relative to top-level path setting
- command: npm run export
cwd: ../myothermodule
source_hashing (Optional[Dict[str, str]]) Overrides for source hash collection and tracking
Example
options:
source_hashing:
enabled: true # if false, build & upload will occur on every deploy
parameter: /${namespace}/myparam # defaults to <namespace>-<name/path>-hash
directories: # overrides default hash directory of top-level path setting
- path: ./
- path: ../common
# Additional (gitignore-format) exclusions to
# hashing (.giignore files are loaded automatically)
exclusions:
- foo/
*
9.5. Static Site 137
runway Documentation, Release 1.18.3
Parameters
namespace (str) The unique namespace for the deployment.
Example
parameters:
namespace: my-awesome-website-${env DEPLOY_ENVIRONMENT}
staticsite_acmcert_arn (Optional[str]) The certificate arn used for any alias domains supplied. This is a requirement
when supplying any custom domain.
Example
parameters:
staticsite_acmcert_arn: arn:aws:acm:<region>:<account-id>:certificate/<cert>
staticsite_aliases (Optional[str]) Any custom domains that should be added to the CloudFront Distribution. This
should be represented as a comma delimited list of domains.
Requires staticsite_acmcert_arn.
Example
parameters:
staticsite_aliases: example.com,foo.example.com
staticsite_auth_at_edge (Optional[bool]) Auth@Edge make the static site private by placing it behind an authoriza-
tion wall. (default: false) See Auth@Edge for more details.
Example
parameters:
staticsite_auth_at_edge: true
staticsite_cf_disable (Optional[bool]) Wether deployment of the CloudFront Distribution should be disabled. (de-
fault: false)
Useful for a development site as it makes it accessible via an S3 url with a much shorter launch time. This
cannot be set to true when using Auth@Edge.
Example
parameters:
staticsite_cf_disable: false
staticsite_cookie_settings (Optional[Dict[str, str]]) The default cookie settings for retrieved tokens and generated
nonce’s. (default is shown in the example)
Requires staticsite_auth_at_edge.
138 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Example
parameters:
staticsite_cookie_settings:
idToken: "Path=/; Secure; SameSite=Lax"
accessToken: "Path=/; Secure; SameSite=Lax"
refreshToken: "Path=/; Secure; SameSite=Lax"
nonce: "Path=/; Secure; HttpOnly; Max-Age=1800; SameSite=Lax"
staticsite_create_user_pool (Optional[bool]) Wether to create a User Pool for the Auth@Edge configuration.
Requires staticsite_auth_at_edge.
Example
parameters:
staticsite_create_user_pool: true
staticsite_custom_error_responses (Optional[List[Dict[str, Union[int, str]]]]) Define custom error responses.
Example
parameters:
staticsite_custom_error_responses:
- ErrorCode: 404
ResponseCode: 200
ResponsePagePath: /index.html
staticsite_enable_cf_logging (Optional[bool]) Wether logging should be enabled for the CloudFront distribution.
(default: true)
Example
parameters:
staticsite_enable_cf_logging: true
staticsite_http_headers (Optional[Dict[str, str]]) Headers that should be sent with each origin response. (default is
shown in the example)
Please note that the Content-Security-Policy is intentionally lax to allow for Single Page Application frame-
work’s to work as expected. Review your Content Security Policy for your project and update these as need be
to match.
Requires staticsite_auth_at_edge.
9.5. Static Site 139
runway Documentation, Release 1.18.3
Example
parameters:
staticsite_http_headers:
Content-Security-Policy: "default-src https: 'unsafe-eval' 'unsafe-inline';
˓→font-src 'self' 'unsafe-inline' 'unsafe-eval' data: https:; object-src 'none';
˓→connect-src 'self' https://
*
.amazonaws.com https://
*
.amazoncognito.com"
Strict-Transport-Security: "max-age=31536000; includeSubdomains; preload"
Referrer-Policy: "same-origin"
X-XSS-Protection: "1; mode=block"
X-Frame-Options: "DENY"
X-Content-Type-Options: "nosniff"
staticsite_lambda_function_associations (Optional[List[Dict[str, str]]]) This section allows the user to deploy
custom Lambda@Edge associations with their pre-build function versions. This takes precedence over stat-
icsite_rewrite_directory_index and cannot currently be used with staticsite_auth_at_edge.
Example
parameters:
staticsite_lambda_function_associations:
- type: origin-request
arn: arn:aws:lambda:<region>:<account-id>:function:<function>:<version>
staticsite_non_spa (Optional[bool]) Wether this site is a single page application (SPA). (default: true)
A custom error response directing ErrorCode: 404 to the primary /index.html as a
ResponseCode: 200 is added, allowing the SPA to take over error handling. If you are not run-
ning an SPA, setting this to true will prevent this custom error from being added. If provided, static-
site_custom_error_responses takes precedence over this setting.
Requires staticsite_auth_at_edge.
Example
parameters:
staticsite_non_spa: true
staticsite_oauth_scopes (Optional[List[str]]) Scope is a mechanism in OAuth 2.0 to limit an application’s access
to a user’s account. An application can request one or more scopes. This information is then presented to the
user in the consent screen and the access token issued to the application will be limited to the scopes granted.
(default is shown in the example)
Requires staticsite_auth_at_edge.
140 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Example
parameters:
staticsite_oauth_scopes:
- phone
- email
- profile
- openid
- aws.cognito.signin.user.admin
staticsite_redirect_path_auth_refresh (Optional[str]) The path that a user is redirected to when their authorization
tokens have expired (1 hour). (default: /refreshauth)
Requires staticsite_auth_at_edge.
Example
parameters:
staticsite_redirect_path_auth_refresh: /refreshauth
staticsite_redirect_path_sign_in (Optional[str]) The path that a user is redirected to after sign-in (default: /
parseauth). This corresponds with the parseauth Lambda@Edge function which will parse the authenti-
cation details and verify the reception.
Requires staticsite_auth_at_edge.
Example
parameters:
staticsite_redirect_path_sign_in: /parseauth
staticsite_redirect_path_sign_out (Optional[str]) The path that a user is redirected to after sign-out (default: /).
This typically should be the root of the site as the user will be asked to re-login.
Requires staticsite_auth_at_edge.
Example
parameters:
staticsite_redirect_path_sign_out: /
staticsite_rewrite_directory_index (Optional[str]) Deploy a Lambda@Edge function designed to rewrite directory
indexes, e.g. supports accessing urls such as example.org/foo/
9.5. Static Site 141
runway Documentation, Release 1.18.3
Example
parameters:
staticsite_rewrite_directory_index: index.html
staticsite_role_boundary_arn (Optional[str]) Defines an IAM Managed Policy that will be set as the permissions
boundary for any IAM Roles created to support the site. (e.g. when using staticsite_auth_at_edge or static-
site_rewrite_directory_index)
Example
parameters:
staticsite_role_boundary_arn: arn:aws:iam::<account-id>:policy/<policy>
staticsite_sign_out_url (Optional[str]) The path a user should access to sign themselves out of the application. (de-
fault: /signout)
Requires staticsite_auth_at_edge.
Example
parameters:
staticsite_sign_out_url: /signout
staticsite_supported_identity_providers (Optional[str]) A comma delimited list of the User Pool client identity
providers. (default: COGNITO)
Requires staticsite_auth_at_edge.
Example
parameters:
staticsite_supported_identity_providers: facebook,onelogin
staticsite_user_pool_arn (Optional[str]) The ARN of a pre-existing Cognito User Pool to use with Auth@Edge.
Requires staticsite_auth_at_edge.
Example
parameters
staticsite_user_pool_arn: arn:aws:cognito-idp:<region>:<account-id>:userpool/
˓→<pool>
staticsite_additional_redirect_domains (Optional[str]) Additional domains (beyond the staticsite_aliases domains
or the CloudFront URL if no aliases are provided) that will be authorized by the Auth@Edge UserPool App-
Client. This parameter typically won’t be needed in production environments, but can be useful in development
environments to allow bypassing Runway Auth@Edge.
This should be represented as a comma delimited list of domains with protocols. Requires static-
site_auth_at_edge.
142 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Example
parameters:
staticsite_additional_redirect_domains: http://localhost:3000
staticsite_web_acl (Optional[str]) The ARN of a web access control list (web ACL) to associate with the CloudFront
Distribution.
Example
parameters:
staticsite_web_acl: arn:aws:waf::<account-id>:certificate/<cert>
staticsite_required_group (Optional[str]) Name of Cognito User Pool group of which users must be a member to
be granted access to the site. Omit to allow all UserPool users to have access.
Requires staticsite_auth_at_edge.
Example
parameters:
staticsite_required_group: AuthorizedUsers
9.5.2 Directory Structure
Example directory structures for a ref:static site <mod-staticsite> module.
Angular SPA
.
runway.yml
sample-app
README.md
.gitignore
angular.json
browserslist
e2e
protractor.conf.js
src
app.e2e-spec.ts
app.po.ts
tsconfig.json
karma.conf.js
package-lock.json
package.json
src
app
app-routing.module.ts
app.component.css
app.component.html
app.component.spec.ts
(continues on next page)
9.5. Static Site 143
runway Documentation, Release 1.18.3
(continued from previous page)
app.component.ts
app.module.ts
assets
environments
environment.prod.ts
environment.ts
favicon.ico
index.html
main.ts
polyfills.ts
styles.css
test.ts
tsconfig.app.json
tsconfig.json
tsconfig.spec.json
tslint.json
React SPA
.
runway.yml
sample-app
README.md
package.json
public
favicon.ico
index.html
logo192.png
logo512.png
manifest.json
robots.txt
src
App.css
App.js
App.test.js
index.css
index.js
logo.svg
serviceWorker.js
setupTests.js
144 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
9.5.3 Examples
Example uses of the static site module
Angular SPA
To view an example deployment of an Angular single page application, run runway gen-sample
static-angular in any directory. This will create a new static-angular/ directory in your current working
directory containing a runway.yml and a sample-app module that can be deployed.
Extra Files in Angular
By default, angular uses environment/environment.ts as its way to pass environment specific configurations
into your application. The downside to this is that you need to build your application for each environment and lose
ability to build once and deploy everywhere.
The static site extra_files option solves this problem by moving environment configuration out of angular and
into runway. A small change to the way the application references environment config will need to be made.
1. Wrap configuration access into a service that can be injected into your components.
2. In the new config service, make an http request to load the config. Since extra_files uploads the files to
the static site bucket, this request should be relative to your application.
3. Cache the config and use normal observable patterns to provide access.
app.config.ts
export interface Config {
endpoint: string;
}
@Injectable({
providedIn: 'root'
})
export class AppConfig {
constructor(private http: HttpClient) {}
getConfig(): Observable<Config> {
return this.http.get<Config>('assets/config.json');
}
}
app.component.ts
export class AppComponent implements OnInit {
title = 'Angular App';
constructor(private config: AppConfig) {}
ngOnInit() {
this.config.getConfig().subscribe((config) => {
this.title = config.endpoint;
(continues on next page)
9.5. Static Site 145
runway Documentation, Release 1.18.3
(continued from previous page)
});
}
}
runway.yaml
---
variables:
website:
api_endpoint:
dev: https://api.dev.example.com
test: https://api.test.example.com
deployments:
- name: WebApp
modules:
- path: .
type: static
environments:
dev: true
test: true
options:
build_steps:
- npm ci
- npm run build
build_output: dist/web
extra_files:
- name: assets/config.json
content:
endpoint: ${var website.api_endpoint.${env DEPLOY_ENVIRONMENT}}
parameters:
namespace: my-app-namespace
staticsite_cf_disable: true
regions:
- us-east-1
Angular Development Workflow
While developing an Angular application, a local live environment is typically used and Runway is not. This means
that assets/config.json does not exist and your application would likely fail. Take the following steps to get
your development environment running.
1. Create a stub src/assets/config.json that defines all the configuration attributes. The values can be
empty strings.
2. Create a ‘dev’ config file: src/assets/config-dev.json. Populate the configuration values with ap-
propriate values for your local dev environment.
3. Edit angular.json
• Add a fileReplacements option to projects.<app>.architect.build.options.
{
"fileReplacements": [{
"replace": "src/assets/config.json",
(continues on next page)
146 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
(continued from previous page)
"with": "src/assets/config-dev.json"
}]
}
4. Run npx ng serve
Note: It would be a better practice to define a new ‘local’ configuration target instead of adding
fileReplacements to the default configuration target.
“build” Configuration
{
"configurations": {
"local": {
"fileReplacements": [{
"replace": "src/assets/config.json",
"with": "src/assets/config-local.json"
}]
}
}
}
“serve” Configuration
{
"configurations": {
"local": {
"browserTarget": "<app>:build:local"
}
}
}
$ npx ng serve --configuration=local
React SPA
To view an example deployment of a React single page application, run runway gen-sample static-react
in any directory. This will create a new static-react/ directory in your current working directory containing a
runway.yml and a sample-app module that can be deployed.
Extra Files in React
React by itself is not concerned with different environments or how a developer initializes the application with different
backends. This is more of a concern with other layers of your application stack, e.g. Redux. However, the concept is
similar to the Angular examples.
Plain React
// Use your favorite http client
import axios from 'axios';
// Make a request to load the config
(continues on next page)
9.5. Static Site 147
runway Documentation, Release 1.18.3
(continued from previous page)
axios.get('config.json').then(resp => {
return resp.data.endpoint;
})
.then(endpoint => {
// Render the react component
ReactDOM.render(<App message={endpoint} />, document.getElementById('root'));
});
React Redux
Initialize the redux store with an initial config
axios.get('config.json').then(resp => {
return resp.data;
})
.then(config => {
// Create a redux store
return store(config);
})
.then(store => {
ReactDOM.render(
<Provider store={store}>
<App/>
</Provider>,
document.getElementById('root')
);
});
Runway Config
---
ignore_git_branch: true
variables:
website:
api_endpoint:
dev: https://api.dev.example.com
test: https://api.test.example.com
deployments:
- name: WebApp
modules:
- path: .
type: static
environments:
dev: true
test: true
options:
build_output: build
build_steps:
- npm ci
- npm run build
extra_files:
- name: config.json
content:
endpoint: ${var website.api_endpoint.${env DEPLOY_ENVIRONMENT}}
parameters:
namespace: my-app-namespace
staticsite_cf_disable: true
(continues on next page)
148 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
(continued from previous page)
regions:
- us-west-2
React Development Workflow
React doesn’t have an equivalent feature as Angular’s fileReplacements so this solution isn’t as flexible.
1. Create the file public/config.json.
Add content that matches the structure defined in extra_files and populate the values needed for local
development.
Example
{
"endpoint": "https://api.dev.example.com"
}
2. (Optional) Add public/config.json to .gitignore
Note: If you don’t want to add public/config.json to .gitignore, you should configure
Runways source hashing to exclude it.
source_hashing:
enabled: true
directories:
- path: ./
exclusions:
- public/config.json
3. Run npm run start
9.5.4 Advanced Features
Auth@Edge
Auth@Edge provides the ability to make a static site private by using Cognito for authentication. The solution is
inspired by similar implementations such as aws-samples/cloudfront-authorization-at-edge.
The following diagram depicts a high-level overview of this solution.
9.5. Static Site 149
runway Documentation, Release 1.18.3
Here is how the solution works:
1. The viewer’s web browser is redirected to Amazon Cognito custom UI page to sign up and authenticate.
2. After authentication, Cognito generates and cryptographically signs a JWT then responds with a redirect con-
taining the JWT embedded in the URL.
3. The viewer’s web browser extracts JWT from the URL and makes a request to private content (private/* path),
adding Authorization request header with JWT.
4. Amazon CloudFront routes the request to the nearest AWS edge location. The CloudFront distribution’s private
behavior is configured to launch a Lambda@Edge function on ViewerRequest event.
5. Lambda@Edge decodes the JWT and checks if the user belongs to the correct Cognito User Pool. It also verifies
the cryptographic signature using the public RSA key for Cognito User Pool. Crypto verification ensures that
JWT was created by the trusted party.
6. After passing all of the verification steps, Lambda@Edge strips out the Authorization header and allows the
request to pass through to designated origin for CloudFront. In this case, the origin is the private content
Amazon S3 bucket.
7. After receiving response from the origin S3 bucket, CloudFront sends the response back to the browser. The
browser displays the data from the returned response.
An example of an Auth@Edge static site configuration is as follows:
variables:
dev:
namespace: sample-app-dev
staticsite_user_pool_arn: arn:aws:cognito-idp:us-east-1:123456789012:userpool/us-
˓→east-1_example
deployments:
- modules:
- path: sampleapp
type: static
parameters:
namespace: ${var ${env DEPLOY_ENVIRONMENT}.namespace}
staticsite_auth_at_edge: true
(continues on next page)
150 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
(continued from previous page)
staticsite_user_pool_arn: ${var ${env DEPLOY_ENVIRONMENT}.staticsite_user_
˓→pool_arn}
regions:
- us-east-1
The Auth@Edge functionality uses an existing Cognito User Pool (optionally configured with federated identity
providers) or can create one for you with the staticsite_create_user_pool option. A user pool app client will be
automatically created within the pool for use with the application.
Extra Files
The extra files option allows you to use a single build across many deployments. Some popular front end frameworks
guide you into including environment specfic parameters as part of the build. i.e. Angular and Redux-React. This
forces you to abandon 12 factor priciples and slows down deployments to other environments.
The static site extra_files option solves this problem by moving environment configuration out of your code and
into runway. A small change to the way the application references environment config will need to be made.
1. While bootstraping or early in the application lifecycle, make an HTTP call to load one of the extra_files.
2. Make the content of the extra_file available to your app using an appropriate abstraction.
See Static Site Examples to see how to do this in Angular and React.
Configuration (extra_files list item)
name (str) The destination name of the file to create.
file (Optional[str]) A reference to an existing file. The content of this file will be uploaded to the static site S3 bucket
using the name as the object key. This or content must be specified.
content_type (Optional[str]) An explicit content type of the file. If not given, the content type will be auto detected
based on the name. Only .json, .yml, and .yaml extentions are recognized automatically.
• application/json to serialize content into JSON.
• text/yaml to serialize content into YAML.
content (Optional[Union[str, List[Any], Dict[str, Any]]]) Inline content that will be used as the file content. This
or file must be specified.
Note: If none of the files or content changed between builds and source hashing is enabled, the upload will be skipped.
9.6 Terraform
Runway provides a simple way to run the Terraform versions you want with variable values specific to each environ-
ment. Terraform does not need to be installed prior to using this module type. Runway maintains a cache of Terraform
versions on a system, downloading and installing different versions as needed.
• Configuration
• Directory Structure
• Advanced Features
9.6. Terraform 151
runway Documentation, Release 1.18.3
9.6.1 Configuration
Options
Options specific to Terraform Modules.
args (Optional[Union[Dict[str, List[str]], List[str]]]) List of CLI arguments/options to pass to Terraform. See Spec-
ifying Terraform CLI Arguments/Options for more details.
Example
options:
args:
- '-parallelism=25'
terraform_backend_config (Optional[Dict[str, str]]) Mapping to configure Terraform backend. See Backend for
more details.
Changed in version 1.11.0: Added support for any key: value.
Example
options:
terraform_backend_config:
bucket: mybucket
dynamodb_table: mytable
region: us-east-1
terraform_version (Optional[Union[str, Dict[str, str]]]) String containing the Terraform version or a mapping of
deploy environment to a Terraform version. See Version Management for more details.
Example
options:
terraform_version: 0.11.13
terraform_write_auto_tfvars (Optional[bool]) Optionally write parameters to a tfvars file instead of updating vari-
ables (default: False). This can be useful in cases where Runway may not be parsing/passing parameters as
expected.
When True, Runway creates a temporary runway-parameters.auto.tfvars.json file in the module
directory. This file contains all of the modules parameters in JSON format. This file is then automatically loaded
by Terraform as needed. If using a remote backend, use of this file to pass variables is required as environment
variables are not available from the CLI and -var-file currently cannot be used. Once the module has
finished processing, the file is deleted.
New in version 1.11.0.
152 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Example
options:
terraform_write_auto_tfvars: true
Variables
Variables can be defined per-environment using one or both of the following options.
tfvars
Standard Terraform tfvars files can be used, exactly as one normally would with terraform apply -var-file.
Runway will automatically detect them when named like ENV-REGION.tfvars or ENV.tfvars.
Example
Contests of a file named common-us-east-1.tfvars
region = "us-east-1"
image_id = "ami-abc123"
runway.yml
Variable values can also be specified as parameter values in runway.yml. It is recommended to use Lookups in the
parameters section to assist in selecting the appropriate values for the deploy environment and/or region being
deployed to but, this is not a requirement if the value will remain the same.
---
deployments:
- modules:
- path: sampleapp-01.tf
parameters:
region: ${env AWS_REGION}
image_id: ${var image_id.${env AWS_REGION}}
mylist:
- item1
- item2
mymap:
key1: value1
key2: value1
- modules:
- path: sampleapp-02.tf
parameters:
region: ${env AWS_REGION}
image_id: ${var image_id.${env AWS_REGION}}
mylist:
- item1
- item2
mymap:
key1: value1
key2: value1
9.6. Terraform 153
runway Documentation, Release 1.18.3
9.6.2 Directory Structure
Example directory structures for a Terraform module.
Example
.
.terraform-version
backend-us-east-1.tfvars
dev-us-east-1.tfvars
main.tf
9.6.3 Advanced Features
Advanced features and detailed information for using Terraform with Runway.
Backend Configuration
If your Terraform will only ever be used with a single backend, it can be defined inline.
main.tf
terraform {
backend "s3" {
region = "us-east-1"
key = "some_unique_identifier_for_my_module" # e.g. contosovpc
bucket = "some_s3_bucket_name"
dynamodb_table = "some_ddb_table_name"
}
}
However, it’s generally preferable to separate the backend configuration out from the rest of the Terraform code. This
form of configuration is known as partial configuration and allows for dynamic or secret values to be passed in at
runtime.
Below are examples of how to implement partial configuration with Runway. All examples provided showcase the
use of the s3 backend type as it is the easiest to use when going from zero to deployed (try runway gen-sample cfngin
for quickstart Terraform backend infrastructure). However, Runway supports the use of any backend type (refer to
Terraform’s documentation for proper partial configuration instructions).
See also:
https://www.terraform.io/docs/backends/config.html#partial-configuration Terraform partial configuration
https://www.terraform.io/docs/backends/types/index.html Terraform backend types
154 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Backend Config File
Backend config options can be specified in a separate file or multiple files per environment and/or region using one of
the following naming schemes.
• backend-ENV-REGION.hcl/tfvars
• backend-ENV.hcl/tfvars
• backend-REGION.hcl/tfvars
• backend.hcl/tfvars
Changed in version 1.11.0: Added support for hcl files.
Example
region = "us-east-1"
bucket = "some_s3_bucket_name"
dynamodb_table = "some_ddb_table_name"
In the above example, where all but the key are defined, the main.tf backend definition is reduced to the following.
main.tf
terraform {
backend "s3" {
key = "some_unique_identifier_for_my_module" # e.g. contosovpc
}
}
runway.yml
Backend config options can also be specified as a module option in the Runway Config File. Lookups can be used to
provide dynamic values to this option.
Important: There is a bug in Terraform 0.12 that prevents passing blocks to -backend-config (issue). This
means that for backends that use blocks in their config (e.g. remote), the blocks must be provided via file. Attributes
are unaffected.
9.6. Terraform 155
runway Documentation, Release 1.18.3
Listing 5: backend.hcl
workspaces {
prefix = "example-"
}
Module Level
---
deployments:
- modules:
- path: sampleapp-01.tf
options:
terraform_backend_config:
bucket: mybucket
dynamodb_table: mytable
region: us-east-1
- path: sampleapp-02.tf
options:
terraform_backend_config:
bucket: ${cfn common-tf-state.TerraformStateBucketName}
dynamodb_table: ${cfn common-tf-state.TerraformStateTableName}
region: ${env AWS_REGION}
Deployment Level
---
deployments:
- modules:
- path: sampleapp-01.tf
- path: sampleapp-02.tf
module_options: # shared between all modules in deployment
terraform_backend_config:
bucket: ${ssm ParamNameHere::region=us-east-1}
dynamodb_table: ${ssm ParamNameHere::region=us-east-1}
region: ${env AWS_REGION}
Specifying Terraform CLI Arguments/Options
Runway can pass custom arguments/options to the Terraform CLI by using the args option.
The value of args can be provided in one of two ways. The simplest way is to provide a list of arguments/options
which will be appended to terraform apply when executed by Runway. Each element of the argument/option
should be it’s own list item (e.g. -parallelism=25 -no-color would be ['-parallelism=25,
'-no-color']).
For more control, a map can be provided to pass arguments/options to other commands. Arguments can be passed to
terraform apply, terraform init, and/or terraform plan by using the action as the key in the map
(see the Runway Example section below). The value of each key in the map must be a list as described in the previous
section.
156 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Important: The following arguments/options are provided by Runway and should not be provided manually: auto-
approve, backend-config, force, no-color, reconfigure, update, and var-file. Providing any of these manually could
result in unintended side-effects.
Runway Example
---
deployments:
- modules:
- path: sampleapp-01.tf
options:
args:
- '-no-color'
- '-parallelism=25'
- path: sampleapp-02.tf
options:
args:
apply:
- '-no-color'
- '-parallelism=25'
init:
- '-no-color'
plan:
- '-no-color'
- '-parallelism=25'
regions:
- us-east-2
environments:
example: true
Command Equivalent
# runway deploy - sampleapp-01.tf
terraform init -reconfigure
terraform apply -no-color -parallelism=25 -auto-approve=false
# runway plan - sampleapp-01.tf
terraform plan
# runway deploy - sampleapp-02.tf
terraform init -reconfigure -no-color
terraform apply -no-color -parallelism=25 -auto-approve=false
# runway plan - sampleapp-02.tf
terraform plan -no-color -parallelism=25
9.6. Terraform 157
runway Documentation, Release 1.18.3
Version Management
By specifying which version of Terraform to use via a .terraform-version file in your module directory, or
a module option, Runway will automatically download & use that version for the module. This, alongside tightly
pinning Terraform provider versions, is highly recommended to keep a predictable experience when deploying your
module.
.terraform-version
0.11.6
runway.yml
---
deployments:
- modules:
- path: sampleapp-01.tf
options:
terraform_version: 0.11.13
- path: sampleapp-02.tf
options:
terraform_version:
"
*
": 0.11.13 # applies to all environments
# prod: 0.9.0 # can also be specified for a specific environment
Without a version specified, Runway will fallback to whatever terraform it finds first in your PATH.
9.6.4 API Docs
runway package
Set package version.
Submodules
runway.config module
Runway config file module.
class runway.config.ConfigComponent(**kwargs)
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.
158 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
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)
Implement evaluation of get.
resolve(context, variables=None, pre_process=False)
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, environ-
ments=None, parameters=None, env_vars=None, op-
tions=None, tags=None, child_modules=None)
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.
9.6. Terraform 159
runway Documentation, Release 1.18.3
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
160 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
One special map keyword, parallel, indicates a list of child modules that will be executed in parallel (simul-
taneously) 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 map-
ping 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 $AC-
COUNT_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 en-
vironment 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>...)
9.6. Terraform 161
runway Documentation, Release 1.18.3
• 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.
162 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
classmethod from_list(modules)
Instantiate ModuleDefinition from a list.
class runway.config.FutureDefinition(strict_environments=False, **kwargs)
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 at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
class runway.config.DeploymentDefinition(deployment)
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
(continues on next page)
9.6. Terraform 163
runway Documentation, Release 1.18.3
(continued from previous page)
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 map-
ping 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 $AC-
COUNT_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 en-
vironment 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 pro-
cessed 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 re-
gions will be processed one at a time. This can be used in tandom with parallel modules.
164 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
assume_role.post_deploy_env_revert will always be true when run in paral-
lel.
• 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 process-
ing and once during processing. Because of this, the keywords/directives that are resolved before process-
ing 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.
Key-
word /
Directive
Support
account_alias
`env lookup`_ (AWS_REGION and AWS_DEFAULT_REGION will not have been set by Run-
way yet), `var lookup`_
account_id
`env lookup`_ (AWS_REGION and AWS_DEFAULT_REGION will not have been set by Run-
way yet), `var lookup`_
assume_role
`env lookup`_ (AWS_REGION and AWS_DEFAULT_REGION will not have been set by Run-
way 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 Run-
way yet), `var lookup`_
parallel_regions
`env lookup`_ (AWS_REGION and AWS_DEFAULT_REGION will not have been set by Run-
way yet), `var lookup`_
parameters
`env lookup`_, `var lookup`_
9.6. Terraform 165
runway Documentation, Release 1.18.3
References
• module
• deploy
• destroy
• plan
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()
Reverse the order of modules and regions.
classmethod from_list(deployments)
Instantiate DeploymentDefinitions from a list.
class runway.config.TestDefinition(name, test_type, args=None, required=True)
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
166 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
• 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. Sup-
ported arguments vary by test type. See Build-in Test Types for the list of arguments sup-
ported 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 de-
termined 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)
Instantiate TestDefinitions from a list.
class runway.config.VariablesDefinition(file_path=None, sys_path=None, **kwargs)
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.
9.6. Terraform 167
runway Documentation, Release 1.18.3
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)
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)
Load variables.
class runway.config.Config(deployments, future=None, ignore_git_branch=False, run-
way_version=None, tests=None, variables=None)
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.
168 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
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 pro-
cessed 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 be-
fore 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
9.6. Terraform 169
runway Documentation, Release 1.18.3
References
• https://www.python.org/dev/peps/pep-0440/#version-specifiers
• deployment
• test
accepted_names = ['runway.yml', 'runway.yaml']
classmethod load_from_file(config_path)
Load config file into a Config object.
classmethod find_config_file(config_dir=None)
Find the Runway config file.
runway.context module
Runway context module.
class runway.context.Context(_=None, **kwargs)
Bases: object
Runway execution context.
Instantiate class.
Keywork Arguments: command (Optional[str]): Runway command/action being run. deploy_environment
(Optional[DeployEnvironment]): Current
deploy environment.
property boto3_credentials
Return a dict of boto3 credentials.
property current_aws_creds
AWS credentials from self.env_vars.
Returns Dict[str, str]
env_name
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
property env_region
Get or set the current AWS region [DEPRECATED].
property env_root
Get environment root directory [DEPRECATED].
property env_vars
Get environment variables [DEPRECATED].
no_color
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
170 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
property is_interactive
Wether the user should be prompted or not.
Determined by the existed of CI in the environment.
Returns bool
property is_noninteractive
Wether the user should be prompted or not.
Determined by the existed of CI in the environment. Inverse of is_interactive property.
Returns bool
property is_python3
Wether running in Python 3 or not.
Used for Python compatability decisions.
Returns bool
property use_concurrent
Wether to use concurrent.futures or not.
Noninteractive is required for concurrent execution to prevent weird user-input behavior.
Python 3 is required because backported futures has issues with ProcessPoolExecutor.
Returns bool
copy()
Copy the contents of this object into a new instance.
Returns New instance with the same contents.
Return type Context
echo_detected_environment()
Print a helper note about how the environment was determined.
get_session(profile=None, region=None)
Create a thread-safe boto3 session.
Parameters
• profile (Optional[str]) – The profile for the session.
• region (Optional[str]) – The region for the session.
Returns A thread-safe boto3 session.
Return type boto3.session.Session
runway.http_backport module
http backport (added in Python >= 3.5).
Backport for http module: https://docs.python.org/3/library/http.html
class runway.http_backport.HTTPStatus
Bases: enum.IntEnum
HTTP status codes and reason phrases.
Backport for http module: https://docs.python.org/3/library/http.html
9.6. Terraform 171
runway Documentation, Release 1.18.3
Status codes from the following RFCs are all observed:
• RFC 7231: Hypertext Transfer Protocol (HTTP/1.1), obsoletes 2616
• RFC 6585: Additional HTTP Status Codes
• RFC 3229: Delta encoding in HTTP
• RFC 4918: HTTP Extensions for WebDAV, obsoletes 2518
• RFC 5842: Binding Extensions to WebDAV
• RFC 7238: Permanent Redirect
• RFC 2295: Transparent Content Negotiation in HTTP
• RFC 2774: An HTTP Extension Framework
• RFC 7725: An HTTP Status Code to Report Legal Obstacles
• RFC 7540: Hypertext Transfer Protocol Version 2 (HTTP/2)
CONTINUE = 100
SWITCHING_PROTOCOLS = 101
PROCESSING = 102
OK = 200
CREATED = 201
ACCEPTED = 202
NON_AUTHORITATIVE_INFORMATION = 203
NO_CONTENT = 204
RESET_CONTENT = 205
PARTIAL_CONTENT = 206
MULTI_STATUS = 207
ALREADY_REPORTED = 208
IM_USED = 226
MULTIPLE_CHOICES = 300
MOVED_PERMANENTLY = 301
FOUND = 302
SEE_OTHER = 303
NOT_MODIFIED = 304
USE_PROXY = 305
TEMPORARY_REDIRECT = 307
PERMANENT_REDIRECT = 308
BAD_REQUEST = 400
UNAUTHORIZED = 401
PAYMENT_REQUIRED = 402
FORBIDDEN = 403
172 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
NOT_FOUND = 404
METHOD_NOT_ALLOWED = 405
NOT_ACCEPTABLE = 406
PROXY_AUTHENTICATION_REQUIRED = 407
REQUEST_TIMEOUT = 408
CONFLICT = 409
GONE = 410
LENGTH_REQUIRED = 411
PRECONDITION_FAILED = 412
REQUEST_ENTITY_TOO_LARGE = 413
REQUEST_URI_TOO_LONG = 414
UNSUPPORTED_MEDIA_TYPE = 415
REQUESTED_RANGE_NOT_SATISFIABLE = 416
EXPECTATION_FAILED = 417
MISDIRECTED_REQUEST = 421
UNPROCESSABLE_ENTITY = 422
LOCKED = 423
FAILED_DEPENDENCY = 424
UPGRADE_REQUIRED = 426
PRECONDITION_REQUIRED = 428
TOO_MANY_REQUESTS = 429
REQUEST_HEADER_FIELDS_TOO_LARGE = 431
UNAVAILABLE_FOR_LEGAL_REASONS = 451
INTERNAL_SERVER_ERROR = 500
NOT_IMPLEMENTED = 501
BAD_GATEWAY = 502
SERVICE_UNAVAILABLE = 503
GATEWAY_TIMEOUT = 504
HTTP_VERSION_NOT_SUPPORTED = 505
VARIANT_ALSO_NEGOTIATES = 506
INSUFFICIENT_STORAGE = 507
LOOP_DETECTED = 508
NOT_EXTENDED = 510
NETWORK_AUTHENTICATION_REQUIRED = 511
9.6. Terraform 173
runway Documentation, Release 1.18.3
runway.path module
Runway configuration ‘path’ settings.
class runway.path.Path(module, env_root, cache_dir=None, git_source_class=<class 'run-
way.sources.git.Git'>)
Bases: object
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
174 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
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
Path Configuration.
Keyword Arguments
• module (Union(str, Dict[str, str])) – The module manifest or a string repre-
sentation of a local path to a module.
• env_root (str) – The current environments root directory path string.
• cache_dir (Optional[str]) – When a remote resource is requested it’s Source object
requires a cache directory to store it’s request. This allows for an override of that default
directory.
9.6. Terraform 175
runway Documentation, Release 1.18.3
• git_source_class (Optional[Git]) – Dependency injection for the Git type
Source.
References
`Git`_
property configuration
Transform object into configuration settings for remote Sources.
classmethod parse(module)
Retrieve the relevant elements of the path variable passed.
Given a dictionary with a path parameter parse the value into it’s specific components. The path structure
is based on the encoding found in Terraform modules.
Parameters module (Dict[str, str]) – The module manifest or a string representation
of a local path to a module.
runway.runway_module_type module
Abstraction for the module ‘type’ value in a a Runway configuration.
class runway.runway_module_type.RunwayModuleType(path, class_path=None,
type_str=None)
Bases: object
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.
Instantiate class.
Keyword Arguments
• path (str) – The required path to the module
176 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
• class_path (Optional[str]) – A supplied class_path to override the autodetected
one.
• type_str (Optional[str]) – An explicit type to assign to the RunwayModuleType
EXTENSION_MAP = {'cdk': 'runway.module.cdk.CloudDevelopmentKit', 'cfn': 'runway.module.cloudformation.CloudFormation', 'k8s': 'runway.module.k8s.K8s', 'sls': 'runway.module.serverless.Serverless', 'tf': 'runway.module.terraform.Terraform', 'web': 'runway.module.staticsite.StaticSite'}
TYPE_MAP = {'cdk': 'runway.module.cdk.CloudDevelopmentKit', 'cloudformation': 'runway.module.cloudformation.CloudFormation', 'kubernetes': 'runway.module.k8s.K8s', 'serverless': 'runway.module.serverless.Serverless', 'static': 'runway.module.staticsite.StaticSite', 'terraform': 'runway.module.terraform.Terraform'}
runway.s3_util module
Utility functions for S3.
runway.s3_util.purge_and_delete_bucket(bucket_name, region='us-east-1', session=None)
Delete all objects and versions in bucket, then delete bucket.
runway.s3_util.purge_bucket(bucket_name, region='us-east-1', session=None)
Delete all objects and versions in bucket.
runway.s3_util.delete_bucket(bucket_name, region='us-east-1', session=None)
Delete bucket.
runway.s3_util.does_bucket_exist(bucket_name, region='us-east-1', session=None)
Check if bucket exists in S3.
runway.s3_util.ensure_bucket_exists(bucket_name, region='us-east-1', session=None)
Ensure S3 bucket exists.
runway.s3_util.does_s3_object_exist(bucket, key, session=None, region='us-east-1')
Determine if object exists on s3.
runway.s3_util.upload(bucket, key, filename, session=None)
Upload file to S3 bucket.
runway.s3_util.download(bucket, key, file_path, session=None)
Download a file from S3 to the given path.
runway.s3_util.download_and_extract_to_mkdtemp(bucket, key, session=None)
Download zip archive and extract it to temporary directory.
runway.s3_util.get_matching_s3_objects(bucket, prefix='', suffix='', session=None)
Generate objects in an S3 bucket.
Parameters
• bucket – Name of the S3 bucket.
• prefix – Only fetch objects whose key starts with this prefix (optional).
• suffix – Only fetch objects whose keys end with this suffix (optional).
• session – Boto3/botocore session.
runway.s3_util.get_matching_s3_keys(bucket, prefix='', suffix='', session=None)
Generate the keys in an S3 bucket.
Parameters
• bucket – Name of the S3 bucket.
• prefix – Only fetch keys that start with this prefix (optional).
• suffix – Only fetch keys that end with this suffix (optional).
• session – Boto3/botocore session.
9.6. Terraform 177
runway Documentation, Release 1.18.3
runway.util module
Utility functions.
class runway.util.cached_property(func)
Bases: object
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
Initialize class.
Parameters func (Callable) – Method being decorated.
class runway.util.JsonEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, al-
low_nan=True, sort_keys=False, indent=None, separators=None,
default=None)
Bases: json.encoder.JSONEncoder
Encode Python objects to JSON data.
This class can be used with json.dumps() to handle most data types that can occur in responses from AWS.
Usage:
>>> json.dumps(data, cls=JsonEncoder)
Constructor for JSONEncoder, with sensible defaults.
If skipkeys is false, then it is a TypeError to attempt encoding of keys that are not str, int, float or None. If
skipkeys is True, such items are simply skipped.
If ensure_ascii is true, the output is guaranteed to be str objects with all incoming non-ASCII characters escaped.
If ensure_ascii is false, the output can contain non-ASCII characters.
If check_circular is true, then lists, dicts, and custom encoded objects will be checked for circular references
during encoding to prevent an infinite recursion (which would cause an OverflowError). Otherwise, no such
check takes place.
If allow_nan is true, then NaN, Infinity, and -Infinity will be encoded as such. This behavior is not JSON
specification compliant, but is consistent with most JavaScript based encoders and decoders. Otherwise, it will
be a ValueError to encode such floats.
If sort_keys is true, then the output of dictionaries will be sorted by key; this is useful for regression tests to
ensure that JSON serializations can be compared on a day-to-day basis.
If indent is a non-negative integer, then JSON array elements and object members will be pretty-printed with
that indent level. An indent level of 0 will only insert newlines. None is the most compact representation.
If specified, separators should be an (item_separator, key_separator) tuple. The default is (‘, ‘, ‘: ‘) if indent is
None and (‘,’, ‘: ‘) otherwise. To get the most compact JSON representation, you should specify (‘,’, ‘:’) to
eliminate whitespace.
If specified, default is a function that gets called for objects that can’t otherwise be serialized. It should return a
JSON encodable version of the object or raise a TypeError.
default(o)
Encode types not supported by the default JSONEncoder.
Parameters o – Object to encode.
178 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Returns JSON serializable data type.
Raises TypeError – Object type could not be encoded.
class runway.util.MutableMap(**kwargs)
Bases: collections.abc.MutableMapping
Base class for mutable map objects.
Initialize class.
Provided kwargs are added to the object as attributes.
Example
property data
Sanitized output of __dict__.
Removes anything that starts with _.
clear_found_cache()
Clear _found_cache.
find(query, default=None, ignore_cache=False)
Find a value in the map.
Previously found queries are cached to increase search speed. The cached value should only be used if
values are not expected to change.
Parameters
• query – A period delimited string that is split to search for nested values
• default – The value to return if the query was unsuccessful.
• ignore_cache – Ignore cached value.
get(key, default=None)
Implement evaluation of self.get.
Parameters
• key – Attribute name to return the value for.
• default – Value to return if attribute is not found.
class runway.util.SafeHaven(argv=None, environ=None, sys_modules_exclude=None,
sys_path=None)
Bases: contextlib.AbstractContextManager
Context manager that caches and resets important values on exit.
Caches and resets os.environ, sys.argv, sys.modules, and sys.path.
Instantiate class.
Parameters
• argv (Optional[List[str]]) – Override the value of sys.argv.
• environ (Optional[Dict[str, str]]) – Update os.environ.
• sys_modules_exclude (Optional[List[str]]) – A list of modules to ex-
clude when reverting sys.modules to its previous state. These are checked as module.
startswith(name).
9.6. Terraform 179
runway Documentation, Release 1.18.3
• sys_path (Optional[List[str]]) – Override the value of sys.path.
reset_all()
Reset all values cached by this context manager.
reset_os_environ()
Reset the value of os.environ.
reset_sys_argv()
Reset the value of sys.argv.
reset_sys_modules()
Reset the value of sys.modules.
reset_sys_path()
Reset the value of sys.path.
class runway.util.YamlDumper(stream, default_style=None, default_flow_style=False, canon-
ical=None, indent=None, width=None, allow_unicode=None,
line_break=None, encoding=None, explicit_start=None, ex-
plicit_end=None, version=None, tags=None, sort_keys=True)
Bases: yaml.dumper.Dumper
Custom YAML Dumper.
This Dumper allows for YAML to be output to follow YAML spec 1.2, example 2.3 of collections (2.1). This
provides an output that is more humanreadable and complies with yamllint.
Example
>>> print(yaml.dump({'key': ['val1', 'val2']}, Dumper=YamlDumper))
Note: YAML 1.2 Specification: https://yaml.org/spec/1.2/spec.html used for reference.
increase_indent(flow=False, indentless=False)
Override parent method.
runway.util.argv(*args)
Context manager for temporarily changing sys.argv.
runway.util.change_dir(newdir)
Change directory.
Adapted from http://stackoverflow.com/a/24176022
runway.util.ensure_file_is_executable(path)
Exit if file is not executable.
runway.util.environ(env=None, **kwargs)
Context manager for temporarily changing os.environ.
The original value of os.environ is restored upon exit.
Parameters env (Dict[str, str]) – Dictionary to use when updating os.environ.
runway.util.json_serial(obj)
JSON serializer for objects not serializable by default json code.
runway.util.load_object_from_string(fqcn, try_reload=False)
Convert “.” delimited strings to a python object.
180 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Parameters
• fqcn (str) – A “.” delimited string representing the full path to an object (function, class,
variable) inside a module
• try_reload (bool) – Try to reload the module so any global variables set within the file
during import are reloaded. This only applies to modules that are already imported and are
not builtin.
Returns Object being imported from the provided path.
Return type Any
Example:
load_object_from_string("os.path.basename")
load_object_from_string("logging.Logger")
load_object_from_string("LocalClassName")
runway.util.merge_dicts(dict1, dict2, deep_merge=True)
Merge dict2 into dict1.
runway.util.extract_boto_args_from_env(env_vars)
Return boto3 client args dict with environment creds.
runway.util.flatten_path_lists(env_dict, env_root=None)
Join paths in environment dict down to strings.
runway.util.merge_nested_environment_dicts(env_dicts, env_name=None, env_root=None)
Return single-level dictionary from dictionary of dictionaries.
runway.util.find_cfn_output(key, outputs)
Return CFN output value.
runway.util.get_embedded_lib_path()
Return path of embedded libraries.
runway.util.get_hash_for_filename(filename, hashfile_path)
Return hash for filename in the hashfile.
runway.util.ignore_exit_code_0()
Capture exit calls and ignore those with exit code 0.
runway.util.fix_windows_command_list(commands)
Return command list with working Windows commands.
npm on windows is npm.cmd, which will blow up subprocess.check_call([‘npm’, ‘. . . ’])
Similar issues arise when calling python apps like pipenv that will have a windows-only suffix applied to them
runway.util.run_commands(commands, directory, env=None)
Run list of commands.
runway.util.get_file_hash(filename, algorithm)
Return cryptographic hash of file.
runway.util.md5sum(filename)
Return MD5 hash of file.
runway.util.sha256sum(filename)
Return SHA256 hash of file.
runway.util.strip_leading_option_delim(args)
Remove leading – if present.
9.6. Terraform 181
runway Documentation, Release 1.18.3
Using the “–” end of options syntax bypasses docopt’s parsing of options.
runway.util.use_embedded_pkgs(embedded_lib_path=None)
Temporarily prepend embedded packages to sys.path.
runway.util.which(program)
Mimic ‘which’ command behavior.
runway.variables module
Runway variables.
runway.variables.resolve_variables(variables, context, provider)
Given a list of variables, resolve all of them.
Parameters
• variables (List[Variable]) – List of variables.
• context (runway.cfngin.context.Context) – CFNgin context.
• provider (runway.cfngin.providers.base.BaseProvider) – Subclass of
the base provider.
class runway.variables.Variable(name, value, variable_type='cfngin')
Bases: object
Represents a variable provided to a Runway directive.
Initialize class.
Parameters
• name – Name of the variable (directive/key).
• value – The variable itself.
• variable_type – Type of variable (cfngin|runway).
property dependencies
Stack names that this variable depends on.
Returns Stack names that this variable depends on.
Return type Set[str]
property resolved
Boolean for whether the Variable has been resolved.
Variables only need to be resolved if they contain lookups.
property value
Return the current value of the Variable.
resolve(context, provider=None, variables=None, **kwargs)
Resolve the variable value.
Parameters
• context – The current context object.
• provider – Subclass of the base provider.
• variables – Object containing variables passed to Runway.
182 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
get(key, default=None)
Implement evaluation of self.get.
Parameters
• key – Attribute name to return the value for.
• default – Value to return if attribute is not found.
class runway.variables.VariableValue
Bases: object
Syntax tree base class to parse variable values.
property dependencies
Stack names that this variable depends on.
property resolved
Use to check if the variable value has been resolved.
Should be implimented in subclasses.
property simplified
Return a simplified version of the value.
This can be used to concatenate two literals into one literal or flatten nested concatenations.
Should be implimented in subclasses where applicable.
property value
Value of the variable. Can be resolved or unresolved.
Should be implimented in subclasses.
resolve(context, provider=None, variables=None, **kwargs)
Resolve the variable value.
Parameters
• context – The current context object.
• provider – Subclass of the base provider.
• variables – Object containing variables passed to Runway.
classmethod parse(input_object, variable_type='cfngin')
Parse complex variable structures using type appropriate subclasses.
Parameters
• input_object – The objected defined as the value of a variable.
• variable_type – Type of variable (cfngin|runway).
class runway.variables.VariableValueLiteral(value)
Bases: runway.variables.VariableValue
The literal value of a variable as provided.
Initialize class.
property resolved
Use to check if the variable value has been resolved.
The ValueLiteral will always appear as resolved because it does not “resolve” since it is the literal definition
of the value.
9.6. Terraform 183
runway Documentation, Release 1.18.3
property value
Value of the variable.
class runway.variables.VariableValueList
Bases: runway.variables.VariableValue, list
A list variable value.
property dependencies
Stack names that this variable depends on.
property resolved
Use to check if the variable value has been resolved.
property simplified
Return a simplified version of the value.
This can be used to concatenate two literals into one literal or flatten nested concatenations.
property value
Value of the variable. Can be resolved or unresolved.
resolve(context, provider=None, variables=None, **kwargs)
Resolve the variable value.
Parameters
• context – The current context object.
• provider – Subclass of the base provider.
• variables – Object containing variables passed to Runway.
classmethod parse(input_object, variable_type='cfngin')
Parse list variable structure.
Parameters
• input_object – The objected defined as the value of a variable.
• variable_type – Type of variable (cfngin|runway).
class runway.variables.VariableValueDict
Bases: runway.variables.VariableValue, dict
A dict variable value.
property dependencies
Stack names that this variable depends on.
property resolved
Use to check if the variable value has been resolved.
property simplified
Return a simplified version of the value.
This can be used to concatenate two literals into one literal or flatten nested concatenations.
property value
Value of the variable. Can be resolved or unresolved.
resolve(context, provider=None, variables=None, **kwargs)
Resolve the variable value.
Parameters
• context – The current context object.
184 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
• provider – Subclass of the base provider.
• variables – Object containing variables passed to Runway.
classmethod parse(input_object, variable_type='cfngin')
Parse list variable structure.
Parameters
• input_object – The objected defined as the value of a variable.
• variable_type – Type of variable (cfngin|runway).
class runway.variables.VariableValueConcatenation
Bases: runway.variables.VariableValue, list
A concatinated variable value.
property dependencies
Stack names that this variable depends on.
property resolved
Use to check if the variable value has been resolved.
property simplified
Return a simplified version of the value.
This can be used to concatenate two literals into one literal or flatten nested concatenations.
property value
Value of the variable. Can be resolved or unresolved.
resolve(context, provider=None, variables=None, **kwargs)
Resolve the variable value.
Parameters
• context – The current context object.
• provider – Subclass of the base provider.
• variables – Object containing variables passed to Runway.
class runway.variables.VariableValueLookup(lookup_name, lookup_data, handler=None,
variable_type='cfngin')
Bases: runway.variables.VariableValue
A lookup variable value.
Initialize class.
Parameters
• lookup_name – Name of the invoked lookup
• lookup_data – Data portion of the lookup
• handler – Lookup handler that will be use to resolve the value.
• variable_type – Type of variable (cfngin|runway).
property dependencies
Stack names that this variable depends on.
property resolved
Use to check if the variable value has been resolved.
9.6. Terraform 185
runway Documentation, Release 1.18.3
property simplified
Return a simplified version of the value.
This can be used to concatenate two literals into one literal or flatten nested concatenations.
property value
Value of the variable. Can be resolved or unresolved.
resolve(context, provider=None, variables=None, **kwargs)
Resolve the variable value.
Parameters
• context – The current context object.
• provider – Subclass of the base provider.
• variables – Object containing variables passed to Runway.
Raises FailedLookup – A lookup failed for any reason.
Subpackages
runway.aws_sso_botocore package
Support for AWS SSO.
IMPORTANT: This will be removed upon botocore/boto3 officially supporting authentication with AWS SSO profiles.
The code in this directory is taken from https://github.com/boto/botocore/tree/
bf6d31f42f90a547707df4e83943702beacda45a and modified to meet the requirements of this project.
Submodules
runway.aws_sso_botocore.credentials module
Botocore with support for AWS SSO credential assets.
runway.aws_sso_botocore.credentials.create_credential_resolver(session,
cache=None,
re-
gion_name=None)
Create a default credential resolver.
This creates a pre-configured credential resolver that includes the default lookup chain for credentials.
class runway.aws_sso_botocore.credentials.ProfileProviderBuilder(session,
cache=None,
re-
gion_name=None,
sso_token_cache=None)
Bases: botocore.credentials.ProfileProviderBuilder
Extends the botocore profile provider builder to support AWS SSO.
Instantiate class.
providers(profile_name, disable_env_vars=False)
Return list of providers.
186 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
class runway.aws_sso_botocore.credentials.SSOCredentialFetcher(start_url,
sso_region,
role_name,
account_id,
client_creator,
to-
ken_loader=None,
cache=None,
ex-
piry_window_seconds=None)
Bases: botocore.credentials.CachedCredentialFetcher
AWS SSO credential fetcher.
Instantiate class.
class runway.aws_sso_botocore.credentials.SSOProvider(load_config, client_creator,
profile_name, cache=None,
token_cache=None)
Bases: botocore.credentials.CredentialProvider
AWS SSO credential provider.
Instantiate class.
METHOD = 'sso'
load()
Load AWS SSO credentials.
runway.aws_sso_botocore.exceptions module
Botocore with support for AWS SSO exceptions.
exception runway.aws_sso_botocore.exceptions.SSOError(**kwargs)
Bases: botocore.exceptions.BotoCoreError
Base class for AWS SSO authentication errors.
fmt = 'An unspecified error happened when resolving SSO credentials'
exception runway.aws_sso_botocore.exceptions.PendingAuthorizationExpiredError(**kwargs)
Bases: runway.aws_sso_botocore.exceptions.SSOError
Pending AWS SSO authorization expired.
fmt = 'The pending authorization to retrieve an SSO token has expired. The device authorization flow to retrieve an SSO token must be restarted.'
exception runway.aws_sso_botocore.exceptions.SSOTokenLoadError(**kwargs)
Bases: runway.aws_sso_botocore.exceptions.SSOError
AWS SSO token load error.
fmt = 'Error loading SSO Token: {error_msg}'
exception runway.aws_sso_botocore.exceptions.UnauthorizedSSOTokenError(**kwargs)
Bases: runway.aws_sso_botocore.exceptions.SSOError
Unauthorized AWS SSO token.
fmt = 'The SSO session associated with this profile has expired or is otherwise invalid. To refresh this SSO session run aws sso login with the corresponding profile.'
9.6. Terraform 187
runway Documentation, Release 1.18.3
runway.aws_sso_botocore.session module
Botocore with support for AWS SSO session assets.
class runway.aws_sso_botocore.session.Session(session_vars=None, event_hooks=None,
include_builtin_handlers=True, pro-
file=None)
Bases: botocore.session.Session
Extends the botocore session to support AWS SSO.
Create a new Session object.
Parameters
• session_vars (dict) – A dictionary that is used to override some or all of the environ-
ment variables associated with this session. The key/value pairs defined in this dictionary
will override the corresponding variables defined in SESSION_VARIABLES.
• event_hooks (BaseEventHooks) – The event hooks object to use. If one is not pro-
vided, an event hooks object will be automatically created for you.
• include_builtin_handlers (bool) – Indicates whether or not to automatically reg-
ister builtin handlers.
• profile (str) – The name of the profile to use for this session. Note that the profile can
only be set when the session is created.
runway.aws_sso_botocore.util module
Botocore with support for AWS SSO utilities.
class runway.aws_sso_botocore.util.SSOTokenLoader(cache=None)
Bases: object
AWS SSO token loader.
Instantiate class.
runway.blueprints package
Empty init for python import traversal.
Submodules
runway.blueprints.tf_state module
Module with Terraform state resources.
class runway.blueprints.tf_state.TfState(name, context, mappings=None, descrip-
tion=None)
Bases: runway.cfngin.blueprints.base.Blueprint
Stacker blueprint for creating Terraform state resources.
Instantiate class.
Parameters
188 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
• name (str) – A name for the blueprint.
• context (runway.cfngin.context.Context) – Context the blueprint is being ex-
ecuted under.
• mappings (dict, optional) – CloudFormation Mappings to be used in the template.
• description (str) – Used to describe the resulting CloudFormation template.
VARIABLES = {'BucketName': {'default': '', 'description': '(optional) Name for the S3 bucket', 'type': <runway.cfngin.blueprints.variables.types.CFNType object>}, 'TableName': {'default': '', 'description': '(optional) Name for the DynamoDB table', 'type': <runway.cfngin.blueprints.variables.types.CFNType object>}}
create_template()
Create template (main function called by Stacker).
Subpackages
runway.blueprints.k8s package
Empty init for python import traversal.
Submodules
runway.blueprints.k8s.k8s_iam module
Module with k8s IAM resources.
class runway.blueprints.k8s.k8s_iam.Iam(name, context, mappings=None, descrip-
tion=None)
Bases: runway.cfngin.blueprints.base.Blueprint
Stacker blueprint for creating k8s IAM resources.
Instantiate class.
Parameters
• name (str) – A name for the blueprint.
• context (runway.cfngin.context.Context) – Context the blueprint is being ex-
ecuted under.
• mappings (dict, optional) – CloudFormation Mappings to be used in the template.
• description (str) – Used to describe the resulting CloudFormation template.
create_template()
Create template (main function called by Stacker).
runway.blueprints.k8s.k8s_master module
Module with k8s cluster resources.
class runway.blueprints.k8s.k8s_master.Cluster(name, context, mappings=None, de-
scription=None)
Bases: runway.cfngin.blueprints.base.Blueprint
Stacker blueprint for creating k8s cluster resources.
Instantiate class.
9.6. Terraform 189
runway Documentation, Release 1.18.3
Parameters
• name (str) – A name for the blueprint.
• context (runway.cfngin.context.Context) – Context the blueprint is being ex-
ecuted under.
• mappings (dict, optional) – CloudFormation Mappings to be used in the template.
• description (str) – Used to describe the resulting CloudFormation template.
VARIABLES = {'EksClusterName': {'description': 'Name of the Kubernetes cluster', 'max_length': 40, 'min_length': 2, 'type': <runway.cfngin.blueprints.variables.types.CFNType object>}, 'EksSubnets': {'description': 'Subnets where the Kubernetes cluster will live', 'type': <runway.cfngin.blueprints.variables.types.CFNType object>}, 'EksVersion': {'description': 'Kubernetes version', 'type': <runway.cfngin.blueprints.variables.types.CFNType object>}, 'VPC': {'description': 'VPC where the Kubernetes cluster will live', 'type': <runway.cfngin.blueprints.variables.types.CFNType object>}}
create_template()
Create template (main function called by Stacker).
runway.blueprints.k8s.k8s_workers module
Module with k8s nodegroup.
runway.blueprints.k8s.k8s_workers.get_valid_instance_types()
Return list of instance types.
class runway.blueprints.k8s.k8s_workers.NodeGroup(name, context, mappings=None, de-
scription=None)
Bases: runway.cfngin.blueprints.base.Blueprint
Stacker blueprint for creating k8s nodegroup.
Instantiate class.
Parameters
• name (str) – A name for the blueprint.
• context (runway.cfngin.context.Context) – Context the blueprint is being ex-
ecuted under.
• mappings (dict, optional) – CloudFormation Mappings to be used in the template.
• description (str) – Used to describe the resulting CloudFormation template.
VARIABLES = {'BootstrapArguments': {'default': '', 'description': 'Arguments to pass to the bootstrap script. See files/bootstrap.sh in https://github.com/awslabs/amazon-eks-ami', 'type': <runway.cfngin.blueprints.variables.types.CFNType object>}, 'ClusterControlPlaneSecurityGroup': {'description': 'The security group of the cluster control plane.', 'type': <runway.cfngin.blueprints.variables.types.CFNType object>}, 'ClusterName': {'description': 'The cluster name provided when the cluster was created. If it is incorrect, nodes will not be able to join the cluster.', 'type': <runway.cfngin.blueprints.variables.types.CFNType object>}, 'KeyName': {'default': '', 'description': '(Optional) EC2 Key Pair to allow SSH access to the instances', 'type': <runway.cfngin.blueprints.variables.types.CFNType object>}, 'NodeAutoScalingGroupMaxSize': {'default': 3, 'description': 'Maximum size of Node Group ASG.', 'type': <runway.cfngin.blueprints.variables.types.CFNType object>}, 'NodeAutoScalingGroupMinSize': {'default': 1, 'description': 'Minimum size of Node Group ASG.', 'type': <runway.cfngin.blueprints.variables.types.CFNType object>}, 'NodeGroupName': {'description': 'Unique identifier for the Node Group.', 'type': <runway.cfngin.blueprints.variables.types.CFNType object>}, 'NodeImageId': {'description': 'AMI id for the node instances.', 'type': <runway.cfngin.blueprints.variables.types.CFNType object>}, 'NodeInstanceProfile': {'description': 'Instance profile for the nodes.', 'type': <runway.cfngin.blueprints.variables.types.CFNType object>}, 'NodeInstanceType': {'allowed_values': ['t1.micro', 't2.nano', 't2.micro', 't2.small', 't2.medium', 't2.large', 't2.xlarge', 't2.2xlarge', 't3.nano', 't3.micro', 't3.small', 't3.medium', 't3.large', 't3.xlarge', 't3.2xlarge', 't3a.nano', 't3a.micro', 't3a.small', 't3a.medium', 't3a.large', 't3a.xlarge', 't3a.2xlarge', 't4g.nano', 't4g.micro', 't4g.small', 't4g.medium', 't4g.large', 't4g.xlarge', 't4g.2xlarge', 'm1.small', 'm1.medium', 'm1.large', 'm1.xlarge', 'm3.medium', 'm3.large', 'm3.xlarge', 'm3.2xlarge', 'm4.large', 'm4.xlarge', 'm4.2xlarge', 'm4.4xlarge', 'm4.10xlarge', 'm4.16xlarge', 'm2.xlarge', 'm2.2xlarge', 'm2.4xlarge', 'cr1.8xlarge', 'r3.large', 'r3.xlarge', 'r3.2xlarge', 'r3.4xlarge', 'r3.8xlarge', 'r4.large', 'r4.xlarge', 'r4.2xlarge', 'r4.4xlarge', 'r4.8xlarge', 'r4.16xlarge', 'r5.large', 'r5.xlarge', 'r5.2xlarge', 'r5.4xlarge', 'r5.8xlarge', 'r5.12xlarge', 'r5.16xlarge', 'r5.24xlarge', 'r5.metal', 'r5a.large', 'r5a.xlarge', 'r5a.2xlarge', 'r5a.4xlarge', 'r5a.8xlarge', 'r5a.12xlarge', 'r5a.16xlarge', 'r5a.24xlarge', 'r5d.large', 'r5d.xlarge', 'r5d.2xlarge', 'r5d.4xlarge', 'r5d.8xlarge', 'r5d.12xlarge', 'r5d.16xlarge', 'r5d.24xlarge', 'r5d.metal', 'r5ad.large', 'r5ad.xlarge', 'r5ad.2xlarge', 'r5ad.4xlarge', 'r5ad.8xlarge', 'r5ad.12xlarge', 'r5ad.16xlarge', 'r5ad.24xlarge', 'r6g.metal', 'r6g.medium', 'r6g.large', 'r6g.xlarge', 'r6g.2xlarge', 'r6g.4xlarge', 'r6g.8xlarge', 'r6g.12xlarge', 'r6g.16xlarge', 'r6gd.metal', 'r6gd.medium', 'r6gd.large', 'r6gd.xlarge', 'r6gd.2xlarge', 'r6gd.4xlarge', 'r6gd.8xlarge', 'r6gd.12xlarge', 'r6gd.16xlarge', 'x1.16xlarge', 'x1.32xlarge', 'x1e.xlarge', 'x1e.2xlarge', 'x1e.4xlarge', 'x1e.8xlarge', 'x1e.16xlarge', 'x1e.32xlarge', 'i2.xlarge', 'i2.2xlarge', 'i2.4xlarge', 'i2.8xlarge', 'i3.large', 'i3.xlarge', 'i3.2xlarge', 'i3.4xlarge', 'i3.8xlarge', 'i3.16xlarge', 'i3.metal', 'i3en.large', 'i3en.xlarge', 'i3en.2xlarge', 'i3en.3xlarge', 'i3en.6xlarge', 'i3en.12xlarge', 'i3en.24xlarge', 'i3en.metal', 'hi1.4xlarge', 'hs1.8xlarge', 'c1.medium', 'c1.xlarge', 'c3.large', 'c3.xlarge', 'c3.2xlarge', 'c3.4xlarge', 'c3.8xlarge', 'c4.large', 'c4.xlarge', 'c4.2xlarge', 'c4.4xlarge', 'c4.8xlarge', 'c5.large', 'c5.xlarge', 'c5.2xlarge', 'c5.4xlarge', 'c5.9xlarge', 'c5.12xlarge', 'c5.18xlarge', 'c5.24xlarge', 'c5.metal', 'c5a.large', 'c5a.xlarge', 'c5a.2xlarge', 'c5a.4xlarge', 'c5a.8xlarge', 'c5a.12xlarge', 'c5a.16xlarge', 'c5a.24xlarge', 'c5ad.large', 'c5ad.xlarge', 'c5ad.2xlarge', 'c5ad.4xlarge', 'c5ad.8xlarge', 'c5ad.12xlarge', 'c5ad.16xlarge', 'c5ad.24xlarge', 'c5d.large', 'c5d.xlarge', 'c5d.2xlarge', 'c5d.4xlarge', 'c5d.9xlarge', 'c5d.12xlarge', 'c5d.18xlarge', 'c5d.24xlarge', 'c5d.metal', 'c5n.large', 'c5n.xlarge', 'c5n.2xlarge', 'c5n.4xlarge', 'c5n.9xlarge', 'c5n.18xlarge', 'c6g.metal', 'c6g.medium', 'c6g.large', 'c6g.xlarge', 'c6g.2xlarge', 'c6g.4xlarge', 'c6g.8xlarge', 'c6g.12xlarge', 'c6g.16xlarge', 'c6gd.metal', 'c6gd.medium', 'c6gd.large', 'c6gd.xlarge', 'c6gd.2xlarge', 'c6gd.4xlarge', 'c6gd.8xlarge', 'c6gd.12xlarge', 'c6gd.16xlarge', 'cc1.4xlarge', 'cc2.8xlarge', 'g2.2xlarge', 'g2.8xlarge', 'g3.4xlarge', 'g3.8xlarge', 'g3.16xlarge', 'g3s.xlarge', 'g4dn.xlarge', 'g4dn.2xlarge', 'g4dn.4xlarge', 'g4dn.8xlarge', 'g4dn.12xlarge', 'g4dn.16xlarge', 'g4dn.metal', 'cg1.4xlarge', 'p2.xlarge', 'p2.8xlarge', 'p2.16xlarge', 'p3.2xlarge', 'p3.8xlarge', 'p3.16xlarge', 'p3dn.24xlarge', 'd2.xlarge', 'd2.2xlarge', 'd2.4xlarge', 'd2.8xlarge', 'f1.2xlarge', 'f1.4xlarge', 'f1.16xlarge', 'm5.large', 'm5.xlarge', 'm5.2xlarge', 'm5.4xlarge', 'm5.8xlarge', 'm5.12xlarge', 'm5.16xlarge', 'm5.24xlarge', 'm5.metal', 'm5a.large', 'm5a.xlarge', 'm5a.2xlarge', 'm5a.4xlarge', 'm5a.8xlarge', 'm5a.12xlarge', 'm5a.16xlarge', 'm5a.24xlarge', 'm5d.large', 'm5d.xlarge', 'm5d.2xlarge', 'm5d.4xlarge', 'm5d.8xlarge', 'm5d.12xlarge', 'm5d.16xlarge', 'm5d.24xlarge', 'm5d.metal', 'm5ad.large', 'm5ad.xlarge', 'm5ad.2xlarge', 'm5ad.4xlarge', 'm5ad.8xlarge', 'm5ad.12xlarge', 'm5ad.16xlarge', 'm5ad.24xlarge', 'h1.2xlarge', 'h1.4xlarge', 'h1.8xlarge', 'h1.16xlarge', 'z1d.large', 'z1d.xlarge', 'z1d.2xlarge', 'z1d.3xlarge', 'z1d.6xlarge', 'z1d.12xlarge', 'z1d.metal', 'u-6tb1.metal', 'u-9tb1.metal', 'u-12tb1.metal', 'u-18tb1.metal', 'u-24tb1.metal', 'a1.medium', 'a1.large', 'a1.xlarge', 'a1.2xlarge', 'a1.4xlarge', 'a1.metal', 'm5dn.large', 'm5dn.xlarge', 'm5dn.2xlarge', 'm5dn.4xlarge', 'm5dn.8xlarge', 'm5dn.12xlarge', 'm5dn.16xlarge', 'm5dn.24xlarge', 'm5n.large', 'm5n.xlarge', 'm5n.2xlarge', 'm5n.4xlarge', 'm5n.8xlarge', 'm5n.12xlarge', 'm5n.16xlarge', 'm5n.24xlarge', 'r5dn.large', 'r5dn.xlarge', 'r5dn.2xlarge', 'r5dn.4xlarge', 'r5dn.8xlarge', 'r5dn.12xlarge', 'r5dn.16xlarge', 'r5dn.24xlarge', 'r5n.large', 'r5n.xlarge', 'r5n.2xlarge', 'r5n.4xlarge', 'r5n.8xlarge', 'r5n.12xlarge', 'r5n.16xlarge', 'r5n.24xlarge', 'inf1.xlarge', 'inf1.2xlarge', 'inf1.6xlarge', 'inf1.24xlarge', 'm6g.metal', 'm6g.medium', 'm6g.large', 'm6g.xlarge', 'm6g.2xlarge', 'm6g.4xlarge', 'm6g.8xlarge', 'm6g.12xlarge', 'm6g.16xlarge', 'm6gd.metal', 'm6gd.medium', 'm6gd.large', 'm6gd.xlarge', 'm6gd.2xlarge', 'm6gd.4xlarge', 'm6gd.8xlarge', 'm6gd.12xlarge', 'm6gd.16xlarge'], 'constraint_description': 'Must be a valid EC2 instance type', 'default': 't2.medium', 'description': 'EC2 instance type for the node instances', 'type': <runway.cfngin.blueprints.variables.types.CFNType object>}, 'NodeVolumeSize': {'default': 20, 'description': 'Node volume size', 'type': <runway.cfngin.blueprints.variables.types.CFNType object>}, 'SpotBidPrice': {'default': '0.68', 'description': 'Bid price for Spot instance workers (only relevant if UseSpotInstances is set to "yes")', 'type': <runway.cfngin.blueprints.variables.types.CFNType object>}, 'Subnets': {'description': 'The subnets where workers can be created.', 'type': <runway.cfngin.blueprints.variables.types.CFNType object>}, 'UseDesiredInstanceCount': {'description': 'Should the initial bootstrap instance count be used?', 'type': <runway.cfngin.blueprints.variables.types.CFNType object>}, 'UseSpotInstances': {'allowed_values': ['yes', 'no'], 'default': 'no', 'description': 'Should the instances be configured as spot instances?', 'type': <runway.cfngin.blueprints.variables.types.CFNType object>}, 'VpcId': {'description': 'The VPC of the worker instances', 'type': <runway.cfngin.blueprints.variables.types.CFNType object>}}
create_template()
Create template (main function called by Stacker).
runway.blueprints.staticsite package
Empty init for python import traversal.
190 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Submodules
runway.blueprints.staticsite.auth_at_edge module
Blueprint for the Authorization@Edge implementation of a Static Site.
Described in detail in this blogpost: https://aws.amazon.com/blogs/networking-and-content-delivery/
authorizationedge-how-to-use-lambdaedge-and-json-web-tokens-to-enhance-web-application-security/
class runway.blueprints.staticsite.auth_at_edge.AuthAtEdge(name, context, map-
pings=None, descrip-
tion=None)
Bases: runway.blueprints.staticsite.staticsite.StaticSite
Auth@Edge Blueprint.
Initialize the Blueprint.
Parameters
• name (str) – The name of the stack.
• context (Context) – The CFNgin Context object.
• mappings (Union(None, Dict)) – Blueprint mappings.
• description (Union(None, str)) – The description of the stack.
IAM_ARN_PREFIX = 'arn:aws:iam::aws:policy/service-role/'
AUTH_VARIABLES = {'NonSPAMode': {'default': False, 'description': 'Whether Auth@Edge should omit SPA specific settings', 'type': <class 'bool'>}, 'OAuthScopes': {'default': [], 'description': 'OAuth2 Scopes', 'type': <class 'list'>}, 'PriceClass': {'default': 'PriceClass_100', 'description': 'CF price class for the distribution.', 'type': <class 'str'>}, 'RedirectPathAuthRefresh': {'default': '/refreshauth', 'description': 'The URL path that should handle the JWT refresh request.', 'type': <class 'str'>}, 'RedirectPathSignIn': {'default': '/parseauth', 'description': 'Auth@Edge: The URL that should handle the redirect from Cognito after sign-in.', 'type': <class 'str'>}, 'SignOutUrl': {'default': '/signout', 'description': 'The URL path that you can visit to sign-out.', 'type': <class 'str'>}}
VARIABLES = {}
create_template()
Create the Blueprinted template for Auth@Edge.
get_auth_at_edge_lambda_and_ver(title, description, handle, role)
Create a lambda function and its version.
Parameters
• title (str) – The name of the function in PascalCase.
• description (str) – Description to be displayed in the lambda panel.
• handle (str) – The underscore separated representation of the name of the lambda.
This handle is used to determine the handler for the lambda as well as identify the correct
Code hook_data information.
• role (IAM.Role) – The Lambda Execution Role.
get_auth_at_edge_lambda(title, description, handler, role)
Create an Auth@Edge lambda resource.
Parameters
• title (str) – The name of the function in PascalCase.
• description (str) – Description to be displayed in the lambda panel.
• handler (str) – The underscore separated representation of the name of the lambda.
This handle is used to determine the handler for the lambda as well as identify the correct
Code hook_data information.
• role (IAM.Role) – The Lambda Execution Role.
9.6. Terraform 191
runway Documentation, Release 1.18.3
add_version(title, lambda_function)
Create a version association with a Lambda@Edge function.
In order to ensure different versions of the function are appropriately uploaded a hash based on the code
of the lambda is appended to the name. As the code changes so will this hash value.
Parameters
• title (str) – The name of the function in PascalCase.
• lambda_function (awslambda.Function) – The Lambda function.
get_distribution_options(bucket, oai, lambda_funcs, check_auth_lambda_version,
http_headers_lambda_version, parse_auth_lambda_version,
refresh_auth_lambda_version, sign_out_lambda_version)
Retrieve the options for our CloudFront distribution.
Keyword Arguments
• bucket – The bucket resource.
• oai – The origin access identity resource.
• lambda_funcs – List of Lambda Function associations.
• check_auth_lambda_version – Lambda Function Version to use.
• http_headers_lambda_version – Lambda Function Version to use.
• parse_auth_lambda_version – Lambda Function Version to use.
• refresh_auth_lambda_version – Lambda Function Version to use.
• sign_out_lambda_version – Lambda Function Version to use.
Returns The CloudFront Distribution Options.
runway.blueprints.staticsite.dependencies module
Module with static website supporting infrastructure.
class runway.blueprints.staticsite.dependencies.Dependencies(name, con-
text, map-
pings=None, de-
scription=None)
Bases: runway.cfngin.blueprints.base.Blueprint
Stacker blueprint for creating static website buckets.
Instantiate class.
Parameters
• name (str) – A name for the blueprint.
• context (runway.cfngin.context.Context) – Context the blueprint is being ex-
ecuted under.
• mappings (dict, optional) – CloudFormation Mappings to be used in the template.
• description (str) – Used to describe the resulting CloudFormation template.
VARIABLES = {'AdditionalRedirectDomains': {'default': [], 'description': '(Optional) AppClient callback/logout domains (in addition to the Aliases)', 'type': <class 'list'>}, 'Aliases': {'default': [], 'description': '(Optional) Domain aliases for the distribution', 'type': <class 'list'>}, 'AuthAtEdge': {'default': False, 'description': 'Utilizing Authorization @ Edge', 'type': <class 'bool'>}, 'CreateUserPool': {'default': False, 'description': 'Whether a User Pool should be created for the project', 'type': <class 'bool'>}, 'OAuthScopes': {'default': ['phone', 'email', 'profile', 'openid', 'aws.cognito.signin.user.admin'], 'description': 'The allowed scopes for OAuth validation', 'type': <class 'list'>}, 'RedirectPathSignIn': {'default': '/parseauth', 'description': 'Auth@Edge redirect sign in path', 'type': <class 'str'>}, 'RedirectPathSignOut': {'default': '/', 'description': 'Auth@Edge redirect sign out path', 'type': <class 'str'>}, 'SupportedIdentityProviders': {'default': [], 'description': 'Auth@Edge AppClient Identity Providers', 'type': <class 'list'>}}
create_template()
Create template (main function called by Stacker).
192 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
runway.blueprints.staticsite.staticsite module
Module with static website bucket and CloudFront distribution.
class runway.blueprints.staticsite.staticsite.StaticSite(name, context, map-
pings=None, descrip-
tion=None)
Bases: runway.cfngin.blueprints.base.Blueprint
CFNgin blueprint for creating S3 bucket and CloudFront distribution.
Instantiate class.
Parameters
• name (str) – A name for the blueprint.
• context (runway.cfngin.context.Context) – Context the blueprint is being ex-
ecuted under.
• mappings (dict, optional) – CloudFormation Mappings to be used in the template.
• description (str) – Used to describe the resulting CloudFormation template.
VARIABLES = {'AcmCertificateArn': {'default': '', 'description': '(Optional) Cert ARN for site', 'type': <class 'str'>}, 'Aliases': {'default': [], 'description': '(Optional) Domain aliases the distribution', 'type': <class 'list'>}, 'DisableCloudFront': {'default': False, 'description': 'Whether to disable CF', 'type': <class 'bool'>}, 'LogBucketName': {'default': '', 'description': 'S3 bucket for CF logs', 'type': <class 'str'>}, 'PriceClass': {'default': 'PriceClass_100', 'description': 'CF price class for the distribution.', 'type': <class 'str'>}, 'RewriteDirectoryIndex': {'default': '', 'description': '(Optional) File name to append to directory requests.', 'type': <class 'str'>}, 'RoleBoundaryArn': {'default': '', 'description': '(Optional) IAM Role permissions boundary applied to any created roles.', 'type': <class 'str'>}, 'WAFWebACL': {'default': '', 'description': '(Optional) WAF id to associate with the distribution.', 'type': <class 'str'>}, 'custom_error_responses': {'default': [], 'description': '(Optional) Custom error responses.', 'type': <class 'list'>}, 'lambda_function_associations': {'default': [], 'description': '(Optional) Lambda function associations.', 'type': <class 'list'>}}
property aliases_specified
Aliases are specified conditional.
property cf_enabled
CloudFront enabled conditional.
property acm_certificate_specified
ACM Certification specified conditional.
property cf_logging_enabled
CloudFront Logging specified conditional.
property directory_index_specified
Directory Index specified conditional.
property role_boundary_specified
IAM Role Boundary specified conditional.
property waf_name_specified
WAF name specified conditional.
create_template()
Create template (main function called by CFNgin).
get_lambda_associations()
Retrieve any lambda associations from the instance variables.
Returns List of Lambda Function association variables
get_directory_index_lambda_association(lambda_associations, direc-
tory_index_rewrite_version)
Retrieve the directory index lambda associations with the added rewriter.
Parameters
• lambda_associations – The lambda associations.
• directory_index_rewrite_version – The directory index rewrite version.
9.6. Terraform 193
runway Documentation, Release 1.18.3
get_cloudfront_distribution_options(bucket, oai, lambda_function_associations)
Retrieve the options for our CloudFront distribution.
Parameters
• bucket – The bucket resource
• oai – The origin access identity resource.
• lambda_function_associations – List of Lambda Function associations.
Returns The CloudFront Distribution Options.
add_aliases()
Add aliases.
add_web_acl()
Add Web ACL.
add_logging_bucket()
Add Logging Bucket.
add_acm_cert()
Add ACM cert.
add_origin_access_identity()
Add the origin access identity resource to the template.
Returns The OAI resource
add_bucket_policy(bucket)
Add a policy to the bucket if CloudFront is disabled. Ensure PublicRead.
Parameters bucket – The bucket resource to place the policy.
Returns The Bucket Policy Resource.
add_bucket()
Add the bucket resource along with an output of it’s name / website url.
Returns The bucket resource.
add_cloudfront_bucket_policy(bucket, oai)
Given a bucket and oai resource add cloudfront access to the bucket.
Keyword Arguments
• bucket – A bucket resource.
• oai – An Origin Access Identity resource.
Returns The CloudFront Bucket access resource.
add_lambda_execution_role(name='LambdaExecutionRole', function_name='')
Create the Lambda@Edge execution role.
Parameters
• name – Name for the Lambda Execution Role.
• function_name – Name of the Lambda Function the Role will be attached to.
add_cloudfront_directory_index_rewrite(role)
Add an index CloudFront directory index rewrite lambda function to the template.
Keyword Arguments role – The index rewrite role resource.
Returns The CloudFront directory index rewrite lambda function resource.
194 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
add_cloudfront_directory_index_rewrite_version(directory_index_rewrite)
Add a specific version to the directory index rewrite lambda.
Parameters directory_index_rewrite (dict) – The directory index rewrite lambda
resource.
Returns The CloudFront directory index rewrite version.
Return type dict
add_cloudfront_distribution(bucket_policy, cloudfront_distribution_options)
Add the CloudFront distribution to the template / output the id and domain name.
Parameters
• bucket_policy (dict) – Bucket policy to allow CloudFront access.
• cloudfront_distribution_options (dict) – The distribution options.
Returns The CloudFront Distribution resource
Return type dict
runway.cfngin package
Import modules.
class runway.cfngin.CFNgin(ctx, parameters=None, sys_path=None)
Bases: object
Control CFNgin.
EXCLUDE_REGEX
Regex used to exclude YAML files when searching for config files.
Type str
EXCLUDE_LIST
Global list of YAML file names to exclude when searching for config files.
Type str
concurrency
Max number of CFNgin stacks that can be deployed concurrently. If the value is 0, will be constrained
based on the underlying graph.
Type int
interactive
Wether or not to prompt the user before taking action.
Type bool
parameters
Combination of the parameters provided when initalizing the class and any environment files that are
found.
Type MutableMap
recreate_failed
Destroy and re-create stacks that are stuck in a failed state from an initial deployment when updating.
Type bool
9.6. Terraform 195
runway Documentation, Release 1.18.3
region
The AWS region where CFNgin is currently being executed.
Type str
sys_path
Working directory.
Type str
tail
Wether or not to display all CloudFormation events in the terminal.
Type bool
Instantiate class.
Parameters
• ctx (runway.context.Context) – Runway context object.
• parameters (Optional[Dict[str. Any]]) – Parameters from Runway.
• sys_path (Optional[str]) – Working directory.
EXCLUDE_LIST = ['bitbucket-pipelines.yml', 'buildspec.yml', 'docker-compose.yml']
EXCLUDE_REGEX = 'runway(\\..
*
)?\\.(yml|yaml)'
deploy(force=False, sys_path=None)
Run the CFNgin deploy action.
Parameters
• force (bool) – Explicitly enable the action even if an environment file is not found.
• sys_path (Optional[str]) – Explicitly define a path to work in. If not provided,
self.sys_path is used.
destroy(force=False, sys_path=None)
Run the CFNgin destroy action.
Parameters
• force (bool) – Explicitly enable the action even if an environment file is not found.
• sys_path (Optional[str]) – Explicitly define a path to work in. If not provided,
self.sys_path is used.
env_file
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
classmethod find_config_files(exclude=None, sys_path=None)
Find CFNgin config files.
Parameters
• exclude (Optional[List[str]]) – List of file names to exclude. This list is ap-
pended to the global exclude list.
• sys_path (Optional[str]) – Explicitly define a path to search for config files.
Returns Path to config files that were found.
196 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Return type List[str]
load(config_path)
Load a CFNgin config into a context object.
Parameters config_path (str) – Valid path to a CFNgin config file.
Returns runway.cfngin.context.Context
plan(force=False, sys_path=None)
Run the CFNgin plan action.
Parameters
• force (bool) – Explicitly enable the action even if an environment file is not found.
• sys_path (Optional[str]) – Explicitly define a path to work in. If not provided,
self.sys_path is used.
should_skip(force=False)
Determine if action should be taken or not.
Parameters force (bool) – If True, will always return False meaning the action should
not be skipped.
Returns Skip action or not.
Return type bool
Submodules
runway.cfngin.awscli_yamlhelper module
Copy of awscli.customizations.cloudformation.yamlhelper.py.
runway.cfngin.awscli_yamlhelper.intrinsics_multi_constructor(loader, tag_prefix,
node)
YAML constructor to parse CloudFormation intrinsics.
This will return a dictionary with key being the intrinsic name
runway.cfngin.awscli_yamlhelper.yaml_dump(dict_to_dump)
Dump the dictionary as a YAML document.
runway.cfngin.awscli_yamlhelper.yaml_parse(yamlstr)
Parse a yaml string.
runway.cfngin.cfngin module
CFNgin entrypoint.
class runway.cfngin.cfngin.CFNgin(ctx, parameters=None, sys_path=None)
Bases: object
Control CFNgin.
EXCLUDE_REGEX
Regex used to exclude YAML files when searching for config files.
Type str
9.6. Terraform 197
runway Documentation, Release 1.18.3
EXCLUDE_LIST
Global list of YAML file names to exclude when searching for config files.
Type str
concurrency
Max number of CFNgin stacks that can be deployed concurrently. If the value is 0, will be constrained
based on the underlying graph.
Type int
interactive
Wether or not to prompt the user before taking action.
Type bool
parameters
Combination of the parameters provided when initalizing the class and any environment files that are
found.
Type MutableMap
recreate_failed
Destroy and re-create stacks that are stuck in a failed state from an initial deployment when updating.
Type bool
region
The AWS region where CFNgin is currently being executed.
Type str
sys_path
Working directory.
Type str
tail
Wether or not to display all CloudFormation events in the terminal.
Type bool
Instantiate class.
Parameters
• ctx (runway.context.Context) – Runway context object.
• parameters (Optional[Dict[str. Any]]) – Parameters from Runway.
• sys_path (Optional[str]) – Working directory.
EXCLUDE_REGEX = 'runway(\\..
*
)?\\.(yml|yaml)'
EXCLUDE_LIST = ['bitbucket-pipelines.yml', 'buildspec.yml', 'docker-compose.yml']
env_file
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
deploy(force=False, sys_path=None)
Run the CFNgin deploy action.
Parameters
198 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
• force (bool) – Explicitly enable the action even if an environment file is not found.
• sys_path (Optional[str]) – Explicitly define a path to work in. If not provided,
self.sys_path is used.
destroy(force=False, sys_path=None)
Run the CFNgin destroy action.
Parameters
• force (bool) – Explicitly enable the action even if an environment file is not found.
• sys_path (Optional[str]) – Explicitly define a path to work in. If not provided,
self.sys_path is used.
load(config_path)
Load a CFNgin config into a context object.
Parameters config_path (str) – Valid path to a CFNgin config file.
Returns runway.cfngin.context.Context
plan(force=False, sys_path=None)
Run the CFNgin plan action.
Parameters
• force (bool) – Explicitly enable the action even if an environment file is not found.
• sys_path (Optional[str]) – Explicitly define a path to work in. If not provided,
self.sys_path is used.
should_skip(force=False)
Determine if action should be taken or not.
Parameters force (bool) – If True, will always return False meaning the action should
not be skipped.
Returns Skip action or not.
Return type bool
classmethod find_config_files(exclude=None, sys_path=None)
Find CFNgin config files.
Parameters
• exclude (Optional[List[str]]) – List of file names to exclude. This list is ap-
pended to the global exclude list.
• sys_path (Optional[str]) – Explicitly define a path to search for config files.
Returns Path to config files that were found.
Return type List[str]
9.6. Terraform 199
runway Documentation, Release 1.18.3
runway.cfngin.context module
CFNgin context.
runway.cfngin.context.get_fqn(base_fqn, delimiter, name=None)
Return the fully qualified name of an object within this context.
If the name passed already appears to be a fully qualified name, it will be returned with no further processing.
class runway.cfngin.context.Context(environment=None, boto3_credentials=None,
stack_names=None, config=None, config_path=None,
region=None, force_stacks=None)
Bases: object
The context under which the current stacks are being executed.
The CFNgin Context is responsible for translating the values passed in via the command line and specified in
the config to Stack objects.
Instantiate class.
Parameters
• boto3_credentials (Optional[Dict[str, str]]) – Credentials to use when
creating a boto3 session from context.
• environment (dict) – A dictionary used to pass in information about the environment.
Useful for templating.
• stack_names (list) – A list of stack_names to operate on. If not passed, usually all
stacks defined in the config will be operated on.
• config (runway.cfngin.config.Config) – The CFNgin configuration being op-
erated on.
• config_path (str) – Path to the config file that was provided.
• region (str) – Name of an AWS region if provided as a CLI argument.
• force_stacks (list) – A list of stacks to force work on. Used to work on locked
stacks.
property bucket_name
Return cfngin_bucket from config, calculated name, or None.
property mappings
Return mappings from config.
property namespace
Return namespace from config.
property namespace_delimiter
Return namespace_delimiter from config or default.
property persistent_graph
Graph if a persistent graph is being used.
Will create an “empty” object in S3 if one is not found.
Returns runway.cfngin.plan.Graph
property persistent_graph_location
Location of the persistent graph in s3.
Returns Dict[str, str] Bucket and Key for the object in S3.
200 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
property persistent_graph_lock_code
Code used to lock the persistent graph S3 object.
Returns Optional[str]
property persistent_graph_locked
Check if persistent graph is locked.
Returns bool
property s3_bucket_verified
Check CFNgin bucket exists and you have access.
If the CFNgin bucket does not exist, will try to create one.
Returns bool
property tags
Return tags from config.
property template_indent
Return template_indent from config or default.
property upload_to_s3
Check if S3 should be used for caching/persistent graph.
Returns (bool)
get_targets()
Return the named targets that are specified in the config.
Returns a list of runway.cfngin.target.Target objects
Return type list
get_session(profile=None, region=None)
Create a thread-safe boto3 session.
Parameters
• profile (Optional[str]) – The profile for the session.
• region (Optional[str]) – The region for the session.
Returns A thread-safe boto3 session.
Return type boto3.session.Session
get_stack(name)
Get a stack by name.
Parameters name (str) – Name of a stack to retrieve.
get_stacks()
Get the stacks for the current action.
Handles configuring the runway.cfngin.stack.Stack objects that will be used in the current ac-
tion.
Returns a list of runway.cfngin.stack.Stack objects
Return type list
get_stacks_dict()
Construct a dict of {stack.fqn: stack} for easy access to stacks.
9.6. Terraform 201
runway Documentation, Release 1.18.3
get_fqn(name=None)
Return the fully qualified name of an object within this context.
If the name passed already appears to be a fully qualified name, it will be returned with no further process-
ing.
lock_persistent_graph(lock_code)
Locks the persistent graph in s3.
Parameters lock_code (str) – The code that will be used to lock the S3 object.
Raises
• runway.cfngin.exceptions.PersistentGraphLocked –
• runway.cfngin.exceptions.PersistentGraphCannotLock –
put_persistent_graph(lock_code)
Upload persistent graph to s3.
Parameters lock_code (str) – The code that will be used to lock the S3 object.
Raises
• runway.cfngin.exceptions.PersistentGraphUnlocked –
• runway.cfngin.exceptions.PersistentGraphLockCodeMissmatch –
set_hook_data(key, data)
Set hook data for the given key.
Parameters
• key (str) – The key to store the hook data in.
• data (collections.Mapping) – A dictionary of data to store, as returned from a
hook.
unlock_persistent_graph(lock_code)
Unlocks the persistent graph in s3.
Parameters lock_code (str) – The code that will be used to lock the S3 object.
Raises runway.cfngin.exceptions.PersistentGraphCannotUnlock –
runway.cfngin.environment module
CFNgin environment file parsing.
runway.cfngin.environment.parse_environment(raw_environment)
Parse environment file contents.
Parameters raw_environment (str) – Environment file read into a string.
Returns Dict[str, Any]
202 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
runway.cfngin.exceptions module
CFNgin exceptions.
exception runway.cfngin.exceptions.CancelExecution
Bases: Exception
Raised when we want to cancel executing the plan.
exception runway.cfngin.exceptions.ChangesetDidNotStabilize(change_set_id)
Bases: Exception
Raised when the applying a changeset fails.
Instantiate class.
Parameters change_set_id (str) – The changeset that failed.
exception runway.cfngin.exceptions.FailedLookup(lookup, error, *args, **kwargs)
Bases: Exception
Intermediary Exception to be converted to FailedVariableLookup.
Should be caught by error handling and runway.cfngin.exceptions.FailedVariableLookup
raised instead to construct a propper error message.
Instantiate class.
Parameters
• lookup (runway.cfngin.variables.VariableValueLookup) – Attempted
lookup and resulted in an exception being raised.
• error (Exception) – The exception that was raised.
exception runway.cfngin.exceptions.FailedVariableLookup(variable_name, lookup, er-
ror, *args, **kwargs)
Bases: Exception
Lookup could not be resolved.
Raised when an exception is raised when trying to resolve a lookup.
Instantiate class.
Parameters
• variable_name (str) – Name of the variable that failed to be resolved.
• lookup (runway.cfngin.variables.VariableValueLookup) – Attempted
lookup and resulted in an exception being raised.
• error (Exception) – The exception that was raised.
exception runway.cfngin.exceptions.GraphError(exception, stack, dependency)
Bases: Exception
Raised when the graph is invalid (e.g. acyclic dependencies).
Instantiate class.
Parameters
• exception (Exception) – The exception that was raised by the invalid graph.
• stack (str) – Name of the stack causing the error.
• dependency (str) – Name of the dependency causing the error.
9.6. Terraform 203
runway Documentation, Release 1.18.3
exception runway.cfngin.exceptions.ImproperlyConfigured(cls, error, *args,
**kwargs)
Bases: Exception
Raised when a componenet is improperly configured.
Instantiate class.
Parameters
• cls (Any) – The class that was improperly configured.
• error (Exception) – The exception that was raised when trying to use cls.
exception runway.cfngin.exceptions.InvalidConfig(errors)
Bases: Exception
Provided config file is invalid.
Instantiate class.
Parameters errors (Union[str, List[Union[Exception, str]]]) – Errors or error
messages that are raised to identify that a config is invalid.
exception runway.cfngin.exceptions.InvalidDockerizePipConfiguration(msg)
Bases: Exception
Raised when the provided configuration for dockerized pip is invalid.
Instantiate class.
Parameters msg (str) – The reason for the error being raised.
exception runway.cfngin.exceptions.InvalidLookupCombination(lookup, lookups,
value, *args,
**kwargs)
Bases: Exception
Improper use of lookups to result in a non-string return value.
Instantiate class.
Parameters
• lookup (runway.cfngin.variables.VariableValueLookup) – The variable
lookup that was attempted but did not return a string.
• lookups (runway.cfngin.variables.VariableValueConcatenation) –
The full variable concatenation the failing lookup is part of.
• value (Any) – The non-string value returned by lookup.
exception runway.cfngin.exceptions.InvalidLookupConcatenation(lookup, lookups,
*args, **kwargs)
Bases: Exception
Intermediary Exception to be converted to InvalidLookupCombination.
Should be caught by error handling and runway.cfngin.exceptions.
InvalidLookupCombination raised instead to construct a propper error message.
Instantiate class.
204 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
exception runway.cfngin.exceptions.InvalidUserdataPlaceholder(blueprint_name,
excep-
tion_message,
*args, **kwargs)
Bases: Exception
Raised when a placeholder name in raw_user_data is not valid.
E.g ${100} would raise this.
Instantiate class.
Parameters
• blueprint_name (str) – Name of the blueprint with invalid userdata placeholder.
• exception_message (str) – Message from the exception that was raised while parsing
the userdata.
exception runway.cfngin.exceptions.MissingEnvironment(key, *args, **kwargs)
Bases: Exception
Raised when an environment lookup is used but the key doesn’t exist.
Instantiate class.
Parameters
• key (str) – The key that was used but doesn’t exist in the
• environment. –
exception runway.cfngin.exceptions.MissingParameterException(parameters, *args,
**kwargs)
Bases: Exception
Raised if a required parameter with no default is missing.
Instantiate class.
Parameters parameters (List[str]) – A list of the parameters that are missing.
exception runway.cfngin.exceptions.MissingVariable(blueprint_name, variable_name,
*args, **kwargs)
Bases: Exception
Raised when a variable with no default is not provided a value.
Instantiate class.
Parameters
• blueprint_name (str) – Name of the blueprint.
• variable_name (str) – Name of the variable missing a value.
exception runway.cfngin.exceptions.OutputDoesNotExist(stack_name, output, *args,
**kwargs)
Bases: Exception
Raised when a specific stack output does not exist.
Instantiate class.
Parameters
• stack_name (str) – Name of the stack.
• output (str) – The output that does not exist.
9.6. Terraform 205
runway Documentation, Release 1.18.3
exception runway.cfngin.exceptions.PipError
Bases: Exception
Raised when pip returns a non-zero exit code.
Instantiate class.
exception runway.cfngin.exceptions.PipenvError
Bases: Exception
Raised when pipenv returns a non-zero exit code.
Instantiate class.
exception runway.cfngin.exceptions.PersistentGraphCannotLock(reason)
Bases: Exception
Raised when the persistent graph in S3 cannot be locked.
Instantiate class.
exception runway.cfngin.exceptions.PersistentGraphCannotUnlock(reason)
Bases: Exception
Raised when the persistent graph in S3 cannot be unlocked.
Instantiate class.
exception runway.cfngin.exceptions.PersistentGraphLocked(message=None, rea-
son=None)
Bases: Exception
Raised when the persistent graph in S3 is lock.
The action being executed requires it to be unlocked before attempted.
Instantiate class.
exception runway.cfngin.exceptions.PersistentGraphLockCodeMissmatch(provided_code,
s3_code)
Bases: Exception
Raised when the provided persistent graph lock code does not match.
The code used to unlock the persistent graph must match the s3 object lock code.
Instantiate class.
exception runway.cfngin.exceptions.PersistentGraphUnlocked(message=None, rea-
son=None)
Bases: Exception
Raised when the persistent graph in S3 is unlock.
The action being executed requires it to be locked before attempted.
Instantiate class.
exception runway.cfngin.exceptions.PlanFailed(failed_steps, *args, **kwargs)
Bases: Exception
Raised if any step of a plan fails.
Instantiate class.
Parameters failed_steps (List[runway.cfngin.plan.Step]) – The steps that failed.
206 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
exception runway.cfngin.exceptions.StackDidNotChange
Bases: Exception
Raised when there are no changes to be made by the provider.
exception runway.cfngin.exceptions.StackDoesNotExist(stack_name, *args, **kwargs)
Bases: Exception
Raised when a stack does not exist in AWS.
Instantiate class.
Parameters stack_name (str) – Name of the stack that does not exist.
exception runway.cfngin.exceptions.StackUpdateBadStatus(stack_name, stack_status,
reason, *args, **kwargs)
Bases: Exception
Raised if the state of a stack can’t be handled.
Instantiate class.
Parameters
• stack_name (str) – Name of the stack.
• stack_status (str) – The stack’s status.
• reason (str) – The reason for the current status.
exception runway.cfngin.exceptions.StackFailed(stack_name, status_reason=None)
Bases: Exception
Raised when a stack action fails.
Primarily used with hooks that act on stacks.
Instantiate class.
Parameters
• stack_name (str) – Name of the stack.
• status_reason (str) – The reason for the current status.
exception runway.cfngin.exceptions.UnableToExecuteChangeSet(stack_name,
change_set_id,
execution_status)
Bases: Exception
Raised if changeset execution status is not AVAILABLE.
Instantiate class.
Parameters
• stack_name (str) – Name of the stack.
• change_set_id (str) – The changeset that failed.
• execution_status (str) – The value of the changeset’s ExecutionStatus at-
tribute.
exception runway.cfngin.exceptions.UnhandledChangeSetStatus(stack_name,
change_set_id, sta-
tus, status_reason)
Bases: Exception
Raised when creating a changeset failed for an unhandled reason.
9.6. Terraform 207
runway Documentation, Release 1.18.3
Handled failure reasons include: no changes
Instantiate class.
Parameters
• stack_name (str) – Name of the stack.
• change_set_id (str) – The changeset that failed.
• status (str) – The state that could not be handled.
• status_reason (str) – Cause of the current state.
exception runway.cfngin.exceptions.UnknownLookupType(lookup_type, *args, **kwargs)
Bases: Exception
Lookup type provided does not match a registered lookup.
Example
If a lookup of ${<lookup_type> query} is used and <lookup_type> is not a registered lookup, this
exception will be raised.
Instantiate class.
Parameters lookup_type (str) – Lookup type that was used but not registered.
exception runway.cfngin.exceptions.UnresolvedVariable(blueprint_name, variable,
*args, **kwargs)
Bases: Exception
Raised when trying to use a variable before it has been resolved.
Instantiate class.
Parameters
• blueprint_name (str) – Name of the blueprint that tried to use the unresolved vari-
ables.
• variable (runway.cfngin.variables.Variable) – The unresolved variable.
exception runway.cfngin.exceptions.UnresolvedVariableValue(lookup, *args,
**kwargs)
Bases: Exception
Intermediary Exception to be converted to UnresolvedVariable.
Should be caught by error handling and runway.cfngin.exceptions.UnresolvedVariable raised
instead to construct a propper error message.
Instantiate class.
Parameters lookup (runway.cfngin.variables.VariableValueLookup) – The
lookup that is not resolved.
exception runway.cfngin.exceptions.UnresolvedVariables(blueprint_name, *args,
**kwargs)
Bases: Exception
Raised when trying to use variables before they has been resolved.
Instantiate class.
208 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Parameters blueprint_name (str) – Name of the blueprint that tried to use the unresolved
variables.
exception runway.cfngin.exceptions.ValidatorError(variable, validator, value, excep-
tion=None)
Bases: Exception
Used for errors raised by custom validators of blueprint variables.
Instantiate class.
Parameters
• variable (str) – The variable that failed validation.
• validator (str) – The validator that was not passed.
• value (str) – The value of the variable that did not pass the validator.
• exception (Exception) – The exception raised by the validator.
exception runway.cfngin.exceptions.VariableTypeRequired(blueprint_name, vari-
able_name, *args,
**kwargs)
Bases: Exception
Raised when a variable defined in a blueprint is missing a type.
Instantiate class.
Parameters
• blueprint_name (str) – Name of the blueprint.
• variable_name (str) – Name of the variable missing a type.
runway.cfngin.plan module
CFNgin plan, plan componenets, and functions for interacting with a plan.
runway.cfngin.plan.json_serial(obj)
Serialize json.
Parameters obj (Any) – A python object.
Example
json.dumps(data, default=json_serial)
runway.cfngin.plan.merge_graphs(graph1, graph2)
Combine two Graphs into one, retaining steps.
Parameters
• graph1 (Graph) – Graph that graph2 will be merged into.
• graph2 (Graph) – Graph that will be merged into graph1.
Returns A combined graph.
Return type Graph
9.6. Terraform 209
runway Documentation, Release 1.18.3
class runway.cfngin.plan.Step(stack, fn=None, watch_func=None)
Bases: object
State machine for executing generic actions related to stacks.
fn
Function to run to execute the step. This function will be ran multiple times until the step is “done”.
Type Optional[Callable]
last_updated
Time when the step was last updated.
Type float
logger
Logger for logging messages about the step.
Type logging.LoggerAdaptor
stack
the stack associated with this step
Type runway.cfngin.stack.Stack
status
The status of step.
Type runway.cfngin.status.Status
watch_func
Function that will be called to “tail” the step action.
Type Optional[Callable]
Instantiate class.
Parameters
• stack (runway.cfngin.stack.Stack) – The stack associated with this step
• fn (Optional[Callable]) – Function to run to execute the step. This function will be
ran multiple times until the step is “done”.
• watch_func (Optional[Callable]) – Function that will be called to “tail” the step
action.
run()
Run this step until it has completed or been skipped.
Returns bool
property name
Name of the step.
This is equal to the name of the stack it operates on.
Returns str
property requires
Return a list of step names this step depends on.
Returns List[str]
property required_by
Return a list of step names that depend on this step.
210 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Returns List[str]
property completed
Return True if the step is in a COMPLETE state.
Returns bool
property skipped
Return True if the step is in a SKIPPED state.
Returns bool
property failed
Return True if the step is in a FAILED state.
Returns bool
property done
Return True if the step is finished.
To be True, status must be either COMPLETE, SKIPPED or FAILED)
Returns bool
property ok
Return True if the step is finished (either COMPLETE or SKIPPED).
Returns bool
property submitted
Return True if the step is SUBMITTED, COMPLETE, or SKIPPED.
Returns bool
set_status(status)
Set the current step’s status.
Parameters status (runway.cfngin.status.Status) – The status to set the step to.
complete()
Shortcut for set_status(COMPLETE).
log_step()
Construct a log message for a set and log it to the UI.
skip()
Shortcut for set_status(SKIPPED).
submit()
Shortcut for set_status(SUBMITTED).
classmethod from_stack_name(stack_name, context, requires=None, fn=None,
watch_func=None)
Create a step using only a stack name.
Parameters
• stack_name (str) – Name of a CloudFormation stack.
• context (runway.cfngin.context.Context) – Context object. Required to
initialize a “fake” runway.cfngin.stack.Stack.
• requires (List[str]) – Stacks that this stack depends on.
• fn (Callable) – The function to run to execute the step. This function will be ran
multiple times until the step is “done”.
9.6. Terraform 211
runway Documentation, Release 1.18.3
• watch_func (Callable) – an optional function that will be called to “tail” the step
action.
Returns Step
classmethod from_persistent_graph(graph_dict, context, fn=None, watch_func=None)
Create a steps for a persistent graph dict.
Parameters
• graph_dict (Dict[str, List[str]]) – A graph dict.
• context (runway.cfngin.context.Context) – Context object. Required to
initialize a “fake” runway.cfngin.stack.Stack.
• requires (List[str]) – Stacks that this stack depends on.
• fn (Callable) – The function to run to execute the step. This function will be ran
multiple times until the step is “done”.
• watch_func (Callable) – an optional function that will be called to “tail” the step
action.
Returns List[Step]
class runway.cfngin.plan.Graph(steps=None, dag=None)
Bases: object
Graph represents a graph of steps.
The Graph helps organize the steps needed to execute a particular action for a set of runway.cfngin.
stack.Stack objects. When initialized with a set of steps, it will first build a Directed Acyclic Graph from
the steps and their dependencies.
dag
an optional runway.cfngin.dag.DAG object. If one is not provided, a new one will be initialized.
Type runway.cfngin.dag.DAG
steps
Dict with key of step name and value of Step.
Type Dict[str, Step]
Example:
>>> dag = DAG()
>>> a = Step("a", fn=build)
>>> b = Step("b", fn=build)
>>> dag.add_step(a)
>>> dag.add_step(b)
>>> dag.connect(a, b)
Instantiate class.
Parameters
• steps (Optional[Dict[str, Step]]) – Dict with key of step name and value of Step for
steps to initialize the Graph with. Note that if this is provided, a pre-configured runway.
cfngin.dag.DAG that already includes these steps should also be provided..
• dag (Optional[runway.cfngin.dag.DAG]) – An optional runway.cfngin.dag.
DAG object. If one is not provided, a new one will be initialized.
212 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
add_step(step, add_dependencies=False, add_dependants=False)
Add a step to the graph.
Parameters
• step (Step) – The step to be added.
• add_dependencies (bool) – Connect steps that need to be completed before this
step.
• add_dependants (bool) – Connect steps that require this step.
add_step_if_not_exists(step, add_dependencies=False, add_dependants=False)
Try to add a step to the graph.
Can be used when failure to add is acceptable.
Parameters
• step (Step) – The step to be added.
• add_dependencies (bool) – Connect steps that need to be completed before this
step.
• add_dependants (bool) – Connect steps that require this step.
add_steps(steps)
Add a list of steps.
Parameters steps (List[Step]) – The step to be added.
pop(step, default=None)
Remove a step from the graph.
Parameters
• step (Step) – The step to remove from the graph.
• default (Any) – Returned if the step could not be popped
Returns Any
connect(step, dep)
Connect a dependency to a step.
Parameters
• step (str) – Step name to add a dependency to.
• dep (str) – Name of dependent step.
transitive_reduction()
Perform a transitive reduction on the underlying DAG.
The transitive reduction of a graph is a graph with as few edges as possible with the same reachability as
the original graph.
See https://en.wikipedia.org/wiki/Transitive_reduction
walk(walker, walk_func)
Walk the steps of the graph.
Parameters
• walker (Callable[[runway.cfngin.dag.DAG], Any]) – Function used to walk the
steps.
9.6. Terraform 213
runway Documentation, Release 1.18.3
• walk_func (Callable[[Step], Any]) – Function called with a Step as the only argu-
ment for each step of the plan.
downstream(step_name)
Return the direct dependencies of the given step.
transposed()
Return a “transposed” version of this graph.
Useful for walking in reverse.
filtered(step_names)
Return a “filtered” version of this graph.
Parameters step_names (List[str]) – Steps to filter.
topological_sort()
Perform a topological sort of the underlying DAG.
Returns List[Step]
to_dict()
Return the underlying DAG as a dictionary.
dumps(indent=None)
Output the graph as a json seralized string for storage.
Parameters indent (Optional[int]) – Number of spaces for each indentation.
Returns str
classmethod from_dict(graph_dict, context)
Create a Graph from a graph dict.
Parameters
• graph_dict (Dict[str, List[str]]) – The dictionary used to create the graph.
• context (runway.cfngin.context.Context) – Required to init stacks.
Returns Graph
classmethod from_steps(steps)
Create a Graph from Steps.
Parameters steps (List[Step]) – Steps used to create the graph.
Returns Graph
class runway.cfngin.plan.Plan(description, graph, context=None, reverse=False, re-
quire_unlocked=True)
Bases: object
A convenience class for working on a Graph.
context
Context object.
Type runway.cfngin.context.Context
description
Plan description.
Type str
graph
Graph of the plan.
214 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Type Graph
id
UUID for the plan.
Type str
reverse
The graph has been transposed for walking in reverse.
Type bool
require_unlocked
Require the persistent graph to be unlocked before executing steps.
Type bool
Initialize class.
Parameters
• description (str) – Description of what the plan is going to do.
• graph (Graph) – Local graph used for the plan.
• context (runway.cfngin.context.Context) – Context object.
• reverse (bool) – Transpose the graph for walking in reverse.
• require_unlocked (bool) – Require the persistent graph to be unlocked before exe-
cuting steps.
outline(level=20, message='')
Print an outline of the actions the plan is going to take.
The outline will represent the rough ordering of the steps that will be taken.
Parameters
• level (Optional[int]) – a valid log level that should be used to log the outline
• message (Optional[str]) – a message that will be logged to the user after the out-
line has been logged.
dump(directory, context, provider=None)
Output the rendered blueprint for all stacks in the plan.
Parameters
• directory (str) – Directory where files will be created.
• context (runway.cfngin.context.Contest) – Current CFNgin context.
• provider (runway.cfngin.providers.aws.default.Provider) –
Provider to use when resolving the blueprints.
execute(*args, **kwargs)
Walk each step in the underlying graph.
Raises
• PersistentGraphLocked – Raised if the persistent graph is locked prior to execution
and this session did not lock it.
• PlanFailed – Raised if any of the steps fail.
walk(walker)
Walk each step in the underlying graph, in topological order.
9.6. Terraform 215
runway Documentation, Release 1.18.3
Parameters walker (func) – a walker function to be passed to runway.cfngin.dag.
DAG to walk the graph.
property lock_code
Code to lock/unlock the persistent graph.
Returns str
property steps
Return a list of all steps in the plan.
Returns List[Step]
property step_names
Return a list of all step names.
Returns List[str]
keys()
Return a list of all step names.
Returns List[str]
runway.cfngin.session_cache module
CFNgin session caching.
runway.cfngin.session_cache.get_session(region=None, profile=None, access_key=None, se-
cret_key=None, session_token=None)
Create a thread-safe boto3 session.
Parameters
• region (Optional[str]) – The region for the session.
• profile (Optional[str]) – The profile for the session.
• access_key (Optional[str]) – AWS Access Key ID.
• secret_key (Optional[str]) – AWS secret Access Key.
• session_token (Optional[str]) – AWS session token.
Returns A thread-safe boto3 session.
Return type boto3.session.Session
runway.cfngin.stack module
CFNgin stack.
class runway.cfngin.stack.Stack(definition, context, variables=None, mappings=None,
locked=False, force=False, enabled=True, protected=False)
Bases: object
Represents gathered information about a stack to be built/updated.
definition
The stack definition from the config.
Type runway.cfngin.config.Stack
216 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
enabled
Whether this stack is enabled
Type bool
force
Whether to force updates on this stack.
Type bool
fqn
Fully qualified name of the stack. Combines the stack name and current namespace.
Type str
in_progress_behavior
The behavior for when a stack is in CREATE_IN_PROGRESS or UPDATE_IN_PROGRESS.
Type Optional[str]
locked
Whether or not the stack is locked.
Type bool
logging
Whether logging is enabled.
Type bool
mappings
Cloudformation mappings passed to the blueprint.
Type Optional[Dict[str, Dict[str, Any]]]
name
Name of the stack taken from the definition.
Type str
outputs
CloudFormation Stack outputs
Type Optional[Dict[str, Any]]
profile
Profile name from the stack definition.
Type str
protected
Whether this stack is protected.
Type bool
region
AWS region name.
Type str
termination_protection
The state of termination protection to apply to the stack.
Type bool
variables
Variables for the stack.
9.6. Terraform 217
runway Documentation, Release 1.18.3
Type Optional[Dict[str, Any]]
Instantiate class.
Parameters
• definition (runway.cfngin.config.Stack) – A stack definition.
• context (runway.cfngin.context.Context) – Current context for building the
stack.
• variables (Optional[Dict[str, Any]]) – Variables for the stack.
• mappings (Optional[Dict[str, Dict[str, Any]]]) – Cloudformation map-
pings passed to the blueprint.
• locked (bool) – Whether or not the stack is locked.
• force (bool) – Whether to force updates on this stack.
• enabled (bool) – Whether this stack is enabled
• protected (bool) – Whether this stack is protected.
property required_by
Return a list of stack names that depend on this stack.
Returns List[str]
property requires
Return a list of stack names this stack depends on.
Returns List[str]
property stack_policy
Return the Stack Policy to use for this stack.
property blueprint
Return the blueprint associated with this stack.
property tags
Return the tags that should be set on this stack.
Includes both the global tags, as well as any stack specific tags or overrides.
Returns Dictionary of tags.
Return type Dict[str, str]
property parameter_values
Return all CloudFormation Parameters for the stack.
CloudFormation Parameters can be specified via Blueprint Variables with a runway.cfngin.
blueprints.variables.types.CFNType type.
Returns dictionary of <parameter name>: <parameter value>.
Return type Dict[str, Any]
property all_parameter_definitions
Return a list of all parameters in the blueprint/template.
Dict[str, Dict[str, str]]: parameter definitions. Keys are parameter names, the values are dicts containing
key/values for various parameter properties.
property required_parameter_definitions
Return all CloudFormation Parameters without a default value.
218 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Returns dict of required CloudFormation Parameters for the blueprint. Will be a dictionary of
<parameter name>: <parameter attributes>.
Return type Dict[str, Dict[str, str]]
resolve(context, provider)
Resolve the Stack variables.
This resolves the Stack variables and then prepares the Blueprint for rendering by passing the resolved
variables to the Blueprint.
Parameters
• context (runway.cfngin.context.Context) – CFNgin context.
• provider (runway.cfngin.providers.base.BaseProvider) – Subclass of
the base provider.
set_outputs(outputs)
Set stack outputs to the provided value.
Parameters outputs (Dict[str, Any]) – CloudFormation Stack outputs.
runway.cfngin.status module
CFNgin statuses.
class runway.cfngin.status.Status(name, code, reason=None)
Bases: object
CFNgin status base class.
name
Name of the status.
Type str
code
Status code.
Type int
reason
Reason for the status.
Type Optional[str]
Instantiate class.
Parameters
• name (str) – Name of the status.
• code (int) – Status code.
• reason (Optional[str]) – Reason for the status.
class runway.cfngin.status.CompleteStatus(reason=None)
Bases: runway.cfngin.status.Status
Status name of ‘complete’ with code of ‘2’.
Instantiate class.
Parameters reason (Optional[str]) – Reason for the status.
9.6. Terraform 219
runway Documentation, Release 1.18.3
class runway.cfngin.status.FailedStatus(reason=None)
Bases: runway.cfngin.status.Status
Status name of ‘failed’ with code of ‘4’.
Instantiate class.
Parameters reason (Optional[str]) – Reason for the status.
class runway.cfngin.status.PendingStatus(reason=None)
Bases: runway.cfngin.status.Status
Status name of ‘pending’ with code of ‘0’.
Instantiate class.
Parameters reason (Optional[str]) – Reason for the status.
class runway.cfngin.status.SkippedStatus(reason=None)
Bases: runway.cfngin.status.Status
Status name of ‘skipped’ with code of ‘3’.
Instantiate class.
Parameters reason (Optional[str]) – Reason for the status.
class runway.cfngin.status.SubmittedStatus(reason=None)
Bases: runway.cfngin.status.Status
Status name of ‘submitted’ with code of ‘1’.
Instantiate class.
Parameters reason (Optional[str]) – Reason for the status.
class runway.cfngin.status.DidNotChangeStatus(reason=None)
Bases: runway.cfngin.status.SkippedStatus
Skipped status with a reason of ‘nochange’.
Instantiate class.
Parameters reason (Optional[str]) – Reason for the status.
reason = 'nochange'
class runway.cfngin.status.NotSubmittedStatus(reason=None)
Bases: runway.cfngin.status.SkippedStatus
Skipped status with a reason of ‘disabled’.
Instantiate class.
Parameters reason (Optional[str]) – Reason for the status.
reason = 'disabled'
class runway.cfngin.status.NotUpdatedStatus(reason=None)
Bases: runway.cfngin.status.SkippedStatus
Skipped status with a reason of ‘locked’.
Instantiate class.
Parameters reason (Optional[str]) – Reason for the status.
reason = 'locked'
220 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
class runway.cfngin.status.StackDoesNotExist(reason=None)
Bases: runway.cfngin.status.SkippedStatus
Skipped status with a reason of ‘does not exist in cloudformation’.
Instantiate class.
Parameters reason (Optional[str]) – Reason for the status.
reason = 'does not exist in cloudformation'
runway.cfngin.target module
CFNgin target.
class runway.cfngin.target.Target(definition)
Bases: object
A “target” is just a node in the graph that only specify dependencies.
These can be useful as a means of logically grouping a set of stacks together that can be targeted with the
targets option.
logging
Whether logging is enabled.
Type bool
name
Name of the target (stack) taken from the definition.
Type str
required_by
List of target (stack) names that depend on this stack.
Type List[str]
requires
List of target (stack) names this target (stack) depends on.
Type List[str]
Instantiate class.
Parameters definition (runway.cfngin.config.Stack) – Stack definition for the tar-
get.
runway.cfngin.tokenize_userdata module
Resources to tokenize userdata.
runway.cfngin.tokenize_userdata.cf_tokenize(raw_userdata)
Parse UserData for Cloudformation helper functions.
http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/user-data.html
http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference.html
http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/quickref-cloudformation.html#
scenario-userdata-base64
9.6. Terraform 221
runway Documentation, Release 1.18.3
It breaks apart the given string at each recognized function (see HELPERS global variable) and instantiates the
helper function objects in place of those.
Parameters raw_userdata (str) – Unparsed userdata data string.
Returns A list of string parts that is useful when used with troposphere.Join() and
troposphere.Base64() to produce userdata.
Return type List[str]
Example
runway.cfngin.ui module
CFNgin UI manipulation.
runway.cfngin.ui.get_raw_input(message)
Just a wrapper for input() for testing purposes.
class runway.cfngin.ui.UI
Bases: object
Used internally from terminal output in a multithreaded environment.
Ensures that two threads don’t write over each other while asking a user for input (e.g. in interactive mode).
Instantiate class.
lock(*_args, **_kwargs)
Obtain an exclusive lock on the UI for the current thread.
log(lvl, msg, *args, **kwargs)
Log the message if the current thread owns the underlying lock.
Parameters
• lvl (int) – Log level.
• msg (Union[str, Exception]) – String template or exception to use for the log
record.
Keyword Arguments logger (Union[logging.LoggerAdaptor, logging.
Logger]) – Specific logger to log to.
unlock(*_args, **_kwargs)
Release the lock on the UI.
info(msg, *args, **kwargs)
Log the line if the current thread owns the underlying lock.
Parameters msg (Union[str, Exception]) – String template or exception to use for the
log record.
Keyword Arguments logger (Union[logging.LoggerAdaptor, logging.
Logger]) – Specific logger to log to.
ask(message)
Collect input from a user in a multithreaded environment.
This wraps the built-in raw_input function to ensure that only 1 thread is asking for input from the user
at a give time. Any process that tries to log output to the terminal will be blocked while the user is being
prompted.
222 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
getpass(*args)
Wrap getpass to lock the UI.
runway.cfngin.util module
CFNgin utilities.
runway.cfngin.util.camel_to_snake(name)
Convert CamelCase to snake_case.
Parameters name (str) – The name to convert from CamelCase to snake_case.
Returns Converted string.
Return type str
runway.cfngin.util.convert_class_name(kls)
Get a string that represents a given class.
Parameters kls (class) – The class being analyzed for its name.
Returns The name of the given kls.
Return type str
runway.cfngin.util.parse_zone_id(full_zone_id)
Parse the returned hosted zone id and returns only the ID itself.
runway.cfngin.util.get_hosted_zone_by_name(client, zone_name)
Get the zone id of an existing zone by name.
Parameters
• client (botocore.client.Route53) – The connection used to interact with
Route53’s API.
• zone_name (str) – The name of the DNS hosted zone to create.
Returns The Id of the Hosted Zone.
Return type str
runway.cfngin.util.get_or_create_hosted_zone(client, zone_name)
Get the Id of an existing zone, or create it.
Parameters
• client (botocore.client.Route53) – The connection used to interact with
Route53’s API.
• zone_name (str) – The name of the DNS hosted zone to create.
Returns The Id of the Hosted Zone.
Return type str
class runway.cfngin.util.SOARecordText(record_text)
Bases: object
Represents the actual body of an SOARecord.
Instantiate class.
9.6. Terraform 223
runway Documentation, Release 1.18.3
class runway.cfngin.util.SOARecord(record)
Bases: object
Represents an SOA record.
Instantiate class.
runway.cfngin.util.get_soa_record(client, zone_id, zone_name)
Get the SOA record for zone_name from zone_id.
Parameters
• client (boto3.client.Client) – The connection used to interact with Route53’s
API.
• zone_id (str) – The AWS Route53 zone id of the hosted zone to query.
• zone_name (str) – The name of the DNS hosted zone to create.
Returns An object representing the parsed SOA record returned from AWS Route53.
Return type runway.cfngin.util.SOARecord
runway.cfngin.util.create_route53_zone(client, zone_name)
Create the given zone_name if it doesn’t already exists.
Also sets the SOA negative caching TTL to something short (300 seconds).
Parameters
• client (boto3.client.Client) – The connection used to interact with Route53’s
API.
• zone_name (str) – The name of the DNS hosted zone to create.
Returns The zone id returned from AWS for the existing, or newly created zone.
Return type str
runway.cfngin.util.merge_map(a, b)
Recursively merge elements of argument b into argument a.
Primarily used for merging two dictionaries together, where dict b takes precedence over dict a. If 2 lists are
provided, they are concatenated.
runway.cfngin.util.yaml_to_ordered_dict(stream, loader=<class
'yaml.loader.SafeLoader'>)
yaml.load alternative with preserved dictionary order.
Parameters
• stream (str) – YAML string to load.
• loader (yaml.loader) – PyYAML loader class. Defaults to safe load.
Returns Parsed YAML.
Return type OrderedDict
runway.cfngin.util.uppercase_first_letter(string_)
Return string with first character upper case.
runway.cfngin.util.cf_safe_name(name)
Convert a name to a safe string for a CloudFormation resource.
Given a string, returns a name that is safe for use as a CloudFormation Resource. (ie: Only alphanumeric
characters)
224 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
runway.cfngin.util.get_config_directory()
Return the directory the config file is located in.
This enables us to use relative paths in config values.
runway.cfngin.util.read_value_from_path(value)
Enable translators to read values from files.
The value can be referred to with the file:// prefix.
Example
conf_key: ${kms file://kms_value.txt}
runway.cfngin.util.get_client_region(client)
Get the region from a boto3.client.Client object.
Parameters client (boto3.client.Client) – The client to get the region from.
Returns AWS region string.
Return type str
runway.cfngin.util.get_s3_endpoint(client)
Get the s3 endpoint for the given boto3.client.Client object.
Parameters client (boto3.client.Client) – The client to get the endpoint from.
Returns The AWS endpoint for the client.
Return type str
runway.cfngin.util.s3_bucket_location_constraint(region)
Return the appropriate LocationConstraint info for a new S3 bucket.
When creating a bucket in a region OTHER than us-east-1, you need to specify a LocationConstraint inside the
CreateBucketConfiguration argument. This function helps you determine the right value given a given client.
Parameters region (str) – The region where the bucket will be created in.
Returns The string to use with the given client for creating a bucket.
Return type str
runway.cfngin.util.ensure_s3_bucket(s3_client, bucket_name, bucket_region, per-
sist_graph=False)
Ensure an s3 bucket exists, if it does not then create it.
Parameters
• s3_client (botocore.client.Client) – An s3 client used to verify and create the
bucket.
• bucket_name (str) – The bucket being checked/created.
• bucket_region (str, optional) – The region to create the bucket in. If not pro-
vided, will be determined by s3_client’s region.
• persist_graph (bool) – Check bucket for recommended settings. If creating a new
bucket, it will be created with recommended settings.
runway.cfngin.util.parse_cloudformation_template(template)
Parse CFN template string.
Leverages the vendored aws-cli yamlhelper to handle JSON or YAML templates.
9.6. Terraform 225
runway Documentation, Release 1.18.3
Parameters template (str) – The template body.
class runway.cfngin.util.Extractor(archive=None)
Bases: object
Base class for extractors.
Instantiate class.
Parameters archive (str) – Archive path.
set_archive(dir_name)
Update archive filename to match directory name & extension.
Parameters dir_name (str) – Archive directory name
static extension()
Serve as placeholder; override this in subclasses.
class runway.cfngin.util.TarExtractor(archive=None)
Bases: runway.cfngin.util.Extractor
Extracts tar archives.
Instantiate class.
Parameters archive (str) – Archive path.
extract(destination)
Extract the archive.
static extension()
Return archive extension.
class runway.cfngin.util.TarGzipExtractor(archive=None)
Bases: runway.cfngin.util.Extractor
Extracts compressed tar archives.
Instantiate class.
Parameters archive (str) – Archive path.
extract(destination)
Extract the archive.
static extension()
Return archive extension.
class runway.cfngin.util.ZipExtractor(archive=None)
Bases: runway.cfngin.util.Extractor
Extracts zip archives.
Instantiate class.
Parameters archive (str) – Archive path.
extract(destination)
Extract the archive.
static extension()
Return archive extension.
class runway.cfngin.util.SourceProcessor(sources, cfngin_cache_dir=None)
Bases: object
226 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Makes remote python package sources available in current environment.
Process a config’s defined package sources.
Parameters
• sources (Dict[str, Any]) – Package sources from CFNgin config dictionary.
• cfngin_cache_dir (str) – Path where remote sources will be cached.
ISO8601_FORMAT = '%Y%m%dT%H%M%SZ'
create_cache_directories()
Ensure that SourceProcessor cache directories exist.
get_package_sources()
Make remote python packages available for local use.
fetch_local_package(config)
Make a local path available to current CFNgin config.
Parameters config (Dict[str, Any]) – ‘local’ path config dictionary.
fetch_s3_package(config)
Make a remote S3 archive available for local use.
Parameters config (Dict[str, Any]) – git config dictionary.
fetch_git_package(config)
Make a remote git repository available for local use.
Parameters config (Dict[str, Any]) – git config dictionary.
update_paths_and_config(config, pkg_dir_name, pkg_cache_dir=None)
Handle remote source defined sys.paths & configs.
Parameters
• config (Dict[str, Any]) – Git config dictionary.
• pkg_dir_name (str) – directory Name of the CFNgin archive.
• pkg_cache_dir (Optional[str]) – Fully qualified path to CFNgin cache cache
directory.
static git_ls_remote(uri, ref )
Determine the latest commit id for a given ref.
Parameters
• uri (str) – Git URI.
• ref (str) – Git ref.
Returns A commit id
Return type str
static determine_git_ls_remote_ref(config)
Determine the ref to be used with the “git ls-remote” command.
Parameters config (runway.cfngin.config.GitPackageSource) – Git config
dictionary; ‘branch’ key is optional.
Returns A branch reference or “HEAD”.
Return type str
9.6. Terraform 227
runway Documentation, Release 1.18.3
determine_git_ref(config)
Determine the ref to be used for git checkout.
Parameters config (Dict[str, Any]) – Git config dictionary.
Returns A commit id or tag name.
Return type str
static sanitize_uri_path(uri)
Take a URI and converts it to a directory safe path.
Parameters uri (str) – URI (e.g. http://example.com/cats).
Returns Directory name for the supplied uri.
Return type str
sanitize_git_path(uri, ref=None)
Take a git URI and ref and converts it to a directory safe path.
Parameters
• uri (str) – Git URI. (e.g. [email protected]:foo/bar.git)
• ref (Optional[str]) – Git ref to be appended to the path.
Returns Directory name for the supplied uri
Return type str
runway.cfngin.util.stack_template_key_name(blueprint)
Given a blueprint, produce an appropriate key name.
Parameters blueprint (runway.cfngin.blueprints.base.Blueprint) – The
blueprint object to create the key from.
Returns Key name resulting from blueprint.
Return type str
Subpackages
runway.cfngin.actions package
Import modules.
Submodules
runway.cfngin.actions.base module
CFNgin base action.
runway.cfngin.actions.base.build_walker(concurrency)
Return a function for waling a graph.
Passed to runway.cfngin.plan.Plan for walking the graph.
If concurrency is 1 (no parallelism) this will return a simple topological walker that doesn’t use any multithread-
ing.
If concurrency is 0, this will return a walker that will walk the graph as fast as the graph topology allows.
228 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
If concurrency is greater than 1, it will return a walker that will only execute a maximum of concurrency steps
at any given time.
Parameters concurrency (int) – Number of threads to use while walking.
Returns Function to walk a runway.cfngin.dag.DAG.
Return type Callable[.., Any]
runway.cfngin.actions.base.stack_template_url(bucket_name, blueprint, endpoint)
Produce an s3 url for a given blueprint.
Parameters
• bucket_name (str) – The name of the S3 bucket where the resulting templates are
stored.
• blueprint (runway.cfngin.blueprints.base.Blueprint) – The blueprint
object to create the URL to.
• endpoint (str) – The s3 endpoint used for the bucket.
Returns S3 URL.
Return type str
class runway.cfngin.actions.base.BaseAction(context, provider_builder=None, can-
cel=None)
Bases: object
Actions perform the actual work of each Command.
Each action is tied to a runway.cfngin.commands.stacker.base.BaseCommand, and is responsi-
ble for building the runway.cfngin.plan.Plan that will be executed to perform that command.
DESCRIPTION
Description used when creating a plan for an action.
Type str
bucket_name
S3 bucket used by the action.
Type str
bucket_region
AWS region where S3 bucket is located.
Type str
cancel
Cancel handler.
Type threading.Event
context
The context for the current run.
Type runway.cfngin.context.Context
provider_builder
An object that will build a provider that will be interacted with in order to perform the necessary actions.
Type Optional[BaseProviderBuilder]
s3_conn
Boto3 S3 client.
9.6. Terraform 229
runway Documentation, Release 1.18.3
Type boto3.client.Client
Instantiate class.
Parameters
• context (runway.cfngin.context.Context) – The context for the current run.
• provider_builder (Optional[BaseProviderBuilder]) – An object that will build
a provider that will be interacted with in order to perform the necessary actions.
• cancel (threading.Event) – Cancel handler.
DESCRIPTION = 'Base action'
NAME = None
property provider
Return a generic provider using the default region.
Used for running things like hooks.
Returns runway.cfngin.providers.base.BaseProvider
build_provider(stack)
Build a runway.cfngin.providers.base.BaseProvider.
Parameters stack (runway.cfngin.stack.Stack) – Stack the action will be executed
on.
Returns Suitable for operating on the given runway.cfngin.stack.Stack.
Return type runway.cfngin.providers.base.BaseProvider
ensure_cfn_bucket()
CloudFormation bucket where templates will be stored.
execute(**kwargs)
Run the action with pre and post steps.
pre_run(**kwargs)
Perform steps before running the action.
post_run(**kwargs)
Perform steps after running the action.
run(**kwargs)
Abstract method for running the action.
s3_stack_push(blueprint, force=False)
Push the rendered blueprint’s template to S3.
Verifies that the template doesn’t already exist in S3 before pushing.
Returns URL to the template in S3.
Return type str
stack_template_url(blueprint)
S3 URL for CloudFormation template object.
Returns str
230 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
runway.cfngin.actions.build module
CFNgin build action.
runway.cfngin.actions.build.build_stack_tags(stack)
Build a common set of tags to attach to a stack.
runway.cfngin.actions.build.should_update(stack)
Test whether a stack should be submitted for updates to CloudFormation.
Parameters stack (runway.cfngin.stack.Stack) – The stack object to check.
Returns If the stack should be updated, return True.
Return type bool
runway.cfngin.actions.build.should_submit(stack)
Test whether a stack should be submitted to CF for update/create.
Parameters stack (runway.cfngin.stack.Stack) – The stack object to check.
Returns If the stack should be submitted, return True.
Return type bool
runway.cfngin.actions.build.should_ensure_cfn_bucket(outline, dump)
Test whether access to the cloudformation template bucket is required.
Parameters
• outline (bool) – The outline action.
• dump (bool) – The dump action.
Returns If access to CF bucket is needed, return True.
Return type bool
class runway.cfngin.actions.build.UsePreviousParameterValue
Bases: object
Class used to indicate a Parameter should use it’s existing value.
runway.cfngin.actions.build.handle_hooks(stage, hooks, provider, context, dump, outline)
Handle pre/post hooks.
Parameters
• stage (str) – The name of the hook stage - pre_build/post_build.
• hooks (list) – A list of dictionaries containing the hooks to execute.
• provider (runway.cfngin.providers.base.BaseProvider) – The provider
the current stack is using.
• context (runway.cfngin.context.Context) – The current CFNgin context.
• dump (bool) – Whether running with dump set or not.
• outline (bool) – Whether running with outline set or not.
class runway.cfngin.actions.build.Action(context, provider_builder=None, cancel=None)
Bases: runway.cfngin.actions.base.BaseAction
Responsible for building & coordinating CloudFormation stacks.
Generates the build plan based on stack dependencies (these dependencies are determined automatically based
on output lookups from other stacks).
9.6. Terraform 231
runway Documentation, Release 1.18.3
The plan can then either be printed out as an outline or executed. If executed, each stack will get launched in
order which entails:
• Pushing the generated CloudFormation template to S3 if it has changed
• Submitting either a build or update of the given stack to the runway.cfngin.providers.base.
BaseProvider.
Instantiate class.
Parameters
• context (runway.cfngin.context.Context) – The context for the current run.
• provider_builder (Optional[BaseProviderBuilder]) – An object that will build
a provider that will be interacted with in order to perform the necessary actions.
• cancel (threading.Event) – Cancel handler.
DESCRIPTION = 'Create/Update stacks'
NAME = 'build'
static build_parameters(stack, provider_stack=None)
Build the CloudFormation Parameters for our stack.
Parameters
• stack (runway.cfngin.stack.Stack) – A CFNgin stack.
• provider_stack (Dict[str, Any]) – An optional CFNgin provider object.
Returns The parameters for the given stack
Return type Dict[str, Any]
pre_run(**kwargs)
Any steps that need to be taken prior to running the action.
run(**kwargs)
Kicks off the build/update of the stacks in the stack_definitions.
This is the main entry point for the Builder.
post_run(**kwargs)
Any steps that need to be taken after running the action.
runway.cfngin.actions.destroy module
CFNgin destroy action.
class runway.cfngin.actions.destroy.Action(context, provider_builder=None, can-
cel=None)
Bases: runway.cfngin.actions.base.BaseAction
Responsible for destroying CloudFormation stacks.
Generates a destruction plan based on stack dependencies. Stack dependencies are reversed from the build
action. For example, if a Stack B requires Stack A during build, during destroy Stack A requires Stack B be
destroyed first.
The plan defaults to printing an outline of what will be destroyed. If forced to execute, each stack will get
destroyed in order.
Instantiate class.
232 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Parameters
• context (runway.cfngin.context.Context) – The context for the current run.
• provider_builder (Optional[BaseProviderBuilder]) – An object that will build
a provider that will be interacted with in order to perform the necessary actions.
• cancel (threading.Event) – Cancel handler.
DESCRIPTION = 'Destroy stacks'
NAME = 'destroy'
pre_run(**kwargs)
Any steps that need to be taken prior to running the action.
run(**kwargs)
Kicks off the destruction of the stacks in the stack_definitions.
post_run(**kwargs)
Any steps that need to be taken after running the action.
runway.cfngin.actions.diff module
CFNgin diff action.
class runway.cfngin.actions.diff.DictValue(key, old_value, new_value)
Bases: object
Used to create a diff of two dictionaries.
Instantiate class.
ADDED = 'ADDED'
REMOVED = 'REMOVED'
MODIFIED = 'MODIFIED'
UNMODIFIED = 'UNMODIFIED'
formatter = '%s%s = %s'
changes()
Return changes to represent the diff between old and new value.
Returns Representation of the change (if any) between old and new value.
Return type List[str]
status()
Status of changes between the old value and new value.
runway.cfngin.actions.diff.diff_dictionaries(old_dict, new_dict)
Calculate the diff two single dimension dictionaries.
Parameters
• old_dict (Dict[Any, Any]) – Old dictionary.
• new_dict (Dict[Any, Any]) – New dictionary.
Returns Number of changed records and the DictValue object containing the changes.
Return type Tuple[int, List[DictValue]]
9.6. Terraform 233
runway Documentation, Release 1.18.3
runway.cfngin.actions.diff.format_params_diff(parameter_diff )
Handle the formatting of differences in parameters.
Parameters parameter_diff (List[DictValue]) – A list of DictValue detailing the differ-
ences between two dicts returned by diff_dictionaries().
Returns A formatted string that represents a parameter diff
Return type str
runway.cfngin.actions.diff.diff_parameters(old_params, new_params)
Compare the old vs. new parameters and returns a “diff”.
If there are no changes, we return an empty list.
Parameters
• old_params (Dict[Any, Any]) – old paramters
• new_params (Dict[Any, Any]) – new parameters
Returns A list of differences.
Return type List[DictValue]
class runway.cfngin.actions.diff.Action(context, provider_builder=None, cancel=None)
Bases: runway.cfngin.actions.build.Action
Responsible for diffing CloudFormation stacks in AWS and locally.
Generates the build plan based on stack dependencies (these dependencies are determined automatically based
on references to output values from other stacks).
The plan is then used to create a changeset for a stack using a generated template based on the current config.
Instantiate class.
Parameters
• context (runway.cfngin.context.Context) – The context for the current run.
• provider_builder (Optional[BaseProviderBuilder]) – An object that will build
a provider that will be interacted with in order to perform the necessary actions.
• cancel (threading.Event) – Cancel handler.
DESCRIPTION = 'Diff stacks'
NAME = 'diff'
run(**kwargs)
Kicks off the diffing of the stacks in the stack_definitions.
pre_run(**kwargs)
Any steps that need to be taken prior to running the action.
Handle CFNgin bucket access denied & not existing.
post_run(**kwargs)
Do nothing.
234 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
runway.cfngin.actions.graph module
CFNgin graph action.
runway.cfngin.actions.graph.each_step(graph)
Yield each step and it’s direct dependencies.
Parameters graph (runway.cfngin.plan.Graph) – Graph to iterate over.
Yields Tuple[Step, Set(str)]
runway.cfngin.actions.graph.dot_format(out, graph, name='digraph')
Output a graph using the graphviz “dot” format.
Parameters
• out (TextIo) – Where output will be written.
• graph (runway.cfngin.plan.Graph) – Graph to be output.
• name (str) – Name of the graph.
runway.cfngin.actions.graph.json_format(out, graph)
Output the graph in a machine readable JSON format.
Parameters
• out (TextIo) – Where output will be written.
• graph (runway.cfngin.plan.Graph) – Graph to be output.
class runway.cfngin.actions.graph.Action(context, provider_builder=None, cancel=None)
Bases: runway.cfngin.actions.base.BaseAction
Responsible for outputing a graph for the current CFNgin config.
Instantiate class.
Parameters
• context (runway.cfngin.context.Context) – The context for the current run.
• provider_builder (Optional[BaseProviderBuilder]) – An object that will build
a provider that will be interacted with in order to perform the necessary actions.
• cancel (threading.Event) – Cancel handler.
DESCRIPTION = 'Print graph'
NAME = 'graph'
run(**kwargs)
Generate the underlying graph and prints it.
9.6. Terraform 235
runway Documentation, Release 1.18.3
runway.cfngin.actions.info module
CFNgin info action.
class runway.cfngin.actions.info.Action(context, provider_builder=None, cancel=None)
Bases: runway.cfngin.actions.base.BaseAction
Get information on CloudFormation stacks.
Displays the outputs for the set of CloudFormation stacks.
Instantiate class.
Parameters
• context (runway.cfngin.context.Context) – The context for the current run.
• provider_builder (Optional[BaseProviderBuilder]) – An object that will build
a provider that will be interacted with in order to perform the necessary actions.
• cancel (threading.Event) – Cancel handler.
NAME = 'info'
run(**kwargs)
Get information on CloudFormation stacks.
runway.cfngin.blueprints package
Import modules.
Submodules
runway.cfngin.blueprints.base module
CFNgin blueprint base classes.
class runway.cfngin.blueprints.base.CFNParameter(name, value)
Bases: object
Wrapper around a value to indicate a CloudFormation Parameter.
Instantiate class.
Parameters
• name (str) – The name of the CloudFormation Parameter.
• value (Any) – The value we’re going to submit as a CloudFormation Parameter.
to_parameter_value()
Return the value to be submitted to CloudFormation.
property ref
Ref the value of a parameter.
Returns Ref for the parameter.
Return type troposphere.Ref
runway.cfngin.blueprints.base.build_parameter(name, properties)
Build a troposphere Parameter with the given properties.
236 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Parameters
• name (str) – The name of the parameter.
• properties (Dict[str, Any]) – Contains the properties that will be applied to
the parameter. See: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/
parameters-section-structure.html
Returns The created parameter object.
Return type troposphere.Parameter
runway.cfngin.blueprints.base.validate_variable_type(var_name, var_type, value)
Ensure the value is the correct variable type.
Parameters
• var_name (str) – The name of the defined variable on a blueprint.
• var_type (type) – The type that the value should be.
• value (Any) – The object representing the value provided for the variable
Returns The appropriate value object. If the original value was of CFNType, the returned value will
be wrapped in CFNParameter.
Return type Any
Raises ValueError – If the value isn’t of var_type and can’t be cast as that type, this is raised.
runway.cfngin.blueprints.base.validate_allowed_values(allowed_values, value)
Support a variable defining which values it allows.
Parameters
• allowed_values (Optional[List[Any]]) – A list of allowed values from the vari-
able definition.
• value (Any) – The object representing the value provided for the variable.
Returns Boolean for whether or not the value is valid.
Return type bool
runway.cfngin.blueprints.base.resolve_variable(var_name, var_def, provided_variable,
blueprint_name)
Resolve a provided variable value against the variable definition.
Parameters
• var_name (str) – The name of the defined variable on a blueprint.
• var_def (Dict[str, Any]) – A dictionary representing the defined variables at-
tributes.
• provided_variable (runway.cfngin.variables.Variable) – The variable
value provided to the blueprint.
• blueprint_name (str) – The name of the blueprint that the variable is being applied
to.
Returns The resolved variable value, could be any python object.
Return type Any
Raises
• MissingVariable – Raised when a variable with no default is not provided a value.
9.6. Terraform 237
runway Documentation, Release 1.18.3
• UnresolvedVariable – Raised when the provided variable is not already resolved.
• ValueError – Raised when the value is not the right type and cannot be
cast as the correct type. Raised by runway.cfngin.blueprints.base.
validate_variable_type()
• ValidatorError – Raised when a validator raises an exception. Wraps the original
exception.
runway.cfngin.blueprints.base.parse_user_data(variables, raw_user_data,
blueprint_name)
Parse the given user data and renders it as a template.
It supports referencing template variables to create userdata that’s supplemented with information from the
stack, as commonly required when creating EC2 userdata files.
Example
Given a raw_user_data string: 'open file ${file}' And a variables dictionary with: {'file':
'test.txt'} parse_user_data would output: open file test.txt
Parameters
• variables (Dict[str, Any]) – Variables available to the template.
• raw_user_data (str) – The user_data to be parsed.
• blueprint_name (str) – The name of the blueprint.
Returns The parsed user data, with all the variables values and refs replaced with their resolved
values.
Return type str
Raises
• InvalidUserdataPlaceholder – Raised when a placeholder name in raw_user_data
is not valid. E.g ${100} would raise this.
• MissingVariable – Raised when a variable is in the raw_user_data that is not given in
the blueprint
class runway.cfngin.blueprints.base.Blueprint(name, context, mappings=None, descrip-
tion=None)
Bases: object
Base implementation for rendering a troposphere template.
Instantiate class.
Parameters
• name (str) – A name for the blueprint.
• context (runway.cfngin.context.Context) – Context the blueprint is being ex-
ecuted under.
• mappings (dict, optional) – CloudFormation Mappings to be used in the template.
• description (str) – Used to describe the resulting CloudFormation template.
get_parameter_definitions()
Get the parameter definitions to submit to CloudFormation.
238 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Any variable definition whose type is an instance of CFNType will be returned as a CloudFormation Pa-
rameter.
Returns Parameter definitions. Keys are parameter names, the values are dicts containing
key/values for various parameter properties.
Return type Dict[str, Dict[str, str]]
get_output_definitions()
Get the output definitions.
Returns Output definitions. Keys are output names, the values are dicts containing key/values
for various output properties.
Return type Dict[str, Dict[str, str]]
get_required_parameter_definitions()
Return all template parameters that do not have a default value.
Returns Dict of required CloudFormation Parameters for the blueprint. Will be a dictionary of
<parameter name>: <parameter attributes>.
Return type Dict[str, Dict[str, str]]
get_parameter_values()
Return a dictionary of variables with type CFNType.
Returns Variables that need to be submitted as CloudFormation Parameters. Will be a dictionary
of <parameter name>: <parameter value>.
Return type Dict[str, str]
setup_parameters()
Add any CloudFormation parameters to the template.
defined_variables()
Return a dictionary of variables defined by the blueprint.
By default, this will just return the values from VARIABLES, but this makes it easy for subclasses to add
variables.
Returns Variables defined by the blueprint.
Return type Dict[str, Any]
get_variables()
Return a dictionary of variables available to the template.
These variables will have been defined within VARIABLES or self.defined_variables. Any variable value
that contains a lookup will have been resolved.
Returns Variables available to the template.
Return type Dict[str, Variable]
Raises UnresolvedVariables – If variables are unresolved.
get_cfn_parameters()
Return a dictionary of variables with type CFNType.
Returns variables that need to be submitted as CloudFormation Parameters.
Return type Dict[str, Any]
9.6. Terraform 239
runway Documentation, Release 1.18.3
resolve_variables(provided_variables)
Resolve the values of the blueprint variables.
This will resolve the values of the VARIABLES with values from the env file, the config, and any lookups
resolved.
Parameters provided_variables (List[runway.cfngin.variables.Variable])
– List of provided variables.
import_mappings()
Import mappings from CFNgin config to the blueprint.
reset_template()
Reset template.
render_template()
Render the Blueprint to a CloudFormation template.
to_json(variables=None)
Render the blueprint and return the template in json form.
Parameters variables (Optional[Dict[str, Any]]) – Dictionary provid-
ing/overriding variable values.
Returns Rhe rendered CFN JSON template.
Return type str
read_user_data(user_data_path)
Read and parse a user_data file.
Parameters user_data_path (str) – Path to the userdata file.
Returns The parsed user data file.
Return type str
set_template_description(description)
Add a description to the Template.
Parameters description (str) – A description to be added to the resulting template.
add_output(name, value)
Add an output to the template.
Wrapper for self.template.add_output(Output(name, Value=value)).
Parameters
• name (str) – The name of the output to create.
• value (str) – The value to put in the output.
property requires_change_set
Return true if the underlying template has transforms.
property rendered
Return rendered blueprint.
property version
Template version.
create_template()
Abstract method called to create a template from the blueprint..
240 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
runway.cfngin.blueprints.raw module
CFNgin blueprint representing raw template module.
runway.cfngin.blueprints.raw.get_template_path(filename)
Find raw template in working directory or in sys.path.
template_path from config may refer to templates colocated with the Stacker config, or files in remote pack-
age_sources. Here, we emulate python module loading to find the path to the template.
Parameters filename (str) – Template filename.
Returns Path to file, or None if no file found
Return type Optional[str]
runway.cfngin.blueprints.raw.get_template_params(template)
Parse a CFN template for defined parameters.
Parameters template (dict) – Parsed CFN template.
Returns Template parameters.
Return type dict
runway.cfngin.blueprints.raw.resolve_variable(provided_variable, blueprint_name)
Resolve a provided variable value against the variable definition.
This acts as a subset of resolve_variable logic in the base module, leaving out everything that doesn’t apply to
CFN parameters.
Parameters
• provided_variable (runway.cfngin.variables.Variable) – The variable
value provided to the blueprint.
• blueprint_name (str) – The name of the blueprint that the variable is being applied
to.
Returns The resolved variable string value.
Return type object
Raises UnresolvedVariable – Raised when the provided variable is not already resolved.
class runway.cfngin.blueprints.raw.RawTemplateBlueprint(name, context,
raw_template_path,
mappings=None, descrip-
tion=None)
Bases: runway.cfngin.blueprints.base.Blueprint
Blueprint class for blueprints auto-generated from raw templates.
Instantiate class.
to_json(variables=None)
Return the template in JSON.
Parameters variables (dict) – Unused in this subclass (variables won’t affect the tem-
plate).
Returns the rendered CFN JSON template
Return type str
9.6. Terraform 241
runway Documentation, Release 1.18.3
to_dict()
Return the template as a python dictionary.
Returns the loaded template as a python dictionary
Return type dict
render_template()
Load template and generate its md5 hash.
get_parameter_definitions()
Get the parameter definitions to submit to CloudFormation.
Returns parameter definitions. Keys are parameter names, the values are dicts containing
key/values for various parameter properties.
Return type Dict[str, Any]
get_output_definitions()
Get the output definitions.
Returns output definitions. Keys are output names, the values are dicts containing key/values
for various output properties.
Return type Dict[str, Any]
resolve_variables(provided_variables)
Resolve the values of the blueprint variables.
This will resolve the values of the template parameters with values from the env file, the config, and
any lookups resolved. The resolution is run twice, in case the blueprint is jinja2 templated and requires
provided variables to render.
Parameters provided_variables (List[runway.cfngin.variables.Variable])
– List of provided variables.
get_parameter_values()
Return a dictionary of variables with type CFNType.
Returns variables that need to be submitted as CloudFormation Parameters. Will be a dictionary
of <parameter name>: <parameter value>.
Return type Dict[str, Any]
property requires_change_set
Return True if the underlying template has transforms.
property rendered
Return (generating first if needed) rendered template.
property version
Return (generating first if needed) version hash.
242 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
runway.cfngin.blueprints.testutil module
Provides a sublass of unittest.TestCase for testing blueprints.
runway.cfngin.blueprints.testutil.diff(first, second)
Human readable differ.
class runway.cfngin.blueprints.testutil.BlueprintTestCase(methodName='runTest')
Bases: unittest.case.TestCase
Extends the functionality of unittest.TestCase for testing blueprints.
Create an instance of the class that will use the named test method when executed. Raises a ValueError if the
instance does not have a method with the specified name.
OUTPUT_PATH = 'tests/fixtures/blueprints'
assertRenderedBlueprint(blueprint)
Test that the rendered blueprint json matches the expected result.
Result files are to be stored in the repo as test/fixtures/blueprints/${blueprint.name}.
json.
class runway.cfngin.blueprints.testutil.YamlDirTestGenerator
Bases: object
Generate blueprint tests from yaml config files.
This class creates blueprint tests from yaml files with a syntax similar to CFNgin configuration syntax. For
example:
namespace: test
stacks:
- name: test_sample
class_path: blueprints.test.Sample
variables:
var1: value1
Will create a test for the specified blueprint, passing that variable as part of the test.
The test will generate a .json file for this blueprint, and compare it with the stored result.
By default, the generator looks for files named test_
*
.yaml in its same directory. In order to use it, subclass
it in a directory containing such tests, and name the class with a pattern that will include it in nosetests’ tests
(for example, TestGenerator).
The subclass may override some @property definitions:
base_class By default, the generated tests are subclasses or runway.cfngin.blueprints.testutil.
BlueprintTestCase. In order to change this, set this property to the desired base class.
yaml_dirs: By default, the directory where the generator is subclassed is searched for test files. Override this
array for specifying more directories. These must be relative to the directory in which the subclass lives
in. Globs may be used. Default: ['.']. Example override: ['.', 'tests/
*
/']
yaml_filename: By default, the generator looks for files named test_
*
.yaml. Use this to change this pat-
tern. Globs may be used.
Instantiate class.
property base_class
Return the baseclass.
9.6. Terraform 243
runway Documentation, Release 1.18.3
property yaml_dirs
Yaml directories.
property yaml_filename
Yaml filename.
test_generator()
Test generator.
Subpackages
runway.cfngin.blueprints.variables package
Import modules.
Submodules
runway.cfngin.blueprints.variables.types module
CFNgin blueprint variable types.
class runway.cfngin.blueprints.variables.types.TroposphereType(defined_type,
many=False,
optional=False,
validate=True)
Bases: object
Represents a Troposphere type.
Troposphere will convert the value provided to the variable to the specified Troposphere type.
Both resource and parameter classes (which are just used to configure other resources) are acceptable as config-
uration values.
Complete resource definitions must be dictionaries, with the keys identifying the resource titles, and the values
being used as the constructor parameters.
Parameter classes can be defined as dictionary or a list of dictionaries. In either case, the keys and values will
be used directly as constructor parameters.
Instantiate class.
Parameters
• defined_type (Any) – Troposphere type
• many (bool) – Whether or not multiple resources can be constructed. If the defined type
is a resource, multiple resources can be passed as a dictionary of dictionaries. If it is a
parameter class, multiple resources are passed as a list.
• optional (bool) – Whether an undefined/null configured value is acceptable. In that
case a value of None will be passed to the template, even if many is enabled.
• validate (bool) – Whether to validate the generated object on creation. Should be left
enabled unless the object will be augmented with mandatory parameters in the template
code, such that it must be validated at a later point.
property resource_name
Name of the type or resource.
244 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
create(value)
Create the troposphere type from the value.
Parameters value (Union[Dict[str, Any], List[Dict[str, Any]]]) – A
dictionary or list of dictionaries (see class documentation for details) to use as parameters
to create the Troposphere type instance. Each dictionary will be passed to the from_dict
method of the type.
Returns Returns the value converted to the troposphere type.
Return type Any
class runway.cfngin.blueprints.variables.types.CFNType(parameter_type)
Bases: object
Represents a CloudFormation Parameter Type.
CFNType can be used as the type for a Blueprint variable. Unlike other variables, a variable with type:
CFNType, will be submitted to CloudFormation as a Parameter.
Instantiate class.
Parameters parameter_type (str) – An AWS specific parameter type (http://goo.gl/PthovJ)
runway.cfngin.config package
CFNgin config.
class runway.cfngin.config.AnyType(required=False, default=Undefined, serial-
ized_name=None, choices=None, validators=None,
deserialize_from=None, export_level=None, se-
rialize_when_none=None, messages=None, meta-
data=None)
Bases: schematics.types.base.BaseType
Any type.
MESSAGES = {'choices': 'Value must be one of {0}.', 'required': 'This field is required.'}
class runway.cfngin.config.Config(raw_data=None, trusted_data=None, deserial-
ize_mapping=None, init=True, partial=True, strict=True,
validate=False, app_data=None, lazy=False, **kwargs)
Bases: schematics.deprecated.Model
Python representation of a CFNgin config file.
This is used internally by CFNgin to parse and validate a yaml formatted CFNgin configuration file, but can also
be used in scripts to generate a CFNgin config file before handing it off to CFNgin to build/destroy.
Example:
from runway.cfngin.config import dump, Config, Stack
vpc = Stack({
"name": "vpc",
"class_path": "blueprints.VPC"})
config = Config()
config.namespace = "prod"
config.stacks = [vpc]
print dump(config)
9.6. Terraform 245
runway Documentation, Release 1.18.3
cfngin_bucket
Bucket to use for CFNgin resources (e.g. CloudFormation templates). May be an empty string.
Type StringType
cfngin_bucket_region
Explicit region to use for cfngin_bucket.
Type StringType
cfngin_cache_dir
Local directory to use for caching.
Type StringType
log_formats
Custom formatting for log messages.
Type DictType
lookups
Register custom lookups.
Type DictType
mappings
Mappings that will be added to all stacks.
Type DictType
namespace
Namespace to prepend to everything.
Type StringType
namespace_delimiter
Character used to separate namespace and anything it prepends.
Type StringType
package_sources
Remote source locations.
Type ModelType
persistent_graph_key
S3 object key were the persistent graph is stored.
Type str
post_build
Hooks to run after a build action.
Type ListType
post_destroy
Hooks to run after a destroy action.
Type ListType
pre_build
Hooks to run before a build action.
Type ListType
pre_destroy
Hooks to run before a destroy action.
246 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Type ListType
service_role
IAM role for CloudFormation to use.
Type StringType
stacker_bucket
[DEPRECATED] Replaced by cfngin_bucket, support will be retained until the release of version
2.0.0 at the earliest.
Type StringType
stacker_bucket_region
[DEPRECATED] Replaced by cfngin_bucket_region, support will be retained until the release of
version 2.0.0 at the earliest.
Type StringType
stacker_cache_dir
[DEPRECATED] Replaced by cfngin_cache_dir, support will be retained until the release of version
2.0.0 at the earliest.
Type StringType
stacks
Stacks to be processed.
Type ListType
sys_path
Relative or absolute path to use as the work directory.
Type StringType
tags
Tags to apply to all resources.
Type DictType
targets
Stag grouping.
Type ListType
template_indent
Spaces to use per-indent level when outputing a template to json.
Type StringType
Extend functionality of the parent class.
Manipulation here allows us to _clone_ the values of legacy stacker field into their new names. Doing so we can
retain support for Stacker configs and CFNgin configs.
cfngin_bucket = <StringType() instance on Config as 'cfngin_bucket'>
cfngin_bucket_region = <StringType() instance on Config as 'cfngin_bucket_region'>
cfngin_cache_dir = <StringType() instance on Config as 'cfngin_cache_dir'>
log_formats = <DictType(StringType) instance on Config as 'log_formats'>
lookups = <DictType(StringType) instance on Config as 'lookups'>
mappings = <DictType(DictType) instance on Config as 'mappings'>
9.6. Terraform 247
runway Documentation, Release 1.18.3
namespace = <StringType() instance on Config as 'namespace'>
namespace_delimiter = <StringType() instance on Config as 'namespace_delimiter'>
package_sources = <ModelType(PackageSources) instance on Config as 'package_sources'>
persistent_graph_key = <StringType() instance on Config as 'persistent_graph_key'>
post_build = <ListType(ModelType) instance on Config as 'post_build'>
post_destroy = <ListType(ModelType) instance on Config as 'post_destroy'>
pre_build = <ListType(ModelType) instance on Config as 'pre_build'>
pre_destroy = <ListType(ModelType) instance on Config as 'pre_destroy'>
service_role = <StringType() instance on Config as 'service_role'>
stacker_bucket = <StringType() instance on Config as 'stacker_bucket'>
stacker_bucket_region = <StringType() instance on Config as 'stacker_bucket_region'>
stacker_cache_dir = <StringType() instance on Config as 'stacker_cache_dir'>
stacks = <ListType(ModelType) instance on Config as 'stacks'>
sys_path = <StringType() instance on Config as 'sys_path'>
tags = <DictType(StringType) instance on Config as 'tags'>
targets = <ListType(ModelType) instance on Config as 'targets'>
template_indent = <StringType() instance on Config as 'template_indent'>
validate(partial=False, convert=True, app_data=None, **kwargs)
Validate the state of the model.
If the data is invalid, raises a DataError with error messages.
Parameters
• partial (bool) – Allow partial data to validate. Essentially drops the
required=True settings from field definitions.
• convert (bool) – Controls whether to perform import conversion before validating.
Can be turned off to skip an unnecessary conversion step if all values are known to have
the right datatypes (e.g., when validating immediately after the initial import).
Raises
• UndefinedValueError –
• SchematicsError –
validate_stacker_bucket(_data, value)
Validate stack_bucket is not used.
If in use, show deprecation warning.
validate_stacker_bucket_region(_data, value)
Validate stacker_bucket_regio is not used.
If in use, show deprecation warning.
validate_stacker_cache_dir(_data, value)
Validate stacker_cache_dir is not used.
If in use, show deprecation warning.
248 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
validate_stacks(_data, value)
Validate stacks.
class runway.cfngin.config.GitPackageSource(raw_data=None, trusted_data=None,
deserialize_mapping=None, init=True,
partial=True, strict=True, validate=False,
app_data=None, lazy=False, **kwargs)
Bases: schematics.deprecated.Model
Git package source model.
Package source located in a git repo.
branch
Branch name.
Type StringType
commit
Commit hash.
Type StringType
configs
List of CFNgin config paths to execute.
Type ListType
paths
List of paths to append to sys.path.
Type ListType
tag
Git tag.
Type StringType
uri
Remote git repo URI.
Type StringType
branch = <StringType() instance on GitPackageSource as 'branch'>
commit = <StringType() instance on GitPackageSource as 'commit'>
configs = <ListType(StringType) instance on GitPackageSource as 'configs'>
paths = <ListType(StringType) instance on GitPackageSource as 'paths'>
tag = <StringType() instance on GitPackageSource as 'tag'>
uri = <StringType() instance on GitPackageSource as 'uri'>
class runway.cfngin.config.Hook(raw_data=None, trusted_data=None, deserial-
ize_mapping=None, init=True, partial=True, strict=True,
validate=False, app_data=None, lazy=False, **kwargs)
Bases: schematics.deprecated.Model
Hook module.
args
Type DictType
data_key
9.6. Terraform 249
runway Documentation, Release 1.18.3
Type StringType
enabled
Type BooleanType
path
Type StringType
required
Type BooleanType
args = <DictType(AnyType) instance on Hook as 'args'>
data_key = <StringType() instance on Hook as 'data_key'>
enabled = <BooleanType() instance on Hook as 'enabled'>
path = <StringType() instance on Hook as 'path'>
required = <BooleanType() instance on Hook as 'required'>
class runway.cfngin.config.LocalPackageSource(raw_data=None, trusted_data=None, de-
serialize_mapping=None, init=True, par-
tial=True, strict=True, validate=False,
app_data=None, lazy=False, **kwargs)
Bases: schematics.deprecated.Model
Local package source model.
Package source located on a local disk.
configs
List of CFNgin config paths to execute.
Type ListType
paths
List of paths to append to sys.path.
Type ListType
source
Source.
Type StringType
configs = <ListType(StringType) instance on LocalPackageSource as 'configs'>
paths = <ListType(StringType) instance on LocalPackageSource as 'paths'>
source = <StringType() instance on LocalPackageSource as 'source'>
class runway.cfngin.config.PackageSources(raw_data=None, trusted_data=None, deseri-
alize_mapping=None, init=True, partial=True,
strict=True, validate=False, app_data=None,
lazy=False, **kwargs)
Bases: schematics.deprecated.Model
Package sources model.
git
Package source located in a git repo.
Type GitPackageSource
250 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
local
Package source located on a local disk.
Type LocalPackageSource
s3
Package source located in AWS S3.
Type S3PackageSource
git = <ListType(ModelType) instance on PackageSources as 'git'>
local = <ListType(ModelType) instance on PackageSources as 'local'>
s3 = <ListType(ModelType) instance on PackageSources as 's3'>
class runway.cfngin.config.S3PackageSource(raw_data=None, trusted_data=None, de-
serialize_mapping=None, init=True, par-
tial=True, strict=True, validate=False,
app_data=None, lazy=False, **kwargs)
Bases: schematics.deprecated.Model
S3 package source model.
Package source located in AWS S3.
bucket
AWS S3 bucket name.
Type StringType
configs
List of CFNgin config paths to execute.
Type ListType
key
Object key. The object should be a zip file.
Type StringType
paths
List of paths to append to sys.path.
Type ListType
requester_pays
AWS S3 requester pays option.
Type BooleanType
use_latest
Use the latest version of the object.
Type BooleanType
bucket = <StringType() instance on S3PackageSource as 'bucket'>
configs = <ListType(StringType) instance on S3PackageSource as 'configs'>
key = <StringType() instance on S3PackageSource as 'key'>
paths = <ListType(StringType) instance on S3PackageSource as 'paths'>
requester_pays = <BooleanType() instance on S3PackageSource as 'requester_pays'>
use_latest = <BooleanType() instance on S3PackageSource as 'use_latest'>
9.6. Terraform 251
runway Documentation, Release 1.18.3
class runway.cfngin.config.Stack(raw_data=None, trusted_data=None, deserial-
ize_mapping=None, init=True, partial=True, strict=True,
validate=False, app_data=None, lazy=False, **kwargs)
Bases: schematics.deprecated.Model
Stack model.
class_path
Type StringType
description
Type StringType
enabled
Type BooleanType
in_progress_behavior
Type StringType
locked
Type BooleanType
name
Type StringType
parameters
Type DictType
profile
Type StringType
protected
Type BooleanType
region
Type StringType
required_by
Type ListType
requires
Type ListType
stack_name
Type StringType
stack_policy_path
Type StringType
tags
Type DictType
template_path
Type StringType
252 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
termination_protection
Type BooleanType
variables
Type DictType
class_path = <StringType() instance on Stack as 'class_path'>
description = <StringType() instance on Stack as 'description'>
enabled = <BooleanType() instance on Stack as 'enabled'>
in_progress_behavior = <StringType() instance on Stack as 'in_progress_behavior'>
locked = <BooleanType() instance on Stack as 'locked'>
name = <StringType() instance on Stack as 'name'>
parameters = <DictType(AnyType) instance on Stack as 'parameters'>
profile = <StringType() instance on Stack as 'profile'>
protected = <BooleanType() instance on Stack as 'protected'>
region = <StringType() instance on Stack as 'region'>
required_by = <ListType(StringType) instance on Stack as 'required_by'>
requires = <ListType(StringType) instance on Stack as 'requires'>
stack_name = <StringType() instance on Stack as 'stack_name'>
stack_policy_path = <StringType() instance on Stack as 'stack_policy_path'>
tags = <DictType(StringType) instance on Stack as 'tags'>
template_path = <StringType() instance on Stack as 'template_path'>
termination_protection = <BooleanType() instance on Stack as 'termination_protection'>
validate_class_path(data, value)
Validate class pass.
validate_parameters(data, value)
Validate parameters.
static validate_stack_source(data)
Validate stack source.
validate_template_path(data, value)
Validate template path.
variables = <DictType(AnyType) instance on Stack as 'variables'>
class runway.cfngin.config.Target(raw_data=None, trusted_data=None, deserial-
ize_mapping=None, init=True, partial=True, strict=True,
validate=False, app_data=None, lazy=False, **kwargs)
Bases: schematics.deprecated.Model
Target model.
name
Type StringType
required_by
Type ListType
9.6. Terraform 253
runway Documentation, Release 1.18.3
requires
Type ListType
name = <StringType() instance on Target as 'name'>
required_by = <ListType(StringType) instance on Target as 'required_by'>
requires = <ListType(StringType) instance on Target as 'requires'>
runway.cfngin.config.dump(config)
Dump a CFNgin Config object as yaml.
Parameters config (Config) – The CFNgin Config object.
Returns The yaml formatted CFNgin Config.
Return type str
runway.cfngin.config.load(config)
Load a CFNgin configuration by modifying syspath, loading lookups, etc.
Parameters config (Config) – The CFNgin config to load.
Returns The CFNgin config provided above.
Return type Config
runway.cfngin.config.parse(raw_config)
Parse a raw yaml formatted CFNgin config.
Parameters raw_config (str) – The raw CFNgin configuration string in yaml format.
Returns The parsed CFNgin config.
Return type Config
runway.cfngin.config.process_remote_sources(raw_config, environment=None)
Stage remote package sources and merge in remote configs.
Parameters
• raw_config (str) – The raw CFNgin configuration string.
• environment (Optional[Dict, Any]) – Any environment values that should be
passed to the config.
Returns The raw CFNgin configuration string.
Return type str
runway.cfngin.config.render(raw_config, environment=None)
Render a config, using it as a template with the environment.
Parameters
• raw_config (str) – The raw CFNgin configuration string.
• environment (Optional[Dict[str, Any]]) – Any environment values that
should be passed to the config.
Returns
The CFNgin configuration populated with any values passed from the environment.
Return type str
runway.cfngin.config.render_parse_load(raw_config, environment=None, validate=True)
Encapsulate the render -> parse -> validate -> load process.
254 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Parameters
• raw_config (str) – The raw CFNgin configuration string.
• environment (Optional[Dict[str, Any]]) – Any environment values that
should be passed to the config.
• validate (bool) – If provided, the config is validated before being loaded.
Returns The parsed CFNgin config.
Return type Config
Subpackages
runway.cfngin.config.translators package
Import modules.
Submodules
runway.cfngin.config.translators.kms module
KMS translator.
Important: The translator is going to be deprecated in favor of the lookup.
runway.cfngin.config.translators.kms.kms_simple_constructor(loader, node)
KMS simple constructor.
runway.cfngin.dag package
CFNgin directed acyclic graph (DAG) implementation.
class runway.cfngin.dag.DAG
Bases: object
Directed acyclic graph implementation.
Instantiate a new DAG with no nodes or edges.
add_edge(ind_node, dep_node)
Add an edge (dependency) between the specified nodes.
Parameters
• ind_node (str) – The independent node to add an edge to.
• dep_node (str) – The dependent node that has a dependency on the ind_node.
Raises
• KeyError – Either the ind_node, or dep_node do not exist.
• DAGValidationError – Raised if the resulting graph is invalid.
9.6. Terraform 255
runway Documentation, Release 1.18.3
add_node(node_name)
Add a node if it does not exist yet, or error out.
Parameters node_name (str) – The unique name of the node to add.
Raises KeyError – Raised if a node with the same name already exist in the graph
add_node_if_not_exists(node_name)
Add a node if it does not exist yet, ignoring duplicates.
Parameters node_name (str) – The name of the node to add.
all_downstreams(node)
Return a list of all nodes downstream in topological order.
Parameters node (str) – The node whose downstream nodes you want to find.
Returns A list of nodes that are downstream from the node.
Return type List[str]
all_leaves()
Return a list of all leaves (nodes with no downstreams).
Returns A list of all the nodes with no downstreams.
Return type List[str]
delete_edge(ind_node, dep_node)
Delete an edge from the graph.
Parameters
• ind_node (str) – The independent node to delete an edge from.
• dep_node (str) – The dependent node that has a dependency on the ind_node.
Raises KeyError – Raised when the edge doesn’t already exist.
delete_node(node_name)
Delete this node and all edges referencing it.
Parameters node_name (str) – The name of the node to delete.
Raises KeyError – Raised if the node does not exist in the graph.
delete_node_if_exists(node_name)
Delete this node and all edges referencing it.
Ignores any node that is not in the graph, rather than throwing an exception.
Parameters node_name (str) – The name of the node to delete.
downstream(node)
Return a list of all nodes this node has edges towards.
Parameters node (str) – The node whose downstream nodes you want to find.
Returns A list of nodes that are immediately downstream from the node.
Return type List[str]
filter(nodes)
Return a new DAG with only the given nodes and their dependencies.
Parameters nodes (list) – The nodes you are interested in.
Returns The filtered graph.
256 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Return type DAG
from_dict(graph_dict)
Reset the graph and build it from the passed dictionary.
The dictionary takes the form of {node_name: [directed edges]}
Parameters graph_dict (Dict[str, Any]) – The dictionary used to create the graph.
Raises TypeError – Raised if the value of items in the dict are not lists.
ind_nodes()
Return a list of all nodes in the graph with no dependencies.
Returns A list of all independent nodes.
Return type List[str]
predecessors(node)
Return a list of all immediate predecessors of the given node.
Parameters node (str) – The node whose predecessors you want to find.
Returns A list of nodes that are immediate predecessors to node.
Return type List[str]
rename_edges(old_node_name, new_node_name)
Change references to a node in existing edges.
Parameters
• old_node_name (str) – The old name for the node.
• new_node_name (str) – The new name for the node.
reset_graph()
Restore the graph to an empty state.
size()
Count of nodes in the graph.
topological_sort()
Return a topological ordering of the DAG.
Returns A list of topologically sorted nodes in the graph.
Return type list
Raises ValueError – Raised if the graph is not acyclic.
transitive_reduction()
Perform a transitive reduction on the DAG.
The transitive reduction of a graph is a graph with as few edges as possible with the same reachability as
the original graph.
See https://en.wikipedia.org/wiki/Transitive_reduction
transpose()
Build a new graph with the edges reversed.
Returns The transposed graph.
Return type runway.cfngin.dag.DAG
validate()
Return (Boolean, message) of whether DAG is valid.
9.6. Terraform 257
runway Documentation, Release 1.18.3
Returns Tuple[bool, str]
walk(walk_func)
Walk each node of the graph in reverse topological order.
This can be used to perform a set of operations, where the next operation depends on the previous operation.
It’s important to note that walking happens serially, and is not parallelized.
Parameters walk_func (types.FunctionType) – The function to be called on each node
of the graph.
exception runway.cfngin.dag.DAGValidationError
Bases: Exception
Raised when DAG validation fails.
class runway.cfngin.dag.ThreadedWalker(semaphore)
Bases: object
Walk a DAG as quickly as the graph topology allows, using threads.
Instantiate class.
Parameters semaphore (threading.Semaphore) – a semaphore object which can be used
to control how many steps are executed in parallel.
walk(dag, walk_func)
Walk each node of the graph, in parallel if it can.
The walk_func is only called when the nodes dependencies have been satisfied.
class runway.cfngin.dag.UnlimitedSemaphore
Bases: object
threading.Semaphore, but acquire always succeeds.
acquire(*args)
Do nothing.
release()
Do nothing.
runway.cfngin.dag.walk(dag, walk_func)
Walk a DAG.
runway.cfngin.hooks package
Import modules.
Submodules
runway.cfngin.hooks.acm module
CFNgin hooks for AWS Certificate Manager.
class runway.cfngin.hooks.acm.Certificate(context, provider, **kwargs)
Bases: runway.cfngin.hooks.base.Hook
Hook for managing a AWS::CertificateManager::Certificate.
Keyword Arguments
258 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
• alt_names (Optional[List[str]]) – Additional FQDNs to be included in the
Subject Alternative Name extension of the ACM certificate. For example, you can add
www.example.net to a certificate for which the domain field is www.example.com if users
can reach your site by using either name.
• domain (str) – The fully qualified domain name (FQDN), such as www.example.com,
with which you want to secure an ACM certificate. Use an asterisk (
*
) to create a wild-
card certificate that protects several sites in the same domain. For example, *.example.com
protects www.example.com, site.example.com, and images.example.com.
• hosted_zone_id (str) – The ID of the Route 53 Hosted Zone that contains the resource
record sets that you want to change. This must exist in the same account that the certificate
will be created in.
• stack_name (Optional[str]) – Provide a name for the stack used to create the cer-
tificate. If not provided, the domain is used (replacing . with -).
• ttl (Optional[int]) – The resource record cache time to live (TTL), in seconds. (de-
fault: 300)
Example: .. code-block: yaml
pre_build:
example-wildcard-cert: path: runway.cfngin.hooks.acm.Certificate required: true args:
domain: ‘*.example.com’ hosted_zone_id: ${xref example-com::HostedZoneId}
Instantiate class.
Parameters
• context (runway.cfngin.context.Context) – Context instance. (passed in by
CFNgin)
• provider (runway.cfngin.providers.base.BaseProvider) – Provider in-
stance. (passed in by CFNgin)
domain_changed()
Check to ensure domain has not changed for existing stack.
get_certificate(interval=5)
Get the certificate being created by a CloudFormation.
Parameters interval (int) – Number of seconds to wait between attempts.
Returns Certificate ARN
Return type str
get_validation_record(cert_arn=None, interval=5, status='PENDING_VALIDATION')
Get validation record from the certificate being created.
Parameters
• cert_arn (str) – ARN of the certificate to validate.
• interval (int) – Number of seconds to wait between attempts.
• status (str) – Validation status to look for when finding a validation record. Typically
only “PENDING_VALIDATION” or “SUCCESS” will be used.
Returns A record set to be added to Route 53.
Return type Dict[str, str]
9.6. Terraform 259
runway Documentation, Release 1.18.3
Raises ValueError – No pending or too many pending certificates.
put_record_set(record_set)
Create/update a record set on a Route 53 Hosted Zone.
Parameters record_set (Dict[str, str]) – Record set to be added to Route 53.
remove_validation_records(records=None)
Remove all record set entries used to validate an ACM Certificate.
Parameters records (Optional[List[Dict[str, str]]]) – List of validation
records to remove from Route 53. This can be provided in cases were the certificate has
been deleted during a rollback.
update_record_set(record_set)
Update a validation record set when the cert has not changed.
Parameters record_set (Dict[str, str]) – Record set to be updated in Route 53.
deploy(status=None)
Deploy an ACM Certificate.
destroy(records=None, skip_r53=False)
Destroy an ACM certificate.
Parameters
• records (Optional[List[Dict[str, str]]]) – List of validation records to
remove from Route 53. This can be provided in cases were the certificate has been deleted
during a rollback.
• skip_r53 (bool) – Skip the removal of validation records.
post_deploy()
Run during the post_deploy stage.
post_destroy()
Run during the post_destroy stage.
pre_deploy()
Run during the pre_deploy stage.
pre_destroy()
Run during the pre_destroy stage.
runway.cfngin.hooks.aws_lambda module
AWS Lambda hook.
runway.cfngin.hooks.aws_lambda.copydir(source, destination, includes, excludes=None, fol-
low_symlinks=False)
Extend the functionality of shutil.
Correctly copies files and directories in a source directory.
Parameters
• source (str) – Source directory.
• destination (str) – Destination directory.
• includes (List[str]) – Glob patterns for files to include.
• excludes (List[str]) – Glob patterns for files to exclude.
260 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
• follow_symlinks (bool) – If true, symlinks will be included in the resulting zip file.
runway.cfngin.hooks.aws_lambda.find_requirements(root)
Identify Python requirement files.
Parameters root (str) – Path that should be searched for files.
Returns Name of supported requirements file and wether it was found. If none are found, None is
returned.
Return type Optional[Dict[str, bool]]
runway.cfngin.hooks.aws_lambda.should_use_docker(dockerize_pip=None)
Assess if Docker should be used based on the value of args.
Parameters dockerize_pip (Union[bool, None, str]) – Value to assess if Docker
should be used for pip.
Returns bool
runway.cfngin.hooks.aws_lambda.handle_requirements(package_root, dest_path, require-
ments, pipenv_timeout=300,
python_path=None,
use_pipenv=False)
Use the correct requirements file.
Parameters
• package_root (str) – Base directory containing a requirements file.
• dest_path (str) – Where to output the requirements file if one needs to be created.
• requirements (Dict[str, bool]) – Map of requirement file names and wether they
exist.
• pipenv_timeout (int) – Seconds to wait for a subprocess to complete.
• python_path (Optional[str]) – Explicit python interpreter to be used. Requirement
file generators must be installed and executable using -m if provided.
• use_pipenv (bool) – Explicitly use pipenv to export a Pipfile as requirements.txt.
Returns Path to the final requirements.txt
Return type str
Raises NotImplementedError – When a requirements file is not found. This should never be
encountered but is included just in case.
runway.cfngin.hooks.aws_lambda.dockerized_pip(work_dir, client=None, runtime=None,
docker_file=None, docker_image=None,
**_kwargs)
Run pip with docker.
Parameters
• work_dir (str) – Work directory for docker.
• client (Optional[docker.DockerClient]) – Custom docker client.
• runtime (Optional[str]) – Lambda runtime. Must provide one of runtime,
docker_file, or docker_image.
• docker_file (Optional[str]) – Path to a Dockerfile to build an image. Must pro-
vide one of runtime, docker_file, or docker_image.
9.6. Terraform 261
runway Documentation, Release 1.18.3
• docker_image (Optional[str]) – Local or remote docker image to use. Must pro-
vide one of runtime, docker_file, or docker_image.
• kwargs (Any) – Advanced options for docker. See source code to determine what is
supported.
Returns Content of the ZIP file as a byte string and calculated hash of all the files
Return type Tuple[str, str]
runway.cfngin.hooks.aws_lambda.select_bucket_region(custom_bucket, hook_region,
cfngin_bucket_region,
provider_region)
Return the appropriate region to use when uploading functions.
Select the appropriate region for the bucket where lambdas are uploaded in.
Parameters
• custom_bucket (Optional[str]) – The custom bucket name provided by the bucket
kwarg of the aws_lambda hook, if provided.
• hook_region (str) – The contents of the bucket_region argument to the hook.
• cfngin_bucket_region (str) – The contents of the cfngin_bucket_region
global setting.
• provider_region (str) – The region being used by the provider.
Returns The appropriate region string.
Return type str
runway.cfngin.hooks.aws_lambda.upload_lambda_functions(context, provider,
**kwargs)
Build Lambda payloads from user configuration and upload them to S3.
Constructs ZIP archives containing files matching specified patterns for each function, uploads the result to
Amazon S3, then stores objects (of type troposphere.awslambda.Code) in the context’s hook data,
ready to be referenced in blueprints.
Configuration consists of some global options, and a dictionary of function specifications. In the specifications,
each key indicating the name of the function (used for generating names for artifacts), and the value determines
what files to include in the ZIP (see more details below).
Payloads are uploaded to either a custom bucket or the CFNgin default bucket, with the key containing it’s
checksum, to allow repeated uploads to be skipped in subsequent runs.
The configuration settings are documented as keyword arguments below.
Parameters
• provider (runway.cfngin.providers.base.BaseProvider) – Provider in-
stance. (passed in by CFNgin)
• context (runway.cfngin.context.Context) – Context instance. (passed in by
CFNgin)
Keyword Arguments
• bucket (Optional[str]) – Custom bucket to upload functions to. Omitting it will
cause the default CFNgin bucket to be used.
• bucket_region (Optional[str]) – The region in which the bucket should exist.
If not given, the region will be either be that of the global cfngin_bucket_region
setting, or else the region in use by the provider.
262 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
• prefix (Optional[str]) – S3 key prefix to prepend to the uploaded zip name.
• follow_symlinks (Optional[bool]) – Will determine if symlinks should be fol-
lowed and included with the zip artifact. (default: False)
• payload_acl (Optional[str]) – The canned S3 object ACL to be applied to the
uploaded payload. (default: private)
• functions (Dict[str, Any]) – Configurations of desired payloads to build. Keys
correspond to function names, used to derive key names for the payload. Each value should
itself be a dictionary, with the following data:
docker_file (Optional[str]) Path to a local DockerFile that will be built and used for
dockerize_pip. Must provide exactly one of docker_file, docker_image,
or runtime.
docker_image (Optional[str]) Custom Docker image to use with dockerize_pip.
Must provide exactly one of docker_file, docker_image, or runtime.
dockerize_pip (Optional[Union[str, bool]]) Whether to use Docker when preparing pack-
age dependencies with pip. Can be set to True/False or the special string ‘non-linux’
which will only run on non Linux systems. To use this option Docker must be installed.
exclude (Optional[Union[str, List[str]]]) Pattern or list of patterns of files to exclude from
the payload. If provided, any files that match will be ignored, regardless of whether they
match an inclusion pattern.
Commonly ignored files are already excluded by default, such as .git, .svn,
__pycache__,
*
.pyc, .gitignore, etc.
include (Optional[Union[str, List[str]]]) Pattern or list of patterns of files to include in the
payload. If provided, only files that match these patterns will be included in the payload.
Omitting it is equivalent to accepting all files that are not otherwise excluded.
path (str) Base directory of the Lambda function payload content. If it not an absolute
path, it will be considered relative to the directory containing the CFNgin configuration
file in use.
Files in this directory will be added to the payload ZIP, according to the include and
exclude patterns. If no patterns are provided, all files in this directory (respecting default
exclusions) will be used.
Files are stored in the archive with path names relative to this directory. So, for example,
all the files contained directly under this directory will be added to the root of the ZIP file.
pipenv_lock_timeout (Optional[int]) Time in seconds to wait while creating lock file with
pipenv.
pipenv_timeout (Optional[int]) Time in seconds to wait while running pipenv.
python_path (Optional[str]) Absolute path to a python interpreter to use for
pip/pipenv actions. If not provided, the current python interpreter will be used
for pip and pipenv will be used from the current $PATH.
runtime (Optional[str]) Runtime of the AWS Lambda Function being uploaded. Used
with dockerize_pip to automatically select the appropriate Docker image to use.
Must provide exactly one of docker_file, docker_image, or runtime.
use_pipenv (Optional[bool]) Explicitly use Pipfile/Pipfile.lock to prepare package depen-
dencies even if a requirements.txt file is found.
9.6. Terraform 263
runway Documentation, Release 1.18.3
Examples
pre_build:
upload_functions:
path: runway.cfngin.hooks.aws_lambda.upload_lambda_functions
required: true
enabled: true
data_key: lambda
args:
bucket: custom-bucket
follow_symlinks: true
prefix: cloudformation-custom-resources/
payload_acl: authenticated-read
functions:
MyFunction:
path: ./lambda_functions
dockerize_pip: non-linux
use_pipenv: true
runtime: python3.8
include:
- '
*
.py'
- '
*
.txt'
exclude:
- '
*
.pyc'
- test/
from troposphere.awslambda import Function
from runway.cfngin.blueprints.base import Blueprint
class LambdaBlueprint(Blueprint):
def create_template(self):
code = self.context.hook_data['lambda']['MyFunction']
self.template.add_resource(
Function(
'MyFunction',
Code=code,
Handler='my_function.handler',
Role='...',
Runtime='python2.7'
)
)
runway.cfngin.hooks.base module
Base class for CFNgin hooks.
class runway.cfngin.hooks.base.Hook(context, provider, **kwargs)
Bases: object
Base class for hooks.
Not all hooks need to be classes and not all classes need to be hooks.
args
Keyword arguments passed to the hook, loaded into a MutableMap object.
Type MutableMap
264 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
blueprint
Blueprint generated by the hook if it will be deploying a stack.
Type Optional[Blueprint]
context
Context instance. (passed in by CFNgin)
Type Context
provider
Provider instance. (passed in by CFNgin)
Type BaseProvider
stack
Stack object if the hook deploys a stack.
Type Optional[Stack]
stack_name
Name of the stack created by the hook if a stack is to be created.
Type str
Instantiate class.
Parameters
• context (runway.cfngin.context.Context) – Context instance. (passed in by
CFNgin)
• provider (runway.cfngin.providers.base.BaseProvider) – Provider in-
stance. (passed in by CFNgin)
property tags
Return tags that should be applied to any resource being created.
Returns troposphere.Tags
generate_stack(**kwargs)
Create a CFNgin Stack object.
Returns Stack
get_template_description(suffix=None)
Generate a template description.
Parameters suffix (Optional[str]) – Suffix to append to the end of a CloudFormation
template description.
Returns CloudFormation template description.
Return type str
deploy_stack(stack=None, wait=False)
Deploy a stack.
Parameters
• stack (Optional[Stack]) – A stack to act on.
• wait (bool) – Wither to wait for the stack to complete before returning.
Returns Ending status of the stack.
Return type Status
9.6. Terraform 265
runway Documentation, Release 1.18.3
destroy_stack(stack=None, wait=None)
Destroy a stack.
Parameters
• stack (Optional[Stack]) – A stack to act on.
• wait (bool) – Wither to wait for the stack to complete before returning.
Returns Ending status of the stack.
Return type Status
post_deploy()
Run during the post_deploy stage.
post_destroy()
Run during the post_destroy stage.
pre_deploy()
Run during the pre_deploy stage.
pre_destroy()
Run during the pre_destroy stage.
class runway.cfngin.hooks.base.HookBuildAction(context, provider)
Bases: runway.cfngin.actions.build.Action
Build action that can be used from hooks.
Instantiate class.
Parameters
• context (runway.cfngin.context.Context) – The context for the current run.
• provider (runway.cfngin.providers.base.BaseProvider) – The provider
instance.
property provider
Override the inherited property to return the local provider.
build_provider(stack)
Override the inherited method to always return local provider.
run(**kwargs)
Run the action for one stack.
class runway.cfngin.hooks.base.HookDestroyAction(context, provider)
Bases: runway.cfngin.hooks.base.HookBuildAction
Destroy action that can be used from hooks.
Instantiate class.
Parameters
• context (runway.cfngin.context.Context) – The context for the current run.
• provider (runway.cfngin.providers.base.BaseProvider) – The provider
instance.
run(**kwargs)
Run the action for one stack.
266 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
class runway.cfngin.hooks.base.HookStackDefinition(name, **kwargs)
Bases: collections.UserDict, object
Stack definition for use in hooks to avoid cyclic imports.
Instantiate class.
runway.cfngin.hooks.command module
Command hook.
runway.cfngin.hooks.command.run_command(provider, context, command, capture=False, inter-
active=False, ignore_status=False, quiet=False,
stdin=None, env=None, **kwargs)
Run a custom command as a hook.
Parameters
• provider (runway.cfngin.providers.base.BaseProvider) – Provider in-
stance. (passed in by CFNgin)
• context (runway.cfngin.context.Context) – Context instance. (passed in by
CFNgin)
Keyword Arguments
• command (Union[str, List[str]]) – Command(s) to run.
• capture (bool) – If enabled, capture the command’s stdout and stderr, and return them
in the hook result. (default: False)
• interactive (bool) – If enabled, allow the command to interact with stdin. Otherwise,
stdin will be set to the null device. (default: False)
• ignore_status (bool) – Don’t fail the hook if the command returns a non-zero status.
(default: False)
• quiet (bool) – Redirect the command’s stdout and stderr to the null device, silencing all
output. Should not be enabled if capture is also enabled. (default: False)
• stdin (Optional[str]) – String to send to the stdin of the command. Implicitly dis-
ables interactive.
• env (Optional[Dict[str, str]]) – Dictionary of environment variable overrides
for the command context. Will be merged with the current environment.
•
**
kwargs (Any) – Any other arguments will be forwarded to the subprocess.Popen
function. Interesting ones include: cwd and shell.
Examples
pre_build:
command_copy_environment:
path: runway.cfngin.hooks.command.run_command
required: true
enabled: true
data_key: copy_env
args:
command: ['cp', 'environment.template', 'environment']
command_git_rev_parse:
(continues on next page)
9.6. Terraform 267
runway Documentation, Release 1.18.3
(continued from previous page)
path: runway.cfngin.hooks.command.run_command
required: true
enabled: true
data_key: get_git_commit
args:
command: ['git', 'rev-parse', 'HEAD']
cwd: ./my-git-repo
capture: true
command_npm_install:
path: runway.cfngin.hooks.command.run_command
args:
command: '`cd $PROJECT_DIR/project; npm install`'
env:
PROJECT_DIR: ./my-project
shell: true
runway.cfngin.hooks.ecs module
AWS ECS hook.
A lot of this code exists to deal w/ the broken ECS connect_to_region function, and will be removed once this pull
request is accepted: https://github.com/boto/boto/pull/3143
runway.cfngin.hooks.ecs.create_clusters(provider, context, **kwargs)
Create ECS clusters.
Parameters
• provider (runway.cfngin.providers.base.BaseProvider) – Provider in-
stance. (passed in by CFNgin)
• context (runway.cfngin.context.Context) – Context instance. (passed in by
CFNgin)
Keyword Arguments clusters (List[str]) – Names of clusters to create.
Returns Whether or not the hook succeeded.
Return type bool
runway.cfngin.hooks.iam module
AWS IAM hook.
runway.cfngin.hooks.iam.create_ecs_service_role(provider, context, **kwargs)
Create ecsServieRole, which has to be named exactly that currently.
http://docs.aws.amazon.com/AmazonECS/latest/developerguide/IAM_policies.html#service_IAM_role
Parameters
• provider (runway.cfngin.providers.base.BaseProvider) – Provider in-
stance. (passed in by CFNgin)
• context (runway.cfngin.context.Context) – Context instance. (passed in by
CFNgin)
Keyword Arguments role_name (str) – Name of the role to create. (default: ecsServiceRole)
268 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Returns Whether or not the hook succeeded.
Return type bool
runway.cfngin.hooks.iam.ensure_server_cert_exists(provider, context, **kwargs)
Ensure server cert exists.
Parameters
• provider (runway.cfngin.providers.base.BaseProvider) – Provider in-
stance. (passed in by CFNgin)
• context (runway.cfngin.context.Context) – Context instance. (passed in by
CFNgin)
Keyword Arguments
• cert_name (str) – Name of the certificate that should exist.
• prompt (bool) – Whether to prompt to upload a certificate if one does not exist. (default:
True)
Returns
Dict containing status, cert_name, and cert_arn.
Return type Dict[str, str]
runway.cfngin.hooks.keypair module
AWS EC2 keypair hook.
runway.cfngin.hooks.keypair.get_existing_key_pair(ec2, keypair_name)
Get existing keypair.
runway.cfngin.hooks.keypair.import_key_pair(ec2, keypair_name, public_key_data)
Import keypair.
runway.cfngin.hooks.keypair.read_public_key_file(path)
Read public key file.
runway.cfngin.hooks.keypair.create_key_pair_from_public_key_file(ec2, key-
pair_name,
pub-
lic_key_path)
Create keypair from public key file.
runway.cfngin.hooks.keypair.create_key_pair_in_ssm(ec2, ssm, keypair_name, parame-
ter_name, kms_key_id=None)
Create keypair in SSM.
runway.cfngin.hooks.keypair.create_key_pair(ec2, keypair_name)
Create keypair.
runway.cfngin.hooks.keypair.create_key_pair_local(ec2, keypair_name, dest_dir)
Create local keypair.
runway.cfngin.hooks.keypair.interactive_prompt(keypair_name)
Interactive prompt.
runway.cfngin.hooks.keypair.ensure_keypair_exists(provider, context, **kwargs)
Ensure a specific keypair exists within AWS.
If the key doesn’t exist, upload it.
9.6. Terraform 269
runway Documentation, Release 1.18.3
Parameters
• provider (runway.cfngin.providers.base.BaseProvider) – Provider in-
stance. (passed in by CFNgin)
• context (runway.cfngin.context.Context) – Context instance. (passed in by
CFNgin)
Keyword Arguments
• keypair (str) – Name of the key pair to create
• ssm_parameter_name (Optional[str]) – Path to an SSM store parameter to re-
ceive the generated private key, instead of importing it or storing it locally.
• ssm_key_id (Optional[str]) – ID of a KMS key to encrypt the SSM parameter with.
If omitted, the default key will be used.
• public_key_path (Optional[str]) – Path to a public key file to be imported in-
stead of generating a new key. Incompatible with the SSM options, as the private key will
not be available for storing.
Returns
In case of failure False, otherwise a dict containing:
status (str): Ene of exists, imported or created.
key_name (str): Name of the key pair.
fingerprint (str): Fingerprint of the key pair.
file_path (Optional[str]): If a new key was created, the path to the file where the private key
was stored.
Return type Union[bool, Dict[str, Optional[str]]]
runway.cfngin.hooks.route53 module
AWS Route 53 hook.
runway.cfngin.hooks.route53.create_domain(provider, context, **kwargs)
Create a domain within route53.
Parameters
• provider (runway.cfngin.providers.base.BaseProvider) – Provider in-
stance. (passed in by CFNgin)
• context (runway.cfngin.context.Context) – Context instance. (passed in by
CFNgin)
Keyword Arguments domain (str) – Domain name for the Route 53 hosted zone to be created.
Returns Dict containing domain and zone_id.
Return type Dict[str, str]
270 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
runway.cfngin.hooks.utils module
Hook utils.
class runway.cfngin.hooks.utils.BlankBlueprint(name, context, mappings=None, de-
scription=None)
Bases: runway.cfngin.blueprints.base.Blueprint
Blueprint that can be built programatically.
Instantiate class.
Parameters
• name (str) – A name for the blueprint.
• context (runway.cfngin.context.Context) – Context the blueprint is being ex-
ecuted under.
• mappings (dict, optional) – CloudFormation Mappings to be used in the template.
• description (str) – Used to describe the resulting CloudFormation template.
create_template()
Create template without raising NotImplementedError.
runway.cfngin.hooks.utils.full_path(path)
Return full path.
runway.cfngin.hooks.utils.handle_hooks(stage, hooks, provider, context)
Handle pre/post_build hooks.
These are pieces of code that we want to run before/after the builder builds the stacks.
Parameters
• stage (str) – The current stage (pre_run, post_run, etc).
• hooks (List[runway.cfngin.config.Hook]) – Hooks to execute.
• provider (runway.cfngin.providers.base.BaseProvider) – Provider in-
stance.
• context (runway.cfngin.context.Context) – Context instance.
Subpackages
runway.cfngin.hooks.docker package
Docker hook.
runway.cfngin.hooks.docker.login(**kwargs)
Docker login hook.
Replicates the functionality of docker login cli command.
Keyword Arguments
• dockercfg_path (Optional[str]) – Use a custom path for the Docker config file
(default $HOME/.docker/config.json if present, otherwise``$HOME/.dockercfg``).
• ecr (runway.cfngin.hooks.docker._data_models.
ElasticContainerRegistry) – Information describing an ECR registry.
9.6. Terraform 271
runway Documentation, Release 1.18.3
• email (Optional[str]) – The email for the registry account.
• password (str) – The plaintext password.
• registry (Optional[str]) – URL to the registry (e.g. https://index.
docker.io/v1/)
• username (str) – The registry username. Optional if supplying ecr.
Submodules
runway.cfngin.hooks.docker.data_models module
Hook data models.
These are makeshift data models for use until Runway v2 is realeased and pydantic can be used.
class runway.cfngin.hooks.docker.data_models.BaseModel
Bases: object
Base model.
dict()
Return object as a dict.
find(query, default=None, **kwargs)
Find a value in the object.
get(name, default=None)
Get a value or return default if it is not found.
Attr: name: The value to look for. default: Returned if no other value is found.
classmethod parse_obj(obj, context=None)
Parse object.
class runway.cfngin.hooks.docker.data_models.ElasticContainerRegistry(account_id=None,
alias=None,
aws_region=None,
**kwargs)
Bases: runway.cfngin.hooks.docker.data_models.BaseModel
AWS Elastic Container Registry.
Instantiate class.
PUBLIC_URI_TEMPLATE = 'public.ecr.aws/{registry_alias}/'
URI_TEMPLATE = '{aws_account_id}.dkr.ecr.{aws_region}.amazonaws.com/'
property fqn
Fully qualified ECR name.
class runway.cfngin.hooks.docker.data_models.DockerImage(image)
Bases: runway.cfngin.hooks.docker.data_models.BaseModel
Wrapper for docker.models.images.Image.
Instantiate class.
property id
ID of the image.
272 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
property repo
Repository URI.
property short_id
`` prefix.
Type ID of the image truncated to 10 characters plus the ``sha256
property tags
List of image tags.
property uri
Return a mapping of tag to image URI.
class runway.cfngin.hooks.docker.data_models.ElasticContainerRegistryRepository(repo_name,
ac-
count_id=None,
aws_region=None,
reg-
istry_alias=None,
**kwargs)
Bases: runway.cfngin.hooks.docker.data_models.BaseModel
AWS Elastic Container Registry (ECR) Repository.
Instantiace class.
Parameters
• account_id – AWS account ID.
• aws_region – AWS region.
• registry_alias – Alias of a public ECR registry.
• repo_name – Name of the ECR repository.
property fqn
Fully qualified ECR repo name.
runway.cfngin.hooks.docker.hook_data module
Docker hook_data object.
class runway.cfngin.hooks.docker.hook_data.DockerHookData(**kwargs)
Bases: runway.util.MutableMap
Docker hook_data object.
Initialize class.
Provided kwargs are added to the object as attributes.
9.6. Terraform 273
runway Documentation, Release 1.18.3
Example
image = None
client
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
update_context(context=None)
Update context object with new the current DockerHookData.
classmethod from_cfngin_context(context=None)
Get existing object or create a new one.
Subpackages
runway.cfngin.hooks.docker.image package
Docker image actions.
Replicates the functionality of docker image CLI commands.
runway.cfngin.hooks.docker.image.build(**kwargs)
Docker image build hook.
Replicates the functionality of docker image build CLI command.
runway.cfngin.hooks.docker.image.push(**kwargs)
Docker image push hook.
Replicates the functionality of docker image push CLI command.
runway.cfngin.hooks.docker.image.remove(**kwargs)
Docker image push remove.
Replicates the functionality of docker image push CLI command.
runway.cfngin.hooks.ecr package
AWS Elastic Container Registry (ECR) hook.
runway.cfngin.hooks.ecr.purge_repository(context, repository_name, **_)
Purge all images from an ECR repository.
runway.cfngin.logger package
CFNgin logger.
class runway.cfngin.logger.ColorFormatter(fmt=None, datefmt=None, style='%')
Bases: logging.Formatter
Handles colorizing formatted log messages if color provided.
Initialize the formatter with specified format strings.
274 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Initialize the formatter either with the specified format string, or a default as described above. Allow for spe-
cialized date formatting with the optional datefmt argument. If datefmt is omitted, you get an ISO8601-like (or
RFC 3339-like) format.
Use a style parameter of ‘%’, ‘{‘ or ‘$’ to specify that you want to use one of %-formatting, str.format()
({}) formatting or string.Template formatting in your format string.
Changed in version 3.2: Added the style parameter.
format(record)
Format log message.
runway.cfngin.logger.setup_logging(verbosity, formats=None)
Configure a proper logger based on verbosity and optional log formats.
Parameters
• verbosity (int) – 0, 1, 2
• formats (Optional[Dict[str, Any]]) – Keys (info, color, debug) which
may override the associated default log formats.
runway.cfngin.lookups package
CFNgin lookups.
Submodules
runway.cfngin.lookups.registry module
CFNgin lookup registry.
runway.cfngin.lookups.registry.register_lookup_handler(lookup_type, han-
dler_or_path)
Register a lookup handler.
Parameters
• lookup_type (str) – Name to register the handler under.
• handler_or_path (Union[Callable, str]) – A function or a path to a handler.
runway.cfngin.lookups.registry.unregister_lookup_handler(lookup_type)
Unregister the specified lookup type.
This is useful when testing various lookup types if you want to unregister the lookup type after the test runs.
Parameters lookup_type (str) – Name of the lookup type to unregister.
runway.cfngin.lookups.registry.resolve_lookups(variable, context, provider)
Resolve a set of lookups.
Parameters
• variable (runway.cfngin.variables.Variable) – The variable resolving it’s
lookups.
• context (runway.cfngin.context.Context) – Context instance.
• provider (runway.cfngin.providers.base.BaseProvider) – Provider in-
stance.
9.6. Terraform 275
runway Documentation, Release 1.18.3
Returns Lookup -> resolved value
Return type Dict[str, Any]
Subpackages
runway.cfngin.lookups.handlers package
Import modules.
Submodules
runway.cfngin.lookups.handlers.ami module
AMI lookup.
exception runway.cfngin.lookups.handlers.ami.ImageNotFound(search_string)
Bases: Exception
Image not found.
Instantiate class.
class runway.cfngin.lookups.handlers.ami.AmiLookup
Bases: runway.lookups.handlers.base.LookupHandler
AMI lookup.
classmethod handle(value, context=None, provider=None, **kwargs)
Fetch the most recent AMI Id using a filter.
Parameters
• value (str) – Parameter(s) given to this lookup.
• context (runway.cfngin.context.Context) – Context instance.
• provider (runway.cfngin.providers.base.BaseProvider) – Provider
instance.
Returns Looked up value.
Return type str
Example
The above fetches the most recent AMI where owner is self account or amazon and the ami name matches
the regex described, the architecture will be either x64 or i386
You can also optionally specify the region in which to perform the AMI lookup.
Valid arguments:
owners (comma delimited) REQUIRED ONCE: aws_account_id | amazon | self
name_regex (a regex) REQUIRED ONCE: e.g. my-ubuntu-server-[0-9]+
executable_users (comma delimited) OPTIONAL ONCE: aws_account_id | amazon | self
276 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Any other arguments specified are sent as filters to the aws api For example, architecture:x86_64
will add a filter
runway.cfngin.lookups.handlers.default module
Lookup to provide a default value.
class runway.cfngin.lookups.handlers.default.DefaultLookup
Bases: runway.lookups.handlers.base.LookupHandler
Lookup to provide a default value.
classmethod handle(value, context=None, provider=None, **kwargs)
Use a value from the environment or fall back to a default value.
Allows defaults to be set at the config file level.
Parameters
• value (str) – Parameter(s) given to this lookup. <env_var>::<default value>
• context (runway.cfngin.context.Context) – Context instance.
• provider (runway.cfngin.providers.base.BaseProvider) – Provider
instance.
Returns Looked up value
Return type str
Example
Groups: ${default app_security_groups::sg-12345,sg-67890}
If app_security_groups is defined in the environment, its defined value will be returned. Otherwise,
sg-12345,sg-67890 will be thereturned value.
runway.cfngin.lookups.handlers.dynamodb module
DynamoDB lookup.
class runway.cfngin.lookups.handlers.dynamodb.DynamodbLookup
Bases: runway.lookups.handlers.base.LookupHandler
DynamoDB lookup.
classmethod handle(value, context=None, provider=None, **kwargs)
Get a value from a DynamoDB table.
Parameters
• value (str) – Parameter(s) given to this lookup.
[<region>:]<tablename>@<primarypartionkey>:<keyvalue>.
<keyvalue>...
• context (runway.cfngin.context.Context) – Context instance.
• provider (runway.cfngin.providers.base.BaseProvider) – Provider
instance.
9.6. Terraform 277
runway Documentation, Release 1.18.3
Note: The region is optional, and defaults to the environment’s AWS_DEFAULT_REGION if not specified.
runway.cfngin.lookups.handlers.envvar module
Environment variable lookup.
class runway.cfngin.lookups.handlers.envvar.EnvvarLookup
Bases: runway.lookups.handlers.base.LookupHandler
Environment variable lookup.
classmethod handle(value, context=None, provider=None, **kwargs)
Retrieve an environment variable.
Parameters
• value (str) – Parameter(s) given to this lookup.
• context (runway.cfngin.context.Context) – Context instance.
• provider (runway.cfngin.providers.base.BaseProvider) – Provider
instance.
Example
# With CFNgin we would reference the environment variable like this:
conf_key: ${envvar ENV_VAR_NAME}
You can optionally store the value in a file, ie:
$ cat envvar_value.txt
ENV_VAR_NAME
and reference it within CFNgin (NOTE: the path should be relative to the CFNgin config file):
conf_key: ${envvar file://envvar_value.txt}
# Both of the above would resolve to
conf_key: ENV_VALUE
runway.cfngin.lookups.handlers.file module
File lookup.
class runway.cfngin.lookups.handlers.file.FileLookup
Bases: runway.lookups.handlers.base.LookupHandler
File lookup.
classmethod handle(value, context=None, provider=None, **kwargs)
Translate a filename into the file contents.
Parameters
• value (str) – Parameter(s) given to this lookup.
278 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
• context (runway.cfngin.context.Context) – Context instance.
• provider (runway.cfngin.providers.base.BaseProvider) – Provider
instance.
Fields should use the following format:
<codec>:<path>
Example:
# We've written a file to /some/path:
$ echo "hello there" > /some/path
# With CFNgin we would reference the contents of this file with the
# following
conf_key: ${file plain:file://some/path}
# The above would resolve to
conf_key: hello there
# Or, if we used wanted a base64 encoded copy of the file data
conf_key: ${file base64:file://some/path}
# The above would resolve to
conf_key: aGVsbG8gdGhlcmUK
Supported codecs:
plain Plain Text
base64 Encode the plain text file at the given path with base64 prior to returning it.
parameterized The same as plain, but additionally supports referencing template parameters to create
userdata that’s supplemented with information from the template, as is commonly needed in EC2
UserData. For example, given a template parameter of BucketName, the file could contain the follow-
ing text:
#!/bin/sh
aws s3 sync s3://{{BucketName}}/somepath /somepath
Then you could use something like this in the YAML config file:
UserData: ${file parameterized:/path/to/file}
Resulting in the UserData parameter being defined as:
{ "Fn::Join" : ["", [
"#!/bin/sh\\naws s3 sync s3://",
{"Ref" : "BucketName"},
"/somepath /somepath"
]] }
parameterized-b64 The same as parameterized, with the results additionally wrapped in {
"Fn::Base64": ... } , which is what you actually need for EC2 UserData.
When using parameterized-b64 for UserData, you should use a variable defined as such:
9.6. Terraform 279
runway Documentation, Release 1.18.3
from troposphere import AWSHelperFn
"UserData": {
"type": AWSHelperFn,
"description": "Instance user data",
"default": Ref("AWS::NoValue")
}
Then assign UserData in a LaunchConfiguration or Instance to self.
get_variables()["UserData"]. Note that we use AWSHelperFn as the type because
the parameterized-b64 codec returns either a Base64 or a GenericHelperFn troposphere object.
json Decode the file as JSON and return the resulting object
json-parameterized Same as json, but applying templating rules from parameterized to every ob-
ject value. Note that object keys are not modified. Example (an external PolicyDocument):
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"some:Action"
],
"Resource": "{{MyResource}}"
}
]
}
yaml Decode the file as YAML and return the resulting object. All strings are returned as unicode even
in Python 2.
yaml-parameterized Same as json-parameterized, but using YAML. Example:
Version: 2012-10-17
Statement:
- Effect: Allow
Action:
- "some:Action"
Resource: "{{MyResource}}"
runway.cfngin.lookups.handlers.file.parameterized_codec(raw, b64)
Parameterize a string, possibly encoding it as Base64 afterwards.
Parameters
• raw (Union[bytes, str]) – String to be processed. Byte strings will be interpreted
as UTF-8.
• b64 (bool) – Whether to wrap the output in a Base64 CloudFormation call.
Returns Output to be included in a CloudFormation template.
Return type troposphere.AWSHelperFn
class runway.cfngin.lookups.handlers.file.SafeUnicodeLoader(stream)
Bases: yaml.loader.SafeLoader
Safe unicode loader.
280 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Initialize the scanner.
construct_yaml_str(node)
Construct yaml str.
runway.cfngin.lookups.handlers.file.yaml_codec(raw, parameterized=False)
YAML codec.
runway.cfngin.lookups.handlers.file.json_codec(raw, parameterized=False)
JSON codec.
runway.cfngin.lookups.handlers.hook_data module
Hook data lookup.
class runway.cfngin.lookups.handlers.hook_data.HookDataLookup
Bases: runway.lookups.handlers.base.LookupHandler
Hook data lookup.
DEPRECATION_MSG = 'lookup query syntax "<hook_name>::<key>" has been deprecated; to learn how to use the new lookup query syntax visit https://docs.onica.com/projects/runway/page/lookups.html'
classmethod legacy_parse(value)
Retain support for legacy lookup syntax.
Parameters value (str) – Parameter(s) given to this lookup.
Format of value: <hook_name>::<key>
classmethod handle(value, context=None, provider=None, **kwargs)
Return the data from hook_data.
Parameters
• value (str) – Parameter(s) given to this lookup.
• context (runway.cfngin.context.Context) – Context instance.
• provider (runway.cfngin.providers.base.BaseProvider) – Provider
instance.
runway.cfngin.lookups.handlers.kms module
AWS KMS lookup.
class runway.cfngin.lookups.handlers.kms.KmsLookup
Bases: runway.lookups.handlers.base.LookupHandler
AWS KMS lookup.
classmethod handle(value, context=None, provider=None, **kwargs)
Decrypt the specified value with a master key in KMS.
Parameters
• value (str) – Parameter(s) given to this lookup.
• context (runway.cfngin.context.Context) – Context instance.
• provider (runway.cfngin.providers.base.BaseProvider) – Provider
instance.
9.6. Terraform 281
runway Documentation, Release 1.18.3
value should be in the following format:
[<region>@]<base64 encrypted value>
Example
# We use the aws cli to get the encrypted value for the string
# "PASSWORD" using the master key called "myKey" in
# us-east-1
$ aws --region us-east-1 kms encrypt --key-id alias/myKey \
--plaintext "PASSWORD" --output text --query CiphertextBlob
CiD6bC8t2Y<...encrypted blob...>
# With CFNgin we would reference the encrypted value like:
conf_key: ${kms us-east-1@CiD6bC8t2Y<...encrypted blob...>}
You can optionally store the encrypted value in a file, ie:
kms_value.txt
us-east-1@CiD6bC8t2Y<...encrypted blob...>
and reference it within CFNgin (NOTE: the path should be relative to the CFNgin config file):
conf_key: ${kms file://kms_value.txt}
# Both of the above would resolve to
conf_key: PASSWORD
runway.cfngin.lookups.handlers.output module
AWS CloudFormation Output lookup.
class runway.cfngin.lookups.handlers.output.Output(stack_name, output_name)
Bases: tuple
Create new instance of Output(stack_name, output_name)
property output_name
Alias for field number 1
property stack_name
Alias for field number 0
class runway.cfngin.lookups.handlers.output.OutputLookup
Bases: runway.lookups.handlers.base.LookupHandler
AWS CloudFormation Output lookup.
classmethod handle(value, context=None, provider=None, **kwargs)
Fetch an output from the designated stack.
Parameters
• value (str) – Parameter(s) given to this lookup.
<stack_name>::<output_name>
• context (runway.cfngin.context.Context) – Context instance.
282 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
• provider (runway.cfngin.providers.base.BaseProvider) – Provider
instance.
Returns Output from the specified stack.
Return type str
classmethod dependencies(lookup_data)
Calculate any dependencies required to perform this lookup.
Note that lookup_data may not be (completely) resolved at this time.
Parameters lookup_data (VariableValue) – Parameter(s) given to this lookup.
Returns Stack names this lookup depends on.
Return type Set[str]
runway.cfngin.lookups.handlers.output.deconstruct(value)
Deconstruct the value.
runway.cfngin.lookups.handlers.rxref module
Handler for fetching outputs from a stack in the current namespace.
class runway.cfngin.lookups.handlers.rxref.RxrefLookup
Bases: runway.lookups.handlers.base.LookupHandler
Rxref lookup.
classmethod handle(value, context=None, provider=None, **kwargs)
Fetch an output from the designated stack in the current namespace.
The output lookup supports fetching outputs from stacks created within a single config file. Sometimes
it’s useful to fetch outputs from stacks created outside of the current config file but using the same names-
pace. rxref supports this by using the runway.cfngin.context.Context to expand the fqn of
the stack.
Parameters
• value (str) – Parameter(s) given to this lookup.
<stack_name>::<output_name>
• context (runway.cfngin.context.Context) – Context instance.
• provider (runway.cfngin.providers.base.BaseProvider) – Provider
instance.
Returns Output from the specified stack.
Return type str
9.6. Terraform 283
runway Documentation, Release 1.18.3
Example
conf_value: ${rxref relative-stack-name::SomeOutputName}
runway.cfngin.lookups.handlers.split module
Split lookup.
class runway.cfngin.lookups.handlers.split.SplitLookup
Bases: runway.lookups.handlers.base.LookupHandler
Split lookup.
classmethod handle(value, context=None, provider=None, **kwargs)
Split the supplied string on the given delimiter, providing a list.
Parameters
• value (str) – Parameter(s) given to this lookup.
• context (runway.cfngin.context.Context) – Context instance.
• provider (runway.cfngin.providers.base.BaseProvider) – Provider
instance.
Returns Looked up value.
Return type str
Format of value:
<delimiter>::<value>
Example
Subnets: ${split ,::subnet-1,subnet-2,subnet-3}
Would result in the variable Subnets getting a list consisting of:
["subnet-1", "subnet-2", "subnet-3"]
This is particularly useful when getting an output from another stack that contains a list. For example,
the standard vpc blueprint outputs the list of Subnets it creates as a pair of Outputs (PublicSubnets,
PrivateSubnets) that are comma separated, so you could use this in your config:
Subnets: ${split ,::${output vpc::PrivateSubnets}}
284 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
runway.cfngin.lookups.handlers.ssmstore module
AWS SSM Parameter Store lookup.
class runway.cfngin.lookups.handlers.ssmstore.SsmstoreLookup
Bases: runway.lookups.handlers.base.LookupHandler
AWS SSM Parameter Store lookup.
DEPRECATION_MSG = 'ssmstore lookup has been deprecated; use the ssm lookup instead'
classmethod handle(value, context=None, provider=None, **kwargs)
Retrieve (and decrypt) a parameter from AWS SSM Parameter Store.
Parameters
• value (str) – Parameter(s) given to this lookup.
• context (runway.cfngin.context.Context) – Context instance.
• provider (runway.cfngin.providers.base.BaseProvider) – Provider
instance.
Returns Looked up value.
Return type str
value should be in the following format:
[<region>@]ssmkey
Note: The region is optional, and defaults to us-east-1 if not given.
Example
# In CFNgin we would reference the encrypted value like:
conf_key: ${ssmstore us-east-1@ssmkey}
You can optionally store the value in a file, ie:
ssmstore_value.txt
us-east-1@ssmkey
and reference it within CFNgin (NOTE: the path should be relative to the CFNgin config file):
conf_key: ${ssmstore file://ssmstore_value.txt}
# Both of the above would resolve to
conf_key: PASSWORD
9.6. Terraform 285
runway Documentation, Release 1.18.3
runway.cfngin.lookups.handlers.xref module
Handler for fetching outputs from fully qualified stacks.
class runway.cfngin.lookups.handlers.xref.XrefLookup
Bases: runway.lookups.handlers.base.LookupHandler
Xref lookup.
DEPRECATION_MSG = 'xref Lookup has been deprecated; use the cfn lookup instead'
classmethod handle(value, context=None, provider=None, **kwargs)
Fetch an output from the designated, fully qualified stack.
The output handler supports fetching outputs from stacks created within a single config file. Sometimes
it’s useful to fetch outputs from stacks created outside of the current config file. xref supports this by not
using the runway.cfngin.context.Context to expand the fqn of the stack.
Parameters
• value (str) – Parameter(s) given to this lookup.
<stack_name>::<output_name>
• context (runway.cfngin.context.Context) – Context instance.
• provider (runway.cfngin.providers.base.BaseProvider) – Provider
instance.
Returns Output from the specified stack.
Return type str
Example
conf_value: ${xref fully-qualified-stack-name::SomeOutputName}
runway.cfngin.providers package
Import modules.
Submodules
runway.cfngin.providers.base module
Provider base class.
runway.cfngin.providers.base.not_implemented(method)
Wrap NotImplimentedError with a formatted message.
class runway.cfngin.providers.base.BaseProviderBuilder
Bases: object
ProviderBuilder base class.
build(region=None)
Abstract method.
286 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
class runway.cfngin.providers.base.BaseProvider
Bases: object
Provider base class.
get_stack(stack_name, *args, **kwargs)
Abstract method.
create_stack(*args, **kwargs)
Abstract method.
update_stack(*args, **kwargs)
Abstract method.
destroy_stack(stack, *args, **kwargs)
Abstract method.
get_stack_status(stack, *args, **kwargs)
Abstract method.
get_outputs(stack_name, *args, **kwargs)
Abstract method.
get_output(stack, output)
Abstract method.
class runway.cfngin.providers.base.Template(url=None, body=None)
Bases: object
CloudFormation stack template, which could be optionally uploaded to s3.
Presence of the url attribute indicates that the template was uploaded to S3, and the uploaded template should
be used for CreateStack/UpdateStack calls.
Instantiate class.
Subpackages
runway.cfngin.providers.aws package
Import modules.
Submodules
runway.cfngin.providers.aws.default module
Default AWS Provider.
runway.cfngin.providers.aws.default.get_cloudformation_client(session)
Get CloudFormaiton boto3 client.
runway.cfngin.providers.aws.default.get_output_dict(stack)
Return a dict of key/values for the outputs for a given CF stack.
Parameters stack (Dict[str, Any]) – The stack object to get outputs from.
Returns A dictionary with key/values for each output on the stack.
Return type Dict[str, Any]
9.6. Terraform 287
runway Documentation, Release 1.18.3
runway.cfngin.providers.aws.default.s3_fallback(fqn, template, parameters, tags,
method, change_set_name=None,
service_role=None)
Falling back to legacy stacker S3 bucket region for templates.
runway.cfngin.providers.aws.default.get_change_set_name()
Return a valid Change Set Name.
The name has to satisfy the following regex:
[a-zA-Z][-a-zA-Z0-9]
*
And must be unique across all change sets.
runway.cfngin.providers.aws.default.requires_replacement(changeset)
Return the changes within the changeset that require replacement.
Parameters changeset (list) – List of changes
Returns A list of changes that require replacement, if any.
Return type list
runway.cfngin.providers.aws.default.output_full_changeset(full_changeset=None,
params_diff=None,
answer=None,
fqn=None)
Optionally output full changeset.
Parameters
• full_changeset (Optional[List[Dict[str, Any]]]) – A list of the full
changeset that will be output if the user specifies verbose.
• params_diff (Optional[List[runway.cfngin.actions.diff.DictValue) – A
list of DictValue detailing the differences between two parameters returned by runway.
cfngin.actions.diff.diff_dictionaries().
• answer (Optional[str]) – predetermined answer to the prompt if it has already been
answered or inferred.
• fqn (Optional[str]) – fully qualified name of the stack.
runway.cfngin.providers.aws.default.ask_for_approval(full_changeset=None,
params_diff=None, in-
clude_verbose=False,
fqn=None)
Prompt the user for approval to execute a change set.
Parameters
• full_changeset (Optional[List[Dict[str, Any]]]) – A list of the full
changeset that will be output if the user specifies verbose.
• params_diff (Optional[List[runway.cfngin.actions.diff]]) – A list of Dict-
Value detailing the differences between two parameters returned by runway.cfngin.
actions.diff.diff_dictionaries()
• include_verbose (bool) – Boolean for whether or not to include the verbose option.
• fqn (str) – fully qualified name of the stack.
Raises CancelExecution – If approval no given.
288 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
runway.cfngin.providers.aws.default.output_summary(fqn, action, changeset,
params_diff, replace-
ments_only=False)
Log a summary of the changeset.
Parameters
• fqn (string) – fully qualified name of the stack
• action (string) – action to include in the log message
• changeset (list) – AWS changeset
• params_diff (list) – A list of dictionaries detailing the differences between two pa-
rameters returned by runway.cfngin.actions.diff.diff_dictionaries()
• replacements_only (bool, optional) – boolean for whether or not we only want
to list replacements
runway.cfngin.providers.aws.default.format_params_diff(params_diff )
Wrap runway.cfngin.actions.diff.format_params_diff() for testing.
runway.cfngin.providers.aws.default.summarize_params_diff(params_diff )
Summarize parameter diff.
runway.cfngin.providers.aws.default.wait_till_change_set_complete(cfn_client,
change_set_id,
try_count=25,
sleep_time=0.5,
max_sleep=3)
Check state of a changeset, returning when it is in a complete state.
Since changesets can take a little bit of time to get into a complete state, we need to poll it until it does so.
This will try to get the state try_count times, waiting sleep_time * 2 seconds between each try up to
the max_sleep number of seconds. If, after that time, the changeset is not in a complete state it fails. These
default settings will wait a little over one minute.
Parameters
• cfn_client (botocore.client.Client) – Used to query CloudFormation.
• change_set_id (str) – The unique changeset id to wait for.
• try_count (int) – Number of times to try the call.
• sleep_time (int) – Time to sleep between attempts.
• max_sleep (int) – Max time to sleep during backoff
Returns The response from CloudFormation for the describe_change_set call.
Return type Dict[str, Any]
runway.cfngin.providers.aws.default.create_change_set(cfn_client, fqn, tem-
plate, parameters, tags,
change_set_type='UPDATE',
service_role=None)
Create CloudFormation change set.
runway.cfngin.providers.aws.default.check_tags_contain(actual, expected)
Check if a set of AWS resource tags is contained in another.
Every tag key in expected must be present in actual, and have the same value. Extra keys in actual but not
in expected are ignored.
9.6. Terraform 289
runway Documentation, Release 1.18.3
Parameters
• actual (List[Dict[str, str]]) – Set of tags to be verified, usually from the de-
scription of a resource. Each item must be a dict containing Key and Value items.
• expected (List[Dict[str, str]]) – Set of tags that must be present in actual
(in the same format).
runway.cfngin.providers.aws.default.generate_cloudformation_args(stack_name,
parame-
ters, tags,
template,
capabili-
ties=None,
change_set_type=None,
ser-
vice_role=None,
stack_policy=None,
change_set_name=None)
Generate the args for common CloudFormation API interactions.
This is used for create_stack/update_stack/create_change_set calls in CloudFormation.
Parameters
• stack_name (str) – The fully qualified stack name in Cloudformation.
• parameters (List[Dict[str, Any]]) – A list of dictionaries that defines the pa-
rameter list to be applied to the Cloudformation stack.
• tags (List[Dict[str, str]]) – A list of dictionaries that defines the tags that
should be applied to the Cloudformation stack.
• template (runway.cfngin.provider.base.Template) – The template object.
• capabilities (Optional[List[str]]) – A list of capabilities to use when updat-
ing Cloudformation.
• change_set_type (Optional[str]) – An optional change set type to use with cre-
ate_change_set.
• service_role (Optional[str]) – An optional service role to use when interacting
with Cloudformation.
• stack_policy (runway.cfngin.providers.base.Template) – A template
object representing a stack policy.
• change_set_name (Optional[str]) – An optional change set name to use with cre-
ate_change_set.
Returns A dictionary of arguments to be used in the Cloudformation API call.
Return type Dict[str, Any]
runway.cfngin.providers.aws.default.generate_stack_policy_args(stack_policy=None)
Convert a stack policy object into keyword args.
Parameters stack_policy (runway.cfngin.providers.base.Template) – A tem-
plate object representing a stack policy.
Returns A dictionary of keyword arguments to be used elsewhere.
Return type dict
290 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
class runway.cfngin.providers.aws.default.ProviderBuilder(region=None,
**kwargs)
Bases: object
Implements a Memorized ProviderBuilder for the AWS provider.
Instantiate class.
build(region=None, profile=None)
Get or create the provider for the given region and profile.
class runway.cfngin.providers.aws.default.Provider(session, region=None, in-
teractive=False, replace-
ments_only=False, recre-
ate_failed=False, ser-
vice_role=None)
Bases: runway.cfngin.providers.base.BaseProvider
AWS CloudFormation Provider.
Instantiate class.
DELETING_STATUS = 'DELETE_IN_PROGRESS'
DELETED_STATUS = 'DELETE_COMPLETE'
IN_PROGRESS_STATUSES = ('CREATE_IN_PROGRESS', 'IMPORT_IN_PROGRESS', 'UPDATE_IN_PROGRESS', 'DELETE_IN_PROGRESS', 'UPDATE_COMPLETE_CLEANUP_IN_PROGRESS')
ROLLING_BACK_STATUSES = ('ROLLBACK_IN_PROGRESS', 'IMPORT_ROLLBACK_IN_PROGRESS', 'UPDATE_ROLLBACK_IN_PROGRESS')
FAILED_STATUSES = ('CREATE_FAILED', 'ROLLBACK_FAILED', 'ROLLBACK_COMPLETE', 'DELETE_FAILED', 'IMPORT_ROLLBACK_FAILED', 'UPDATE_ROLLBACK_FAILED', 'UPDATE_ROLLBACK_COMPLETE')
COMPLETE_STATUSES = ('CREATE_COMPLETE', 'DELETE_COMPLETE', 'IMPORT_COMPLETE', 'UPDATE_COMPLETE', 'IMPORT_ROLLBACK_COMPLETE', 'UPDATE_ROLLBACK_COMPLETE')
RECREATION_STATUSES = ('CREATE_FAILED', 'ROLLBACK_FAILED', 'ROLLBACK_COMPLETE')
REVIEW_STATUS = 'REVIEW_IN_PROGRESS'
get_stack(stack_name, *args, **kwargs)
Get stack.
get_stack_status(stack, *args, **kwargs)
Get stack status.
is_stack_being_destroyed(stack, **kwargs)
Whether the status of the stack indicates it is ‘being destroyed’.
is_stack_completed(stack)
Whether the status of the stack indicates it is ‘complete’.
is_stack_in_progress(stack)
Whether the status of the stack indicates it is ‘in progress’.
is_stack_destroyed(stack)
Whether the status of the stack indicates it is ‘deleted’.
is_stack_recreatable(stack)
Whether the status of the stack indicates it is ‘recreating’.
is_stack_rolling_back(stack)
Whether the status of the stack indicates it is ‘rolling back’.
is_stack_failed(stack)
Whether the status of the stack indicates it is ‘failed’.
9.6. Terraform 291
runway Documentation, Release 1.18.3
is_stack_in_review(stack)
Whether the status of the stack indicates if ‘review in progress’.
tail_stack(stack, cancel, action=None, log_func=None, retries=None)
Tail the events of a stack.
get_events(stack_name, chronological=True)
Get the events in batches and return in chronological order.
get_rollback_status_reason(stack_name)
Process events and returns latest roll back reason.
tail(stack_name, cancel, log_func=<staticmethod object>, sleep_time=5, include_initial=True)
Show and then tail the event log.
destroy_stack(stack, *args, **kwargs)
Destroy a CloudFormation Stack.
Parameters stack (stacker.stack.Stack) – Stack to be destroyed.
Keyword Arguments
• action (str) – Name of the action being executed. This impacts the log message used.
• approval (Optional[str]) – Response to approval prompt.
• force_interactive (bool) – Always ask for approval.
create_stack(fqn, template, parameters, tags, force_change_set=False, stack_policy=None, termi-
nation_protection=False, **kwargs)
Create a new Cloudformation stack.
Parameters
• fqn (str) – The fully qualified name of the Cloudformation stack.
• template (runway.cfngin.providers.base.Template) – A Template ob-
ject to use when creating the stack.
• parameters (list) – A list of dictionaries that defines the parameter list to be applied
to the Cloudformation stack.
• tags (list) – A list of dictionaries that defines the tags that should be applied to the
Cloudformation stack.
• force_change_set (bool) – Whether or not to force change set use.
• stack_policy (runway.cfngin.providers.base.Template) – A template
object representing a stack policy.
• termination_protection (bool) – End state of the stack’s termination protection.
select_update_method(force_interactive, force_change_set)
Select the correct update method when updating a stack.
Parameters
• force_interactive (str) – Whether or not to force interactive mode no matter what
mode the provider is in.
• force_change_set (bool) – Whether or not to force change set use.
Returns The correct object method to use when updating.
Return type function
292 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
prepare_stack_for_update(stack, tags)
Prepare a stack for updating.
It may involve deleting the stack if is has failed it’s initial creation. The deletion is only allowed if:
• The stack contains all the tags configured in the current context;
• The stack is in one of the statuses considered safe to re-create
• recreate_failed is enabled, due to either being explicitly enabled by the user, or because inter-
active mode is on.
Parameters
• stack (dict) – a stack object returned from get_stack
• tags (list) – list of expected tags that must be present in the stack if it must be re-
created
Returns True if the stack can be updated, False if it must be re-created
Return type bool
update_stack(fqn, template, old_parameters, parameters, tags, force_interactive=False,
force_change_set=False, stack_policy=None, termination_protection=False,
**kwargs)
Update a Cloudformation stack.
Parameters
• fqn (str) – The fully qualified name of the Cloudformation stack.
• template (runway.cfngin.providers.base.Template) – A Template ob-
ject to use when updating the stack.
• old_parameters (List[Dict[str, Any]]) – A list of dictionaries that defines
the parameter list on the existing Cloudformation stack.
• parameters (List[Dict[str, Any ]]) – A list of dictionaries that defines the
parameter list to be applied to the Cloudformation stack.
• tags (List[Dict[str, str]]) – A list of dictionaries that defines the tags that
should be applied to the Cloudformation stack.
• force_interactive (bool) – A flag that indicates whether the update should be
interactive. If set to True, interactive mode will be used no matter if the provider is in
interactive mode or not. False will follow the behavior of the provider.
• force_change_set (bool) – A flag that indicates whether the update must be exe-
cuted with a change set.
• stack_policy (runway.cfngin.providers.base.Template) – A template
object representing a stack policy.
• termination_protection (bool) – End state of the stack’s termination protection.
update_termination_protection(fqn, termination_protection)
Update a Stack’s termination protection if needed.
Runs before the normal stack update process.
Parameters
• fqn (str) – The fully qualified name of the Cloudformation stack.
• termination_protection (bool) – End state of the stack’s termination protection.
9.6. Terraform 293
runway Documentation, Release 1.18.3
deal_with_changeset_stack_policy(fqn, stack_policy)
Set a stack policy when using changesets.
ChangeSets don’t allow you to set stack policies in the same call to update them. This sets it before
executing the changeset if the stack policy is passed in.
Parameters
• fqn (str) – Fully qualified name of the stack.
• stack_policy (runway.cfngin.providers.base.Template) – A template
object representing a stack policy.
interactive_destroy_stack(fqn, approval=None, **kwargs)
Delete a CloudFormation stack in interactive mode.
Parameters
• fqn (str) – A fully qualified stack name.
• approval (Optional[str]) – Response to approval prompt.
interactive_update_stack(fqn, template, old_parameters, parameters, stack_policy, tags)
Update a Cloudformation stack in interactive mode.
Parameters
• fqn (str) – The fully qualified name of the Cloudformation stack.
• template (runway.cfngin.providers.base.Template) – A Template ob-
ject to use when updating the stack.
• old_parameters (List[Dict[str, Any]]) – A list of dictionaries that defines
the parameter list on the existing Cloudformation stack.
• parameters (List[Dict[str, Any ]]) – A list of dictionaries that defines the
parameter list to be applied to the Cloudformation stack.
• stack_policy (runway.cfngin.providers.base.Template) – A template
object representing a stack policy.
• tags (List[Dict[str, str]]) – A list of dictionaries that defines the tags that
should be applied to the Cloudformation stack.
noninteractive_destroy_stack(fqn, **kwargs)
Delete a CloudFormation stack without interaction.
Parameters fqn (str) – A fully qualified stack name.
noninteractive_changeset_update(fqn, template, old_parameters, parameters, stack_policy,
tags)
Update a Cloudformation stack using a change set.
This is required for stacks with a defined Transform (i.e. SAM), as the default update_stack API
cannot be used with them.
Parameters
• fqn (str) – The fully qualified name of the Cloudformation stack.
• template (runway.cfngin.providers.base.Template) – A Template ob-
ject to use when updating the stack.
• old_parameters (list) – A list of dictionaries that defines the parameter list on the
existing Cloudformation stack.
294 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
• parameters (list) – A list of dictionaries that defines the parameter list to be applied
to the Cloudformation stack.
• stack_policy (runway.cfngin.providers.base.Template) – A template
object representing a stack policy.
• tags (list) – A list of dictionaries that defines the tags that should be applied to the
Cloudformation stack.
select_destroy_method(force_interactive)
Select the correct destroy method for destroying a stack.
Parameters force_interactive (bool) – Always ask for approval.
Returns Interactive or non-interactive method to be invoked.
default_update_stack(fqn, template, old_parameters, parameters, tags, stack_policy=None)
Update a Cloudformation stack in default mode.
Parameters
• fqn (str) – The fully qualified name of the Cloudformation stack.
• template (runway.cfngin.providers.base.Template) – A Template ob-
ject to use when updating the stack.
• old_parameters (list) – A list of dictionaries that defines the parameter list on the
existing Cloudformation stack.
• parameters (list) – A list of dictionaries that defines the parameter list to be applied
to the Cloudformation stack.
• tags (list) – A list of dictionaries that defines the tags that should be applied to the
Cloudformation stack.
• stack_policy (runway.cfngin.providers.base.Template) – A template
object representing a stack policy.
static get_stack_name(stack)
Get stack name.
static get_stack_tags(stack)
Get stack tags.
get_outputs(stack_name, *args, **kwargs)
Get stack outputs.
static get_output_dict(stack)
Get stack outputs dict.
get_stack_info(stack)
Get the template and parameters of the stack currently in AWS.
Returns Tuple[str, Dict[str, Any]]
get_stack_changes(stack, template, parameters, tags)
Get the changes from a ChangeSet.
Parameters
• stack (runway.cfngin.stack.Stack) – The stack to get changes.
• template (runway.cfngin.providers.base.Template) – A Template ob-
ject to compaired to.
9.6. Terraform 295
runway Documentation, Release 1.18.3
• parameters (List[Dict[str, Any ]]) – A list of dictionaries that defines the
parameter list to be applied to the Cloudformation stack.
• tags (List[Dict[str, Any]]) – A list of dictionaries that defines the tags that
should be applied to the Cloudformation stack.
Returns Stack outputs with inferred changes.
Return type Dict[str, Any]
static params_as_dict(parameters_list)
Parameters as dict.
runway.core package
Core Runway API.
class runway.core.Runway(config, context)
Bases: object
Runway’s core functionality.
Instantiate class.
Parameters
• config – Runway config.
• context – Runway context.
deploy(deployments=None)
Deploy action.
Parameters deployments – List of deployments to run. If not provided, all deployments in
the config will be run.
destroy(deployments=None)
Destroy action.
Parameters deployments – List of deployments to run. If not provided, all deployments in
the config will be run in reverse.
get_env_vars(deployments=None)
Get env_vars defined in the config.
Parameters deployments – List of deployments to get env_vars from.
Returns Resolved env_vars from the deployments.
plan(deployments=None)
Plan action.
Parameters deployments – List of deployments to run. If not provided, all deployments in
the config will be run.
static reverse_deployments(deployments)
Reverse deployments and the modules within them.
Parameters deployments – List of deployments to reverse.
Returns Deployments and modules in reverse order.
test()
Run tests defined in the config.
296 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Subpackages
runway.core.components package
Core Runway components.
class runway.core.components.DeployEnvironment(_=None, **kwargs)
Bases: object
Runway deploy environment.
Instantiate class.
Keyword Arguments
• environ (Optional[Dict[str, str]]) – Environment variables.
• explicit_name (Optional[str]) – Explicitly provide the deploy environment
name.
• ignore_git_branch (bool) – Ignore the git branch when determining the deploy en-
vironment name.
• root_dir (Optional[Path]) – Root directory of the project.
property aws_credentials
Get AWS credentials from environment variables.
property aws_profile
Get AWS profile from environment variables.
property aws_region
Get AWS region from environment variables.
branch_name
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
property ci
Return CI status.
Returns bool
copy()
Copy the contents of this object into a new instance.
Returns New instance with the same contents.
Return type DeployEnvironment
property debug
Get debug setting from the environment.
property ignore_git_branch
Whether to ignore git branch when determining name.
log_name()
Output name to log.
9.6. Terraform 297
runway Documentation, Release 1.18.3
property max_concurrent_cfngin_stacks
Max number of CFNgin stacks that can be deployed concurrently.
This property can be set by exporting RUNWAY_MAX_CONCURRENT_CFNGIN_STACKS. If no value is
specified, the value will be constrained based on the underlying graph.
Returns Value from environment variable or 0.
Return type int
property max_concurrent_modules
Max number of modules that can be deployed to concurrently.
This property can be set by exporting RUNWAY_MAX_CONCURRENT_MODULES. If no value is specified,
min(61, os.cpu_count()) is used.
On Windows, this must be equal to or lower than 61.
IMPORTANT: When using parallel_regions and child_modules together, please con-
sider the nature of their relationship when manually setting this value. (parallel_regions
*
child_modules)
Returns Value from environment variable or min(61, os.cpu_count())
Return type int
property max_concurrent_regions
Max number of regions that can be deployed to concurrently.
This property can be set by exporting RUNWAY_MAX_CONCURRENT_REGIONS. If no value is specified,
min(61, os.cpu_count()) is used.
On Windows, this must be equal to or lower than 61.
IMPORTANT: When using parallel_regions and child_modules together, please con-
sider the nature of their relationship when manually setting this value. (parallel_regions
*
child_modules)
Returns Value from environment variable or min(61, os.cpu_count())
Return type int
name
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
property verbose
Get verbose setting from the environment.
class runway.core.components.Deployment(context, definition, future=None, variables=None)
Bases: object
Runway deployment.
Instantiate class.
Parameters
• context (Context) – Runway context object.
• definition (DeploymentDefinition) – A single deployment definition.
• future (Optional[FutureDefinition]) – Future functionality configuration.
298 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
• variables (VariablesDefinition) – Runway variables.
property account_alias_config
Parse the definition to get the correct AWS account alias configuration.
Returns Expected AWS account alias for the current context.
Return type Optional[str]
property account_id_config
Parse the definition to get the correct AWS account ID configuration.
Returns Expected AWS account ID for the current context.
Return type Optional[str]
property assume_role_config
Parse the definition to get the correct assume role configuration.
Returns Assume role definition for the current context.
Return type Dict[str, Union[int, str]]
deploy()
Deploy the deployment.
High level method for running a deployment.
destroy()
Destroy the deployment.
High level method for running a deployment.
property env_vars_config
Parse the definition to get the correct env_vars configuration.
plan()
Plan for the next deploy of the deployment.
High level method for running a deployment.
regions
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
run(action, region)
Run a single deployment in a single region.
Low level API access to run a deployment object.
Parameters
• action (str) – Action to run (deploy, destroy, plan, etc.)
• region (str) – AWS region to run in.
classmethod run_list(action, context, deployments, future, variables)
Run a list of deployments.
Parameters
• action (str) – Name of action to run.
• context (Context) – Runway context.
9.6. Terraform 299
runway Documentation, Release 1.18.3
• deployments (List[DeploymentDefinition]) – List of deployments to run.
• future (FutureDefinition) – Future definition.
• variables (VariablesDefinition) – Runway variables for lookup resolution.
use_async
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
validate_account_credentials(context=None)
Exit if requested deployment account doesn’t match credentials.
Parameters context (Optional[Context]) – Context object.
Raises SystemExit – AWS Account associated with the current credentials did not match the
defined criteria.
class runway.core.components.Module(context, definition, deployment=None, future=None,
variables=None)
Bases: object
Runway module.
Instantiate class.
Parameters
• context (Context) – Runway context object.
• definition (ModuleDefinition) – A single module definition.
• deployment (Optional[DeploymentDefinition]) – Deployment that this mod-
ule is a part of.
• future (Optional[FutureDefinition]) – Future functionality configuration.
• variables (Optional[VariablesDefinition]) – Runway variables.
child_modules
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
deploy()
Deploy the module.
High level method for running a module.
destroy()
Destroy the module.
High level method for running a module.
fqn
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
300 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
path
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
payload
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
plan()
Plan for the next deploy of the module.
High level method for running a module.
run(action)
Run a single module.
Low level API access to run a module object.
Parameters action – Name of action to run.
classmethod run_list(action, context, modules, variables, deployment=None, future=None)
Run a list of modules.
Parameters
• action – Name of action to run.
• context – Runway context.
• modules – List of modules to run.
• variables – Variable definition for resolving lookups in the module.
• deployment – Deployment the modules are a part of.
• future (Optional[FutureDefinition]) – Future functionality configuration.
should_skip
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
type
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
use_async
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
9.6. Terraform 301
runway Documentation, Release 1.18.3
runway.core.providers package
Runway providers.
Subpackages
runway.core.providers.aws package
Runway AWS objects.
class runway.core.providers.aws.AccountDetails(context)
Bases: object
AWS account details.
Instantiate class.
Parameters context – Runway context object.
aliases
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
id
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
class runway.core.providers.aws.AssumeRole(context, role_arn=None, dura-
tion_seconds=None, revert_on_exit=True,
session_name=None)
Bases: contextlib.AbstractContextManager
Context manager for assuming an AWS role.
Instantiate class.
Parameters
• context (Context) – Runway context object.
• role_arn (Optional[str]) – ARN of role to be assumed.
• duration_seconds (Optional[int]) – Seconds that the assumed role’s credentials
will be valid for. (default: 3600)
• revert_on_exit (bool) – Whether credentials in the environment will be reverted
upon exiting the context manager.
• session_name (Optional[bool]) – Name to use for the assumed role session. (de-
fault: runway)
assume()
Perform role assumption.
restore_existing_iam_env_vars()
Restore backed up IAM environment variables.
302 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
save_existing_iam_env_vars()
Backup IAM environment variables for later restoration.
class runway.core.providers.aws.BaseResponse(**kwargs)
Bases: object
Analyse the response from AWS S3 HeadBucket API response.
error
Information about a service or networking error.
Type ResponseError
metadata
Information about the request.
Type ResponseMetadata
Instantiate class.
Keyword Arguments
• Error – Information about a service or networking error.
• ResponseMetadata – Information about the request.
class runway.core.providers.aws.ResponseError(**kwargs)
Bases: object
Analyse the response from AWS S3 HeadBucket API response.
code
A unique short code representing the error that was emitted.
Type str
message
A longer human readable error message.
Type str
Instantiate class.
Keyword Arguments
• Code (str) – A unique short code representing the error that was emitted.
• Message (str) – A longer human readable error message.
class runway.core.providers.aws.ResponseMetadata(**kwargs)
Bases: object
Analyse the response from AWS S3 HeadBucket API response.
host_id
Host ID data.
Type Optional[str]
https_headers
A map of response header keys and their respective values.
Type Dict[str, Any]
http_status_code
The HTTP status code of the response (e.g., 200, 404).
Type int
9.6. Terraform 303
runway Documentation, Release 1.18.3
request_id
The unique request ID associated with the response. Log this value when debugging requests for AWS
support.
Type Optional[str]
retry_attempts
The number of retries that were attempted before the request was completed.
Type int
Instantiate class.
Keyword Arguments
• HostId (str) – Host ID data.
• HTTPHeaders (Dict[str, Any]) – A map of response header keys and their respec-
tive values.
• HTTPStatusCode (int) – The HTTP status code of the response (e.g., 200, 404).
• RequestId (str) – The unique request ID associated with the response. Log this value
when debugging requests for AWS support.
• RetryAttempts (int) – The number of retries that were attempted before the request
was completed.
property forbidden
Whether the response returned 403 (forbidden).
property not_found
Whether the response returned 404 (Not Found).
runway.core.providers.aws.cli(cmd)
Invoke AWS command.
Parameters cmd – Command to be passed to awscli.
Raises RuntimeError – awscli returned a non-zero exit code.
Subpackages
runway.core.providers.aws.s3 package
AWS S3 objects.
class runway.core.providers.aws.s3.Bucket(context, name, region=None)
Bases: object
AWS S3 bucket.
Instantiate class.
Parameters
• context – Current context object.
• name – The name of the bucket.
• region – The bucket’s region.
304 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
client
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
create(**kwargs)
Create an S3 Bucket if it does not already exist.
Bucket creation will be skipped if it already exists or access is forbidden.
Keyword arguments are passed directly to the boto3 method.
Returns boto3 response.
enable_versioning()
Enable versioning on the bucket if not already enabled.
property exists
Check whether the bucket exists.
Opposite of not_found.
forbidden
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
get_versioning()
Get the versioning state of a bucket.
To retrieve the versioning state of a bucket, you must be the bucket owner.
Returns The current versioning state of the bucket containing Status and MFADelete (only
if this has ever been configured).
head
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
not_found
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
9.6. Terraform 305
runway Documentation, Release 1.18.3
runway.env_mgr package
Base module for environment managers.
class runway.env_mgr.EnvManager(bin_name, dir_name, path=None)
Bases: object
Base environment manager class.
bin
Path to the binary of the current version.
Type Optional[str]
current_version
The current binary version being used.
Type Optional[str]
env_dir_name
Name of the directory within the users home directory where binary versions will be stored.
Type str
path
The current working directory.
Type Path
Initialize class.
Parameters
• bin_name (str) – Name of the binary file (e.g. kubectl)
• dir_name (str) – Name of the directory within the users home directory where binary
versions will be stored.
• path (Optional[Path]) – The current working directory.
property bin
Path to the version binary.
Returns Path
command_suffix
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
env_dir
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
versions_dir
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
306 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
runway.env_mgr.handle_bin_download_error(exc, name)
Give user info about their failed download.
Submodules
runway.env_mgr.kbenv module
Kubectl version management.
runway.env_mgr.kbenv.verify_kb_release(kb_url, download_dir, filename)
Compare checksum and exit if it doesn’t match.
Different releases provide varying checksum files. To account for this, start at SHA512 and work down to the
first available checksum.
requests is used for downloading these small files because of difficulty in getting 404 status from urllib on py2.
Once py2 support is dropped, downloads can be moved to urllib.
https://stackoverflow.com/questions/1308542/how-to-catch-404-error-in-urllib-urlretrieve
runway.env_mgr.kbenv.download_kb_release(version, versions_dir, kb_platform=None,
arch=None)
Download kubectl and return path to it.
runway.env_mgr.kbenv.get_version_requested(path)
Return string listing requested kubectl version.
class runway.env_mgr.kbenv.KBEnvManager(path=None)
Bases: runway.env_mgr.EnvManager
kubectl version management.
Designed to be compatible with https://github.com/alexppg/kbenv.
Initialize class.
install(version_requested=None)
Ensure kubectl is available.
runway.env_mgr.tfenv module
Terraform version management.
runway.env_mgr.tfenv.download_tf_release(version, versions_dir, command_suffix,
tf_platform=None, arch=None)
Download Terraform archive and return path to it.
runway.env_mgr.tfenv.get_available_tf_versions(include_prerelease=False)
Return available Terraform versions.
runway.env_mgr.tfenv.get_latest_tf_version(include_prerelease=False)
Return latest Terraform version.
runway.env_mgr.tfenv.load_terrafrom_module(parser, path)
Load all Terraform files in a module into one dict.
Parameters
• parser (Union[hcl, hcl2]) – Parser to use when loading files.
• path (Path) – Terraform module path. All Terraform files in the path will be loaded.
9.6. Terraform 307
runway Documentation, Release 1.18.3
Returns Combined contents of all Terraform files in a single dict.
Return type Dict[str, Any]
class runway.env_mgr.tfenv.TFEnvManager(path=None)
Bases: runway.env_mgr.EnvManager
Terraform version management.
Designed to be compatible with https://github.com/tfutils/tfenv.
Initialize class.
backend
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
terraform_block
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
version_file
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
get_min_required()
Get the defined minimum required version of Terraform.
Returns The minimum required version as defined in the module.
Return type str
get_version_from_file(file_path=None)
Get Terraform version from a file.
Parameters file_path (Optional[Path]) – Path to file that will be read.
install(version_requested=None)
Ensure Terraform is available.
runway.hooks package
Empty init for python import traversal.
308 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Submodules
runway.hooks.cleanup_s3 module
CFNgin hook for cleaning up resources prior to CFN stack deletion.
runway.hooks.cleanup_s3.purge_bucket(context, provider, **kwargs)
Delete objects in bucket.
runway.hooks.cleanup_ssm module
CFNgin hook for cleaning up resources prior to CFN stack deletion.
runway.hooks.cleanup_ssm.delete_param(context, provider, **kwargs)
Delete SSM parameter.
Subpackages
runway.hooks.staticsite package
Empty init for python import traversal.
Submodules
runway.hooks.staticsite.build_staticsite module
CFNgin hook for building static website.
runway.hooks.staticsite.build_staticsite.zip_and_upload(app_dir, bucket, key, ses-
sion=None)
Zip built static site and upload to S3.
runway.hooks.staticsite.build_staticsite.build(context, provider, **kwargs)
Build static site.
runway.hooks.staticsite.cleanup module
Replicated Lambda Function cleanup warning.
runway.hooks.staticsite.cleanup.get_replicated_function_names(outputs)
Extract replicated function names from CFN outputs.
runway.hooks.staticsite.cleanup.warn(context, provider, **kwargs)
Notify the user of Lambda functions to delete.
Parameters
• context (runway.cfngin.context.Context) – The context instance.
• provider (runway.cfngin.providers.base.BaseProvider) – The provider
instance.
Keyword Arguments stack_relative_name (str) – CFNgin stack name with Functions.
9.6. Terraform 309
runway Documentation, Release 1.18.3
runway.hooks.staticsite.upload_staticsite module
CFNgin hook for syncing static website to S3 bucket.
runway.hooks.staticsite.upload_staticsite.get_archives_to_prune(archives,
hook_data)
Return list of keys to delete.
Parameters
• archives (Dict) – The full list of file archives
• hook_data (Dict) – CFNgin hook data
runway.hooks.staticsite.upload_staticsite.sync(context, provider, **kwargs)
Sync static website to S3 bucket.
Parameters
• context (runway.cfngin.context.Context) – The context instance.
• provider (runway.cfngin.providers.base.BaseProvider) – The provider
instance.
runway.hooks.staticsite.upload_staticsite.display_static_website_url(website_url_handle,
provider,
con-
text)
Based on the url handle display the static website url.
Parameters
• website_url_handle (str) – the Output handle for the website url
• provider (runway.cfngin.providers.base.BaseProvider) – The provider
instance.
• context (runway.cfngin.context.Context) – context instance
runway.hooks.staticsite.upload_staticsite.update_ssm_hash(context, session)
Update the SSM hash with the new tracking data.
Parameters
• context (runway.cfngin.context.Context) – context instance
• session (runway.cfngin.session.Session) – CFNgin session
runway.hooks.staticsite.upload_staticsite.get_distribution_data(context,
provider,
**kwargs)
Retrieve information about the distribution.
Parameters
• context (runway.cfngin.context.Context) – The context instance.
• provider (runway.cfngin.providers.base.BaseProvider) – The provider
instance
runway.hooks.staticsite.upload_staticsite.invalidate_distribution(session,
identi-
fier='',
path='',
domain='',
**_)
310 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Invalidate the current distribution.
Parameters
• session (Session) – The current CFNgin session.
• identifier (string) – The distribution id.
• path (string) – The distribution path.
• domain (string) – The distribution domain.
runway.hooks.staticsite.upload_staticsite.prune_archives(context, session)
Prune the archives from the bucket.
Parameters
• context (runway.cfngin.context.Context) – The context instance.
• session (runway.cfngin.session.Session) – The CFNgin session.
runway.hooks.staticsite.upload_staticsite.auto_detect_content_type(filename)
Auto detects the content type based on the filename.
Parameters filename (str) – A filename to use to auto detect the content type.
Returns The content type of the file. None if the content type could not be detected.
Return type str
runway.hooks.staticsite.upload_staticsite.get_content_type(extra_file)
Return the content type of the file.
Parameters extra_file (Dict[str, Union[str, Dict[Any]]]) – The extra file con-
figuration.
Returns The content type of the extra file. If ‘content_type’ is provided then that is returned, other-
ways it is auto detected based on the name.
Return type str
runway.hooks.staticsite.upload_staticsite.get_content(extra_file)
Get serialized content based on content_type.
Parameters extra_file (Dict[str, Union[str, Dict[Any]]]) – The extra file con-
figuration.
Returns Serialized content based on the content_type.
Return type str
runway.hooks.staticsite.upload_staticsite.calculate_hash_of_extra_files(extra_files)
Return a hash of all of the given extra files.
Adapted from stacker.hooks.aws_lambda; used according to its license: https://github.com/cloudtools/stacker/
blob/1.4.0/LICENSE
All attributes of the extra file object are included when hashing: name, content_type, content, and file data.
Parameters extra_files (List[Dict[str, Union[str, Dict[Any]]]]) – The list
of extra file configurations.
Returns The hash of all the files.
Return type str
runway.hooks.staticsite.upload_staticsite.get_ssm_value(session, name)
Get the ssm parameter value.
9.6. Terraform 311
runway Documentation, Release 1.18.3
Parameters
• session (runway.cfngin.session.Session) – The CFNgin session.
• name (str) – The parameter name.
Returns The parameter value.
Return type str
runway.hooks.staticsite.upload_staticsite.set_ssm_value(session, name, value, de-
scription='')
Set the ssm parameter.
Parameters
• session (runway.cfngin.session.Session) – The CFNgin session.
• name (str) – The name of the parameter.
• value (str) – The value of the parameter.
• description (str) – A description of the parameter.
runway.hooks.staticsite.upload_staticsite.sync_extra_files(context, bucket, ex-
tra_files, **kwargs)
Sync static website extra files to S3 bucket.
Parameters
• context (runway.cfngin.context.Context) – The context instance.
• bucket (str) – The static site bucket name.
• extra_files (List[Dict[str, str]]) – List of files and file content that should
be uploaded.
runway.hooks.staticsite.util module
Utility functions for website build/upload.
runway.hooks.staticsite.util.calculate_hash_of_files(files, root)
Return a hash of all of the given files at the given root.
Adapted from stacker.hooks.aws_lambda; used according to its license: https://github.com/cloudtools/stacker/
blob/1.4.0/LICENSE
Parameters
• files (list[str]) – file names to include in the hash calculation, relative to root.
• root (str) – base directory to analyze files in.
Returns A hash of the hashes of the given files.
Return type str
runway.hooks.staticsite.util.get_hash_of_files(root_path, directories=None)
Generate md5 hash of files.
runway.hooks.staticsite.util.get_ignorer(path, additional_exclusions=None)
Create ignorer with directory gitignore file.
312 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Subpackages
runway.hooks.staticsite.auth_at_edge package
Empty init for python import traversal.
Submodules
runway.hooks.staticsite.auth_at_edge.callback_url_retriever module
Callback URL Retriever.
Dependency pre-hook responsible for ensuring correct callback urls are retrieved or a temporary one is used in it’s
place.
runway.hooks.staticsite.auth_at_edge.callback_url_retriever.get(context,
provider,
**kwargs)
Retrieve the callback URLs for User Pool Client Creation.
When the User Pool is created a Callback URL is required. During a post hook entitled client_updater
these Callback URLs are updated to that of the Distribution. Before then we need to ensure that if a Client
already exists that the URLs for that client are used to prevent any interuption of service during deploy.
Parameters
• context (runway.cfngin.context.Context) – The context instance.
• provider (runway.cfngin.providers.base.BaseProvider) – The provider
instance.
Keyword Arguments
• user_pool_id (str) – The ID of the User Pool to check for a client.
• stack_name (str) –
runway.hooks.staticsite.auth_at_edge.client_updater module
User Pool Client Updater.
Responsible for updating the User Pool Client with the generated distribution url + callback url paths.
runway.hooks.staticsite.auth_at_edge.client_updater.get_redirect_uris(domains,
redi-
rect_path_sign_in,
redi-
rect_path_sign_out)
Create dict of redirect URIs for AppClient.
runway.hooks.staticsite.auth_at_edge.client_updater.update(context, provider,
**kwargs)
Update the callback urls for the User Pool Client.
Required to match the redirect_uri being sent which contains our distribution and alternate domain names.
Parameters
• context (runway.cfngin.context.Context) – The context instance.
9.6. Terraform 313
runway Documentation, Release 1.18.3
• provider (runway.cfngin.providers.base.BaseProvider) – The provider
instance.
Keyword Arguments
• alternate_domains (List[str]) – A list of any alternate domains that need to be
listed with the primary distribution domain.
• redirect_path_sign_in (str) – The redirect path after sign in.
• redirect_path_sign_out (str) – The redirect path after sign out.
• oauth_scopes (List[str]) – A list of all available validation scopes for oauth.
runway.hooks.staticsite.auth_at_edge.domain_updater module
User Pool Client Domain Updater.
runway.hooks.staticsite.auth_at_edge.domain_updater.update(context, provider,
**kwargs)
Retrieve/Update the domain name of the specified client.
A domain name is required in order to make authorization and token requests. This prehook ensures we have
one available, and if not we create one based on the user pool and client ids.
Parameters
• context (runway.cfngin.context.Context) – The context instance.
• provider (runway.cfngin.providers.base.BaseProvider) – The provider
instance.
Keyword Arguments
• user_pool_id (str) – The ID of the Cognito User Pool.
• client_id (str) – The ID of the Cognito User Pool Client.
runway.hooks.staticsite.auth_at_edge.domain_updater.delete(context, provider,
**kwargs)
Delete the domain if the user pool was created by Runway.
If a User Pool was created by Runway, and populated with a domain, that domain must be deleted prior to the
User Pool itself being deleted or an error will occur. This process ensures that our generated domain name is
deleted, or skips if not able to find one.
Parameters
• context (runway.cfngin.context.Context) – The context instance.
• provider (runway.cfngin.providers.base.BaseProvider) – The provider
instance.
Keyword Arguments client_id (str) – The ID of the Cognito User Pool Client.
runway.hooks.staticsite.auth_at_edge.domain_updater.get_user_pool_domain(prefix,
re-
gion)
Return a user pool domain name based on the prefix received and region.
Parameters
• prefix (str) – The domain prefix for the domain.
• region (str) – The region in which the pool resides.
314 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
runway.hooks.staticsite.auth_at_edge.lambda_config module
CFNgin prehook responsible for creation of Lambda@Edge functions.
runway.hooks.staticsite.auth_at_edge.lambda_config.write(context, provider,
**kwargs)
Writes/Uploads the configured lambdas for Auth@Edge.
Lambda@Edge does not have the ability to allow Environment variables at the time of this writing. In order to
configure our lambdas with dynamic variables we first will go through and update a “shared” template with all of
the configuration elements and add that to a temporary folder along with each of the individual Lambda@Edge
functions. This temporary folder is then used with the CFNgin awsLambda hook to build the functions.
Parameters
• context (cfngin.Context) – The CFNgin context.
• provider (cfngin.Provider) – The CFNgin provider.
Keyword Arguments
• client_id (str) – The ID of the Cognito User Pool Client.
• cookie_settings (dict) – The settings for our customized cookies.
• http_headers (dict) – The additional headers added to our requests.
• nonce_signing_secret_param_name (str) – SSM param name to store nonce
signing secret.
• oauth_scopes (List[str]) – The validation scopes for our OAuth requests.
• redirect_path_auth_refresh (str) – The URL path for authorization refresh
redirect (Correlates to the refresh auth lambda).
• redirect_path_sign_in (str) – The URL path to be redirected to after sign in (Cor-
relates to the parse auth lambda).
• redirect_path_sign_out (str) – The URL path to be redirected to after sign out
(Correlates to the root to be asked to resigning).
• required_group (Optional[str]) – Optional User Pool group to which access
should be restricted.
• user_pool_id (str) – The ID of the Cognito User Pool.
runway.hooks.staticsite.auth_at_edge.lambda_config.get_nonce_signing_secret(param_name,
con-
text)
Retrieve signing secret, generating & storing it first if not present.
runway.hooks.staticsite.auth_at_edge.lambda_config.random_key(length=16)
Generate a random key of specified length from the allowed secret characters.
Parameters length (int) – The length of the random key.
9.6. Terraform 315
runway Documentation, Release 1.18.3
runway.hooks.staticsite.auth_at_edge.user_pool_id_retriever module
Retrieve the ID of the Cognito User Pool.
runway.hooks.staticsite.auth_at_edge.user_pool_id_retriever.get(context,
provider,
**kwargs)
Retrieve the ID of the Cognito User Pool.
The User Pool can either be supplied via an ARN or by being generated. If the user has supplied an ARN that
utilize that, otherwise retrieve the generated id. Used in multiple pre_hooks for Auth@Edge.
Parameters
• context (runway.cfngin.context.Context) – The context instance.
• provider (runway.cfngin.providers.base.BaseProvider) – The provider
instance.
Keyword Arguments
• user_pool_arn (str) – The ARN of the supplied User pool.
• created_user_pool_id (str) – The ID of the created Cognito User Pool.
runway.lookups package
Empty init for python import traversal.
Submodules
runway.lookups.registry module
Register test handlers.
runway.lookups.registry.register_lookup_handler(lookup_type, handler_or_path)
Register a lookup handler.
Parameters
• lookup_type – Name to register the handler under
• handler_or_path – a function or a path to a handler
runway.lookups.registry.unregister_lookup_handler(lookup_type)
Unregister the specified test type.
This is useful when testing various lookup types if you want to unregister the lookup type after the test runs.
Parameters lookup_type – Name of the lookup type to unregister
316 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Subpackages
runway.lookups.handlers package
Import classes.
Submodules
runway.lookups.handlers.base module
Lookup Arguments
Arguments can be passed to Lookups to effect how they function.
To provide arguments to a Lookup, use a double-colon (::) after the query. Each argument is then defined as a key
and value seperated with equals (=) and the arguments theselves are seperated with a comma (,). The arguments can
have an optional space after the comma and before the next key to make them easier to read but this is not required.
The value of all arguments are read as strings.
Example
${var my_query::default=true, transform=bool}
${env MY_QUERY::default=1,transform=bool}
Each Lookup may have their own, specific arguments that it uses to modify its functionality or the value it returns.
There is also a common set of arguments that all Lookups accept.
Common Lookup Arguments
default (Any) If the Lookup is unable to find a value for the provided query, this value will be returned instead of
raising an exception.
get (Optional[str]) Can be used on a dictionary type object to retrieve a specific piece of data. This is executed after
the optional load step.
indent (Optional[int]) Number of spaces to use per indent level when transforming a dictionary type object to a
string.
load (Optional[str]) Load the data to be processed by a Lookup using a specific parser. This is the first action taking
on the data after it has been retrieved from its source. The data must be in a format that is supported by the
parser in order for it to be used.
json Loads a JSON seralizable string into a dictionary like object.
troposphere Loads the properties of a subclass of troposphere.BaseAWSObject into a dictionary.
yaml Loads a YAML seralizable string into a dictionary like object.
region (Optional[str]) AWS region used when creating a boto3.Session to retrieve data. If not provided, the
region currently being processed will be used. This can be specified to always get data from one region regardless
of region is being deployed to.
transform (Optional[str]) Transform the data that will be returned by a Lookup into a different data type. This is the
last action taking on the data before it is returned. Supports the following:
9.6. Terraform 317
runway Documentation, Release 1.18.3
str Converts any value to a string. The original data type determines the end result.
list, set, and tuple will become a comma delimited list
dict and anything else will become an escaped JSON string.
bool Converts a string or boolean value into a boolean.
Example
deployments:
- parameters:
some_variable: ${var some_value::default=my_value}
comma_list: ${var my_list::default=undefined, transform=str}
class runway.lookups.handlers.base.LookupHandler
Bases: object
Base class for lookup handlers.
classmethod dependencies(_lookup_data)
Calculate any dependencies required to perform this lookup.
Note that lookup_data may not be (completely) resolved at this time.
Parameters lookup_data (VariableValue) – Parameter(s) given to this lookup.
Returns Set
classmethod format_results(value, get=None, load=None, transform=None, **kwargs)
Format results to be returned by a lookup.
Parameters
• value (Any) – Data collected by the Lookup.
• get (Optional[str]) – Nested value to get from a dictionary like object.
• load (Optional[str]) – Parser to use to parse a formatted string before the get and
transform method.
• transform (Optional[str]) – Convert the final value to a different data type before
returning it.
Raises TypeError – If get is provided but the value value is not a dictionary like object.
Runs the following actions in order:
1. load() if load is provided.
2. runway.util.MutableMap.find() or dict.get() depending on the data type if get is
provided.
3. transform() if transform is provided.
classmethod handle(value, context, **kwargs)
Perform the lookup.
Parameters
• value – Parameter(s) given to the lookup.
• context – The current context object.
• provider – Optional provider to use when handling the lookup.
318 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Returns (Any) Looked-up value.
classmethod parse(value)
Parse the value passed to a lookup in a standardized way.
Parameters value – The raw value passed to a lookup.
Returns The lookup query and a dict of arguments
classmethod load(value, parser=None, **kwargs)
Load a formatted string or object into a python data type.
First action taken in format_results(). If a lookup needs to handling loading data to process it
before it enters format_results(), is should use args.pop('load') to prevent the data from
being loaded twice.
Parameters
• value – What is being loaded.
• parser – Name of the parser to use.
Returns The loaded value.
classmethod transform(value, to_type='str', **kwargs)
Transform the result of a lookup into another datatype.
Last action taken in format_results(). If a lookup needs to handling transforming the data in a
way that the base class can’t support it should overwrite this method of the base class to register different
transform methods.
Parameters
• value – What is to be transformed.
• to_type – The type the value will be transformed into.
Returns The transformed value.
runway.lookups.handlers.cfn module
Retrieve a value from CloudFormation Stack Outputs.
The query syntax for this lookup is <stack-name>.<output-name>. When specifying the output name, be sure
to use the Logical ID of the output; not the Export.Name.
If the Lookup is unable to find a CloudFormation Stack Output matching the provided query, the default value is
returned or an exception is raised to show why the value could be be resolved (e.g. Stack does not exist or output does
not exist on the Stack).
See also:
https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/outputs-section-structure.html
9.6. Terraform 319
runway Documentation, Release 1.18.3
Arguments
This Lookup supports all Common Lookup Arguments.
Example
Listing 6: Runway config
deployments:
- modules:
path: sampleapp.tf
options:
terraform_backend_config:
bucket: ${cfn common-tf-state.TerraformStateBucketName::region=us-east-1}
dynamodb_table: ${cfn common-tf-state.TerraformStateTableName::region=us-
˓→east-1}
region: us-east-1
Listing 7: CFNgin config
stacks:
my-stack:
variables:
SomeParameter: ${cfn AnotherStack.OutputName}
class runway.lookups.handlers.cfn.OutputQuery(stack_name, output_name)
Bases: tuple
Create new instance of OutputQuery(stack_name, output_name)
property output_name
Alias for field number 1
property stack_name
Alias for field number 0
class runway.lookups.handlers.cfn.CfnLookup
Bases: runway.lookups.handlers.base.LookupHandler
CloudFormation Stack Output lookup.
static should_use_provider(args, provider)
Determine if the provider should be used for the lookup.
This will open happen when the lookup is used with CFNgin.
Parameters
• args – Parsed arguments provided to the lookup.
• provider – CFNgin provider.
static get_stack_output(client, query)
Get CloudFormation Stack output.
Parameters
• client – Boto3 CloudFormation client.
• query (OutputQuery) – What to get.
Returns Value of the requested output.
320 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Return type str
classmethod handle(value, context, provider=None, **_)
Retrieve a value from CloudFormation Stack outputs.
Parameters
• value – The value passed to the Lookup.
• context – The current context object.
• provider – AWS provider.
Returns Result of the query.
Raises OutputDoesNotExist – Output does not exist on the Stack provided and default was
not provided.
runway.lookups.handlers.ecr module
Retrieve a value from AWS Elastic Container Registry (ECR).
This Lookup only supports very specific queries.
Supported Queries
login-password
Get a password to login to ECR registry.
The returned value can be passed to the login command of the container client of your preference, such as the Docker
CFNgin hook. After you have authenticated to an Amazon ECR registry with this Lookup, you can use the client to
push and pull images from that registry as long as your IAM principal has access to do so until the token expires. The
authorization token is valid for 12 hours.
Arguments
This Lookup does not support any arguments.
Example
Listing 8: runway.yml
deployments:
- modules:
- path: example.cfn
parameters:
ecr_password: ${ecr login-password}
...
9.6. Terraform 321
runway Documentation, Release 1.18.3
Listing 9: cfngin.yml
pre_build:
- path: runway.cfngin.hooks.docker.login
args:
password: ${ecr login-password}
...
class runway.lookups.handlers.ecr.EcrLookup
Bases: runway.lookups.handlers.base.LookupHandler
ECR Lookup.
static get_login_password(client)
Get a password to login to ECR registry.
classmethod handle(value, context, **_)
Retrieve a value from AWS Elastic Container Registry (ECR).
Parameters
• value – The value passed to the Lookup.
• context – The current context object.
runway.lookups.handlers.env module
Retrieve a value from an environment variable.
The value is retrieved from a copy of the current environment variables that is saved to the context object. These envi-
ronment variables are manipulated at runtime by Runway to fill in additional values such as DEPLOY_ENVIRONMENT
and AWS_REGION to match the current execution.
Note: DEPLOY_ENVIRONMENT and AWS_REGION can only be resolved during the processing of a module. To
ensure no error occurs when trying to resolve one of these in a Deployment definition, provide a default value.
If the Lookup is unable to find an environment variable matching the provided query, the default value is returned or a
ValueError is raised if a default value was not provided.
Arguments
This Lookup supports all Common Lookup Arguments but, the folling have limited or no effect:
• region
Example
deployment:
- modules:
- path: sampleapp.cfn
parameters:
creator: ${env USER}
env_vars:
ENVIRONMENT: ${env DEPLOY_ENVIRONMENT::default=default}
322 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
class runway.lookups.handlers.env.EnvLookup
Bases: runway.lookups.handlers.base.LookupHandler
Environment variable Lookup.
classmethod handle(value, context, **_)
Retrieve an environment variable.
The value is retrieved from a copy of the current environment variables that is saved to the context object.
These environment variables are manipulated at runtime by Runway to fill in additional values such as
DEPLOY_ENVIRONMENT and AWS_REGION to match the current execution.
Parameters
• value – The value passed to the Lookup.
• context – The current context object.
Raises ValueError – Unable to find a value for the provided query and a default value was
not provided.
runway.lookups.handlers.ssm module
Retrieve a value from SSM Parameter Store.
If the Lookup is unable to find an SSM Parameter matching the provided query, the default value is returned or
ParameterNotFound is raised if a default value is not provided.
Parameters of type SecureString are automatically decrypted.
Parameters of type StringList are returned as a list.
Arguments
This Lookup supports all Common Lookup Arguments.
Example
deployment:
- modules:
- path: sampleapp.cfn
parameters:
secret_value: ${ssm /example/secret}
conf_file: ${ssm /example/config/json::load=json, get=value}
toggle: ${ssm toggle::load=yaml, get=val, transform=bool}
env_vars:
SOME_VARIABLE: ${ssm /example/param::region=us-east-1}
DEFAULT_VARIABLE: ${ssm /example/default::default=default}
class runway.lookups.handlers.ssm.SsmLookup
Bases: runway.lookups.handlers.base.LookupHandler
SSM Parameter Store Lookup.
classmethod handle(value, context, **_)
Retrieve a value from SSM Parameter Store.
Parameters
9.6. Terraform 323
runway Documentation, Release 1.18.3
• value – The value passed to the Lookup.
• context – The current context object.
Raises ParameterNotFound – Parameter not found in SSM and a default value was not
provided.
runway.lookups.handlers.var module
Retrieve a variable from the variables file or definition.
If the Lookup is unable to find an defined variable matching the provided query, the default value is returned or a
ValueError is raised if a default value was not provided.
Nested values can be used by providing the full path to the value but, it will not select a list element.
The returned value can contain any YAML support data type (dictionaries/mappings/hashes, lists/arrays/sequences,
strings, numbers, and booleon).
Arguments
This Lookup supports all Common Lookup Arguments but, the folling have limited or no effect:
• region
Example
deployment:
- modules:
- path: sampleapp.cfn
parameters:
ami_id: ${var ami_id.${env AWS_REGION}}
env_vars:
SOME_VARIABLE: ${var some_variable::default=default}
class runway.lookups.handlers.var.VarLookup
Bases: runway.lookups.handlers.base.LookupHandler
Variable definition Lookup.
classmethod handle(value, context, **kwargs)
Retrieve a variable from the variable definition.
The value is retrieved from the variables passed to Runway using either a variables file or the variables
directive of the config file.
Parameters
• value – The value passed to the Lookup.
• variables – The resolved variables pass to Runway.
Raises ValueError – Unable to find a value for the provided query and a default value was
not provided.
324 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
runway.module package
Runway module module.
class runway.module.ModuleOptions
Bases: collections.abc.MutableMapping
Base class for Runway module options.
static merge_nested_env_dicts(data, env_name=None)
Merge nested env dicts.
Parameters
• data (Any) – Data to try to merge.
• env_name (Optional[str]) – Current environment.
Returns Any
classmethod parse(context, **kwargs)
Parse module options definition to extract usable options.
Parameters context (Context) – Runway context object.
class runway.module.RunwayModule(context, path, options=None)
Bases: object
Base class for Runway modules.
Instantiate class.
Parameters
• context (Context) – Runway context object.
• path (Union[str, Path]) – Path to the module.
• options (Dict[str, Dict[str, Any]]) – Everything in the module definition
merged with applicable values from the deployment definition.
deploy()
Implement dummy method (set in consuming classes).
destroy()
Implement dummy method (set in consuming classes).
plan()
Implement dummy method (set in consuming classes).
class runway.module.RunwayModuleNpm(context, path, options=None)
Bases: runway.module.RunwayModule
Base class for Runway modules that use npm.
Instantiate class.
Parameters
• context (Context) – Runway context object.
• path (Union[str, Path]) – Path to the module.
• options (Dict[str, Dict[str, Any]]) – Everything in the module definition
merged with applicable values from the deployment definition.
9.6. Terraform 325
runway Documentation, Release 1.18.3
check_for_npm()
Ensure npm is installed and in the current path.
log_npm_command(command)
Log an npm command that is going to be run.
Parameters command (List[str]) – List that will be passed into a subprocess.
npm_install()
Run npm install.
package_json_missing()
Check for the existence for a package.json file in the module.
Returns True if the file was not found.
Return type bool
runway.module.format_npm_command_for_logging(command)
Convert npm command list to string for display to user.
runway.module.generate_node_command(command, command_opts, path, log-
ger=<RunwayLogger runway.module (WARNING)>)
Return node bin command list for subprocess execution.
runway.module.run_module_command(cmd_list, env_vars, exit_on_error=True, log-
ger=<RunwayLogger runway.module (WARNING)>)
Shell out to provisioner command.
runway.module.run_npm_install(path, options, context, logger=<RunwayLogger runway.module
(WARNING)>)
Run npm install/ci.
runway.module.use_npm_ci(path)
Return true if npm ci should be used in lieu of npm install.
runway.module.warn_on_boto_env_vars(env_vars)
Inform user if boto-specific environment variables are in use.
Submodules
runway.module.cdk module
CDK module.
runway.module.cdk.get_cdk_stacks(module_path, env_vars, context_opts)
Return list of CDK stacks.
class runway.module.cdk.CloudDevelopmentKit(context, path, options=None)
Bases: runway.module.RunwayModule
CDK Runway Module.
Instantiate class.
Parameters
• context (Context) – Runway context object.
• path (Union[str, Path]) – Path to the module.
• options (Dict[str, Dict[str, Any]]) – Everything in the module definition
merged with applicable values from the deployment definition.
326 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
run_cdk(command='deploy')
Run CDK.
plan()
Run cdk diff.
deploy()
Run cdk deploy.
destroy()
Run cdk destroy.
runway.module.cloudformation module
Cloudformation module.
class runway.module.cloudformation.CloudFormation(context, path, options=None)
Bases: runway.module.RunwayModule
CloudFormation (Stacker) Runway Module.
Instantiate class.
Parameters
• context (Context) – Runway context object.
• path (Union[str, Path]) – Path to the module.
• options (Dict[str, Dict[str, Any]]) – Everything in the module definition
merged with applicable values from the deployment definition.
deploy()
Run stacker build.
destroy()
Run stacker destroy.
plan()
Run stacker diff.
runway.module.k8s module
K8s (kustomize) module.
runway.module.k8s.gen_overlay_dirs(environment, region)
Generate possible overlay directories.
runway.module.k8s.get_module_defined_k8s_ver(k8s_version_opts, env_name)
Return version of Terraform requested in module options.
runway.module.k8s.get_overlay_dir(overlays_path, environment, region)
Determine overlay directory to use.
runway.module.k8s.generate_response(overlay_path, module_path, environment, region)
Determine if environment is defined.
class runway.module.k8s.K8s(context, path, options=None)
Bases: runway.module.RunwayModule
Kubectl Runway Module.
9.6. Terraform 327
runway Documentation, Release 1.18.3
Instantiate class.
Parameters
• context (Context) – Runway context object.
• path (Union[str, Path]) – Path to the module.
• options (Dict[str, Dict[str, Any]]) – Everything in the module definition
merged with applicable values from the deployment definition.
run_kubectl(command='plan')
Run kubectl.
plan()
Run kustomize build and display generated plan.
deploy()
Run kubectl apply.
destroy()
Run kubectl delete.
runway.module.serverless module
Serverless module.
runway.module.serverless.gen_sls_config_files(stage, region)
Generate possible SLS config files names.
runway.module.serverless.run_sls_print(sls_opts, env_vars, path)
Run sls print command.
runway.module.serverless.get_src_hash(sls_config, path)
Get hash(es) of serverless source.
runway.module.serverless.deploy_package(sls_opts, bucketname, context, path, log-
ger=<RunwayLogger runway.module.serverless
(WARNING)>)
Run sls package command.
Parameters
• sls_opts (List[str]) – List of options for Serverless CLI.
• bucketname (str) – S3 Bucket name.
• context (Context) – Runway context object.
• path (str) – Module path.
• logger (Optional[logging.Logger]) – A more granular logger for log messages.
class runway.module.serverless.Serverless(context, path, options=None)
Bases: runway.module.RunwayModuleNpm
Serverless Runway Module.
Instantiate class.
Parameters
• context (Context) – Runway context object.
• path (str) – Path to the module.
328 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
• options (Dict[str, Dict[str, Any]]) – Everything in the module definition
merged with applicable values from the deployment definition.
property cli_args
Generate CLI args from self used in all Serverless commands.
Returns List[str]
env_file
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
property skip
Determine if the module should be skipped.
Returns To skip, or not to skip, that is the question.
Return type bool
extend_serverless_yml(func)
Extend the Serverless config file with additional YAML from options.
Parameters func (Callable) – Callable to use after handling the Serverless config file.
gen_cmd(command, args_list=None)
Generate and log a Serverless command.
This does not execute the command, only prepares it for use.
Parameters
• command (str) – The Serverless command to be executed.
• args_list (Optiona[List[str]]) – Additional arguments to include in the gen-
erated command.
Returns The full command to be passed into a subprocess.
Return type List[str]
sls_deploy(skip_install=False)
Execute sls deploy command.
Parameters skip_install (bool) – Skip npm install before running the Serverless
command. (default: False)
sls_print(item_path=None, skip_install=False)
Execute sls print command.
Keyword Arguments
• item_path (Optional[str]) – Period-separated path to print a sub-value (eg:
“provider.name”).
• skip_install (bool) – Skip npm install before running the Serverless com-
mand. (default: False)
Returns Resolved Serverless config file.
Return type Dict[str, Any]
Raises SystemExit – If a runway-tmp.serverless.yml file already exists.
9.6. Terraform 329
runway Documentation, Release 1.18.3
sls_remove(skip_install=False)
Execute sls remove command.
Parameters skip_install (bool) – Skip npm install before running the Serverless
command. (default: False)
plan()
Entrypoint for Runway’s plan action.
deploy()
Entrypoint for Runway’s deploy action.
destroy()
Entrypoint for Runway’s destroy action.
class runway.module.serverless.ServerlessOptions(args, extend_serverless_yml, pro-
motezip, skip_npm_ci=False)
Bases: runway.module.ModuleOptions
Module options for Serverless.
Instantiate class.
Keyword Arguments
• args (List[str]) – Arguments to append to Serverless CLI commands. These will
always be placed after the default arguments provided by Runway.
• extend_serverless_yml (Dict[str, Any]) – If provided, a temporary Server-
less config will be created will be created from what exists in the module directory then the
value of this option will be merged into it. The temporary file will be deleted at the end of
execution.
• promotezip (Dict[str, str]) – If provided, promote Serverless generated zip files
between environments from a build AWS account.
• skip_npm_ci (bool) – Skip the npm ci Runway executes at the begining of each
Serverless module run.
property args
Args to pass to the CLI.
Returns List of arguments.
Return type List[str]
update_args(key, value)
Update a known CLI argument.
Parameters
• key (str) – Dict key to be updated.
• value (str) – New value
Raises KeyError – The key provided for update is now a known arg.
classmethod parse(**kwargs)
Parse the options definition and return an options object.
Keyword Arguments
• args (Optional[List[str]]) – Arguments to append to Serverless CLI com-
mands. These will always be placed after the default arguments provided by Runway.
330 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
• extend_serverless_yml (Optional[Dict[str, Any]]) – If provided, a
temporary Serverless config will be created will be created from what exists in the module
directory then the value of this option will be merged into it. The temporary file will be
deleted at the end of execution.
• promotezip (Optional[Dict[str, str]]) – If provided, promote Serverless
generated zip files between environments from a build AWS account.
• skip_npm_ci (bool) – Skip the npm ci Runway executes at the begining of each
Serverless module run.
Returns ServerlessOptions
Raises ValueError – promotezip was provided but missing bucketname.
runway.module.staticsite module
Static website module.
runway.module.staticsite.add_url_scheme(url)
Add the scheme to an existing url.
Parameters url (str) – The current url.
class runway.module.staticsite.StaticSite(context, path, options=None)
Bases: runway.module.RunwayModule
Static website Runway Module.
Initialize.
plan()
Create website CFN module and run stacker diff.
deploy()
Create website CFN module and run stacker build.
destroy()
Create website CFN module and run stacker destroy.
runway.module.terraform module
Terraform module.
runway.module.terraform.gen_workspace_tfvars_files(environment, region)
Generate possible Terraform workspace tfvars filenames.
runway.module.terraform.update_env_vars_with_tf_var_values(os_env_vars, tf_vars)
Return os_env_vars with TF_VAR_ values for each tf_var.
class runway.module.terraform.Terraform(context, path, options=None)
Bases: runway.module.RunwayModule
Terraform Runway Module.
Instantiate class.
Parameters
• context (Context) – Runway context object.
• path (Union[str, Path]) – Path to the module.
9.6. Terraform 331
runway Documentation, Release 1.18.3
• options (Dict[str, Dict[str, Any]]) – Everything in the module definition
merged with applicable values from the deployment definition.
auto_tfvars
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
current_workspace
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
env_file
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
property skip
Determine if the module should be skipped.
Returns To skip, or not to skip, that is the question.
Return type bool
tfenv
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
tf_bin
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
cleanup_dot_terraform()
Remove .terraform excluding the plugins directly.
This step is crucial for allowing Runway to deploy to multiple regions or deploy environments without
promping the user for input.
The plugins directory is retained to improve performance when they are used by subsequent runs.
gen_command(command, args_list=None)
Generate Terraform command.
handle_backend()
Handle backend configuration.
This needs to be run before “skip” is assessed or env_file/auto_tfvars is used in case their behavior needs
to be altered.
handle_parameters()
Handle parameters.
332 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Either updating environment variables or writing to a file.
terraform_apply()
Execute terraform apply command.
https://www.terraform.io/docs/commands/apply.html
terraform_destroy()
Execute terraform destroy command.
https://www.terraform.io/docs/commands/destroy.html
terraform_get()
Execute terraform get command.
https://www.terraform.io/docs/commands/get.html
terraform_init()
Execute terraform init command.
https://www.terraform.io/docs/commands/init.html
terraform_plan()
Execute terraform plan command.
https://www.terraform.io/docs/commands/plan.html
terraform_workspace_list()
Execute terraform workspace list command.
https://www.terraform.io/docs/commands/workspace/list.html
Returns The available Terraform workspaces.
Return type str
terraform_workspace_new(workspace)
Execute terraform workspace new command.
https://www.terraform.io/docs/commands/workspace/new.html
Parameters workspace (str) – Terraform workspace to create.
terraform_workspace_select(workspace)
Execute terraform workspace select command.
https://www.terraform.io/docs/commands/workspace/select.html
Parameters workspace (str) – Terraform workspace to select.
terraform_workspace_show()
Execute terraform workspace show command.
https://www.terraform.io/docs/commands/workspace/show.html
Returns The current Terraform workspace.
Return type str
run(action)
Run module.
plan()
Run Terraform plan.
deploy()
Run Terraform apply.
9.6. Terraform 333
runway Documentation, Release 1.18.3
destroy()
Run Terraform destroy.
class runway.module.terraform.TerraformOptions(args, backend, workspace, ver-
sion=None, write_auto_tfvars=False)
Bases: runway.module.ModuleOptions
Module options for Terraform.
Instantiate class.
Parameters
• args (Union[Dict[str, List[str]], List[str]]) – Arguments to append to
Terraform CLI commands. If providing a list, all arguments will be passed to terraform
apply only. Can also be provided as a mapping to pass arguments to terraform
apply, terraform init, and/or terraform plan.
• backend (TerraformBackendConfig) – Backend configuration.
• workspace (str) – Name of the Terraform workspace to use. While it is recommended
to let Runway manage this automatically, it has been exposed as an option for cases when a
static workspace needs to be used (e.g. remote backend).
• version (Optional[str]) – Terraform version.
• write_auto_tfvars (bool) – Optionally write parameters to a tfvars file instead of
updating environment variables.
static resolve_version(context, terraform_version=None, **_)
Resolve terraform_version option.
classmethod parse(context, path=None, **kwargs)
Parse the options definition and return an options object.
Parameters
• context (Context) – Runway context object.
• path (Optional[Path]) – Path to the module.
Keyword Arguments
• args (Union[Dict[str, List[str]], List[str]]) – Arguments to append
to Terraform CLI commands. If providing a list, all arguments will be passed to
terraform apply only. Can also be provided as a mapping to pass arguments to
terraform apply, terraform init, and/or terraform plan.
• terraform_backend_config (Optional[Dict[str, str]]) – Mapping of
Terraform backend configuration options.
• terraform_backend_cfn_outputs (Optional[Dict[str, str]]) – Map-
ping of Terraform backend configuration options whose values are stored in Cloudforma-
tion outputs.
• terraform_backend_ssm_params (Optional[Dict[str, str]]) – Map-
ping of Terraform backend configuration options whose values are stored in SSM param-
eters.
• terraform_version (Optional[Union[Dict[str, str], str]]) – Ver-
sion of Terraform to use when processing a module.
• terraform_workspace (str) – Name of the Terraform workspace to use. While it is
recommended to let Runway manage this automatically, it has been exposed as an option
for cases when a static workspace may be needed.
334 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
• terraform_write_auto_tfvars (bool) – Optionally write parameters to a tfvars
file instead of updating environment variables.
Returns TerraformOptions
class runway.module.terraform.TerraformBackendConfig(context, config_file=None,
**kwargs)
Bases: runway.module.ModuleOptions
Terraform backend configuration module options.
OPTIONS
A list of option names that are parsed by this class.
Type List[str]
Instantiate class.
See Terraform documentation for the keyword arguments needed for the desired backend.
https://www.terraform.io/docs/backends/types/index.html
OPTIONS = ['terraform_backend_config', 'terraform_backend_cfn_outputs', 'terraform_backend_ssm_params']
init_args
Decorator for creating cached properties.
A property that is only computed once per instance and then replaces itself with an ordinary at-
tribute. Deleting the attribute resets the property. Source: https://github.com/bottlepy/bottle/commit/
fa7733e075da0d790d809aa3d2f53071897e6f76
get_full_configuration()
Get full backend configuration.
static resolve_cfn_outputs(client, **kwargs)
Resolve CloudFormation output values.
Parameters client (CloudformationClient) – Boto3 Cloudformation client.
Keyword Arguments
• bucket (Optional[str]) – Cloudformation output containing an S3 bucket name.
• dynamodb_table (Optional[str]) – Cloudformation output containing a Dy-
namoDB table name.
Returns Resolved values from Cloudformation.
Return type Dict[str, str]
static resolve_ssm_params(client, **kwargs)
Resolve SSM parameters.
Parameters client (SSMClient) – Boto3 SSM client.
Keyword Arguments
• bucket (Optional[str]) – SSM parameter containing an S3 bucket name.
• dynamodb_table (Optional[str]) – SSM parameter containing a DynamoDB ta-
ble name.
Returns Resolved values from SSM.
Return type Dict[str, str]
static gen_backend_filenames(environment, region)
Generate possible Terraform backend filenames.
9.6. Terraform 335
runway Documentation, Release 1.18.3
Parameters
• environment (str) – Current deploy environment.
• region (str) – Current AWS region.
Returns List of possible file names.
Return type List[str]
classmethod get_backend_file(path, environment, region)
Determine Terraform backend file.
Parameters
• path (Path) – Path to the module.
• environment (str) – Current deploy environment.
• region (str) – Current AWS region.
Returns Path to a hcl/tfvars file.
Return type Optional[Path]
classmethod parse(context, path=None, **kwargs)
Parse backend options and return an options object.
Parameters
• context (Context) – Runway context object.
• path (Optional[Path]) – Path to the module.
Keyword Arguments
• terraform_backend_config (Optional[Dict[str, str]]) – Mapping of
Terraform backend configuration options.
• terraform_backend_cfn_outputs (Optional[Dict[str, str]]) – Map-
ping of Terraform backend configuration options whose values are stored in Cloudforma-
tion outputs.
• terraform_backend_ssm_params (Optional[Dict[str, str]]) – Map-
ping of Terraform backend configuration options whose values are stored in SSM param-
eters.
Returns TerraformBackendConfig
runway.sources package
Empty init for python import traversal.
336 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Submodules
runway.sources.git module
‘Git’ type Path Source.
class runway.sources.git.Git(uri='', location='', options=None, **kwargs)
Bases: runway.sources.source.Source
Git Path Source.
The Git path source can be tasked with cloning a remote repository and pointing to a specific module folder (or
the root).
Git Path Source.
Keyword Arguments
• uri (str) – The uniform resource identifier that targets the remote git repository
• location (string) – The relative location to the root of the repository where the module
resides. Leaving this as an empty string, /, or ./ will have runway look in the root folder.
• options (Union(None, Dict[str, str])) – A reference can be passed along via
the options so that a specific version of the repository is cloned. commit, tag, branch are
all valid keys with respective output
fetch()
Retrieve the git repository from it’s remote location.
classmethod sanitize_git_path(path)
Sanitize the git path for folder/file assignment.
Keyword Arguments path (str) – The path string to be sanitized
runway.sources.source module
Abstract parent class for a ‘Source’ type object.
Allows us to specify specific remote sourced resources for out application (Git, S3, ect.)
class runway.sources.source.Source(cache_dir='', **_)
Bases: object
Abstract parent class for a ‘Source’ type object.
The Source parent class allows us to specify remote resources for our application via services such as Git or
S3. A cache directory, as part of object’s configuration, is automatically created by default in the users home
directory: ~/.runway_cache. This folder can be overridden by specifying the cache_dir property in the
configuration passed.
Every Source type object is expected to have a fetch method which will return the folder path at where the
module requested resides.
Source.
Parameters cache_dir (str) – The directory where the given remote resource should be cached
fetch()
Retrieve remote source. To be implemented in each subclass.
9.6. Terraform 337
runway Documentation, Release 1.18.3
static sanitize_directory_path(uri)
Sanitize a Source directory path string.
Parameters uri (str) – The uniform resource identifier when targetting a remote resource.
runway.tests package
Empty init for python import traversal.
Submodules
runway.tests.registry module
Register test handlers.
runway.tests.registry.register_test_handler(test_type, handler_or_path)
Register a test handler.
Parameters
• test_type (str) – Name to register the handler under.
• handler_or_path (OneOf[func, str]) – Function or a path to a handler.
runway.tests.registry.unregister_test_handler(test_type)
Unregister the specified test type.
This is useful when testing various lookup types if you want to unregister the lookup type after the test runs.
Parameters test_type (str) – Name of the lookup type to unregister.
Subpackages
runway.tests.handlers package
Import classes.
Submodules
runway.tests.handlers.base module
Base module for test handlers.
class runway.tests.handlers.base.TestHandler
Bases: object
Base class for test handlers.
classmethod handle(name, args)
Redefine in subclass.
static get_dirs(provided_path)
Return list of directories.
338 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
runway.tests.handlers.cfn_lint module
cfn-list test runner.
class runway.tests.handlers.cfn_lint.CfnLintHandler
Bases: runway.tests.handlers.base.TestHandler
Lints CFN.
classmethod handle(name, args)
Perform the actual test.
Relies on .cfnlintrc file to be located beside the Runway config file.
runway.tests.handlers.script module
Script test runner.
class runway.tests.handlers.script.ScriptHandler
Bases: runway.tests.handlers.base.TestHandler
Handle script tests.
Parameters commands (List[str]) – A list of commands to be executed in order. Each com-
mand is run in its own subprocess. The working directory will be the same as where the ‘runway
test’ command was executed.
Example
tests:
• name: example-test type: script args:
commands:
– echo “this is an example”
– pwd
classmethod handle(name, args)
Perform the actual test.
runway.tests.handlers.yaml_lint module
yamllint test runner.
class runway.tests.handlers.yaml_lint.YamllintHandler
Bases: runway.tests.handlers.base.TestHandler
Lints yaml.
static get_yaml_files_at_path(provided_path)
Return list of yaml files.
classmethod get_yamllint_options(path)
Return yamllint option list.
classmethod handle(name, args)
Perform the actual test.
9.6. Terraform 339
runway Documentation, Release 1.18.3
9.6.5 Advanced Configuration
This section has been placed in the Developer Guide because it details advanced configuration that should only be
used by those with intimate knowledge of how Runway works.
Environment Variables
Environment variables can be used to alter the functionality of Runway.
CI (Any) If not undefined, Runway will operate in non-iterative mode.
DEBUG (int) Used to select the debug logs to display
• 0 or not defined with show no debug logs
• 1 will show Runway’s debug logs
• 2 will show Runway’s debug logs and some dependency debug logs (e.g. botocore)
DEPLOY_ENVIRONMENT (str) Explicitly define the deploy environment.
CFNGIN_STACK_POLL_TIME (int) Number of seconds between CloudFormation API calls. Adjusting this will
impact API throttling. (default: 30)
RUNWAY_COLORIZE (str) Explicitly enable/disable colorized output for CDK, Serverless, and Terraform mod-
ules. Having this set to a truthy value will prevent -no-color/--no-color from being added to any com-
mands even if stdout is not a TTY. Having this set to a falsy value will include -no-color/--no-color
in commands even if stdout is a TTY. If the IaC tool has other mechanisms for disabling color output, using a
truthy value will not circumvent them.
Truthy values are y, yes, t, true, on and 1. Falsy values are n, no, f, false, off and 0. Raises
ValueError if anything else is used.
RUNWAY_MAX_CONCURRENT_MODULES (int) Max number of modules that can be deployed to concur-
rently. (default: min(61, os.cpu_count()))
On Windows, this must be equal to or lower than 61.
IMPORTANT: When using parallel_regions and child_modules together, please consider the na-
ture of their relationship when manually setting this value. (parallel_regions
*
child_modules)
RUNWAY_MAX_CONCURRENT_REGIONS (int) Max number of regions that can be deployed to concurrently.
(default: min(61, os.cpu_count()))
On Windows, this must be equal to or lower than 61.
IMPORTANT: When using parallel_regions and child_modules together, please consider the na-
ture of their relationship when manually setting this value. (parallel_regions
*
child_modules)
RUNWAY_LOG_FIELD_STYLES (str) Can be provided to customize the styling (color, bold, etc) used for Lo-
gRecord attributes (except for message). By default, Runway does not apply style to fields. For information on
how to format the value, see the documentation provided by coloredlogs.
RUNWAY_LOG_FORMAT (str) Can be provided to use a custom log message format. The value should be a
format string using %-formatting. In addition to being able to use LogRecord attributes in the string, Runway
provides the additional fields of %(hostname)s and %(programname)s.
If not provided, [%(programname)s] %(message)s is used unless using debug, verbose or no color. In
that case, %(levelname)s:%(name)s:%(message)s is used.
RUNWAY_LOG_LEVEL_STYLES (str) Can be provided to customize the styling (color, bold, etc) used for log
messages sent to each log level. If provided, the parsed value will be merged with Runway’s default styling. For
information on how to format the value, see the documentation provided by coloredlogs.
340 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
RUNWAY_NO_COLOR (Any) Disable Runway’s colorized logs. Providing this will also change the log format to
%(levelname)s:%(name)s:%(message)s.
VERBOSE (Any) If not undefined, Runway will display verbose logs and change the logging format to
%(levelname)s:%(name)s:%(message)s.
9.6.6 Contribution Requirements
Please review our Getting Started Guide for Developers before working on your contribution. It contains information
on setting up a development environment to make following some of these requirements easier.
Branch Requirements
Branches must start with one of the following prefixes (e.g. <prefix>/<your-branch-name>). This is due to
how labels are applied to PRs. If the branch does not meet the requirement, any PRs from it will be blocked from
being merged.
bugfix | fix | hotfix The branch contains a fix for a big.
feature | feat The branch contains a new feature or enhancement to an existing feature.
docs | documentation The branch only contains updates to documentation.
maintain | maint | maintenance The branch does not contain changes to the project itself to is aimed at maintaining
the repo, CI/CD, or testing infrastructure. (e.g. README, GitHub action, integration test infrastructure)
release Reserved for maintainers to prepare for the release of a new version.
Documentation Requirements
Docstrings
In general, we loosely follow the Google Python Style Guide for Comments and Docstrings.
We use the napoleon extension for Sphinx to parse docstrings. Napoleon provides an Example Google Style Python
Docstring that can be referenced.
reStructuredText Formatting
In general, we loosely follow the Python Style Guide for documentation.
Note: Not all documentation pages follow this yet. If the page you are updating deviates from this format, adapt to
the format of the page.
9.6. Terraform 341
runway Documentation, Release 1.18.3
Headings
Section headers are created by underlining (and optionally overlining) the section title with a punctuation character, at
least as long as the text.
1. # with overline, for h1 (generally only one per file, at the top of the file)
2.
*
with overline, for h2
3. =, for h3
4. -, for h4
5. ^, for h5
6. ", for h6
h1 and h2 should have two blank lines separating them from sections with headings of the same level or higher.
A ‘’rubric” directive can be used to create a non-indexed heading.
Example
#########
Heading 1
#########
*********
Heading 2
*********
Heading 3
=========
Heading 4
---------
Heading 5
^^^^^^^^^
Heading 6
"""""""""
.. rubric:: Non-indexed Heading
*********
Heading 2
*********
Heading 3
=========
342 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
PR Requirements
In order for a PR to be merged it must be passing all checks and be approved by at least one maintainer. Some of the
checks can be run locally using make lint and make test.
To be considered for approval, the PR must meet the following requirements.
• Title must be a brief explanation of what was done in the PR (think commit message).
• A summary of was done.
• Explain why this change is needed.
• Detail the changes that were made (think CHANGELOG).
• Screenshot if applicable.
• Include tests for any new features or changes to existing features. (unit tests and integration tests depending on
the nature of the change)
• Documentation was updated for any new feature or changes to existing features.
9.6.7 Custom Plugin Support
Need to expand Runway to wrap other tools? Yes - you can do that with custom plugin support.
Overview
Runway can import Python modules that can perform custom deployments with your own set of Runway modules.
Let’s say for example you want to have Runway execute an Ansible playbook to create an EC2 security group as one
of the steps in the middle of your Runway deployment list - this is possible with your own plugin. The custom plugin
support allows you to mix-and-match natively supported modules (e.g. CloudFormation, Terraform) with plugins you
write providing additional support for non-native modules. Although written in Python, these plugins can natively
execute non Python binaries.
RunwayModule Class
Runway provides a Python Class named RunwayModule that can be imported into your custom plugin/Python
module. This base class will give you the ability to write your own module that can be added to your runway.yml
deployment list (More info on runway.yml below). There are three required functions:
plan This code block gets called when runway taxi executes
deploy This code block gets called when runway takeoff executes
destroy This code block gets called when runway destroy executes
All of these functions are required, but are permitted to be empty no-op/pass statements if applicable.
9.6. Terraform 343
runway Documentation, Release 1.18.3
Context Object
self.context includes many helpful resources for use in your Python module. Some notable examples are:
- self.context.env_name - name of the environment
- self.context.env_region - region in which the module is being executed
- self.context.env_vars - OS environment variables provided to the module
- self.path - path to your Runway module folder
runway.yml Example
After you have written your plugin, you need to add the module class_path to your module’s configuration. Below
is an example runway.yml containing a single module that looks for an Ansible playbook in a folder at the root of
your Runway environment (i.e. repo) named “security_group.ansible”.
Setting class_path tells Runway to import the DeployToAWS Python class, from a file named Ansible.py in
a folder named “local_runway_extensions” (Standard Python import conventions apply). Runway will execute the
deploy function in your class when you perform a runway deploy (AKA takeoff).
deployments:
- modules:
- path: security_group.ansible
class_path: local_runway_extensions.Ansible.DeployToAWS
regions:
- us-east-1
Below is the Ansible.py module referenced above that wraps the ansible-playbook command. It
will be responsible for deploying an EC2 Security Group from the playbook with a naming convention of
<env>-<region>.yaml within a fictional security_group.ansible Runway module folder. In this exam-
ple, the ansible-playbook binary would already have been installed prior to a Runway deploy, but this example
does check to see if it is installed before execution and logs an error if not. The Runway plugin will only execute the
ansible-playbook against a yaml file associated with the environment and set for the Runway execution and region
defined in the runway.yml.
Using the above runway.yml and the plugin/playbook below saved to the Runway module folder you will only
have a deployment occur in the dev environment in us-east-1. If you decide to perform a runway deployment in
the prod environment, or in a different region, the ansible-playbook deployment will be skipped. This matches the
behavior of the Runway’s native modules.
"""Ansible Plugin example for Runway."""
import logging
import subprocess
import sys
import os
from runway.module import RunwayModule
from runway.util import which
LOGGER = logging.getLogger('runway')
def check_for_playbook(playbook_path):
"""Determine if environment/region playbook exists."""
if os.path.isfile(playbook_path):
LOGGER.info("Processing playbook: %s", playbook_path)
(continues on next page)
344 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
(continued from previous page)
return {'skipped_configs': False}
else:
LOGGER.error("No playbook for this environment/region found -- "
"looking for %s", playbook_path)
return {'skipped_configs': True}
class DeployToAWS(RunwayModule):
"""Ansible Runway Module."""
def plan(self):
"""Skip plan"""
LOGGER.info('plan not currently supported for Ansible')
pass
def deploy(self):
"""Run ansible-playbook."""
if not which('ansible-playbook'):
LOGGER.error('"ansible-playbook" not found in path or is not '
'executable; please ensure it is installed'
'correctly.')
sys.exit(1)
playbook_path = (self.path + "-" + self.context.env_name + self.context.env_
˓→region)
response = check_for_playbook(playbook_path)
if response['skipped_configs']:
return response
else:
subprocess.check_output(
['ansible-playbook', playbook_path])
return response
def destroy(self):
"""Skip destroy."""
LOGGER.info('Destroy not currently supported for Ansible')
pass
And below is the example Ansible playbook itself, saved as dev-us-east-1.yaml in the security_group.ansible
folder:
- hosts: localhost
connection: local
gather_facts: false
tasks:
- name: create a security group in us-east-1
ec2_group:
name: dmz
description: Dev example ec2 group
region: us-east-1
rules:
- proto: tcp
from_port: 80
to_port: 80
cidr_ip: 0.0.0.0/0
register: security_group
The above would be deployed if runway deploy was executed in the dev environment to us-east-1.
9.6. Terraform 345
runway Documentation, Release 1.18.3
9.6.8 Getting Started
Before getting started, fork this repo and clone your fork.
Development Environment
This project uses pipenv to create Python virtual environment. This must be installed on your system before setting
up your dev environment.
With pipenv installed, run make sync_all to setup your development environment. This will create all the requred
virtual environments to work on runway, build docs locally, and run integration tests locally. The virtual environments
all have Runway installed as editable meaning as you make changes to the code of your local clone, it will be reflected
in all the virtual environments.
pre-commit
pre-commit is configured for this project to help developers follow the coding style. If you used make sync or make
sync_all to setup your environment, it is already setup for you. If not, you can run pipenv run pre-commit
install to to install the pre-commit hooks.
You can also run pipenv run pre-commit run --all-files at any time to manually trigger these hooks.
9.6.9 GitHub Actions
GitHub Actions are used to manage issues, pull requests, test, releases, and publishing.
Branch Name
Runs on PR open/reopen to check that the incoming branch is using one of the correct prefixes for labels to be applied.
Accepted Prefixes
• bugfix/
• chore/
• docs/
• enhancement/
• feat/
• feature/
• fix/
• hotfix/
• maint/
• maintain/
• maintenance/
• release/
346 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
CI/CD
Based on the execution environment, this workflow will run different steps.
PR Branch
• Lint & test
• build & upload Pyinstaller artifacts
• build & upload python artifacts
Master Branch
• Lint & test
• build & upload Pyinstaller artifacts
• build & upload PyPi & npm artifacts
• publish a development version to Test PyPi and npm
Linting & Tests
Linting and tests are run on Ubuntu and Windows for the following python versions:
• 2.7
• 3.5
• 3.6
• 3.7
All version and OS combinations are run in parallel. If any of them fail, all the other tests will fail immediately.
We are not currently running linting & tests on macOS due to the limited concurrent runner count of macOS runners.
There are also enough similarities between macOS and Ubuntu in regards to the functionality of Runway that it is not
deemed to be a necessity at this time.
Secrets
These are the secrets used by this workflow that have been added to the repo and how to generate them. They can be
added to any any fork to enable similar results but, you will need to change the name of the application for publishing
to succeed.
aws_access_key & aws_secret_key AWS access key ID and secret access key for an IAM user that has the permis-
sions required to publish to AWS S3.
npm_api_token An npm authentication token. For steps on how to create the authentication token, see the Creating
an npm authentication token documentation.
pypi_password A PyPi API token. It is recommended to scope the token to the project contained in the repo. For
steps on how to create the API token, see the Creating a PyPi API token documentation.
test_pypi_password A Test PyPi API token. It is recommended to scope the token to the project contained in the
repo. For steps on how to create the API token, see the Creating a PyPi API token documentation.
9.6. Terraform 347
runway Documentation, Release 1.18.3
Release Management
When a commit is pushed to release (tag is pushed, PR is merged) a release draft is created (if one does not exist) and
PRs since the last tag are added following the included template. Changes are categorized based on PR labels.
Publish Release
When a GitHub Release is published, the final artifacts are created and published to AWS S3, PyPi, & npm.
9.6.10 Building Pyinstaller Packages Locally
We use Pyinstaller to build executables that do not require Python to be installed on a system. These are built by Travis
CI for distribution to ensure a consistent environment but they can also be build locally for testing.
Prerequisites
These need to be installed globally so they are not included in the Pipfile.
• setuptools==45.2.0
• virtualenv==16.7.9
• pipenv==2018.11.26
Process
1. Export OS_NAME environment variable for your system (ubuntu-18.04, macos-10.15, or
windows-latest).
2. Execute make build_pyinstaller_file or make build_pyinstaller_folder from the root
of the repo.
The output of these commands can be found in ./artifacts
9.6.11 Infrastructure
The Runway repository uses some external infrastructure to run tests and server public content. The code that deploys
this infrastructure is located in the infrastructure/ directory. Each subdirectory is a logical separation between
AWS accounts.
Deploying Infrastructure
Infrastructure can be deployed from the root of the infrastructure/ directory for any environment. We make
use of make to simplify the process.
To execute Runway for an environment, use the following command syntax.
$ make <runway-subcommand> <environment>
348 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Example
$ make deploy public
public
AWS account for public facing assets.
Onica SSO Name
onica-public-prod
Resources
• public S3 bucket that houses build artifacts
– binary executables
• IAM user used by GitHub Actions & it’s policies
– able to sync with the artifact bucket
– add entries to a DynamoDB table for the oni.ca URL shortener app
*
path to download the binary executables from S3
testing
Note: Currently exists in the integration_test_infrastructure/ directory as codebuild/.
AWS account for running Runway integration and end-to-end tests.
Onica SSO Name
onica-platform-runway-testing-lab
Resources
TBA
9.6. Terraform 349
runway Documentation, Release 1.18.3
testing-alt
Note: Currently exists in the integration_test_infrastructure/ directory as alt_account_role/.
AWS account for running Runway integration and end-to-end tests that require cross-account access to complete.
Onica SSO Name
onica-platform-runway-testing-alt-lab
Resources
TBA
9.6.12 Labels
Definitions for each label and how they are/should be used.
Proper application of labels is important for the correct, automated actions to be taken. For example, PRs need to be
labeled for release descriptions to be generated correctly.
bug
Something isn’t working.
Issue
Automatically applied to bug reports when they are opened. Can be manually added if the issue is determined to be a
bug report after further investigation.
Should only have one of bug, documentation, feature, maintenance, question, or release.
Pull Request
Should be added manually when the intent is to fix functionality that is not working as expected.
Should only have one of bug, documentation, feature, maintenance, or release.
documentation
Changes to documentation.
350 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Issue
Should be added manually to any requests for improving documentation.
Should only have one of bug, documentation, feature, maintenance, question, or release.
Pull Request
Should be added manually if the only changes are documentation updates. This includes the ReadTheDoc source files
and any README.
Should only have one of bug, documentation, feature, maintenance, or release.
duplicate
This issue or pull request already exists.
Issue
Should be manually added to any issue where the feature request, bug report, question, etc is already covered by an
existing issue, PR, or task. When applying this label, add the appropriate links to the original item then close.
Pull Request
Should be manually added if the feature or bug fix is covered in another PR. Discuss with both parties and determine
the best approach to move forward with, closing the other.
feature
Request, pull request, or task for new functionality or a change to existing functionality.
Issue
Automatically applied to any feature request. Can manually added if the issue is determined to be feature request after
further investigation.
Should only have one of bug, documentation, feature, maintenance, question, or release.
Pull Request
Should be manually added for any new functionality or changes to existing functionality.
Should only have one of bug, documentation, feature, maintenance, or release.
9.6. Terraform 351
runway Documentation, Release 1.18.3
good first issue
Issue or task that would be a good place to start for any new contributors.
Issue
Should be manually added to any issue that can be completed with limited experience with this project.
help wanted
Extra attention is needed.
Issue
Should be manually added if further guidance by a maintainer is required or feedback is needed from a wider audience.
Pull Request
Should be manually added if further guidance by a maintainer is required or feedback is needed from a wider audience.
invalid
This doesn’t seem right.
Issue
Does not pertain to this project or is unintelligible beyond hope.
Pull Request
Does not pertain to this project, is unintelligible beyond hope, or is not a direction the project should go.
maintenance
General upkeep, does not impact the functionally of the application itself.
Issue
Should be manually added if it pertains to changing a dependency version, repo script, GitHub Action, etc.
Should only have one of bug, documentation, feature, maintenance, question, or release.
352 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Pull Request
Should be manually added if it pertains to changing a dependency version, repo script, GitHub Action, etc.
Should only have one of bug, documentation, feature, maintenance, or release.
priority:critical
Critical issue or pull request.
Issue
Should be added manually to any catastrophic bug reports for core functionality that is broken or compromised security.
Should only have one of priority:critical, priority:high, priority:medium or priority:low.
Pull Request
Should be added manually to any catastrophic bugs for core functionality that is broken or compromised security.
Should only have one of priority:critical, priority:high, priority:medium or priority:low.
priority:high
High priority issue or pull request.
Issue
Should be added manually if deemed high priority.
Should only have one of priority:critical, priority:high, priority:medium or priority:low.
Pull Request
Should be added manually if deemed high priority.
Should only have one of priority:critical, priority:high, priority:medium or priority:low.
priority:low
Low priority issue or pull request.
9.6. Terraform 353
runway Documentation, Release 1.18.3
Issue
Automatically added to all new issues when they are opened.
Should only have one of priority:critical, priority:high, priority:medium or priority:low.
Pull Request
Should only have one of priority:critical, priority:high, priority:medium or priority:low.
priority:medium
Medium priority issue or pull request.
Issue
Should be added manually if deemed medium priority.
Should only have one of priority:critical, priority:high, priority:medium or priority:low.
Pull Request
Should be added manually if deemed medium priority.
Should only have one of priority:critical, priority:high, priority:medium or priority:low.
question
Information is needed about how something should be done.
Issue
Automatically added to issues opened as questions. Can be manually added if the issue is determined to be just a
question after further investigation.
Should only have one of bug, documentation, feature, maintenance, question, or release.
Pull Request
Should not be used.
354 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
release
A release task or pull request.
Issue
Should be manually added if the issue is being used to track the release process.
Should only have one of bug, documentation, feature, maintenance, question, or release.
Pull Request
Should be manually added to PR related to a release. Should only be merged if the master branch is the target, never
the release branch. PRs intended to run integration tests with the source set as master and target of release
are acceptable but should never be merged, only closed.
Should only have one of bug, documentation, feature, maintenance, or release.
skip-changelog
Do not include on the release change log.
Issue
Should not be used.
Pull Request
Should be manually added if the PR does not change the application or application documentation to keep the release
changelog clean of any PRs that do not impact the application. Primarily only used for changes to GitHub Actions,
scripts, or repository management.
status:abandoned
Issue or pull request was abandoned by the author.
Issue
Should be manually added if a request for more information was made but not provided for >=2 weeks. After applying
this label and a short comment, the issue should be closed.
9.6. Terraform 355
runway Documentation, Release 1.18.3
Pull Request
Should be manually added if a request for more information or changes was made but not provided for >=2 weeks. If
the PR is not worth assigning someone else to finish, a short comment should be left and the PR closed.
status:accepted
Issue or pull request was accepted by a maintainer.
Issue
Should be manually added if the issue is something that a maintainer would like to pursue.
If an issue was not created by a maintainer and does not have this label, it should not be worked on as there is a high
chance any associated PRs will be denied.
Pull Request
Should be manually added if a PR was not created by a maintainer, is not associated with an issue, but is something a
maintainer would like to pursue.
status:available
Task available for assignment.
Issue
Should be manually added to an issue after it has been accepted and open for assignment to anyone who would like to
contribute. Once assigned to someone, it should be removed.
Pull Request
Should be manually added to a PR that was abandoned by the author and should be finished. Once assigned to
someone, it should be removed.
status:blocked
Issue or pull request is blocked by something.
Issue
Should be manually added if the issue requires another issue, PR, etc to be complete before it can be started or
completed. Once unblocked, it should be removed.
356 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Pull Request
Should be manually added if the PR requires another issue, PR, etc to be complete before it can be merged. Once
unblocked, it should be removed.
status:completed
Task is complete.
Issue
TBD
Pull Request
TBD
status:in_progress
Task is actively being worked on.
Issue
Should be manually added if the issue is accepted, assigned, and is actively being worked on. Should not be used if
the issue is status:blocked or status:on_hold.
Pull Request
Should be manually added if the PR is accepted, assigned, and is actively being worked on. Should not be used if the
PR is status:blocked or status:on_hold.
status:on_hold
Task was recently worked on but is now on hold.
Issue
Should be manually added if the issue is accepted and assigned but is not actively being worked on and is not blocked.
Should be removed once work has continued. Primarily used when switching tasks to something of higher priority.
9.6. Terraform 357
runway Documentation, Release 1.18.3
Pull Request
Should be manually added if the PR is accepted and assigned but is not actively being worked on and is not blocked.
Should be removed once work has continued. Primarily used when switching tasks to something of higher priority.
status:pending
Task is pending review or something else.
Issue
TBD
Pull Request
TBD
status:review_needed
Issue or pull request needs to be reviewed by a maintainer.
Issue
Automatically applied to issues when they are opened. Should be manually added when a maintainer needs to re-
review. Should be removed after the issue has been accepted or rejected.
Pull Request
Should be manually added when a maintainer needs to review or re-review for acceptance. Should be removed after
the issue has been accepted or rejected.
status:revision_needed
Issue or pull request needs to be revised by the author.
Issue
Should be manually added when the issue if it needs to be revised by the author to add more information, examples,
etc. Should be removed once the issue is fixed.
358 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Pull Request
Should be manually added when the PR needs to be revised by the author to add more information, examples, etc, or
it does not meet requirements. Should be removed once the PR is fixed.
wontfix
This will not be worked on.
Issue
Should be manually added when the issue has been rejected by a maintainer.
Pull Request
Should be manually added when the PR has been rejected by a maintainer.
9.6.13 Release Process
Steps that should be taken when preparing for and executing a release.
Preparation
1. Merge all PRs that should be included in the release.
2. Open a draft PR. This should have master as the source and release as the target. The PR should be labeled as
release.
3. Integration tests should be triggered automatically by opening the PR. Wait for the tests to complete before
continuing.
Important: Only one instance of each test should be run at a time. Either cancel any running test or wait for them to
finish before committing/merging anything new to master which will trigger a new instance of each test to begin.
4. Fix any failing integration tests.
5. Close the PR.
6. Fetch updates for all branches of the onicagroup/runway remote. (e.g. git fetch --all)
7. Checkout the master branch from the onicagroup/runway remote. This is to ensure your local master branch
matches the correct remote. (e.g. git checkout -b master --track <remote>/master)
8. Apply a version bump where necessary (CHANGELOG.md, etc)
9. Commit any changes to master.
10. Push the commits to the onicagroup/runway remote. (e.g. git push <remote> master)
9.6. Terraform 359
runway Documentation, Release 1.18.3
Execution
1. Fetch updates for all branches of the onicagroup/runway remote. (e.g. git fetch --all)
2. Checkout the master branch from the onicagroup/runway remote. This is to ensure your local master branch
matches the correct remote. (e.g. git checkout -b master --track <remote>/master)
3. Checkout the release branch from the onicagroup/runway remote. (e.g. git checkout -b release
--track <remote>/release)
4. Execute git merge --ff-only master to fast forward the branch.
5. Push the changes to the onicagroup/runway remote. (e.g. git push <remote> release)
6. Create a tag on the release branch for the new version. This can be done one of two ways:
• Navigate to the Releases section of the repository on GitHub. The should be a Draft Release already started
that was automatically generated from PRs that were merged since the last release. Editing the draft will give
provide the option to create a new tag for the release.
• Create a signed tag on the release branch for the new version and push it to the onicagroup/runway remote
git tag --sign v0.0.0
git push <remote> v0.0.0
7. Navigate to the Releases section of the repository on GitHub and edit the Draft Release if you have not done so
already.
8. Rename the release to match the version tag and associate it with the tag that was just created.
9. Edit the description of the release as needed but, there should be little to no changes required if all PRs were
properly labeled.
10. Mark the release as a pre-release if applicable (alpha, beta, release candidate, etc).
11. Publish the release on GitHub.
At this point, GitHub Action will begin building the deployment packages & automatically publishing them to npm,
PyPi, and AWS S3. The Publish Release workflow can be monitored for progress.
After all the publishing steps have completed:
12. Download the following artifacts from the Publish Release workflow:
• npm-pack
• pyinstaller-onefile-macos-10.15
• pyinstaller-onefile-ubuntu-18.04
• pyinstaller-onefile-windows-latest
• pypi-dist
13. Attach all artifacts to the release that were previously downloaded.
360 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
9.6.14 Apache License
Version 2.0
Date January 2004
URL http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
“License” shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through
9 of this document.
“Licensor” shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
“Legal Entity” shall mean the union of the acting entity and all other entities that control, are controlled by, or are
under common control with that entity. For the purposes of this definition, “control” means (i) the power, direct or
indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of
fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
“You” (or “Your”) shall mean an individual or Legal Entity exercising permissions granted by this License.
“Source” form shall mean the preferred form for making modifications, including but not limited to software source
code, documentation source, and configuration files.
“Object” form shall mean any form resulting from mechanical transformation or translation of a Source form, includ-
ing but not limited to compiled object code, generated documentation, and conversions to other media types.
“Work” shall mean the work of authorship, whether in Source or Object form, made available under the License, as
indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix
below).
“Derivative Works” shall mean any work, whether in Source or Object form, that is based on (or derived from) the
Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an
original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
“Contribution” shall mean any work of authorship, including the original version of the Work and any modifications
or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the
Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner.
For the purposes of this definition, “submitted” means any form of electronic, verbal, or written communication sent to
the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code
control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of dis-
cussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated
in writing by the copyright owner as “Not a Contribution.”
“Contributor” shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been
received by Licensor and subsequently incorporated within the Work.
9.6. Terraform 361
runway Documentation, Release 1.18.3
2. Grant of Copyright License.
Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-
exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly
display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
3. Grant of Patent License.
Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide,
non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims
licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their
Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against
any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated
within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under
this License for that Work shall terminate as of the date such litigation is filed.
4. Redistribution.
You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You meet the following conditions:
• You must give any other recipients of the Work or Derivative Works a copy of this License; and
• You must cause any modified files to carry prominent notices stating that You changed the files; and
• You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark,
and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part
of the Derivative Works; and
• If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You
distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding
those notices that do not pertain to any part of the Derivative Works, in at least one of the following places:
within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation,
if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents of the NOTICE file are for informational
purposes only and do not modify the License. You may add Your own attribution notices within Derivative
Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such
additional attribution notices cannot be construed as modifying the License. You may add Your own copyright
statement to Your modifications and may provide additional or different license terms and conditions for use,
reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your
use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
5. Submission of Contributions.
Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to
the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you
may have executed with Licensor regarding such Contributions.
362 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
6. Trademarks.
This License does not grant permission to use the trade names, trademarks, service marks, or product names of the
Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing
the content of the NOTICE file.
7. Disclaimer of Warranty.
Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides
its Contributions) on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT,
MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for deter-
mining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of
permissions under this License.
8. Limitation of Liability.
In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by
applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to
You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising
as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of
goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even
if such Contributor has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability.
While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance
of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in
accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any
other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional
liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work
To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets
“[]” replaced with your own identifying information. (Don’t include the brackets!) The text should be enclosed in
the appropriate comment syntax for the file format. We also recommend that a file or class name and description of
purpose be included on the same “printed page” as the copyright notice for easier identification within third-party
archives.
Copyright 2018 Onica Group LLC
Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in
compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is dis-
tributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
9.6. Terraform 363
runway Documentation, Release 1.18.3
express or implied. See the License for the specific language governing permissions and limitations under
the License.
9.6.15 Terminology
Runway
Deploy Environment
Deploy environments are used for selecting the options/variables/parameters to be used with each Module. The deploy
environment is derived from the current directory (if its not a git repo), active git branch, or environment variable
(DEPLOY_ENVIRONMENT). Standard deploy environments would be something like prod, dev, and test.
When using a git branch, Runway expects the branch to be prefixed with ENV-. If this is found, Runway knows that it
should always use the value that follows the prefix. If it’s the master branch, Runway will use the deploy environment
name of common. If the branch name does not follow either of these schemas and Runway is being run interactively
from the CLI, it will prompt of confirmation of the deploy environment that should be used.
When using a directory, Runway expects the directory’s name to be prefixed with ENV-. If this is found, Runway
knows that it should always use the value that follows the prefix.
Deployment
A deployment contains a list of modules and options for all the modules in the deployment. A Runway config file can
contain multiple deployments and a deployment can contain multiple modules.
Lookup (Runway)
A method for expanding values in the Runway Config File file when processing a deployment/module. These are only
supported in select areas of the Runway Config File (see the config docs for more details).
Module
A module is a directory containing a single infrastructure-as-code tool configuration of an application, a component,
or some infrastructure (eg. a set of CloudFormation templates). It is defined in a deployment by path. Modules can
also contain granular options that only pertain to it based on its module type.
Parameters
A mapping of key: value that is passed to a module. Through the use of a Lookup (Runway), the value can be
changed per region or deploy environment. The value can be any data type but, support for complex data types
depends on the module type.
364 Chapter 9. Module Configuration
runway Documentation, Release 1.18.3
Runway’s CFngin
Blueprint
A python class that is responsible for creating a CloudFormation template. Usually this is built using troposphere.
config
A YAML config file that defines the stack definitions for all of the stacks you want CFNgin to manage.
context
Context is responsible for translating the values passed in via the command line and specified in the config to stacks.
environment
A set of variables that can be used inside the config, allowing you to slightly adjust configs based on which environment
you are launching.
graph
A mapping of object name to set/list of dependencies.
A graph is constructed for each execution of CFNgin from the contents of the config file.
Example
{
"stack1": [],
"stack2": [
"stack1"
]
}
• stack1 depends on nothing.
• stack2 depends on stack1
hook
These are python functions/methods that are executed before or after the action is taken.
9.6. Terraform 365
runway Documentation, Release 1.18.3
lookup
A method for expanding values in the config at build time. By default lookups are used to reference Output values
from other stacks within the same namespace.
namespace
A way to uniquely identify a stack. Used to determine the naming of many things, such as the S3 bucket where
compiled templates are stored, as well as the prefix for stack names.
output
A CloudFormation Template concept. Stacks can output values, allowing easy access to those values. Often used to
export the unique ID’s of resources that templates create. CFNgin makes it simple to pull outputs from one stack and
then use them as a variable in another stack.
persistent graph
A graph that is persisted between CFNgin executions. It is stored in in the Stack S3 bucket.
provider
Provider that supports provisioning rendered blueprints. By default, an AWS provider is used.
stack
The resulting stack of resources that is created by CloudFormation when it executes a template. Each stack managed
by CFNgin is defined by a stack definition in the config.
stack definition
Defines the stack you want to build, usually there are multiple of these in the config. It also defines the variables to be
used when building the stack.
variable
Dynamic variables that are passed into stacks when they are being built. Variables are defined within the config.
366 Chapter 9. Module Configuration
CHAPTER
TEN
INDICES AND TABLES
• genindex
• modindex
• search
367
runway Documentation, Release 1.18.3
368 Chapter 10. Indices and tables
PYTHON MODULE INDEX
r
runway, 158
runway.aws_sso_botocore, 186
runway.aws_sso_botocore.credentials, 186
runway.aws_sso_botocore.exceptions, 187
runway.aws_sso_botocore.session, 188
runway.aws_sso_botocore.util, 188
runway.blueprints, 188
runway.blueprints.k8s, 189
runway.blueprints.k8s.k8s_iam, 189
runway.blueprints.k8s.k8s_master, 189
runway.blueprints.k8s.k8s_workers, 190
runway.blueprints.staticsite, 190
runway.blueprints.staticsite.auth_at_edge,
191
runway.blueprints.staticsite.dependencies,
192
runway.blueprints.staticsite.staticsite,
193
runway.blueprints.tf_state, 188
runway.cfngin, 195
runway.cfngin.actions, 228
runway.cfngin.actions.base, 228
runway.cfngin.actions.build, 231
runway.cfngin.actions.destroy, 232
runway.cfngin.actions.diff, 233
runway.cfngin.actions.graph, 235
runway.cfngin.actions.info, 236
runway.cfngin.awscli_yamlhelper, 197
runway.cfngin.blueprints, 236
runway.cfngin.blueprints.base, 236
runway.cfngin.blueprints.raw, 241
runway.cfngin.blueprints.testutil, 243
runway.cfngin.blueprints.variables, 244
runway.cfngin.blueprints.variables.types,
244
runway.cfngin.cfngin, 197
runway.cfngin.config, 245
runway.cfngin.config.translators, 255
runway.cfngin.config.translators.kms,
255
runway.cfngin.context, 200
runway.cfngin.dag, 255
runway.cfngin.environment, 202
runway.cfngin.exceptions, 203
runway.cfngin.hooks, 258
runway.cfngin.hooks.acm, 258
runway.cfngin.hooks.aws_lambda, 260
runway.cfngin.hooks.base, 264
runway.cfngin.hooks.command, 267
runway.cfngin.hooks.docker, 271
runway.cfngin.hooks.docker.data_models,
272
runway.cfngin.hooks.docker.hook_data,
273
runway.cfngin.hooks.docker.image, 274
runway.cfngin.hooks.ecr, 274
runway.cfngin.hooks.ecs, 268
runway.cfngin.hooks.iam, 268
runway.cfngin.hooks.keypair, 269
runway.cfngin.hooks.route53, 270
runway.cfngin.hooks.utils, 271
runway.cfngin.logger, 274
runway.cfngin.lookups, 275
runway.cfngin.lookups.handlers, 276
runway.cfngin.lookups.handlers.ami, 276
runway.cfngin.lookups.handlers.default,
277
runway.cfngin.lookups.handlers.dynamodb,
277
runway.cfngin.lookups.handlers.envvar,
278
runway.cfngin.lookups.handlers.file, 278
runway.cfngin.lookups.handlers.hook_data,
281
runway.cfngin.lookups.handlers.kms, 281
runway.cfngin.lookups.handlers.output,
282
runway.cfngin.lookups.handlers.rxref,
283
runway.cfngin.lookups.handlers.split,
284
runway.cfngin.lookups.handlers.ssmstore,
285
369
runway Documentation, Release 1.18.3
runway.cfngin.lookups.handlers.xref, 286
runway.cfngin.lookups.registry, 275
runway.cfngin.plan, 209
runway.cfngin.providers, 286
runway.cfngin.providers.aws, 287
runway.cfngin.providers.aws.default, 287
runway.cfngin.providers.base, 286
runway.cfngin.session_cache, 216
runway.cfngin.stack, 216
runway.cfngin.status, 219
runway.cfngin.target, 221
runway.cfngin.tokenize_userdata, 221
runway.cfngin.ui, 222
runway.cfngin.util, 223
runway.config, 158
runway.context, 170
runway.core, 296
runway.core.components, 297
runway.core.providers, 302
runway.core.providers.aws, 302
runway.core.providers.aws.s3, 304
runway.env_mgr, 306
runway.env_mgr.kbenv, 307
runway.env_mgr.tfenv, 307
runway.hooks, 308
runway.hooks.cleanup_s3, 309
runway.hooks.cleanup_ssm, 309
runway.hooks.staticsite, 309
runway.hooks.staticsite.auth_at_edge,
313
runway.hooks.staticsite.auth_at_edge.callback_url_retriever,
313
runway.hooks.staticsite.auth_at_edge.client_updater,
313
runway.hooks.staticsite.auth_at_edge.domain_updater,
314
runway.hooks.staticsite.auth_at_edge.lambda_config,
315
runway.hooks.staticsite.auth_at_edge.user_pool_id_retriever,
316
runway.hooks.staticsite.build_staticsite,
309
runway.hooks.staticsite.cleanup, 309
runway.hooks.staticsite.upload_staticsite,
310
runway.hooks.staticsite.util, 312
runway.http_backport, 171
runway.lookups, 316
runway.lookups.handlers, 317
runway.lookups.handlers.base, 59
runway.lookups.handlers.cfn, 61
runway.lookups.handlers.ecr, 321
runway.lookups.handlers.env, 63
runway.lookups.handlers.ssm, 63
runway.lookups.handlers.var, 64
runway.lookups.registry, 316
runway.module, 325
runway.module.cdk, 326
runway.module.cloudformation, 327
runway.module.k8s, 327
runway.module.serverless, 328
runway.module.staticsite, 331
runway.module.terraform, 331
runway.path, 174
runway.path.Path, 51
runway.runway_module_type, 176
runway.runway_module_type.RunwayModuleType,
53
runway.s3_util, 177
runway.sources, 336
runway.sources.git, 337
runway.sources.source, 337
runway.tests, 338
runway.tests.handlers, 338
runway.tests.handlers.base, 338
runway.tests.handlers.cfn_lint, 339
runway.tests.handlers.script, 339
runway.tests.handlers.yaml_lint, 339
runway.tests.registry, 338
runway.util, 178
runway.variables, 182
370 Python Module Index
INDEX
A
ACCEPTED (runway.http_backport.HTTPStatus at-
tribute), 172
accepted_names (runway.config.Config attribute),
170
account_alias() (run-
way.config.DeploymentDefinition property),
166
account_alias_config() (run-
way.core.components.Deployment property),
299
account_id() (runway.config.DeploymentDefinition
property), 166
account_id_config() (run-
way.core.components.Deployment property),
299
AccountDetails (class in run-
way.core.providers.aws), 302
acm_certificate_specified() (run-
way.blueprints.staticsite.staticsite.StaticSite
property), 193
acquire() (runway.cfngin.dag.UnlimitedSemaphore
method), 258
Action (class in runway.cfngin.actions.build), 231
Action (class in runway.cfngin.actions.destroy), 232
Action (class in runway.cfngin.actions.diff ), 234
Action (class in runway.cfngin.actions.graph), 235
Action (class in runway.cfngin.actions.info), 236
add_acm_cert() (run-
way.blueprints.staticsite.staticsite.StaticSite
method), 194
add_aliases() (run-
way.blueprints.staticsite.staticsite.StaticSite
method), 194
add_bucket() (run-
way.blueprints.staticsite.staticsite.StaticSite
method), 194
add_bucket_policy() (run-
way.blueprints.staticsite.staticsite.StaticSite
method), 194
add_cloudfront_bucket_policy() (run-
way.blueprints.staticsite.staticsite.StaticSite
method), 194
add_cloudfront_directory_index_rewrite()
(runway.blueprints.staticsite.staticsite.StaticSite
method), 194
add_cloudfront_directory_index_rewrite_version()
(runway.blueprints.staticsite.staticsite.StaticSite
method), 194
add_cloudfront_distribution() (run-
way.blueprints.staticsite.staticsite.StaticSite
method), 195
add_edge() (runway.cfngin.dag.DAG method), 255
add_lambda_execution_role() (run-
way.blueprints.staticsite.staticsite.StaticSite
method), 194
add_logging_bucket() (run-
way.blueprints.staticsite.staticsite.StaticSite
method), 194
add_node() (runway.cfngin.dag.DAG method), 255
add_node_if_not_exists() (run-
way.cfngin.dag.DAG method), 256
add_origin_access_identity() (run-
way.blueprints.staticsite.staticsite.StaticSite
method), 194
add_output() (run-
way.cfngin.blueprints.base.Blueprint method),
240
add_step() (runway.cfngin.plan.Graph method), 212
add_step_if_not_exists() (run-
way.cfngin.plan.Graph method), 213
add_steps() (runway.cfngin.plan.Graph method),
213
add_url_scheme() (in module run-
way.module.staticsite), 331
add_version() (run-
way.blueprints.staticsite.auth_at_edge.AuthAtEdge
method), 191
add_web_acl() (run-
way.blueprints.staticsite.staticsite.StaticSite
method), 194
ADDED (runway.cfngin.actions.diff.DictValue attribute),
233
aliases (runway.core.providers.aws.AccountDetails
371
runway Documentation, Release 1.18.3
attribute), 302
aliases_specified() (run-
way.blueprints.staticsite.staticsite.StaticSite
property), 193
all_downstreams() (runway.cfngin.dag.DAG
method), 256
all_leaves() (runway.cfngin.dag.DAG method), 256
all_parameter_definitions() (run-
way.cfngin.stack.Stack property), 218
ALREADY_REPORTED (run-
way.http_backport.HTTPStatus attribute),
172
AmiLookup (class in run-
way.cfngin.lookups.handlers.ami), 276
AnyType (class in runway.cfngin.config), 245
args (runway.cfngin.config.Hook attribute), 249, 250
args (runway.cfngin.hooks.base.Hook attribute), 264
args() (runway.config.TestDefinition property), 167
args() (runway.module.serverless.ServerlessOptions
property), 330
argv() (in module runway.util), 180
ask() (runway.cfngin.ui.UI method), 222
ask_for_approval() (in module run-
way.cfngin.providers.aws.default), 288
assertRenderedBlueprint() (run-
way.cfngin.blueprints.testutil.BlueprintTestCase
method), 243
assume() (runway.core.providers.aws.AssumeRole
method), 302
assume_role() (run-
way.config.DeploymentDefinition property),
166
assume_role_config() (run-
way.core.components.Deployment property),
299
AssumeRole (class in runway.core.providers.aws), 302
AUTH_VARIABLES (run-
way.blueprints.staticsite.auth_at_edge.AuthAtEdge
attribute), 191
AuthAtEdge (class in run-
way.blueprints.staticsite.auth_at_edge), 191
auto_detect_content_type() (in module run-
way.hooks.staticsite.upload_staticsite), 311
auto_tfvars (runway.module.terraform.Terraform at-
tribute), 332
aws_credentials() (run-
way.core.components.DeployEnvironment
property), 297
aws_profile() (run-
way.core.components.DeployEnvironment
property), 297
aws_region() (run-
way.core.components.DeployEnvironment
property), 297
B
backend (runway.env_mgr.tfenv.TFEnvManager at-
tribute), 308
BAD_GATEWAY (runway.http_backport.HTTPStatus at-
tribute), 173
BAD_REQUEST (runway.http_backport.HTTPStatus at-
tribute), 172
base_class() (run-
way.cfngin.blueprints.testutil.YamlDirTestGenerator
property), 243
BaseAction (class in runway.cfngin.actions.base), 229
BaseModel (class in run-
way.cfngin.hooks.docker.data_models), 272
BaseProvider (class in run-
way.cfngin.providers.base), 286
BaseProviderBuilder (class in run-
way.cfngin.providers.base), 286
BaseResponse (class in runway.core.providers.aws),
303
bin (runway.env_mgr.EnvManager attribute), 306
bin() (runway.env_mgr.EnvManager property), 306
BlankBlueprint (class in runway.cfngin.hooks.utils),
271
Blueprint (class in runway.cfngin.blueprints.base),
238
blueprint (runway.cfngin.hooks.base.Hook attribute),
265
blueprint() (runway.cfngin.stack.Stack property),
218
BlueprintTestCase (class in run-
way.cfngin.blueprints.testutil), 243
boto3_credentials() (runway.context.Context
property), 170
branch (runway.cfngin.config.GitPackageSource
attribute), 249
branch_name (runway.core.components.DeployEnvironment
attribute), 297
Bucket (class in runway.core.providers.aws.s3), 304
bucket (runway.cfngin.config.S3PackageSource at-
tribute), 251
bucket_name (runway.cfngin.actions.base.BaseAction
attribute), 229
bucket_name() (runway.cfngin.context.Context prop-
erty), 200
bucket_region (run-
way.cfngin.actions.base.BaseAction attribute),
229
build() (in module run-
way.cfngin.hooks.docker.image), 274
build() (in module run-
way.hooks.staticsite.build_staticsite), 309
build() (runway.cfngin.providers.aws.default.ProviderBuilder
method), 291
build() (runway.cfngin.providers.base.BaseProviderBuilder
372 Index
runway Documentation, Release 1.18.3
method), 286
build_parameter() (in module run-
way.cfngin.blueprints.base), 236
build_parameters() (run-
way.cfngin.actions.build.Action static method),
232
build_provider() (run-
way.cfngin.actions.base.BaseAction method),
230
build_provider() (run-
way.cfngin.hooks.base.HookBuildAction
method), 266
build_stack_tags() (in module run-
way.cfngin.actions.build), 231
build_walker() (in module run-
way.cfngin.actions.base), 228
C
cached_property (class in runway.util), 178
calculate_hash_of_extra_files() (in mod-
ule runway.hooks.staticsite.upload_staticsite),
311
calculate_hash_of_files() (in module run-
way.hooks.staticsite.util), 312
camel_to_snake() (in module runway.cfngin.util),
223
cancel (runway.cfngin.actions.base.BaseAction at-
tribute), 229
CancelExecution, 203
Certificate (class in runway.cfngin.hooks.acm), 258
cf_enabled() (run-
way.blueprints.staticsite.staticsite.StaticSite
property), 193
cf_logging_enabled() (run-
way.blueprints.staticsite.staticsite.StaticSite
property), 193
cf_safe_name() (in module runway.cfngin.util), 224
cf_tokenize() (in module run-
way.cfngin.tokenize_userdata), 221
CFNgin (class in runway.cfngin), 195
CFNgin (class in runway.cfngin.cfngin), 197
cfngin_bucket (runway.cfngin.config.Config at-
tribute), 245, 247
cfngin_bucket_region (run-
way.cfngin.config.Config attribute), 246,
247
cfngin_cache_dir (runway.cfngin.config.Config at-
tribute), 246, 247
CfnLintHandler (class in run-
way.tests.handlers.cfn_lint), 339
CfnLookup (class in runway.lookups.handlers.cfn), 320
CFNParameter (class in run-
way.cfngin.blueprints.base), 236
CFNType (class in run-
way.cfngin.blueprints.variables.types), 245
change_dir() (in module runway.util), 180
changes() (runway.cfngin.actions.diff.DictValue
method), 233
ChangesetDidNotStabilize, 203
check_for_npm() (run-
way.module.RunwayModuleNpm method),
325
check_tags_contain() (in module run-
way.cfngin.providers.aws.default), 289
child_modules (runway.core.components.Module at-
tribute), 300
ci() (runway.core.components.DeployEnvironment
property), 297
class_path (runway.cfngin.config.Stack attribute),
252, 253
class_path() (runway.config.ModuleDefinition
property), 162
cleanup_dot_terraform() (run-
way.module.terraform.Terraform method),
332
clear_found_cache() (runway.util.MutableMap
method), 179
cli() (in module runway.core.providers.aws), 304
cli_args() (runway.module.serverless.Serverless
property), 329
client (runway.cfngin.hooks.docker.hook_data.DockerHookData
attribute), 274
client (runway.core.providers.aws.s3.Bucket at-
tribute), 304
CloudDevelopmentKit (class in run-
way.module.cdk), 326
CloudFormation (class in run-
way.module.cloudformation), 327
Cluster (class in runway.blueprints.k8s.k8s_master),
189
code (runway.cfngin.status.Status attribute), 219
code (runway.core.providers.aws.ResponseError at-
tribute), 303
ColorFormatter (class in runway.cfngin.logger), 274
command_suffix (runway.env_mgr.EnvManager at-
tribute), 306
commit (runway.cfngin.config.GitPackageSource
attribute), 249
complete() (runway.cfngin.plan.Step method), 211
COMPLETE_STATUSES (run-
way.cfngin.providers.aws.default.Provider
attribute), 291
completed() (runway.cfngin.plan.Step property), 211
CompleteStatus (class in runway.cfngin.status), 219
concurrency (runway.cfngin.CFNgin attribute), 195
concurrency (runway.cfngin.cfngin.CFNgin at-
tribute), 198
Index 373
runway Documentation, Release 1.18.3
Config (class in runway.cfngin.config), 245
Config (class in runway.config), 43, 168
ConfigComponent (class in runway.config), 158
configs (runway.cfngin.config.GitPackageSource at-
tribute), 249
configs (runway.cfngin.config.LocalPackageSource
attribute), 250
configs (runway.cfngin.config.S3PackageSource at-
tribute), 251
configuration() (runway.path.Path property), 176
CONFLICT (runway.http_backport.HTTPStatus at-
tribute), 173
connect() (runway.cfngin.plan.Graph method), 213
construct_yaml_str() (run-
way.cfngin.lookups.handlers.file.SafeUnicodeLoader
method), 281
Context (class in runway.cfngin.context), 200
Context (class in runway.context), 170
context (runway.cfngin.actions.base.BaseAction at-
tribute), 229
context (runway.cfngin.hooks.base.Hook attribute),
265
context (runway.cfngin.plan.Plan attribute), 214
CONTINUE (runway.http_backport.HTTPStatus at-
tribute), 172
convert_class_name() (in module run-
way.cfngin.util), 223
copy() (runway.context.Context method), 171
copy() (runway.core.components.DeployEnvironment
method), 297
copydir() (in module run-
way.cfngin.hooks.aws_lambda), 260
create() (runway.cfngin.blueprints.variables.types.TroposphereType
method), 244
create() (runway.core.providers.aws.s3.Bucket
method), 305
create_cache_directories() (run-
way.cfngin.util.SourceProcessor method),
227
create_change_set() (in module run-
way.cfngin.providers.aws.default), 289
create_clusters() (in module run-
way.cfngin.hooks.ecs), 268
create_credential_resolver() (in module
runway.aws_sso_botocore.credentials), 186
create_domain() (in module run-
way.cfngin.hooks.route53), 270
create_ecs_service_role() (in module run-
way.cfngin.hooks.iam), 268
create_key_pair() (in module run-
way.cfngin.hooks.keypair), 269
create_key_pair_from_public_key_file()
(in module runway.cfngin.hooks.keypair), 269
create_key_pair_in_ssm() (in module run-
way.cfngin.hooks.keypair), 269
create_key_pair_local() (in module run-
way.cfngin.hooks.keypair), 269
create_route53_zone() (in module run-
way.cfngin.util), 224
create_stack() (run-
way.cfngin.providers.aws.default.Provider
method), 292
create_stack() (run-
way.cfngin.providers.base.BaseProvider
method), 287
create_template() (run-
way.blueprints.k8s.k8s_iam.Iam method),
189
create_template() (run-
way.blueprints.k8s.k8s_master.Cluster
method), 190
create_template() (run-
way.blueprints.k8s.k8s_workers.NodeGroup
method), 190
create_template() (run-
way.blueprints.staticsite.auth_at_edge.AuthAtEdge
method), 191
create_template() (run-
way.blueprints.staticsite.dependencies.Dependencies
method), 192
create_template() (run-
way.blueprints.staticsite.staticsite.StaticSite
method), 193
create_template() (run-
way.blueprints.tf_state.TfState method),
189
create_template() (run-
way.cfngin.blueprints.base.Blueprint method),
240
create_template() (run-
way.cfngin.hooks.utils.BlankBlueprint method),
271
CREATED (runway.http_backport.HTTPStatus attribute),
172
current_aws_creds() (runway.context.Context
property), 170
current_version (runway.env_mgr.EnvManager at-
tribute), 306
current_workspace (run-
way.module.terraform.Terraform attribute),
332
D
DAG (class in runway.cfngin.dag), 255
dag (runway.cfngin.plan.Graph attribute), 212
DAGValidationError, 258
data() (runway.config.ConfigComponent property),
159
374 Index
runway Documentation, Release 1.18.3
data() (runway.util.MutableMap property), 179
data_key (runway.cfngin.config.Hook attribute), 249,
250
deal_with_changeset_stack_policy() (run-
way.cfngin.providers.aws.default.Provider
method), 294
debug() (runway.core.components.DeployEnvironment
property), 297
deconstruct() (in module run-
way.cfngin.lookups.handlers.output), 283
default() (runway.util.JsonEncoder method), 178
default_names (runway.config.VariablesDefinition
attribute), 168
default_update_stack() (run-
way.cfngin.providers.aws.default.Provider
method), 295
DefaultLookup (class in run-
way.cfngin.lookups.handlers.default), 277
defined_variables() (run-
way.cfngin.blueprints.base.Blueprint method),
239
definition (runway.cfngin.stack.Stack attribute), 216
delete() (in module run-
way.hooks.staticsite.auth_at_edge.domain_updater),
314
delete_bucket() (in module runway.s3_util), 177
delete_edge() (runway.cfngin.dag.DAG method),
256
delete_node() (runway.cfngin.dag.DAG method),
256
delete_node_if_exists() (run-
way.cfngin.dag.DAG method), 256
delete_param() (in module run-
way.hooks.cleanup_ssm), 309
DELETED_STATUS (run-
way.cfngin.providers.aws.default.Provider
attribute), 291
DELETING_STATUS (run-
way.cfngin.providers.aws.default.Provider
attribute), 291
Dependencies (class in run-
way.blueprints.staticsite.dependencies), 192
dependencies() (run-
way.cfngin.lookups.handlers.output.OutputLookup
class method), 283
dependencies() (run-
way.lookups.handlers.base.LookupHandler
class method), 318
dependencies() (runway.variables.Variable prop-
erty), 182
dependencies() (runway.variables.VariableValue
property), 183
dependencies() (run-
way.variables.VariableValueConcatenation
property), 185
dependencies() (run-
way.variables.VariableValueDict property),
184
dependencies() (run-
way.variables.VariableValueList property),
184
dependencies() (run-
way.variables.VariableValueLookup property),
185
deploy() (runway.cfngin.CFNgin method), 196
deploy() (runway.cfngin.cfngin.CFNgin method), 198
deploy() (runway.cfngin.hooks.acm.Certificate
method), 260
deploy() (runway.core.components.Deployment
method), 299
deploy() (runway.core.components.Module method),
300
deploy() (runway.core.Runway method), 296
deploy() (runway.module.cdk.CloudDevelopmentKit
method), 327
deploy() (runway.module.cloudformation.CloudFormation
method), 327
deploy() (runway.module.k8s.K8s method), 328
deploy() (runway.module.RunwayModule method),
325
deploy() (runway.module.serverless.Serverless
method), 330
deploy() (runway.module.staticsite.StaticSite
method), 331
deploy() (runway.module.terraform.Terraform
method), 333
deploy_package() (in module run-
way.module.serverless), 328
deploy_stack() (runway.cfngin.hooks.base.Hook
method), 265
DeployEnvironment (class in run-
way.core.components), 297
Deployment (class in runway.core.components), 298
DeploymentDefinition (class in runway.config),
44, 163
DEPRECATION_MSG (run-
way.cfngin.lookups.handlers.hook_data.HookDataLookup
attribute), 281
DEPRECATION_MSG (run-
way.cfngin.lookups.handlers.ssmstore.SsmstoreLookup
attribute), 285
DEPRECATION_MSG (run-
way.cfngin.lookups.handlers.xref.XrefLookup
attribute), 286
DESCRIPTION (runway.cfngin.actions.base.BaseAction
attribute), 229, 230
DESCRIPTION (runway.cfngin.actions.build.Action at-
tribute), 232
Index 375
runway Documentation, Release 1.18.3
DESCRIPTION (runway.cfngin.actions.destroy.Action
attribute), 233
DESCRIPTION (runway.cfngin.actions.diff.Action at-
tribute), 234
DESCRIPTION (runway.cfngin.actions.graph.Action at-
tribute), 235
description (runway.cfngin.config.Stack attribute),
252, 253
description (runway.cfngin.plan.Plan attribute), 214
destroy() (runway.cfngin.CFNgin method), 196
destroy() (runway.cfngin.cfngin.CFNgin method),
199
destroy() (runway.cfngin.hooks.acm.Certificate
method), 260
destroy() (runway.core.components.Deployment
method), 299
destroy() (runway.core.components.Module method),
300
destroy() (runway.core.Runway method), 296
destroy() (runway.module.cdk.CloudDevelopmentKit
method), 327
destroy() (runway.module.cloudformation.CloudFormation
method), 327
destroy() (runway.module.k8s.K8s method), 328
destroy() (runway.module.RunwayModule method),
325
destroy() (runway.module.serverless.Serverless
method), 330
destroy() (runway.module.staticsite.StaticSite
method), 331
destroy() (runway.module.terraform.Terraform
method), 333
destroy_stack() (runway.cfngin.hooks.base.Hook
method), 265
destroy_stack() (run-
way.cfngin.providers.aws.default.Provider
method), 292
destroy_stack() (run-
way.cfngin.providers.base.BaseProvider
method), 287
determine_git_ls_remote_ref() (run-
way.cfngin.util.SourceProcessor static
method), 227
determine_git_ref() (run-
way.cfngin.util.SourceProcessor method),
227
dict() (runway.cfngin.hooks.docker.data_models.BaseModel
method), 272
DictValue (class in runway.cfngin.actions.diff ), 233
DidNotChangeStatus (class in run-
way.cfngin.status), 220
diff() (in module runway.cfngin.blueprints.testutil),
243
diff_dictionaries() (in module run-
way.cfngin.actions.diff ), 233
diff_parameters() (in module run-
way.cfngin.actions.diff ), 234
directory_index_specified() (run-
way.blueprints.staticsite.staticsite.StaticSite
property), 193
display_static_website_url() (in module
runway.hooks.staticsite.upload_staticsite), 310
DockerHookData (class in run-
way.cfngin.hooks.docker.hook_data), 273
DockerImage (class in run-
way.cfngin.hooks.docker.data_models), 272
dockerized_pip() (in module run-
way.cfngin.hooks.aws_lambda), 261
does_bucket_exist() (in module runway.s3_util),
177
does_s3_object_exist() (in module run-
way.s3_util), 177
domain_changed() (run-
way.cfngin.hooks.acm.Certificate method),
259
done() (runway.cfngin.plan.Step property), 211
dot_format() (in module run-
way.cfngin.actions.graph), 235
download() (in module runway.s3_util), 177
download_and_extract_to_mkdtemp() (in
module runway.s3_util), 177
download_kb_release() (in module run-
way.env_mgr.kbenv), 307
download_tf_release() (in module run-
way.env_mgr.tfenv), 307
downstream() (runway.cfngin.dag.DAG method), 256
downstream() (runway.cfngin.plan.Graph method),
214
dump() (in module runway.cfngin.config), 254
dump() (runway.cfngin.plan.Plan method), 215
dumps() (runway.cfngin.plan.Graph method), 214
DynamodbLookup (class in run-
way.cfngin.lookups.handlers.dynamodb),
277
E
each_step() (in module run-
way.cfngin.actions.graph), 235
echo_detected_environment() (run-
way.context.Context method), 171
EcrLookup (class in runway.lookups.handlers.ecr), 322
ElasticContainerRegistry (class in run-
way.cfngin.hooks.docker.data_models), 272
ElasticContainerRegistryRepository (class
in runway.cfngin.hooks.docker.data_models),
273
enable_versioning() (run-
way.core.providers.aws.s3.Bucket method),
376 Index
runway Documentation, Release 1.18.3
305
enabled (runway.cfngin.config.Hook attribute), 250
enabled (runway.cfngin.config.Stack attribute), 252,
253
enabled (runway.cfngin.stack.Stack attribute), 216
enabled (runway.config.FutureDefinition attribute),
163
ensure_bucket_exists() (in module run-
way.s3_util), 177
ensure_cfn_bucket() (run-
way.cfngin.actions.base.BaseAction method),
230
ensure_file_is_executable() (in module run-
way.util), 180
ensure_keypair_exists() (in module run-
way.cfngin.hooks.keypair), 269
ensure_s3_bucket() (in module run-
way.cfngin.util), 225
ensure_server_cert_exists() (in module run-
way.cfngin.hooks.iam), 269
env_dir (runway.env_mgr.EnvManager attribute), 306
env_dir_name (runway.env_mgr.EnvManager at-
tribute), 306
env_file (runway.cfngin.CFNgin attribute), 196
env_file (runway.cfngin.cfngin.CFNgin attribute),
198
env_file (runway.module.serverless.Serverless
attribute), 329
env_file (runway.module.terraform.Terraform at-
tribute), 332
env_name (runway.context.Context attribute), 170
env_region() (runway.context.Context property),
170
env_root() (runway.context.Context property), 170
env_vars() (runway.config.ConfigComponent prop-
erty), 159
env_vars() (runway.context.Context property), 170
env_vars_config() (run-
way.core.components.Deployment property),
299
environ() (in module runway.util), 180
environments() (runway.config.ConfigComponent
property), 159
EnvLookup (class in runway.lookups.handlers.env),
322
EnvManager (class in runway.env_mgr), 306
EnvvarLookup (class in run-
way.cfngin.lookups.handlers.envvar), 278
error (runway.core.providers.aws.BaseResponse
attribute), 303
EXCLUDE_LIST (runway.cfngin.CFNgin attribute),
195, 196
EXCLUDE_LIST (runway.cfngin.cfngin.CFNgin at-
tribute), 197, 198
EXCLUDE_REGEX (runway.cfngin.CFNgin attribute),
195, 196
EXCLUDE_REGEX (runway.cfngin.cfngin.CFNgin
attribute), 197, 198
execute() (runway.cfngin.actions.base.BaseAction
method), 230
execute() (runway.cfngin.plan.Plan method), 215
exists() (runway.core.providers.aws.s3.Bucket prop-
erty), 305
EXPECTATION_FAILED (run-
way.http_backport.HTTPStatus attribute),
173
extend_serverless_yml() (run-
way.module.serverless.Serverless method),
329
extension() (runway.cfngin.util.Extractor static
method), 226
extension() (runway.cfngin.util.TarExtractor static
method), 226
extension() (runway.cfngin.util.TarGzipExtractor
static method), 226
extension() (runway.cfngin.util.ZipExtractor static
method), 226
EXTENSION_MAP (run-
way.runway_module_type.RunwayModuleType
attribute), 177
extract() (runway.cfngin.util.TarExtractor method),
226
extract() (runway.cfngin.util.TarGzipExtractor
method), 226
extract() (runway.cfngin.util.ZipExtractor method),
226
extract_boto_args_from_env() (in module
runway.util), 181
Extractor (class in runway.cfngin.util), 226
F
failed() (runway.cfngin.plan.Step property), 211
FAILED_DEPENDENCY (run-
way.http_backport.HTTPStatus attribute),
173
FAILED_STATUSES (run-
way.cfngin.providers.aws.default.Provider
attribute), 291
FailedLookup, 203
FailedStatus (class in runway.cfngin.status), 219
FailedVariableLookup, 203
fetch() (runway.sources.git.Git method), 337
fetch() (runway.sources.source.Source method), 337
fetch_git_package() (run-
way.cfngin.util.SourceProcessor method),
227
fetch_local_package() (run-
way.cfngin.util.SourceProcessor method),
Index 377
runway Documentation, Release 1.18.3
227
fetch_s3_package() (run-
way.cfngin.util.SourceProcessor method),
227
FileLookup (class in run-
way.cfngin.lookups.handlers.file), 278
filter() (runway.cfngin.dag.DAG method), 256
filtered() (runway.cfngin.plan.Graph method), 214
find() (runway.cfngin.hooks.docker.data_models.BaseModel
method), 272
find() (runway.util.MutableMap method), 179
find_cfn_output() (in module runway.util), 181
find_config_file() (runway.config.Config class
method), 170
find_config_files() (runway.cfngin.CFNgin
class method), 196
find_config_files() (run-
way.cfngin.cfngin.CFNgin class method),
199
find_file() (runway.config.VariablesDefinition class
method), 168
find_requirements() (in module run-
way.cfngin.hooks.aws_lambda), 261
fix_windows_command_list() (in module run-
way.util), 181
flatten_path_lists() (in module runway.util),
181
fmt (runway.aws_sso_botocore.exceptions.PendingAuthorizationExpiredError
attribute), 187
fmt (runway.aws_sso_botocore.exceptions.SSOError at-
tribute), 187
fmt (runway.aws_sso_botocore.exceptions.SSOTokenLoadError
attribute), 187
fmt (runway.aws_sso_botocore.exceptions.UnauthorizedSSOTokenError
attribute), 187
fn (runway.cfngin.plan.Step attribute), 210
forbidden (runway.core.providers.aws.s3.Bucket at-
tribute), 305
FORBIDDEN (runway.http_backport.HTTPStatus at-
tribute), 172
forbidden() (runway.core.providers.aws.ResponseMetadata
property), 304
force (runway.cfngin.stack.Stack attribute), 217
format() (runway.cfngin.logger.ColorFormatter
method), 275
format_npm_command_for_logging() (in mod-
ule runway.module), 326
format_params_diff() (in module run-
way.cfngin.actions.diff ), 233
format_params_diff() (in module run-
way.cfngin.providers.aws.default), 289
format_results() (run-
way.lookups.handlers.base.LookupHandler
class method), 318
formatter (runway.cfngin.actions.diff.DictValue at-
tribute), 233
FOUND (runway.http_backport.HTTPStatus attribute),
172
fqn (runway.cfngin.stack.Stack attribute), 217
fqn (runway.core.components.Module attribute), 300
fqn() (runway.cfngin.hooks.docker.data_models.ElasticContainerRegistry
property), 272
fqn() (runway.cfngin.hooks.docker.data_models.ElasticContainerRegistryRepository
property), 273
from_cfngin_context() (run-
way.cfngin.hooks.docker.hook_data.DockerHookData
class method), 274
from_dict() (runway.cfngin.dag.DAG method), 257
from_dict() (runway.cfngin.plan.Graph class
method), 214
from_list() (runway.config.DeploymentDefinition
class method), 166
from_list() (runway.config.ModuleDefinition class
method), 163
from_list() (runway.config.TestDefinition class
method), 167
from_persistent_graph() (run-
way.cfngin.plan.Step class method), 212
from_stack_name() (runway.cfngin.plan.Step class
method), 211
from_steps() (runway.cfngin.plan.Graph class
method), 214
full_path() (in module runway.cfngin.hooks.utils),
271
FutureDefinition (class in runway.config), 163
G
GATEWAY_TIMEOUT (run-
way.http_backport.HTTPStatus attribute),
173
gen_backend_filenames() (run-
way.module.terraform.TerraformBackendConfig
static method), 335
gen_cmd() (runway.module.serverless.Serverless
method), 329
gen_command() (runway.module.terraform.Terraform
method), 332
gen_overlay_dirs() (in module run-
way.module.k8s), 327
gen_sls_config_files() (in module run-
way.module.serverless), 328
gen_workspace_tfvars_files() (in module
runway.module.terraform), 331
generate_cloudformation_args() (in module
runway.cfngin.providers.aws.default), 290
generate_node_command() (in module run-
way.module), 326
378 Index
runway Documentation, Release 1.18.3
generate_response() (in module run-
way.module.k8s), 327
generate_stack() (runway.cfngin.hooks.base.Hook
method), 265
generate_stack_policy_args() (in module
runway.cfngin.providers.aws.default), 290
get() (in module run-
way.hooks.staticsite.auth_at_edge.callback_url_retriever),
313
get() (in module run-
way.hooks.staticsite.auth_at_edge.user_pool_id_retriever),
316
get() (runway.cfngin.hooks.docker.data_models.BaseModel
method), 272
get() (runway.config.ConfigComponent method), 159
get() (runway.util.MutableMap method), 179
get() (runway.variables.Variable method), 182
get_archives_to_prune() (in module run-
way.hooks.staticsite.upload_staticsite), 310
get_auth_at_edge_lambda() (run-
way.blueprints.staticsite.auth_at_edge.AuthAtEdge
method), 191
get_auth_at_edge_lambda_and_ver() (run-
way.blueprints.staticsite.auth_at_edge.AuthAtEdge
method), 191
get_available_tf_versions() (in module run-
way.env_mgr.tfenv), 307
get_backend_file() (run-
way.module.terraform.TerraformBackendConfig
class method), 336
get_cdk_stacks() (in module runway.module.cdk),
326
get_certificate() (run-
way.cfngin.hooks.acm.Certificate method),
259
get_cfn_parameters() (run-
way.cfngin.blueprints.base.Blueprint method),
239
get_change_set_name() (in module run-
way.cfngin.providers.aws.default), 288
get_client_region() (in module run-
way.cfngin.util), 225
get_cloudformation_client() (in module run-
way.cfngin.providers.aws.default), 287
get_cloudfront_distribution_options()
(runway.blueprints.staticsite.staticsite.StaticSite
method), 193
get_config_directory() (in module run-
way.cfngin.util), 224
get_content() (in module run-
way.hooks.staticsite.upload_staticsite), 311
get_content_type() (in module run-
way.hooks.staticsite.upload_staticsite), 311
get_directory_index_lambda_association()
(runway.blueprints.staticsite.staticsite.StaticSite
method), 193
get_dirs() (runway.tests.handlers.base.TestHandler
static method), 338
get_distribution_data() (in module run-
way.hooks.staticsite.upload_staticsite), 310
get_distribution_options() (run-
way.blueprints.staticsite.auth_at_edge.AuthAtEdge
method), 192
get_embedded_lib_path() (in module run-
way.util), 181
get_env_vars() (runway.core.Runway method), 296
get_events() (run-
way.cfngin.providers.aws.default.Provider
method), 292
get_existing_key_pair() (in module run-
way.cfngin.hooks.keypair), 269
get_file_hash() (in module runway.util), 181
get_fqn() (in module runway.cfngin.context), 200
get_fqn() (runway.cfngin.context.Context method),
201
get_full_configuration() (run-
way.module.terraform.TerraformBackendConfig
method), 335
get_hash_for_filename() (in module run-
way.util), 181
get_hash_of_files() (in module run-
way.hooks.staticsite.util), 312
get_hosted_zone_by_name() (in module run-
way.cfngin.util), 223
get_ignorer() (in module run-
way.hooks.staticsite.util), 312
get_lambda_associations() (run-
way.blueprints.staticsite.staticsite.StaticSite
method), 193
get_latest_tf_version() (in module run-
way.env_mgr.tfenv), 307
get_login_password() (run-
way.lookups.handlers.ecr.EcrLookup static
method), 322
get_matching_s3_keys() (in module run-
way.s3_util), 177
get_matching_s3_objects() (in module run-
way.s3_util), 177
get_min_required() (run-
way.env_mgr.tfenv.TFEnvManager method),
308
get_module_defined_k8s_ver() (in module
runway.module.k8s), 327
get_nonce_signing_secret() (in module run-
way.hooks.staticsite.auth_at_edge.lambda_config),
315
get_or_create_hosted_zone() (in module run-
way.cfngin.util), 223
Index 379
runway Documentation, Release 1.18.3
get_output() (run-
way.cfngin.providers.base.BaseProvider
method), 287
get_output_definitions() (run-
way.cfngin.blueprints.base.Blueprint method),
239
get_output_definitions() (run-
way.cfngin.blueprints.raw.RawTemplateBlueprint
method), 242
get_output_dict() (in module run-
way.cfngin.providers.aws.default), 287
get_output_dict() (run-
way.cfngin.providers.aws.default.Provider
static method), 295
get_outputs() (run-
way.cfngin.providers.aws.default.Provider
method), 295
get_outputs() (run-
way.cfngin.providers.base.BaseProvider
method), 287
get_overlay_dir() (in module run-
way.module.k8s), 327
get_package_sources() (run-
way.cfngin.util.SourceProcessor method),
227
get_parameter_definitions() (run-
way.cfngin.blueprints.base.Blueprint method),
238
get_parameter_definitions() (run-
way.cfngin.blueprints.raw.RawTemplateBlueprint
method), 242
get_parameter_values() (run-
way.cfngin.blueprints.base.Blueprint method),
239
get_parameter_values() (run-
way.cfngin.blueprints.raw.RawTemplateBlueprint
method), 242
get_raw_input() (in module runway.cfngin.ui), 222
get_redirect_uris() (in module run-
way.hooks.staticsite.auth_at_edge.client_updater),
313
get_replicated_function_names() (in mod-
ule runway.hooks.staticsite.cleanup), 309
get_required_parameter_definitions()
(runway.cfngin.blueprints.base.Blueprint
method), 239
get_rollback_status_reason() (run-
way.cfngin.providers.aws.default.Provider
method), 292
get_s3_endpoint() (in module runway.cfngin.util),
225
get_session() (in module run-
way.cfngin.session_cache), 216
get_session() (runway.cfngin.context.Context
method), 201
get_session() (runway.context.Context method),
171
get_soa_record() (in module runway.cfngin.util),
224
get_src_hash() (in module run-
way.module.serverless), 328
get_ssm_value() (in module run-
way.hooks.staticsite.upload_staticsite), 311
get_stack() (runway.cfngin.context.Context
method), 201
get_stack() (runway.cfngin.providers.aws.default.Provider
method), 291
get_stack() (runway.cfngin.providers.base.BaseProvider
method), 287
get_stack_changes() (run-
way.cfngin.providers.aws.default.Provider
method), 295
get_stack_info() (run-
way.cfngin.providers.aws.default.Provider
method), 295
get_stack_name() (run-
way.cfngin.providers.aws.default.Provider
static method), 295
get_stack_output() (run-
way.lookups.handlers.cfn.CfnLookup static
method), 320
get_stack_status() (run-
way.cfngin.providers.aws.default.Provider
method), 291
get_stack_status() (run-
way.cfngin.providers.base.BaseProvider
method), 287
get_stack_tags() (run-
way.cfngin.providers.aws.default.Provider
static method), 295
get_stacks() (runway.cfngin.context.Context
method), 201
get_stacks_dict() (runway.cfngin.context.Context
method), 201
get_targets() (runway.cfngin.context.Context
method), 201
get_template_description() (run-
way.cfngin.hooks.base.Hook method), 265
get_template_params() (in module run-
way.cfngin.blueprints.raw), 241
get_template_path() (in module run-
way.cfngin.blueprints.raw), 241
get_user_pool_domain() (in module run-
way.hooks.staticsite.auth_at_edge.domain_updater),
314
get_valid_instance_types() (in module run-
way.blueprints.k8s.k8s_workers), 190
get_validation_record() (run-
380 Index
runway Documentation, Release 1.18.3
way.cfngin.hooks.acm.Certificate method),
259
get_variables() (run-
way.cfngin.blueprints.base.Blueprint method),
239
get_version_from_file() (run-
way.env_mgr.tfenv.TFEnvManager method),
308
get_version_requested() (in module run-
way.env_mgr.kbenv), 307
get_versioning() (run-
way.core.providers.aws.s3.Bucket method),
305
get_yaml_files_at_path() (run-
way.tests.handlers.yaml_lint.YamllintHandler
static method), 339
get_yamllint_options() (run-
way.tests.handlers.yaml_lint.YamllintHandler
class method), 339
getpass() (runway.cfngin.ui.UI method), 222
Git (class in runway.sources.git), 337
git (runway.cfngin.config.PackageSources attribute),
250, 251
git_ls_remote() (run-
way.cfngin.util.SourceProcessor static
method), 227
GitPackageSource (class in runway.cfngin.config),
249
GONE (runway.http_backport.HTTPStatus attribute), 173
Graph (class in runway.cfngin.plan), 212
graph (runway.cfngin.plan.Plan attribute), 214
GraphError, 203
H
handle() (runway.cfngin.lookups.handlers.ami.AmiLookup
class method), 276
handle() (runway.cfngin.lookups.handlers.default.DefaultLookup
class method), 277
handle() (runway.cfngin.lookups.handlers.dynamodb.DynamodbLookup
class method), 277
handle() (runway.cfngin.lookups.handlers.envvar.EnvvarLookup
class method), 278
handle() (runway.cfngin.lookups.handlers.file.FileLookup
class method), 278
handle() (runway.cfngin.lookups.handlers.hook_data.HookDataLookup
class method), 281
handle() (runway.cfngin.lookups.handlers.kms.KmsLookup
class method), 281
handle() (runway.cfngin.lookups.handlers.output.OutputLookup
class method), 282
handle() (runway.cfngin.lookups.handlers.rxref.RxrefLookup
class method), 283
handle() (runway.cfngin.lookups.handlers.split.SplitLookup
class method), 284
handle() (runway.cfngin.lookups.handlers.ssmstore.SsmstoreLookup
class method), 285
handle() (runway.cfngin.lookups.handlers.xref.XrefLookup
class method), 286
handle() (runway.lookups.handlers.base.LookupHandler
class method), 318
handle() (runway.lookups.handlers.cfn.CfnLookup
class method), 321
handle() (runway.lookups.handlers.ecr.EcrLookup
class method), 322
handle() (runway.lookups.handlers.env.EnvLookup
class method), 323
handle() (runway.lookups.handlers.ssm.SsmLookup
class method), 323
handle() (runway.lookups.handlers.var.VarLookup
class method), 324
handle() (runway.tests.handlers.base.TestHandler
class method), 338
handle() (runway.tests.handlers.cfn_lint.CfnLintHandler
class method), 339
handle() (runway.tests.handlers.script.ScriptHandler
class method), 339
handle() (runway.tests.handlers.yaml_lint.YamllintHandler
class method), 339
handle_backend() (run-
way.module.terraform.Terraform method),
332
handle_bin_download_error() (in module run-
way.env_mgr), 306
handle_hooks() (in module run-
way.cfngin.actions.build), 231
handle_hooks() (in module run-
way.cfngin.hooks.utils), 271
handle_parameters() (run-
way.module.terraform.Terraform method),
332
handle_requirements() (in module run-
way.cfngin.hooks.aws_lambda), 261
head (runway.core.providers.aws.s3.Bucket attribute),
305
Hook (class in runway.cfngin.config), 249
Hook (class in runway.cfngin.hooks.base), 264
HookBuildAction (class in run-
way.cfngin.hooks.base), 266
HookDataLookup (class in run-
way.cfngin.lookups.handlers.hook_data),
281
HookDestroyAction (class in run-
way.cfngin.hooks.base), 266
HookStackDefinition (class in run-
way.cfngin.hooks.base), 266
host_id (runway.core.providers.aws.ResponseMetadata
attribute), 303
http_status_code (run-
Index 381
runway Documentation, Release 1.18.3
way.core.providers.aws.ResponseMetadata
attribute), 303
HTTP_VERSION_NOT_SUPPORTED (run-
way.http_backport.HTTPStatus attribute),
173
https_headers (run-
way.core.providers.aws.ResponseMetadata
attribute), 303
HTTPStatus (class in runway.http_backport), 171
I
Iam (class in runway.blueprints.k8s.k8s_iam), 189
IAM_ARN_PREFIX (run-
way.blueprints.staticsite.auth_at_edge.AuthAtEdge
attribute), 191
id (runway.cfngin.plan.Plan attribute), 215
id (runway.core.providers.aws.AccountDetails at-
tribute), 302
id() (runway.cfngin.hooks.docker.data_models.DockerImage
property), 272
ignore_exit_code_0() (in module runway.util),
181
ignore_git_branch() (run-
way.core.components.DeployEnvironment
property), 297
IM_USED (runway.http_backport.HTTPStatus attribute),
172
image (runway.cfngin.hooks.docker.hook_data.DockerHookData
attribute), 274
ImageNotFound, 276
import_key_pair() (in module run-
way.cfngin.hooks.keypair), 269
import_mappings() (run-
way.cfngin.blueprints.base.Blueprint method),
240
ImproperlyConfigured, 203
in_progress_behavior (run-
way.cfngin.config.Stack attribute), 252, 253
in_progress_behavior (runway.cfngin.stack.Stack
attribute), 217
IN_PROGRESS_STATUSES (run-
way.cfngin.providers.aws.default.Provider
attribute), 291
increase_indent() (runway.util.YamlDumper
method), 180
ind_nodes() (runway.cfngin.dag.DAG method), 257
info() (runway.cfngin.ui.UI method), 222
init_args (runway.module.terraform.TerraformBackendConfig
attribute), 335
install() (runway.env_mgr.kbenv.KBEnvManager
method), 307
install() (runway.env_mgr.tfenv.TFEnvManager
method), 308
INSUFFICIENT_STORAGE (run-
way.http_backport.HTTPStatus attribute),
173
interactive (runway.cfngin.CFNgin attribute), 195
interactive (runway.cfngin.cfngin.CFNgin at-
tribute), 198
interactive_destroy_stack() (run-
way.cfngin.providers.aws.default.Provider
method), 294
interactive_prompt() (in module run-
way.cfngin.hooks.keypair), 269
interactive_update_stack() (run-
way.cfngin.providers.aws.default.Provider
method), 294
INTERNAL_SERVER_ERROR (run-
way.http_backport.HTTPStatus attribute),
173
intrinsics_multi_constructor() (in module
runway.cfngin.awscli_yamlhelper), 197
invalidate_distribution() (in module run-
way.hooks.staticsite.upload_staticsite), 310
InvalidConfig, 204
InvalidDockerizePipConfiguration, 204
InvalidLookupCombination, 204
InvalidLookupConcatenation, 204
InvalidUserdataPlaceholder, 204
is_interactive() (runway.context.Context prop-
erty), 170
is_noninteractive() (runway.context.Context
property), 171
is_python3() (runway.context.Context property),
171
is_stack_being_destroyed() (run-
way.cfngin.providers.aws.default.Provider
method), 291
is_stack_completed() (run-
way.cfngin.providers.aws.default.Provider
method), 291
is_stack_destroyed() (run-
way.cfngin.providers.aws.default.Provider
method), 291
is_stack_failed() (run-
way.cfngin.providers.aws.default.Provider
method), 291
is_stack_in_progress() (run-
way.cfngin.providers.aws.default.Provider
method), 291
is_stack_in_review() (run-
way.cfngin.providers.aws.default.Provider
method), 291
is_stack_recreatable() (run-
way.cfngin.providers.aws.default.Provider
method), 291
is_stack_rolling_back() (run-
382 Index
runway Documentation, Release 1.18.3
way.cfngin.providers.aws.default.Provider
method), 291
ISO8601_FORMAT (run-
way.cfngin.util.SourceProcessor attribute),
227
J
json_codec() (in module run-
way.cfngin.lookups.handlers.file), 281
json_format() (in module run-
way.cfngin.actions.graph), 235
json_serial() (in module runway.cfngin.plan), 209
json_serial() (in module runway.util), 180
JsonEncoder (class in runway.util), 178
K
K8s (class in runway.module.k8s), 327
KBEnvManager (class in runway.env_mgr.kbenv), 307
key (runway.cfngin.config.S3PackageSource attribute),
251
keys() (runway.cfngin.plan.Plan method), 216
kms_simple_constructor() (in module run-
way.cfngin.config.translators.kms), 255
KmsLookup (class in run-
way.cfngin.lookups.handlers.kms), 281
L
last_updated (runway.cfngin.plan.Step attribute),
210
legacy_parse() (run-
way.cfngin.lookups.handlers.hook_data.HookDataLookup
class method), 281
LENGTH_REQUIRED (run-
way.http_backport.HTTPStatus attribute),
173
load() (in module runway.cfngin.config), 254
load() (runway.aws_sso_botocore.credentials.SSOProvider
method), 187
load() (runway.cfngin.CFNgin method), 197
load() (runway.cfngin.cfngin.CFNgin method), 199
load() (runway.config.VariablesDefinition class
method), 168
load() (runway.lookups.handlers.base.LookupHandler
class method), 319
load_from_file() (runway.config.Config class
method), 170
load_object_from_string() (in module run-
way.util), 180
load_terrafrom_module() (in module run-
way.env_mgr.tfenv), 307
local (runway.cfngin.config.PackageSources attribute),
250, 251
LocalPackageSource (class in run-
way.cfngin.config), 250
lock() (runway.cfngin.ui.UI method), 222
lock_code() (runway.cfngin.plan.Plan property), 216
lock_persistent_graph() (run-
way.cfngin.context.Context method), 202
locked (runway.cfngin.config.Stack attribute), 252, 253
locked (runway.cfngin.stack.Stack attribute), 217
LOCKED (runway.http_backport.HTTPStatus attribute),
173
log() (runway.cfngin.ui.UI method), 222
log_formats (runway.cfngin.config.Config attribute),
246, 247
log_name() (runway.core.components.DeployEnvironment
method), 297
log_npm_command() (run-
way.module.RunwayModuleNpm method),
326
log_step() (runway.cfngin.plan.Step method), 211
logger (runway.cfngin.plan.Step attribute), 210
logging (runway.cfngin.stack.Stack attribute), 217
logging (runway.cfngin.target.Target attribute), 221
login() (in module runway.cfngin.hooks.docker), 271
LookupHandler (class in run-
way.lookups.handlers.base), 318
lookups (runway.cfngin.config.Config attribute), 246,
247
LOOP_DETECTED (runway.http_backport.HTTPStatus
attribute), 173
M
mappings (runway.cfngin.config.Config attribute), 246,
247
mappings (runway.cfngin.stack.Stack attribute), 217
mappings() (runway.cfngin.context.Context property),
200
max_concurrent_cfngin_stacks() (run-
way.core.components.DeployEnvironment
property), 297
max_concurrent_modules() (run-
way.core.components.DeployEnvironment
property), 298
max_concurrent_regions() (run-
way.core.components.DeployEnvironment
property), 298
md5sum() (in module runway.util), 181
menu_entry() (runway.config.DeploymentDefinition
property), 166
menu_entry() (runway.config.ModuleDefinition
property), 162
merge_dicts() (in module runway.util), 181
merge_graphs() (in module runway.cfngin.plan),
209
merge_map() (in module runway.cfngin.util), 224
merge_nested_env_dicts() (run-
way.module.ModuleOptions static method),
Index 383
runway Documentation, Release 1.18.3
325
merge_nested_environment_dicts() (in mod-
ule runway.util), 181
message (runway.core.providers.aws.ResponseError
attribute), 303
MESSAGES (runway.cfngin.config.AnyType attribute),
245
metadata (runway.core.providers.aws.BaseResponse
attribute), 303
METHOD (runway.aws_sso_botocore.credentials.SSOProvider
attribute), 187
METHOD_NOT_ALLOWED (run-
way.http_backport.HTTPStatus attribute),
173
MISDIRECTED_REQUEST (run-
way.http_backport.HTTPStatus attribute),
173
MissingEnvironment, 205
MissingParameterException, 205
MissingVariable, 205
MODIFIED (runway.cfngin.actions.diff.DictValue at-
tribute), 233
Module (class in runway.core.components), 300
module_options() (run-
way.config.DeploymentDefinition property),
166
ModuleDefinition (class in runway.config), 48, 159
ModuleOptions (class in runway.module), 325
MOVED_PERMANENTLY (run-
way.http_backport.HTTPStatus attribute),
172
MULTI_STATUS (runway.http_backport.HTTPStatus at-
tribute), 172
MULTIPLE_CHOICES (run-
way.http_backport.HTTPStatus attribute),
172
MutableMap (class in runway.util), 179
N
NAME (runway.cfngin.actions.base.BaseAction attribute),
230
NAME (runway.cfngin.actions.build.Action attribute), 232
NAME (runway.cfngin.actions.destroy.Action attribute),
233
NAME (runway.cfngin.actions.diff.Action attribute), 234
NAME (runway.cfngin.actions.graph.Action attribute),
235
NAME (runway.cfngin.actions.info.Action attribute), 236
name (runway.cfngin.config.Stack attribute), 252, 253
name (runway.cfngin.config.Target attribute), 253, 254
name (runway.cfngin.stack.Stack attribute), 217
name (runway.cfngin.status.Status attribute), 219
name (runway.cfngin.target.Target attribute), 221
name (runway.core.components.DeployEnvironment at-
tribute), 298
name() (runway.cfngin.plan.Step property), 210
namespace (runway.cfngin.config.Config attribute),
246, 247
namespace() (runway.cfngin.context.Context prop-
erty), 200
namespace_delimiter (run-
way.cfngin.config.Config attribute), 246,
248
namespace_delimiter() (run-
way.cfngin.context.Context property), 200
NETWORK_AUTHENTICATION_REQUIRED (run-
way.http_backport.HTTPStatus attribute),
173
no_color (runway.context.Context attribute), 170
NO_CONTENT (runway.http_backport.HTTPStatus at-
tribute), 172
NodeGroup (class in run-
way.blueprints.k8s.k8s_workers), 190
NON_AUTHORITATIVE_INFORMATION (run-
way.http_backport.HTTPStatus attribute),
172
noninteractive_changeset_update() (run-
way.cfngin.providers.aws.default.Provider
method), 294
noninteractive_destroy_stack() (run-
way.cfngin.providers.aws.default.Provider
method), 294
NOT_ACCEPTABLE (runway.http_backport.HTTPStatus
attribute), 173
NOT_EXTENDED (runway.http_backport.HTTPStatus at-
tribute), 173
not_found (runway.core.providers.aws.s3.Bucket at-
tribute), 305
NOT_FOUND (runway.http_backport.HTTPStatus at-
tribute), 172
not_found() (runway.core.providers.aws.ResponseMetadata
property), 304
NOT_IMPLEMENTED (run-
way.http_backport.HTTPStatus attribute),
173
not_implemented() (in module run-
way.cfngin.providers.base), 286
NOT_MODIFIED (runway.http_backport.HTTPStatus at-
tribute), 172
NotSubmittedStatus (class in run-
way.cfngin.status), 220
NotUpdatedStatus (class in runway.cfngin.status),
220
npm_install() (runway.module.RunwayModuleNpm
method), 326
384 Index
runway Documentation, Release 1.18.3
O
OK (runway.http_backport.HTTPStatus attribute), 172
ok() (runway.cfngin.plan.Step property), 211
OPTIONS (runway.module.terraform.TerraformBackendConfig
attribute), 335
options() (runway.config.ModuleDefinition prop-
erty), 162
outline() (runway.cfngin.plan.Plan method), 215
Output (class in run-
way.cfngin.lookups.handlers.output), 282
output_full_changeset() (in module run-
way.cfngin.providers.aws.default), 288
output_name() (run-
way.cfngin.lookups.handlers.output.Output
property), 282
output_name() (run-
way.lookups.handlers.cfn.OutputQuery prop-
erty), 320
OUTPUT_PATH (runway.cfngin.blueprints.testutil.BlueprintTestCase
attribute), 243
output_summary() (in module run-
way.cfngin.providers.aws.default), 288
OutputDoesNotExist, 205
OutputLookup (class in run-
way.cfngin.lookups.handlers.output), 282
OutputQuery (class in runway.lookups.handlers.cfn),
320
outputs (runway.cfngin.stack.Stack attribute), 217
P
package_json_missing() (run-
way.module.RunwayModuleNpm method),
326
package_sources (runway.cfngin.config.Config at-
tribute), 246, 248
PackageSources (class in runway.cfngin.config), 250
parallel_regions() (run-
way.config.DeploymentDefinition property),
166
parameter_values() (runway.cfngin.stack.Stack
property), 218
parameterized_codec() (in module run-
way.cfngin.lookups.handlers.file), 280
parameters (runway.cfngin.CFNgin attribute), 195
parameters (runway.cfngin.cfngin.CFNgin attribute),
198
parameters (runway.cfngin.config.Stack attribute),
252, 253
parameters() (runway.config.ConfigComponent
property), 159
params_as_dict() (run-
way.cfngin.providers.aws.default.Provider
static method), 296
parse() (in module runway.cfngin.config), 254
parse() (runway.lookups.handlers.base.LookupHandler
class method), 319
parse() (runway.module.ModuleOptions class
method), 325
parse() (runway.module.serverless.ServerlessOptions
class method), 330
parse() (runway.module.terraform.TerraformBackendConfig
class method), 336
parse() (runway.module.terraform.TerraformOptions
class method), 334
parse() (runway.path.Path class method), 176
parse() (runway.variables.VariableValue class
method), 183
parse() (runway.variables.VariableValueDict class
method), 185
parse() (runway.variables.VariableValueList class
method), 184
parse_cloudformation_template() (in mod-
ule runway.cfngin.util), 225
parse_environment() (in module run-
way.cfngin.environment), 202
parse_obj() (runway.cfngin.hooks.docker.data_models.BaseModel
class method), 272
parse_user_data() (in module run-
way.cfngin.blueprints.base), 238
parse_zone_id() (in module runway.cfngin.util),
223
PARTIAL_CONTENT (run-
way.http_backport.HTTPStatus attribute),
172
Path (class in runway.path), 174
path (runway.cfngin.config.Hook attribute), 250
path (runway.core.components.Module attribute), 300
path (runway.env_mgr.EnvManager attribute), 306
path() (runway.config.ModuleDefinition property), 162
paths (runway.cfngin.config.GitPackageSource at-
tribute), 249
paths (runway.cfngin.config.LocalPackageSource at-
tribute), 250
paths (runway.cfngin.config.S3PackageSource at-
tribute), 251
payload (runway.core.components.Module attribute),
301
PAYMENT_REQUIRED (run-
way.http_backport.HTTPStatus attribute),
172
PendingAuthorizationExpiredError, 187
PendingStatus (class in runway.cfngin.status), 220
PERMANENT_REDIRECT (run-
way.http_backport.HTTPStatus attribute),
172
persistent_graph() (run-
way.cfngin.context.Context property), 200
persistent_graph_key (run-
Index 385
runway Documentation, Release 1.18.3
way.cfngin.config.Config attribute), 246,
248
persistent_graph_location() (run-
way.cfngin.context.Context property), 200
persistent_graph_lock_code() (run-
way.cfngin.context.Context property), 200
persistent_graph_locked() (run-
way.cfngin.context.Context property), 201
PersistentGraphCannotLock, 206
PersistentGraphCannotUnlock, 206
PersistentGraphLockCodeMissmatch, 206
PersistentGraphLocked, 206
PersistentGraphUnlocked, 206
PipenvError, 206
PipError, 205
Plan (class in runway.cfngin.plan), 214
plan() (runway.cfngin.CFNgin method), 197
plan() (runway.cfngin.cfngin.CFNgin method), 199
plan() (runway.core.components.Deployment method),
299
plan() (runway.core.components.Module method), 301
plan() (runway.core.Runway method), 296
plan() (runway.module.cdk.CloudDevelopmentKit
method), 327
plan() (runway.module.cloudformation.CloudFormation
method), 327
plan() (runway.module.k8s.K8s method), 328
plan() (runway.module.RunwayModule method), 325
plan() (runway.module.serverless.Serverless method),
330
plan() (runway.module.staticsite.StaticSite method),
331
plan() (runway.module.terraform.Terraform method),
333
PlanFailed, 206
pop() (runway.cfngin.plan.Graph method), 213
post_build (runway.cfngin.config.Config attribute),
246, 248
post_deploy() (run-
way.cfngin.hooks.acm.Certificate method),
260
post_deploy() (runway.cfngin.hooks.base.Hook
method), 266
post_destroy (runway.cfngin.config.Config at-
tribute), 246, 248
post_destroy() (run-
way.cfngin.hooks.acm.Certificate method),
260
post_destroy() (runway.cfngin.hooks.base.Hook
method), 266
post_run() (runway.cfngin.actions.base.BaseAction
method), 230
post_run() (runway.cfngin.actions.build.Action
method), 232
post_run() (runway.cfngin.actions.destroy.Action
method), 233
post_run() (runway.cfngin.actions.diff.Action
method), 234
pre_build (runway.cfngin.config.Config attribute),
246, 248
pre_deploy() (runway.cfngin.hooks.acm.Certificate
method), 260
pre_deploy() (runway.cfngin.hooks.base.Hook
method), 266
pre_destroy (runway.cfngin.config.Config attribute),
246, 248
pre_destroy() (run-
way.cfngin.hooks.acm.Certificate method),
260
pre_destroy() (runway.cfngin.hooks.base.Hook
method), 266
PRE_PROCESS_VARIABLES (run-
way.config.ConfigComponent attribute),
158, 159
PRE_PROCESS_VARIABLES (run-
way.config.DeploymentDefinition attribute),
166
pre_run() (runway.cfngin.actions.base.BaseAction
method), 230
pre_run() (runway.cfngin.actions.build.Action
method), 232
pre_run() (runway.cfngin.actions.destroy.Action
method), 233
pre_run() (runway.cfngin.actions.diff.Action method),
234
PRECONDITION_FAILED (run-
way.http_backport.HTTPStatus attribute),
173
PRECONDITION_REQUIRED (run-
way.http_backport.HTTPStatus attribute),
173
predecessors() (runway.cfngin.dag.DAG method),
257
prepare_stack_for_update() (run-
way.cfngin.providers.aws.default.Provider
method), 292
process_remote_sources() (in module run-
way.cfngin.config), 254
PROCESSING (runway.http_backport.HTTPStatus at-
tribute), 172
profile (runway.cfngin.config.Stack attribute), 252,
253
profile (runway.cfngin.stack.Stack attribute), 217
ProfileProviderBuilder (class in run-
way.aws_sso_botocore.credentials), 186
protected (runway.cfngin.config.Stack attribute), 252,
253
protected (runway.cfngin.stack.Stack attribute), 217
386 Index
runway Documentation, Release 1.18.3
Provider (class in run-
way.cfngin.providers.aws.default), 291
provider (runway.cfngin.hooks.base.Hook attribute),
265
provider() (runway.cfngin.actions.base.BaseAction
property), 230
provider() (runway.cfngin.hooks.base.HookBuildAction
property), 266
provider_builder (run-
way.cfngin.actions.base.BaseAction attribute),
229
ProviderBuilder (class in run-
way.cfngin.providers.aws.default), 290
providers() (runway.aws_sso_botocore.credentials.ProfileProviderBuilder
method), 186
PROXY_AUTHENTICATION_REQUIRED (run-
way.http_backport.HTTPStatus attribute),
173
prune_archives() (in module run-
way.hooks.staticsite.upload_staticsite), 311
PUBLIC_URI_TEMPLATE (run-
way.cfngin.hooks.docker.data_models.ElasticContainerRegistry
attribute), 272
purge_and_delete_bucket() (in module run-
way.s3_util), 177
purge_bucket() (in module run-
way.hooks.cleanup_s3), 309
purge_bucket() (in module runway.s3_util), 177
purge_repository() (in module run-
way.cfngin.hooks.ecr), 274
push() (in module runway.cfngin.hooks.docker.image),
274
put_persistent_graph() (run-
way.cfngin.context.Context method), 202
put_record_set() (run-
way.cfngin.hooks.acm.Certificate method),
260
R
random_key() (in module run-
way.hooks.staticsite.auth_at_edge.lambda_config),
315
RawTemplateBlueprint (class in run-
way.cfngin.blueprints.raw), 241
read_public_key_file() (in module run-
way.cfngin.hooks.keypair), 269
read_user_data() (run-
way.cfngin.blueprints.base.Blueprint method),
240
read_value_from_path() (in module run-
way.cfngin.util), 225
reason (runway.cfngin.status.DidNotChangeStatus at-
tribute), 220
reason (runway.cfngin.status.NotSubmittedStatus at-
tribute), 220
reason (runway.cfngin.status.NotUpdatedStatus at-
tribute), 220
reason (runway.cfngin.status.StackDoesNotExist at-
tribute), 221
reason (runway.cfngin.status.Status attribute), 219
recreate_failed (runway.cfngin.CFNgin attribute),
195
recreate_failed (runway.cfngin.cfngin.CFNgin at-
tribute), 198
RECREATION_STATUSES (run-
way.cfngin.providers.aws.default.Provider
attribute), 291
ref() (runway.cfngin.blueprints.base.CFNParameter
property), 236
region (runway.cfngin.CFNgin attribute), 195
region (runway.cfngin.cfngin.CFNgin attribute), 198
region (runway.cfngin.config.Stack attribute), 252, 253
region (runway.cfngin.stack.Stack attribute), 217
regions (runway.core.components.Deployment at-
tribute), 299
regions() (runway.config.DeploymentDefinition
property), 166
register_lookup_handler() (in module run-
way.cfngin.lookups.registry), 275
register_lookup_handler() (in module run-
way.lookups.registry), 316
register_test_handler() (in module run-
way.tests.registry), 338
release() (runway.cfngin.dag.UnlimitedSemaphore
method), 258
remove() (in module run-
way.cfngin.hooks.docker.image), 274
remove_validation_records() (run-
way.cfngin.hooks.acm.Certificate method),
260
REMOVED (runway.cfngin.actions.diff.DictValue at-
tribute), 233
rename_edges() (runway.cfngin.dag.DAG method),
257
render() (in module runway.cfngin.config), 254
render_parse_load() (in module run-
way.cfngin.config), 254
render_template() (run-
way.cfngin.blueprints.base.Blueprint method),
240
render_template() (run-
way.cfngin.blueprints.raw.RawTemplateBlueprint
method), 242
rendered() (runway.cfngin.blueprints.base.Blueprint
property), 240
rendered() (runway.cfngin.blueprints.raw.RawTemplateBlueprint
property), 242
Index 387
runway Documentation, Release 1.18.3
repo() (runway.cfngin.hooks.docker.data_models.DockerImage
property), 272
REQUEST_ENTITY_TOO_LARGE (run-
way.http_backport.HTTPStatus attribute),
173
REQUEST_HEADER_FIELDS_TOO_LARGE (run-
way.http_backport.HTTPStatus attribute),
173
request_id (runway.core.providers.aws.ResponseMetadata
attribute), 303
REQUEST_TIMEOUT (run-
way.http_backport.HTTPStatus attribute),
173
REQUEST_URI_TOO_LONG (run-
way.http_backport.HTTPStatus attribute),
173
REQUESTED_RANGE_NOT_SATISFIABLE (run-
way.http_backport.HTTPStatus attribute),
173
requester_pays (run-
way.cfngin.config.S3PackageSource attribute),
251
require_unlocked (runway.cfngin.plan.Plan at-
tribute), 215
required (runway.cfngin.config.Hook attribute), 250
required() (runway.config.TestDefinition property),
167
required_by (runway.cfngin.config.Stack attribute),
252, 253
required_by (runway.cfngin.config.Target attribute),
253, 254
required_by (runway.cfngin.target.Target attribute),
221
required_by() (runway.cfngin.plan.Step property),
210
required_by() (runway.cfngin.stack.Stack property),
218
required_parameter_definitions() (run-
way.cfngin.stack.Stack property), 218
requires (runway.cfngin.config.Stack attribute), 252,
253
requires (runway.cfngin.config.Target attribute), 254
requires (runway.cfngin.target.Target attribute), 221
requires() (runway.cfngin.plan.Step property), 210
requires() (runway.cfngin.stack.Stack property), 218
requires_change_set() (run-
way.cfngin.blueprints.base.Blueprint property),
240
requires_change_set() (run-
way.cfngin.blueprints.raw.RawTemplateBlueprint
property), 242
requires_replacement() (in module run-
way.cfngin.providers.aws.default), 288
reset_all() (runway.util.SafeHaven method), 180
RESET_CONTENT (runway.http_backport.HTTPStatus
attribute), 172
reset_graph() (runway.cfngin.dag.DAG method),
257
reset_os_environ() (runway.util.SafeHaven
method), 180
reset_sys_argv() (runway.util.SafeHaven method),
180
reset_sys_modules() (runway.util.SafeHaven
method), 180
reset_sys_path() (runway.util.SafeHaven method),
180
reset_template() (run-
way.cfngin.blueprints.base.Blueprint method),
240
resolve() (runway.cfngin.stack.Stack method), 219
resolve() (runway.config.ConfigComponent method),
159
resolve() (runway.variables.Variable method), 182
resolve() (runway.variables.VariableValue method),
183
resolve() (runway.variables.VariableValueConcatenation
method), 185
resolve() (runway.variables.VariableValueDict
method), 184
resolve() (runway.variables.VariableValueList
method), 184
resolve() (runway.variables.VariableValueLookup
method), 186
resolve_cfn_outputs() (run-
way.module.terraform.TerraformBackendConfig
static method), 335
resolve_lookups() (in module run-
way.cfngin.lookups.registry), 275
resolve_ssm_params() (run-
way.module.terraform.TerraformBackendConfig
static method), 335
resolve_variable() (in module run-
way.cfngin.blueprints.base), 237
resolve_variable() (in module run-
way.cfngin.blueprints.raw), 241
resolve_variables() (in module run-
way.variables), 182
resolve_variables() (run-
way.cfngin.blueprints.base.Blueprint method),
239
resolve_variables() (run-
way.cfngin.blueprints.raw.RawTemplateBlueprint
method), 242
resolve_version() (run-
way.module.terraform.TerraformOptions
static method), 334
resolved() (runway.variables.Variable property), 182
resolved() (runway.variables.VariableValue prop-
388 Index
runway Documentation, Release 1.18.3
erty), 183
resolved() (runway.variables.VariableValueConcatenation
property), 185
resolved() (runway.variables.VariableValueDict
property), 184
resolved() (runway.variables.VariableValueList
property), 184
resolved() (runway.variables.VariableValueLiteral
property), 183
resolved() (runway.variables.VariableValueLookup
property), 185
resource_name() (run-
way.cfngin.blueprints.variables.types.TroposphereType
property), 244
ResponseError (class in runway.core.providers.aws),
303
ResponseMetadata (class in run-
way.core.providers.aws), 303
restore_existing_iam_env_vars() (run-
way.core.providers.aws.AssumeRole method),
302
retry_attempts (run-
way.core.providers.aws.ResponseMetadata
attribute), 304
reverse (runway.cfngin.plan.Plan attribute), 215
reverse() (runway.config.DeploymentDefinition
method), 166
reverse_deployments() (runway.core.Runway
static method), 296
REVIEW_STATUS (run-
way.cfngin.providers.aws.default.Provider
attribute), 291
role_boundary_specified() (run-
way.blueprints.staticsite.staticsite.StaticSite
property), 193
ROLLING_BACK_STATUSES (run-
way.cfngin.providers.aws.default.Provider
attribute), 291
run() (runway.cfngin.actions.base.BaseAction method),
230
run() (runway.cfngin.actions.build.Action method), 232
run() (runway.cfngin.actions.destroy.Action method),
233
run() (runway.cfngin.actions.diff.Action method), 234
run() (runway.cfngin.actions.graph.Action method),
235
run() (runway.cfngin.actions.info.Action method), 236
run() (runway.cfngin.hooks.base.HookBuildAction
method), 266
run() (runway.cfngin.hooks.base.HookDestroyAction
method), 266
run() (runway.cfngin.plan.Step method), 210
run() (runway.core.components.Deployment method),
299
run() (runway.core.components.Module method), 301
run() (runway.module.terraform.Terraform method),
333
run_cdk() (runway.module.cdk.CloudDevelopmentKit
method), 326
run_command() (in module run-
way.cfngin.hooks.command), 267
run_commands() (in module runway.util), 181
run_kubectl() (runway.module.k8s.K8s method),
328
run_list() (runway.core.components.Deployment
class method), 299
run_list() (runway.core.components.Module class
method), 301
run_module_command() (in module run-
way.module), 326
run_npm_install() (in module runway.module),
326
run_sls_print() (in module run-
way.module.serverless), 328
Runway (class in runway.core), 296
runway (module), 158
runway.aws_sso_botocore (module), 186
runway.aws_sso_botocore.credentials
(module), 186
runway.aws_sso_botocore.exceptions (mod-
ule), 187
runway.aws_sso_botocore.session (module),
188
runway.aws_sso_botocore.util (module), 188
runway.blueprints (module), 188
runway.blueprints.k8s (module), 189
runway.blueprints.k8s.k8s_iam (module),
189
runway.blueprints.k8s.k8s_master (mod-
ule), 189
runway.blueprints.k8s.k8s_workers (mod-
ule), 190
runway.blueprints.staticsite (module), 190
runway.blueprints.staticsite.auth_at_edge
(module), 191
runway.blueprints.staticsite.dependencies
(module), 192
runway.blueprints.staticsite.staticsite
(module), 193
runway.blueprints.tf_state (module), 188
runway.cfngin (module), 195
runway.cfngin.actions (module), 228
runway.cfngin.actions.base (module), 228
runway.cfngin.actions.build (module), 231
runway.cfngin.actions.destroy (module),
232
runway.cfngin.actions.diff (module), 233
runway.cfngin.actions.graph (module), 235
Index 389
runway Documentation, Release 1.18.3
runway.cfngin.actions.info (module), 236
runway.cfngin.awscli_yamlhelper (module),
197
runway.cfngin.blueprints (module), 236
runway.cfngin.blueprints.base (module),
236
runway.cfngin.blueprints.raw (module), 241
runway.cfngin.blueprints.testutil (mod-
ule), 243
runway.cfngin.blueprints.variables (mod-
ule), 244
runway.cfngin.blueprints.variables.types
(module), 244
runway.cfngin.cfngin (module), 197
runway.cfngin.config (module), 245
runway.cfngin.config.translators (mod-
ule), 255
runway.cfngin.config.translators.kms
(module), 255
runway.cfngin.context (module), 200
runway.cfngin.dag (module), 255
runway.cfngin.environment (module), 202
runway.cfngin.exceptions (module), 203
runway.cfngin.hooks (module), 258
runway.cfngin.hooks.acm (module), 258
runway.cfngin.hooks.aws_lambda (module),
260
runway.cfngin.hooks.base (module), 264
runway.cfngin.hooks.command (module), 267
runway.cfngin.hooks.docker (module), 271
runway.cfngin.hooks.docker.data_models
(module), 272
runway.cfngin.hooks.docker.hook_data
(module), 273
runway.cfngin.hooks.docker.image (mod-
ule), 274
runway.cfngin.hooks.ecr (module), 274
runway.cfngin.hooks.ecs (module), 268
runway.cfngin.hooks.iam (module), 268
runway.cfngin.hooks.keypair (module), 269
runway.cfngin.hooks.route53 (module), 270
runway.cfngin.hooks.utils (module), 271
runway.cfngin.logger (module), 274
runway.cfngin.lookups (module), 275
runway.cfngin.lookups.handlers (module),
276
runway.cfngin.lookups.handlers.ami (mod-
ule), 276
runway.cfngin.lookups.handlers.default
(module), 277
runway.cfngin.lookups.handlers.dynamodb
(module), 277
runway.cfngin.lookups.handlers.envvar
(module), 278
runway.cfngin.lookups.handlers.file
(module), 278
runway.cfngin.lookups.handlers.hook_data
(module), 281
runway.cfngin.lookups.handlers.kms (mod-
ule), 281
runway.cfngin.lookups.handlers.output
(module), 282
runway.cfngin.lookups.handlers.rxref
(module), 283
runway.cfngin.lookups.handlers.split
(module), 284
runway.cfngin.lookups.handlers.ssmstore
(module), 285
runway.cfngin.lookups.handlers.xref
(module), 286
runway.cfngin.lookups.registry (module),
275
runway.cfngin.plan (module), 209
runway.cfngin.providers (module), 286
runway.cfngin.providers.aws (module), 287
runway.cfngin.providers.aws.default
(module), 287
runway.cfngin.providers.base (module), 286
runway.cfngin.session_cache (module), 216
runway.cfngin.stack (module), 216
runway.cfngin.status (module), 219
runway.cfngin.target (module), 221
runway.cfngin.tokenize_userdata (module),
221
runway.cfngin.ui (module), 222
runway.cfngin.util (module), 223
runway.config (module), 158
runway.context (module), 170
runway.core (module), 296
runway.core.components (module), 297
runway.core.providers (module), 302
runway.core.providers.aws (module), 302
runway.core.providers.aws.s3 (module), 304
runway.env_mgr (module), 306
runway.env_mgr.kbenv (module), 307
runway.env_mgr.tfenv (module), 307
runway.hooks (module), 308
runway.hooks.cleanup_s3 (module), 309
runway.hooks.cleanup_ssm (module), 309
runway.hooks.staticsite (module), 309
runway.hooks.staticsite.auth_at_edge
(module), 313
runway.hooks.staticsite.auth_at_edge.callback_url_retriever
(module), 313
runway.hooks.staticsite.auth_at_edge.client_updater
(module), 313
runway.hooks.staticsite.auth_at_edge.domain_updater
(module), 314
390 Index
runway Documentation, Release 1.18.3
runway.hooks.staticsite.auth_at_edge.lambda_config
(module), 315
runway.hooks.staticsite.auth_at_edge.user_pool_id_retriever
(module), 316
runway.hooks.staticsite.build_staticsite
(module), 309
runway.hooks.staticsite.cleanup (module),
309
runway.hooks.staticsite.upload_staticsite
(module), 310
runway.hooks.staticsite.util (module), 312
runway.http_backport (module), 171
runway.lookups (module), 316
runway.lookups.handlers (module), 317
runway.lookups.handlers.base (module), 59,
317
runway.lookups.handlers.cfn (module), 61,
319
runway.lookups.handlers.ecr (module), 321
runway.lookups.handlers.env (module), 63,
322
runway.lookups.handlers.ssm (module), 63,
323
runway.lookups.handlers.var (module), 64,
324
runway.lookups.registry (module), 316
runway.module (module), 325
runway.module.cdk (module), 326
runway.module.cloudformation (module), 327
runway.module.k8s (module), 327
runway.module.serverless (module), 328
runway.module.staticsite (module), 331
runway.module.terraform (module), 331
runway.path (module), 174
runway.path.Path (module), 51
runway.runway_module_type (module), 176
runway.runway_module_type.RunwayModuleType
(module), 53
runway.s3_util (module), 177
runway.sources (module), 336
runway.sources.git (module), 337
runway.sources.source (module), 337
runway.tests (module), 338
runway.tests.handlers (module), 338
runway.tests.handlers.base (module), 338
runway.tests.handlers.cfn_lint (module),
339
runway.tests.handlers.script (module), 339
runway.tests.handlers.yaml_lint (module),
339
runway.tests.registry (module), 338
runway.util (module), 178
runway.variables (module), 182
RunwayModule (class in runway.module), 325
RunwayModuleNpm (class in runway.module), 325
RunwayModuleType (class in run-
way.runway_module_type), 176
RxrefLookup (class in run-
way.cfngin.lookups.handlers.rxref ), 283
S
s3 (runway.cfngin.config.PackageSources attribute), 251
s3_bucket_location_constraint() (in mod-
ule runway.cfngin.util), 225
s3_bucket_verified() (run-
way.cfngin.context.Context property), 201
s3_conn (runway.cfngin.actions.base.BaseAction at-
tribute), 229
s3_fallback() (in module run-
way.cfngin.providers.aws.default), 287
s3_stack_push() (run-
way.cfngin.actions.base.BaseAction method),
230
S3PackageSource (class in runway.cfngin.config),
251
SafeHaven (class in runway.util), 179
SafeUnicodeLoader (class in run-
way.cfngin.lookups.handlers.file), 280
sanitize_directory_path() (run-
way.sources.source.Source static method),
337
sanitize_git_path() (run-
way.cfngin.util.SourceProcessor method),
228
sanitize_git_path() (runway.sources.git.Git
class method), 337
sanitize_uri_path() (run-
way.cfngin.util.SourceProcessor static
method), 228
save_existing_iam_env_vars() (run-
way.core.providers.aws.AssumeRole method),
302
ScriptHandler (class in run-
way.tests.handlers.script), 339
SEE_OTHER (runway.http_backport.HTTPStatus at-
tribute), 172
select_bucket_region() (in module run-
way.cfngin.hooks.aws_lambda), 262
select_destroy_method() (run-
way.cfngin.providers.aws.default.Provider
method), 295
select_update_method() (run-
way.cfngin.providers.aws.default.Provider
method), 292
Serverless (class in runway.module.serverless), 328
ServerlessOptions (class in run-
way.module.serverless), 330
Index 391
runway Documentation, Release 1.18.3
service_role (runway.cfngin.config.Config at-
tribute), 247, 248
SERVICE_UNAVAILABLE (run-
way.http_backport.HTTPStatus attribute),
173
Session (class in runway.aws_sso_botocore.session),
188
set_archive() (runway.cfngin.util.Extractor
method), 226
set_hook_data() (runway.cfngin.context.Context
method), 202
set_outputs() (runway.cfngin.stack.Stack method),
219
set_ssm_value() (in module run-
way.hooks.staticsite.upload_staticsite), 312
set_status() (runway.cfngin.plan.Step method), 211
set_template_description() (run-
way.cfngin.blueprints.base.Blueprint method),
240
setup_logging() (in module runway.cfngin.logger),
275
setup_parameters() (run-
way.cfngin.blueprints.base.Blueprint method),
239
sha256sum() (in module runway.util), 181
short_id() (runway.cfngin.hooks.docker.data_models.DockerImage
property), 273
should_ensure_cfn_bucket() (in module run-
way.cfngin.actions.build), 231
should_skip (runway.core.components.Module at-
tribute), 301
should_skip() (runway.cfngin.CFNgin method), 197
should_skip() (runway.cfngin.cfngin.CFNgin
method), 199
should_submit() (in module run-
way.cfngin.actions.build), 231
should_update() (in module run-
way.cfngin.actions.build), 231
should_use_docker() (in module run-
way.cfngin.hooks.aws_lambda), 261
should_use_provider() (run-
way.lookups.handlers.cfn.CfnLookup static
method), 320
simplified() (runway.variables.VariableValue prop-
erty), 183
simplified() (run-
way.variables.VariableValueConcatenation
property), 185
simplified() (runway.variables.VariableValueDict
property), 184
simplified() (runway.variables.VariableValueList
property), 184
simplified() (run-
way.variables.VariableValueLookup property),
185
size() (runway.cfngin.dag.DAG method), 257
skip() (runway.cfngin.plan.Step method), 211
skip() (runway.module.serverless.Serverless prop-
erty), 329
skip() (runway.module.terraform.Terraform property),
332
skipped() (runway.cfngin.plan.Step property), 211
SkippedStatus (class in runway.cfngin.status), 220
sls_deploy() (runway.module.serverless.Serverless
method), 329
sls_print() (runway.module.serverless.Serverless
method), 329
sls_remove() (runway.module.serverless.Serverless
method), 329
SOARecord (class in runway.cfngin.util), 223
SOARecordText (class in runway.cfngin.util), 223
Source (class in runway.sources.source), 337
source (runway.cfngin.config.LocalPackageSource at-
tribute), 250
SourceProcessor (class in runway.cfngin.util), 226
SplitLookup (class in run-
way.cfngin.lookups.handlers.split), 284
SsmLookup (class in runway.lookups.handlers.ssm),
323
SsmstoreLookup (class in run-
way.cfngin.lookups.handlers.ssmstore), 285
SSOCredentialFetcher (class in run-
way.aws_sso_botocore.credentials), 186
SSOError, 187
SSOProvider (class in run-
way.aws_sso_botocore.credentials), 187
SSOTokenLoader (class in run-
way.aws_sso_botocore.util), 188
SSOTokenLoadError, 187
Stack (class in runway.cfngin.config), 251
Stack (class in runway.cfngin.stack), 216
stack (runway.cfngin.hooks.base.Hook attribute), 265
stack (runway.cfngin.plan.Step attribute), 210
stack_name (runway.cfngin.config.Stack attribute),
252, 253
stack_name (runway.cfngin.hooks.base.Hook at-
tribute), 265
stack_name() (run-
way.cfngin.lookups.handlers.output.Output
property), 282
stack_name() (run-
way.lookups.handlers.cfn.OutputQuery prop-
erty), 320
stack_policy() (runway.cfngin.stack.Stack prop-
erty), 218
stack_policy_path (runway.cfngin.config.Stack at-
tribute), 252, 253
stack_template_key_name() (in module run-
392 Index
runway Documentation, Release 1.18.3
way.cfngin.util), 228
stack_template_url() (in module run-
way.cfngin.actions.base), 229
stack_template_url() (run-
way.cfngin.actions.base.BaseAction method),
230
StackDidNotChange, 206
StackDoesNotExist, 207
StackDoesNotExist (class in runway.cfngin.status),
220
stacker_bucket (runway.cfngin.config.Config
attribute), 247, 248
stacker_bucket_region (run-
way.cfngin.config.Config attribute), 247,
248
stacker_cache_dir (runway.cfngin.config.Config
attribute), 247, 248
StackFailed, 207
stacks (runway.cfngin.config.Config attribute), 247,
248
StackUpdateBadStatus, 207
StaticSite (class in run-
way.blueprints.staticsite.staticsite), 193
StaticSite (class in runway.module.staticsite), 331
Status (class in runway.cfngin.status), 219
status (runway.cfngin.plan.Step attribute), 210
status() (runway.cfngin.actions.diff.DictValue
method), 233
Step (class in runway.cfngin.plan), 209
step_names() (runway.cfngin.plan.Plan property),
216
steps (runway.cfngin.plan.Graph attribute), 212
steps() (runway.cfngin.plan.Plan property), 216
strip_leading_option_delim() (in module
runway.util), 181
submit() (runway.cfngin.plan.Step method), 211
submitted() (runway.cfngin.plan.Step property), 211
SubmittedStatus (class in runway.cfngin.status),
220
summarize_params_diff() (in module run-
way.cfngin.providers.aws.default), 289
SUPPORTS_VARIABLES (run-
way.config.ConfigComponent attribute),
158, 159
SUPPORTS_VARIABLES (run-
way.config.DeploymentDefinition attribute),
166
SUPPORTS_VARIABLES (run-
way.config.ModuleDefinition attribute), 162
SUPPORTS_VARIABLES (runway.config.TestDefinition
attribute), 167
SWITCHING_PROTOCOLS (run-
way.http_backport.HTTPStatus attribute),
172
sync() (in module run-
way.hooks.staticsite.upload_staticsite), 310
sync_extra_files() (in module run-
way.hooks.staticsite.upload_staticsite), 312
sys_path (runway.cfngin.CFNgin attribute), 196
sys_path (runway.cfngin.cfngin.CFNgin attribute),
198
sys_path (runway.cfngin.config.Config attribute), 247,
248
T
tag (runway.cfngin.config.GitPackageSource attribute),
249
tags (runway.cfngin.config.Config attribute), 247, 248
tags (runway.cfngin.config.Stack attribute), 252, 253
tags() (runway.cfngin.context.Context property), 201
tags() (runway.cfngin.hooks.base.Hook property), 265
tags() (runway.cfngin.hooks.docker.data_models.DockerImage
property), 273
tags() (runway.cfngin.stack.Stack property), 218
tail (runway.cfngin.CFNgin attribute), 196
tail (runway.cfngin.cfngin.CFNgin attribute), 198
tail() (runway.cfngin.providers.aws.default.Provider
method), 292
tail_stack() (run-
way.cfngin.providers.aws.default.Provider
method), 292
TarExtractor (class in runway.cfngin.util), 226
Target (class in runway.cfngin.config), 253
Target (class in runway.cfngin.target), 221
targets (runway.cfngin.config.Config attribute), 247,
248
TarGzipExtractor (class in runway.cfngin.util), 226
Template (class in runway.cfngin.providers.base), 287
template_indent (runway.cfngin.config.Config at-
tribute), 247, 248
template_indent() (runway.cfngin.context.Context
property), 201
template_path (runway.cfngin.config.Stack at-
tribute), 252, 253
TEMPORARY_REDIRECT (run-
way.http_backport.HTTPStatus attribute),
172
termination_protection (run-
way.cfngin.config.Stack attribute), 252, 253
termination_protection (run-
way.cfngin.stack.Stack attribute), 217
Terraform (class in runway.module.terraform), 331
terraform_apply() (run-
way.module.terraform.Terraform method),
333
terraform_block (run-
way.env_mgr.tfenv.TFEnvManager attribute),
308
Index 393
runway Documentation, Release 1.18.3
terraform_destroy() (run-
way.module.terraform.Terraform method),
333
terraform_get() (run-
way.module.terraform.Terraform method),
333
terraform_init() (run-
way.module.terraform.Terraform method),
333
terraform_plan() (run-
way.module.terraform.Terraform method),
333
terraform_workspace_list() (run-
way.module.terraform.Terraform method),
333
terraform_workspace_new() (run-
way.module.terraform.Terraform method),
333
terraform_workspace_select() (run-
way.module.terraform.Terraform method),
333
terraform_workspace_show() (run-
way.module.terraform.Terraform method),
333
TerraformBackendConfig (class in run-
way.module.terraform), 335
TerraformOptions (class in run-
way.module.terraform), 334
test() (runway.core.Runway method), 296
test_generator() (run-
way.cfngin.blueprints.testutil.YamlDirTestGenerator
method), 244
TestDefinition (class in runway.config), 54, 166
TestHandler (class in runway.tests.handlers.base),
338
tf_bin (runway.module.terraform.Terraform attribute),
332
tfenv (runway.module.terraform.Terraform attribute),
332
TFEnvManager (class in runway.env_mgr.tfenv), 308
TfState (class in runway.blueprints.tf_state), 188
ThreadedWalker (class in runway.cfngin.dag), 258
to_dict() (runway.cfngin.blueprints.raw.RawTemplateBlueprint
method), 241
to_dict() (runway.cfngin.plan.Graph method), 214
to_json() (runway.cfngin.blueprints.base.Blueprint
method), 240
to_json() (runway.cfngin.blueprints.raw.RawTemplateBlueprint
method), 241
to_parameter_value() (run-
way.cfngin.blueprints.base.CFNParameter
method), 236
TOO_MANY_REQUESTS (run-
way.http_backport.HTTPStatus attribute),
173
topological_sort() (runway.cfngin.dag.DAG
method), 257
topological_sort() (runway.cfngin.plan.Graph
method), 214
transform() (runway.lookups.handlers.base.LookupHandler
class method), 319
transitive_reduction() (run-
way.cfngin.dag.DAG method), 257
transitive_reduction() (run-
way.cfngin.plan.Graph method), 213
transpose() (runway.cfngin.dag.DAG method), 257
transposed() (runway.cfngin.plan.Graph method),
214
TroposphereType (class in run-
way.cfngin.blueprints.variables.types), 244
type (runway.core.components.Module attribute), 301
TYPE_MAP (runway.runway_module_type.RunwayModuleType
attribute), 177
U
UI (class in runway.cfngin.ui), 222
UnableToExecuteChangeSet, 207
UNAUTHORIZED (runway.http_backport.HTTPStatus at-
tribute), 172
UnauthorizedSSOTokenError, 187
UNAVAILABLE_FOR_LEGAL_REASONS (run-
way.http_backport.HTTPStatus attribute),
173
UnhandledChangeSetStatus, 207
UnknownLookupType, 208
UnlimitedSemaphore (class in runway.cfngin.dag),
258
unlock() (runway.cfngin.ui.UI method), 222
unlock_persistent_graph() (run-
way.cfngin.context.Context method), 202
UNMODIFIED (runway.cfngin.actions.diff.DictValue at-
tribute), 233
UNPROCESSABLE_ENTITY (run-
way.http_backport.HTTPStatus attribute),
173
unregister_lookup_handler() (in module run-
way.cfngin.lookups.registry), 275
unregister_lookup_handler() (in module run-
way.lookups.registry), 316
unregister_test_handler() (in module run-
way.tests.registry), 338
UnresolvedVariable, 208
UnresolvedVariables, 208
UnresolvedVariableValue, 208
UNSUPPORTED_MEDIA_TYPE (run-
way.http_backport.HTTPStatus attribute),
173
394 Index
runway Documentation, Release 1.18.3
update() (in module run-
way.hooks.staticsite.auth_at_edge.client_updater),
313
update() (in module run-
way.hooks.staticsite.auth_at_edge.domain_updater),
314
update_args() (run-
way.module.serverless.ServerlessOptions
method), 330
update_context() (run-
way.cfngin.hooks.docker.hook_data.DockerHookData
method), 274
update_env_vars_with_tf_var_values() (in
module runway.module.terraform), 331
update_paths_and_config() (run-
way.cfngin.util.SourceProcessor method),
227
update_record_set() (run-
way.cfngin.hooks.acm.Certificate method),
260
update_ssm_hash() (in module run-
way.hooks.staticsite.upload_staticsite), 310
update_stack() (run-
way.cfngin.providers.aws.default.Provider
method), 293
update_stack() (run-
way.cfngin.providers.base.BaseProvider
method), 287
update_termination_protection() (run-
way.cfngin.providers.aws.default.Provider
method), 293
UPGRADE_REQUIRED (run-
way.http_backport.HTTPStatus attribute),
173
upload() (in module runway.s3_util), 177
upload_lambda_functions() (in module run-
way.cfngin.hooks.aws_lambda), 262
upload_to_s3() (runway.cfngin.context.Context
property), 201
uppercase_first_letter() (in module run-
way.cfngin.util), 224
uri (runway.cfngin.config.GitPackageSource attribute),
249
uri() (runway.cfngin.hooks.docker.data_models.DockerImage
property), 273
URI_TEMPLATE (run-
way.cfngin.hooks.docker.data_models.ElasticContainerRegistry
attribute), 272
use_async (runway.core.components.Deployment at-
tribute), 300
use_async (runway.core.components.Module at-
tribute), 301
use_concurrent() (runway.context.Context prop-
erty), 171
use_embedded_pkgs() (in module runway.util), 182
use_latest (runway.cfngin.config.S3PackageSource
attribute), 251
use_npm_ci() (in module runway.module), 326
USE_PROXY (runway.http_backport.HTTPStatus at-
tribute), 172
UsePreviousParameterValue (class in run-
way.cfngin.actions.build), 231
V
validate() (runway.cfngin.config.Config method),
248
validate() (runway.cfngin.dag.DAG method), 257
validate_account_credentials() (run-
way.core.components.Deployment method),
300
validate_allowed_values() (in module run-
way.cfngin.blueprints.base), 237
validate_class_path() (run-
way.cfngin.config.Stack method), 253
validate_parameters() (run-
way.cfngin.config.Stack method), 253
validate_stack_source() (run-
way.cfngin.config.Stack static method), 253
validate_stacker_bucket() (run-
way.cfngin.config.Config method), 248
validate_stacker_bucket_region() (run-
way.cfngin.config.Config method), 248
validate_stacker_cache_dir() (run-
way.cfngin.config.Config method), 248
validate_stacks() (runway.cfngin.config.Config
method), 248
validate_template_path() (run-
way.cfngin.config.Stack method), 253
validate_variable_type() (in module run-
way.cfngin.blueprints.base), 237
ValidatorError, 209
value() (runway.variables.Variable property), 182
value() (runway.variables.VariableValue property),
183
value() (runway.variables.VariableValueConcatenation
property), 185
value() (runway.variables.VariableValueDict prop-
erty), 184
value() (runway.variables.VariableValueList prop-
erty), 184
value() (runway.variables.VariableValueLiteral prop-
erty), 183
value() (runway.variables.VariableValueLookup prop-
erty), 186
Variable (class in runway.variables), 182
VARIABLES (runway.blueprints.k8s.k8s_master.Cluster
attribute), 190
Index 395
runway Documentation, Release 1.18.3
VARIABLES (runway.blueprints.k8s.k8s_workers.NodeGroup
attribute), 190
VARIABLES (runway.blueprints.staticsite.auth_at_edge.AuthAtEdge
attribute), 191
VARIABLES (runway.blueprints.staticsite.dependencies.Dependencies
attribute), 192
VARIABLES (runway.blueprints.staticsite.staticsite.StaticSite
attribute), 193
VARIABLES (runway.blueprints.tf_state.TfState at-
tribute), 189
variables (runway.cfngin.config.Stack attribute), 253
variables (runway.cfngin.stack.Stack attribute), 217
VariablesDefinition (class in runway.config), 55,
167
VariableTypeRequired, 209
VariableValue (class in runway.variables), 183
VariableValueConcatenation (class in run-
way.variables), 185
VariableValueDict (class in runway.variables),
184
VariableValueList (class in runway.variables),
184
VariableValueLiteral (class in run-
way.variables), 183
VariableValueLookup (class in runway.variables),
185
VARIANT_ALSO_NEGOTIATES (run-
way.http_backport.HTTPStatus attribute),
173
VarLookup (class in runway.lookups.handlers.var),
324
verbose() (runway.core.components.DeployEnvironment
property), 298
verify_kb_release() (in module run-
way.env_mgr.kbenv), 307
version() (runway.cfngin.blueprints.base.Blueprint
property), 240
version() (runway.cfngin.blueprints.raw.RawTemplateBlueprint
property), 242
version_file (runway.env_mgr.tfenv.TFEnvManager
attribute), 308
versions_dir (runway.env_mgr.EnvManager at-
tribute), 306
W
waf_name_specified() (run-
way.blueprints.staticsite.staticsite.StaticSite
property), 193
wait_till_change_set_complete() (in mod-
ule runway.cfngin.providers.aws.default), 289
walk() (in module runway.cfngin.dag), 258
walk() (runway.cfngin.dag.DAG method), 258
walk() (runway.cfngin.dag.ThreadedWalker method),
258
walk() (runway.cfngin.plan.Graph method), 213
walk() (runway.cfngin.plan.Plan method), 215
warn() (in module runway.hooks.staticsite.cleanup),
309
warn_on_boto_env_vars() (in module run-
way.module), 326
watch_func (runway.cfngin.plan.Step attribute), 210
which() (in module runway.util), 182
write() (in module run-
way.hooks.staticsite.auth_at_edge.lambda_config),
315
X
XrefLookup (class in run-
way.cfngin.lookups.handlers.xref ), 286
Y
yaml_codec() (in module run-
way.cfngin.lookups.handlers.file), 281
yaml_dirs() (runway.cfngin.blueprints.testutil.YamlDirTestGenerator
property), 243
yaml_dump() (in module run-
way.cfngin.awscli_yamlhelper), 197
yaml_filename() (run-
way.cfngin.blueprints.testutil.YamlDirTestGenerator
property), 244
yaml_parse() (in module run-
way.cfngin.awscli_yamlhelper), 197
yaml_to_ordered_dict() (in module run-
way.cfngin.util), 224
YamlDirTestGenerator (class in run-
way.cfngin.blueprints.testutil), 243
YamlDumper (class in runway.util), 180
YamllintHandler (class in run-
way.tests.handlers.yaml_lint), 339
Z
zip_and_upload() (in module run-
way.hooks.staticsite.build_staticsite), 309
ZipExtractor (class in runway.cfngin.util), 226
396 Index