Commands

deploy

Used to deploy modules with Runway.

When run, the environment is determined from the current git branch unless ignore_git_branch: true is specified in the Runway config file. If the DEPLOY_ENVIRONMENT environment variable is set, it’s value will be used. If neither the git branch or environment variable are available, the directory name is used. The environment identified here is used to determine the env/config files to use. It is also used with options defined in the Runway config file such as assume_role, account_id, etc. See Runway Config for details on these options.

The user will be prompted to select which deployment(s) and module(s) to process unless there is only one deployment and/or module, the environment variable CI is set, or the --tag <tag>... option provided is used. In which case, the deployment(s) and module(s) will be processed in sequence, in the order they are defined.

Options

--tag <tag>...

Select modules for processing by tag or tags. This option can be specified
more than once to build a list of tags that are treated as “AND”.
(ex. --tag <tag1> --tag <tag2> would select all modules with BOTH tags).

Example

# manually select deployment(s) and module(s)
$ runway deploy

# select all modules with the tag 'app:example' AND 'my-tag'
$ runway deploy --tag app:example --tag my-tag

# process all deployment(s) and module(s)
$ CI=1 runway deploy

destroy

Used to destroy modules with Runway.

Danger

Use extreme caution when using with CI or --tag <tag>.... You will not be prompted before deletion. All modules (or those selected by tag) for the current environment will be irrecoverably deleted.

When run, the environment is determined from the current git branch unless ignore_git_branch: true is specified in the Runway config file. If the DEPLOY_ENVIRONMENT environment variable is set, it’s value will be used. If neither the git branch or environment variable are available, the directory name is used. The environment identified here is used to determine the env/config files to use. It is also used with options defined in the Runway config file such as assume_role, account_id, etc. See Runway Config for details on these options.

The user will be prompted to select which deployment(s) and module(s) to process unless there is only one deployment and/or module, the environment variable CI is set, or the --tag <tag>... option provided is used. In which case, the deployment(s) and module(s) will be processed in sequence, in reverse of the order they are defined.

Options

--tag <tag>...

Select modules for processing by tag or tags. This option can be specified
more than once to build a list of tags that are treated as “AND”.
(ex. --tag <tag1> --tag <tag2> would select all modules with BOTH tags).

Example

# manually select deployment(s) and module(s)
$ runway destroy

# select all modules with the tag 'app:example' AND 'my-tag'
$ runway destroy --tag app:example --tag my-tag

# process all deployment(s) and module(s)
$ CI=1 runway destroy

dismantle

Alias of destroy.

envvars

Output runway.yml-defined environment variables.

OS environment variables can be set in runway.yml for different Runway environments (e.g. dev & prod KUBECONFIG values). The envvars command allows access to these values for use outside of Runway.

Example

$ eval "$(runway envvars)"

gen-sample

Generate a sample Runway module directory.

The sample module is created in the current directory. If a directory already exists with the name it tries to use, it will not create the sample directory.

Available Samples

Name

Description

cdk-csharp

AWS CDK module using C#

cdk-py

AWS CDK module using Python

cdk-tsc

AWS CDK module using TypeScript

cfn

CloudFormation module stack with S3 bucket & DDB table (perfect for storing Terraform backend state)

k8s-cfn-repo

Kubernetes module EKS cluster & sample app using CloudFormation

k8s-tf-repo

Kubernetes module EKS cluster & sample app using Terraform

sls-py

Serverless Framework module using Python

sls-tsc

Serverless Framework module using TypeScript

stacker

Troposphere/Stacker module identical the cfn sample but with the template written in python

static-angular

`StaticSite`_ module of a StaticSite and the Angular framework

static-react

`StaticSite`_ module of a StaticSite and the React framework

tf

Terraform module

Example

# create a "sampleapp.cfn" sample module directory
$ runway gen-sample cfn

# create a "runway-sample-tfstate.cfn" sample module directory
$ runway gen-sample stacker

# create a "sampleapp.sls" sample module directory
$ runway gen-sample sls-py

init

