### Example of var.stacks_instance

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.5. Special variables.md

Provides an example of var.stacks_instance, which is the name of the instance or an empty string if not applicable.

```text
foo
```

--------------------------------

### Example Output of `stacks version`

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.3.12. stacks version.md

This shows the typical output when running the `stacks version` command, indicating the specific versions of Stacks and Python installed.

```text
Stacks 2.0.8
Python 3.12.8
```

--------------------------------

### Example of var.stacks_layer

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.5. Special variables.md

Provides an example of var.stacks_layer, representing the full directory name of the current layer.

```text
production@us-east-1_foo
```

--------------------------------

### Example: Render a Layer

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.3.1. stacks render.md

Demonstrates how to navigate to a layer directory and execute the `stacks render` command to generate Terraform code.

```shell
$ cd stacks/vpc/layers/production
$ stacks render
```

--------------------------------

### Example of var.stacks_environments map

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.5. Special variables.md

Demonstrates the structure of var.stacks_environments, a map containing settings for all environments.

```json
{
	production = {
		production      = true
		aws_region      = "eu-south-2"
		aws_assume_role = "Admin"
	}
	development = {
		production      = false
		aws_region      = "eu-south-2"
		aws_assume_role = "Developer"
	}
}
```

--------------------------------

### Install Stacks using uv

Source: https://github.com/cisco-open/stacks/blob/main/docs/2.1. Installation instructions.md

Use this command to install Stacks with uv. Ensure you have Python and uv installed.

```shell
uv tool install git+https://github.com/cisco-open/stacks.git
```

--------------------------------

### Example of var.stacks_environment

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.5. Special variables.md

Shows the value of var.stacks_environment, which is the name of the current environment.

```text
production
```

--------------------------------

### Install Stacks from source for development

Source: https://github.com/cisco-open/stacks/blob/main/docs/2.1. Installation instructions.md

Clone the repository and install Stacks in editable mode using uv for development. This allows immediate use of changes without reinstallation.

```shell
git clone git@github.com:cisco-open/stacks.git
cd stacks/
uv tool install --editable .
```

--------------------------------

### Example of var.stacks_stack

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.5. Special variables.md

Demonstrates the value of var.stacks_stack, which is the name of the current stack.

```text
vpc
```

--------------------------------

### Install Stacks using pip

Source: https://github.com/cisco-open/stacks/blob/main/docs/2.1. Installation instructions.md

Use this command to install Stacks with pip. Ensure you have Python and pip installed.

```shell
pip3 install --break-system-packages git+https://github.com/cisco-open/stacks.git
```

--------------------------------

### stacks surgery move Example

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.3.10. stacks surgery move.md

Demonstrates how to move a resource, specifically `aws_vpc.main`, from the production environment to the development environment. Ensure you are in the correct directory before executing.

```bash
$ cd stacks/vpc/layers/production
$ stacks surgery move aws_vpc.main aws_vpc.main stacks/vpc/layers/development
```

--------------------------------

### Display Stacks and Python Version

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.3.12. stacks version.md

Use this command to check the installed versions of Stacks and Python. This is useful for verifying your environment setup.

```shell
stacks version
```

--------------------------------

### Example of var.stacks_subenvironment

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.5. Special variables.md

Illustrates the value of var.stacks_subenvironment, which is the name of the subenvironment or an empty string if not applicable.

```text
us-east-1
```

--------------------------------

### Example of var.stacks_path

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.5. Special variables.md

Illustrates the value of var.stacks_path, representing the current layer's path relative to the stacks directory parent.

```text
stacks/vpc/layers/production
```

--------------------------------

### Example Stacks Directory Structure

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.4. Directory structure.md

This illustrates the complete directory layout for a Stacks project, highlighting the placement of environment and stack configurations, and their respective files.

