Skip to content

Commit e18e7eb

Browse files
milldrmilldr
authored
DEV-3192: Atmos Pro Docs (#775)
1 parent 7625df7 commit e18e7eb

File tree

47 files changed

+518
-124
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

47 files changed

+518
-124
lines changed

‎docs/jumpstart/action-items.mdx‎

Lines changed: 0 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -169,14 +169,6 @@ Confirm if you plan to deploy any of the following integrations. If so, we will
169169

170170
<Steps>
171171

172-
<Step>
173-
### <StepNumber/> Spacelift Access
174-
175-
If deploying Spacelift, we will need a Spacelift subscription. Please see [How to Sign Up for Spacelift](/layers/spacelift). This document answers many common questions and describes the signup process step-by-step.
176-
177-
Cloud Posse will need "admin" access for Spacelift to deploy all resources.
178-
</Step>
179-
180172
<Step>
181173
### <StepNumber/> Datadog Access
182174

‎docs/jumpstart/handoffs.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -77,13 +77,13 @@ https://github.com/facebook/docusaurus/issues/6201
7777
<PrimaryCTA to="/layers/software-delivery">Get Started</PrimaryCTA>
7878
</Slide>
7979

80-
<Slide title="GitOps with GitHub Actions">
80+
<Slide title="Terraform Automation with GitHub Actions">
8181
<figure>
8282
<ReactPlayer controls url='https://docs.cloudposse.com/assets/refarch/handoffs/gitops.mp4' />
8383
<figcaption>AI generated voice</figcaption>
8484
</figure>
8585

86-
<PrimaryCTA to="/layers/gitops">Get Started</PrimaryCTA>
86+
<PrimaryCTA to="/layers/atmos-pro">Get Started</PrimaryCTA>
8787
</Slide>
8888

8989
<Slide title="ECS Platform">

‎docs/jumpstart/kickoff.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -131,7 +131,7 @@ This document outlines what to expect from your first call with Cloud Posse. In
131131
</TaskList>
132132

133133
<Admonition>
134-
These are the design decisions you can customize as part of the Jumpstart package. [All other decisions are pre-made](/tags/design-decision/) for you, but you’re welcome to review them. If you’d like to make additional changes, [let us know—we’re happy to provide a quote](https://cloudposse.com/meet).
134+
These are the design decisions you can customize as part of the Jumpstart package. [All other decisions are pre-made](/tags/design-decision/) for you, but you're welcome to review them. If you'd like to make additional changes, [let us know—we're happy to provide a quote](https://cloudposse.com/meet).
135135
</Admonition>
136136

137137
</Step>
@@ -147,7 +147,7 @@ This document outlines what to expect from your first call with Cloud Posse. In
147147
- [Component Development](/learn/component-development)
148148
- [Account Management](/layers/accounts/)
149149
- [Network and DNS](/layers/network/)
150-
- [Spacelift](/layers/spacelift) or [GitOps](/layers/gitops)
150+
- [Automate Terraform](/layers/atmos-pro)
151151
- [ECS](/layers/ecs) or [EKS](/layers/eks)
152152
- [Monitoring](/layers/monitoring) and [Alerting](/layers/alerting)
153153
- [Release Engineering](/layers/software-delivery)
@@ -197,7 +197,7 @@ The Jumpstart accelerator does not include support. To get help, we offer multip
197197

198198
### Slack
199199

200-
If you need help scheduling meetings, please post in your team’s Cloud Posse channel (e.g., `#acme-general`). This keeps discussions open and prevents duplicated or siloed information in direct messages (DMs). In general, please avoid DMs, as they make it harder to escalate requests or follow up. Feel free to @ a team member if you need assistance—we’re here to help!
200+
If you need help scheduling meetings, please post in your team's Cloud Posse channel (e.g., `#acme-general`). This keeps discussions open and prevents duplicated or siloed information in direct messages (DMs). In general, please avoid DMs, as they make it harder to escalate requests or follow up. Feel free to @ a team member if you need assistance—we're here to help!
201201

202202
You can also reach out to our community with our [SweetOps Slack community](#sweetops-slack).
203203

‎docs/layers/atmos-pro/atmos-pro.mdx‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
title: "Atmos Pro"
3+
sidebar_label: "Atmos Pro"
4+
sidebar_class_name: hidden
5+
---
6+
import Intro from '@site/src/components/Intro';
7+
import KeyPoints from '@site/src/components/KeyPoints';
8+
import Steps from '@site/src/components/Steps';
9+
10+
<Intro>
11+
Atmos Pro is our advanced GitOps solution for Terraform and OpenTofu automation, designed to provide enterprise-grade workflow orchestration in GitHub Actions. It extends the capabilities of standard GitHub Actions with powerful features for managing infrastructure deployments, ensuring compliance, and maintaining infrastructure as code at scale.
12+
</Intro>
13+
14+
## The Problem
15+
16+
While GitHub Actions provides a solid foundation for CI/CD, it lacks the specialized tooling needed for complex infrastructure deployments. Teams face several challenges:
17+
18+
<Steps>
19+
- **Limited Deployment Control**: GitHub Actions doesn't provide built-in mechanisms for ordered deployments or dependency management between infrastructure components
20+
- **Poor Visibility**: Understanding the impact of changes across your infrastructure requires manual investigation
21+
- **Insufficient Guardrails**: Basic GitHub Actions workflows don't enforce deployment policies or prevent dangerous operations
22+
- **Drift Management**: Keeping infrastructure in sync with code requires additional tooling and manual processes
23+
- **Multi-Cloud Complexity**: Managing deployments across different cloud providers adds another layer of complexity
24+
</Steps>
25+
26+
Traditional Terraform Automation and Collaboration Software (TACOS) solutions like Terraform Cloud, Spacelift, or Env0 attempt to solve these problems but often come with significant costs and vendor lock-in.
27+
28+
## Our Solution
29+
30+
Atmos Pro enhances GitHub Actions with enterprise-grade features specifically designed for infrastructure deployment:
31+
32+
<Steps>
33+
* **Ordered Deployments**: Ensure infrastructure components are deployed in the correct sequence based on their dependencies
34+
* **Dependency Visualization**: Automatically generate and maintain dependency graphs for your infrastructure
35+
* **Drift Detection**: Continuously monitor and report on infrastructure drift with automated remediation options
36+
* **Enhanced Guardrails**: Implement policy controls and approval gates to prevent dangerous operations
37+
* **Native GitOps**: Leverage Git as the single source of truth with full audit trails and change history
38+
* **Beautiful Job Summaries**: Clear, actionable insights into deployment status and changes
39+
</Steps>
40+
41+
## How It Works
42+
43+
Atmos Pro integrates seamlessly with your GitOps workflow, providing automated infrastructure planning and deployment through two main processes:
44+
45+
### Pull Request Workflow
46+
47+
When a developer creates a pull request, Atmos Pro automatically triggers the planning process:
48+
49+
<Steps>
50+
1. **Developer Makes a Change**: Infrastructure code is modified in a feature branch
51+
2. **Code Is Pushed**: Changes are pushed to the feature branch
52+
3. **GitHub Actions Trigger**: Atmos affected stacks are identified
53+
4. **Atmos Uploads**: Affected stacks information is uploaded
54+
5. **Atmos Pro Dispatches**: Plan workflows are triggered for affected components
55+
6. **Status Updates**: Atmos Pro maintains a status comment showing the progress of plans
56+
</Steps>
57+
58+
### Merge Workflow
59+
60+
When a pull request is merged, Atmos Pro automatically handles the deployment:
61+
62+
<Steps>
63+
1. **Pull Request Is Merged**: Changes are merged into the main branch
64+
2. **GitHub Actions Trigger**: Atmos affected stacks are identified
65+
3. **Atmos Uploads**: Affected stacks information is uploaded
66+
4. **Atmos Pro Dispatches**: Apply workflows are triggered for affected components
67+
5. **Status Updates**: Atmos Pro maintains a status comment showing the progress of deployments
68+
</Steps>
69+
70+
## References
71+
72+
[Setup Documentation](/layers/atmos-pro/setup): Learn how to set up and configure Atmos Pro for your infrastructure, including prerequisites and initial configuration steps.
73+
74+
[atmos-pro.com](https://www.atmos-pro.com): Explore the full documentation for Atmos Pro features and capabilities, including detailed guides and API references.
75+
76+
[atmos.tools](https://www.atmos.tools): Learn about the core Atmos CLI and its features, which form the foundation for Atmos Pro's enhanced capabilities.

‎docs/layers/atmos-pro/setup.mdx‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
---
2+
title: "Setup Atmos Pro"
3+
sidebar_label: "Setup"
4+
sidebar_position: 1
5+
---
6+
import Intro from '@site/src/components/Intro';
7+
import KeyPoints from '@site/src/components/KeyPoints';
8+
import Steps from '@site/src/components/Steps';
9+
import Step from '@site/src/components/Step';
10+
import StepNumber from '@site/src/components/StepNumber';
11+
import TaskList from '@site/src/components/TaskList';
12+
import Tabs from '@theme/Tabs';
13+
import TabItem from '@theme/TabItem';
14+
import CodeBlock from '@theme/CodeBlock';
15+
import PartialAtmosPro from '@site/examples/snippets/.github/workflows/atmos-pro.yaml';
16+
import PartialAtmosProTerraformPlan from '@site/examples/snippets/.github/workflows/atmos-pro-terraform-plan.yaml';
17+
import PartialAtmosProTerraformApply from '@site/examples/snippets/.github/workflows/atmos-pro-terraform-apply.yaml';
18+
19+
<Intro>
20+
Setting up Atmos Pro is straightforward: install the GitHub App, grant repository permissions, set up the workflows, and deploy the AWS infrastructure. This guide provides an overview of each step, with detailed instructions available in the linked pages.
21+
</Intro>
22+
23+
## Setup Process
24+
25+
<Steps>
26+
<Step>
27+
### <StepNumber/> Install the GitHub App
28+
29+
The first step is to install the Atmos Pro GitHub App into your infrastructure repository. This will set up the initial connection between your repository and Atmos Pro.
30+
31+
<TaskList>
32+
- Sign up for Atmos Pro using GitHub
33+
- Create or join a workspace
34+
- Install the Atmos Pro GitHub App
35+
- Import your repositories
36+
</TaskList>
37+
38+
For step-by-step instructions, see the [official Atmos Pro installation guide](https://atmos-pro.com/docs/install).
39+
</Step>
40+
41+
<Step>
42+
### <StepNumber/> Grant Repository Permissions
43+
44+
The second step is to grant repository permissions in Atmos Pro to enable ordered deployments and other features.
45+
46+
<TaskList>
47+
- Permission: `Affected Stacks Create`
48+
- Workflow: `*`
49+
- Branch: `*`
50+
- Environment: `*`
51+
</TaskList>
52+
53+
For detailed instructions on repository permissions, see the [official Atmos Pro repository permissions guide](https://atmos-pro.com/docs/ordered-deployments/repository-permissions).
54+
</Step>
55+
56+
<Step>
57+
### <StepNumber/> Set Up Workflows
58+
59+
The third step is to configure the workflows in your repository. This includes reviewing the generated workflows, setting up environment variables, and configuring branch protection rules.
60+
61+
<TaskList>
62+
- Review the 3 GitHub Action workflows
63+
- Add the Workspace ID to GitHub repository variables
64+
- Merge the workflows into the default branch
65+
</TaskList>
66+
67+
_The dispatched workflows need to exist in the default branch before they can be triggered!_
68+
69+
The following workflows should be added to your repository:
70+
71+
<Tabs>
72+
<TabItem value="atmos-pro" label="atmos-pro.yaml">
73+
This workflow is triggered by GitHub on pull request events (opened, synchronized, reopened) and when the PR is merged (closed). It uses the `atmos describe affected` command to identify affected components and upload them to Atmos Pro.
74+
75+
<CodeBlock language="yaml" title=".github/workflows/atmos-pro.yaml">
76+
{PartialAtmosPro}
77+
</CodeBlock>
78+
</TabItem>
79+
<TabItem value="atmos-pro-terraform-plan" label="atmos-pro-terraform-plan.yaml">
80+
This workflow is dispatched by Atmos Pro to create Terraform plans for affected components. It is a reusable workflow that takes stack and component as inputs.
81+
82+
<CodeBlock language="yaml" title=".github/workflows/atmos-pro-terraform-plan.yaml">
83+
{PartialAtmosProTerraformPlan}
84+
</CodeBlock>
85+
</TabItem>
86+
<TabItem value="atmos-pro-terraform-apply" label="atmos-pro-terraform-apply.yaml">
87+
This workflow is dispatched by Atmos Pro to apply Terraform changes for affected components. It is a reusable workflow that takes stack and component as inputs.
88+
89+
<CodeBlock language="yaml" title=".github/workflows/atmos-pro-terraform-apply.yaml">
90+
{PartialAtmosProTerraformApply}
91+
</CodeBlock>
92+
</TabItem>
93+
</Tabs>
94+
95+
For additional workflow setup instructions, see the [official Atmos Pro workflow configuration guide](https://atmos-pro.com/docs/ordered-deployments/github-workflow-config).
96+
</Step>
97+
98+
<Step>
99+
### <StepNumber/> Deploy AWS Infrastructure
100+
101+
The final step is to deploy the required AWS infrastructure. This will create all necessary resources for running Atmos Terraform Plan and Apply from GitHub Actions.
102+
103+
<TaskList>
104+
- Configure Terraform State Backend
105+
- For role assumption, deploy the GitHub OIDC provider and roles
106+
- To store Terraform planfiles, deploy the S3 bucket and DynamoDB table.
107+
</TaskList>
108+
109+
For step-by-step AWS deployment instructions, choose one of the following options:
110+
- [Atmos and Terraform deployment](/layers/atmos-pro/tutorials/deploy-with-terraform)
111+
- [CloudFormation deployment](/layers/atmos-pro/tutorials/deploy-with-cloudformation)
112+
</Step>
113+
</Steps>
114+
115+
<KeyPoints title="Tips">
116+
1. Make sure you have admin access to both GitHub and AWS before starting the setup
117+
2. Follow the detailed instructions in each linked guide for specific steps
118+
3. Test the setup with a small change before deploying major infrastructure changes
119+
</KeyPoints>
120+
121+
## Verification
122+
123+
After completing all four steps, you can verify the setup by:
124+
125+
<Steps>
126+
<Step>
127+
### <StepNumber/> Test GitHub Integration
128+
129+
- Create a new pull request with a small stack change
130+
- The Atmos Pro GitHub App will automatically comment on the PR
131+
- The comment will show the status of affected components
132+
- As workflows are dispatched for each component, the comment will automatically update
133+
</Step>
134+
135+
<Step>
136+
### <StepNumber/> Verify AWS Resources
137+
138+
- Check that the S3 bucket for storing Terraform plans exists
139+
- Verify the DynamoDB table for tracking deployments is created
140+
- Confirm the IAM roles have the correct permissions
141+
</Step>
142+
</Steps>

‎docs/layers/atmos-pro/tutorials/deploy-with-cloudformation.mdx‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
title: "Deploy Infrastructure with CloudFormation"
3+
sidebar_label: "Deploy with CloudFormation"
4+
sidebar_position: 2
5+
---
6+
import Intro from '@site/src/components/Intro';
7+
import KeyPoints from '@site/src/components/KeyPoints';
8+
import Steps from '@site/src/components/Steps';
9+
import Step from '@site/src/components/Step';
10+
import StepNumber from '@site/src/components/StepNumber';
11+
import TaskList from '@site/src/components/TaskList';
12+
import Admonition from '@theme/Admonition';
13+
14+
<Intro>
15+
Deploy the required AWS infrastructure for Atmos Pro with just a few clicks using CloudFormation. This approach provides a quick and straightforward way to set up all necessary resources.
16+
</Intro>
17+
18+
<Admonition type="info" title="Coming Soon">
19+
Cloudformation support will be available soon. This will provide a one-click deployment experience for setting up the required infrastructure.
20+
</Admonition>
21+
22+
## Deployment Steps
23+
24+
<Steps>
25+
<Step>
26+
### <StepNumber/> Authenticate with AWS
27+
28+
<TaskList>
29+
- Sign in to your AWS account
30+
- Ensure you have administrator access
31+
</TaskList>
32+
</Step>
33+
34+
<Step>
35+
### <StepNumber/> Deploy Infrastructure
36+
37+
<TaskList>
38+
- Click the "Deploy to AWS" button below
39+
- Review the CloudFormation template parameters
40+
- Click "Create stack" to deploy
41+
</TaskList>
42+
43+
<Admonition type="info" title="Coming Soon">
44+
The "Deploy to AWS" button will be available soon. This will provide a one-click deployment experience for setting up the required infrastructure.
45+
</Admonition>
46+
</Step>
47+
</Steps>
48+
49+
## Review
50+
51+
Congratulations! The CloudFormation stack has now deployed:
52+
53+
<TaskList>
54+
- An IAM role configured with trusted relationships for GitHub Actions
55+
- An S3 bucket to store Terraform plan files
56+
- A DynamoDB table for managing those plan files
57+
</TaskList>
58+
59+
You're now ready to start using Atmos Pro with GitHub Actions.

0 commit comments

Comments
 (0)