methods

stack arguments

The stack arguments or variables play an important role in defining the behavior and configuration of a stack. Here are the different ways to handle stack arguments:

Required Variables: These are variables that must be set in order for the automation to run successfully. If these variables are not provided or their values are not set, the automation will raise an error. Here’s an example of how to define a required variable:
```
stack.parse.add_required(key=< variable name >,
                         default=< default_value or "null" >)
```
Optional Variables: These are variables that are not required for the automation to run, but they can be set if available as part of the inputs. Here’s an example of how to define an optional variable:
```
stack.parse.add_optional(key=< variable name >,
                         default=< default_value or "null" >)
```
Set Variables Explicitly: In some cases, you may need to set the value of a variable explicitly. This can be done using the set_variable method. Here’s an example:
```
stack.set_variable(< variable name >,
                   < variable value >)
```
Initialize Variables: After defining the required and optional variables, it’s important to initialize them before using them in the automation. This can be done using the init_variables method:
```
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

The use of substacks simplifies and enhances the automation creation process by automatically managing downstream automation.
Stacks can refer to other stacks using the substack method.
The following steps are involved:
- Declare the substack using the add_substack command.
- Include the substack in the stack namespace using init_substacks.
- Invoke the substack with stack arguments using .insert(**inputargs).
Stacks are considered as first-class entities and are referenced as <author>:::<stack_name>::<version>.
- For example: elasticdev:::ec2_ubuntu
- For example: elasticdev:::ec2_ubuntu:0.0.1 (with locked versions)

Here’s an 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, also known as stack groups, can be executed at either the orchestration or delegation level. The delegation level involves executing execution groups by a server, similar to how Chef or Puppet works.

Both orchestration and delegation level execution groups are essentially the same component. However, for clarity in authoring, they are referenced differently depending on the level. Orchestration level execution groups are called using the execgroup methods, while delegated execution groups are called using the hostgroup methods. The examples provided below will help illustrate this distinction.

Execution groups are considered as second-class entities.

execgroups

They are referenced as <author>:::<repo_name>::<group_name>::<version>.
- For example: elasticdev:::docker::ecs_fastest_ci
- For example: elasticdev:::docker::ecs_fastest_ci:0.01 (with a locked version)

To reference and call execution groups at the orchestration level, follow these steps:

Declare the execution groups using the add_execgroup command, providing an explicit alias.
- An explicit alias is necessary because add_execgroup can include multiple execution groups separated by spaces.
Include the execution groups in the stack namespace using init_execgroups.
- 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 into servers for configuration management using Config0, follow these steps:

Declare the execution group using the “add_hostgroup” command, providing an explicit alias.
- An explicit alias is required since add_hostgroup can include multiple execution groups separated by spaces.
Include the execution group in the parent stack namespace using the “init_hostgroups” command.
- Delegate the execution group to a host using the appropriate method.

# 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")