```directory structure
|-- environments/               # The environments folder must be named after the value of the STACKS_ENVIRONMENTS_DIR environment variable, which defaults to "environments".
|   `-- production/             # Environment names must follow the ^[a-zA-Z0-9-]{,254}$ regular expression.
|       `-- env.tfvars          # Environments can only have one env.tfvars file to define environment-specific variables.
`-- stacks/                     # The stacks folder must be named after the value of the STACKS_STACKS_DIR environment variable, which defaults to "stacks".
   |-- ec2/                     # Stack names must follow the ^[a-zA-Z0-9-]{,254}$ regular expression.
   |   |-- base/                # The stack base folder must be named after the value of the STACKS_BASE_DIR environment variable, which defaults to "base".
   |   |   |-- backend.tf       # The base folder contains a Terraform root module, you can use Jinja on any one of its *.tf files.
   |   |   `-- modules/...      # You can also have folders here for stuff like local modules, but those don't get Jinja support unless added to the var.stacks_jinja_enabled_modules special variable.
   |   |-- layers/              # The layers folder must be named after the value of the STACKS_LAYERS_DIR environment variable, which defaults to "layers".
   |   |   |-- production/      # Stack layers must be named after an existing environment. Stacks must run within one of these layer directories.
   |   |   |   |-- layer.tfvars # Layers can contain any number of *.tfvars files, which are sorted alphabetically for preference (i.e. a.tfvars is overriden by z.tfvars).
   |   |   |   `-- stacks.out/  # Stacks operations that produce output code store it in stacks.out (or the value of the STACKS_OUTPUT_DIR environment variable). Make sure to exclude this directory from version control.
   |   |   `-- production_foo/  # If you want to deploy your stack multiple times per environment you can use layer instances, which are represented by a layer suffixed by an underscore followed by a string that must follow the ^[a-zA-Z0-9-]{,254}$ regular expression.
   |   |       `-- .keep        # Technically, you don't have to have anything in layer directories, but make sure your version control checks out empty directories, otherwise you can create something like an empty ".keep" file like so.
   |   `-- stack.tfvars         # Stacks can contain any number of *.tfvars files, which are sorted alphabetically for preference (i.e. a.tfvars is overriden by z.tfvars).
   |-- global.tf                # The stacks folder can contain any number of *.tf files, which are joined with the stack base code for cross-stack Terraform code reusability (for example, to define state backends and providers).
   `-- globals.tfvars           # The stacks folder can contain any number of *.tfvars files, which are sorted alphabetically for preference (i.e. a.tfvars is overriden by z.tfvars).

```

--------------------------------

### Example of var.stacks_root

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.5. Special variables.md

Shows the value of var.stacks_root, which is the path to the stacks directory parent relative to Terraform's runtime working directory.

```text
../../../../../..
```

--------------------------------

### Running Terraform Apply with Stacks

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.3.2. stacks terraform.md

Example of how to execute a Terraform apply command after navigating to a layer directory. Ensure you are in the correct layer directory before running.

```shell
$ cd stacks/vpc/layers/production
$ stacks terraform apply
...
```

--------------------------------

### Edit Remote Terraform State Example

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.3.11. stacks surgery edit.md

Demonstrates how to navigate to a project directory and execute the `stacks surgery edit` command to open the remote Terraform state in an editor. Ensure you are in the correct project directory before running.

```shell
$ cd stacks/vpc/layers/production
$ stacks surgery edit
```

--------------------------------

### Stacks Surgery Edit Usage

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.3.11. stacks surgery edit.md

Displays the command-line usage and available options for the `stacks surgery edit` command. No setup is required to view this information.

```shell
Usage: stacks surgery edit [OPTIONS]

  Edit state with vi.

Options:
  --help  Show this message and exit.
```

--------------------------------

### Encrypt a Secret with Stacks

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.1.6. Inline secret encryption.md

Encrypt a secret string using your public key. The '--' is optional unless the secret starts with '--'. The output is the encrypted secret string.

```shell
$ stacks encrypt --public-key-path path/to/public.pem -- 'mysecr3t'  # the "--" before your secret is only required if your secret begins with "--", so Stacks doesn't parse it as a non-existent flag, but it doesn't hurt to always use it
ENC[l42kj562...v349120j]
```

--------------------------------

### Assign Owner Variable

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.2.3. Input validation.md

This is an example of how to define the 'owner' variable in a stack or layer configuration. The value must be present in the 'owners' list defined elsewhere to pass validation.

```hcl
owner = "engineering"
```

--------------------------------

### Fetch AWS VPC Resource Attribute from Different Stack

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.1.5. Custom Jinja functions.md

Access resource attributes from another layer's state using the `resource` function. This example fetches the `id` attribute of an `aws_vpc.main` resource.

```hcl
# stacks/ec2/stack.tfvars.jinja:
vpc_id = "{{ resource("aws_vpc.main", stack="vpc")["id"] }}"
```

--------------------------------

### Create First Environment

Source: https://github.com/cisco-open/stacks/blob/main/docs/2.2. I am starting from scratch.md

Define your first deployment environment by creating a subdirectory under `environments/` and an `env.tfvars` file within it. The environment name must follow a specific regex pattern.

```shell
|-- environments/
|   `-- development/
|       `-- env.tfvars  # must be named "env.tfvars"
`-- stacks/

```

