Skip to main content

Atmos Components

Components are opinionated, self-contained building blocks of Infrastructure-as-Code (IAC) that solve one specific problem or use-case. Atmos was written to support any number of tools, but also supports a couple of native integration with tools like terraform and helmfile. A common use-case for Atmos is implementing workflows for terraform "root modules".

Component Schema​

A Component consists of the infrastructure as code business logic (e.g. a Terraform "root" module) as well as the configuration of that component. The configuration of a component is stored in a Stack configuration.


Disambiguation

  • Terraform Component is a Terraform Root Module that consists of the resources defined in the .tf files in a working directory (e.g. components/terraform/infra/vpc)

  • Atmos Component provides configuration (variables and other settings) for a type of component (e.g. a Terraform component) and is defined in one or more YAML stack config files (which are called Atmos stacks)


The schema of an Atmos Component in an Atmos Stack is as follows:

components:
  terraform:
    # the slug of the component
    example:

      # configuration specific to atmos
      metadata:
        # Components can be of type "real" (default) or "abstract"
        type: real
        # This is the directory path of the component. 
        # In this example, we're referencing a component in the `componentns/terraform/stable/example` folder.
        component: stable/example

        # We can leverage multiple inheritance to sequentially deep merge multiple configurations
        inherits:
          - example-defaults

        # Settings are where we store configuration related to integrations.
        # It's a freeform map; anything can be placed here.
        settings:
          spacelift: { }

      # Define the terraform variables, which will get deep-merged and exported to a `.tfvars` file by atmos.
      vars:
        enabled: true
        name: superduper
        nodes: 10

Component Attributes​

vars​

The vars section is a free-form map. Use component validation to enforce policies.

vars.namespace​

This is an optional terraform-null-label convention.

The namespace of all stacks. Typically, there will be one namespace for the organization.

Example:

vars:
  namespace: acme

vars.tenant​

This is an optional terraform-null-label convention.

In a multi-tenant configuration, the tenant represents a single tenant. By convention, we typically recommend that every tenant have it's own Organizational Unit (OU).

Example:

vars:
  tenant: platform

vars.stage​

This is an optional terraform-null-label convention.

The stage is where workloads run. See our glossary for disamgiguation.

Example:

vars:
  # Production stage
  stage: prod

vars.environment​

This is an optional terraform-null-label convention.

The environment is used for location where things run. See our glossary for disamgiguation.

Example:


vars:
  # us-east-1
  environment: ue1

metadata​

The metadata section extends functionality of the component.

settings​

The settings block is a free-form map used to pass configuration information to integrations.

Types of Components​

The type of a component is expressed in the metadata.type parameter of a given component configuration.

There are two types of components:

  • real - is a "concrete" component instance
  • abstract - a component configuration, which cannot be instantiated directly. The concept is borrowed from "abstract base classes" of Object Oriented Programming.

Flavors of Components​

Atmos natively supports two types of components, but the convention can be extended to anything (e.g. docker, packer, ansible, etc.)

  1. Terraform:These are stand-alone "root modules" that implement some piece of your infrastructure. For example, typical components might be an EKS cluster, RDS cluster, EFS filesystem, S3 bucket, DynamoDB table, etc. You can find the full library of SweetOps Terraform components on GitHub. By convention, we store components in the components/terraform/ directory within the infrastructure repository.

  2. Helmfiles: These are stand-alone applications deployed usinghelmfileto Kubernetes. For example, typical helmfiles might deploy the DataDog agent, cert-manager controller, nginx-ingress controller, etc. Similarly, the full library of SweetOps Helmfile components is on GitHub. By convention, we store these types of components in the components/helmfile/ directory within the infrastructure repository. Please note, use these public helmfiles as examples; they may not be current.

Terraform Components​

One important distinction about components that is worth noting: components should be opinionated terraform "root" modules that typically call other child modules. Components are the building blocks of your infrastructure. This is where you define all the business logic for how to provision some common piece of infrastructure like ECR repos (with the ecr component) or EKS clusters (with the eks/cluster component). Our convention is to stick components in the components/terraform/ directory.

If your components rely on submodules, our convention is to use a modules/ subfolder of the component to store them.

We do not recommend consuming one terraform component inside of another as that would defeat the purpose; each component is intended to be a loosely coupled unit of IaC with its own lifecycle. Further more, since components define a state backend and providers, it's not advisable to call one root module from another root module.