stacker package

Subpackages

Submodules

stacker.context module

class stacker.context.Context(environment=None, stack_names=None, config=None, force_stacks=None)[source]

Bases: future.types.newobject.newobject

The context under which the current stacks are being executed.

The stacker Context is responsible for translating the values passed in via the command line and specified in the config to Stack objects.

Parameters:
  • environment (dict) – A dictionary used to pass in information about the environment. Useful for templating.
  • stack_names (list) – A list of stack_names to operate on. If not passed, usually all stacks defined in the config will be operated on.
  • config (stacker.config.Config) – The stacker configuration being operated on.
  • force_stacks (list) – A list of stacks to force work on. Used to work on locked stacks.
bucket_name
get_fqn(name=None)[source]

Return the fully qualified name of an object within this context.

If the name passed already appears to be a fully qualified name, it will be returned with no further processing.

get_stack(name)[source]
get_stacks()[source]

Get the stacks for the current action.

Handles configuring the stacker.stack.Stack objects that will be used in the current action.

Returns:a list of stacker.stack.Stack objects
Return type:list
get_stacks_dict()[source]
get_targets()[source]

Returns the named targets that are specified in the config.

Returns:a list of stacker.target.Target objects
Return type:list
mappings
namespace
namespace_delimiter
set_hook_data(key, data)[source]

Set hook data for the given key.

Parameters:
  • key (str) – The key to store the hook data in.
  • data (collections.Mapping) – A dictionary of data to store, as returned from a hook.
tags
template_indent
upload_templates_to_s3
stacker.context.get_fqn(base_fqn, delimiter, name=None)[source]

Return the fully qualified name of an object within this context.

If the name passed already appears to be a fully qualified name, it will be returned with no further processing.

stacker.environment module

stacker.environment.parse_environment(raw_environment)[source]

stacker.exceptions module

exception stacker.exceptions.CancelExecution[source]

Bases: exceptions.Exception

Exception raised when we want to cancel executing the plan.

exception stacker.exceptions.ChangesetDidNotStabilize(change_set_id)[source]

Bases: exceptions.Exception

exception stacker.exceptions.FailedVariableLookup(variable_name, lookup, error, *args, **kwargs)[source]

Bases: exceptions.Exception

exception stacker.exceptions.GraphError(exception, stack, dependency)[source]

Bases: exceptions.Exception

Raised when the graph is invalid (e.g. acyclic dependencies)

exception stacker.exceptions.ImproperlyConfigured(cls, error, *args, **kwargs)[source]

Bases: exceptions.Exception

exception stacker.exceptions.InvalidConfig(errors)[source]

Bases: exceptions.Exception

exception stacker.exceptions.InvalidLookupCombination(lookup, lookups, value, *args, **kwargs)[source]

Bases: exceptions.Exception

exception stacker.exceptions.InvalidUserdataPlaceholder(blueprint_name, exception_message, *args, **kwargs)[source]

Bases: exceptions.Exception

exception stacker.exceptions.MissingEnvironment(key, *args, **kwargs)[source]

Bases: exceptions.Exception

exception stacker.exceptions.MissingParameterException(parameters, *args, **kwargs)[source]

Bases: exceptions.Exception

exception stacker.exceptions.MissingVariable(blueprint_name, variable_name, *args, **kwargs)[source]

Bases: exceptions.Exception

exception stacker.exceptions.OutputDoesNotExist(stack_name, output, *args, **kwargs)[source]

Bases: exceptions.Exception

exception stacker.exceptions.PlanFailed(failed_steps, *args, **kwargs)[source]

Bases: exceptions.Exception

exception stacker.exceptions.StackDidNotChange[source]

Bases: exceptions.Exception

Exception raised when there are no changes to be made by the provider.

exception stacker.exceptions.StackDoesNotExist(stack_name, *args, **kwargs)[source]

Bases: exceptions.Exception