--------------------------------

### Base Directory Structure

Source: https://github.com/cisco-open/stacks/blob/main/docs/2.2. I am starting from scratch.md

Create the initial directory structure for your project. This includes `environments/` for deployment contexts and `stacks/` for your infrastructure code.

```shell
|-- environments/
`-- stacks/

```

--------------------------------

### Create First Stack

Source: https://github.com/cisco-open/stacks/blob/main/docs/2.2. I am starting from scratch.md

Set up your first stack, including its base Terraform module and a layer for a specific environment. This involves creating directories for the stack base, layers, and associated variable files.

```shell
|-- environments/
|   `-- development/
|       `-- env.tfvars
`-- stacks/
   `-- vpc/
       |-- base/
       |   |-- backend.tf
       |   `-- main.tf           # you can do any code structure you want here
       |-- layers/
       |   `-- development/      # must be named after an existing environment
       |       `-- layer.tfvars  # can be named <anything>.tfvars
       `-- stack.tfvars          # can be named <anything>.tfvars

```

--------------------------------

### Stacks Render Command Usage

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.3.1. stacks render.md

Displays the available options for the `stacks render` command, including initialization behavior and help.

```shell
Usage: stacks render [OPTIONS]

  Render a layer into working Terraform code.

Options:
  --init TEXT  Run terraform init (auto, always, never)
  --help       Show this message and exit.
```

--------------------------------

### Execute stacks diff in a Layer Directory

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.3.3. stacks diff.md

Demonstrates how to navigate to a layer directory and execute the `stacks diff` command.

```shell
$ cd stacks/vpc/layers/production
$ stacks diff
```

--------------------------------

### Fetch VPC ID with Full Parameter Specification

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.1.5. Custom Jinja functions.md

Demonstrates fetching a variable using the `variable` function with all possible parameters: `stack`, `environment`, `subenvironment`, and `instance`. Parameters not specified default to the caller's context.

```hcl
# stacks/ec2/layers/development@us-east-1_foo/layer.tfvars.jinja:
vpc_id = "{{ variable("vpc_id", stack="vpc", environment="development", subenvironment="us-east-1", instance="foo") }}"  # stack/environment/subenvironment/instance all default to the caller's
```

--------------------------------

### Using Jinja for Terraform Module Source Variables

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.1.3. Jinja templating for Terraform.md

Demonstrates how Jinja can be used to dynamically set variables, such as the source for a Terraform module, allowing for greater code reusability across projects.

```hcl
module "vpc" {
	source = "{{ var.module_vpc_source }}"

	name = "main"
	cidr = "10.0.0.0/16"
}
```

--------------------------------

### Display `stacks surgery list` Usage

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.3.6. stacks surgery list.md

Shows the command's usage, including available options and a brief description. Use this to understand the command's basic functionality.

```bash
Usage: stacks surgery list [OPTIONS]

  List all resources in state by address.

Options:
  --help  Show this message and exit.
```

--------------------------------

### Use Default Provider

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.2.2. Terraform provider generation.md

This snippet shows how to use the default provider, which automatically uses the environment's account and region.

```hcl
# stacks/vpc/base/foo.tf
resource "foo" "bar" {  # uses the environment's account and region (default provider)
  foo = "bar"
}

```

--------------------------------

### stacks diff Command Usage

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.3.3. stacks diff.md

Displays the usage instructions and available options for the `stacks diff` command.

```shell
Usage: stacks diff [OPTIONS]

  Render and compare Git HEAD vs current uncommitted changes.

