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:

cdk diff - https://docs.aws.amazon.com/cdk/latest/guide/tools.html
stacker diff - https://stacker.readthedocs.io/en/stable/commands.html#diff
terraform plan - https://www.terraform.io/docs/commands/plan.html

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