exception stacker.exceptions.StackUpdateBadStatus(stack_name, stack_status, reason, *args, **kwargs)[source]

Bases: exceptions.Exception

exception stacker.exceptions.UnableToExecuteChangeSet(stack_name, change_set_id, execution_status)[source]

Bases: exceptions.Exception

exception stacker.exceptions.UnhandledChangeSetStatus(stack_name, change_set_id, status, status_reason)[source]

Bases: exceptions.Exception

exception stacker.exceptions.UnknownLookupType(lookup, *args, **kwargs)[source]

Bases: exceptions.Exception

exception stacker.exceptions.UnresolvedVariable(blueprint_name, variable, *args, **kwargs)[source]

Bases: exceptions.Exception

exception stacker.exceptions.UnresolvedVariables(blueprint_name, *args, **kwargs)[source]

Bases: exceptions.Exception

exception stacker.exceptions.ValidatorError(variable, validator, value, exception=None)[source]

Bases: exceptions.Exception

Used for errors raised by custom validators of blueprint variables.

exception stacker.exceptions.VariableTypeRequired(blueprint_name, variable_name, *args, **kwargs)[source]

Bases: exceptions.Exception

stacker.plan module

class stacker.plan.Graph(steps=None, dag=None)[source]

Bases: future.types.newobject.newobject

Graph represents a graph of steps.

The Graph helps organize the steps needed to execute a particular action for a set of stacker.stack.Stack objects. When initialized with a set of steps, it will first build a Directed Acyclic Graph from the steps and their dependencies.

Example:

>>> dag = DAG()
>>> a = Step("a", fn=build)
>>> b = Step("b", fn=build)
>>> dag.add_step(a)
>>> dag.add_step(b)
>>> dag.connect(a, b)
Parameters:
  • steps (list) – an optional list of Step objects to execute.
  • dag (stacker.dag.DAG) – an optional stacker.dag.DAG object. If one is not provided, a new one will be initialized.
add_step(step)[source]
connect(step, dep)[source]
downstream(step_name)[source]

Returns the direct dependencies of the given step

filtered(step_names)[source]

Returns a “filtered” version of this graph.

to_dict()[source]
topological_sort()[source]
transitive_reduction()[source]
transposed()[source]

Returns a “transposed” version of this graph. Useful for walking in reverse.

walk(walker, walk_func)[source]
class stacker.plan.Plan(description, graph)[source]

Bases: future.types.newobject.newobject

A convenience class for working on a Graph. :param description: description of the plan. :type description: str :param graph: a graph of steps. :type graph: Graph

dump(directory, context, provider=None)[source]
execute(*args, **kwargs)[source]

Walks each step in the underlying graph, and raises an exception if any of the steps fail.

Raises:PlanFailed – Raised if any of the steps fail.
keys()[source]
outline(level=20, message='')[source]

Print an outline of the actions the plan is going to take. The outline will represent the rough ordering of the steps that will be taken. :param level: a valid log level that should be used to log

the outline
Parameters:message (str, optional) – a message that will be logged to the user after the outline has been logged.
step_names
steps
walk(walker)[source]

Walks each step in the underlying graph, in topological order.

Parameters:walker (func) – a walker function to be passed to stacker.dag.DAG to walk the graph.
class stacker.plan.Step(stack, fn, watch_func=None)[source]

Bases: future.types.newobject.newobject

State machine for executing generic actions related to stacks. :param stack: the stack associated

with this step
Parameters:
  • fn (func) – the function to run to execute the step. This function will be ran multiple times until the step is “done”.
  • watch_func (func) – an optional function that will be called to “tail” the step action.
complete()[source]

A shortcut for set_status(COMPLETE)

completed

Returns True if the step is in a COMPLETE state.

done

Returns True if the step is finished (either COMPLETE, SKIPPED or FAILED)

failed

Returns True if the step is in a FAILED state.

name
ok

Returns True if the step is finished (either COMPLETE or SKIPPED)