Options:
  --help  Show this message and exit.
```

--------------------------------

### stacks encrypt Usage

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.3.4. stacks encrypt.md

Displays the command-line usage for `stacks encrypt`, including available options and their requirements. Use this command to encrypt strings with a public key.

```bash
Usage: stacks encrypt [OPTIONS] [STRING]

  Encrypt a secret string using a public key. Can run in any directory.

Options:
  --public-key-path TEXT  [required]
  --from-stdin            Read input string from standard input
  --help                  Show this message and exit.
```

--------------------------------

### Stacks Terraform Command Usage

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.3.2. stacks terraform.md

Displays the available options and arguments for the 'stacks terraform' command. Use this to understand command structure and available flags.

```bash
Usage: stacks terraform [OPTIONS] [ARGS]...

  Terraform command wrapper.

Options:
  --init TEXT  Run terraform init (auto, always, never)
  --help       Show this message and exit.
```

--------------------------------

### Deploy Development Layer

Source: https://github.com/cisco-open/stacks/blob/main/docs/2.2. I am starting from scratch.md

Navigate to the development layer directory and apply Terraform configurations to deploy the layer.

```shell
cd stacks/vpc/layers/development
stacks terraform apply
```

--------------------------------

### Jinja Variable File Placement

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.1.4. Jinja templating for variables.md

Illustrates the directory structure for placing Jinja-templated variable files (`.tfvars.jinja`) alongside standard variable files.

```text
|-- environments/
|   `-- production/
|       `-- env.tfvars                 # not here
`-- stacks/
   |-- ec2/
   |   |-- base/
   |   |-- layers/
   |   |   `-- production/
   |   |       |-- layer.tfvars        # not here
   |   |       `-- layer.tfvars.jinja  # here
   |   |-- stack.tfvars                # not here
   |   `-- stack.tfvars.jinja          # here
   |-- globals.tfvars                  # not here
   `-- globals.tfvars.jinja            # here
```

--------------------------------

### stacks surgery move Usage

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.3.10. stacks surgery move.md

Displays the command-line usage and available options for `stacks surgery move`. Use this command to understand its parameters and flags.

```bash
Usage: stacks surgery move [OPTIONS] FROM_ADDRESS TO_ADDRESS TO_PATH

  Move a resource from one state to another by address.

Options:
  --help  Show this message and exit.
```

--------------------------------

### Deploy Production Layer

Source: https://github.com/cisco-open/stacks/blob/main/docs/2.2. I am starting from scratch.md

Navigate to the production layer directory and apply Terraform configurations to deploy the layer.

```shell
cd stacks/vpc/layers/production
stacks terraform apply
```

--------------------------------

### Stacks Decrypt Command Usage

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.3.5. stacks decrypt.md

Displays the usage instructions and available options for the `stacks decrypt` command. Requires the path to the private key.

```bash
Usage: stacks decrypt [OPTIONS] STRING

  Decrypt an encrypted string using a private key. Can run in any directory.

Options:
  --private-key-path TEXT  [required]
  --help                   Show this message and exit.

```

--------------------------------

### Share backend.tf Across Stacks

Source: https://github.com/cisco-open/stacks/blob/main/docs/2.2. I am starting from scratch.md

Move your `backend.tf` file to the `stacks/` directory to make it a Jinja template shared by all child stacks. This avoids repeating backend configuration in each stack.

```text
|-- environments/
`-- stacks/
   |-- backend.tf        # (Step 3) Make it a Jinja template and put it here for all stacks to share.
   |-- ec2/
   |   |-- base/         # (Step 1) Remove backend.tf here.
   |   |   `-- main.tf
   |   |-- layers/
   |   `-- stack.tfvars
   `-- vpc/
       |-- base/         # (Step 2) ...and here.
       |   `-- main.tf
       |-- layers/
       `-- stack.tfvars
```

--------------------------------

### Stacks Surgery Import Usage

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.3.7. stacks surgery import.md

Displays the usage instructions for the `stacks surgery import` command, including its arguments and options. This command is used to import a resource into state by its ID.