Creates a sample Runway Config File in the current directory.

If a Runway config file is already present, no action is taken.

Example

$ runway init

Sample Runway Config File

---
# See full syntax at https://docs.onica.com/projects/runway/en/latest/
deployments:
  - modules:
      - nameofmyfirstmodulefolder
      - nameofmysecondmodulefolder
      # - etc...
    regions:
      - us-east-1

kbenv

Manage versions and execute Kubernetes commands.

Runway’s built-in kubectl version management ensure the correct version is used for a given environment. Define a .kubectl-version file in your k8s module and that version will be automatically downloaded & used during Runway operations.

The tfenv subcommand supplements this functionality in 2 ways:

  • The install option will download kubectl (e.g. for pre-seeding a deployment system)

  • The run option will execute arbitrary kubectl commands

Examples

$ runway kbenv install 1.14.5
$ runway kbenv install  # retrieves version from .kubectl-version

$ runway kbenv run -- get namespace

plan

Used to plan actions by comparing what is live and what is defined locally.

Note

Currently only supported for AWS CDK, CloudFormation, Terraform, and Troposphere.

When run, the environment is determined from the current git branch unless ignore_git_branch: true is specified in the Runway config file. If the DEPLOY_ENVIRONMENT environment variable is set, it’s value will be used. If neither the git branch or environment variable are available, the directory name is used. The environment identified here is used to determine the env/config files to use. It is also used with options defined in the Runway config file such as assume_role, account_id, etc. See Runway Config for details on these options.

The user will be prompted to select which deployment(s) and module(s) to process unless there is only one deployment and/or module, the environment variable CI is set, or the --tag <tag>... option provided is used. In which case, the deployment(s) and module(s) will be processed in sequence, in the order they are defined.

Options

--tag <tag>...

Select modules for processing by tag or tags. This option can be specified
more than once to build a list of tags that are treated as “AND”.
(ex. --tag <tag1> --tag <tag2> would select all modules with BOTH tags).

Equivalent To

There are the native commands that are used:

Example

$ runway plan

preflight

Alias of test.

run-aws

Execute aws cli commands using the version bundled with Runway.

This command gives access to the aws CLI when it might not otherwise be installed (e.g. when using the bundled version of Runway).

Example

$ runway run-aws -- s3 ls

run-python

Execute a python script using a bundled copy of python.

By using this command Runway can execute actions using a bundled copy of python without requiring python to be installed on a system. This is only applicable when installing the bundled version of Runway, not from PyPI (pip install runway). When installed from PyPI, the system’s python is used.

Example

$ runway run-python my-script.py

run-stacker

Execute the “shimmed” Stacker aka Runway CFNgin.

This command allows direct access to Runway’s CloudFormation management tool.

Example

$ runway run-stacker -- build example.env example.yaml

takeoff

Alias of deploy.

taxi

Alias of plan.

test

Execute tests as defined in the Runway Config File.

If one of the tests fails, the command will exit unless the required option is set to false for the failing test. If it is not required, the next test will be executed.

References

tfenv

Manage versions and execute Terraform commands.

Runway’s built-in Terraform version management allows for long-term stability of Terraform executions. Define a .terraform-version file in your Terraform module and that version will be automatically downloaded & used during Runway operations.

The tfenv subcommand supplements this functionality in 2 ways:

  • The install option will download Terraform (e.g. for pre-seeding a deployment system)

  • The run option will execute arbitrary Terraform commands

Examples

$ runway tfenv install 0.12.1
$ runway tfenv install  # retrieves version from .terraform-version

$ runway tfenv run -- workspace list

whichenv

Identify the current environment and print it to the terminal.

When run, the environment is determined from the current git branch unless ignore_git_branch: true is specified in the Runway config file. If the DEPLOY_ENVIRONMENT environment variable is set, it’s value will be used. If neither the git branch or environment variable are available, the directory name is used. The environment identified here is used to determine the env/config files to use. It is also used with options defined in the Runway config file such as assume_role, account_id, etc. See Runway Config for details on these options.

Example

$ runway whichenv
common