README.yaml

#
# This is the canonical configuration for the `README.md`
# Run `make readme` to rebuild the `README.md`
#

# Name of this project
name: terraform-yaml-stack-config

# Logo for this project
#logo: docs/logo.png

# License of this project
license: "APACHE2"

# Copyrights
copyrights:
  - name: "Cloud Posse, LLC"
    url: "https://cloudposse.com"
    year: "2021"

# Canonical GitHub repo
github_repo: cloudposse/terraform-yaml-stack-config

# Badges to display
badges:
  - name: Latest Release
    image: https://img.shields.io/github/release/cloudposse/terraform-yaml-stack-config.svg?style=for-the-badge
    url: https://github.com/cloudposse/terraform-yaml-stack-config/releases/latest
  - name: Last Updated
    image: https://img.shields.io/github/last-commit/cloudposse/terraform-yaml-stack-config.svg?style=for-the-badge
    url: https://github.com/cloudposse/terraform-yaml-stack-config/commits
  - name: Slack Community
    image: https://slack.cloudposse.com/for-the-badge.svg
    url: https://slack.cloudposse.com
categories:
  - config
  - configuration
  - configuration-management
  - configuration-files
  - yaml
  - yaml-config
  - yaml-files
  - yaml-configuration
  - terraform
  - terraform-module
  - terraform-list
  - terraform-map
  - stack
  - stacks
  - helm
  - helmfile
  - provider
  - terraform-provider
  - terraform-backend
  - deep-merge
  - backend
  - s3
  - backend-s3
  - spacelift

# List any related terraform modules that this module may be used with or that this module depends on.

# List any related terraform modules that this module may be used with or that this module depends on.

# List any related terraform modules that this module may be used with or that this module depends on.

# List any related terraform modules that this module may be used with or that this module depends on.

# List any related terraform modules that this module may be used with or that this module depends on.

# List any related terraform modules that this module may be used with or that this module depends on.

# List any related terraform modules that this module may be used with or that this module depends on.
related:
  - name: "terraform-provider-utils"
    description: "The Cloud Posse Terraform Provider for various utilities."
    url: "https://github.com/cloudposse/terraform-provider-utils"
  - name: "terraform-yaml-config"
    description: "Terraform module to convert local and remote YAML configuration templates into Terraform lists and maps."
    url: "https://github.com/cloudposse/terraform-yaml-config"
  - name: "terraform-datadog-monitor"
    description: "Terraform module to configure and provision Datadog monitors from a YAML configuration, complete with automated tests."
    url: "https://github.com/cloudposse/terraform-datadog-monitor"
  - name: "terraform-opsgenie-incident-management"
    description: "Terraform module to provision Opsgenie resources from YAML configurations using the Opsgenie provider, complete with automated tests."
    url: "https://github.com/cloudposse/terraform-opsgenie-incident-management"
  - name: "terraform-aws-components"
    description: "Catalog of reusable Terraform components and blueprints for provisioning reference architectures."
    url: "https://github.com/cloudposse/terraform-aws-components"
  - name: "reference-architectures"
    description: "Get up and running quickly with one of our reference architecture using our fully automated cold-start process."
    url: "https://github.com/cloudposse/reference-architectures"

# List any resources helpful for someone to get started. For example, link to the hashicorp documentation or AWS documentation.
references:
  - name: "Terraform Standard Module Structure"
    description: "HashiCorp's standard module structure is a file and directory layout we recommend for reusable modules distributed in separate repositories."
    url: "https://www.terraform.io/docs/modules/index.html#standard-module-structure"
  - name: "Terraform Module Requirements"
    description: "HashiCorp's guidance on all the requirements for publishing a module. Meeting the requirements for publishing a module is extremely easy."
    url: "https://www.terraform.io/docs/registry/modules/publish.html#requirements"
  - name: "Terraform Version Pinning"
    description: "The required_version setting can be used to constrain which versions of the Terraform CLI can be used with your configuration."
    url: "https://www.terraform.io/docs/configuration/terraform.html#specifying-a-required-terraform-version"
  - name: "Terraform `templatefile` Function"
    description: "`templatefile` reads the file at the given path and renders its content as a template using a supplied set of template variables."
    url: "https://www.terraform.io/docs/configuration/functions/templatefile.html"

# Short description of this project
description: |-
  Terraform module that loads and processes an opinionated ["stack" configuration](#examples) from YAML sources
  using the [`terraform-provider-utils`](https://github.com/cloudposse/terraform-provider-utils) Terraform provider.

  It supports deep-merged variables, settings, ENV variables, backend config, remote state, and [Spacelift](https://spacelift.io/) stacks config outputs for Terraform and helmfile components.

# Introduction to the project
introduction: |2-

  The module is composed of the following sub-modules:

    - [vars](modules/vars) - accepts stack configuration and returns deep-merged variables for a Terraform or helmfile component.
    - [settings](modules/settings) - accepts stack configuration and returns deep-merged settings for a Terraform or helmfile component.
    - [env](modules/env) - accepts stack configuration and returns deep-merged ENV variables for a Terraform or helmfile component.
    - [backend](modules/backend) - accepts stack configuration and returns backend config for a Terraform component.
    - [remote-state](modules/remote-state) - accepts stack configuration and returns remote state outputs for a Terraform component.
      The module supports `s3` and `remote` (Terraform Cloud) backends.
    - [spacelift](modules/spacelift) - accepts infrastructure stack configuration and transforms it into Spacelift stacks.

# How to use this module. Should be an easy example to copy and paste.
usage: |-
  For a complete example, see [examples/complete](examples/complete).

  For automated tests of the complete example using [bats](https://github.com/bats-core/bats-core) and [Terratest](https://github.com/gruntwork-io/terratest),
  see [test](test).

  For an example on how to configure remote state for Terraform components in YAML config files and then read the components outputs from the remote state,
  see [examples/remote-state](examples/remote-state).

  For an example on how to process `vars`, `settings`, `env` and `backend` configurations for all Terraform and helmfile components for a list of stacks,
  see [examples/stacks](examples/stacks).

# Example usage
examples: |2-

  Here's an example of a stack configuration file:

  ```yaml
    import:
      - ue2-globals
    vars:
      stage: dev
    terraform:
      vars: {}
    helmfile:
      vars: {}
    components:
      terraform:
        vpc:
          backend:
            s3:
              workspace_key_prefix: "vpc"
          vars:
            cidr_block: "10.102.0.0/18"
        eks:
          backend:
            s3:
              workspace_key_prefix: "eks"
          vars: {}
      helmfile:
        nginx-ingress:
          vars:
            installed: true
  ```

  The `import` section refers to other stack configurations that are automatically deep merged.

  ### Complete example

  This example loads the stack config `my-stack` (which in turn imports other YAML config dependencies)
  and returns variables and backend config for the Terraform component `my-vpc` from the stack `my-stack`.

  ```hcl
    module "vars" {
      source = "cloudposse/stack-config/yaml//modules/vars"
      # version     = "x.x.x"

      stack_config_local_path = "./stacks"
      stack                   = "my-stack"
      component_type          = "terraform"
      component               = "my-vpc"

      context = module.this.context
    }

    module "backend" {
      source = "cloudposse/stack-config/yaml//modules/backend"
      # version     = "x.x.x"

      stack_config_local_path = "./stacks"
      stack                   = "my-stack"
      component_type          = "terraform"
      component               = "my-vpc"

      context = module.this.context
    }

    module "settings" {
      source = "cloudposse/stack-config/yaml//modules/settings"
      # version     = "x.x.x"

      stack_config_local_path = "./stacks"
      stack                   = "my-stack"
      component_type          = "terraform"
      component               = "my-vpc"

      context = module.this.context
    }

    module "env" {
      source = "cloudposse/stack-config/yaml//modules/env"
      # version     = "x.x.x"

      stack_config_local_path = "./stacks"
      stack                   = "my-stack"
      component_type          = "terraform"
      component               = "my-vpc"

      context = module.this.context
    }

  ```

  The example returns the following deep-merged `vars`, `settings`, `env`, and `backend` configurations for the `my-vpc` Terraform component:

  ```hcl
  backend = {
    "acl" = "bucket-owner-full-control"
    "bucket" = "eg-ue2-root-tfstate"
    "dynamodb_table" = "eg-ue2-root-tfstate-lock"
    "encrypt" = true
    "key" = "terraform.tfstate"
    "region" = "us-east-2"
    "role_arn" = "arn:aws:iam::xxxxxxxxxxxx:role/eg-gbl-root-terraform"
    "workspace_key_prefix" = "vpc"
  }

  backend_type = "s3"
  base_component = "vpc"

  env = {
    "ENV_TEST_1" = "test1_override"
    "ENV_TEST_2" = "test2_override"
    "ENV_TEST_3" = "test3"
    "ENV_TEST_4" = "test4"
  }

  settings = {
    "spacelift" = {
      "autodeploy" = true
      "branch" = "test"
      "triggers" = [
        "1",
        "2",
      ]
      "workspace_enabled" = true
    }
    "version" = 1
  }

  vars = {
    "availability_zones" = [
      "us-east-2a",
      "us-east-2b",
      "us-east-2c",
    ]
    "cidr_block" = "10.132.0.0/18"
    "environment" = "ue2"
    "level" = 3
    "namespace" = "eg"
    "param" = "param4"
    "region" = "us-east-2"
    "stage" = "prod"
    "subnet_type_tag_key" = "example/subnet/type"
    "test_map" = {
      "a" = "a_override_2"
      "b" = "b_override"
      "c" = [
        1,
        2,
        3,
      ]
      "map2" = {
        "atr1" = 1
        "atr2" = 2
        "atr3" = [
          "3a",
          "3b",
          "3c",
        ]
      }
    }
    "var_1" = "1_override"
    "var_2" = "2_override"
    "var_3" = "3a"
  }

  ```

  See [examples/complete](examples/complete) for more details.


  ### Remote state example

  This example accepts a stack config `my-stack` (which in turn imports other YAML config dependencies)
  and returns remote state outputs from the `s3` backend for `my-vpc` and `eks` Terraform components.

  __NOTE:__ The backend type (`s3`) and backend configuration for the components are defined in the stack YAML config files.

  ```hcl
    module "remote_state_my_vpc" {
      source = "cloudposse/stack-config/yaml//modules/remote-state"
      # Cloud Posse recommends pinning every module to a specific version
      # version     = "x.x.x"

      stack_config_local_path = "./stacks"
      stack                   = "my-stack"
      component               = "my-vpc"
    }

    module "remote_state_eks" {
      source = "cloudposse/stack-config/yaml//modules/remote-state"
      # Cloud Posse recommends pinning every module to a specific version
      # version     = "x.x.x"

      stack_config_local_path = "./stacks"
      stack                   = "my-stack"
      component               = "eks"
    }
  ```

  See [examples/remote-state](examples/remote-state) for more details.

# How to get started quickly
#quickstart: |-
#  Here's how to get started...

# Other files to include in this README from the project folder
include:
  - "docs/targets.md"
  - "docs/terraform.md"

# Contributors to this project
contributors: []