```bash
Usage: stacks surgery import [OPTIONS] ADDRESS RESOURCE

  Import a resource into state by id.

Options:
  --help  Show this message and exit.
```

--------------------------------

### Configure Backend Type and Arguments

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.2.1. Terraform state backend configuration.md

This HCLvars file specifies the backend type (e.g., 's3') and provides the necessary arguments for the backend configuration, such as region, bucket, dynamodb_table, and role_arn for AWS S3.

```hcl
# stacks/backend.tfvars
backend_type = "s3"
backend-args = {
  region         = "eu-south-2"
  bucket         = "my-terraform-state"
  dynamodb_table = "my-terraform-state"
  role_arn       = "arn:aws:iam::0123456789:role/Terraform"
}
```

--------------------------------

### Use Environment-Specific Provider

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.2.2. Terraform provider generation.md

This snippet shows how to use a provider aliased to a specific environment, 'development', utilizing its account and region.

```hcl
# stacks/vpc/base/foo.tf
resource "foo" "bar" {
  provider = aws.development  # uses the "development" environment's account and region

  foo = "bar"
}

```

--------------------------------

### Generate a New Key Pair with Stacks

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.1.6. Inline secret encryption.md

Generate a new public and private key pair for encrypting and decrypting secrets. Store the private key securely and exclude it from version control.

```shell
stacks genkey --public-key-path public.pem --private-key-path private.pem
```

--------------------------------

### Use Environment and Region Specific Provider

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.2.2. Terraform provider generation.md

This snippet demonstrates using a provider aliased to a specific environment ('development') and region ('us-east-2'), targeting that environment's account.

```hcl
# stacks/vpc/base/foo.tf
resource "foo" "bar" {
  provider = aws.development_us-east-2  # uses the "development" environment's account in the us-east-2 region

  foo = "bar"
}

```

--------------------------------

### Fetch VPC ID from Different Environment and Stack

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.1.5. Custom Jinja functions.md

Retrieve a variable from a different stack and environment using the `variable` function. Specify both `stack` and `environment` parameters.

```hcl
# stacks/ec2/layers/development/layer.tfvars.jinja:
vpc_id = "{{ variable("vpc_id", stack="vpc", environment="production") }}"
```

--------------------------------

### Fetch VPC ID Output from Different Stack

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.1.5. Custom Jinja functions.md

Use the `output` function to retrieve an output value from another stack within the same layer. This is useful for referencing outputs of dependent infrastructure.

```hcl
# stacks/ec2/stack.tfvars.jinja:
vpc_id = "{{ output("vpc_id", stack="vpc") }}"
```

--------------------------------

### Directory Structure for Jinja in Terraform

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.1.3. Jinja templating for Terraform.md

Illustrates the directory structure where Jinja templating is supported within Terraform files (*.tf) and modules, but not in other file types like Python scripts.

```text
|-- environments/
`-- stacks/
   `-- vpc/
       |-- base/
       |   |-- main.tf      # you get Jinja support here (any *.tf files)
       |   |-- module
       |   |   `-- main.tf  # and here (if you add the module to var.stacks_jinja_enabled_modules)
       |   `-- script.py    # but not here (since it's not Terraform code)
       `-- layers/
```

--------------------------------

### Define Terraform State Backend Template

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.2.1. Terraform state backend configuration.md

This HCL template defines the Terraform backend configuration. It uses variables for backend type and arguments, allowing for dynamic configuration. The state file key is constructed using a variable for the Stacks path.

```hcl
# stacks/backend.tf
terraform {
  backend "{{ var.backend_type }}" {
    {% for key, value in var.backend_args.items() -%}
    {{ key }} = "{{ value }}"
    {% endfor -%}
    key = "{{ var.stacks_path }}/terraform.tfstate"  # e.g. "stacks/vpc/layers/production/terraform.tfstate"
  }
}
```

--------------------------------

### Global Terraform File Location

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.1.1. Global Terraform code.md

Illustrates the directory structure for placing global Terraform files within the Stacks project. Global Terraform code should reside in the 'stacks' directory.

```bash
|-- environments/
`-- stacks/
   |-- ...
   `-- global.tf   # here
