Skip to content

Commit 4804cd4

Browse files
milldrmilldr
committed
documentation for atmos pro with cloudformation
1 parent bfc5ca0 commit 4804cd4

File tree

2 files changed

+144
-11
lines changed

2 files changed

+144
-11
lines changed

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

Lines changed: 115 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -12,12 +12,28 @@ import TaskList from '@site/src/components/TaskList';
1212
import Admonition from '@theme/Admonition';
1313

1414
<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.
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 including state backend, plan file storage, and GitHub OIDC integration.
1616
</Intro>
1717

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>
18+
<KeyPoints>
19+
- Deploy complete Terraform backend infrastructure in a single CloudFormation stack
20+
- Set up S3 buckets for state and plan file storage
21+
- Configure DynamoDB tables for state locking and plan file management
22+
- Create GitHub OIDC integration for secure authentication
23+
- Configure Atmos Pro to use the deployed infrastructure
24+
</KeyPoints>
25+
26+
## Overview
27+
28+
Atmos Pro doesn't run Terraform or Atmos itself. It dispatches GitHub Actions that **you control**. To run Terraform in those GitHub Actions, you need to set up a few things in your cloud environment:
29+
30+
<TaskList>
31+
- **State Backend** (S3 + DynamoDB) to store Terraform state and enable state locking
32+
- **Plan File Storage** (S3 + DynamoDB) to persist Terraform plan outputs for review and approvals
33+
- **OIDC Integration** with GitHub for workflows to authenticate with your cloud provider
34+
</TaskList>
35+
36+
To make things easier, we've provided a CloudFormation template that sets up everything for you.
2137

2238
## Deployment Steps
2339

@@ -28,6 +44,7 @@ import Admonition from '@theme/Admonition';
2844
<TaskList>
2945
- Sign in to your AWS account
3046
- Ensure you have administrator access
47+
- Choose your deployment region (we recommend `us-east-1`)
3148
</TaskList>
3249
</Step>
3350

