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-aws-components"

# Tags of this project
tags:
  - terraform
  - terraform-modules
  - aws
  - components
  - terraform-components
  - root
  - geodesic
  - reference-implementation
  - reference-architecture

# Categories of this project
categories:
  - terraform-modules/root
  - terraform-components

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

# License of this project
license: "APACHE2"

# Canonical GitHub repo
github_repo: "cloudposse/terraform-aws-components"

# Badges to display
badges:
  - name: "Latest Release"
    image: "https://img.shields.io/github/release/cloudposse/terraform-aws-components.svg?style=for-the-badge"
    url: "https://github.com/cloudposse/terraform-aws-components/releases/latest"
  - name: "Last Update"
    image: https://img.shields.io/github/last-commit/cloudposse/terraform-aws-components/main?style=for-the-badge
    url: https://github.com/cloudposse/terraform-aws-components/commits/main/
  - name: "Slack Community"
    image: "https://slack.cloudposse.com/for-the-badge.svg"
    url: "https://slack.cloudposse.com"

references:
  - name: "Cloud Posse Documentation"
    description: "Complete documentation for the Cloud Posse solution"
    url: "https://docs.cloudposse.com"
  - name: "Reference Architectures"
    description: "Launch effortlessly with our turnkey reference architectures, built either by your team or ours."
    url: "https://cloudposse.com/"

related:
- name: "Cloud Posse Terraform Modules"
  description: Our collection of reusable Terraform modules used by our reference architectures.
  url: "https://docs.cloudposse.com/modules/"
- name: "Atmos"
  description: "Atmos is like docker-compose but for your infrastructure"
  url: "https://atmos.tools"


# Short description of this project
description: |-
  > [!WARNING]  
  > ## Migration of Components to a New GitHub Organization (CODE FREEZE 11/12 - 11/17)
  > We are in the process of migrating each component in this repository to individual repositories under a new GitHub organization.
  > This change aims to improve the stability, maintainability, and usability of our components.  
  >  
  > [Learn more](https://github.com/cloudposse/terraform-aws-components/issues/1177)  about the migration and what to expect.

  This is a collection of reusable [AWS Terraform components](https://atmos.tools/core-concepts/components/) for provisioning infrastructure used by the Cloud Posse [reference architectures](https://cloudposse.com).
  They work really well with [Atmos](https://atmos.tools), our open-source tool for managing infrastructure as code with Terraform.

introduction: |-
  In this repo you'll find real-world examples of how we've implemented Terraform "root" modules as native
  [Atmos Components](https://atmos.tools/core-concepts/components/) for our customers. These Components
  leverage our hundreds of free and open-source [terraform "child" modules](https://cpco.io/terraform-modules).

  The [component library](https://docs.cloudposse.com/components/) captures the business logic, opinions, best practices and
  non-functional requirements for an organization.

  It's from this library that other developers in your organization will pick and choose from whenever they need to deploy some new
  capability.

  These components make a lot of assumptions (aka ["convention over configuration"](https://en.wikipedia.org/wiki/Convention_over_configuration)) about how we've configured our environments.
  That said, they still serve as an excellent reference for others on how to build, organize and distribute enterprise-grade infrastructure
  with Terraform that can be used with [Atmos](https://atmos.tools).

# How to use this project
usage: |-

  Please take a look at each [component's README](https://docs.cloudposse.com/components/) for specific usage.

  > [!TIP]
  > ## 👽 Use Atmos with Terraform
  > To orchestrate multiple environments with ease using Terraform, Cloud Posse recommends using [Atmos](https://atmos.tools),
  > our open-source tool for Terraform automation.
  >
  > <details>
  > <summary><strong>Watch demo of using Atmos with Terraform</strong></summary>
  > <img src="https://github.com/cloudposse/atmos/blob/master/docs/demo.gif?raw=true"/><br/>
  > <strong>Example of running <a href="https://atmos.tools"><code>atmos</code></a> to manage infrastructure from our <a href="https://atmos.tools/quick-start/">Quick Start</a> tutorial.</strong>
  > </detalis>

  Generally, you can use these components in [Atmos](https://atmos.tools/core-concepts/components/) by adding something like the following
  code into your [stack manifest](https://atmos.tools/core-concepts/stacks/):

  ```yaml
  components:                      # List of components to include in the stack
    terraform:                     # The toolchain being used for configuration
      vpc:                         # The name of the component (e.g. terraform "root" module)
        vars:                      # Terraform variables (e.g. `.tfvars`)
          cidr_block: 10.0.0.0/16  # A variable input passed to terraform via `.tfvars`
  ```

  ## Automated Updates of Components using GitHub Actions

  Leverage our [GitHub Action](https://atmos.tools/integrations/github-actions/component-updater) to automate the creation and management of pull requests for component updates.

  This is done by creating a new file (e.g. `atmos-component-updater.yml`) in the `.github/workflows` directory of your repository.

  The file should contain the following:

  ```yaml
  jobs:
  update:
    runs-on:
      - "ubuntu-latest"
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 1

      - name: Update Atmos Components
        uses: cloudposse/github-action-atmos-component-updater@v2
        env:
          # https://atmos.tools/cli/configuration/#environment-variables
          ATMOS_CLI_CONFIG_PATH: ${{ github.workspace }}/rootfs/usr/local/etc/atmos/
        with:
          github-access-token: ${{ secrets.GITHUB_TOKEN }}
          log-level: INFO
          max-number-of-prs: 10

      - name: Delete abandoned update branches
        uses: phpdocker-io/github-actions-delete-abandoned-branches@v2
        with:
          github_token: ${{ github.token }}
          last_commit_age_days: 0
          allowed_prefixes: "component-update/"
          dry_run: no
  ```

  For the full documentation on how to use the Component Updater GitHub Action, please see the [Atmos Integrations](https://atmos.tools/integrations/github-actions/component-updater) documentation.

  ## Using `pre-commit` Hooks

  This repository uses [pre-commit](https://pre-commit.com/) and [pre-commit-terraform](https://github.com/antonbabenko/pre-commit-terraform) to enforce consistent Terraform code and documentation. This is accomplished by triggering hooks during `git commit` to block commits that don't pass checks (E.g. format, and module documentation). You can find the hooks that are being executed in the [`.pre-commit-config.yaml`](.pre-commit-config.yaml) file.

  You can install [pre-commit](https://pre-commit.com/) and this repo's pre-commit hooks on a Mac machine by running the following commands:

  ```bash
  brew install pre-commit gawk terraform-docs coreutils
  pre-commit install --install-hooks
  ```

  Then run the following command to rebuild the docs for all Terraform components:

  ```bash
  make rebuild-docs
  ```

  > [!IMPORTANT]
  > ## Deprecated Components
  > Terraform components which are no longer actively maintained are kept in the [`deprecated/`](deprecated/) folder.
  >
  > Many of these deprecated components are used in our older reference architectures.
  >
  > We intend to eventually delete, but are leaving them for now in the repo.

include:
  - "docs/targets.md"

# Contributors to this project
contributors: []