```

--------------------------------

### Use Specific Region Provider

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.2.2. Terraform provider generation.md

This snippet demonstrates using a provider explicitly configured for the 'us-west-2' region, targeting the environment's account.

```hcl
# stacks/vpc/base/foo.tf
resource "foo" "bar" {
  provider = aws.us-west-2  # uses the environment's account in the us-west-2 region

  foo = "bar"
}

```

--------------------------------

### Conditional Resource Inclusion with Jinja in Terraform

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.1.3. Jinja templating for Terraform.md

Shows how Jinja's if blocks can be used to conditionally include or exclude Terraform resources, offering a more readable alternative to complex count attributes.

```hcl
{% if var.enable_cloudtrail %}
resource "aws_cloudtrail" "main" {
  name = "main"
}
{% endif %}
```

--------------------------------

### Deploy Another Stack

Source: https://github.com/cisco-open/stacks/blob/main/docs/2.2. I am starting from scratch.md

Apply Terraform configurations to deploy an additional stack, such as an EC2 stack, within the VPC.

```shell
stacks terraform apply
```

--------------------------------

### Reference VPC Resource ID using resource() Jinja filter

Source: https://github.com/cisco-open/stacks/blob/main/docs/2.2. I am starting from scratch.md

Use the `resource` Jinja filter to look up a resource by its address in another stack's state and inject its attributes, such as the VPC ID. This is an alternative to using the `output` filter.

```jinja
{{ resource("aws_vpc.main", stack="vpc")["id"] }}
```

--------------------------------

### Reference VPC ID using output() Jinja filter

Source: https://github.com/cisco-open/stacks/blob/main/docs/2.2. I am starting from scratch.md

Use the `output` Jinja filter to dynamically inject the `vpc_id` from the `vpc` stack into your `ec2` stack. This removes the need for hard-coded remote state data sources.

```jinja
{{ output("vpc_id", stack="vpc") }}
```

--------------------------------

### Define Per-Environment AWS Region and Role ARN

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.2.2. Terraform provider generation.md

These files define the specific AWS region and role ARN for different environments like production and development.

```hcl
# environments/production/env.tfvars
aws_region   = "us-east-1"
aws_role_arn = "arn:aws:iam::0123456789:role/Terraform"

```

```hcl
# environments/development/env.tfvars
aws_region   = "eu-south-2"
aws_role_arn = "arn:aws:iam::9876543210:role/Terraform"

```

--------------------------------

### Fetch VPC ID from Same Layer, Different Stack

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.1.5. Custom Jinja functions.md

Use the `variable` function to retrieve a variable from another stack within the same layer. Ensure the target stack is accessible.

```hcl
# stacks/ec2/stack.tfvars.jinja:
vpc_id = "{{ variable("vpc_id", stack="vpc") }}"
```

--------------------------------

### Define Valid Owners List

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.2.3. Input validation.md

This HCL variable file defines a list of valid 'owners' that can be assigned to stacks or layers. It serves as the reference list for the input validation logic.

```hcl
# stacks/owners.tfvars
owners = [
  "engineering",
  "marketing",
  "operations",
  "sales",
]
```

--------------------------------

### Generate MD5 Checksum of a String

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.1.5. Custom Jinja functions.md

Utilize the `md5` Jinja function to compute the MD5 checksum of a given string. This is useful for generating unique identifiers or verifying data integrity.

```hcl
# stacks/ec2/stacks.tfvars.jinja
foo_md5 = "{{ md5("foo") }}"
```

--------------------------------

### Usage of `stacks surgery rename`

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.3.9. stacks surgery rename.md

This command renames a resource from one state address to another. Ensure you provide both the FROM_ADDRESS and TO_ADDRESS.

```bash
Usage: stacks surgery rename [OPTIONS] FROM_ADDRESS TO_ADDRESS

  Rename a resource in the current state.

Options:
  --help  Show this message and exit.
