runway.cfngin.lookups.handlers.kms module

AWS KMS lookup.

class runway.cfngin.lookups.handlers.kms.KmsLookup[source]

Bases: runway.lookups.handlers.base.LookupHandler

AWS KMS lookup.

classmethod handle(value: str, context: CfnginContext, **_: Any) → str[source]

Decrypt the specified value with a master key in KMS.

Parameters

  • value – Parameter(s) given to this lookup.

  • context – Context instance.

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
classmethod dependencies(_LookupHandler__lookup_query: VariableValue) → Set[str]

Calculate any dependencies required to perform this lookup.

Note that lookup_query may not be (completely) resolved at this time.

classmethod format_results(value: Any, get: Optional[str] = None, load: Optional[str] = None, transform: Optional[str] = None, **kwargs: Any) → Any

Format results to be returned by a lookup.

Parameters

  • value – Data collected by the Lookup.

  • get – Nested value to get from a dictionary like object.

  • load – Parser to use to parse a formatted string before the get and transform method.

  • transform – 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 load(value: Any, parser: Optional[str] = None, **kwargs: Any) → Any

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 parse(value: str) → Tuple[str, Dict[str, str]]

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 transform(value: Any, *, to_type: Optional[str] = 'str', **kwargs: Any) → Any

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.