required_by
requires
run()[source]

Runs this step until it has completed successfully, or been skipped.

set_status(status)[source]

Sets the current step’s status. :param status: The status to set the

step to.
skip()[source]

A shortcut for set_status(SKIPPED)

skipped

Returns True if the step is in a SKIPPED state.

submit()[source]

A shortcut for set_status(SUBMITTED)

submitted

Returns True if the step is SUBMITTED, COMPLETE, or SKIPPED.

stacker.plan.build_graph(steps)[source]

Builds a graph of steps. :param steps: a list of Step objects to execute. :type steps: list

stacker.plan.build_plan(description, graph, targets=None, reverse=False)[source]

Builds a plan from a list of steps. :param description: an arbitrary string to

describe the plan.
Parameters:
  • graph (Graph) – a list of Graph to execute.
  • targets (list) – an optional list of step names to filter the graph to. If provided, only these steps, and their transitive dependencies will be executed. If no targets are specified, every node in the graph will be executed.
  • reverse (bool) – If provided, the graph will be walked in reverse order (dependencies last).
stacker.plan.log_step(step)[source]

stacker.session_cache module

stacker.session_cache.get_session(region, profile=None)[source]

Creates a boto3 session with a cache

Parameters:
  • region (str) – The region for the session
  • profile (str) – The profile for the session
Returns:

A boto3 session with

credential caching

Return type:

boto3.session.Session

stacker.stack module

class stacker.stack.Stack(definition, context, variables=None, mappings=None, locked=False, force=False, enabled=True, protected=False)[source]

Bases: future.types.newobject.newobject

Represents gathered information about a stack to be built/updated.

Parameters:
  • definition (stacker.config.Stack) – A stack definition.
  • context (stacker.context.Context) – Current context for building the stack.
  • mappings (dict, optional) – Cloudformation mappings passed to the blueprint.
  • locked (bool, optional) – Whether or not the stack is locked.
  • force (bool, optional) – Whether to force updates on this stack.
  • enabled (bool, optional) – Whether this stack is enabled
all_parameter_definitions

Return a list of all parameters in the blueprint/template.

blueprint
parameter_values

Return all CloudFormation Parameters for the stack.

CloudFormation Parameters can be specified via Blueprint Variables with a stacker.blueprints.variables.types.CFNType type.

Returns:dictionary of <parameter name>: <parameter value>.
Return type:dict
required_by
required_parameter_definitions

Return all the required CloudFormation Parameters for the stack.

requires
resolve(context, provider)[source]

Resolve the Stack variables.

This resolves the Stack variables and then prepares the Blueprint for rendering by passing the resolved variables to the Blueprint.

Parameters:
  • context (stacker.context.Context) – stacker context
  • provider (stacker.provider.base.BaseProvider) – subclass of the base provider
set_outputs(outputs)[source]
stack_policy
tags

Returns the tags that should be set on this stack. Includes both the global tags, as well as any stack specific tags or overrides.

Returns:dictionary of tags
Return type:dict

stacker.status module

class stacker.status.CompleteStatus(reason=None)[source]

Bases: stacker.status.Status

class stacker.status.DidNotChangeStatus(reason=None)[source]

Bases: stacker.status.SkippedStatus

reason = 'nochange'
class stacker.status.FailedStatus(reason=None)[source]

Bases: stacker.status.Status

class stacker.status.NotSubmittedStatus(reason=None)[source]

Bases: stacker.status.SkippedStatus

reason = 'disabled'
class stacker.status.NotUpdatedStatus(reason=None)[source]

Bases: stacker.status.SkippedStatus

reason = 'locked'
class stacker.status.PendingStatus(reason=None)[source]

Bases: stacker.status.Status

class stacker.status.SkippedStatus(reason=None)[source]

Bases: stacker.status.Status

class stacker.status.StackDoesNotExist(reason=None)[source]

Bases: stacker.status.SkippedStatus

