stacker.lookups.handlers package

Submodules

stacker.lookups.handlers.ami module

class stacker.lookups.handlers.ami.AmiLookup

Bases: stacker.lookups.handlers.LookupHandler

classmethod handle(value, provider, **kwargs)

Fetch the most recent AMI Id using a filter

For example:

${ami [<region>@]owners:self,account,amazon name_regex:serverX-[0-9]+ architecture:x64,i386}

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

Any other arguments specified are sent as filters to the aws api For example, “architecture:x86_64” will add a filter

exception stacker.lookups.handlers.ami.ImageNotFound(search_string)

Bases: exceptions.Exception

stacker.lookups.handlers.default module

class stacker.lookups.handlers.default.DefaultLookup

Bases: stacker.lookups.handlers.LookupHandler

classmethod handle(value, **kwargs)

Use a value from the environment or fall back to a default if the

environment doesn’t contain the variable.

Format of value:

<env_var>::<default value>

For 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 the returned value.

This allows defaults to be set at the config file level.

stacker.lookups.handlers.dynamodb module

class stacker.lookups.handlers.dynamodb.DynamodbLookup

Bases: stacker.lookups.handlers.LookupHandler

classmethod handle(value, **kwargs)

Get a value from a dynamodb table

dynamodb field types should be in the following format:

[<region>:]<tablename>@<primarypartionkey>:<keyvalue>.<keyvalue>…

Note: The region is optional, and defaults to the environment’s AWS_DEFAULT_REGION if not specified.

stacker.lookups.handlers.envvar module

class stacker.lookups.handlers.envvar.EnvvarLookup

Bases: stacker.lookups.handlers.LookupHandler

classmethod handle(value, **kwargs)

Retrieve an environment variable.

For example:

# In stacker 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 stacker (NOTE: the path should be relative to the stacker config file):

