Thinking Like Atmos
Atmos can change how you think about the Terraform code you write to build your infrastructure.
When you design cloud architectures with Atmos, you will first break them apart into pieces called components. Then, you will implement Terraform "root modules" for each of those components. Finally, compose your components in any way you like using stacks, without the need to write any code or messy templates for code generation.
In this tutorial, we’ll guide you through the thought process of building Terraform "root modules" that are suitable for use as components. To ensure your components are highly reusable, parameterize them with variables. Design them to serve a single purpose, making them the smallest possible unit of infrastructure in a typical software development lifecycle (SDLC). Group pieces that usually change together, and separate those that change independently.
You're about to discover a new way to think about terraform...
Try our Simple Tutorial
Learn Atmos
Your Architecture is Made up of Components
Start by thinking about your architecture in terms of its logical components.
For example, let’s consider the architecture of a typical modern website. Its components might include a network, a cluster, some applications running on it, a database to store data, a cache, and maybe some object storage.
Each of these logical pieces is a component and typically changes independently.
They are loosely related and this relationship forms a stack. A stack logically combines components without tightly coupling them, ensuring each component’s state is separate. This approach minimizes the blast radius of changes, keeps the state separate, and allows teams to own components. Plus, it encourages reuse since there is a finite number of ways to express infrastructure.
Then, to implement this architecture with Atmos, you will usually follow these same five steps every time.
Why don't we just put everything into a single "Root module"?
The goal should be to build a loosely coupled service-oriented architecture (SOA). Like with modern app design, we should avoid monolithic infrastructure code. Decoupling our infrastructure into components ensures resilience and maintainability.
When we place all the infrastructure into a single "root module," we end up with a Terralith, which is roughly Stage-2 of the Terraform maturity path. All your eggs are in one basket.
- Massive blast radius for every change
- Brittle and prolonged plan/apply cycles
- All your state is in one place
Large root modules are less reusable across teams due to varying requirements, resulting in many specialized root modules without significant benefits. As these root modules grow, they become increasingly time-consuming to plan and apply. This can even lead to hitting cloud provider rate limits, rendering your infrastructure code undeployable.
The Five Steps of Atmos
Step 0: Start Your Project
Create a solid foundation with a well-structured folder layout, embracing best practices and conventions for a consistently organized project. By convention, we recommend keeping all configurations separate from your components, which helps ensure your components' reusability across teams.
See Example
Ready to learn this topic?
Projects are organized into a well-structured folder layout, embracing best practices and conventions for a consistently organized project. Learn About Projects
Step 0: Write Your Components (e.g. Terraform Root Modules)
For each component in your architecture, write a Terraform root module.
Use your existing Terraform root modules or create new ones. As your component library grows, you’ll need to write fewer new components, enabling faster development cycles by reusing infrastructure components across projects.
Try to reuse 80% of your components across projects, and only write new ones when necessary.
Each component stands alone as its own “root module.” Think of them as layers if it helps.What you should end up with are "root modules" for each of these pieces. Something like this...
See Example
Ready to learn this topic?
Components form the essential building blocks of your architecture. They are the smallest unit of infrastructure in a typical software development lifecycle (SDLC). Learn Atmos Components
Step 0: Pass Values Between Components
Use Terraform's native ability to read the remote state or configuration of any other component, for a "loosely coupled" architecture. Atmos provides methods that make this easy.
Ready to learn this topic?
Passing state between components is how you build a loosely coupled architecture. Learn How
Step 0: Configure Your Components with Stacks
Configure your environments such as development, staging, and production—each tailored to different stages of the lifecycle, ensuring smooth transitions and robust deployment strategies. Use a combination imports and inheritance for a template-free way to keep your configurations DRY and enforce consistency across your stacks.
See Example
Ready to learn this topic?
Components are configured with Stacks, which are defined om YAML. Stacks are separate from Components (terraform root modules) to ensure root modules remain highly reusable across teams and promote testing. Learn Configuration
Step 0: Deploy Stacks with Atmos 🚀
Execute deployments with precision using Terraform's plan and apply commands, fully integrated with native GitOps workflows through GitHub Actions for seamless deployment automation. Leverage workflows to orchestrate more complicated deployments that involve multiple steps.
See Example
Ready to learn this topic?
Deploy Components with Atmos, fully integrated with GitOps workflows through GitHub Actions for seamless deployment automation. Deploying with Atmos
Where to Go From Here
This brief introduction covered the essentials of designing cloud architectures that can be used with Atmos.
Now you can start with your first Atmos project! Try out our Simple/Advanced Quick Start, or delve deeper into the syntax and concepts used in this tutorial.
Try our Simple Tutorial
Learn Atmos