reason = 'does not exist in cloudformation'
class stacker.status.Status(name, code, reason=None)[source]

Bases: future.types.newobject.newobject

class stacker.status.SubmittedStatus(reason=None)[source]

Bases: stacker.status.Status

stacker.tokenize_userdata module

stacker.tokenize_userdata.cf_tokenize(s)[source]

Parses UserData for Cloudformation helper functions.

http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/user-data.html http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference.html http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/quickref-cloudformation.html#scenario-userdata-base64

It breaks apart the given string at each recognized function (see HELPERS) and instantiates the helper function objects in place of those.

Returns a list of parts as a result. Useful when used with Join() and Base64() CloudFormation functions to produce user data.

ie: Base64(Join(‘’, cf_tokenize(userdata_string)))

stacker.util module

class stacker.util.Extractor(archive=None)[source]

Bases: future.types.newobject.newobject

Base class for extractors.

static extension()[source]

Serve as placeholder; override this in subclasses.

set_archive(dir_name)[source]

Update archive filename to match directory name & extension.

Parameters:dir_name (string) – Archive directory name
class stacker.util.SOARecord(record)[source]

Bases: future.types.newobject.newobject

Represents an SOA record.

class stacker.util.SOARecordText(record_text)[source]

Bases: future.types.newobject.newobject

Represents the actual body of an SOARecord.

class stacker.util.SourceProcessor(sources, stacker_cache_dir=None)[source]

Bases: future.types.newobject.newobject

Makes remote python package sources available in current environment.

ISO8601_FORMAT = '%Y%m%dT%H%M%SZ'
create_cache_directories()[source]

Ensure that SourceProcessor cache directories exist.

determine_git_ls_remote_ref(config)[source]

Determine the ref to be used with the “git ls-remote” command.

Parameters:config (stacker.config.GitPackageSource) – git config dictionary; ‘branch’ key is optional
Returns:A branch reference or “HEAD”
Return type:str
determine_git_ref(config)[source]

Determine the ref to be used for ‘git checkout’.

Parameters:config (dict) – git config dictionary
Returns:A commit id or tag name
Return type:str
fetch_git_package(config)[source]

Make a remote git repository available for local use.

Parameters:config (dict) – git config dictionary
fetch_s3_package(config)[source]

Make a remote S3 archive available for local use.

Parameters:config (dict) – git config dictionary
get_package_sources()[source]

Make remote python packages available for local use.

git_ls_remote(uri, ref)[source]

Determine the latest commit id for a given ref.

Parameters:
  • uri (string) – git URI
  • ref (string) – git ref
Returns:

A commit id

Return type:

str

sanitize_git_path(uri, ref=None)[source]

Take a git URI and ref and converts it to a directory safe path.

Parameters:
  • uri (string) – git URI (e.g. git@github.com:foo/bar.git)
  • ref (string) – optional git ref to be appended to the path
Returns:

Directory name for the supplied uri

Return type:

str

sanitize_uri_path(uri)[source]

Take a URI and converts it to a directory safe path.

