cloudposse/docs/developing-components

Developing Components

Scope: This skill is generic and applies to any Cloud Posse reference architecture project. It covers patterns for

vendoring and creating Terraform components that are consistent across all customers.

Components are opinionated Terraform root modules that implement a specific AWS resource with predefined conventions.

Before Creating a New Component

Always check for existing components first. Creating new components adds maintenance burden.

1. Check Local Components

ls components/terraform/

Many use cases can be solved by configuring existing generic components via catalog:

• `iam-role` - Any IAM role. Create stacks/catalog/iam-role/my-role.yaml instead of a new component.
• `s3-bucket` - Any S3 bucket with standard configurations.
• `lambda` - Lambda functions with common patterns.

2. Check Cloud Posse Component Library

Browse https://docs.cloudposse.com/components/library/ for pre-built components. Common ones:

• eks/cluster - Kubernetes
• aurora-postgres, rds - Databases
• elasticache-redis - Caching
• ecs, ecs-service - Container workloads
• s3-bucket, dynamodb, sqs-queue - Storage and messaging
• cloudwatch-logs, sns-topic - Monitoring and notifications

Cloud Posse Component Sources

Find latest version:

gh release view --repo cloudposse-terraform-components/aws-<component> --json tagName

Vendoring a Cloud Posse Component

1. Create the component directory and component.yaml:

mkdir -p components/terraform/<component-name>

1. Create components/terraform/<component-name>/component.yaml:

<!-- prettier-ignore-start -->

apiVersion: atmos/v1
kind: ComponentVendorConfig
spec:
  source:
    uri: github.com/cloudposse-terraform-components/aws-<component>.git//src?ref={{ .Version }}
    version: <latest-version>  # Use gh release view to find this
    included_paths:
      - "**/**"
    excluded_paths:
      - "providers.tf"
  mixins:
    # Use provider mixin without account-map dependency (for single-account deployments)
    - uri: https://raw.githubusercontent.com/cloudposse-terraform-components/mixins/{{ .Version }}/src/mixins/provider-without-account-map.tf
      version: v0.3.2
      filename: providers.tf

<!-- prettier-ignore-end -->

1. Pull the component:

atmos vendor pull -c <component-name>

3. When to Create a Custom Component

Create a new component when:

• Tightly coupled resources - The resources share the same lifecycle and must be created/destroyed together. For

example, an application-specific ECS service with its ALB target group, CloudWatch alarms, and autoscaling policies.

• Unique to your infrastructure - The configuration is specific to your organization and wouldn't benefit from Cloud

Posse's generic abstractions.

• Single account/region deployment - All resources deploy to one AWS account and region. If resources span accounts

or regions, split into separate components.

Teralithic components (all-in-one) are appropriate when:

• Resources are always deployed together and never independently
• Splitting would create artificial boundaries requiring complex cross-component wiring
• The blast radius is acceptable (all resources affected by any change)

Avoid custom components when:

• You're wrapping a single AWS resource (use generic components instead)
• The resources have different lifecycles (e.g., database vs. application)
• You might reuse this pattern elsewhere (vendor or create a generic component)

New Component Structure

Every new component requires three parts:

1. Root Module (components/terraform/<component-name>/)

Required files (copy from an existing component like ecs):

• `context.tf` - Always identical across all components. Copy from any existing component. Provides Cloud Posse's

null-label context for consistent naming.

• `providers.tf` - Standard provider configuration. Copy from an existing component. Includes the

account_map_enabled variable and dummy iam_roles module for compatibility.

• `versions.tf` - OpenTofu/Terraform and provider version constraints
• `variables.tf` - Component-specific input variables
• `main.tf` - Main resource definitions
• `outputs.tf` - Output values

Note on remote-state.tf: Avoid creating remote-state.tf files for new components. Instead, use Atmos functions (!terraform.state) in stack YAML to pass values from other components. This keeps components simpler and moves cross-component wiring to the stack configuration layer.

2. Catalog Defaults (stacks/catalog/<component-name>/defaults.yaml)

Define organization-wide default values for the component, including dependency lookups:

components:
  terraform:
    <component-name>/defaults:
      metadata:
        component: <component-name>
        type: abstract # Makes this a base configuration, not directly deployable
      vars:
        enabled: true
        name: <component-name>
        # Static defaults
        some_setting: "default-value"
        # Dynamic lookups - resolved at plan time based on current stack
        vpc_id: !terraform.state vpc vpc_id
        subnet_ids: !terraform.state vpc private_subnet_ids

3. Stack Configuration (stacks/orgs/acme/<tenant>/<stage>/<region>/<layer>.yaml)

Import the catalog - often no component block is needed if catalog defaults are complete:

import:
  - orgs/acme/plat/dev/_defaults
  - mixins/region/us-east-1
  - catalog/<component-name>/defaults

If overrides are needed:

import:
  - catalog/<component-name>/defaults
 
components:
  terraform:
    <component-name>:
      vars:
        # Account/region-specific overrides only
        some_setting: "override-value"

Naming Conventions

• Use descriptive, specific names that indicate the component's purpose
• Prefix with the service/platform when specific (e.g., ecs-adot-collector not just adot-collector)
• Use slashes for component hierarchies in catalogs (e.g., iam-role/grafana-cloudwatch-access,

grafana/datasource/cloudwatch)

Stack File Organization

Stack files in stacks/orgs/acme/ mirror the AWS account structure:

• orgs/acme/core/ - Core accounts (root, audit, security, network, auto, artifacts)
• orgs/acme/plat/ - Platform accounts (sandbox, dev, staging, prod)

Within each stage, organized by region:

• global-region/ - Global (us-east-1) resources like IAM
• us-east-2/ - Regional resources

Regional stack files are typically split by layer:

• foundation.yaml - VPC, networking, base infrastructure
• platform.yaml - Shared platform services (ECS clusters, databases)
• app.yaml - Application-specific resources