conf_key: ${envvar file://envvar_value.txt}

# Both of the above would resolve to conf_key: ENV_VALUE

stacker.lookups.handlers.file module

class stacker.lookups.handlers.file.FileLookup

Bases: stacker.lookups.handlers.LookupHandler

classmethod handle(value, **kwargs)

Translate a filename into the file contents.

Fields should use the following format:

<codec>:<path>

For example:

# We've written a file to /some/path:
$ echo "hello there" > /some/path

# In stacker 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

• 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 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:

  { "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:

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

class stacker.lookups.handlers.file.SafeUnicodeLoader(stream)

Bases: yaml.loader.SafeLoader

construct_yaml_str(node)

stacker.lookups.handlers.file.json_codec(raw, parameterized=False)

stacker.lookups.handlers.file.parameterized_codec(raw, b64)

Parameterize a string, possibly encoding it as Base64 afterwards

Parameters:

• raw (str | bytes) – 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

stacker.lookups.handlers.file.yaml_codec(raw, parameterized=False)

stacker.lookups.handlers.hook_data module

class stacker.lookups.handlers.hook_data.HookDataLookup

Bases: stacker.lookups.handlers.LookupHandler

classmethod handle(value, context, **kwargs)

Returns the value of a key for a given hook in hook_data.

Format of value:

<hook_name>::<key>

stacker.lookups.handlers.kms module

class stacker.lookups.handlers.kms.KmsLookup

Bases: stacker.lookups.handlers.LookupHandler

classmethod handle(value, **kwargs)

Decrypt the specified value with a master key in KMS.

kmssimple field types should be in the following format:

[<region>@]<base64 encrypted value>

Note: The region is optional, and defaults to the environment’s AWS_DEFAULT_REGION if not specified.

For example:

# We use the aws cli to get the encrypted value for the string # “PASSWORD” using the master key called “myStackerKey” in # us-east-1 $ aws –region us-east-1 kms encrypt –key-id alias/myStackerKey –plaintext “PASSWORD” –output text –query CiphertextBlob

CiD6bC8t2Y<…encrypted blob…>

# In stacker 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 stacker (NOTE: the path should be relative to the stacker config file):

conf_key: ${kms file://kms_value.txt}

# Both of the above would resolve to conf_key: PASSWORD

stacker.lookups.handlers.output module

class stacker.lookups.handlers.output.Output(stack_name, output_name)

Bases: tuple

output_name

Alias for field number 1

stack_name

Alias for field number 0

class stacker.lookups.handlers.output.OutputLookup

Bases: stacker.lookups.handlers.LookupHandler

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 – Parameter(s) given to this lookup

:type lookup_data VariableValue :return: Set of stack names (str) this lookup depends on :rtype: set

classmethod handle(value, context=None, **kwargs)

Fetch an output from the designated stack.

Parameters:

• value (str) – string with the following format: <stack_name>::<output_name>, ie. some-stack::SomeOutput
• context (stacker.context.Context) – stacker context

Returns:

output from the specified stack

Return type:

str

stacker.lookups.handlers.output.deconstruct(value)

stacker.lookups.handlers.rxref module

Handler for fetching outputs from fully qualified stacks.

The output handler supports fetching outputs from stacks created within a sigle config file. Sometimes it’s useful to fetch outputs from stacks created outside of the current config file. rxref supports this by not using the stacker.context.Context to expand the fqn of the stack.

Example

conf_value: ${rxref

some-relative-fully-qualified-stack-name::SomeOutputName}

class stacker.lookups.handlers.rxref.RxrefLookup

Bases: stacker.lookups.handlers.LookupHandler

classmethod handle(value, provider=None, context=None, **kwargs)

Fetch an output from the designated stack.

Parameters:

• value (str) – string with the following format: <stack_name>::<output_name>, ie. some-stack::SomeOutput
• provider (stacker.provider.base.BaseProvider) – subclass of the base provider
• context (stacker.context.Context) – stacker context

Returns:

output from the specified stack

Return type:

str

stacker.lookups.handlers.split module

class stacker.lookups.handlers.split.SplitLookup

Bases: stacker.lookups.handlers.LookupHandler

classmethod handle(value, **kwargs)

Split the supplied string on the given delimiter, providing a list.

Format of value:

<delimiter>::<value>

For 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}}

stacker.lookups.handlers.ssmstore module

class stacker.lookups.handlers.ssmstore.SsmstoreLookup

Bases: stacker.lookups.handlers.LookupHandler

classmethod handle(value, **kwargs)

Retrieve (and decrypt if applicable) a parameter from AWS SSM Parameter Store.

ssmstore field types should be in the following format:

[<region>@]ssmkey

Note: The region is optional, and defaults to us-east-1 if not given.

For example:

# In stacker 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 stacker (NOTE: the path should be relative to the stacker config file):

conf_key: ${ssmstore file://ssmstore_value.txt}

# Both of the above would resolve to conf_key: PASSWORD

stacker.lookups.handlers.xref module

Handler for fetching outputs from fully qualified stacks.

The output handler supports fetching outputs from stacks created within a sigle 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 stacker.context.Context to expand the fqn of the stack.

Example

conf_value: ${xref some-fully-qualified-stack-name::SomeOutputName}

class stacker.lookups.handlers.xref.XrefLookup

Bases: stacker.lookups.handlers.LookupHandler

classmethod handle(value, provider=None, **kwargs)

Fetch an output from the designated stack.

Parameters:

• value (str) – string with the following format: <stack_name>::<output_name>, ie. some-stack::SomeOutput
• provider (stacker.provider.base.BaseProvider) – subclass of the base provider

Returns:

output from the specified stack

Return type:

str

Module contents

class stacker.lookups.handlers.LookupHandler

Bases: object

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 – Parameter(s) given to this lookup

:type lookup_data VariableValue :return: Set of stack names (str) this lookup depends on :rtype: set

classmethod handle(value, context, provider)

Perform the actual lookup

Parameters:

• value (str) – Parameter(s) given to this lookup
• context –
• provider –

Returns:

Looked-up value

Return type:

str