Methods

Stack Arguments

Stack arguments or variables define the behavior and configuration of a stack. Here are the different ways to handle stack arguments:

Required Variables

Variables that must be set for successful automation. If not provided, the automation will raise an error.

stack.parse.add_required(key="variable_name", 
                         default="default_value_or_null")

Optional Variables

Variables that aren’t required but can be included as part of the inputs.

stack.parse.add_optional(key="variable_name", 
                         default="default_value_or_null")

Setting Variables Explicitly

Set a variable’s value directly using the set_variable method.

stack.set_variable("variable_name", 
                  "variable_value")

Initializing Variables

After defining required and optional variables, initialize them before use.

stack.init_variables()

Example

# Required variables
stack.parse.add_required(key="aws_default_region",
                         default="us-east-1")

stack.parse.add_required(key="tag",
                         default="null")

# Optional variables
# null or None is provided by syntax below
stack.parse.add_optional(key="commit_hash",
                         default="null")

# Initialize Variables
stack.init_variables()

# Set Variables Explicitly
stack.set_variable("security_group", 
                   "default")

Stack Substacks

Substacks simplify automation creation by managing downstream automation. Here’s how to use them:

1. Declare the substack using add_substack
2. Include the substack in the stack namespace using init_substacks
3. Invoke the substack with arguments using insert(**inputargs)

Stacks are referenced as <author>:::<stack_name>::<version>:
Example: elasticdev:::ec2_ubuntu
Example with locked version: elasticdev:::ec2_ubuntu:0.0.1

Basic Example

# Declare substacks with add method
# author is elasticdev
# stack name is ec2_ubuntu
stack.add_substack('elasticdev:::ec2_ubuntu')

# init the stack namespace
stack.init_substacks()

# Note, the "label" reference to this stack is the
# last element from the fully qualified reference
# "ec2_ubuntu"
stack.ec2_ubuntu.insert(**inputargs)

Full Example

# Declare substacks with add method, which is referenced through
# stack_name without the author reference - ec2-ubuntu
stack.add_substack('elasticdev:::ec2_ubuntu')

# initialize the substacks into the stack namespace
stack.init_substacks()

# create ubuntu docker host
default_values = {
    "size": "t2.medium",
    "disksize": 100,
    "hostname": "test-ubuntu",
    "key": "app-key",
    "image": "ami-ywqreio69345",
    "ip_key": "private_ip",
    "security_group": "web",
    "aws_default_region": "us-east-1"
}

inputargs = {
    "default_values": default_values,
    "automation_phase": "initialize_infrastructure",
    "human_description": "Initiates a server on Ec2",
    "display": True
}

inputargs["display_hash"] = stack.get_hash_object(inputargs)

# call the substack by entering the arguments
# for the substack after the insert command
stack.ec2_ubuntu.insert(**inputargs)

Stack Groups

Execution groups (stack groups) can run at either orchestration or delegation level. For clarity:
Orchestration level: Called using execgroup methods
Delegation level: Called using hostgroup methods (similar to Chef or Puppet)

Execution groups are considered second-class entities.

Execgroups

Referenced as <author>:::<repo_name>::<group_name>::<version>:
Example: elasticdev:::docker::ecs_fastest_ci
Example with locked version: elasticdev:::docker::ecs_fastest_ci:0.01

To use execution groups at the orchestration level:

1. Declare execution groups using add_execgroup with an explicit alias
2. Include them in the stack namespace using init_execgroups
3. Call the execution group with arguments using insert(**inputargs)

# add execgroup
stack.add_execgroup("config0-publish:::gitlab::project")

# initialize the execgroups into the stack namespace
stack.init_execgroups()

env_vars = {
    "NAME": global_address_state_id,
    "STATEFUL_ID": global_address_state_id,
    "RESOURCE_TYPE": "global_address",
    "RESOURCE_TAGS": f"global_address,{stack.vpc_name}"
}

inputargs = {
    "name": global_address_state_id,
    "env_vars": json.dumps(env_vars),
    "stateful_id": global_address_state_id,
    "human_description": f'Allocating global address for vpc "{stack.vpc_name}"'
}

# call the execution group through the alias "global_address"
stack.global_address.insert(**inputargs)

Hostgroups

To incorporate a hostgroup for configuration management:

1. Declare the execution group using add_hostgroup with an explicit alias
2. Include it in the parent stack namespace using init_hostgroups
3. Delegate the execution group to a host

# Declare execution group with an alias "ecs_fastest_ci"
stack.add_hostgroups("elasticdev:::docker::ecs_fastest_ci", 
                     "ecs_fastest_ci")

# initialize the hostgroups 
stack.init_hostgroups()

# call and assign the hostgroups
stack.add_groups_to_host(groups=stack.ecs_fastest_ci,
                         hostname="chevron-001")