stacker package¶
Subpackages¶
- stacker.actions package
- stacker.blueprints package
- stacker.commands package
- stacker.config package
- stacker.hooks package
- stacker.logger package
- stacker.lookups package
- Subpackages
- stacker.lookups.handlers package
- Submodules
- stacker.lookups.handlers.ami module
- stacker.lookups.handlers.default module
- stacker.lookups.handlers.dynamodb module
- stacker.lookups.handlers.envvar module
- stacker.lookups.handlers.file module
- stacker.lookups.handlers.hook_data module
- stacker.lookups.handlers.kms module
- stacker.lookups.handlers.output module
- stacker.lookups.handlers.rxref module
- stacker.lookups.handlers.split module
- stacker.lookups.handlers.ssmstore module
- stacker.lookups.handlers.xref module
- Module contents
- stacker.lookups.handlers package
- Submodules
- stacker.lookups.registry module
- Module contents
- Subpackages
- stacker.providers package
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_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
objectsReturn type: list
-
get_targets
()[source]¶ Returns the named targets that are specified in the config.
Returns: a list of stacker.target.Target
objectsReturn 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.
-
template_indent
¶
-
upload_templates_to_s3
¶
stacker.environment module¶
-
class
stacker.environment.
DictWithSourceType
(source_type, *args)[source]¶ Bases:
dict
An environment dict which keeps track of its source.
Environment files may be loaded from simple key/value files, or from structured YAML files, and we need to render them using a different strategy based on their source. This class adds a source_type property to a dict which keeps track of whether the source for the dict is yaml or simple.
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.
FailedLookup
(lookup, error, *args, **kwargs)[source]¶ Bases:
exceptions.Exception
Intermediary Exception to be converted to FailedVariableLookup once it bubbles up there
-
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.
InvalidLookupCombination
(lookup, lookups, value, *args, **kwargs)[source]¶ Bases:
exceptions.Exception
-
exception
stacker.exceptions.
InvalidLookupConcatenation
(lookup, lookups, *args, **kwargs)[source]¶ Bases:
exceptions.Exception
Intermediary Exception to be converted to InvalidLookupCombination once it bubbles up there
-
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_type, *args, **kwargs)[source]¶ Bases:
exceptions.Exception
-
exception
stacker.exceptions.
UnresolvedVariable
(blueprint_name, variable, *args, **kwargs)[source]¶ Bases:
exceptions.Exception
-
exception
stacker.exceptions.
UnresolvedVariableValue
(lookup, *args, **kwargs)[source]¶ Bases:
exceptions.Exception
Intermediary Exception to be converted to UnresolvedVariable once it bubbles up there
-
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.
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 ofstacker.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 optionalstacker.dag.DAG
object. If one is not provided, a new one will be initialized.
- steps (list) – an optional list of
-
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
-
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.
-
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 outlineParameters: message (str, optional) – a message that will be logged to the user after the outline has been logged.
-
step_names
¶
-
steps
¶
-
-
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 stepParameters: - 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.
-
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
¶
-
set_status
(status)[source]¶ Sets the current step’s status. :param status: The status to set the
step to.
-
skipped
¶ Returns True if the step is in a SKIPPED state.
-
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 ofGraph
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).
- graph (
stacker.session_cache module¶
stacker.stack module¶
-
class
stacker.stack.
Stack
(definition, context, variables=None, mappings=None, locked=False, force=False, enabled=True, protected=False, notification_arns=None)[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.
- protected (boot, optional) – Whether this stack is protected.
- notification_arns (list, optional) – An optional list of SNS topic ARNs to send CloudFormation Events to.
-
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
- context (
-
stack_policy
¶
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
- definition (
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.
-
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'¶
-
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 optionalReturns: 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_local_package
(config)[source]¶ Make a local path available to current stacker config.
Parameters: config (dict) – ‘local’ path config dictionary
-
fetch_s3_package
(config)[source]¶ Make a remote S3 archive available for local use.
Parameters: config (dict) – git config dictionary
-
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, pkg_cache_dir=None)[source]¶ Handle remote source defined sys.paths & configs.
Parameters: - config (dict) – git config dictionary
- pkg_dir_name (string) – directory name of the stacker archive
- pkg_cache_dir (string) – fully qualified path to stacker cache cache directory
-
-
class
stacker.util.
TarExtractor
(archive=None)[source]¶ Bases:
stacker.util.Extractor
Extracts tar archives.
-
class
stacker.util.
TarGzipExtractor
(archive=None)[source]¶ Bases:
stacker.util.Extractor
Extracts compressed tar archives.
-
class
stacker.util.
ZipExtractor
(archive=None)[source]¶ Bases:
stacker.util.Extractor
Extracts zip archives.
-
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
- client (
-
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.
- s3_client (
-
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
- client (
-
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
- client (
-
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: - client (
-
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.
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 (any) – Initial value of the variable from the config (str, list, dict)
-
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
- context (
-
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.
-
class
stacker.variables.
VariableValue
[source]¶ Bases:
future.types.newobject.newobject
Abstract Syntax Tree base object to parse the value for a variable
-
class
stacker.variables.
VariableValueConcatenation
[source]¶ Bases:
stacker.variables.VariableValue
,list
-
class
stacker.variables.
VariableValueDict
[source]¶ Bases:
stacker.variables.VariableValue
,dict
-
class
stacker.variables.
VariableValueList
[source]¶ Bases:
stacker.variables.VariableValue
,list
-
class
stacker.variables.
VariableValueLookup
(lookup_name, lookup_data, handler=None)[source]¶
-
stacker.variables.
resolve_variables
(variables, context, provider)[source]¶ Given a list of variables, resolve all of them.
Parameters: - variables (list of
stacker.variables.Variable
) – list of variables - context (
stacker.context.Context
) – stacker context - provider (
stacker.provider.base.BaseProvider
) – subclass of the base provider
- variables (list of