From 3d98c349c460969091db72990a0b68a81dce2065 Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Wed, 29 Oct 2025 10:35:03 -0500 Subject: [PATCH 01/14] Clarify AWS Organization creation and Quickstart requirements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This comprehensive update addresses user confusion and gaps in the documentation across three key areas: ## 1. Organization Creation Clarity (Terraform vs Console) - Clarified that AWS Organization is created with Terraform, not the console - Console steps are only for post-creation configuration (quotas, AWS RAM) - Added documentation for the manual creation + import option for teams that want to request quota increases early ## 2. Atmos & Configuration Clarity - Added Atmos primer explaining stacks, components, and catalogs - Provided concrete example of account.yaml structure with explanations - Added learning resources for Atmos beginners - Clarified the difference between docs and actual configurations needed ## 3. Commercial Model & Quickstart Requirements - Added prominent "How Commercial Open Source Works" explanation - Clarified that following docs without Quickstart/Jumpstart is not supported - Added early CTAs on Getting Started page to guide users to Choose Your Path - Added prerequisite checkpoints at critical entry points (accounts layer overview, prepare-aws-organization page, deploy-accounts page) ## Impact These changes prevent the exact user experience that prompted them: - User reads docs, answers design decisions, then gets stuck at "Check the configuration of the 'account' in the stack catalog" because configs don't exist without purchasing Quickstart/Jumpstart Users are now intercepted at multiple touchpoints with clear explanations of what's needed and friendly guidance to the right path. 🤖 Generated with Claude Code Co-Authored-By: Claude --- docs/intro/intro.mdx | 15 +++- docs/intro/path.mdx | 24 ++++-- docs/layers/accounts/accounts.mdx | 10 +++ docs/layers/accounts/deploy-accounts.mdx | 86 +++++++++++++++++++ .../accounts/prepare-aws-organization.mdx | 37 +++++++- .../tutorials/manual-configuration.mdx | 7 +- 6 files changed, 169 insertions(+), 10 deletions(-) diff --git a/docs/intro/intro.mdx b/docs/intro/intro.mdx index 9d5dbfa09..564b7ee08 100644 --- a/docs/intro/intro.mdx +++ b/docs/intro/intro.mdx @@ -28,7 +28,20 @@ graph LR E --> E ``` -Before you jump into the Cloud Posse reference architecture, let’s review what makes it tick. Cloud Posse has helped companies—from scrappy startups to massive enterprises—win big with Terraform. But here’s the key: we do things differently. Everything is based on open source that your team owns and operates. We’re not another enterprise platform with hidden lock-in. If your team depends on our work, we offer [support](/support) to help you move faster and build with confidence. +
+ Choose Your Path + View Pricing +
+ +:::info Get Started the Right Way + +All documentation on this site describes our **AWS Reference Architecture**. We provide all tools for free, but **the complete configuration that ties everything together is what we sell** through Quickstart (DIY) and Jumpstart (done-for-you). + +**New here?** Start by [choosing your path](/intro/path) to understand how to get the configurations you'll need. + +::: + +Before you jump into the Cloud Posse reference architecture, let's review what makes it tick. Cloud Posse has helped companies—from scrappy startups to massive enterprises—win big with Terraform. But here’s the key: we do things differently. Everything is based on open source that your team owns and operates. We’re not another enterprise platform with hidden lock-in. If your team depends on our work, we offer [support](/support) to help you move faster and build with confidence. Our goal? To create a collaborative ecosystem where everyone, regardless of the company, can work together on infrastructure, so we stop reinventing the wheel. diff --git a/docs/intro/path.mdx b/docs/intro/path.mdx index c4374fb88..7f1756e4f 100644 --- a/docs/intro/path.mdx +++ b/docs/intro/path.mdx @@ -14,21 +14,35 @@ import SecondaryCTA from "@site/src/components/SecondaryCTA"; import Steps from "@site/src/components/Steps"; - There are two easy ways to get started. You can dive right in with our Quickstart documentation if you're a hands-on learner. Alternatively, if you prefer Cloud Posse to do it for you, try our Jumpstart. Pick what works best for you! Plus, we provide [multiple support options](/support) if you get stuck. + Ready to build with our reference architecture? Choose your path: **Quickstart** (you implement with our configs) or **Jumpstart** (we implement for you). Both include the complete reference architecture configurations—the critical piece that ties all our free tools together. All of the documentation on this site corresponds to our [AWS Reference Architecture](https://cloudposse.com/services). -We give away all the tools for free—[Terraform modules](https://github.com/cloudposse), [components](https://github.com/cloudposse-terraform-components), [Atmos](https://atmos.tools), and TONS more. But the system that ties it all together? That’s what we sell. Our reference architecture funds the Open Source that powers your business. +We give away all the tools for free—[Terraform modules](https://github.com/cloudposse), [components](https://github.com/cloudposse-terraform-components), [Atmos](https://atmos.tools), and TONS more. But the system that ties it all together? That's what we sell. Our reference architecture funds the Open Source that powers your business. + +:::tip How Commercial Open Source Works + +At Cloud Posse, we give away **everything** except one critical piece: **the configuration**. + +All our tools are free—[Terraform modules](https://github.com/cloudposse), [components](https://github.com/cloudposse-terraform-components), [Atmos](https://atmos.tools), GitHub Actions, and more. But the complete system that ties it all together? That's what we sell. + +**Why this matters:** The documentation on this site describes our reference architecture, but **following it without the Quickstart or Jumpstart configurations is not a supported path**. You'll encounter gaps and blockers (like needing Atmos stack configs that don't exist without our configurations). + +This commercial model sustains the open source ecosystem your business depends on. When you invest in Quickstart or Jumpstart, you're funding the continuous development of all the free tools you use. + +::: - Our Quickstart provides an end-to-end configuration of our AWS reference architecture [customized to your needs](/quickstart/kickoff/#-review-design-decisions) and implemented by you at your own pace. + Our Quickstart provides the **complete end-to-end configuration** of our AWS reference architecture, [customized to your needs](/quickstart/kickoff/#-review-design-decisions) and implemented by you at your own pace. + + **What you get:** The Atmos stack configurations (`stacks/catalog/*.yaml`), component wiring, and architectural decisions that tie our free tools together. This is the missing piece you can't get from the docs alone. - You can start today, by following along with our [Quickstart documentation](/quickstart) to get a sense of what's involved. + Browse our [Quickstart documentation](/quickstart) to preview what's involved before purchasing. - To get started, roll up your sleeves and follow the steps below to start building out your infrastructure! + **Ready to build?** Follow these steps: - [Buy our "Quickstart"](https://cloudposse.com/pricing) to receive all the configurations. diff --git a/docs/layers/accounts/accounts.mdx b/docs/layers/accounts/accounts.mdx index 929028e32..cac1bce08 100644 --- a/docs/layers/accounts/accounts.mdx +++ b/docs/layers/accounts/accounts.mdx @@ -27,6 +27,16 @@ This chapter presents how Cloud Posse designs and manages AWS Account architectu
AI generated voice
+:::caution Before You Start + +This guide describes the **account management architecture** in our reference architecture. To actually implement it, you'll need the complete Atmos stack configurations that define your AWS Organization structure. + +**Don't have the configs yet?** [Choose your path](/intro/path) to get the Quickstart (DIY) or Jumpstart (done-for-you) package, which includes all the `stacks/catalog/*.yaml` files referenced throughout this documentation. + +**Already have configs?** Continue reading to understand the architecture. + +::: + ## The Problem The [AWS Well-Architected Framework](https://docs.aws.amazon.com/pdfs/wellarchitected/latest/userguide/wellarchitected-ug.pdf) defines AWS architectural best practices and presents a set of foundational questions to enable you to understand how a specific architecture aligns with cloud best practices. diff --git a/docs/layers/accounts/deploy-accounts.mdx b/docs/layers/accounts/deploy-accounts.mdx index a2e6de8a6..eef338c64 100644 --- a/docs/layers/accounts/deploy-accounts.mdx +++ b/docs/layers/accounts/deploy-accounts.mdx @@ -25,6 +25,18 @@ This step-by-step process outlines how to deploy AWS accounts using `atmos` work | Deploy accounts settings | `atmos workflow deploy/account-settings -f quickstart/foundation/accounts` | | Finalize account setup | Click Ops | +:::info Required: Quickstart Configurations + +This deployment guide references Atmos stack configurations that are provided as part of our [Quickstart package](/intro/path). Specifically, you'll need: + +- `stacks/catalog/account.yaml` - Defines your AWS Organization structure +- `stacks/catalog/account-map.yaml` - Maps account names and roles +- Various mixin files that configure organizational units and accounts + +**New to the reference architecture?** The complete stack catalog is what we sell—it's how we sustain our open source. [Learn more about choosing your path](/intro/path). + +::: + ## Prepare Account Deployment @@ -33,6 +45,8 @@ This step-by-step process outlines how to deploy AWS accounts using `atmos` work provisioned**. If you aren't confident about the email configuration, account names, or anything else, now is the time to make changes or ask for help. + **Need help understanding the configuration?** See the expandable example below for a sample `account.yaml` structure and explanation of key fields. For adding new accounts or OUs later, see [How to Add a New Organizational Unit](/layers/accounts/tutorials/how-to-add-a-new-organizational-unit/). + You should double-check the following: @@ -41,6 +55,74 @@ This step-by-step process outlines how to deploy AWS accounts using `atmos` work all the mixins have been imported) - Plan the run with `atmos terraform plan account -s core-gbl-root` + + + If you're unfamiliar with Atmos, here's what you need to know: + + - **Stacks** are YAML configuration files that define infrastructure (e.g., `core-gbl-root` is a stack) + - **Components** are Terraform modules that get deployed (e.g., `account` is a component) + - **Catalogs** (`stacks/catalog/*.yaml`) contain reusable configuration that stacks can import + - Commands follow the pattern: `atmos terraform -s ` + + For a deeper introduction, see [How to Use Atmos](/learn/maintenance/tutorials/how-to-use-atmos). + + +
+ Example: What does account.yaml look like? + + The `stacks/catalog/account.yaml` file defines your AWS Organization structure. Here's a simplified example: + + ```yaml + components: + terraform: + account: + vars: + account_email_format: aws+%s@example.com + account_iam_user_access_to_billing: "ALLOW" + organization_enabled: true + + organizational_units: + - name: core + accounts: + - name: core-identity + tenant: core + stage: identity + tags: + eks: false + - name: core-security + tenant: core + stage: security + tags: + eks: false + + - name: plat + accounts: + - name: plat-dev + tenant: plat + stage: dev + tags: + eks: true + - name: plat-staging + tenant: plat + stage: staging + tags: + eks: true + - name: plat-prod + tenant: plat + stage: prod + tags: + eks: true + ``` + + **Key fields to customize:** + - `account_email_format`: Email pattern for new accounts (AWS requires unique emails per account) + - `organizational_units`: List of OUs and the accounts within them + - `name`: Account name (becomes the AWS account name) + - `tenant` and `stage`: Used for naming conventions + - `tags`: Metadata for organizational purposes + + See the [aws-account component](https://github.com/cloudposse-terraform-components/aws-account) for all available configuration options. +
@@ -48,6 +130,10 @@ This step-by-step process outlines how to deploy AWS accounts using `atmos` work + + The workflow above creates the AWS Organization automatically using Terraform. Alternatively, if you created the Organization manually in the AWS Console beforehand (to expedite quota increase requests), Terraform will detect the existing Organization and can import it to manage it as code going forward. + + diff --git a/docs/layers/accounts/prepare-aws-organization.mdx b/docs/layers/accounts/prepare-aws-organization.mdx index 1e71de25d..8864ad12c 100644 --- a/docs/layers/accounts/prepare-aws-organization.mdx +++ b/docs/layers/accounts/prepare-aws-organization.mdx @@ -9,6 +9,28 @@ import Steps from '@site/src/components/Steps'; The Cold Start involves more manual steps than other layers. Read through the following steps and see [the detailed documentation](/layers/accounts/tutorials/manual-configuration/) for edge cases. +:::caution Prerequisites + +**Before following this guide**, ensure you have: + +1. ✅ **Purchased Quickstart or Jumpstart** - This guide references stack configurations (`stacks/catalog/account.yaml`) that are only provided with our paid packages +2. ✅ **Completed the kickoff call** - Your configurations should be customized to your design decisions +3. ✅ **Set up your infrastructure repository** - See [Create Repository](/layers/project/create-repository) + +**Don't have the Quickstart configs yet?** You'll get stuck at the "Check the configuration of the 'account' in the stack catalog" step because that file won't exist. [Choose your path](/intro/path) first. + +::: + + +This guide assumes familiarity with [Atmos](https://atmos.tools), our infrastructure orchestration tool. If you're new to Atmos: + +1. Review [How to Use Atmos](/learn/maintenance/tutorials/how-to-use-atmos) for basic commands +2. Understand that Atmos uses YAML configuration files (called "stacks") to define infrastructure +3. You don't need to be an Atmos expert—you can learn as you go by following the deployment steps + +The [Deploy Accounts guide](/layers/accounts/deploy-accounts/) includes configuration examples to help you understand what needs to be configured. + + In short, the steps are... | Steps | Actions | @@ -58,10 +80,23 @@ From the root account: 1. ### Enable Regions (Optional) The 17 original AWS regions are enabled by default. If you are using a region that is not enabled by default (such as Middle East/Bahrain), you need to take extra steps. For details, see [the detailed documentation](/layers/accounts/tutorials/manual-configuration/#optional-enable-regions) 1. ### Prepare for Account Quota Increase - In order to deploy all accounts, you need to request an increase of the Account Quota from AWS support. This requires an AWS Organization to be created first, which we will create with Terraform in the [Deploy Accounts guide](/layers/accounts/deploy-accounts/#-prepare-account-deployment). This request can take a few days to process, so it's important to get it started early so that it doesn't become a blocker. + In order to deploy all accounts, you need to request an increase of the Account Quota from AWS support. This requires an AWS Organization to be created first, which we will create with Terraform in the [Deploy Accounts guide](/layers/accounts/deploy-accounts/#-prepare-account-deployment). **You can optionally create the Organization manually in the AWS Console first and then import it into Terraform, which allows you to submit the quota increase request earlier (see note below).** This request can take a few days to process, so it's important to get it started early so that it doesn't become a blocker. At this time we don't need to request the increase, but we should be prepared to do so as soon as the AWS Organization is created. + :::tip Manual Creation Option + + Some teams prefer to create the Organization manually in the AWS Console first, then import it into Terraform afterward so it's fully managed as code. This approach allows you to submit the service quota request to increase the account limit right away, without needing to set up Terraform state and everything else first. + + To do this: + 1. Create the Organization manually in the AWS Console + 2. Submit the quota increase request immediately (can take several days) + 3. Set up Terraform/Atmos as described in the guides + 4. Import the existing Organization into Terraform when deploying the `account` component + + This helps keep things moving since quota requests in the reference architecture often exceed default limits and can take time to process. + ::: + For more details, see diff --git a/docs/layers/accounts/tutorials/manual-configuration.mdx b/docs/layers/accounts/tutorials/manual-configuration.mdx index 561ccb156..fcf5d9fca 100644 --- a/docs/layers/accounts/tutorials/manual-configuration.mdx +++ b/docs/layers/accounts/tutorials/manual-configuration.mdx @@ -321,10 +321,11 @@ email address to access, update, or delete the account. Your AWS Organization is managed by the `account` component, along with accounts and organizational units. However, because the AWS defaults for an Organization and its accounts are not exactly what we want, and there is no way -to change them via Terraform, we have to first provision the AWS Organization, then take some steps on the AWS console, -and then we can provision the rest. +to change them via Terraform, we have to first provision the AWS Organization **with Terraform**, then take some manual configuration steps in the AWS console (such as requesting quota increases and enabling AWS RAM), and then we can provision the member accounts. -### Use AWS Console to create and set up the Organization +### Configure Organization Settings via AWS Console + +The AWS Organization itself is created automatically by Terraform (see [Deploy Accounts guide](/layers/accounts/deploy-accounts/)). However, some post-creation configuration tasks must be done manually through the AWS console. Unfortunately, there are some tasks that need to be done via the console. Log into the AWS Console with the root (not SuperAdmin) credentials you have saved in 1Password. From 0082191e1edf87689e46d1a136c79d539378efaa Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Wed, 29 Oct 2025 11:38:50 -0500 Subject: [PATCH 02/14] Fix missing component imports causing build failures MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add missing Note component import in prepare-aws-organization.mdx - Add missing SecondaryCTA component import in intro.mdx Fixes CI build errors: - Error: Expected component `Note` to be defined - Error: Expected component `SecondaryCTA` to be defined 🤖 Generated with Claude Code Co-Authored-By: Claude --- docs/intro/intro.mdx | 1 + docs/layers/accounts/prepare-aws-organization.mdx | 1 + 2 files changed, 2 insertions(+) diff --git a/docs/intro/intro.mdx b/docs/intro/intro.mdx index 564b7ee08..317ec21f8 100644 --- a/docs/intro/intro.mdx +++ b/docs/intro/intro.mdx @@ -9,6 +9,7 @@ import Intro from '@site/src/components/Intro'; import KeyPoints from '@site/src/components/KeyPoints'; import ActionCard from '@site/src/components/ActionCard'; import PrimaryCTA from '@site/src/components/PrimaryCTA'; +import SecondaryCTA from '@site/src/components/SecondaryCTA'; import DocCardList from '@theme/DocCardList'; import Steps from '@site/src/components/Steps'; import Step from '@site/src/components/Step'; diff --git a/docs/layers/accounts/prepare-aws-organization.mdx b/docs/layers/accounts/prepare-aws-organization.mdx index 8864ad12c..7417b83c2 100644 --- a/docs/layers/accounts/prepare-aws-organization.mdx +++ b/docs/layers/accounts/prepare-aws-organization.mdx @@ -6,6 +6,7 @@ sidebar_position: 2 import Intro from '@site/src/components/Intro'; import KeyPoints from '@site/src/components/KeyPoints'; import Steps from '@site/src/components/Steps'; +import Note from '@site/src/components/Note'; The Cold Start involves more manual steps than other layers. Read through the following steps and see [the detailed documentation](/layers/accounts/tutorials/manual-configuration/) for edge cases. From 17287de458c5b026c6fc3f334d0b0d0506758882 Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Wed, 29 Oct 2025 11:47:19 -0500 Subject: [PATCH 03/14] Fix DocCard layout: keep icon and title on same line MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The icon and title were wrapping to separate lines on the DocCard components. Changes: - Set .cardTitle to use flexbox (display: flex, align-items: center) - Added flex-wrap: nowrap to prevent wrapping - Set .icon to inline-flex for proper alignment This ensures the icon and title stay side-by-side as intended. 🤖 Generated with Claude Code Co-Authored-By: Claude --- src/theme/DocCard/styles.module.css | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/theme/DocCard/styles.module.css b/src/theme/DocCard/styles.module.css index b1eeabf54..d4f31b1dd 100644 --- a/src/theme/DocCard/styles.module.css +++ b/src/theme/DocCard/styles.module.css @@ -14,9 +14,10 @@ margin-right: 0.5rem; line-height: 1.5rem; vertical-align: middle; + display: inline-flex; + align-items: center; } - .cardContainer:hover { border-color: var(--ifm-color-primary); box-shadow: 0 3px 6px 0 rgb(0 0 0 / 20%); @@ -28,6 +29,9 @@ .cardTitle { font-size: 1.2rem; + display: flex; + align-items: center; + flex-wrap: nowrap; } .cardDescription { From e2876171831a73ee994af34daa8ea1860f45608b Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Wed, 29 Oct 2025 11:48:39 -0500 Subject: [PATCH 04/14] Update messaging: change to 'Need help finding the configurations?' MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Changed from 'Don't have the configs yet?' to more helpful and positive framing: 'Need help finding the configurations? Start here' This is friendlier and more action-oriented. Updated in: - docs/layers/accounts/accounts.mdx - docs/layers/accounts/prepare-aws-organization.mdx 🤖 Generated with Claude Code Co-Authored-By: Claude --- docs/layers/accounts/accounts.mdx | 2 +- docs/layers/accounts/prepare-aws-organization.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/layers/accounts/accounts.mdx b/docs/layers/accounts/accounts.mdx index cac1bce08..e494f5c8a 100644 --- a/docs/layers/accounts/accounts.mdx +++ b/docs/layers/accounts/accounts.mdx @@ -31,7 +31,7 @@ This chapter presents how Cloud Posse designs and manages AWS Account architectu This guide describes the **account management architecture** in our reference architecture. To actually implement it, you'll need the complete Atmos stack configurations that define your AWS Organization structure. -**Don't have the configs yet?** [Choose your path](/intro/path) to get the Quickstart (DIY) or Jumpstart (done-for-you) package, which includes all the `stacks/catalog/*.yaml` files referenced throughout this documentation. +**Need help finding the configurations? [Start here](/intro/path)** to get the Quickstart (DIY) or Jumpstart (done-for-you) package, which includes all the `stacks/catalog/*.yaml` files referenced throughout this documentation. **Already have configs?** Continue reading to understand the architecture. diff --git a/docs/layers/accounts/prepare-aws-organization.mdx b/docs/layers/accounts/prepare-aws-organization.mdx index 7417b83c2..4ff4d1d9e 100644 --- a/docs/layers/accounts/prepare-aws-organization.mdx +++ b/docs/layers/accounts/prepare-aws-organization.mdx @@ -18,7 +18,7 @@ The Cold Start involves more manual steps than other layers. Read through the fo 2. ✅ **Completed the kickoff call** - Your configurations should be customized to your design decisions 3. ✅ **Set up your infrastructure repository** - See [Create Repository](/layers/project/create-repository) -**Don't have the Quickstart configs yet?** You'll get stuck at the "Check the configuration of the 'account' in the stack catalog" step because that file won't exist. [Choose your path](/intro/path) first. +**Need help finding the configurations? [Start here](/intro/path)** - You'll get stuck at the "Check the configuration of the 'account' in the stack catalog" step because that file won't exist without them. ::: From 22f80f4f9c8b95b74463c4fd7770080b4384bef9 Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Wed, 29 Oct 2025 11:52:49 -0500 Subject: [PATCH 05/14] Update messaging and convert intro to ActionCard MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Changes: 1. Updated messaging throughout to 'Looking for the configurations? Start here' - More neutral and action-oriented than previous versions - Updated in accounts.mdx and prepare-aws-organization.mdx 2. Converted intro.mdx from info admonition + separate CTAs to ActionCard - More visually prominent and cohesive - CTAs now integrated into the card - Consistent with ActionCard pattern used elsewhere 🤖 Generated with Claude Code Co-Authored-By: Claude --- docs/intro/intro.mdx | 18 ++++++++---------- docs/layers/accounts/accounts.mdx | 2 +- .../accounts/prepare-aws-organization.mdx | 2 +- 3 files changed, 10 insertions(+), 12 deletions(-) diff --git a/docs/intro/intro.mdx b/docs/intro/intro.mdx index 317ec21f8..72f754646 100644 --- a/docs/intro/intro.mdx +++ b/docs/intro/intro.mdx @@ -29,18 +29,16 @@ graph LR E --> E ``` -
- Choose Your Path - View Pricing -
+ + All documentation on this site describes our **AWS Reference Architecture**. We provide all tools for free, but **the complete configuration that ties everything together is what we sell** through Quickstart (DIY) and Jumpstart (done-for-you). -:::info Get Started the Right Way + **Looking for the configurations?** Start by choosing your path to understand how to get the configurations you'll need. -All documentation on this site describes our **AWS Reference Architecture**. We provide all tools for free, but **the complete configuration that ties everything together is what we sell** through Quickstart (DIY) and Jumpstart (done-for-you). - -**New here?** Start by [choosing your path](/intro/path) to understand how to get the configurations you'll need. - -::: +
+ Choose Your Path + View Pricing +
+ Before you jump into the Cloud Posse reference architecture, let's review what makes it tick. Cloud Posse has helped companies—from scrappy startups to massive enterprises—win big with Terraform. But here’s the key: we do things differently. Everything is based on open source that your team owns and operates. We’re not another enterprise platform with hidden lock-in. If your team depends on our work, we offer [support](/support) to help you move faster and build with confidence. diff --git a/docs/layers/accounts/accounts.mdx b/docs/layers/accounts/accounts.mdx index e494f5c8a..870b6d724 100644 --- a/docs/layers/accounts/accounts.mdx +++ b/docs/layers/accounts/accounts.mdx @@ -31,7 +31,7 @@ This chapter presents how Cloud Posse designs and manages AWS Account architectu This guide describes the **account management architecture** in our reference architecture. To actually implement it, you'll need the complete Atmos stack configurations that define your AWS Organization structure. -**Need help finding the configurations? [Start here](/intro/path)** to get the Quickstart (DIY) or Jumpstart (done-for-you) package, which includes all the `stacks/catalog/*.yaml` files referenced throughout this documentation. +**Looking for the configurations? [Start here](/intro/path)** to get the Quickstart (DIY) or Jumpstart (done-for-you) package, which includes all the `stacks/catalog/*.yaml` files referenced throughout this documentation. **Already have configs?** Continue reading to understand the architecture. diff --git a/docs/layers/accounts/prepare-aws-organization.mdx b/docs/layers/accounts/prepare-aws-organization.mdx index 4ff4d1d9e..36bd7988f 100644 --- a/docs/layers/accounts/prepare-aws-organization.mdx +++ b/docs/layers/accounts/prepare-aws-organization.mdx @@ -18,7 +18,7 @@ The Cold Start involves more manual steps than other layers. Read through the fo 2. ✅ **Completed the kickoff call** - Your configurations should be customized to your design decisions 3. ✅ **Set up your infrastructure repository** - See [Create Repository](/layers/project/create-repository) -**Need help finding the configurations? [Start here](/intro/path)** - You'll get stuck at the "Check the configuration of the 'account' in the stack catalog" step because that file won't exist without them. +**Looking for the configurations? [Start here](/intro/path)** - You'll get stuck at the "Check the configuration of the 'account' in the stack catalog" step because that file won't exist without them. ::: From d21b135c27d0602359346d2feb173e88435358c4 Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Wed, 29 Oct 2025 11:55:25 -0500 Subject: [PATCH 06/14] Add bottom margin to ActionCard component MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ActionCards were appearing too close to content below them. Added margin-bottom: 2em to .action-card for proper spacing. 🤖 Generated with Claude Code Co-Authored-By: Claude --- src/components/ActionCard/index.css | 1 + 1 file changed, 1 insertion(+) diff --git a/src/components/ActionCard/index.css b/src/components/ActionCard/index.css index 37074336b..6eea2064d 100644 --- a/src/components/ActionCard/index.css +++ b/src/components/ActionCard/index.css @@ -6,6 +6,7 @@ border-radius: 1.3em; box-shadow: 0 4px 8px rgba(0, 0, 0, 0.2); margin-top: 4em; + margin-bottom: 2em; } .action-card h2 { From e8a8ce9c25cc1d4357aa044b3f8a5d419e53d636 Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Wed, 29 Oct 2025 11:56:42 -0500 Subject: [PATCH 07/14] Fix whitespace in admonition: break up run-on sentences MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The 'How Commercial Open Source Works' admonition had sentences running together without proper spacing/paragraph breaks. Changes: - Split long paragraphs into shorter, more digestible chunks - Each major point now gets its own paragraph - Improves readability and prevents text from appearing as a wall This fixes the visual issue where sentences like 'the configuration.All our tools' and 'we sell.Why this matters:' were running together. 🤖 Generated with Claude Code Co-Authored-By: Claude --- docs/intro/path.mdx | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/intro/path.mdx b/docs/intro/path.mdx index 7f1756e4f..73a99b601 100644 --- a/docs/intro/path.mdx +++ b/docs/intro/path.mdx @@ -25,11 +25,17 @@ We give away all the tools for free—[Terraform modules](https://github.com/clo At Cloud Posse, we give away **everything** except one critical piece: **the configuration**. -All our tools are free—[Terraform modules](https://github.com/cloudposse), [components](https://github.com/cloudposse-terraform-components), [Atmos](https://atmos.tools), GitHub Actions, and more. But the complete system that ties it all together? That's what we sell. +All our tools are free—[Terraform modules](https://github.com/cloudposse), [components](https://github.com/cloudposse-terraform-components), [Atmos](https://atmos.tools), GitHub Actions, and more. -**Why this matters:** The documentation on this site describes our reference architecture, but **following it without the Quickstart or Jumpstart configurations is not a supported path**. You'll encounter gaps and blockers (like needing Atmos stack configs that don't exist without our configurations). +But the complete system that ties it all together? That's what we sell. -This commercial model sustains the open source ecosystem your business depends on. When you invest in Quickstart or Jumpstart, you're funding the continuous development of all the free tools you use. +**Why this matters:** The documentation on this site describes our reference architecture, but **following it without the Quickstart or Jumpstart configurations is not a supported path**. + +You'll encounter gaps and blockers (like needing Atmos stack configs that don't exist without our configurations). + +This commercial model sustains the open source ecosystem your business depends on. + +When you invest in Quickstart or Jumpstart, you're funding the continuous development of all the free tools you use. ::: From 32aeb970ac51920cc87241e3dd572da6668cafa5 Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Wed, 29 Oct 2025 15:21:46 -0500 Subject: [PATCH 08/14] Reframe Community section: collaboration over support MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Changed the Community section description to accurately reflect that it's a place for peer collaboration and knowledge sharing, not commercial support. Old: 'for those who want to engage with the SweetOps community and get support' New: 'for connecting with others who are building infrastructure with Cloud Posse's open source tools... a place to share experiences, learn from peers, and collaborate on common challenges' This better represents the community as a watering hole and talk shop for practitioners, not a support channel for the commercial reference architecture. 🤖 Generated with Claude Code Co-Authored-By: Claude --- docs/intro/intro.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/intro/intro.mdx b/docs/intro/intro.mdx index 72f754646..8af12e5fe 100644 --- a/docs/intro/intro.mdx +++ b/docs/intro/intro.mdx @@ -87,7 +87,7 @@ This documentation site breaks down SweetOps into the following sections to help ### Community - The [**Community**](/community) section is for those who want to engage with the SweetOps community and get support. + The [**Community**](/community) section is for connecting with others who are building infrastructure with Cloud Posse's open source tools and reference architecture. It's a place to share experiences, learn from peers, and collaborate on common challenges. - Join our Slack community From 10ec1cc145880882f3b4084fa55515e7cbff1181 Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Wed, 29 Oct 2025 15:25:12 -0500 Subject: [PATCH 09/14] Restore list styles with Tailwind and refocus Community on open source MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two changes in this commit: 1. Restore bullet points and numbering for markdown lists (Tailwind-compatible) - Added @layer base CSS with @apply directives for list-disc and list-decimal - Applies to .markdown and article contexts - Works with Tailwind's utility-first approach - Uses pl-6, my-4 spacing utilities 2. Refocus Community section on open source collaboration - Changed from generic 'connecting with others' to specific emphasis on 'collaborating on the development of Cloud Posse's open source' - Highlights PR reviews, problem-solving, and collective ecosystem building - Clarifies it's about working together to improve modules/components/tools 🤖 Generated with Claude Code Co-Authored-By: Claude --- docs/intro/intro.mdx | 2 +- src/css/custom.css | 18 ++++++++++++++++++ 2 files changed, 19 insertions(+), 1 deletion(-) diff --git a/docs/intro/intro.mdx b/docs/intro/intro.mdx index 8af12e5fe..5c4c8b49a 100644 --- a/docs/intro/intro.mdx +++ b/docs/intro/intro.mdx @@ -87,7 +87,7 @@ This documentation site breaks down SweetOps into the following sections to help ### Community - The [**Community**](/community) section is for connecting with others who are building infrastructure with Cloud Posse's open source tools and reference architecture. It's a place to share experiences, learn from peers, and collaborate on common challenges. + The [**Community**](/community) section is for collaborating on the development of Cloud Posse's open source. Request pull request reviews, ask how others have solved similar problems, and work together to improve our modules, components, and tools. It's where the community collectively builds the ecosystem. - Join our Slack community diff --git a/src/css/custom.css b/src/css/custom.css index 4ffea10f6..705c51df6 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -277,6 +277,24 @@ img.center { --ifm-h1-font-size: 2.5rem; } +/* Restore list styles for markdown content (Tailwind-compatible) */ +@layer base { + .markdown ul, + article ul { + @apply list-disc pl-6 my-4; + } + + .markdown ol, + article ol { + @apply list-decimal pl-6 my-4; + } + + .markdown li, + article li { + @apply my-1; + } +} + .margin-top--md, .margin-vert--md { margin-top: 1rem !important; From 266be81d503b0a744a03892588f05c21eb418243 Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Wed, 29 Oct 2025 15:27:27 -0500 Subject: [PATCH 10/14] Update announcement bar to match new messaging MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Changed from 'Missing the Quickstart configurations?' to 'Looking for the configurations? Start here' to match the consistent messaging used throughout the docs. Also removed emphasis on 'Quickstart' for a cleaner appearance. 🤖 Generated with Claude Code Co-Authored-By: Claude --- docusaurus.config.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus.config.js b/docusaurus.config.js index 44d90be9a..2d29b7ac3 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -246,7 +246,7 @@ async function createConfig() { announcementBar: { id: 'quickstart', content: - 'Missing the Quickstart configurations? Start here!', + 'Looking for the configurations? Start here', backgroundColor: 'var(--announcement-bar-background)', textColor: 'var(--announcement-bar-text-color)', isCloseable: true, From ccaf23acb05d170a06a4aebe8bbe9c83df17b441 Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Wed, 29 Oct 2025 15:28:59 -0500 Subject: [PATCH 11/14] Add right margin to inline paragraphs in admonitions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Admonitions use display: inline on paragraphs to save vertical space, but paragraphs were running together without spacing between them. Added margin-right: 0.5em to .theme-admonition > div p to ensure proper spacing between inline paragraphs while maintaining the compact layout. Fixes the issue where text like 'the configuration.All our tools' appeared as one continuous string. 🤖 Generated with Claude Code Co-Authored-By: Claude --- src/css/admonitions.css | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/css/admonitions.css b/src/css/admonitions.css index d8107514a..5437a1c14 100644 --- a/src/css/admonitions.css +++ b/src/css/admonitions.css @@ -45,3 +45,7 @@ html[data-theme='dark'] .admonitionContent_node_modules-\@docusaurus-theme-class margin-right: 0.5em; } +.theme-admonition > div p { + margin-right: 0.5em; +} + From 668ce6a871c393ca0a9c9d6e2bf86d0af0aa6ea5 Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Thu, 30 Oct 2025 11:48:13 -0500 Subject: [PATCH 12/14] Move Prerequisites admonition to bottom of Prerequisites section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The large Prerequisites admonition was taking up too much above-the-fold space when users first land on the page. Moved it from the top of the page to the end of the Prerequisites section (after 'Start your Geodesic shell before continuing') where it's more contextual and doesn't dominate the initial view. Users now see: 1. Intro text about Cold Start 2. First Time Using Atmos note 3. Quick overview table 4. Prerequisites section 5. THEN the detailed prerequisites admonition This provides better progressive disclosure and doesn't overwhelm new visitors. 🤖 Generated with Claude Code Co-Authored-By: Claude --- .../accounts/prepare-aws-organization.mdx | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/layers/accounts/prepare-aws-organization.mdx b/docs/layers/accounts/prepare-aws-organization.mdx index 36bd7988f..a3ccb9bac 100644 --- a/docs/layers/accounts/prepare-aws-organization.mdx +++ b/docs/layers/accounts/prepare-aws-organization.mdx @@ -10,18 +10,6 @@ import Note from '@site/src/components/Note'; The Cold Start involves more manual steps than other layers. Read through the following steps and see [the detailed documentation](/layers/accounts/tutorials/manual-configuration/) for edge cases. -:::caution Prerequisites - -**Before following this guide**, ensure you have: - -1. ✅ **Purchased Quickstart or Jumpstart** - This guide references stack configurations (`stacks/catalog/account.yaml`) that are only provided with our paid packages -2. ✅ **Completed the kickoff call** - Your configurations should be customized to your design decisions -3. ✅ **Set up your infrastructure repository** - See [Create Repository](/layers/project/create-repository) - -**Looking for the configurations? [Start here](/intro/path)** - You'll get stuck at the "Check the configuration of the 'account' in the stack catalog" step because that file won't exist without them. - -::: - This guide assumes familiarity with [Atmos](https://atmos.tools), our infrastructure orchestration tool. If you're new to Atmos: @@ -54,6 +42,18 @@ Follow the [prerequisites steps in the How-to Get Started guide](/layers/project Start your Geodesic shell before continuing. +:::caution Prerequisites + +**Before following this guide**, ensure you have: + +1. ✅ **Purchased Quickstart or Jumpstart** - This guide references stack configurations (`stacks/catalog/account.yaml`) that are only provided with our paid packages +2. ✅ **Completed the kickoff call** - Your configurations should be customized to your design decisions +3. ✅ **Set up your infrastructure repository** - See [Create Repository](/layers/project/create-repository) + +**Looking for the configurations? [Start here](/intro/path)** - You'll get stuck at the "Check the configuration of the 'account' in the stack catalog" step because that file won't exist without them. + +::: + ## Before Running Terraform (ClickOps) From 36d045c5b439fb5ed09626295e5e49dfaf078ad1 Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Thu, 30 Oct 2025 12:02:22 -0500 Subject: [PATCH 13/14] Fix Prerequisites admonition: remove redundant numbering and update wording MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two changes: 1. Removed numbered list (1. 2. 3.) - keeping only checkmark emojis - Using both numbers and checkmarks was redundant - Each item now on its own line with just ✅ prefix - Cleaner visual presentation 2. Changed 'should be customized' to 'will be customized' - More assertive/definitive language - Reflects that customization is guaranteed, not conditional 🤖 Generated with Claude Code Co-Authored-By: Claude --- docs/layers/accounts/prepare-aws-organization.mdx | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/layers/accounts/prepare-aws-organization.mdx b/docs/layers/accounts/prepare-aws-organization.mdx index a3ccb9bac..03e9c0e11 100644 --- a/docs/layers/accounts/prepare-aws-organization.mdx +++ b/docs/layers/accounts/prepare-aws-organization.mdx @@ -46,9 +46,11 @@ Start your Geodesic shell before continuing. **Before following this guide**, ensure you have: -1. ✅ **Purchased Quickstart or Jumpstart** - This guide references stack configurations (`stacks/catalog/account.yaml`) that are only provided with our paid packages -2. ✅ **Completed the kickoff call** - Your configurations should be customized to your design decisions -3. ✅ **Set up your infrastructure repository** - See [Create Repository](/layers/project/create-repository) +✅ **Purchased Quickstart or Jumpstart** - This guide references stack configurations (`stacks/catalog/account.yaml`) that are only provided with our paid packages + +✅ **Completed the kickoff call** - Your configurations will be customized to your design decisions + +✅ **Set up your infrastructure repository** - See [Create Repository](/layers/project/create-repository) **Looking for the configurations? [Start here](/intro/path)** - You'll get stuck at the "Check the configuration of the 'account' in the stack catalog" step because that file won't exist without them. From 57107b04e15298389834dd8e43ba3ed7273c781e Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Thu, 30 Oct 2025 12:03:25 -0500 Subject: [PATCH 14/14] Change admonition title from 'Prerequisites' to 'Before You Begin' MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The page had two 'Prerequisites' headings which was confusing: - Section heading: ## Prerequisites - Admonition title: PREREQUISITES Changed the admonition title to 'Before You Begin' to differentiate it from the section heading and make it clear this is a different type of information (Quickstart requirements vs general prerequisites). 🤖 Generated with Claude Code Co-Authored-By: Claude --- docs/layers/accounts/prepare-aws-organization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/layers/accounts/prepare-aws-organization.mdx b/docs/layers/accounts/prepare-aws-organization.mdx index 03e9c0e11..f4da3a583 100644 --- a/docs/layers/accounts/prepare-aws-organization.mdx +++ b/docs/layers/accounts/prepare-aws-organization.mdx @@ -42,7 +42,7 @@ Follow the [prerequisites steps in the How-to Get Started guide](/layers/project Start your Geodesic shell before continuing. -:::caution Prerequisites +:::caution Before You Begin **Before following this guide**, ensure you have: