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-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: "2020"

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

# Badges to display
badges:
  - name: "Latest Release"
    image: "https://img.shields.io/github/release/cloudposse/terraform-yaml-config.svg"
    url: "https://github.com/cloudposse/terraform-yaml-config/releases/latest"
  - name: "Slack Community"
    image: "https://slack.cloudposse.com/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
  - account

# List any related terraform modules that this module may be used with or that this module depends on.
related:
  - 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"
  - name: "Terraform `template_file` data source"
    description: "The `template_file` data source renders a template from a template string, which is usually loaded from an external file."
    url: "https://registry.terraform.io/providers/hashicorp/template/latest/docs/data-sources/file"
  - name: "Deepmerge"
    description: "Terraform module to perform a deep map merge of standard Terraform maps and objects."
    url: "https://github.com/Imperative-Systems-Inc/terraform-modules/tree/master/deepmerge"

# Short description of this project
description: |-
  Terraform module to convert local and remote YAML configuration templates into Terraform lists and maps.

# Introduction to the project
introduction: |-
  The module accepts paths to local and remote YAML configuration template files
  and converts the templates into Terraform lists and maps for consumption in other Terraform modules.

  The module can accept a map of parameters for interpolation within the YAML config templates.

  The module also supports a top-level `import` attribute in map configuration templates, which will include the file and perform a deep merge.
  Up to 10 levels of imports hierarchy are supported, and all imported maps are deep merged into a final configuration map.

  For example, if you have a config file like this (e.g. `myconfig.yaml`):

    ```yaml
      import:
        - file1
        - file2
    ```

  Then, this module will deep merge `file1.yaml` and `file2.yaml` into `myconfig.yaml`.

  __Note:__ Do not include the extensions (e.g. `.yaml`) in the imports.

  ### Attributions

  Big thanks to [Imperative Systems Inc.](https://github.com/Imperative-Systems-Inc)
  for the excellent [deepmerge](https://github.com/Imperative-Systems-Inc/terraform-modules/tree/master/deepmerge) Terraform module
  to perform a deep map merge of standard Terraform maps and objects.

# 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)
  (which tests and deploys the example on Datadog), see [test](test).

  For an example of using local config maps with `import` and deep merging into a final configuration map, see [examples/imports-local](examples/imports-local).

  For an example of using remote config maps with `import` and deep merging into a final configuration map, see [examples/imports-remote](examples/imports-remote).

# Example usage
examples: |-

  ### Example of local and remote maps and lists configurations with interpolation parameters

  ```hcl
  module "yaml_config" {
    source = "cloudposse/config/yaml"
    # Cloud Posse recommends pinning every module to a specific version
    # version     = "x.x.x"

    map_config_local_base_path = "./config"

    map_config_paths = [
      "map-configs/*.yaml",
      "https://raw.githubusercontent.com/cloudposse/terraform-opsgenie-incident-management/master/examples/config/resources/services.yaml",
      "https://raw.githubusercontent.com/cloudposse/terraform-opsgenie-incident-management/master/examples/config/resources/team_routing_rules.yaml"
    ]

    list_config_local_base_path = "./config"

    list_config_paths = [
      "list-configs/*.yaml",
      "https://raw.githubusercontent.com/cloudposse/terraform-aws-service-control-policies/master/examples/complete/policies/organization-policies.yaml"
    ]

    parameters = {
      param1 = "1"
      param2 = "2"
    }

    context = module.this.context
  }
  ```

  ### Example of local maps configurations with `import` and deep merging

  In the example, we use two levels of imports,
  and the module deep merges the local config files `imports-level-3.yaml`, `imports-level-2.yaml`, and `imports-level-1.yaml`
  into a final config map.

  See [examples/imports-local](examples/imports-local) for more details.

  ```hcl
  module "yaml_config" {
    source = "cloudposse/config/yaml"
    # Cloud Posse recommends pinning every module to a specific version
    # version     = "x.x.x"

    map_config_local_base_path = "./config"

    map_config_paths = [
      "imports-level-1.yaml"
    ]

    context = module.this.context
  }
  ```

  ### Example of remote maps configurations with with `import` and deep merging

  In the example, we use two levels of imports,
  and the module deep merges the remote config files `globals.yaml`, `ue2-globals.yaml`, and `ue2-prod.yaml`
  into a final config map.

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

  ```hcl
  module "yaml_config" {
    source = "cloudposse/config/yaml"
    # Cloud Posse recommends pinning every module to a specific version
    # version     = "x.x.x"

    map_config_remote_base_path = "https://raw.githubusercontent.com/cloudposse/atmos/master/example/stacks"

    map_config_paths = [
      "https://raw.githubusercontent.com/cloudposse/atmos/master/example/stacks/ue2-prod.yaml"
    ]

    context = module.this.context
  }
  ```

# 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:
  - name: "Erik Osterman"
    github: "osterman"
  - name: "Andriy Knysh"
    github: "aknysh"