Parameters:uri (string) – URI (e.g. http://example.com/cats)
Returns:Directory name for the supplied uri
Return type:str
update_paths_and_config(config, pkg_dir_name)[source]

Handle remote source defined sys.paths & configs.

Parameters:
  • config (dict) – git config dictionary
  • pkg_dir_name (string) – directory name of the stacker archive
class stacker.util.TarExtractor(archive=None)[source]

Bases: stacker.util.Extractor

Extracts tar archives.

static extension()[source]

Return archive extension.

extract(destination)[source]

Extract the archive.

class stacker.util.TarGzipExtractor(archive=None)[source]

Bases: stacker.util.Extractor

Extracts compressed tar archives.

static extension()[source]

Return archive extension.

extract(destination)[source]

Extract the archive.

class stacker.util.ZipExtractor(archive=None)[source]

Bases: stacker.util.Extractor

Extracts zip archives.

static extension()[source]

Return archive extension.

extract(destination)[source]

Extract the archive.

stacker.util.camel_to_snake(name)[source]

Converts CamelCase to snake_case.

Parameters:name (string) – The name to convert from CamelCase to snake_case.
Returns:Converted string.
Return type:string
stacker.util.cf_safe_name(name)[source]

Converts a name to a safe string for a Cloudformation resource.

Given a string, returns a name that is safe for use as a CloudFormation Resource. (ie: Only alphanumeric characters)

stacker.util.convert_class_name(kls)[source]

Gets a string that represents a given class.

Parameters:kls (class) – The class being analyzed for its name.
Returns:The name of the given kls.
Return type:string
stacker.util.create_route53_zone(client, zone_name)[source]

Creates the given zone_name if it doesn’t already exists.

Also sets the SOA negative caching TTL to something short (300 seconds).

Parameters:
  • client (botocore.client.Route53) – The connection used to interact with Route53’s API.
  • zone_name (string) – The name of the DNS hosted zone to create.
Returns:

The zone id returned from AWS for the existing, or newly

created zone.

Return type:

string

stacker.util.ensure_s3_bucket(s3_client, bucket_name, bucket_region)[source]

Ensure an s3 bucket exists, if it does not then create it.

Parameters:
  • s3_client (botocore.client.Client) – An s3 client used to verify and create the bucket.
  • bucket_name (str) – The bucket being checked/created.
  • bucket_region (str, optional) – The region to create the bucket in. If not provided, will be determined by s3_client’s region.
stacker.util.get_client_region(client)[source]

Gets the region from a boto3.client.Client object.

Parameters:client (boto3.client.Client) – The client to get the region from.
Returns:AWS region string.
Return type:string
stacker.util.get_config_directory()[source]

Return the directory the config file is located in.

This enables us to use relative paths in config values.

stacker.util.get_hosted_zone_by_name(client, zone_name)[source]

Get the zone id of an existing zone by name.

Parameters:
  • client (botocore.client.Route53) – The connection used to interact with Route53’s API.
  • zone_name (string) – The name of the DNS hosted zone to create.
Returns:

The Id of the Hosted Zone.

Return type:

string

stacker.util.get_or_create_hosted_zone(client, zone_name)[source]

Get the Id of an existing zone, or create it.

Parameters:
  • client (botocore.client.Route53) – The connection used to interact with Route53’s API.
  • zone_name (string) – The name of the DNS hosted zone to create.
Returns:

The Id of the Hosted Zone.

Return type:

string

stacker.util.get_s3_endpoint(client)[source]

Gets the s3 endpoint for the given boto3.client.Client object.

Parameters:client (boto3.client.Client) – The client to get the endpoint from.
Returns:The AWS endpoint for the client.
Return type:string
stacker.util.get_soa_record(client, zone_id, zone_name)[source]

Gets the SOA record for zone_name from zone_id.

Parameters:
  • client (botocore.client.Route53) – The connection used to interact with Route53’s API.
  • zone_id (string) – The AWS Route53 zone id of the hosted zone to query.
  • zone_name (string) – The name of the DNS hosted zone to create.
Returns:

An object representing the parsed SOA

record returned from AWS Route53.

Return type:

stacker.util.SOARecord

stacker.util.handle_hooks(stage, hooks, provider, context)[source]

Used to handle pre/post_build hooks.

These are pieces of code that we want to run before/after the builder builds the stacks.

Parameters:
  • stage (string) – The current stage (pre_run, post_run, etc).
  • hooks (list) – A list of stacker.config.Hook containing the hooks to execute.
  • provider (stacker.provider.base.BaseProvider) – The provider the current stack is using.
  • context (stacker.context.Context) – The current stacker context.
stacker.util.load_object_from_string(fqcn)[source]

Converts “.” delimited strings to a python object.

Given a “.” delimited string representing the full path to an object (function, class, variable) inside a module, return that object. Example:

load_object_from_string(“os.path.basename”) load_object_from_string(“logging.Logger”) load_object_from_string(“LocalClassName”)

stacker.util.merge_map(a, b)[source]

Recursively merge elements of argument b into argument a.

Primarly used for merging two dictionaries together, where dict b takes precedence over dict a. If 2 lists are provided, they are concatenated.

stacker.util.parse_cloudformation_template(template)[source]

Parse CFN template string.

Leverages the vendored aws-cli yamlhelper to handle JSON or YAML templates.

Parameters:template (str) – The template body.
stacker.util.parse_zone_id(full_zone_id)[source]

Parses the returned hosted zone id and returns only the ID itself.

stacker.util.read_value_from_path(value)[source]

Enables translators to read values from files.

The value can be referred to with the file:// prefix. ie:

conf_key: ${kms file://kms_value.txt}
stacker.util.s3_bucket_location_constraint(region)[source]

Returns the appropriate LocationConstraint info for a new S3 bucket.

When creating a bucket in a region OTHER than us-east-1, you need to specify a LocationConstraint inside the CreateBucketConfiguration argument. This function helps you determine the right value given a given client.

Parameters:region (str) – The region where the bucket will be created in.
Returns:The string to use with the given client for creating a bucket.
Return type:string
stacker.util.stack_template_key_name(blueprint)[source]

Given a blueprint, produce an appropriate key name.

Parameters:blueprint (stacker.blueprints.base.Blueprint) – The blueprint object to create the key from.
Returns:Key name resulting from blueprint.
Return type:string
stacker.util.uppercase_first_letter(s)[source]

Return string “s” with first character upper case.

stacker.util.yaml_to_ordered_dict(stream, loader=<class 'yaml.loader.SafeLoader'>)[source]

Provides yaml.load alternative with preserved dictionary order.

Parameters:
  • stream (string) – YAML string to load.
  • loader (yaml.loader) – PyYAML loader class. Defaults to safe load.
Returns:

Parsed YAML.

Return type:

OrderedDict

stacker.variables module

class stacker.variables.LookupTemplate(template)[source]

Bases: string.Template

A custom string template we use to replace lookup values

idpattern = '[_a-z][^\\$\\{\\}]*'
pattern = <_sre.SRE_Pattern object>
class stacker.variables.Variable(name, value)[source]

Bases: future.types.newobject.newobject

Represents a variable passed to a stack.

Parameters:
  • name (str) – Name of the variable
  • value (str) – Initial value of the variable from the config
lookups

Return any lookups within the value

needs_resolution

Return True if the value has any lookups that need resolving.

replace(resolved_lookups)[source]

Replace lookups in the Variable with their resolved values.

Parameters:resolved_lookups (dict) – dict of stacker.lookups.Lookup -> resolved value.
resolve(context, provider)[source]

Recursively resolve any lookups with the Variable.

Parameters:
  • context (stacker.context.Context) – Current context for building the stack
  • provider (stacker.provider.base.BaseProvider) – subclass of the base provider
resolved

Boolean for whether the Variable has been resolved.

Variables only need to be resolved if they contain lookups.

value

Return the current value of the Variable.

_resolved_value takes precedence over _value.

stacker.variables.resolve(value, replacements)[source]

Recursively resolve any lookups within the data structure.

Parameters:
  • value (Union[str, list, dict]) – a structure that contains lookups
  • replacements – resolved lookup values
Returns:

value passed in with lookup values resolved

Return type:

Union[str, list, dict]

stacker.variables.resolve_string(value, replacements)[source]

Resolve any lookups within a string.

Parameters:
  • value (str) – string value we’re resolving lookups within
  • replacements (dict) – resolved lookup values
Returns:

value with any lookups resolved

Return type:

str

stacker.variables.resolve_variables(variables, context, provider)[source]

Given a list of variables, resolve all of them.

Parameters:

Module contents