Brownfield Considerations

You can adopt Atmos with your existing Terraform root modules. Start with your current code, backend, and workspace, then introduce architectural design patterns incrementally when they help your team.

A brownfield environment contains existing infrastructure and workflows. Adding Atmos does not require rewriting Terraform, recreating resources, or decomposing a root module first. Follow the native Terraform migration guide to configure Atmos around what you already have.

Brownfield Development in Atmos

Begin with one root module and one environment:

1. Point components.terraform.base_path in atmos.yaml at the directory containing your existing root modules. Moving them into components/terraform is optional.
2. Define a stack and its component inputs. You can include existing .tfvars files.
3. Preserve the existing backend type, state location, and Terraform workspace. Use component metadata.terraform_workspace when you need to select an existing workspace explicitly. If the module already declares its backend, disable components.terraform.auto_generate_backend_file to avoid a duplicate backend declaration.
4. Compare the Atmos plan with your existing Terraform plan before switching execution.

Reusable, independently deployable components and shared stack configuration can provide more benefits over time. Treat decomposition as a separate architectural improvement: changes to resource addresses or state boundaries need their own migration plan. Our component best practices and Atmos mindset explain the recommended patterns; they are not prerequisites for adoption.

Remote State in Brownfield Development

Terraform can read existing remote state regardless of whether Atmos originally orchestrated the deployment, provided you configure the correct backend and have access. You can also pass existing resource identifiers through variables or retrieve them with provider data sources.

When there is no accessible Terraform state containing the outputs you need, the Cloud Posse remote-state module supports a static backend. It supplies configured values through the same output interface used by components that consume that module. This is an optional integration pattern, not a requirement for adopting Atmos.

Providing Outputs with a static Backend

Atmos supports brownfield configuration by using the remote state of type static.

Suppose that we need to provision the vpc Terraform component and, instead of provisioning an S3 bucket for VPC Flow Logs, we want to use an existing bucket.

The vpc Terraform component needs the outputs from the vpc-flow-logs-bucket Terraform component to configure VPC Flow Logs.

Let's redesign the example with the vpc and vpc-flow-logs-bucket components described in Terraform Component Remote State and configure the static remote state for the vpc-flow-logs-bucket component to use an existing S3 bucket.

Examples

Configure the vpc-flow-logs-bucket Component

In the stacks/catalog/vpc-flow-logs-bucket.yaml file, add the following configuration for the vpc-flow-logs-bucket/defaults Atmos component:

stacks/catalog/vpc-flow-logs-bucket.yaml

components:
  terraform:
    vpc-flow-logs-bucket/defaults:
      metadata:
        type: abstract
      # Use `static` remote state to configure the attributes for an existing
      # S3 bucket for VPC Flow Logs
      remote_state_backend_type: static
      remote_state_backend:
        static:
          # ARN of the existing S3 bucket
          # `vpc_flow_logs_bucket_arn` is used as an input for the `vpc` component
          vpc_flow_logs_bucket_arn: "arn:aws:s3:::my-vpc-flow-logs-bucket"

In the stacks/ue2-dev.yaml stack config file, add the following config for the vpc-flow-logs-bucket-1 Atmos component in the ue2-dev Atmos stack:

stacks/ue2-dev.yaml

# Import the base Atmos component configuration from the `catalog`.
# `import` supports POSIX-style Globs for file names/paths (double-star `**` is supported).
# File extensions are optional (if not specified, `.yaml` is used by default).
import:
  - catalog/vpc-flow-logs-bucket

components:
  terraform:
    vpc-flow-logs-bucket-1:
      metadata:
        # Point to the Terraform component in `components/terraform` folder
        component: infra/vpc-flow-logs-bucket
        inherits:
          # Inherit all settings and variables from the
          # `vpc-flow-logs-bucket/defaults` base Atmos component
          - vpc-flow-logs-bucket/defaults

Configure and Provision the vpc Component

In the components/terraform/infra/vpc/remote-state.tf file, configure the remote-state Terraform module to obtain the remote state for the vpc-flow-logs-bucket-1 Atmos component:

components/terraform/infra/vpc/remote-state.tf