@@ -40,20 +57,111 @@ import Admonition from '@theme/Admonition';
4057
- Click "Create stack" to deploy
4158
</TaskList>
4259

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.
60+
<Admonition type="warning" title="Important">
61+
Your stack name must be unique across all AWS accounts. We use the stack name as part of the S3 bucket and DynamoDB table IDs.
4562
</Admonition>
63+
64+
[![Launch Stack](https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png)](https://console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/new?stackName=my-terraform-backend&templateURL=https://s3.amazonaws.com/cplive-core-ue2-public-cloudformation/aws-cloudformation-terraform-backend.yaml)
65+
66+
Or manually deploy the template with the AWS CLI:
67+
68+
```bash
69+
aws cloudformation deploy \
70+
--stack-name my-backend \
71+
--template-url https://s3.amazonaws.com/cplive-core-ue2-public-cloudformation/aws-cloudformation-terraform-backend.yaml \
72+
--capabilities CAPABILITY_NAMED_IAM \
73+
--no-fail-on-empty-changeset \
74+
--parameter-overrides GitHubOrg=my-org
75+
```
76+
</Step>
77+
78+
<Step>
79+
### <StepNumber/> Configure Atmos Pro
80+
81+
Once deployed, you will need to add the new role and plan file storage configuration to your Atmos configuration.
82+
83+
#### GitHub Integration Configuration
84+
85+
```yaml
86+
integrations:
87+
github:
88+
gitops:
89+
opentofu-version: "1.10.0"
90+
artifact-storage:
91+
region: "us-east-1" # Ensure this matches the region where the template was deployed
92+
bucket: "my-backend-tfplan" # Get this value from the PlanBucketName output
93+
table: "my-backend-tfplan" # Get this value from the PlanDynamoDBTableName output
94+
role: "arn:aws:iam::123456789012:role/my-backend-github-actions" # Get this value from the GitHubActionsRoleARN output
95+
role:
96+
plan: "arn:aws:iam::123456789012:role/my-backend-github-actions" # Get this value from the GitHubActionsRoleARN output
97+
apply: "arn:aws:iam::123456789012:role/my-backend-github-actions" # Get this value from the GitHubActionsRoleARN output
98+
```
99+
100+
#### State Backend Configuration
101+
102+
Then use the state backend with Atmos by specifying the S3 bucket and DynamoDB table:
103+
104+
```yaml
105+
terraform:
106+
backend_type: s3
107+
backend:
108+
s3:
109+
bucket: my-backend-tfstate # Get this value from the StateBucketName output
110+
dynamodb_table: my-backend-tfstate # Get this value from the StateDynamoDBTableName output
111+
role_arn: null # Set to null to use the current AWS credentials
112+
encrypt: true
113+
key: terraform.tfstate
114+
acl: bucket-owner-full-control
115+
region: us-east-1 # Ensure this matches the region where the template was deployed
116+
remote_state_backend:
117+
s3:
118+
role_arn: null # Set to null to use the current AWS credentials
119+
```
46120
</Step>
47121
</Steps>
48122
123+
## CloudFormation Parameters
124+
125+
| Parameter | Description | Default |
126+
| ----------------------- | ------------------------------------------------------------------------------------------------ | ------- |
127+
| `CreateStateBackend` | Set to 'true' to create state backend resources (S3 bucket, DynamoDB table), 'false' to skip | true |
128+
| `CreatePlanFileStorage` | Set to 'true' to create plan file storage resources (S3 bucket, DynamoDB table), 'false' to skip | true |
129+
| `CreateGitHubAccess` | Set to 'true' to create GitHub access resources (OIDC provider, IAM role), 'false' to skip | true |
130+
| `CreateOIDCProvider` | Set to 'true' to create the GitHub OIDC provider, 'false' to skip (if it already exists) | true |
131+
| `GitHubOrg` | GitHub organization or username | |
132+
| `GitHubRepo` | GitHub repository name. Set to `*` to allow all repositories | \* |
133+
49134
## Review
50135

51136
Congratulations! The CloudFormation stack has now deployed:
52137

53138
<TaskList>
54139
- An IAM role configured with trusted relationships for GitHub Actions
140+
- An S3 bucket to store Terraform state files
141+
- A DynamoDB table for state locking
55142
- An S3 bucket to store Terraform plan files
56143
- A DynamoDB table for managing those plan files
144+
- GitHub OIDC provider for secure authentication
57145
</TaskList>
58146

59-
You're now ready to start using Atmos Pro with GitHub Actions.
147+
You're now ready to start using Atmos Pro with GitHub Actions.
148+
149+
## Cleanup
150+
151+
To destroy the template, run:
152+
153+
```bash
154+
aws cloudformation delete-stack --stack-name my-backend
155+
```
156+
157+
This will destroy the stack and all the resources it created. However, if the S3 bucket is not empty, the stack will fail to destroy.
158+
159+
To destroy the stack and empty the S3 bucket, run:
160+
161+
```bash
162+
aws cloudformation delete-stack --stack-name my-backend --deletion-mode FORCE_DELETE_STACK
163+
```
164+
165+
<Admonition type="warning" title="Warning">
166+
This will destroy the state files and empty the S3 bucket. This is a destructive action and cannot be undone.
167+
</Admonition>

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

Lines changed: 29 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,29 @@ import Admonition from '@theme/Admonition';
1313
import AtmosWorkflow from '@site/src/components/AtmosWorkflow';
1414
import CodeBlock from '@theme/CodeBlock';
1515

16+
<Intro>
17+
Verify and complete the AWS infrastructure setup for Atmos Pro using Atmos and Terraform. This approach checks your existing backend infrastructure and deploys the additional resources needed for plan file storage and GitHub OIDC integration.
18+
</Intro>
19+
20+
<KeyPoints>
21+
- Verify existing Terraform backend infrastructure (S3 + DynamoDB)
22+
- Deploy new S3 bucket and DynamoDB table for plan file storage
23+
- Ensure GitHub OIDC integration is properly configured
24+
- Create IAM roles for GitHub Actions authentication
25+
</KeyPoints>
26+
27+
## Overview
28+
29+
Atmos Pro doesn't run Terraform or Atmos itself. It dispatches GitHub Actions that **you control**. To run Terraform in those GitHub Actions, you need to set up a few things in your cloud environment:
30+
31+
<TaskList>
32+
- **State Backend** (S3 + DynamoDB) to store Terraform state and enable state locking
33+
- **Plan File Storage** (S3 + DynamoDB) to persist Terraform plan outputs for review and approvals
34+
- **OIDC Integration** with GitHub for workflows to authenticate with your cloud provider
35+
</TaskList>
36+
37+
This deployment method verifies your existing backend infrastructure (which should already be deployed as part of the reference architecture) and deploys the additional resources needed for plan file storage and GitHub OIDC integration.
38+
1639
## Quick Start
1740

1841
| Steps | |
@@ -88,12 +111,14 @@ import CodeBlock from '@theme/CodeBlock';
88111

89112
## Review
90113

91-
Congratulations! The Atmos components have now deployed:
114+
Congratulations! The Atmos components have now verified and deployed:
92115

93116
<TaskList>
94-
- An IAM role configured with trusted relationships for GitHub Actions
95-
- An S3 bucket to store Terraform plan files
96-
- A DynamoDB table for managing those plan files
117+
- Verified existing Terraform backend infrastructure (S3 bucket and DynamoDB table for state)
118+
- Deployed new S3 bucket to store Terraform plan files
119+
- Deployed new DynamoDB table for managing plan files
120+
- Ensured GitHub OIDC provider is properly configured
121+
- Created IAM roles for GitHub Actions authentication
97122
</TaskList>
98123

99124
You're now ready to start using Atmos Pro with GitHub Actions.

0 commit comments

Comments
 (0)