```

--------------------------------

### Define AWS Providers Template

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.2.2. Terraform provider generation.md

This HCL template defines a reusable macro for configuring AWS providers, including aliasing, region, role assumption, and default tags. It demonstrates injecting default and environment-specific providers.

```hcl
# stacks/aws.tf
{% macro aws_provider(alias, region, role) -%}
provider "aws" {
  {% if alias -%}
  alias = "{{ alias }}"
  {% endif -%}
  region = "{{ region }}"
  assume_role {
    role_arn = "{{ role }}"
  }
  default_tags {
    tags = {
      stacks_path = "{{ var.stacks_path }}"
    }
  }
}
{% endmacro -%}

# injects default provider in var.aws_region with var.aws_role_arn
{{ aws_provider(alias=None, region=var.aws_region, role=var.aws_role_arn) }}

# injects provider with var.aws_role_arn in all var.aws_regions
{% for region in var.aws_regions -%}
{{ aws_provider(alias=region, region=region, role=var.aws_role_arn) }}
{% endfor -%}

# injects providers for all other environments in all var.aws_regions
{% for environment, variables in var.stacks_environments.items() -%}
{{ aws_provider(alias=environment, region=variables.aws_region, role=variables.aws_role_arn) }}
{% for region in var.aws_regions -%}
{{ aws_provider(alias=[environment,region]|join("_"), region=region, role=variables.aws_role_arn) }}
{% endfor -%}
{% endfor -%}

```

--------------------------------

### Define AWS Regions

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.2.2. Terraform provider generation.md

This file defines the list of AWS regions to be used for provider configuration.

```hcl
# stacks/aws.tfvars
aws_regions = [
  "us-east-1",
  "us-east-2",
  "us-west-1",
  "us-west-2",
  "eu-central-1",
]

```

--------------------------------

### Enforce Owner Variable Definition and Validity

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.2.3. Input validation.md

This snippet demonstrates how to use the `throw` filter to validate that the 'owner' variable is defined and exists within a list of allowed owners. It halts rendering if these conditions are not met.

```hcl
# stacks/owners.tf
{% if 'owner' not in var %}{{ throw('var.owner is not defined') }}{% endif %}
{% if var.owner not in var.owners %}{{ throw('var.owner not in var.owners') }}{% endif %}
```

--------------------------------

### Share common variables with globals.tfvars

Source: https://github.com/cisco-open/stacks/blob/main/docs/2.2. I am starting from scratch.md

Create a `globals.tfvars` file in the `stacks/` directory to store common variables shared across all stacks. This mirrors the practice of sharing global Terraform code.

```text
|-- environments/
`-- stacks/
   |-- backend.tf
   |-- globals.tfvars  # put common variables here
   |-- ec2/
   `-- vpc/
```

--------------------------------

### stacks decrypt

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.3.5. stacks decrypt.md

Decrypts an encrypted string using a private key. This command can be run from any directory.

```APIDOC
## stacks decrypt

### Description
Decrypt an encrypted string using a private key. Can run in any directory.

### Usage
```
Usage: stacks decrypt [OPTIONS] STRING
```

### Parameters
#### Options
- **--private-key-path** (TEXT) - Required - Path to the private key file for decryption.
- **--help** - Show this message and exit.

### Arguments
- **STRING** - The encrypted string to decrypt.
```

--------------------------------

### Decrypt an Encrypted Secret with Stacks

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.1.6. Inline secret encryption.md

Decrypt an encrypted secret string using your private key. Ensure the STACKS_PRIVATE_KEY_PATH environment variable is set to your private key's location.

```shell
$ stacks decrypt --private-key-path path/to/private.pem 'ENC[l42kj562...v349120j]'
mysecr3t
```

--------------------------------

### stacks surgery remove Usage

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.3.8. stacks surgery remove.md

Use this command to remove a resource from state by its address. It is equivalent to `stacks terraform state rm`.

```bash
Usage: stacks surgery remove [OPTIONS] ADDRESS

  Remove a resource from state by address.

Options:
  --help  Show this message and exit.
```

--------------------------------

### Embed Encrypted Secret in Terraform Variables

Source: https://github.com/cisco-open/stacks/blob/main/docs/3.1.6. Inline secret encryption.md

Assign the encrypted secret string to a variable in a *.tfvars file. Only string values can be encrypted and must be used via *.tfvars.

```hcl
# environments/production/env.tfvars
aws_secret_access_key = "ENC[l42kj562...v349120j]"
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.