module "vpc_flow_logs_bucket" {
  count = local.vpc_flow_logs_enabled ? 1 : 0

  source  = "cloudposse/stack-config/yaml//modules/remote-state"
  version = "1.5.0"

  # Specify the Atmos component name (defined in YAML stack config files)
  # for which to get the remote state outputs
  component = var.vpc_flow_logs_bucket_component_name

  # `context` input is a way to provide the information about the stack (using the context
  # variables `namespace`, `tenant`, `environment`, `stage` defined in the stack config)
  context = module.this.context
}

In the components/terraform/infra/vpc/vpc-flow-logs.tf file, configure the aws_flow_log resource for the vpc Terraform component to use the remote state output vpc_flow_logs_bucket_arn from the vpc-flow-logs-bucket-1 Atmos component:

components/terraform/infra/vpc/vpc-flow-logs.tf

locals {
  enabled               = module.this.enabled
  vpc_flow_logs_enabled = local.enabled && var.vpc_flow_logs_enabled
}

resource "aws_flow_log" "default" {
  count = local.vpc_flow_logs_enabled ? 1 : 0

  # Use the remote state output `vpc_flow_logs_bucket_arn` of the `vpc_flow_logs_bucket` component
  log_destination = module.vpc_flow_logs_bucket[0].outputs.vpc_flow_logs_bucket_arn

  log_destination_type = var.vpc_flow_logs_log_destination_type
  traffic_type         = var.vpc_flow_logs_traffic_type
  vpc_id               = module.vpc.vpc_id

  tags = module.this.tags
}

In the stacks/catalog/vpc.yaml file, add the following default config for the vpc/defaults Atmos component:

stacks/catalog/vpc.yaml

components:
  terraform:
    vpc/defaults:
      metadata:
        # `metadata.type: abstract` makes the component `abstract`,
        # explicitly prohibiting the component from being deployed.
        # `atmos terraform apply` will fail with an error.
        # If `metadata.type` attribute is not specified, it defaults to `real`.
        # `real` components can be provisioned by `atmos` and CI/CD like Spacelift and Atlantis.
        type: abstract
      # Default variables, which will be inherited and can be overridden in the derived components
      vars:
        public_subnets_enabled: false
        nat_gateway_enabled: false
        nat_instance_enabled: false
        max_subnet_count: 3
        vpc_flow_logs_enabled: false
        vpc_flow_logs_log_destination_type: s3
        vpc_flow_logs_traffic_type: "ALL"

In the stacks/ue2-dev.yaml stack config file, add the following config for the vpc/1 Atmos component in the ue2-dev stack:

stacks/ue2-dev.yaml

# Import the base component configuration from the `catalog`.
# `import` supports POSIX-style Globs for file names/paths (double-star `**` is supported).
# File extensions are optional (if not specified, `.yaml` is used by default).
import:
  - catalog/vpc

components:
  terraform:
    vpc/1:
      metadata:
        # Point to the Terraform component in `components/terraform` folder
        component: infra/vpc
        inherits:
          # Inherit all settings and variables from the `vpc/defaults` base Atmos component
          - vpc/defaults
      vars:
        # Define variables that are specific for this component
        # and are not set in the base component
        name: vpc-1
        ipv4_primary_cidr_block: 10.8.0.0/18
        # Override the default variables from the base component
        vpc_flow_logs_enabled: true
        vpc_flow_logs_traffic_type: "REJECT"

        # Specify the name of the Atmos component that provides configuration
        # for the `infra/vpc-flow-logs-bucket` Terraform component
        vpc_flow_logs_bucket_component_name: vpc-flow-logs-bucket-1

Having the stacks configured as shown above, we can now provision the vpc/1 Atmos component in the ue2-dev stack by executing the following Atmos commands:

atmos terraform plan vpc/1 -s ue2-dev
atmos terraform apply vpc/1 -s ue2-dev

When the commands are executed, the vpc_flow_logs_bucket remote-state module detects that the vpc-flow-logs-bucket-1 component has the static remote state configured, and instead of reading its remote state from the S3 state bucket, it just returns the static values from the remote_state_backend.static section. The vpc_flow_logs_bucket_arn is then used as an input for the vpc component.