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. |
|
The name of the lookup you wish to use (e.g.
|
The separator between lookup name a query. |
|
|
The value the lookup will be looking for. (e.g.
|
|
The separator between a query and optional arguments. |
|
An argument passed to a lookup. Multiple
arguments can be passed to a lookup by
separating them with a comma ( |
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.
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 oftroposphere.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
, andtuple
will become a comma delimited listdict
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}
Built-in Lookups¶
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
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
stacks:
my-stack:
variables:
SomeParameter: ${cfn AnotherStack.OutputName}
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
deployments:
- modules:
- path: example.cfn
parameters:
ecr_password: ${ecr login-password}
...
pre_build:
- path: runway.cfngin.hooks.docker.login
args:
password: ${ecr login-password}
...
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 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.
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}
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}
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}