diff --git a/changelog/.gitkeep b/changelog/.gitignore similarity index 100% rename from changelog/.gitkeep rename to changelog/.gitignore diff --git a/docs/best-practices/.workstation-best-practices.md b/docs/best-practices/.workstation-best-practices.mdx similarity index 100% rename from docs/best-practices/.workstation-best-practices.md rename to docs/best-practices/.workstation-best-practices.mdx diff --git a/docs/best-practices/best-practices.mdx b/docs/best-practices/best-practices.mdx new file mode 100644 index 000000000..315964939 --- /dev/null +++ b/docs/best-practices/best-practices.mdx @@ -0,0 +1,3 @@ +> Physics is the law, everything else is a recommendation. +> Anyone can break laws created by people, but I have yet to see anyone break the laws of physics. +>

— **Elon Musk**

 diff --git a/docs/best-practices/editor-config.md b/docs/best-practices/developer/editor-config.mdx similarity index 100% rename from docs/best-practices/editor-config.md rename to docs/best-practices/developer/editor-config.mdx diff --git a/docs/best-practices/github-sign-your-commits-with-ssh.md b/docs/best-practices/developer/github-sign-your-commits-with-ssh.mdx similarity index 100% rename from docs/best-practices/github-sign-your-commits-with-ssh.md rename to docs/best-practices/developer/github-sign-your-commits-with-ssh.mdx diff --git a/docs/best-practices/docker-best-practices.md b/docs/best-practices/docker.mdx similarity index 92% rename from docs/best-practices/docker-best-practices.md rename to docs/best-practices/docker.mdx index 1a03ea026..844a43046 100644 --- a/docs/best-practices/docker-best-practices.md +++ b/docs/best-practices/docker.mdx @@ -1,7 +1,13 @@ --- title: Docker Best Practices +site_title: Docker description: "Collection of some of our docker-specific best practices." --- +import Intro from '@site/src/components/Intro'; + + +Docker best practices that we follow are listed here. Note that this is not an exhaustive list, but rather some of the ones that have stood out for us as practical ways of leveraging Docker together with the Cloud Posse reference architecture. + ## Inheritance diff --git a/docs/best-practices/github-feature-branches.md b/docs/best-practices/github-feature-branches.mdx similarity index 90% rename from docs/best-practices/github-feature-branches.md rename to docs/best-practices/github-feature-branches.mdx index 4adcb242d..88e5c7cd2 100644 --- a/docs/best-practices/github-feature-branches.md +++ b/docs/best-practices/github-feature-branches.mdx @@ -1,7 +1,12 @@ --- title: Feature Branches -description: "The Feature Branch Workflow is a requirement for CI/CD. It's a process by which all feature development takes place in a dedicated branch instead of the `master` branch. This makes it easy for multiple developers to collaborate on a particular feature while at the same time ensuring that the master branch remains stable." +description: "Use separate branches for developing specific features." --- +import Intro from '@site/src/components/Intro' + + +The Feature Branch Workflow is a requirement for CI/CD. It's a process by which all feature development takes place in a dedicated branch instead of the `master` branch. This makes it easy for multiple developers to collaborate on a particular feature while at the same time ensuring that the master branch remains stable." + ## Problem diff --git a/docs/best-practices/github-pull-requests.md b/docs/best-practices/github-pull-requests.mdx similarity index 100% rename from docs/best-practices/github-pull-requests.md rename to docs/best-practices/github-pull-requests.mdx diff --git a/docs/best-practices/github-best-practices.md b/docs/best-practices/github.mdx similarity index 100% rename from docs/best-practices/github-best-practices.md rename to docs/best-practices/github.mdx diff --git a/docs/best-practices/make-best-practices.md b/docs/best-practices/makefile.mdx similarity index 91% rename from docs/best-practices/make-best-practices.md rename to docs/best-practices/makefile.mdx index 6521744a6..a2bba535e 100644 --- a/docs/best-practices/make-best-practices.md +++ b/docs/best-practices/makefile.mdx @@ -7,6 +7,11 @@ tags: - Makefile - best-practices --- +import Intro from '@site/src/components/Intro'; + + +GNU Makefiles are a convenient way for last-mile automation across multiple tool sets. We used to rely more heavily on Makefiles, but have since transitioned our usage predominantly into Atmos itself. That said, here is a collection of some of the best practices we’ve amassed over the years from extensively leveraging Makefiles. + ## Avoid using Evals diff --git a/docs/best-practices/markdown-best-practices.md b/docs/best-practices/markdown.mdx similarity index 83% rename from docs/best-practices/markdown-best-practices.md rename to docs/best-practices/markdown.mdx index cc83e5650..0153d0381 100644 --- a/docs/best-practices/markdown-best-practices.md +++ b/docs/best-practices/markdown.mdx @@ -2,6 +2,11 @@ title: Markdown Best Practices description: "Using Markdown is essential for clear communication on mediums such as GitHub, Slack or just plain text. Here are some of our recommendations on when to use certain conventions." --- +import Intro from '@site/src/components/Intro'; + + +Most of our documentation is provided in Markdown format. Here are some of the conventions and best practices we follow when writing Markdown. Please note that we use the term Markdown loosely to refer to GitHub-flavored Markdown, and we also use quite a bit of MDX, which is what all of our documentation in Docusaurus uses. + ![Markdown Logo](/assets/13f56b6-markdown.png) diff --git a/docs/best-practices/password-management.md b/docs/best-practices/password-management.mdx similarity index 100% rename from docs/best-practices/password-management.md rename to docs/best-practices/password-management.mdx diff --git a/docs/best-practices/project-management-gost-framework.md b/docs/best-practices/project-management-gost-framework.mdx similarity index 100% rename from docs/best-practices/project-management-gost-framework.md rename to docs/best-practices/project-management-gost-framework.mdx diff --git a/docs/best-practices/project-management-managers-vs-makers.md b/docs/best-practices/project-management-managers-vs-makers.mdx similarity index 100% rename from docs/best-practices/project-management-managers-vs-makers.md rename to docs/best-practices/project-management-managers-vs-makers.mdx diff --git a/docs/best-practices/project-management-raci-matrix.md b/docs/best-practices/project-management-raci-matrix.mdx similarity index 100% rename from docs/best-practices/project-management-raci-matrix.md rename to docs/best-practices/project-management-raci-matrix.mdx diff --git a/docs/best-practices/semver.md b/docs/best-practices/semver.mdx similarity index 100% rename from docs/best-practices/semver.md rename to docs/best-practices/semver.mdx diff --git a/docs/best-practices/terraform-best-practices.md b/docs/best-practices/terraform.mdx similarity index 100% rename from docs/best-practices/terraform-best-practices.md rename to docs/best-practices/terraform.mdx diff --git a/docs/category/README.md b/docs/category/README.mdx similarity index 100% rename from docs/category/README.md rename to docs/category/README.mdx diff --git a/docs/category/how-to/index.md b/docs/category/how-to/index.mdx similarity index 100% rename from docs/category/how-to/index.md rename to docs/category/how-to/index.mdx diff --git a/docs/category/legacy/index.md b/docs/category/legacy/index.mdx similarity index 100% rename from docs/category/legacy/index.md rename to docs/category/legacy/index.mdx diff --git a/docs/community/code-of-conduct.md b/docs/community/code-of-conduct.mdx similarity index 100% rename from docs/community/code-of-conduct.md rename to docs/community/code-of-conduct.mdx diff --git a/docs/community/contact-us.md b/docs/community/contact-us.mdx similarity index 100% rename from docs/community/contact-us.md rename to docs/community/contact-us.mdx diff --git a/docs/community/contribute/automated-testing.md b/docs/community/contribute/automated-testing.mdx similarity index 100% rename from docs/community/contribute/automated-testing.md rename to docs/community/contribute/automated-testing.mdx diff --git a/docs/community/contribute/code-reviews.md b/docs/community/contribute/code-reviews.mdx similarity index 100% rename from docs/community/contribute/code-reviews.md rename to docs/community/contribute/code-reviews.mdx diff --git a/docs/community/contribute/contributor-tips.md b/docs/community/contribute/contributor-tips.mdx similarity index 100% rename from docs/community/contribute/contributor-tips.md rename to docs/community/contribute/contributor-tips.mdx diff --git a/docs/community/contribute/our-github.md b/docs/community/contribute/our-github.mdx similarity index 100% rename from docs/community/contribute/our-github.md rename to docs/community/contribute/our-github.mdx diff --git a/docs/community/faq.md b/docs/community/faq.mdx similarity index 100% rename from docs/community/faq.md rename to docs/community/faq.mdx diff --git a/docs/community/slack.mdx b/docs/community/slack.mdx index b32548415..dc8972a81 100644 --- a/docs/community/slack.mdx +++ b/docs/community/slack.mdx @@ -23,5 +23,3 @@ Cloud Posse has a great community of active users who are more than willing to h allowtransparency="true" style={{ borderRadius: '6px', display: 'flex', marginRight: 'auto', marginLeft: 'auto'}} > - - diff --git a/docs/community/support.mdx b/docs/community/support.mdx index 6dde76e3d..9be0ee0bd 100644 --- a/docs/community/support.mdx +++ b/docs/community/support.mdx @@ -1,46 +1,20 @@ --- -title: "FAQ" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1176371788/FAQ +title: "Community Support" +sidebar_label: "Support" sidebar_position: 100 -custom_edit_url: https://github.com/cloudposse/refarch-scaffold/tree/main/docs/docs/faq.md --- # FAQ -Here are some quick answers to frequently asked questions. See also our [Troubleshooting](/reference-architecture/reference/troubleshooting) . +Here are some quick answers to frequently asked questions. See also our [Troubleshooting](/reference-architecture/reference/troubleshooting). ## Documentation ### How do I request additional documentation? -Please request documentation via your given team's Slack channel. +Please request documentation by opening a [GitHub Issue](https://github.com/cloudposse/docs/issues). Please provide as much detail as possible about what you would like to see documented and what related documents you discovered that were not helpful. -### What’s the difference between this documentation and our public documentation? - -Our [public documentation](/) is written more generally since we cannot make any assumptions about how the public is using our tools. The reference architecture documentation is more opinionated on how we use our tools, for example, how we layout stacks, components, etc. - -## Terraform - -### How to upgrade Terraform? - -See [How to Switch Versions of Terraform](/reference-architecture/how-to-guides/tutorials/how-to-switch-versions-of-terraform) for a more complete guide. - -TL;DR: - -- Note the version you want to use -- Make sure the version is available in [cloudposse/packages](https://github.com/cloudposse/packages/pulls?q=terraform) to see if the version desired is in a merged PR for terraform -- Make sure the version is available in Spacelift by editing an existing stack and see if the new version is available -- Update Terraform in `Dockerfile` -- Update Terraform in `.github/workflows/pre-commit.yaml` github action -- Update Terraform in `components/terraform/spacelift/default.auto.tfvars` - -### How to use `context.tf`? - -Copy this file from `https://github.com/cloudposse/terraform-null-label/blob/master/exports/context.tf` and then place it in your Terraform module to automatically get Cloud Posse's standard configuration inputs suitable for passing to Cloud Posse modules. - -``` -curl -sL https://raw.githubusercontent.com/cloudposse/terraform-null-label/master/exports/context.tf -o context.tf -``` - -Modules should access the whole context as `module.this.context` to get the input variables with nulls for defaults, for example `context = module.this.context`, and access individual variables as `module.this.`, with final values filled in. +### Can I pay for support? +Yes, we offer paid support via [GitHub Sponsorships](https://github.com/sponsors/cloudposse). + diff --git a/docs/generated/components/index.mdx b/docs/generated/components/index.mdx new file mode 100644 index 000000000..dceb19680 --- /dev/null +++ b/docs/generated/components/index.mdx @@ -0,0 +1,12 @@ +--- +title: Atmos Components +sidebar_label: Atmos Components +description: Atmos Components +sidebar_position: 0 +--- + +This is a collection of reusable Atmos Components. + +## Introduction + +In this library you'll find real-world examples of how we've implemented reusable Atmos Components. diff --git a/docs/generated/components/library/aws/account/README.md b/docs/generated/components/library/aws/account/README.mdx similarity index 100% rename from docs/generated/components/library/aws/account/README.md rename to docs/generated/components/library/aws/account/README.mdx diff --git a/docs/generated/github-actions/index.mdx b/docs/generated/github-actions/index.mdx index 4e3a4ad6b..9e78bf0df 100644 --- a/docs/generated/github-actions/index.mdx +++ b/docs/generated/github-actions/index.mdx @@ -4,9 +4,8 @@ sidebar_label: Overview of GitHub Actions description: GitHub Actions sidebar_position: 0 --- +import Intro from '@site/src/components/Intro' -This is a collection of reusable GitHub Actions. - -## Introduction - -In this library you'll find real-world examples of how we've implemented reusable GitHub Actions to solve common CI/CD challenges. + +In this library you'll find all the GitHub Actions we've implemented to solve common CI/CD challenges. + diff --git a/docs/generated/github-actions/library/actions/docker-build-push/README.md b/docs/generated/github-actions/library/actions/docker-build-push/README.mdx similarity index 100% rename from docs/generated/github-actions/library/actions/docker-build-push/README.md rename to docs/generated/github-actions/library/actions/docker-build-push/README.mdx diff --git a/docs/generated/modules/index.mdx b/docs/generated/modules/index.mdx new file mode 100644 index 000000000..7ca359862 --- /dev/null +++ b/docs/generated/modules/index.mdx @@ -0,0 +1,12 @@ +--- +title: Terraform Modules +sidebar_label: Terraform Modules +description: Terraform Modules +sidebar_position: 0 +--- + +This is a collection of reusable Terraform Modules. + +## Introduction + +In this library you'll find real-world examples of how we've implemented reusable Terraform Modules. diff --git a/docs/generated/modules/library/aws/dms/README.md b/docs/generated/modules/library/aws/dms/README.mdx similarity index 100% rename from docs/generated/modules/library/aws/dms/README.md rename to docs/generated/modules/library/aws/dms/README.mdx diff --git a/docs/layers/accounts/accounts.mdx b/docs/layers/accounts/accounts.mdx index a5740a432..8eed4f297 100644 --- a/docs/layers/accounts/accounts.mdx +++ b/docs/layers/accounts/accounts.mdx @@ -1,31 +1,32 @@ --- -title: "Accounts" +title: "Account Management" +sidebar_label: "Accounts" sidebar_class_name: hidden --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; +import ReactPlayer from "react-player"; -# Account Management - -This chapter is intended to present how Cloud Posse has designed AWS Account architecture and management. We will -explain how Cloud Posse provisions and manages AWS Accounts, the reasoning behind our decisions, and how this -architecture will better align your organization with the -[AWS Well-Architected Framework](https://docs.aws.amazon.com/pdfs/wellarchitected/latest/userguide/wellarchitected-ug.pdf) + +This chapter presents how Cloud Posse designs and manages AWS Account architectures. We will explain how Cloud Posse provisions and manages AWS Accounts, the reasoning behind our decisions, and how this architecture will better align your organization with the [AWS Well-Architected Framework](https://docs.aws.amazon.com/pdfs/wellarchitected/latest/userguide/wellarchitected-ug.pdf) + -import ReactPlayer from "react-player"; + +- Why to leverage multiple AWS accounts within an AWS Organization +- How we organize accounts into organizational units (OUs) to manage access and apply Service Control Policies (SCPs) to provide guard rails +- The set of components we use to provision, configure, and manage AWS accounts, including account-level settings, service control policies, and Terraform state backends, using native Terraform with Atmos + - +
+ +
AI generated voice
+
## 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. +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. -The AWS Well-Architected Framework provides several foundational recommendations, one of which is to distribute -workloads across multiple AWS accounts. However, the framework does not prescribe how this should be achieved. AWS -offers resources such as Control Tower or Account Factory for provisioning accounts, but these resources have some -limitations. The primary issue is that they cannot be managed with Terraform, which means that manual effort is required -to use them. +The AWS Well-Architected Framework provides several foundational recommendations, one of which is to distribute workloads across multiple AWS accounts. However, the framework does not prescribe how this should be achieved. AWS offers resources such as Control Tower or Account Factory for provisioning accounts, but these resources have some limitations. The primary issue is that they cannot be managed with Terraform, which means that manual effort is required to use them. ## Our Solution diff --git a/docs/layers/accounts/cloudtrail.mdx b/docs/layers/accounts/cloudtrail.mdx index 291221f4c..c44a23ca9 100644 --- a/docs/layers/accounts/cloudtrail.mdx +++ b/docs/layers/accounts/cloudtrail.mdx @@ -1,9 +1,10 @@ --- -title: "Deploy CloudTrail" +title: "Deploy CloudTrail and ECR" +sidebar_label: "Deploy CloudTrail" sidebar_position: 30 --- - -# Deploy CloudTrail and ECR +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; Now that all the accounts have been deployed, we need to finalize the setup of the accounts. This includes deploying CloudTrail and ECR. These foundational components will be necessary to move forward with the rest of the deployment. diff --git a/docs/layers/accounts/deploy-accounts.mdx b/docs/layers/accounts/deploy-accounts.mdx index 3d3129224..3271a42aa 100644 --- a/docs/layers/accounts/deploy-accounts.mdx +++ b/docs/layers/accounts/deploy-accounts.mdx @@ -1,9 +1,10 @@ --- -title: "Deploy Accounts" +title: "Deploying AWS Accounts" +sidebar_label: "Deploy Accounts" sidebar_position: 20 --- - -# Deploying AWS Accounts +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; | Steps | | | ------------------------- | ---------------------------------------------------- | diff --git a/docs/layers/accounts/design-decisions/decide-on-aws-account-flavors-and-organizational-units.mdx b/docs/layers/accounts/design-decisions/decide-on-aws-account-flavors-and-organizational-units.mdx index fc4a87385..8a7a526e5 100644 --- a/docs/layers/accounts/design-decisions/decide-on-aws-account-flavors-and-organizational-units.mdx +++ b/docs/layers/accounts/design-decisions/decide-on-aws-account-flavors-and-organizational-units.mdx @@ -1,36 +1,28 @@ --- title: "Decide on AWS Account Flavors and Organizational Units" +sidebar_label: "AWS Account Flavors and OUs" +description: "Decide how to organize workloads for isolation and management" refarch_id: REFARCH-55 --- - -# Decide on AWS Account Flavors and Organizational Units +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Context and Problem Statement -The -[AWS Well-Architected Framework](https://docs.aws.amazon.com/wellarchitected/latest/userguide/wellarchitected-ug.pdf) -recommends splitting workloads across multiple AWS accounts. +The [AWS Well-Architected Framework](https://docs.aws.amazon.com/wellarchitected/latest/userguide/wellarchitected-ug.pdf) recommends splitting workloads across multiple AWS accounts. When moving to an infrastructure-as-code (IaC) model of infrastructure provisioning, many of the same best practices that apply to regular software development should apply to IaC. Part of that is not making changes to a production -environment that hasn't been tested in a staging environment. If the production and staging environments are in the same -account, then there are insufficient assurances/guarantees/protections in place to prevent breaking production. +environment that hasn't been tested in a staging environment. If the production and staging environments are in the same account, then there are insufficient assurances/guarantees/protections in place to prevent breaking production. -Constructs like VPCs only provide network-level isolation, but not IAM-level isolation. And within a single AWS account, -there’s no practical way to manage IAM-level boundaries between multiple stages like dev/staging/prod. For example, to -provision most terraform modules, “administrative” level access is required because provisioning any IAM roles requires -admin privileges. That would mean that a developer needs to be an “admin” in order to iterate on a module. +Constructs like VPCs only provide network-level isolation, but not IAM-level isolation. And within a single AWS account, there’s no practical way to manage IAM-level boundaries between multiple stages like dev/staging/prod. For example, to provision most terraform modules, “administrative” level access is required because provisioning any IAM roles requires admin privileges. That would mean that a developer needs to be an “admin” in order to iterate on a module. -Leveraging multiple AWS accounts within an AWS Organization is the _only way_ to satisfy these requirements. Guardrails -can be be in place to restrict what can happen in an account and by whom. +Leveraging multiple AWS accounts within an AWS Organization is the _only way_ to satisfy these requirements. Guardrails can be be in place to restrict what can happen in an account and by whom. We must decide how to organize the flat account structure into organizational units. Organizational units can then leverage things like Service Control Policies to restrict what can happen inside the accounts. -Multiple AWS accounts should be used to provide a higher degree of isolation by segmenting/isolating workloads. There is -no additional cost for operating multiple AWS accounts. It does add additional overhead to manage as a standard set of -components will to manage the account. AWS support only applies to one account, so it may need to be purchased for each -account unless the organization upgrades to Enterprise Support. +Multiple AWS accounts should be used to provide a higher degree of isolation by segmenting/isolating workloads. There is no additional cost for operating multiple AWS accounts. It does add additional overhead to manage as a standard set of components will to manage the account. AWS support only applies to one account, so it may need to be purchased for each account unless the organization upgrades to Enterprise Support. Multiple AWS accounts are all managed underneath an AWS Organization and organized into multiple organizational units (OUs). Service Control Policies can restrict what runs in an account and place boundaries around an account that even diff --git a/docs/layers/accounts/design-decisions/decide-on-aws-organization-strategy.mdx b/docs/layers/accounts/design-decisions/decide-on-aws-organization-strategy.mdx index 6a06c4cca..a9f9eb868 100644 --- a/docs/layers/accounts/design-decisions/decide-on-aws-organization-strategy.mdx +++ b/docs/layers/accounts/design-decisions/decide-on-aws-organization-strategy.mdx @@ -1,7 +1,11 @@ --- title: "Decide on AWS Organization Strategy" +sidebar_label: "AWS Organization Strategy" +description: Decide whether to create or reuse AWS Organizations refarch_id: REFARCH-471 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # Decide on AWS Organization Strategy diff --git a/docs/layers/accounts/design-decisions/decide-on-aws-support.mdx b/docs/layers/accounts/design-decisions/decide-on-aws-support.mdx index fdfda2400..9e47c2637 100644 --- a/docs/layers/accounts/design-decisions/decide-on-aws-support.mdx +++ b/docs/layers/accounts/design-decisions/decide-on-aws-support.mdx @@ -1,12 +1,16 @@ --- title: "Decide on AWS Support" +sidebar_label: "AWS Support" +description: "Decide which accounts need AWS Support" refarch_id: REFARCH-417 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; -# Decide on AWS Support - + AWS Support is always enabled on a per-account basis. With an AWS Enterprise Agreement, AWS support is already included from a billing perspective for all accounts, but it still needs to be enabled on a per-account basis. + :::caution diff --git a/docs/layers/accounts/design-decisions/decide-on-email-address-format-for-aws-accounts.mdx b/docs/layers/accounts/design-decisions/decide-on-email-address-format-for-aws-accounts.mdx index 5aca5ee5b..542a5f3a5 100644 --- a/docs/layers/accounts/design-decisions/decide-on-email-address-format-for-aws-accounts.mdx +++ b/docs/layers/accounts/design-decisions/decide-on-email-address-format-for-aws-accounts.mdx @@ -1,7 +1,11 @@ --- title: "Decide on Email Address Format for AWS Accounts" +sidebar_label: "Email Address Format for AWS Accounts" +description: "Decide what emails will be used for AWS Accounts" refarch_id: REFARCH-51 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # Decide on Email Address Format for AWS Accounts diff --git a/docs/layers/accounts/design-decisions/decide-on-mfa-solution-for-aws-root-accounts.mdx b/docs/layers/accounts/design-decisions/decide-on-mfa-solution-for-aws-root-accounts.mdx index 0911bc951..db7e3a2bf 100644 --- a/docs/layers/accounts/design-decisions/decide-on-mfa-solution-for-aws-root-accounts.mdx +++ b/docs/layers/accounts/design-decisions/decide-on-mfa-solution-for-aws-root-accounts.mdx @@ -1,9 +1,11 @@ --- title: "Decide on MFA Solution for AWS Root Accounts" +sidebar_label: "MFA Solution for AWS Root Accounts" +description: "Decide on MFA Solution for AWS Root Accounts" refarch_id: REFARCH-50 --- - -# Decide on MFA Solution for AWS Root Accounts +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; We need an MFA solution for protecting the master AWS accounts. The two most common options are `TOTP` and U2F (universal authenticator devices). diff --git a/docs/layers/accounts/design-decisions/decide-on-terraform-state-backend-architecture.mdx b/docs/layers/accounts/design-decisions/decide-on-terraform-state-backend-architecture.mdx index 827ad9436..e2f7da6d6 100644 --- a/docs/layers/accounts/design-decisions/decide-on-terraform-state-backend-architecture.mdx +++ b/docs/layers/accounts/design-decisions/decide-on-terraform-state-backend-architecture.mdx @@ -1,9 +1,11 @@ --- title: "Decide on Terraform State Backend Architecture" +sidebar_label: "Terraform State Backend Architecture" +description: Decide how to organize Terraform State across accounts refarch_id: REFARCH-522 --- - -# Decide on Terraform State Backend Architecture +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Context and Problem Statement diff --git a/docs/layers/accounts/initialize-tfstate.mdx b/docs/layers/accounts/initialize-tfstate.mdx index 72d71cd23..48ecbc1d9 100644 --- a/docs/layers/accounts/initialize-tfstate.mdx +++ b/docs/layers/accounts/initialize-tfstate.mdx @@ -1,9 +1,10 @@ --- -title: "Initialize Terraform Backend" +title: "Initializing the Terraform State S3 Backend" +sidebar_label: "Initialize Terraform Backend" sidebar_position: 10 --- - -# Initializing the Terraform State S3 Backend +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; | Steps | | | ------------------------- | ----------------------------------------- | diff --git a/docs/layers/accounts/prepare-aws-organization.mdx b/docs/layers/accounts/prepare-aws-organization.mdx index 071130c9e..50a6e82ec 100644 --- a/docs/layers/accounts/prepare-aws-organization.mdx +++ b/docs/layers/accounts/prepare-aws-organization.mdx @@ -1,9 +1,10 @@ --- -title: "Prepare your AWS Organization" +title: "Preparing Your AWS Organization" +sidebar_label: "Prepare your AWS Organization" sidebar_position: 0 --- - -# Preparing Your AWS Organization +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; :::tip Cold Start diff --git a/docs/layers/accounts/tutorials/cold-start.mdx b/docs/layers/accounts/tutorials/cold-start.mdx index 49d5c0544..602e4519e 100644 --- a/docs/layers/accounts/tutorials/cold-start.mdx +++ b/docs/layers/accounts/tutorials/cold-start.mdx @@ -3,23 +3,20 @@ title: "Overview of the Cold Start" sidebar_position: 00 refarch_id: REFARCH-313 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # Implement AWS Cold Start These documents explain the complete cold-start process required to initialize a net-new AWS Organization using the SweetOps process by Cloud Posse. The cold-start process is the first step in setting up a new AWS Organization and is -the most involved part of the process. It requires a lot of manual steps and remediations to bootstrap all the tooling -and configurations before we can start to do anything meaningful. Please take your time to read through the entire -process before starting and reach out if you have any questions! +the most involved part of the process. It requires a lot of manual steps and remediations to bootstrap all the tooling and configurations before we can start to do anything meaningful. Please take the time to read through the entire process before starting, and reach out if you have any questions! ## Problem -
-AWS provides poor documentation for all the steps required for setting up a new AWS Organization. Once the Organization -is set up, there’s _a lot_ of manual steps and remediations required to bootstrap all the tooling and configurations -before we can start to do anything meaningful. +AWS provides poor documentation for all the steps required for setting up a new AWS Organization. Once the Organization is set up, there’s _a lot_ of manual steps and remediations required to bootstrap all the tooling and configurations before we can start to do anything meaningful. ## Solution diff --git a/docs/layers/accounts/tutorials/deprecated-cold-start-components.md b/docs/layers/accounts/tutorials/deprecated-cold-start-components.mdx similarity index 97% rename from docs/layers/accounts/tutorials/deprecated-cold-start-components.md rename to docs/layers/accounts/tutorials/deprecated-cold-start-components.mdx index ed699e6d2..d0b01977e 100644 --- a/docs/layers/accounts/tutorials/deprecated-cold-start-components.md +++ b/docs/layers/accounts/tutorials/deprecated-cold-start-components.mdx @@ -1,11 +1,10 @@ --- title: "Deprecated Cold Start Components" --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; -# Deprecated Cold Start Components - -This page serves as a tombstone for deprecated components included in the cold start. Here you will find documentation -on how you could set those components up. +This page serves as a tombstone for deprecated components included in the cold start. Here you will find documentation on how you could set those components up. | **Deprecated Component** | **Replaced By:** | | ------------------------ | ---------------- | diff --git a/docs/layers/accounts/tutorials/how-to-add-a-new-organizational-unit.md b/docs/layers/accounts/tutorials/how-to-add-a-new-organizational-unit.mdx similarity index 89% rename from docs/layers/accounts/tutorials/how-to-add-a-new-organizational-unit.md rename to docs/layers/accounts/tutorials/how-to-add-a-new-organizational-unit.mdx index 1d4a9a788..c4e5d3f0c 100644 --- a/docs/layers/accounts/tutorials/how-to-add-a-new-organizational-unit.md +++ b/docs/layers/accounts/tutorials/how-to-add-a-new-organizational-unit.mdx @@ -1,8 +1,9 @@ --- title: "Add a new Organizational Unit" +sidebar_label: "How to add a new Organizational Unit" --- - -# How to add a new Organizational Unit +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem diff --git a/docs/layers/accounts/tutorials/how-to-add-or-mirror-a-new-region.md b/docs/layers/accounts/tutorials/how-to-add-or-mirror-a-new-region.mdx similarity index 94% rename from docs/layers/accounts/tutorials/how-to-add-or-mirror-a-new-region.md rename to docs/layers/accounts/tutorials/how-to-add-or-mirror-a-new-region.mdx index 97d6e465a..0da896069 100644 --- a/docs/layers/accounts/tutorials/how-to-add-or-mirror-a-new-region.md +++ b/docs/layers/accounts/tutorials/how-to-add-or-mirror-a-new-region.mdx @@ -1,8 +1,9 @@ --- -title: "Add or mirror a new region" +title: "How to add or mirror a new region" +sidebar_label: "Add or mirror a new region" --- - -# How to add or mirror a new region +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; **DRAFT** diff --git a/docs/layers/accounts/tutorials/how-to-adopt-import-legacy-aws-accounts-for-use-with-the-infrast.md b/docs/layers/accounts/tutorials/how-to-adopt-import-legacy-aws-accounts-for-use-with-the-infrast.mdx similarity index 98% rename from docs/layers/accounts/tutorials/how-to-adopt-import-legacy-aws-accounts-for-use-with-the-infrast.md rename to docs/layers/accounts/tutorials/how-to-adopt-import-legacy-aws-accounts-for-use-with-the-infrast.mdx index 7875b405e..901a1ed83 100644 --- a/docs/layers/accounts/tutorials/how-to-adopt-import-legacy-aws-accounts-for-use-with-the-infrast.md +++ b/docs/layers/accounts/tutorials/how-to-adopt-import-legacy-aws-accounts-for-use-with-the-infrast.mdx @@ -1,15 +1,15 @@ --- -title: "Adopt/Import Legacy AWS Accounts" +title: "How to Adopt/Import Legacy AWS Accounts for Use With the Infrastructure Monorepo" +sidebar_label: "Adopt/Import Legacy AWS Accounts" --- - -# How to Adopt/Import Legacy AWS Accounts for Use With the Infrastructure Monorepo +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem Legacy AWS accounts may be owned by an organization (the company, not the AWS organization) but not part of the AWS Organization provisioned by the Infrastructure Monorepo via Atmos. This process is meant to “adopt” or “import” the -accounts in question for use with the Infrastructure Monorepo, so that their infrastructure may be automated via Atmos -and Spacelift. +accounts in question for use with the Infrastructure Monorepo, so that their infrastructure may be automated via Atmos and Spacelift. ## Solution diff --git a/docs/layers/accounts/tutorials/how-to-create-and-setup-aws-accounts.md b/docs/layers/accounts/tutorials/how-to-create-and-setup-aws-accounts.mdx similarity index 94% rename from docs/layers/accounts/tutorials/how-to-create-and-setup-aws-accounts.md rename to docs/layers/accounts/tutorials/how-to-create-and-setup-aws-accounts.mdx index 4848ad0fe..420e61686 100644 --- a/docs/layers/accounts/tutorials/how-to-create-and-setup-aws-accounts.md +++ b/docs/layers/accounts/tutorials/how-to-create-and-setup-aws-accounts.mdx @@ -1,8 +1,9 @@ --- -title: "Create AWS Accounts" +title: "How to Create and Setup AWS Accounts" +sidebar_label: "Create AWS Accounts" --- - -# How to Create and Setup AWS Accounts +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem diff --git a/docs/layers/accounts/tutorials/how-to-create-superadmin-user.md b/docs/layers/accounts/tutorials/how-to-create-superadmin-user.mdx similarity index 97% rename from docs/layers/accounts/tutorials/how-to-create-superadmin-user.md rename to docs/layers/accounts/tutorials/how-to-create-superadmin-user.mdx index 91dcd9191..4c9bbf73a 100644 --- a/docs/layers/accounts/tutorials/how-to-create-superadmin-user.md +++ b/docs/layers/accounts/tutorials/how-to-create-superadmin-user.mdx @@ -1,8 +1,9 @@ --- -title: "Create the SuperAdmin user" +title: "How to Create `SuperAdmin` user" +sidebar_label: "Create the `SuperAdmin` user" --- - -# How to Create SuperAdmin user +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; [REFARCH-73 - Provision SuperAdmin User for Root Level IAM Management](https://cloudposse.atlassian.net/browse/REFARCH-73) diff --git a/docs/layers/accounts/tutorials/how-to-delete-aws-accounts.md b/docs/layers/accounts/tutorials/how-to-delete-aws-accounts.mdx similarity index 97% rename from docs/layers/accounts/tutorials/how-to-delete-aws-accounts.md rename to docs/layers/accounts/tutorials/how-to-delete-aws-accounts.mdx index d23adafeb..29b6d55db 100644 --- a/docs/layers/accounts/tutorials/how-to-delete-aws-accounts.md +++ b/docs/layers/accounts/tutorials/how-to-delete-aws-accounts.mdx @@ -1,8 +1,9 @@ --- -title: "Delete AWS Accounts" +title: "How to Delete AWS Accounts" +sidebar_label: "Delete AWS Accounts" --- - -# How to Delete AWS Accounts +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem diff --git a/docs/layers/accounts/tutorials/how-to-manage-account-settings.md b/docs/layers/accounts/tutorials/how-to-manage-account-settings.mdx similarity index 92% rename from docs/layers/accounts/tutorials/how-to-manage-account-settings.md rename to docs/layers/accounts/tutorials/how-to-manage-account-settings.mdx index 6abbdb6c7..57e677b86 100644 --- a/docs/layers/accounts/tutorials/how-to-manage-account-settings.md +++ b/docs/layers/accounts/tutorials/how-to-manage-account-settings.mdx @@ -1,8 +1,9 @@ --- -title: "Manage Account Settings" +title: "How to manage Account Settings" +sidebar_label: "Manage Account Settings" --- - -# How to manage Account Settings +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem diff --git a/docs/layers/accounts/tutorials/how-to-register-pristine-aws-root-account.md b/docs/layers/accounts/tutorials/how-to-register-pristine-aws-root-account.mdx similarity index 95% rename from docs/layers/accounts/tutorials/how-to-register-pristine-aws-root-account.md rename to docs/layers/accounts/tutorials/how-to-register-pristine-aws-root-account.mdx index a21693f61..f5416a340 100644 --- a/docs/layers/accounts/tutorials/how-to-register-pristine-aws-root-account.md +++ b/docs/layers/accounts/tutorials/how-to-register-pristine-aws-root-account.mdx @@ -1,8 +1,9 @@ --- -title: "Register Pristine AWS Root Account" +title: "How to Register Pristine AWS Root Account" +sidebar_label: "Register Pristine AWS Root Account" --- - -# How to Register Pristine AWS Root Account +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; [REFARCH-60 - Register Pristine AWS Root Account](https://cloudposse.atlassian.net/browse/REFARCH-60) diff --git a/docs/layers/accounts/tutorials/how-to-set-up-aws-email-notifications.md b/docs/layers/accounts/tutorials/how-to-set-up-aws-email-notifications.mdx similarity index 93% rename from docs/layers/accounts/tutorials/how-to-set-up-aws-email-notifications.md rename to docs/layers/accounts/tutorials/how-to-set-up-aws-email-notifications.mdx index ee5e05a60..01d6b1bfa 100644 --- a/docs/layers/accounts/tutorials/how-to-set-up-aws-email-notifications.md +++ b/docs/layers/accounts/tutorials/how-to-set-up-aws-email-notifications.mdx @@ -1,8 +1,9 @@ --- title: "Set Up AWS Email Notifications" +sidebar_label: "How to Set Up AWS Email Notifications" --- - -# How to Set Up AWS Email Notifications +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; :::caution diff --git a/docs/layers/accounts/tutorials/manual-configuration.md b/docs/layers/accounts/tutorials/manual-configuration.mdx similarity index 99% rename from docs/layers/accounts/tutorials/manual-configuration.md rename to docs/layers/accounts/tutorials/manual-configuration.mdx index 991d8b2a2..8986fbc58 100644 --- a/docs/layers/accounts/tutorials/manual-configuration.md +++ b/docs/layers/accounts/tutorials/manual-configuration.mdx @@ -1,9 +1,10 @@ --- -title: "Detailed Cold Start Implementation" +title: "Cold Start Implementation In Depth" +sidebar_label: "Detailed Cold Start" sidebar_position: 10 --- - -# Cold Start Implementation In Depth +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; These steps are part of laying the foundation for your environment and are necessary prerequisites for using Terraform. diff --git a/docs/layers/accounts/tutorials/terraform-s3-state.md b/docs/layers/accounts/tutorials/terraform-s3-state.mdx similarity index 90% rename from docs/layers/accounts/tutorials/terraform-s3-state.md rename to docs/layers/accounts/tutorials/terraform-s3-state.mdx index 91679dd26..ee0e51fed 100644 --- a/docs/layers/accounts/tutorials/terraform-s3-state.md +++ b/docs/layers/accounts/tutorials/terraform-s3-state.mdx @@ -1,9 +1,10 @@ --- -title: "Structure of Terraform S3 State" +title: "Structure of Terraform S3 State Backend Bucket" +sidebar_label: "Terraform S3 State" sidebar_position: 20 --- - -# Structure of Terraform S3 State Backend Bucket +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; Understand the anatomy of a Terraform S3 state backend bucket and how workspaces, key prefixes and buckets are used. @@ -18,10 +19,7 @@ From HashiCorp ### The `backend.tf.json` File This file is programmatically generated by [Atmos](/fundamentals/atmos) using all the capabilities of -[Stacks](/fundamentals/stacks) to deep merge. Every component defines a `backend.tf.json`, which is what distinguishes -it as a root module (as opposed to a terraform child module). The backend tells terraform where to access the last known -deployed state of infrastructure for the given component. Since the backend is stored in S3, it’s easily accessed by in -a distributed manner by anyone running terraform. +[Stacks](/fundamentals/stacks) to deep merge. Every component defines a `backend.tf.json`, which is what distinguishes it as a root module (as opposed to a terraform child module). The backend tells terraform where to access the last known deployed state of infrastructure for the given component. Since the backend is stored in S3, it’s easily accessed by in a distributed manner by anyone running terraform. :::info diff --git a/docs/layers/alerting/08-alerting.md b/docs/layers/alerting/08-alerting.mdx similarity index 78% rename from docs/layers/alerting/08-alerting.md rename to docs/layers/alerting/08-alerting.mdx index 94f19a96e..df677095b 100644 --- a/docs/layers/alerting/08-alerting.md +++ b/docs/layers/alerting/08-alerting.mdx @@ -1,11 +1,16 @@ -# Alerting +--- +title: "Alerting" +sidebar_label: "Alerting" +sidebar_position: 1 +--- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Quick Start You will need a OpsGenie account! -Please follow the sign up steps in -[How to Sign Up for OpsGenie](https://docs.cloudposse.com/reference-architecture/how-to-guides/integrations/opsgenie/how-to-sign-up-for-opsgenie/) +Please follow the sign up steps in [How to Sign Up for OpsGenie](https://docs.cloudposse.com/reference-architecture/how-to-guides/integrations/opsgenie/how-to-sign-up-for-opsgenie/) ## How To diff --git a/docs/layers/alerting/alerting.md b/docs/layers/alerting/alerting.mdx similarity index 98% rename from docs/layers/alerting/alerting.md rename to docs/layers/alerting/alerting.mdx index 0ba95750a..c14d48ef5 100644 --- a/docs/layers/alerting/alerting.md +++ b/docs/layers/alerting/alerting.mdx @@ -2,15 +2,14 @@ title: "Alerting" sidebar_class_name: hidden --- - -# Alerting +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; Alerting is the process of notifying users of a system of a change in its state. This is typically done by sending an email or a text message to a user or a group of users. Alerting goes hand in hand with [monitoring](/reference-architecture/fundamentals/monitoring/). When a system is monitored properly, only the right people are notified when something goes wrong. -:::info -**IMPORTANT** +:::important This Quick Start assumes you have read through [the Monitoring Quick Start](/reference-architecture/fundamentals/monitoring/) diff --git a/docs/layers/alerting/design-decisions/decide-on-default-schedules.md b/docs/layers/alerting/design-decisions/decide-on-default-schedules.mdx similarity index 86% rename from docs/layers/alerting/design-decisions/decide-on-default-schedules.md rename to docs/layers/alerting/design-decisions/decide-on-default-schedules.mdx index c7a56ce35..7481ebea4 100644 --- a/docs/layers/alerting/design-decisions/decide-on-default-schedules.md +++ b/docs/layers/alerting/design-decisions/decide-on-default-schedules.mdx @@ -1,12 +1,10 @@ --- title: "Decide on Default Schedules" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1271824449/REFARCH-520+-+Decide+on+Default+Schedules +sidebar_label: "Default Schedules" sidebar_position: 100 refarch_id: REFARCH-520 --- -# Decide on Default Schedules - ## Context and Problem Statement By default, an opsgenie team comes with its own schedule. Sometimes however we want different schedules for different timezones. A team spread across the world would have to manually keep track of the schedule to make sure individuals are only on call for particular hours. diff --git a/docs/layers/alerting/design-decisions/decide-on-incident-ruleset.md b/docs/layers/alerting/design-decisions/decide-on-incident-ruleset.mdx similarity index 93% rename from docs/layers/alerting/design-decisions/decide-on-incident-ruleset.md rename to docs/layers/alerting/design-decisions/decide-on-incident-ruleset.mdx index c83cd3ac2..c7c068744 100644 --- a/docs/layers/alerting/design-decisions/decide-on-incident-ruleset.md +++ b/docs/layers/alerting/design-decisions/decide-on-incident-ruleset.mdx @@ -1,12 +1,10 @@ --- title: "Decide on Incident Ruleset" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1271922722/REFARCH-519+-+Decide+on+Incident+Ruleset +sidebar_label: "Incident Ruleset" sidebar_position: 100 refarch_id: REFARCH-519 --- -# Decide on Incident Ruleset - ## Context and Problem Statement We need to decide the rules that make an alert an incident. This ruleset could be based on priority-level of the alert, message, or by tag. diff --git a/docs/layers/alerting/design-decisions/decide-on-teams-for-escalations.md b/docs/layers/alerting/design-decisions/decide-on-teams-for-escalations.mdx similarity index 88% rename from docs/layers/alerting/design-decisions/decide-on-teams-for-escalations.md rename to docs/layers/alerting/design-decisions/decide-on-teams-for-escalations.mdx index 3313e1613..71224c51e 100644 --- a/docs/layers/alerting/design-decisions/decide-on-teams-for-escalations.md +++ b/docs/layers/alerting/design-decisions/decide-on-teams-for-escalations.mdx @@ -1,12 +1,10 @@ --- title: "Decide on Teams for Escalations" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1171947816/REFARCH-468+-+Decide+on+Teams+for+Escalations +sidebar_label: "Teams for Escalations" sidebar_position: 100 refarch_id: REFARCH-468 --- -# Decide on Teams for Escalations - ## Problem Teams need to be notified of incidents tied to services that affect them. diff --git a/docs/layers/alerting/OpsGenie/how-to-add-users-to-a-team-in-opsgenie.md b/docs/layers/alerting/opsgenie/how-to-add-users-to-a-team-in-opsgenie.mdx similarity index 74% rename from docs/layers/alerting/OpsGenie/how-to-add-users-to-a-team-in-opsgenie.md rename to docs/layers/alerting/opsgenie/how-to-add-users-to-a-team-in-opsgenie.mdx index a48eacbf9..600309a24 100644 --- a/docs/layers/alerting/OpsGenie/how-to-add-users-to-a-team-in-opsgenie.md +++ b/docs/layers/alerting/opsgenie/how-to-add-users-to-a-team-in-opsgenie.mdx @@ -1,13 +1,13 @@ --- -title: "Adding Users to a Team" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1289027670/How+to+Add+Users+to+a+Team+in+OpsGenie +title: How to Add Users to a Team in OpsGenie +sidebar_label: "Adding Users to a Team" sidebar_position: 102 --- - -# How to Add Users to a Team in OpsGenie +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem -We often need to change who on a team responding to particular alerts. +We often need to change who on a team responds to particular alerts. ### Prerequisites Assuming you are using the [opsgenie-team](/components/library/aws/opsgenie-team/) component with `ignore_team_members` set to `false` diff --git a/docs/layers/alerting/OpsGenie/how-to-create-escalation-rules-in-opsgenie.md b/docs/layers/alerting/opsgenie/how-to-create-escalation-rules-in-opsgenie.mdx similarity index 86% rename from docs/layers/alerting/OpsGenie/how-to-create-escalation-rules-in-opsgenie.md rename to docs/layers/alerting/opsgenie/how-to-create-escalation-rules-in-opsgenie.mdx index 6e01f37c4..909e74280 100644 --- a/docs/layers/alerting/OpsGenie/how-to-create-escalation-rules-in-opsgenie.md +++ b/docs/layers/alerting/opsgenie/how-to-create-escalation-rules-in-opsgenie.mdx @@ -1,10 +1,10 @@ --- -title: "Adding Escalation Rules" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1278377985/How+to+Create+Escalation+Rules+in+OpsGenie +title: "How to Create Escalation Rules in OpsGenie" +sidebar_label: "Adding Escalation Rules" sidebar_position: 103 --- - -# How to Create Escalation Rules in OpsGenie +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem You want to control what to do when an alert isn’t acknowledged. diff --git a/docs/layers/alerting/OpsGenie/how-to-create-new-teams-in-opsgenie.md b/docs/layers/alerting/opsgenie/how-to-create-new-teams-in-opsgenie.mdx similarity index 91% rename from docs/layers/alerting/OpsGenie/how-to-create-new-teams-in-opsgenie.md rename to docs/layers/alerting/opsgenie/how-to-create-new-teams-in-opsgenie.mdx index 12ee6ba36..ae96216fa 100644 --- a/docs/layers/alerting/OpsGenie/how-to-create-new-teams-in-opsgenie.md +++ b/docs/layers/alerting/opsgenie/how-to-create-new-teams-in-opsgenie.mdx @@ -1,10 +1,10 @@ --- -title: "Create a New Team" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1277591559/How+to+Create+New+Teams+in+OpsGenie +title: "How to Create New Teams in OpsGenie" +sidebar_label: "Create a New Team" sidebar_position: 101 --- - -# How to Create New Teams in OpsGenie +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem As a company grows so does its number of teams. We need a way to be easily able to configure a new team with alerting on particular resources. @@ -15,7 +15,6 @@ The [opsgenie-team](/components/library/aws/opsgenie-team/) component can be use :::tip **TL;DR** Create a new opsgenie-team component. Then tag resources with the `team: ` to start sending alerts through datadog. - ::: ### Prerequisites diff --git a/docs/layers/alerting/OpsGenie/how-to-onboard-a-new-service-with-datadog-and-opsgenie.md b/docs/layers/alerting/opsgenie/how-to-onboard-a-new-service-with-datadog-and-opsgenie.mdx similarity index 94% rename from docs/layers/alerting/OpsGenie/how-to-onboard-a-new-service-with-datadog-and-opsgenie.md rename to docs/layers/alerting/opsgenie/how-to-onboard-a-new-service-with-datadog-and-opsgenie.mdx index 72fedff18..e6404a195 100644 --- a/docs/layers/alerting/OpsGenie/how-to-onboard-a-new-service-with-datadog-and-opsgenie.md +++ b/docs/layers/alerting/opsgenie/how-to-onboard-a-new-service-with-datadog-and-opsgenie.mdx @@ -1,10 +1,10 @@ --- -title: "Onboard a New Service" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1288601737/How+to+Onboard+a+New+Service+with+Datadog+and+OpsGenie +title: "How to Onboard a New Service with Datadog and OpsGenie" +sidebar_label: "Onboard a New Service" sidebar_position: 105 --- - -# How to Onboard a New Service with Datadog and OpsGenie +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem When spinning up a new service you want to quickly get a set of monitors up and running on the app, even if more detailed APMs are to come. Similarly, we immediately want a particular team to be considered the app owner, who will be notified if the app has an alert. diff --git a/docs/layers/alerting/OpsGenie/how-to-setup-rotations-in-opsgenie.md b/docs/layers/alerting/opsgenie/how-to-setup-rotations-in-opsgenie.mdx similarity index 73% rename from docs/layers/alerting/OpsGenie/how-to-setup-rotations-in-opsgenie.md rename to docs/layers/alerting/opsgenie/how-to-setup-rotations-in-opsgenie.mdx index c1c760928..560631718 100644 --- a/docs/layers/alerting/OpsGenie/how-to-setup-rotations-in-opsgenie.md +++ b/docs/layers/alerting/opsgenie/how-to-setup-rotations-in-opsgenie.mdx @@ -1,12 +1,13 @@ --- -title: "Adding Rotations" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1277788177/How+to+Setup+Rotations+in+OpsGenie +title: "How to Setup Rotations in OpsGenie" +sidebar_label: "Adding Rotations" sidebar_position: 104 --- - -# How to Setup Rotations in OpsGenie +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem + You need to configure rotations to allow people to be on call for periods of time before rotating to off-call and having someone else cover. ## Solution diff --git a/docs/layers/alerting/OpsGenie/how-to-sign-up-for-opsgenie.md b/docs/layers/alerting/opsgenie/how-to-sign-up-for-opsgenie.mdx similarity index 95% rename from docs/layers/alerting/OpsGenie/how-to-sign-up-for-opsgenie.md rename to docs/layers/alerting/opsgenie/how-to-sign-up-for-opsgenie.mdx index d06aeaa83..03a2624c9 100644 --- a/docs/layers/alerting/OpsGenie/how-to-sign-up-for-opsgenie.md +++ b/docs/layers/alerting/opsgenie/how-to-sign-up-for-opsgenie.mdx @@ -1,15 +1,17 @@ --- -title: "Sign Up" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1209499827 +title: "How to Sign Up for OpsGenie?" +sidebar_label: "Sign Up" sidebar_position: 100 --- - -# How to Sign Up for OpsGenie? +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem + You’ve been asked to [sign up for OpsGenie](https://www.atlassian.com/software/opsgenie/pricing), but are unsure of what plan is needed for your organization. The pricing increases depending on features, but you’re not sure what features will be required. ## Solution + [https://www.atlassian.com/software/opsgenie/pricing](https://www.atlassian.com/software/opsgenie/pricing) :::tip @@ -19,6 +21,7 @@ We recommend the Enterprise Plan. Some resources cannot be provisioned unless on a Standard or Enterprise plan. While our terraform modules support all plans, what we will do will be limited. Using Standard is ok to start, but we really recommend Enterprise has some more features we recommend leveraging. ### Option 1: Enterprise Plan (Recommended) + The main thing we can use from the Enterprise plan (and supported by the component) is “Service Subscriptions”. > Opsgenie enables you to map alerts to the business services they impact and have a clear understanding of which teams need to respond and who needs to be kept up to date on the progress towards resolution. Disparate teams are notified simultaneously and presented with the tools they need to collaborate during resolution.With this, it basically means that the services we create (e.g. backend, a website, an app, a k8s deployemnt, or really any abstraction we can call a service) can be managed like this: @@ -26,6 +29,7 @@ The main thing we can use from the Enterprise plan (and supported by the compone ``` Service → Datadog alert → Opsgenie business service → Opsgenie alert → Opsgenie incident → Team notification → Escalation ``` + This entire chain can be used only in the Enterprise plan. All of these things are only available in the Enterprise Plan: [https://www.atlassian.com/software/opsgenie/service-aware-incident-management](https://www.atlassian.com/software/opsgenie/service-aware-incident-management) @@ -35,6 +39,7 @@ So in short, if you have 20 microservices that send metrics to Datadog, Datadog The last part (alert → incident → team notification → incident status page → acknowledgment → postmortem) is only in Enterprise plans. ### Option 2: Standard Plan + In Standard, all parts can be deployed and used separately, e.g. ``` @@ -50,6 +55,7 @@ They don’t allow to use of Opsgenie services to create incidents and notify te > Opsgenie enables you to map alerts to the business services they impact and have a clear understanding of which teams need to respond and who needs to be kept up to date on the progress towards resolution. Disparate teams are notified simultaneously and presented with the tools they need to collaborate during resolution. ## Troubleshooting +
### Error: `You do not have the right to use Service API, Took: 0.002000, RequestId: f4550375-efa7-49bc-ac04-3a0d6709f7d1` diff --git a/docs/layers/alerting/OpsGenie/OpsGenie.md b/docs/layers/alerting/opsgenie/opsgenie.mdx similarity index 98% rename from docs/layers/alerting/OpsGenie/OpsGenie.md rename to docs/layers/alerting/opsgenie/opsgenie.mdx index 89eaefa32..cdddd9390 100644 --- a/docs/layers/alerting/OpsGenie/OpsGenie.md +++ b/docs/layers/alerting/opsgenie/opsgenie.mdx @@ -1,10 +1,11 @@ --- -title: "OpsGenie" +title: "How to Implement Incident Management with OpsGenie" +sidebar_label: "OpsGenie" confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1192231154/How+to+Implement+Incident+Management+with+OpsGenie sidebar_position: 10 --- - -# How to Implement Incident Management with OpsGenie +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Introduction Cloud Posse advises customers with very similar monitoring requirements because we have standardized our delivery model for our customers. This is our strategy for implementing OpsGenie for Incident Management. The actual fine-tuning of any implementation needs to be tailored to the customer’s needs based on the [Design Decisions](#design-decisions). diff --git a/docs/layers/application-cicd/application-cicd.mdx b/docs/layers/application-cicd/application-cicd.mdx index 5f12b8021..1fde28f08 100644 --- a/docs/layers/application-cicd/application-cicd.mdx +++ b/docs/layers/application-cicd/application-cicd.mdx @@ -1,8 +1,13 @@ --- title: "Quick Start" +sidebar_label: "Quick Start" sidebar_position: 0 sidebar_class_name: hidden +description: "Get started with Cloud Posse's Release Engineering." --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; +import ReactPlayer from 'react-player'; :::info DevOps @@ -11,9 +16,10 @@ For more, see [What is DevOps](https://aws.amazon.com/devops/what-is-devops/). ::: -import ReactPlayer from 'react-player'; - - +
+ +
AI generated voice
+
## The Problem diff --git a/docs/layers/application-cicd/design-decisions/decide-how-to-distribute-docker-images.md b/docs/layers/application-cicd/design-decisions/decide-how-to-distribute-docker-images.mdx similarity index 89% rename from docs/layers/application-cicd/design-decisions/decide-how-to-distribute-docker-images.md rename to docs/layers/application-cicd/design-decisions/decide-how-to-distribute-docker-images.mdx index 06dae0a56..3b58dfcc5 100644 --- a/docs/layers/application-cicd/design-decisions/decide-how-to-distribute-docker-images.md +++ b/docs/layers/application-cicd/design-decisions/decide-how-to-distribute-docker-images.mdx @@ -1,11 +1,11 @@ --- title: "Decide How to distribute Docker Images" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1175847134/REFARCH-91+-+Decide+How+to+distribute+Docker+Images +sidebar_label: "Decide How to distribute Docker Images" sidebar_position: 100 refarch_id: REFARCH-91 --- - -# Decide How to distribute Docker Images +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; #### Use AWS ECR diff --git a/docs/layers/application-cicd/design-decisions/decide-on-argocd-architecture.md b/docs/layers/application-cicd/design-decisions/decide-on-argocd-architecture.mdx similarity index 99% rename from docs/layers/application-cicd/design-decisions/decide-on-argocd-architecture.md rename to docs/layers/application-cicd/design-decisions/decide-on-argocd-architecture.mdx index c45dc79bb..2a55727ca 100644 --- a/docs/layers/application-cicd/design-decisions/decide-on-argocd-architecture.md +++ b/docs/layers/application-cicd/design-decisions/decide-on-argocd-architecture.mdx @@ -1,11 +1,11 @@ --- title: "Decide on ArgoCD Architecture" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1171980417/REFARCH-420+-+Decide+on+ArgoCD+Architecture +sidebar_label: "Decide on ArgoCD Architecture" sidebar_position: 100 refarch_id: REFARCH-420 --- - -# Decide on ArgoCD Architecture +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Considerations diff --git a/docs/layers/application-cicd/design-decisions/decide-on-argocd-deployment-repo-architecture.md b/docs/layers/application-cicd/design-decisions/decide-on-argocd-deployment-repo-architecture.mdx similarity index 88% rename from docs/layers/application-cicd/design-decisions/decide-on-argocd-deployment-repo-architecture.md rename to docs/layers/application-cicd/design-decisions/decide-on-argocd-deployment-repo-architecture.mdx index 36b9958d4..61ab1a021 100644 --- a/docs/layers/application-cicd/design-decisions/decide-on-argocd-deployment-repo-architecture.md +++ b/docs/layers/application-cicd/design-decisions/decide-on-argocd-deployment-repo-architecture.mdx @@ -1,11 +1,11 @@ --- title: "Decide on ArgoCD Deployment Repo Architecture" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1171947862/REFARCH-405+-+Decide+on+ArgoCD+Deployment+Repo+Architecture +sidebar_label: "ArgoCD Deployment Repo Architecture" sidebar_position: 100 refarch_id: REFARCH-405 --- - -# Decide on ArgoCD Deployment Repo Architecture +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ### Context diff --git a/docs/layers/application-cicd/design-decisions/decide-on-branching-strategy.md b/docs/layers/application-cicd/design-decisions/decide-on-branching-strategy.mdx similarity index 97% rename from docs/layers/application-cicd/design-decisions/decide-on-branching-strategy.md rename to docs/layers/application-cicd/design-decisions/decide-on-branching-strategy.mdx index e7d22144a..30c289b06 100644 --- a/docs/layers/application-cicd/design-decisions/decide-on-branching-strategy.md +++ b/docs/layers/application-cicd/design-decisions/decide-on-branching-strategy.mdx @@ -1,11 +1,12 @@ --- title: "Decide on Branching Strategy" +sidebar_label: "Branching Strategy" confluence: sidebar_position: 100 refarch_id: --- - -# Decide on Branching Strategy +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Context and Problem Statement diff --git a/docs/layers/application-cicd/design-decisions/decide-on-customer-apps-for-migration.md b/docs/layers/application-cicd/design-decisions/decide-on-customer-apps-for-migration.mdx similarity index 90% rename from docs/layers/application-cicd/design-decisions/decide-on-customer-apps-for-migration.md rename to docs/layers/application-cicd/design-decisions/decide-on-customer-apps-for-migration.mdx index 8095e52ef..1f850ed60 100644 --- a/docs/layers/application-cicd/design-decisions/decide-on-customer-apps-for-migration.md +++ b/docs/layers/application-cicd/design-decisions/decide-on-customer-apps-for-migration.mdx @@ -1,11 +1,12 @@ --- title: "Decide on Customer Apps for Migration" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1171783740/REFARCH-256+-+Decide+on+Customer+Apps+for+Migration +sidebar_label: "Customer Apps for Migration" sidebar_position: 100 refarch_id: REFARCH-256 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; -# Decide on Customer Apps for Migration We need to identify an application and its associated services that are suitable as the first candidate for migration to the new platform. This is an application that will be targeted by all the release engineering work. We can pretty much handle anything, but ideal candidates have these characteristics: [https://cloudposse.com/12-factor-app/](https://cloudposse.com/12-factor-app/) diff --git a/docs/layers/application-cicd/design-decisions/decide-on-database-seeding-strategy-for-ephemeral-preview-enviro.md b/docs/layers/application-cicd/design-decisions/decide-on-database-seeding-strategy-for-ephemeral-preview-enviro.mdx similarity index 90% rename from docs/layers/application-cicd/design-decisions/decide-on-database-seeding-strategy-for-ephemeral-preview-enviro.md rename to docs/layers/application-cicd/design-decisions/decide-on-database-seeding-strategy-for-ephemeral-preview-enviro.mdx index a53edf13c..0ac847033 100644 --- a/docs/layers/application-cicd/design-decisions/decide-on-database-seeding-strategy-for-ephemeral-preview-enviro.md +++ b/docs/layers/application-cicd/design-decisions/decide-on-database-seeding-strategy-for-ephemeral-preview-enviro.mdx @@ -1,13 +1,14 @@ --- title: "Decide on Database Seeding Strategy for Ephemeral Preview Environments" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1171619913/REFARCH-144+-+Decide+on+Database+Seeding+Strategy+for+Ephemeral+Preview+Environments +sidebar_label: "Database Seeding Strategy" sidebar_position: 100 refarch_id: REFARCH-144 --- - -# Decide on Database Seeding Strategy for Ephemeral Preview Environments +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem + We need to decide how to provision databases for use with preview environments. These databases must come up very quickly (e.g. 10-20 seconds rather than 20-30 minutes it takes for RDS). Once these databases come online, we need to have data staged for them to be useful. Restoring very large database dumps can be very slow and we need to update database dumps and scrub them. We typically cannot (and should not) use snapshots directly from production due to constraints around how we must handle PII, PHI, CDH, etc. :::caution diff --git a/docs/layers/application-cicd/design-decisions/decide-on-github-actions-workflow-organization-strategy.md b/docs/layers/application-cicd/design-decisions/decide-on-github-actions-workflow-organization-strategy.mdx similarity index 95% rename from docs/layers/application-cicd/design-decisions/decide-on-github-actions-workflow-organization-strategy.md rename to docs/layers/application-cicd/design-decisions/decide-on-github-actions-workflow-organization-strategy.mdx index 667b20470..10c11f618 100644 --- a/docs/layers/application-cicd/design-decisions/decide-on-github-actions-workflow-organization-strategy.md +++ b/docs/layers/application-cicd/design-decisions/decide-on-github-actions-workflow-organization-strategy.mdx @@ -1,13 +1,14 @@ --- title: "Decide on GitHub Actions Workflow Organization Strategy" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1171947681/REFARCH-421+-+Decide+on+GitHub+Actions+Workflow+Organization+Strategy +sidebar_label: "GitHub Actions Workflow Organization Strategy" sidebar_position: 100 refarch_id: REFARCH-421 --- - -# Decide on GitHub Actions Workflow Organization Strategy +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem + GitHub Actions Workflow files scattered in repositories throughout the GitHub organization can quickly violate the DRY principle if they contain repeated code. ## Considerations @@ -15,6 +16,7 @@ GitHub Actions Workflow files scattered in repositories throughout the GitHub or ### Standardize Workflows Across the Organization ### Metrics and Observability + With appropriate metrics, you’ll be able to answer questions like: - Are we deploying faster? ...or slowing down? @@ -28,16 +30,19 @@ See [https://www.datadoghq.com/blog/datadog-github-actions-ci-visibility/](https [https://www.leanix.net/en/wiki/vsm/dora-metrics](https://www.leanix.net/en/wiki/vsm/dora-metrics) ### Public Actions + Trusted organizations for public actions Verified organizations for public actions ### Private Actions + Private actions technically require GitHub Enterprise. We can do a workaround for non-enterprise organizations: an explicit `git clone` of a private actions repo. ### Shared Workflows ### Code Reusability + [Composite Actions](https://docs.github.com/en/actions/creating-actions/creating-a-composite-action) can be leveraged to solve that problem. Composite Actions are very similar to GHA workflow files in that they contain multiple steps, some of which can reference open-source Actions. Still, they are not individual workflows but rather actions that another workflow can reference. These Composite Actions thus reduce code repetition within the organization. ### GitHub Script @@ -56,6 +61,7 @@ deployment.newDeployment(JSON.parse(`${{ inputs.stages }}`)) ``` ## Recommendation + - Use a private repository for reusable GitHub workflows (e.g. `acme/github-workflows`) - Use GitHub Enterprise to support approval steps @@ -75,6 +81,7 @@ back replicas. The recommended default is 30 minutes, but no one size fits all. documentation for your consideration: [scaling runners](https://github.com/actions/actions-runner-controller/blob/master/docs/automatically-scaling-runners.md) ## Related + - [Decide on Strategy for Continuous Integration](/reference-architecture/fundamentals/design-decisions/foundational-release-engineering/decide-on-strategy-for-continuous-integration) - [Decide on Self-Hosted GitHub Runner Strategy](/reference-architecture/fundamentals/design-decisions/foundational-release-engineering/decide-on-self-hosted-github-runner-strategy) diff --git a/docs/layers/application-cicd/design-decisions/decide-on-hot-fix-or-rollback-strategy.md b/docs/layers/application-cicd/design-decisions/decide-on-hot-fix-or-rollback-strategy.mdx similarity index 91% rename from docs/layers/application-cicd/design-decisions/decide-on-hot-fix-or-rollback-strategy.md rename to docs/layers/application-cicd/design-decisions/decide-on-hot-fix-or-rollback-strategy.mdx index 15eb96ce7..b4eb95005 100644 --- a/docs/layers/application-cicd/design-decisions/decide-on-hot-fix-or-rollback-strategy.md +++ b/docs/layers/application-cicd/design-decisions/decide-on-hot-fix-or-rollback-strategy.mdx @@ -1,11 +1,12 @@ --- title: "Decide on Hot-fix or Rollback Strategy" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1171947700/REFARCH-428+-+Decide+on+Hot-fix+or+Rollback+Strategy +sidebar_label: "Hot-fix or Rollback Strategy" sidebar_position: 100 refarch_id: REFARCH-428 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; -# Decide on Hot-fix or Rollback Strategy Releasing a change is when it’s made available to a user or subset of users. In an ideal world, deployments should not equal releases. ## Considerations diff --git a/docs/layers/application-cicd/design-decisions/decide-on-how-ecs-apps-are-deployed.md b/docs/layers/application-cicd/design-decisions/decide-on-how-ecs-apps-are-deployed.mdx similarity index 78% rename from docs/layers/application-cicd/design-decisions/decide-on-how-ecs-apps-are-deployed.md rename to docs/layers/application-cicd/design-decisions/decide-on-how-ecs-apps-are-deployed.mdx index 5b6f3a34e..fcd16e31c 100644 --- a/docs/layers/application-cicd/design-decisions/decide-on-how-ecs-apps-are-deployed.md +++ b/docs/layers/application-cicd/design-decisions/decide-on-how-ecs-apps-are-deployed.mdx @@ -1,11 +1,12 @@ --- title: "Decide on how ECS apps are deployed" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1175847107/REFARCH-411+-+Decide+on+how+ECS+apps+are+deployed +sidebar_label: "ECS apps deployment" sidebar_position: 100 refarch_id: REFARCH-411 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; -# Decide on how ECS apps are deployed We need to decide on what methodology to use when deploying applications to ECS. Think of Helm Charts in Kubernetes as similar to using Terraform Modules for ECS Tasks diff --git a/docs/layers/application-cicd/design-decisions/decide-on-kubernetes-application-artifacts.md b/docs/layers/application-cicd/design-decisions/decide-on-kubernetes-application-artifacts.mdx similarity index 83% rename from docs/layers/application-cicd/design-decisions/decide-on-kubernetes-application-artifacts.md rename to docs/layers/application-cicd/design-decisions/decide-on-kubernetes-application-artifacts.mdx index 8acc22f63..f2ff922b8 100644 --- a/docs/layers/application-cicd/design-decisions/decide-on-kubernetes-application-artifacts.md +++ b/docs/layers/application-cicd/design-decisions/decide-on-kubernetes-application-artifacts.mdx @@ -1,11 +1,12 @@ --- title: "Decide on Kubernetes Application Artifacts" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1171980462/REFARCH-427+-+Decide+on+Kubernetes+Application+Artifacts +sidebar_label: "Kubernetes Application Artifacts" sidebar_position: 100 refarch_id: REFARCH-427 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; -# Decide on Kubernetes Application Artifacts We prefer strategies that ship the Application code (e.g. docker images) with the Application configuration (E.g. everything needed to run the application on the platform, such as manifests, IAM roles, etc.) **Application-specific Infrastructure Considerations** diff --git a/docs/layers/application-cicd/design-decisions/decide-on-pipeline-strategy.mdx b/docs/layers/application-cicd/design-decisions/decide-on-pipeline-strategy.mdx index aefb1049d..624498243 100644 --- a/docs/layers/application-cicd/design-decisions/decide-on-pipeline-strategy.mdx +++ b/docs/layers/application-cicd/design-decisions/decide-on-pipeline-strategy.mdx @@ -1,9 +1,11 @@ --- title: "Decide on Pipeline Strategy" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1171718383/REFARCH-253+-+Decide+on+Pipeline+Strategy +sidebar_label: "Pipeline Strategy" sidebar_position: 100 refarch_id: REFARCH-253 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Context and Problem Statement diff --git a/docs/layers/application-cicd/design-decisions/decide-on-release-engineering-strategy.md b/docs/layers/application-cicd/design-decisions/decide-on-release-engineering-strategy.mdx similarity index 91% rename from docs/layers/application-cicd/design-decisions/decide-on-release-engineering-strategy.md rename to docs/layers/application-cicd/design-decisions/decide-on-release-engineering-strategy.mdx index 1ce9795d1..af7299305 100644 --- a/docs/layers/application-cicd/design-decisions/decide-on-release-engineering-strategy.md +++ b/docs/layers/application-cicd/design-decisions/decide-on-release-engineering-strategy.mdx @@ -1,4 +1,9 @@ -# Decide on Release Engineering Strategy +--- +title: Decide on Release Engineering Strategy +sidebar_label: Release Engineering Strategy +--- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem A consistent branching strategy is needed to ensure that a consistent workflow is shared across all projects. @@ -17,7 +22,7 @@ The Gitflow branching model consists of the following branches: - **Release Branches:** Created from the develop branch, release branches are used to prepare for a new production release. Any bug fixes and final testing are done on this branch before being merged back into both the develop and master branches. - **Hotfix Branches:** Similar to release branches, hotfix branches are created from the master branch to address any critical bugs or issues discovered in the production code. Once the hotfix is complete, it is merged back into both the master and develop branches. -The benefit of Gitflow is that it provides a clear path for changes to be made to the codebase, ensuring that production-ready code is only released from the master branch. It also allows for multiple developers to work on features and bug fixes in parallel without disrupting the development workflow. +The benefit of Gitflow is that it provides a clear path for changes to be made to the codebase, ensuring that production-ready code is only released from the master branch. It also allows for multiple developers to work on features and bug fixes in parallel without disrupting the development workflow.
diff --git a/docs/layers/application-cicd/design-decisions/decide-on-release-promotion-strategy.md b/docs/layers/application-cicd/design-decisions/decide-on-release-promotion-strategy.mdx similarity index 92% rename from docs/layers/application-cicd/design-decisions/decide-on-release-promotion-strategy.md rename to docs/layers/application-cicd/design-decisions/decide-on-release-promotion-strategy.mdx index 2b03f7185..ba32f7785 100644 --- a/docs/layers/application-cicd/design-decisions/decide-on-release-promotion-strategy.md +++ b/docs/layers/application-cicd/design-decisions/decide-on-release-promotion-strategy.mdx @@ -1,13 +1,14 @@ --- title: "Decide on Release Promotion Strategy" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1171750987/REFARCH-419+-+Decide+on+Release+Promotion+Strategy +sidebar_label: "Release Promotion Strategy" sidebar_position: 100 refarch_id: REFARCH-419 --- - -# Decide on Release Promotion Strategy +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ### Problem and Context + We need to control when a release is deployed to a given stage (E.g. dev, staging, production). We must decide how releases will be promoted from staging to production. @@ -15,6 +16,7 @@ We must decide how releases will be promoted from staging to production. How that will be accomplished will depend on whether or not GitHub Enterprise features are available and whether or not it’s possible to use semantic versioning or not. ### Assumptions + - Auto deployment to the `dev` stage will be triggered upon every commit to the default branch (e.g. `main`) ### Options diff --git a/docs/layers/application-cicd/design-decisions/decide-on-repositories-strategy.md b/docs/layers/application-cicd/design-decisions/decide-on-repositories-strategy.mdx similarity index 97% rename from docs/layers/application-cicd/design-decisions/decide-on-repositories-strategy.md rename to docs/layers/application-cicd/design-decisions/decide-on-repositories-strategy.mdx index b098ae17f..f97821d0c 100644 --- a/docs/layers/application-cicd/design-decisions/decide-on-repositories-strategy.md +++ b/docs/layers/application-cicd/design-decisions/decide-on-repositories-strategy.mdx @@ -1,11 +1,11 @@ --- title: "Decide on Repositories Strategy" -confluence: +sidebar_label: "Repositories Strategy" sidebar_position: 100 refarch_id: --- - -# Decide on Repositories Strategy +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Context and Problem Statement diff --git a/docs/layers/application-cicd/design-decisions/decide-on-seeding-strategy-for-staging-environments.md b/docs/layers/application-cicd/design-decisions/decide-on-seeding-strategy-for-staging-environments.mdx similarity index 85% rename from docs/layers/application-cicd/design-decisions/decide-on-seeding-strategy-for-staging-environments.md rename to docs/layers/application-cicd/design-decisions/decide-on-seeding-strategy-for-staging-environments.mdx index 6b595a4ed..606fe03e2 100644 --- a/docs/layers/application-cicd/design-decisions/decide-on-seeding-strategy-for-staging-environments.md +++ b/docs/layers/application-cicd/design-decisions/decide-on-seeding-strategy-for-staging-environments.mdx @@ -1,11 +1,11 @@ --- title: "Decide on Seeding Strategy for Staging Environments" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1171947646/REFARCH-423+-+Decide+on+Seeding+Strategy+for+Staging+Environments +sidebar_label: "Seeding Strategy for Staging" sidebar_position: 100 refarch_id: REFARCH-423 --- - -# Decide on Seeding Strategy for Staging Environments +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem Longer-lived staging environments need a dataset that closely resembles production. If this dataset becomes stale, we’ll not be effectively testing releases before they hit production. Restoring snapshots from production is not recommended. diff --git a/docs/layers/application-cicd/design-decisions/decide-on-self-hosted-github-runner-strategy.md b/docs/layers/application-cicd/design-decisions/decide-on-self-hosted-github-runner-strategy.mdx similarity index 98% rename from docs/layers/application-cicd/design-decisions/decide-on-self-hosted-github-runner-strategy.md rename to docs/layers/application-cicd/design-decisions/decide-on-self-hosted-github-runner-strategy.mdx index d44d01582..42147ed93 100644 --- a/docs/layers/application-cicd/design-decisions/decide-on-self-hosted-github-runner-strategy.md +++ b/docs/layers/application-cicd/design-decisions/decide-on-self-hosted-github-runner-strategy.mdx @@ -1,22 +1,26 @@ --- title: "Decide on Self-Hosted GitHub Runner Strategy" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1175355578/REFARCH-394+-+Decide+on+Self-Hosted+GitHub+Runner+Strategy +sidebar_label: "Self-Hosted GitHub Runner Strategy" sidebar_position: 100 refarch_id: REFARCH-394 --- - -# Decide on Self-Hosted GitHub Runner Strategy +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem + GitHub Actions enables organizations to run their own runners (aka workers) free-of-charge. Only problem is we have to host them and there’s a couple of ways of doing it, each with their own pros and cons. For the most part, we don’t consider it optional to deploy runners, if using GitHub Actions. ## Considerations + We have prior art for the following strategies. The strategies are not mutually exclusive, but most often we see companies only implement one solution. ## Considerations + GitHub Actions is the CI/CD platform offered by GitHub. Its main advantages are that, firstly, it comes at no additional costs on top of the cost of seats for users within the GitHub organization, when using self-hosted Runners. Secondly, there is a thriving ecosystem of open source Actions that can be used within GitHub Action workflows. ### Self-hosted Runners on EC2 + GitHub Actions Runners can be self-hosted on EC2 or on Kubernetes clusters. This is probably the easiest to deploy and understand how it works, but it’s the least optimal way of managing runners. On EC2, the [Runner executable](https://github.com/actions/runner) can be installed using a user-data script, or baked into the AMI of the instance to be deployed to EC2. The runner can be deployed to an Auto Scaling Group (ASG), which usually presents a de-registration problem when the ASG scales in, however EventBridge and AWS Systems Manager can be utilized in tandem to have the runner de-register prior to being terminated (see: [Cloud Posse's github-runners component](https://github.com/cloudposse/terraform-aws-components/tree/95ade5b36b61d2432179399bd0e9fa8639eeb899/modules/github-runners) which has this implementation). @@ -33,6 +37,7 @@ If we go this route, we’ll also want to determine if we should deploy the Data This is our recommended approach ::: + Deploying these Runners on Kubernetes is possible using [actions-runner-controller](https://github.com/actions-runner-controller/actions-runner-controller). With this controller, a small-to-medium-sized cluster can house a large number of Runners (depending on their requested Memory and CPU resources), and these Runners can scale automatically using the controller’s `HorizontalRunnerAutoscaler` CRD. This has the benefit that it can scale to zero and leverages all the monitoring we have on the platform. This solution also allows for using a custom runner image without having to rebuild an AMI or modify a user-data script and re-launch instances, which would be necessary when deploying the Runners to EC2. `actions-runner-controller` also supports several various mechanisms for scaling the number of Runners: `PercentageRunnersBusy` simply scales the Runners up or down based on how many of them are currently busy, without having to maintain a list of repositories used by the Runners, which would be the case in `TotalNumberOfQueuedAndInProgressWorkflowRuns`. The most efficient and recommended option for horizontal auto-scaling using the `actions-runner-controller`, however, is to [enable the controller’s webhook server](https://github.com/actions-runner-controller/actions-runner-controller#webhook-driven-scaling) and configure the `HorizontalRunnerAutoscaler` to scale on GitHub webhook events (for event name: `check_run`, type: `created`, status: `queued`). Note that the `actions-runner-controller` does not have any logic to automatically create the webhook configuration in GitHub, and hence, the webhook server needs to be exposed and configured manually in GitHub or using the GitHub API. If using `aws-load-balancer-controller`, ensure that within `actions-runner-controller` Helm chart, `githubWebhookServer.ingress.enabled` is set to `true`, and if using `external-dns`, set `githubWebhookServer.ingress.annotations` to include an `external-dns.alpha.kubernetes.io/alias`. Finally, configure the webhook in GitHub to match the hostname and port of the endpoint corresponding to the newly-created Ingress object. @@ -42,6 +47,7 @@ In general, Cloud Posse recommends using `actions-runner-controller` over EC2-ba [https://github.com/summerwind/actions-runner-controller](https://github.com/summerwind/actions-runner-controller) ### Repository-wide or Organization-wide Runners + Self-hosted GitHub Actions Runners can be made to be either repository-wide or organization-wide. Runners registered for a specific repository can only run for workflows corresponding to that repository, while Runners registered for an organization can run for any workflow for any repository in an organization, provided that the labels selected by the `runs-on` attribute in the workflow definition match the labels corresponding to the runner. Repo-level runners have the befit of reduced scope for PAT, however, pools are not shared across repos so there are wasted resources. In general, Cloud Posse recommends choosing Organization-wide Runners and ensuring horizontal scaling is configured to adequately respond to an influx of queued runs (see the previous section). @@ -49,6 +55,7 @@ In general, Cloud Posse recommends choosing Organization-wide Runners and ensuri [https://docs.github.com/en/actions/hosting-your-own-runners/managing-access-to-self-hosted-runners-using-groups](https://docs.github.com/en/actions/hosting-your-own-runners/managing-access-to-self-hosted-runners-using-groups) ### Labeling Runners + Whenever a GitHub Actions Runner is registered, it provides a list of labels to GitHub. Then, workflow definitions can specify which Runners to run on. For example, if the workflow syntax specifies `runs-on: [self-hosted, linux]`, then the runner must be registered with the label `linux`. @@ -62,6 +69,7 @@ In another example, if two Runners are registered, one with the labels `linux`, Some advanced configurations may involve creating multiple `RunnerDeployment` CRDs (`actions-runner-controller`) which use different container images with different linux distributions or with different packages installed, then naming the labels accordingly. In general, Cloud Posse’s recommendation is to create meaningful runner labels that can be later referenced by developers writing GHA Workflow YAML files. ### Integration with AWS + The GitHub Actions Runners often need to perform continuous integration tasks such as write to S3 or push container images to ECR. With GitHub-hosted Runners this has historically been difficult but is now made possible [using GitHub’s support for OIDC](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect), which allows for creating a trust relationship between GitHub-hosted Runners and an IAM role in one of the organization’s AWS account (preferably a dedicated `automation` account). For `actions-runner-controller`, this has been historically possible for a longer time now on self-hosted GitHub Actions Runners running on `actions-runner-controller` using EKS cluster’s OIDC provider (see: [IRSA](https://docs.aws.amazon.com/emr/latest/EMR-on-EKS-DevelopmentGuide/setting-up-enable-IAM.html)). If using GHA Runners on EC2, an EC2 instance profile can be created, allowing the instances to assume an IAM role. ## Related Decisions diff --git a/docs/layers/application-cicd/design-decisions/decide-on-strategy-for-continuous-integration.md b/docs/layers/application-cicd/design-decisions/decide-on-strategy-for-continuous-integration.mdx similarity index 88% rename from docs/layers/application-cicd/design-decisions/decide-on-strategy-for-continuous-integration.md rename to docs/layers/application-cicd/design-decisions/decide-on-strategy-for-continuous-integration.mdx index 9e3cfa95f..b0978655e 100644 --- a/docs/layers/application-cicd/design-decisions/decide-on-strategy-for-continuous-integration.md +++ b/docs/layers/application-cicd/design-decisions/decide-on-strategy-for-continuous-integration.mdx @@ -1,9 +1,11 @@ --- title: "Decide on Strategy for Continuous Integration" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1171980446/REFARCH-426+-+Decide+on+Strategy+for+Continuous+Integration +sidebar_label: "Continuous Integration" sidebar_position: 100 refarch_id: REFARCH-426 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # Decide on Strategy for Continuous Integration diff --git a/docs/layers/application-cicd/design-decisions/decide-on-strategy-for-developer-environments.md b/docs/layers/application-cicd/design-decisions/decide-on-strategy-for-developer-environments.mdx similarity index 72% rename from docs/layers/application-cicd/design-decisions/decide-on-strategy-for-developer-environments.md rename to docs/layers/application-cicd/design-decisions/decide-on-strategy-for-developer-environments.mdx index 287fc56bb..b8e2da584 100644 --- a/docs/layers/application-cicd/design-decisions/decide-on-strategy-for-developer-environments.md +++ b/docs/layers/application-cicd/design-decisions/decide-on-strategy-for-developer-environments.mdx @@ -1,11 +1,11 @@ --- title: "Decide on Strategy for Developer Environments" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1171685583/REFARCH-424+-+Decide+on+Strategy+for+Developer+Environments +sidebar_label: "Developer Environments" sidebar_position: 100 refarch_id: REFARCH-424 --- - -# Decide on Strategy for Developer Environments +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Versioning Considerations diff --git a/docs/layers/application-cicd/design-decisions/decide-on-strategy-for-preview-environments-e-g-review-apps.md b/docs/layers/application-cicd/design-decisions/decide-on-strategy-for-preview-environments-e-g-review-apps.mdx similarity index 97% rename from docs/layers/application-cicd/design-decisions/decide-on-strategy-for-preview-environments-e-g-review-apps.md rename to docs/layers/application-cicd/design-decisions/decide-on-strategy-for-preview-environments-e-g-review-apps.mdx index 565624663..9ffafdde6 100644 --- a/docs/layers/application-cicd/design-decisions/decide-on-strategy-for-preview-environments-e-g-review-apps.md +++ b/docs/layers/application-cicd/design-decisions/decide-on-strategy-for-preview-environments-e-g-review-apps.mdx @@ -1,11 +1,11 @@ --- title: "Decide on Strategy for Preview Environments (e.g. Review Apps)" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1171980430 +sidebar_label: "Preview Environments" sidebar_position: 100 refarch_id: REFARCH-425 --- - -# Decide on Strategy for Preview Environments (e.g. Review Apps) +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Considerations diff --git a/docs/layers/application-cicd/design-decisions/decide-on-terraform-configuration-pattern-for-application-reposi.md b/docs/layers/application-cicd/design-decisions/decide-on-terraform-configuration-pattern-for-application-reposi.mdx similarity index 89% rename from docs/layers/application-cicd/design-decisions/decide-on-terraform-configuration-pattern-for-application-reposi.md rename to docs/layers/application-cicd/design-decisions/decide-on-terraform-configuration-pattern-for-application-reposi.mdx index 3991d54df..cc006248d 100644 --- a/docs/layers/application-cicd/design-decisions/decide-on-terraform-configuration-pattern-for-application-reposi.md +++ b/docs/layers/application-cicd/design-decisions/decide-on-terraform-configuration-pattern-for-application-reposi.mdx @@ -1,11 +1,11 @@ --- title: "Decide on Terraform Configuration Pattern for Application Repositories" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1264746925/REFARCH-514+-+Decide+on+Terraform+Configuration+Pattern+for+Application+Repositories +sidebar_label: "Terraform Configuration Pattern" sidebar_position: 100 refarch_id: REFARCH-514 --- - -# Decide on Terraform Configuration Pattern for Application Repositories +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Context and Problem Statement diff --git a/docs/layers/application-cicd/dockerized-ecs-ecspresso/06-ecspresso.mdx b/docs/layers/application-cicd/dockerized-ecs-ecspresso/06-ecspresso.mdx index e9aa9e8c5..b0402400b 100644 --- a/docs/layers/application-cicd/dockerized-ecs-ecspresso/06-ecspresso.mdx +++ b/docs/layers/application-cicd/dockerized-ecs-ecspresso/06-ecspresso.mdx @@ -1,7 +1,11 @@ -# Ecspresso - -This setup guide will help you get started with [ecspresso](https://github.com/kayac/ecspresso). It features an example -app, which demonstrates how your GitHub Actions work with your infrastructure repository. +--- +title: Ecspresso +sidebar_label: Ecspresso +--- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; + +This setup guide will help you get started with [ecspresso](https://github.com/kayac/ecspresso). It features an example app, which demonstrates how your GitHub Actions work with your infrastructure repository. :::caution Default Workflows Placement diff --git a/docs/layers/application-cicd/dockerized-ecs-ecspresso/dockerized-ecs-ecspresso.md b/docs/layers/application-cicd/dockerized-ecs-ecspresso/dockerized-ecs-ecspresso.mdx similarity index 98% rename from docs/layers/application-cicd/dockerized-ecs-ecspresso/dockerized-ecs-ecspresso.md rename to docs/layers/application-cicd/dockerized-ecs-ecspresso/dockerized-ecs-ecspresso.mdx index a6bc304aa..2e52732a4 100644 --- a/docs/layers/application-cicd/dockerized-ecs-ecspresso/dockerized-ecs-ecspresso.md +++ b/docs/layers/application-cicd/dockerized-ecs-ecspresso/dockerized-ecs-ecspresso.mdx @@ -1,13 +1,12 @@ --- title: "ECS with ecspresso" +sidebar_label: "ECS with ecspresso" sidebar_position: 100 --- - - -```mdx-code-block +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -``` ### Overview diff --git a/docs/layers/application-cicd/dockerized-eks-argocd/06-argocd.md b/docs/layers/application-cicd/dockerized-eks-argocd/06-argocd.mdx similarity index 98% rename from docs/layers/application-cicd/dockerized-eks-argocd/06-argocd.md rename to docs/layers/application-cicd/dockerized-eks-argocd/06-argocd.mdx index ae52007c5..d803fa19d 100644 --- a/docs/layers/application-cicd/dockerized-eks-argocd/06-argocd.md +++ b/docs/layers/application-cicd/dockerized-eks-argocd/06-argocd.mdx @@ -1,4 +1,10 @@ -# ArgoCD +--- +title: ArgoCD +sidebar_label: ArgoCD +description: ArgoCD is a declarative, GitOps continuous delivery tool for Kubernetes. +--- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; :::caution SAML Security Considerations diff --git a/docs/layers/application-cicd/dockerized-eks-argocd/argocd/argocd.md b/docs/layers/application-cicd/dockerized-eks-argocd/argocd/argocd.mdx similarity index 95% rename from docs/layers/application-cicd/dockerized-eks-argocd/argocd/argocd.md rename to docs/layers/application-cicd/dockerized-eks-argocd/argocd/argocd.mdx index 48f874f8e..8ee82d580 100644 --- a/docs/layers/application-cicd/dockerized-eks-argocd/argocd/argocd.md +++ b/docs/layers/application-cicd/dockerized-eks-argocd/argocd/argocd.mdx @@ -1,9 +1,12 @@ --- title: "ArgoCD" +sidebar_label: "ArgoCD" sidebar_position: 10 tags: - argocd --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ArgoCD is an open-source declarative, GitOps continuous delivery tool for Kubernetes applications. It enables developers to manage and deploy applications on Kubernetes clusters using Git repositories as the source of truth for configuration and definitions. ArgoCD follows the GitOps methodology, which means that the entire application configuration, including manifests, parameters, and even application state, is stored in a Git repository. diff --git a/docs/layers/application-cicd/dockerized-eks-argocd/argocd/github-commit-notifications.md b/docs/layers/application-cicd/dockerized-eks-argocd/argocd/github-commit-notifications.mdx similarity index 96% rename from docs/layers/application-cicd/dockerized-eks-argocd/argocd/github-commit-notifications.md rename to docs/layers/application-cicd/dockerized-eks-argocd/argocd/github-commit-notifications.mdx index 698d3b5ef..41a15aca8 100644 --- a/docs/layers/application-cicd/dockerized-eks-argocd/argocd/github-commit-notifications.md +++ b/docs/layers/application-cicd/dockerized-eks-argocd/argocd/github-commit-notifications.mdx @@ -1,13 +1,15 @@ --- -title: "Synchronous Notifications" +title: "How to setup Synchronous Notifications for ArgoCD with GitHub Commit Statuses" +sidebar_label: "Synchronous Notifications" sidebar_position: 40 +description: "Setup Synchronous Notifications for ArgoCD with GitHub Commit Statuses" tags: - argocd - github - eks --- - -# How to setup Synchronous Notifications for ArgoCD with GitHub Commit Statuses +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; Synchronous notifications are used in ArgoCD release engineering workflows to notify an application workflow of a successful deployment. The application repo deploys an updated app manifest to the ArgoCD deployment repo. Then the ArgoCD app in the EKS cluster pulls and deploys that updated application. Depending on the result of that deployment, ArgoCD triggers a notifier. diff --git a/docs/layers/application-cicd/dockerized-eks-argocd/argocd/identity-center-apps.md b/docs/layers/application-cicd/dockerized-eks-argocd/argocd/identity-center-apps.mdx similarity index 91% rename from docs/layers/application-cicd/dockerized-eks-argocd/argocd/identity-center-apps.md rename to docs/layers/application-cicd/dockerized-eks-argocd/argocd/identity-center-apps.mdx index f01280240..f73556a85 100644 --- a/docs/layers/application-cicd/dockerized-eks-argocd/argocd/identity-center-apps.md +++ b/docs/layers/application-cicd/dockerized-eks-argocd/argocd/identity-center-apps.mdx @@ -1,13 +1,14 @@ --- -title: "Identity Center Apps" +title: "How to create an AWS Identity Center Application for ArgoCD" +sidebar_label: "Identity Center Apps" sidebar_position: 30 tags: - argocd - identity - eks --- - -# How to create an AWS Identity Center Application for ArgoCD +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; In order to authenticate with ArgoCD, we recommend using an AWS IAM Identity Center SAML Application. These apps can use existing Identity Center groups that we've already setup as part of the [Identity layer](/reference-architecture/setup/identity/). diff --git a/docs/layers/application-cicd/dockerized-eks-argocd/argocd/pats.md b/docs/layers/application-cicd/dockerized-eks-argocd/argocd/pats.mdx similarity index 98% rename from docs/layers/application-cicd/dockerized-eks-argocd/argocd/pats.md rename to docs/layers/application-cicd/dockerized-eks-argocd/argocd/pats.mdx index f0c7d5a50..acbc21ab4 100644 --- a/docs/layers/application-cicd/dockerized-eks-argocd/argocd/pats.md +++ b/docs/layers/application-cicd/dockerized-eks-argocd/argocd/pats.mdx @@ -1,5 +1,6 @@ --- -title: "Authorization (PAT)" +title: "How to set up Authorization for ArgoCD with GitHub PATs" +sidebar_label: "Authorization (PAT)" sidebar_position: 20 tags: - argocd @@ -7,8 +8,8 @@ tags: - eks - pat --- - -# How to set up Authorization for ArgoCD with GitHub PATs +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; :::tip Fine-grained Personal Access Tokens (PAT) diff --git a/docs/layers/application-cicd/dockerized-eks-argocd/dockerized-eks-argocd.md b/docs/layers/application-cicd/dockerized-eks-argocd/dockerized-eks-argocd.mdx similarity index 98% rename from docs/layers/application-cicd/dockerized-eks-argocd/dockerized-eks-argocd.md rename to docs/layers/application-cicd/dockerized-eks-argocd/dockerized-eks-argocd.mdx index 5768fd531..75b74819c 100644 --- a/docs/layers/application-cicd/dockerized-eks-argocd/dockerized-eks-argocd.md +++ b/docs/layers/application-cicd/dockerized-eks-argocd/dockerized-eks-argocd.mdx @@ -1,12 +1,12 @@ --- title: "EKS with ArgoCD" +sidebar_label: "EKS with ArgoCD" sidebar_position: 100 --- - -```mdx-code-block +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -``` ### Overview diff --git a/docs/layers/application-cicd/lambda/lambda.md b/docs/layers/application-cicd/lambda/lambda.mdx similarity index 96% rename from docs/layers/application-cicd/lambda/lambda.md rename to docs/layers/application-cicd/lambda/lambda.mdx index a5cf5a725..8333d12e0 100644 --- a/docs/layers/application-cicd/lambda/lambda.md +++ b/docs/layers/application-cicd/lambda/lambda.mdx @@ -1,12 +1,13 @@ --- title: "Lambda with GitHub Workflows" +sidebar_label: "Lambda with GitHub Workflows" +description: "Deploy a Lambda functions using GitHub Workflows." sidebar_position: 100 --- - -```mdx-code-block +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -``` ### Overview diff --git a/docs/layers/bonus-tutorials/bonus-tutorials.md b/docs/layers/bonus-tutorials/bonus-tutorials.md deleted file mode 100644 index e409574ee..000000000 --- a/docs/layers/bonus-tutorials/bonus-tutorials.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_class_name: hidden ---- - -# How-to Guides - -How-to guides show how to solve specific problems within SweetOps via a series of easy-to-follow steps. - -## All Guides - -- [How to Get Started](/reference-architecture/fundamentals) -- [How to Log into AWS](reference-architecture/setup/how-to-log-into-aws/) -- [Integrations](/reference-architecture/how-to-guides/integrations) -- [Tutorials](/reference-architecture/how-to-guides/tutorials) -- [Upgrades](/reference-architecture/how-to-guides/upgrades) diff --git a/docs/layers/bonus-tutorials/bonus-tutorials.mdx b/docs/layers/bonus-tutorials/bonus-tutorials.mdx new file mode 100644 index 000000000..4aefb5dd6 --- /dev/null +++ b/docs/layers/bonus-tutorials/bonus-tutorials.mdx @@ -0,0 +1,15 @@ +--- +title: "How-to Guides" +description: Tutorials with easy-to-follow steps. +sidebar_class_name: hidden +--- +import Intro from '@site/src/components/Intro' +import DocCardList from '@theme/DocCardList' + + +How-to guides show how to solve specific problems within SweetOps via a series of easy-to-follow steps. + + +## All Guides + + diff --git a/docs/layers/bonus-tutorials/design-decisions/archived-decisions/archived-decisions.md b/docs/layers/bonus-tutorials/design-decisions/archived-decisions/archived-decisions.mdx similarity index 79% rename from docs/layers/bonus-tutorials/design-decisions/archived-decisions/archived-decisions.md rename to docs/layers/bonus-tutorials/design-decisions/archived-decisions/archived-decisions.mdx index b1036b457..752d49ce0 100644 --- a/docs/layers/bonus-tutorials/design-decisions/archived-decisions/archived-decisions.md +++ b/docs/layers/bonus-tutorials/design-decisions/archived-decisions/archived-decisions.mdx @@ -1,6 +1,7 @@ --- title: "Archived Decisions" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1184432667/Archived+Decisions +sidebar_label: "Archived Decisions" +description: "These Design Decisions have been superseded and are no longer used." sidebar_position: 10 --- diff --git a/docs/layers/bonus-tutorials/design-decisions/archived-decisions/decide-on-rds-requirements.md b/docs/layers/bonus-tutorials/design-decisions/archived-decisions/decide-on-rds-requirements.mdx similarity index 71% rename from docs/layers/bonus-tutorials/design-decisions/archived-decisions/decide-on-rds-requirements.md rename to docs/layers/bonus-tutorials/design-decisions/archived-decisions/decide-on-rds-requirements.mdx index d86da5eee..fbfff62da 100644 --- a/docs/layers/bonus-tutorials/design-decisions/archived-decisions/decide-on-rds-requirements.md +++ b/docs/layers/bonus-tutorials/design-decisions/archived-decisions/decide-on-rds-requirements.mdx @@ -1,6 +1,6 @@ --- title: "Decide on RDS requirements" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1173520412/REFARCH-363+-+Decide+on+RDS+requirements +sidebar_label: "RDS Requirements" sidebar_position: 100 refarch_id: REFARCH-363 --- diff --git a/docs/layers/bonus-tutorials/design-decisions/archived-decisions/decide-on-status-page-requirements.md b/docs/layers/bonus-tutorials/design-decisions/archived-decisions/decide-on-status-page-requirements.mdx similarity index 75% rename from docs/layers/bonus-tutorials/design-decisions/archived-decisions/decide-on-status-page-requirements.md rename to docs/layers/bonus-tutorials/design-decisions/archived-decisions/decide-on-status-page-requirements.mdx index 9f3b9d483..90ae51759 100644 --- a/docs/layers/bonus-tutorials/design-decisions/archived-decisions/decide-on-status-page-requirements.md +++ b/docs/layers/bonus-tutorials/design-decisions/archived-decisions/decide-on-status-page-requirements.mdx @@ -1,6 +1,6 @@ --- title: "Decide on Status Page Requirements" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1171947803/REFARCH-467+-+Decide+on+Status+Page+Requirements +sidebar_label: "Status Page Requirements" sidebar_position: 100 refarch_id: REFARCH-467 --- @@ -8,7 +8,7 @@ refarch_id: REFARCH-467 # Decide on Status Page Requirements ## Problem -The business may be obligated or want to communicate transparently to customers' the availability of all services affecting the platforms/products stability. +The business may be obligated or want to communicate transparently to customers the availability of all services affecting the platforms/products stability. ## Solution Use [StatusPage.io](http://StatusPage.io) by Atlassian to integrate with OpsGenie and other dependent services to communicate overall availability. diff --git a/docs/layers/bonus-tutorials/design-decisions/decide-on-api-gateway-requirements.md b/docs/layers/bonus-tutorials/design-decisions/decide-on-api-gateway-requirements.mdx similarity index 97% rename from docs/layers/bonus-tutorials/design-decisions/decide-on-api-gateway-requirements.md rename to docs/layers/bonus-tutorials/design-decisions/decide-on-api-gateway-requirements.mdx index 817853a17..2d2aadfa8 100644 --- a/docs/layers/bonus-tutorials/design-decisions/decide-on-api-gateway-requirements.md +++ b/docs/layers/bonus-tutorials/design-decisions/decide-on-api-gateway-requirements.mdx @@ -1,15 +1,16 @@ --- title: "Decide on API Gateway Requirements" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1423867939/REFARCH-540+-+Decide+on+API+Gateway+Requirements +sidebar_label: "API Gateway" sidebar_position: 100 refarch_id: REFARCH-540 --- - -# Decide on API Gateway Requirements +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Context and Problem Statement ## Overview + Amazon API Gateway is an AWS service designed to simplify publishing highly-scalable REST, HTTP, and WebSocket APIs. These API Gateways act as a central point of access at the edge and can access backend services running on EC2, EKS, ECS, Lambda, and AWS Services directly, such as DynamoDB, S3, or SQS. The API Gateway has several benefits over a conventional ALB in that it’s optimized for APIs: namely, it can authenticate requests, cache, rate-limiting, feature flagging, a/b testing, rewrite requests/responses, aggregate requests, etc. It’s arguably a simpler alternative to using something like a Service Mesh. ## Common Scenarios diff --git a/docs/layers/bonus-tutorials/design-decisions/decide-on-cloudfront-requirements.md b/docs/layers/bonus-tutorials/design-decisions/decide-on-cloudfront-requirements.mdx similarity index 97% rename from docs/layers/bonus-tutorials/design-decisions/decide-on-cloudfront-requirements.md rename to docs/layers/bonus-tutorials/design-decisions/decide-on-cloudfront-requirements.mdx index cd2466465..310d9a0a8 100644 --- a/docs/layers/bonus-tutorials/design-decisions/decide-on-cloudfront-requirements.md +++ b/docs/layers/bonus-tutorials/design-decisions/decide-on-cloudfront-requirements.mdx @@ -1,13 +1,14 @@ --- title: "Decide on CloudFront Requirements" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1365016609/REFARCH-530+-+Decide+on+CloudFront+Requirements +sidebar_label: "CloudFront Requirements" sidebar_position: 100 refarch_id: REFARCH-530 --- - -# Decide on CloudFront Requirements +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Context and Problem Statement + A CDN such as CloudFront speeds up the user experience primarily in 2 ways. 1. **Caching.** By caching content on a server closer to the user (called the “edge server”), the user can benefit from the much shorter connection path to the nearby server, obtaining responses much more quickly. diff --git a/docs/layers/bonus-tutorials/design-decisions/decide-on-cognito-requirements.md b/docs/layers/bonus-tutorials/design-decisions/decide-on-cognito-requirements.mdx similarity index 96% rename from docs/layers/bonus-tutorials/design-decisions/decide-on-cognito-requirements.md rename to docs/layers/bonus-tutorials/design-decisions/decide-on-cognito-requirements.mdx index 5e884a332..561ffd680 100644 --- a/docs/layers/bonus-tutorials/design-decisions/decide-on-cognito-requirements.md +++ b/docs/layers/bonus-tutorials/design-decisions/decide-on-cognito-requirements.mdx @@ -1,18 +1,20 @@ --- title: "Decide on Cognito Requirements" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1365213271/REFARCH-525+-+Decide+on+Cognito+Requirements +sidebar_label: "Cognito Requirements" sidebar_position: 100 refarch_id: REFARCH-525 --- - -# Decide on Cognito Requirements +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Overview + Amazon Cognito provides authentication, authorization, and user management for your web and mobile apps. Users can sign in directly with a user name and password stored in Cognito or through a third party such as a SAML IdP, OIDC, Facebook, Amazon, Google, or Apple. There are two main components to Amazon Cognito: User Pools and Identity Pools. User Pools are directories of your applications’ users while Identity Pools are used to grant application users access to other AWS services such as S3. User Pools and Identity Pools can be used together or separately, depending on your needs. ## Common Scenarios + There are several common use cases for Cognito, some of the most common of which are detailed below. To configure the Cognito component, we’ll need to know as much as possible about your configuration. Ideally, you’ve already set it up previously and can share the precise configuration you’re using. ### App Authentication and Authorization diff --git a/docs/layers/bonus-tutorials/design-decisions/decide-on-iam-roles-for-github-action-runners.md b/docs/layers/bonus-tutorials/design-decisions/decide-on-iam-roles-for-github-action-runners.mdx similarity index 92% rename from docs/layers/bonus-tutorials/design-decisions/decide-on-iam-roles-for-github-action-runners.md rename to docs/layers/bonus-tutorials/design-decisions/decide-on-iam-roles-for-github-action-runners.mdx index 175f603d6..117805dcb 100644 --- a/docs/layers/bonus-tutorials/design-decisions/decide-on-iam-roles-for-github-action-runners.md +++ b/docs/layers/bonus-tutorials/design-decisions/decide-on-iam-roles-for-github-action-runners.mdx @@ -1,13 +1,14 @@ --- title: "Decide on IAM Roles for GitHub Action Runners" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1175978160/REFARCH-305+-+Decide+on+IAM+Roles+for+GitHub+Action+Runners +sidebar_label: "IAM Roles for GitHub Action Runners" sidebar_position: 100 refarch_id: REFARCH-305 --- - -# Decide on IAM Roles for GitHub Action Runners +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem + In order for GitHub Actions runners to be able to access AWS resources, they need to be able to assume an IAM role. The trust relationship of this IAM role depends on how the Runners are hosted: diff --git a/docs/layers/bonus-tutorials/design-decisions/decide-on-kinesis-requirements.md b/docs/layers/bonus-tutorials/design-decisions/decide-on-kinesis-requirements.mdx similarity index 95% rename from docs/layers/bonus-tutorials/design-decisions/decide-on-kinesis-requirements.md rename to docs/layers/bonus-tutorials/design-decisions/decide-on-kinesis-requirements.mdx index 854ed5016..0142df5ce 100644 --- a/docs/layers/bonus-tutorials/design-decisions/decide-on-kinesis-requirements.md +++ b/docs/layers/bonus-tutorials/design-decisions/decide-on-kinesis-requirements.mdx @@ -1,17 +1,18 @@ --- title: "Decide on Kinesis Requirements" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1365409860/REFARCH-527+-+Decide+on+Kinesis+Requirements +sidebar_label: "Kinesis Requirements" sidebar_position: 100 refarch_id: REFARCH-527 --- - -# Decide on Kinesis Requirements +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Context and Problem Statement Amazon Kinesis collects, processes, and analyzes real-time, streaming data to get timely insights and react quickly to new information. It provides key capabilities to cost-effectively process streaming data at any scale, along with the flexibility to choose the tools that best suit the requirements of your application. Frequently, it’s used to ingest real-time data such as video, audio, application logs, website clickstreams, and IoT telemetry data for machine learning, analytics, and other applications. With Kinesis, information can be acted on as soon as it arrives, so apps can respond instantly instead of waiting until all data is collected before processing. ## Considered Options + Kinesis has 4 major use-cases: streaming, firehose, analytics, and video. We have experience working with streams and firehose, but not the newer analytics and video offerings. **AWS Kinesis Data Streams** is for real-time data streaming. It can continuously capture gigabyte-scale data every second from multiple sources. It’s basically Amazon’s proprietary alternative to Kafka. diff --git a/docs/layers/bonus-tutorials/design-decisions/decide-on-kms-requirements.md b/docs/layers/bonus-tutorials/design-decisions/decide-on-kms-requirements.mdx similarity index 99% rename from docs/layers/bonus-tutorials/design-decisions/decide-on-kms-requirements.md rename to docs/layers/bonus-tutorials/design-decisions/decide-on-kms-requirements.mdx index 3c9d41a5e..ec0ed7976 100644 --- a/docs/layers/bonus-tutorials/design-decisions/decide-on-kms-requirements.md +++ b/docs/layers/bonus-tutorials/design-decisions/decide-on-kms-requirements.mdx @@ -1,14 +1,16 @@ --- title: "Decide on KMS Requirements" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1364951148/REFARCH-532+-+Decide+on+KMS+Requirements +sidebar_label: "KMS Requirements" sidebar_position: 100 refarch_id: REFARCH-532 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; -# Decide on KMS Requirements AWS Key Management Service (AWS KMS) makes it easy to create and manage cryptographic keys and control their use across various AWS services and in your applications. AWS KMS is a secure and resilient service that uses hardware security modules that have been validated under FIPS 140-2, or are in the process of being validated, to protect your keys. AWS KMS is integrated with AWS CloudTrail to provide you with logs of all key usage to help meet your regulatory and compliance needs. ## Context and Problem Statement + Best practice, security certifications, and compliance regulations require that data be “encrypted at rest.” AWS provides options for encrypting data at rest virtually anywhere AWS provides for data storage. However, there remain considerations regarding managing the encryption _keys_ for the encrypted data. Consideration should begin with a review of governmental, industry, and corporate compliance requirements, standards, and goals regarding encryption at rest, auditability, data localization, data preservation and recovery, high availability, and disaster recovery. Cloud Posse does not provide advice on compliance requirements, it is up to the client to determine their own needs. For example, here is AWS' approach to HIPAA compliance, summarized: diff --git a/docs/layers/bonus-tutorials/design-decisions/decide-on-transactional-email-smtp-provider-for-operational-email.md b/docs/layers/bonus-tutorials/design-decisions/decide-on-transactional-email-smtp-provider-for-operational-email.mdx similarity index 86% rename from docs/layers/bonus-tutorials/design-decisions/decide-on-transactional-email-smtp-provider-for-operational-email.md rename to docs/layers/bonus-tutorials/design-decisions/decide-on-transactional-email-smtp-provider-for-operational-email.mdx index a38b34674..7fb3be8ab 100644 --- a/docs/layers/bonus-tutorials/design-decisions/decide-on-transactional-email-smtp-provider-for-operational-email.md +++ b/docs/layers/bonus-tutorials/design-decisions/decide-on-transactional-email-smtp-provider-for-operational-email.mdx @@ -1,18 +1,20 @@ --- title: "Decide on Transactional Email (SMTP) Provider for Operational Emails" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1175650562/REFARCH-79+-+Decide+on+Transactional+Email+%28SMTP%29+Provider+for+Operational+Emails +sidebar_label: "Transactional Email (SMTP) Provider" sidebar_position: 100 refarch_id: REFARCH-79 --- - -# Decide on Transactional Email (SMTP) Provider for Operational Emails +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem + We’ll want to have an SMTP email gateway that’s used by services like Alert Manager, Sentry, Printunl, et al to send emails. ## Considered Options #### AWS SES + Our recommended option is to provision an SES gateway using our [https://github.com/cloudposse/terraform-aws-ses](https://github.com/cloudposse/terraform-aws-ses) module for this. It’s also worth noting is that every AWS SES starts in Sandbox. Sending emails via it (emails not verified in AWS SES) is only allowed after support requests (so requires some human intervention to automate). @@ -38,9 +40,11 @@ SES is also only available in the following regions: This will use the vanity branded domain in [Decide on Vanity (Branded) Domain](/reference-architecture/fundamentals/design-decisions/foundational-platform/decide-on-vanity-branded-domain) if SES is used for customer-facing emails. If these are for internal domains then we can use the service discovery domains. #### Mailgun + The other option we typically recommend is mailgun. It’s very economical and easy to integrate with. There’s also a terraform provider for managing mailgun configurations. #### Bring-your-own + We’ll happily integrate with whatever SMTP system your company uses today. :::caution diff --git a/docs/layers/bonus-tutorials/design-decisions/design-decisions.md b/docs/layers/bonus-tutorials/design-decisions/design-decisions.md deleted file mode 100644 index fd406c9f0..000000000 --- a/docs/layers/bonus-tutorials/design-decisions/design-decisions.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: "Design Decisions" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1168212012/Design+Decisions -sidebar_position: 200 ---- - -# Design Decisions -Design Decisions are architectural considerations for how to approach or implement some sort of functionality. Each Design Decision references the corresponding REFARCH ticket in jira. The decision outcomes should be documented as Architectural Design Records (ADRs). - -See [https://cloudposse.atlassian.net/wiki/pages/resumedraft.action?draftId=1173454868](https://cloudposse.atlassian.net/wiki/pages/resumedraft.action?draftId=1173454868) for adding design decisions to this reference architecture as well as [How to write ADRs](/reference-architecture/how-to-guides/tutorials/how-to-write-adrs) . - -:::note -This is our entire reference catalog of Design Decisions and not all may be relevant to the scope of a particular engagement. - -::: - -## Recently Updated - -## All Decisions - -They are broken down in the following way: - -- [Cold Start](/reference-architecture/fundamentals/design-decisions/cold-start) -- [Foundational Infrastructure](/reference-architecture/fundamentals/design-decisions/foundational-infrastructure) -- [Foundational Platform](/reference-architecture/fundamentals/design-decisions/foundational-platform) -- [Foundational Monitoring Platform](/reference-architecture/fundamentals/design-decisions/foundational-monitoring-platform) -- [Foundational Release Engineering](/reference-architecture/fundamentals/design-decisions/foundational-release-engineering) -- [Foundational Incident Management](/reference-architecture/fundamentals/design-decisions/foundational-incident-management) -- [Foundational Benchmark Compliance](/reference-architecture/fundamentals/design-decisions/foundational-benchmark-compliance) -- [Foundational Application Dependencies](/reference-architecture/fundamentals/design-decisions/foundational-application-dependencies) -- [Archived Decisions](/reference-architecture/fundamentals/design-decisions/archived-decisions) -- [Decide on Datadog Log Forwarding Requirements](/reference-architecture/fundamentals/design-decisions/decide-on-datadog-log-forwarding-requirements) -- [Decide on Terraform State Backend Architecture](/reference-architecture/fundamentals/design-decisions/decide-on-terraform-state-backend-architecture) -- [Decide on Cognito Requirements](/reference-architecture/fundamentals/design-decisions/decide-on-cognito-requirements) -- [Decide on Kinesis Requirements](/reference-architecture/fundamentals/design-decisions/decide-on-kinesis-requirements) -- [Decide on CloudFront Requirements](/reference-architecture/fundamentals/design-decisions/decide-on-cloudfront-requirements) -- [Decide on KMS Requirements](/reference-architecture/fundamentals/design-decisions/decide-on-kms-requirements) -- [Decide on Strategy for Continuous Deployment](/reference-architecture/fundamentals/design-decisions/decide-on-strategy-for-continuous-deployment) -- [Decide on CI/CD Platform](/reference-architecture/fundamentals/design-decisions/decide-on-ci-cd-platform) -- [Decide on Strategy for Managing and Orchestrating Secrets](/reference-architecture/fundamentals/design-decisions/decide-on-strategy-for-managing-and-orchestrating-secrets) -- [Decide on API Gateway Requirements](/reference-architecture/fundamentals/design-decisions/decide-on-api-gateway-requirements) -- [Decide on IPv4 and IPv6 support](/reference-architecture/fundamentals/design-decisions/decide-on-ipv4-and-ipv6-support) -- [Decide on IAM Roles for GitHub Action Runners](/reference-architecture/fundamentals/design-decisions/decide-on-iam-roles-for-github-action-runners) - - diff --git a/docs/layers/bonus-tutorials/design-decisions/design-decisions.mdx b/docs/layers/bonus-tutorials/design-decisions/design-decisions.mdx new file mode 100644 index 000000000..28561a326 --- /dev/null +++ b/docs/layers/bonus-tutorials/design-decisions/design-decisions.mdx @@ -0,0 +1,26 @@ +--- +title: "Design Decisions" +sidebar_label: "Design Decisions" +sidebar_position: 200 +--- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; +import DocCardList from '@theme/DocCardList' + + +Design Decisions are architectural considerations for how to approach or implement some sort of functionality. The decision outcomes should be documented as Architectural Design Records (ADRs). + + +See [how to document a new design decision](/layers/bonus-tutorials/how-to-document-a-new-design-decision) to this reference architecture as well as [How to write ADRs](/reference-architecture/how-to-guides/tutorials/how-to-write-adrs) . + +:::note +This is our entire reference catalog of Design Decisions and not all may be relevant to the scope of a particular engagement. + +::: + +## All Decisions + +They are broken down in the following way: + + + diff --git a/docs/layers/bonus-tutorials/how-to-customize-the-geodesic-shell.md b/docs/layers/bonus-tutorials/how-to-customize-the-geodesic-shell.mdx similarity index 98% rename from docs/layers/bonus-tutorials/how-to-customize-the-geodesic-shell.md rename to docs/layers/bonus-tutorials/how-to-customize-the-geodesic-shell.mdx index 0d6faac3c..3e21be04a 100644 --- a/docs/layers/bonus-tutorials/how-to-customize-the-geodesic-shell.md +++ b/docs/layers/bonus-tutorials/how-to-customize-the-geodesic-shell.mdx @@ -1,10 +1,10 @@ --- title: "Customize the Geodesic Shell" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1186103470/How+to+Customize+the+Geodesic+Shell +sidebar_label: "Customize the Geodesic Shell" sidebar_position: 100 --- - -# How to Customize the Geodesic Shell +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem diff --git a/docs/layers/bonus-tutorials/how-to-define-stacks-for-multiple-regions.md b/docs/layers/bonus-tutorials/how-to-define-stacks-for-multiple-regions.mdx similarity index 91% rename from docs/layers/bonus-tutorials/how-to-define-stacks-for-multiple-regions.md rename to docs/layers/bonus-tutorials/how-to-define-stacks-for-multiple-regions.mdx index 499142c11..dd1833251 100644 --- a/docs/layers/bonus-tutorials/how-to-define-stacks-for-multiple-regions.md +++ b/docs/layers/bonus-tutorials/how-to-define-stacks-for-multiple-regions.mdx @@ -1,10 +1,11 @@ --- -title: "Define Multiple Regions" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1186365815 +title: "How to Define Stacks for Multiple Regions?" +sidebar_label: "Define Multiple Regions" +description: "How to define stacks for multiple regions" sidebar_position: 100 --- - -# How to Define Stacks for Multiple Regions? +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem diff --git a/docs/layers/bonus-tutorials/how-to-document-a-new-design-decision.md b/docs/layers/bonus-tutorials/how-to-document-a-new-design-decision.mdx similarity index 96% rename from docs/layers/bonus-tutorials/how-to-document-a-new-design-decision.md rename to docs/layers/bonus-tutorials/how-to-document-a-new-design-decision.mdx index 45f37d18d..06a490afc 100644 --- a/docs/layers/bonus-tutorials/how-to-document-a-new-design-decision.md +++ b/docs/layers/bonus-tutorials/how-to-document-a-new-design-decision.mdx @@ -1,10 +1,10 @@ --- -title: "Document a New Design Decision" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1173454868/How+to+Document+a+New+Design+Decision +title: "How to Document a New Design Decision" +sidebar_label: "Document a New Design Decision" sidebar_position: 100 --- - -# How to Document a New Design Decision +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem diff --git a/docs/layers/bonus-tutorials/how-to-load-test-in-aws.md b/docs/layers/bonus-tutorials/how-to-load-test-in-aws.mdx similarity index 97% rename from docs/layers/bonus-tutorials/how-to-load-test-in-aws.md rename to docs/layers/bonus-tutorials/how-to-load-test-in-aws.mdx index 0f03947c0..ecdbef5ce 100644 --- a/docs/layers/bonus-tutorials/how-to-load-test-in-aws.md +++ b/docs/layers/bonus-tutorials/how-to-load-test-in-aws.mdx @@ -1,12 +1,13 @@ --- -title: "Load Test in AWS" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1257799689/How+to+Load+Test+in+AWS +title: "How to Load Test in AWS" +sidebar_label: "Load Test in AWS" sidebar_position: 100 --- - -# How to Load Test in AWS +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem + You’re tasked with load testing a service in AWS. You need to understand what can adversely affect your testing and anything to be aware of before beginning your tests. ## Solution diff --git a/docs/layers/bonus-tutorials/how-to-manage-terraform-dependencies-in-micro-service-repositori.md b/docs/layers/bonus-tutorials/how-to-manage-terraform-dependencies-in-micro-service-repositori.mdx similarity index 97% rename from docs/layers/bonus-tutorials/how-to-manage-terraform-dependencies-in-micro-service-repositori.md rename to docs/layers/bonus-tutorials/how-to-manage-terraform-dependencies-in-micro-service-repositori.mdx index 40e84a708..50ee60222 100644 --- a/docs/layers/bonus-tutorials/how-to-manage-terraform-dependencies-in-micro-service-repositori.md +++ b/docs/layers/bonus-tutorials/how-to-manage-terraform-dependencies-in-micro-service-repositori.mdx @@ -1,12 +1,13 @@ --- -title: "Manage Terraform Dependencies" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1212448779/How+to+Manage+Terraform+Dependencies+in+Micro-service+Repositories +title: "How to Manage Terraform Dependencies in Micro-service Repositories" +sidebar_label: "Manage Terraform Dependencies" sidebar_position: 100 --- - -# How to Manage Terraform Dependencies in Micro-service Repositories +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem + The organization’s infrastructure monorepo (commonly located in GitHub at `[organization]/infrastructure`, `[organization]/infra`, etc.) is responsible for managing the organization’s foundational infrastructure, such as: - AWS Accounts diff --git a/docs/layers/bonus-tutorials/how-to-rollback-terraform-state-for-a-component-rollback-terrafo.md b/docs/layers/bonus-tutorials/how-to-rollback-terraform-state-for-a-component-rollback-terraform.mdx similarity index 92% rename from docs/layers/bonus-tutorials/how-to-rollback-terraform-state-for-a-component-rollback-terrafo.md rename to docs/layers/bonus-tutorials/how-to-rollback-terraform-state-for-a-component-rollback-terraform.mdx index 7f1f7081d..f6b321eb6 100644 --- a/docs/layers/bonus-tutorials/how-to-rollback-terraform-state-for-a-component-rollback-terrafo.md +++ b/docs/layers/bonus-tutorials/how-to-rollback-terraform-state-for-a-component-rollback-terraform.mdx @@ -1,17 +1,18 @@ --- -title: "Rollback Terraform State" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1245610009 +title: "How to rollback Terraform state for a component" +sidebar_label: "Rollback Terraform State" sidebar_position: 100 +description: "How to Rollback Terraform State for a Component (rollback `terraform.tfstate` file to a previous version)" --- - -# How to Rollback Terraform State for a Component (rollback `terraform.tfstate` file to a previous version) +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem If Terraform state for a component gets corrupted or lost for some reason, it’s possible to rollback the terraform state to a previous version since we use S3 bucket versioning on all state objects. -## -Solution +## Solution + Components represent terraform “root” modules and their Terraform state is stored in an s3 state bucket. Rolling back to that state requires a series of commands to be executed under the appropriate IAM role. 1. Assume the `root-admin` IAM role to be able to access s3 buckets in the `root` account. From `geodesic`, run the following command (replace `` with your company namespace): diff --git a/docs/layers/bonus-tutorials/how-to-rotate-kops-master-node-certificates.md b/docs/layers/bonus-tutorials/how-to-rotate-kops-master-node-certificates.mdx similarity index 87% rename from docs/layers/bonus-tutorials/how-to-rotate-kops-master-node-certificates.md rename to docs/layers/bonus-tutorials/how-to-rotate-kops-master-node-certificates.mdx index 19630d0be..1ce6f9290 100644 --- a/docs/layers/bonus-tutorials/how-to-rotate-kops-master-node-certificates.md +++ b/docs/layers/bonus-tutorials/how-to-rotate-kops-master-node-certificates.mdx @@ -1,15 +1,18 @@ --- -title: "Rotate Kops Master Node Certificates" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1381990476/How+to+Rotate+Kops+Master+Node+Certificates +title: "How to Rotate Kops Master Node Certificates" +sidebar_label: "Rotate Kops Certificates" sidebar_position: 100 +description: "How to Rotate Kops Master Node Certificates" --- - -# How to Rotate Kops Master Node Certificates +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem + Old Kubernetes clusters (deployed prior to Kubernetes 1.16.2) may require manual certificate rotation. When the certificates expire, the master nodes can no longer communicate and the cluster becomes destabilized. ## Solution + If the master nodes are all still operating normally, then upgrading to Kubernetes 1.16.2 or later should fix the issue and prevent it from recurring. However, if master nodes are already off line due to expired certificates, you will need to rotate them manually. :::tip @@ -59,6 +62,7 @@ echo | openssl s_client -connect localhost:2380 2>/dev/null | openssl x509 -noou ### Repeat this entire process on all master nodes ### Verify cluster healthy + Wait for pods to show as `Ready` ``` diff --git a/docs/layers/bonus-tutorials/how-to-run-docker-in-docker-with-geodesic.md b/docs/layers/bonus-tutorials/how-to-run-docker-in-docker-with-geodesic.mdx similarity index 88% rename from docs/layers/bonus-tutorials/how-to-run-docker-in-docker-with-geodesic.md rename to docs/layers/bonus-tutorials/how-to-run-docker-in-docker-with-geodesic.mdx index 48f2c8866..4e0f78cfc 100644 --- a/docs/layers/bonus-tutorials/how-to-run-docker-in-docker-with-geodesic.md +++ b/docs/layers/bonus-tutorials/how-to-run-docker-in-docker-with-geodesic.mdx @@ -1,10 +1,10 @@ --- -title: "Run Docker-in-Docker with Geodesic" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1186332735 +title: "How to run Docker-in-Docker with Geodesic?" +sidebar_label: "Run Docker-in-Docker with Geodesic" sidebar_position: 100 --- - -# How to run Docker-in-Docker with Geodesic? +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem diff --git a/docs/layers/bonus-tutorials/how-to-support-govcloud-and-other-aws-partitions-with-terraform.md b/docs/layers/bonus-tutorials/how-to-support-govcloud-and-other-aws-partitions-with-terraform.mdx similarity index 73% rename from docs/layers/bonus-tutorials/how-to-support-govcloud-and-other-aws-partitions-with-terraform.md rename to docs/layers/bonus-tutorials/how-to-support-govcloud-and-other-aws-partitions-with-terraform.mdx index b2bbf39e1..ebd5842d4 100644 --- a/docs/layers/bonus-tutorials/how-to-support-govcloud-and-other-aws-partitions-with-terraform.md +++ b/docs/layers/bonus-tutorials/how-to-support-govcloud-and-other-aws-partitions-with-terraform.mdx @@ -1,10 +1,10 @@ --- -title: "Support GovCloud and Other AWS Partitions" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1186365528/How+to+support+GovCloud+and+Other+AWS+Partitions+with+Terraform +title: "How to support GovCloud and Other AWS Partitions with Terraform" +sidebar_label: "Support GovCloud and Other AWS Partitions" sidebar_position: 100 --- - -# How to support GovCloud and Other AWS Partitions with Terraform +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem @@ -17,7 +17,7 @@ Most Cloud Posse terraform modules should work in these partitions. ::: -For services available in the China regions, see [https://www.amazonaws.cn/en/about-aws/regional-product-services/](https://www.amazonaws.cn/en/about-aws/regional-product-services/) . For services available in GovCloud, consult [https://docs.aws.amazon.com/govcloud-us/latest/UserGuide/using-services.html](https://docs.aws.amazon.com/govcloud-us/latest/UserGuide/using-services.html) . +For services available in the China regions, see [https://www.amazonaws.cn/en/about-aws/regional-product-services/](https://www.amazonaws.cn/en/about-aws/regional-product-services/). For services available in GovCloud, consult [https://docs.aws.amazon.com/govcloud-us/latest/UserGuide/using-services.html](https://docs.aws.amazon.com/govcloud-us/latest/UserGuide/using-services.html). In order to support multiple partitions in HCL, simply use the following convention leveraging the `aws_partition` data source anywhere you need to construct an ARN. @@ -39,4 +39,3 @@ data "aws_iam_policy_document" "bucket_policy" { } } ``` - diff --git a/docs/layers/bonus-tutorials/how-to-switch-versions-of-terraform.md b/docs/layers/bonus-tutorials/how-to-switch-versions-of-terraform.mdx similarity index 93% rename from docs/layers/bonus-tutorials/how-to-switch-versions-of-terraform.md rename to docs/layers/bonus-tutorials/how-to-switch-versions-of-terraform.mdx index 435e8985c..171a8e27f 100644 --- a/docs/layers/bonus-tutorials/how-to-switch-versions-of-terraform.md +++ b/docs/layers/bonus-tutorials/how-to-switch-versions-of-terraform.mdx @@ -1,17 +1,19 @@ --- -title: "Switch Versions of Terraform" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1190330414/How+to+Switch+Versions+of+Terraform +title: "How to Switch Versions of Terraform" +sidebar_label: "Switch Versions of Terraform" sidebar_position: 100 --- - -# How to Switch Versions of Terraform +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem + You need to use (or want to upgrade to) the latest version of terraform for a component you’re working on, but do not want to affect other components. ## Solution #### Install Desired Version of Terraform + First, make sure you’ve installed the latest version of `terraform` in [Geodesic](/fundamentals/geodesic) by following our guide [How to Upgrade or Install Versions of Terraform](/reference-architecture/how-to-guides/upgrades/how-to-upgrade-or-install-versions-of-terraform). #### Switch Terraform Versions (Local Geodesic Shell) @@ -27,6 +29,7 @@ update-alternatives --set terraform /usr/share/terraform/${Major.Minor}/bin/terr ``` ### Terraform Releases + [https://github.com/hashicorp/terraform/releases](https://github.com/hashicorp/terraform/releases) #### Switch Terraform Versions for a Component on a stack diff --git a/docs/layers/bonus-tutorials/how-to-terraform-non-aws-infrastructure.md b/docs/layers/bonus-tutorials/how-to-terraform-non-aws-infrastructure.mdx similarity index 89% rename from docs/layers/bonus-tutorials/how-to-terraform-non-aws-infrastructure.md rename to docs/layers/bonus-tutorials/how-to-terraform-non-aws-infrastructure.mdx index 6ac297553..05848db2f 100644 --- a/docs/layers/bonus-tutorials/how-to-terraform-non-aws-infrastructure.md +++ b/docs/layers/bonus-tutorials/how-to-terraform-non-aws-infrastructure.mdx @@ -1,10 +1,10 @@ --- -title: "Terraform non-AWS Infrastructure" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1182334977 +title: "How to terraform non-AWS infrastructure?" +sidebar_label: "Terraform non-AWS Infrastructure" sidebar_position: 100 --- - -# How to terraform non-AWS infrastructure? +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem diff --git a/docs/layers/bonus-tutorials/how-to-use-atmos-with-existing-terraform.md b/docs/layers/bonus-tutorials/how-to-use-atmos-with-existing-terraform.mdx similarity index 97% rename from docs/layers/bonus-tutorials/how-to-use-atmos-with-existing-terraform.md rename to docs/layers/bonus-tutorials/how-to-use-atmos-with-existing-terraform.mdx index ca16ee55c..d6bffd2c6 100644 --- a/docs/layers/bonus-tutorials/how-to-use-atmos-with-existing-terraform.md +++ b/docs/layers/bonus-tutorials/how-to-use-atmos-with-existing-terraform.mdx @@ -1,12 +1,13 @@ --- -title: "Use Atmos with Existing Terraform" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1195769857/How+to+Use+Atmos+with+Existing+Terraform +title: "How to Use Atmos with Existing Terraform" +sidebar_label: "Use Atmos with Existing Terraform" sidebar_position: 100 --- - -# How to Use Atmos with Existing Terraform +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem + Not everyone beginning to implement Atmos is starting with a clean slate, and many users would like to put Atmos to use with their existing Terraform infrastructure. However, the SweetOps approach is highly opinionated and as a result, can be intimidating for new users to begin to apply the practices to existing infrastructure. How can we leverage Atmos to incrementally build off our existing Terraform infrastructure and begin to DRY variable configurations? ## Solution @@ -28,6 +29,7 @@ Applying Atmos to existing infrastructure can be an easy process if broken into ::: ### **Part 1**: Organization + The first and foremost key to success with Atmos is organization. Organization of Terraform components, variables, and environment configuration naturally lead to DRY code, easier understanding, and less room for errors. With Atmos, we organize all `components` ([Components](/components)) and variables configuration, referred to as `stacks` ([Stacks](/fundamentals/stacks)), into respective folders. An example layout would look like the following: ``` @@ -41,6 +43,7 @@ infrastructure/ ``` #### Steps + 1. Decide on a unique name to give your components. Make sure if follows our [Components](/components). 2. Create the folder in `components/terraform` with the given name of the component @@ -48,6 +51,7 @@ infrastructure/ 3. Move all existing Terraform code to the path `components/terraform`. ### **Part 2**: Stacks + Stacks are what Atmos uses to define configuration and variables for each component in any environment. Our standard convention is that each `stack` operates in a given region and environment; for example, `ue1-nonprod.yaml` defines the configuration for `nonprod` operating in the `us-east-1` region. Anything included in these stacks should be **unique** to that given region and environment or be imported by a global configuration file. Read more about [Stacks](/fundamentals/stacks) ``` @@ -62,6 +66,7 @@ infrastructure/ ``` #### Steps + 1. Create a `yaml` file for each environment and region 2. Use the following as an example to start each stack. Only include unique configuration for the given environment and region. @@ -76,6 +81,7 @@ components: ``` ### **Part 3**: Catalog + The `catalog` defines every component available to use. Each component is given a configuration file within the `catalog` where common config is set. For example, a basic configuration for a component called `ec2-instance` would look like the following: @@ -93,6 +99,7 @@ components: When we want to use a `component` with a `stack`, we can import that `component` from the `catalog`. Then that given `stack` can define unique variables for that `component`. Read more about the `catalog` and how to use imports under [How to Use Imports and Catalogs in Stacks](/reference-architecture/how-to-guides/tutorials/how-to-use-imports-and-catalogs-in-stacks) #### Steps + 1. Create the `catalog` folder under `stacks/` 2. Create a `yaml` configuration file for each component. @@ -105,9 +112,11 @@ import: ``` ### **Part 4**: DRY Components + Another key concept with Atmos is to avoid all variable repetition; any non-unique variable should only be specified a single time. With Atmos, they are usually three places to define a variable: #### Component variables + There are variables defined with the Terraform component in `components/terraform` and are nonspecific to your organization. Typically default values are included with `defaults.tfvars`. For example: ``` @@ -116,6 +125,7 @@ enabled = false ``` #### Catalog variables + Variables defined within the catalog can be specific to your organization but should be nonspecific to any region or environment. For example, a catalog configuration might look like the following: ``` @@ -133,6 +143,7 @@ components: ``` #### Stack variables + Stack variables include any variables defined specifically for an environment, region, or a combination of the two. Define these in the most optimal way to avoid any repetition between stacks, and use imports as necessary to pull shared configuration. In this example below, the us-east-1 sandbox stack pulls the shared configuration for us-east-1, imports the `ec2-instance` component, and defines unique variables for the `vpc` component. ``` @@ -152,14 +163,17 @@ components: ``` #### Steps + 1. Copy any unique variables from the Terraform component into the highest stack level possible 2. Remove any non-general variables from the Terraform component ### **Part 5**: Importing State + Atmos supports all built-in [Terraform Subcommands](https://www.terraform.io/docs/cli/commands/index.html), including `import`. Once the components and stacks are properly created, running `atmos terraform import -s ` will pull the existing state for any resource. Each resource in the existing Terraform state will need to be imported into the new Atmos-created Terraform state. See the [Terraform documentation on import](https://www.terraform.io/docs/cli/import/index.html) for additional details. ## Summary + At this point, all Terraform components should be defined under `components/terraform` and all variables configurations listed in `stacks/catalog`. Any deployment into a given environment and region is listed within the given `stack` with an import. For example: ``` @@ -178,6 +192,7 @@ infrastructure/ ``` #### Next Steps + Now that your environment is properly configured, follow the [Atmos](/fundamentals/atmos) documentation for running commands. diff --git a/docs/layers/bonus-tutorials/how-to-use-atmos.md b/docs/layers/bonus-tutorials/how-to-use-atmos.mdx similarity index 95% rename from docs/layers/bonus-tutorials/how-to-use-atmos.md rename to docs/layers/bonus-tutorials/how-to-use-atmos.mdx index 3c14b10f5..29b06ef0b 100644 --- a/docs/layers/bonus-tutorials/how-to-use-atmos.md +++ b/docs/layers/bonus-tutorials/how-to-use-atmos.mdx @@ -1,10 +1,10 @@ --- -title: "Use Atmos" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1176338474/How+to+use+Atmos +title: "How to use Atmos" +sidebar_label: "Use Atmos" sidebar_position: 100 --- - -# How to use Atmos +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Getting Started diff --git a/docs/layers/bonus-tutorials/how-to-use-imports-and-catalogs-in-stacks.md b/docs/layers/bonus-tutorials/how-to-use-imports-and-catalogs-in-stacks.mdx similarity index 92% rename from docs/layers/bonus-tutorials/how-to-use-imports-and-catalogs-in-stacks.md rename to docs/layers/bonus-tutorials/how-to-use-imports-and-catalogs-in-stacks.mdx index 9745f8677..610093167 100644 --- a/docs/layers/bonus-tutorials/how-to-use-imports-and-catalogs-in-stacks.md +++ b/docs/layers/bonus-tutorials/how-to-use-imports-and-catalogs-in-stacks.mdx @@ -1,10 +1,10 @@ --- -title: "Use Imports and Catalogs in Stacks" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1183973406/How+to+Use+Imports+and+Catalogs+in+Stacks +title: "How to Use Imports and Catalogs in Stacks" +sidebar_label: "Use Imports and Catalogs in Stacks" sidebar_position: 100 --- - -# How to Use Imports and Catalogs in Stacks +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem diff --git a/docs/layers/bonus-tutorials/how-to-use-terraform-remote-state.md b/docs/layers/bonus-tutorials/how-to-use-terraform-remote-state.mdx similarity index 95% rename from docs/layers/bonus-tutorials/how-to-use-terraform-remote-state.md rename to docs/layers/bonus-tutorials/how-to-use-terraform-remote-state.mdx index 4dbfd396d..6d6e9a125 100644 --- a/docs/layers/bonus-tutorials/how-to-use-terraform-remote-state.md +++ b/docs/layers/bonus-tutorials/how-to-use-terraform-remote-state.mdx @@ -1,10 +1,10 @@ --- -title: "Use Terraform Remote State" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1193738389/How+to+Use+Terraform+Remote+State +title: "How to Use Terraform Remote State" +sidebar_label: "Use Terraform Remote State" sidebar_position: 100 --- - -# How to Use Terraform Remote State +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem diff --git a/docs/layers/bonus-tutorials/how-to-version-pin-components-in-stack-configurations.md b/docs/layers/bonus-tutorials/how-to-version-pin-components-in-stack-configurations.mdx similarity index 93% rename from docs/layers/bonus-tutorials/how-to-version-pin-components-in-stack-configurations.md rename to docs/layers/bonus-tutorials/how-to-version-pin-components-in-stack-configurations.mdx index 8e54d461a..ceb62b1a9 100644 --- a/docs/layers/bonus-tutorials/how-to-version-pin-components-in-stack-configurations.md +++ b/docs/layers/bonus-tutorials/how-to-version-pin-components-in-stack-configurations.mdx @@ -1,12 +1,13 @@ --- -title: "Version Pin Components in Stack Configurations" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1183973747/How+to+Version+Pin+Components+in+Stack+Configurations +title: "How to Version Pin Components in Stack Configurations" +sidebar_label: "Version Pin Components" sidebar_position: 100 --- - -# How to Version Pin Components in Stack Configurations +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem + One of the common best practices in Infrastructure as Code is to use strict version pinning. But before we get into the details on how to do this, let’s note that in all of our components and modules, we refer to a module by specific version (e.g. `1.2.3`) or some semver expression (e.g. `~> 1.2.0`). However, in most of our stack configs, you’ll generally see that all stacks refer to the same exact version of a component (e.g. the same exact directory). Doesn’t this violate the principle of version pinning? Not exactly. Rather than pin each environment to a specific version, we’re saying we want to pin all environments to the same version (commit SHA), and instead, release to environments at the cadence we want. The driver behind this is we want all environments to converge on the same version and we want our tools (e.g. Spacelift) to tell us when they diverge. If on the other hand, we were version pinning each environment, then we would need to devise some other strategy to ensure that environments do not diverge. With that said, there are still some situations where we want to forcibly diverge environments for an extended period of time. For example, perhaps some environment will be sunset in the near future, and keeping it current is not worth the effort. In this case, we might want to diverge so we can release hotfixes without needing to upgrade. @@ -43,6 +44,7 @@ There’s nothing special about the `rds@1.2.3` component name. You could use `r Other hacks like Git submodules can be used to accomplish a similar outcome. We just cannot stress enough that practicing version pinning of components by the environment will lead to serious drift and offload the burden to keep the environments updated to engineers, rather than automation. ## Related + - [How to Keep Everything Up to Date](/reference-architecture/how-to-guides/upgrades/how-to-keep-everything-up-to-date) diff --git a/docs/layers/bonus-tutorials/how-to-write-adrs.md b/docs/layers/bonus-tutorials/how-to-write-adrs.mdx similarity index 97% rename from docs/layers/bonus-tutorials/how-to-write-adrs.md rename to docs/layers/bonus-tutorials/how-to-write-adrs.mdx index 8ec63728f..3b0b77076 100644 --- a/docs/layers/bonus-tutorials/how-to-write-adrs.md +++ b/docs/layers/bonus-tutorials/how-to-write-adrs.mdx @@ -1,10 +1,10 @@ --- -title: "Write ADRs" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1171652644/How+to+write+ADRs +title: "How to write ADRs" +sidebar_label: "Write ADRs" sidebar_position: 100 --- - -# How to write ADRs +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; Architectural Design Records (ADRs) are how we capture the decision from our customers and record it in the customer's repository. diff --git a/docs/layers/foundation/component-development.mdx b/docs/layers/component-development/component-development.mdx similarity index 94% rename from docs/layers/foundation/component-development.mdx rename to docs/layers/component-development/component-development.mdx index 7756e7fbb..9f8f95fc0 100644 --- a/docs/layers/foundation/component-development.mdx +++ b/docs/layers/component-development/component-development.mdx @@ -1,21 +1,20 @@ --- -title: "Developing Components" +title: "Component Development" +sidebar_label: "Developing Components" sidebar_position: 100 --- - -# Component Development +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; +import ReactPlayer from "react-player"; # The Problem -While all companies are unique, their infrastructure doesn't need to be. Well-built infrastructure consists of reusable -building blocks that implement all the standard components like servers, clusters, load balancers, etc. Rather than -building everything from scratch “the hard way”, there's an easier way. Using our “reference architecture” and its -service catalog of all the essential pieces of infrastructure, everything a business needs can be composed together as -an architecture using “Stack” configurations. Best of all, it's all native terraform. - -import ReactPlayer from "react-player"; +While all companies are unique, their infrastructure doesn't need to be. Well-built infrastructure consists of reusable building blocks that implement all the standard components like servers, clusters, load balancers, etc. Rather than building everything from scratch “the hard way”, there's an easier way. Using our “reference architecture” and its service catalog of all the essential pieces of infrastructure, everything a business needs can be composed together as an architecture using “Stack” configurations. Best of all, it's all native terraform. - +
+ +
AI generated voice
+
# Our Solution diff --git a/docs/layers/data/09-data.md b/docs/layers/data/09-data.mdx similarity index 85% rename from docs/layers/data/09-data.md rename to docs/layers/data/09-data.mdx index a9645ed1a..0d5e6de7b 100644 --- a/docs/layers/data/09-data.md +++ b/docs/layers/data/09-data.mdx @@ -1,3 +1,10 @@ +--- +title: Data +description: Data layer components +--- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; + # Data ## Quick Start @@ -23,25 +30,25 @@ All deployment steps below assume that the environment has been successfully set At the moment we have support for: -- [Aurora PostgreSQL](https://docs.cloudposse.com/components/library/aws/aurora-postgres/) +- [Aurora PostgreSQL](https://docs.cloudposse.com/components/library/aws/aurora-postgres/) -- [Aurora PostgreSQL Resources](https://docs.cloudposse.com/components/library/aws/aurora-postgres-resources/) +- [Aurora PostgreSQL Resources](https://docs.cloudposse.com/components/library/aws/aurora-postgres-resources/) -- [Aurora MySQL](https://docs.cloudposse.com/components/library/aws/aurora-mysql/) +- [Aurora MySQL](https://docs.cloudposse.com/components/library/aws/aurora-mysql/) -- [Aurora MySQL Resources](https://docs.cloudposse.com/components/library/aws/aurora-mysql-resources/) +- [Aurora MySQL Resources](https://docs.cloudposse.com/components/library/aws/aurora-mysql-resources/) -- [AWS Backup](https://docs.cloudposse.com/components/library/aws/aws-backup/) +- [AWS Backup](https://docs.cloudposse.com/components/library/aws/aws-backup/) -- [DocumentDB](https://docs.cloudposse.com/components/library/aws/documentdb/) +- [DocumentDB](https://docs.cloudposse.com/components/library/aws/documentdb/) -- [DynamoDB](https://docs.cloudposse.com/components/library/aws/dynamodb/) +- [DynamoDB](https://docs.cloudposse.com/components/library/aws/dynamodb/) -- [Elasticsearch Cluster](https://docs.cloudposse.com/components/library/aws/elasticsearch/) +- [Elasticsearch Cluster](https://docs.cloudposse.com/components/library/aws/elasticsearch/) -- [RDS](https://docs.cloudposse.com/components/library/aws/rds/) +- [RDS](https://docs.cloudposse.com/components/library/aws/rds/) -- [RedShift](https://docs.cloudposse.com/components/library/aws/redshift/) +- [RedShift](https://docs.cloudposse.com/components/library/aws/redshift/) - [ElastiCache Redis](https://docs.cloudposse.com/components/library/aws/elasticache-redis/) ### Vendor diff --git a/docs/layers/data/design-decisions/decide-on-amazon-managed-workflows-for-apache-airflow-mwaa-requi.md b/docs/layers/data/design-decisions/decide-on-amazon-managed-workflows-for-apache-airflow-mwaa-requi.mdx similarity index 95% rename from docs/layers/data/design-decisions/decide-on-amazon-managed-workflows-for-apache-airflow-mwaa-requi.md rename to docs/layers/data/design-decisions/decide-on-amazon-managed-workflows-for-apache-airflow-mwaa-requi.mdx index 400a7afc0..9e6906b8f 100644 --- a/docs/layers/data/design-decisions/decide-on-amazon-managed-workflows-for-apache-airflow-mwaa-requi.md +++ b/docs/layers/data/design-decisions/decide-on-amazon-managed-workflows-for-apache-airflow-mwaa-requi.mdx @@ -1,9 +1,10 @@ --- title: "Decide on Amazon Managed Workflows for Apache Airflow (MWAA) Requirements" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1203929171/REFARCH-491+-+Decide+on+Amazon+Managed+Workflows+for+Apache+Airflow+%28MWAA%29+Requirements sidebar_position: 100 refarch_id: REFARCH-491 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # Decide on Amazon Managed Workflows for Apache Airflow (MWAA) Requirements diff --git a/docs/layers/data/design-decisions/decide-on-amazon-opensearch-service-elasticsearch-requirements.md b/docs/layers/data/design-decisions/decide-on-amazon-opensearch-service-elasticsearch-requirements.mdx similarity index 96% rename from docs/layers/data/design-decisions/decide-on-amazon-opensearch-service-elasticsearch-requirements.md rename to docs/layers/data/design-decisions/decide-on-amazon-opensearch-service-elasticsearch-requirements.mdx index af24161be..1a4d0a72b 100644 --- a/docs/layers/data/design-decisions/decide-on-amazon-opensearch-service-elasticsearch-requirements.md +++ b/docs/layers/data/design-decisions/decide-on-amazon-opensearch-service-elasticsearch-requirements.mdx @@ -1,9 +1,10 @@ --- title: "Decide on Amazon OpenSearch Service (Elasticsearch) Requirements" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1175355560/REFARCH-362+-+Decide+on+Amazon+OpenSearch+Service+%28Elasticsearch%29++Requirements sidebar_position: 100 refarch_id: REFARCH-362 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # Decide on Amazon OpenSearch Service (Elasticsearch) Requirements diff --git a/docs/layers/data/design-decisions/decide-on-automated-backup-requirements.md b/docs/layers/data/design-decisions/decide-on-automated-backup-requirements.mdx similarity index 80% rename from docs/layers/data/design-decisions/decide-on-automated-backup-requirements.md rename to docs/layers/data/design-decisions/decide-on-automated-backup-requirements.mdx index 93e2297ed..eaf8213fb 100644 --- a/docs/layers/data/design-decisions/decide-on-automated-backup-requirements.md +++ b/docs/layers/data/design-decisions/decide-on-automated-backup-requirements.mdx @@ -1,9 +1,10 @@ --- title: "Decide on Automated Backup Requirements" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1222541490/REFARCH-493+-+Decide+on+Automated+Backup+Requirements sidebar_position: 100 refarch_id: REFARCH-493 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # Decide on Automated Backup Requirements diff --git a/docs/layers/data/design-decisions/decide-on-aws-backup-requirements.md b/docs/layers/data/design-decisions/decide-on-aws-backup-requirements.mdx similarity index 85% rename from docs/layers/data/design-decisions/decide-on-aws-backup-requirements.md rename to docs/layers/data/design-decisions/decide-on-aws-backup-requirements.mdx index 228055aa9..52813ad18 100644 --- a/docs/layers/data/design-decisions/decide-on-aws-backup-requirements.md +++ b/docs/layers/data/design-decisions/decide-on-aws-backup-requirements.mdx @@ -1,9 +1,10 @@ --- title: "Decide on AWS Backup Requirements" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1203830920/REFARCH-489+-+Decide+on+AWS+Backup+Requirements sidebar_position: 100 refarch_id: REFARCH-489 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # Decide on AWS Backup Requirements diff --git a/docs/layers/data/design-decisions/decide-on-aws-emr-requirements.md b/docs/layers/data/design-decisions/decide-on-aws-emr-requirements.mdx similarity index 86% rename from docs/layers/data/design-decisions/decide-on-aws-emr-requirements.md rename to docs/layers/data/design-decisions/decide-on-aws-emr-requirements.mdx index 1b7a57975..d14fec3ac 100644 --- a/docs/layers/data/design-decisions/decide-on-aws-emr-requirements.md +++ b/docs/layers/data/design-decisions/decide-on-aws-emr-requirements.mdx @@ -1,9 +1,10 @@ --- title: "Decide on AWS EMR Requirements" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1204125709/REFARCH-490+-+Decide+on+AWS+EMR+Requirements sidebar_position: 100 refarch_id: REFARCH-490 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # Decide on AWS EMR Requirements diff --git a/docs/layers/data/design-decisions/decide-on-aws-managed-rabbitmq-requirements.md b/docs/layers/data/design-decisions/decide-on-aws-managed-rabbitmq-requirements.mdx similarity index 79% rename from docs/layers/data/design-decisions/decide-on-aws-managed-rabbitmq-requirements.md rename to docs/layers/data/design-decisions/decide-on-aws-managed-rabbitmq-requirements.mdx index 8f20e336e..630806822 100644 --- a/docs/layers/data/design-decisions/decide-on-aws-managed-rabbitmq-requirements.md +++ b/docs/layers/data/design-decisions/decide-on-aws-managed-rabbitmq-requirements.mdx @@ -1,9 +1,10 @@ --- title: "Decide on AWS Managed RabbitMQ Requirements" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1204256781/REFARCH-488+-+Decide+on+AWS+Managed+RabbitMQ+Requirements sidebar_position: 100 refarch_id: REFARCH-488 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # Decide on AWS Managed RabbitMQ Requirements diff --git a/docs/layers/data/design-decisions/decide-on-database-schema-migration-strategy.md b/docs/layers/data/design-decisions/decide-on-database-schema-migration-strategy.mdx similarity index 95% rename from docs/layers/data/design-decisions/decide-on-database-schema-migration-strategy.md rename to docs/layers/data/design-decisions/decide-on-database-schema-migration-strategy.mdx index 279d939b2..92361ef4c 100644 --- a/docs/layers/data/design-decisions/decide-on-database-schema-migration-strategy.md +++ b/docs/layers/data/design-decisions/decide-on-database-schema-migration-strategy.mdx @@ -1,9 +1,10 @@ --- title: "Decide on Database Schema Migration Strategy" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1171783759/REFARCH-422+-+Decide+on+Database+Schema+Migration+Strategy sidebar_position: 100 refarch_id: REFARCH-422 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # Decide on Database Schema Migration Strategy diff --git a/docs/layers/data/design-decisions/decide-on-documentdb-requirements.md b/docs/layers/data/design-decisions/decide-on-documentdb-requirements.mdx similarity index 96% rename from docs/layers/data/design-decisions/decide-on-documentdb-requirements.md rename to docs/layers/data/design-decisions/decide-on-documentdb-requirements.mdx index b735974d5..049a169a1 100644 --- a/docs/layers/data/design-decisions/decide-on-documentdb-requirements.md +++ b/docs/layers/data/design-decisions/decide-on-documentdb-requirements.mdx @@ -1,9 +1,10 @@ --- title: "Decide on DocumentDB Requirements" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1183973819/REFARCH-479+-+Decide+on+DocumentDB+Requirements sidebar_position: 100 refarch_id: REFARCH-479 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # Decide on DocumentDB Requirements diff --git a/docs/layers/data/design-decisions/decide-on-dynamodb-requirements.md b/docs/layers/data/design-decisions/decide-on-dynamodb-requirements.mdx similarity index 96% rename from docs/layers/data/design-decisions/decide-on-dynamodb-requirements.md rename to docs/layers/data/design-decisions/decide-on-dynamodb-requirements.mdx index 1e3a8849c..a4b641f75 100644 --- a/docs/layers/data/design-decisions/decide-on-dynamodb-requirements.md +++ b/docs/layers/data/design-decisions/decide-on-dynamodb-requirements.mdx @@ -1,9 +1,10 @@ --- title: "Decide on DynamoDB Requirements" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1184301425/REFARCH-478+-+Decide+on+DynamoDB+Requirements sidebar_position: 100 refarch_id: REFARCH-478 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # Decide on DynamoDB Requirements diff --git a/docs/layers/data/design-decisions/decide-on-elasticache-redis-requirements.md b/docs/layers/data/design-decisions/decide-on-elasticache-redis-requirements.mdx similarity index 95% rename from docs/layers/data/design-decisions/decide-on-elasticache-redis-requirements.md rename to docs/layers/data/design-decisions/decide-on-elasticache-redis-requirements.mdx index 58e85f155..138322c82 100644 --- a/docs/layers/data/design-decisions/decide-on-elasticache-redis-requirements.md +++ b/docs/layers/data/design-decisions/decide-on-elasticache-redis-requirements.mdx @@ -1,9 +1,10 @@ --- title: "Decide on Elasticache Redis Requirements" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1175650441/REFARCH-365+-+Decide+on+Elasticache+Redis+Requirements sidebar_position: 100 refarch_id: REFARCH-365 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # Decide on Elasticache Redis Requirements diff --git a/docs/layers/data/design-decisions/decide-on-msk-requirements.md b/docs/layers/data/design-decisions/decide-on-msk-requirements.mdx similarity index 96% rename from docs/layers/data/design-decisions/decide-on-msk-requirements.md rename to docs/layers/data/design-decisions/decide-on-msk-requirements.mdx index fb5b7db8e..ca38d2cc2 100644 --- a/docs/layers/data/design-decisions/decide-on-msk-requirements.md +++ b/docs/layers/data/design-decisions/decide-on-msk-requirements.mdx @@ -1,9 +1,10 @@ --- title: "Decide on MSK Requirements" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1201537168/REFARCH-486+-+Decide+on+MSK+Requirements sidebar_position: 100 refarch_id: REFARCH-486 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # Decide on MSK Requirements diff --git a/docs/layers/data/design-decisions/decide-on-rds-aurora-db-cluster-requirements.mdx b/docs/layers/data/design-decisions/decide-on-rds-aurora-db-cluster-requirements.mdx index 8e1f46720..76060d0e8 100644 --- a/docs/layers/data/design-decisions/decide-on-rds-aurora-db-cluster-requirements.mdx +++ b/docs/layers/data/design-decisions/decide-on-rds-aurora-db-cluster-requirements.mdx @@ -1,9 +1,10 @@ --- title: "Decide on RDS Aurora DB Cluster Requirements" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1184661505/REFARCH-476+-+Decide+on+RDS+Aurora+DB+Cluster+Requirements sidebar_position: 100 refarch_id: REFARCH-476 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # Decide on RDS Aurora DB Cluster Requirements diff --git a/docs/layers/data/design-decisions/decide-on-rds-technology-and-architecture.md b/docs/layers/data/design-decisions/decide-on-rds-technology-and-architecture.mdx similarity index 98% rename from docs/layers/data/design-decisions/decide-on-rds-technology-and-architecture.md rename to docs/layers/data/design-decisions/decide-on-rds-technology-and-architecture.mdx index 5ba773286..f0dfe92cb 100644 --- a/docs/layers/data/design-decisions/decide-on-rds-technology-and-architecture.md +++ b/docs/layers/data/design-decisions/decide-on-rds-technology-and-architecture.mdx @@ -1,9 +1,10 @@ --- title: "Decide on RDS Technology and Architecture" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1175388285/REFARCH-211+-+Decide+on+RDS+Technology+and+Architecture sidebar_position: 100 refarch_id: REFARCH-211 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # Decide on RDS Technology and Architecture diff --git a/docs/layers/data/design-decisions/decide-on-s3-bucket-requirements.md b/docs/layers/data/design-decisions/decide-on-s3-bucket-requirements.mdx similarity index 93% rename from docs/layers/data/design-decisions/decide-on-s3-bucket-requirements.md rename to docs/layers/data/design-decisions/decide-on-s3-bucket-requirements.mdx index c79cbb194..c10a3b306 100644 --- a/docs/layers/data/design-decisions/decide-on-s3-bucket-requirements.md +++ b/docs/layers/data/design-decisions/decide-on-s3-bucket-requirements.mdx @@ -1,9 +1,10 @@ --- title: "Decide on S3 Bucket Requirements" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1175617703/REFARCH-364+-+Decide+on+S3+Bucket+Requirements sidebar_position: 100 refarch_id: REFARCH-364 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # Decide on S3 Bucket Requirements diff --git a/docs/layers/data/design-decisions/decide-on-sftp-requirements.md b/docs/layers/data/design-decisions/decide-on-sftp-requirements.mdx similarity index 89% rename from docs/layers/data/design-decisions/decide-on-sftp-requirements.md rename to docs/layers/data/design-decisions/decide-on-sftp-requirements.mdx index a0d09e894..51584ff53 100644 --- a/docs/layers/data/design-decisions/decide-on-sftp-requirements.md +++ b/docs/layers/data/design-decisions/decide-on-sftp-requirements.mdx @@ -1,9 +1,10 @@ --- title: "Decide on SFTP Requirements" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1201438831/REFARCH-485+-+Decide+on+SFTP+Requirements sidebar_position: 100 refarch_id: REFARCH-485 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # Decide on SFTP Requirements diff --git a/docs/layers/data/design-decisions/decide-on-the-backup-aws-region-for-aurora-global-cluster.md b/docs/layers/data/design-decisions/decide-on-the-backup-aws-region-for-aurora-global-cluster.mdx similarity index 88% rename from docs/layers/data/design-decisions/decide-on-the-backup-aws-region-for-aurora-global-cluster.md rename to docs/layers/data/design-decisions/decide-on-the-backup-aws-region-for-aurora-global-cluster.mdx index 6212f53f9..926784e78 100644 --- a/docs/layers/data/design-decisions/decide-on-the-backup-aws-region-for-aurora-global-cluster.md +++ b/docs/layers/data/design-decisions/decide-on-the-backup-aws-region-for-aurora-global-cluster.mdx @@ -1,9 +1,10 @@ --- title: "Decide on the backup AWS region for Aurora Global Cluster" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1175978124/REFARCH-242+-+Decide+on+the+backup+AWS+region+for+Aurora+Global+Cluster sidebar_position: 100 refarch_id: REFARCH-242 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # Decide on the backup AWS region for Aurora Global Cluster diff --git a/docs/layers/data/design-decisions/decide-whether-to-use-rds-iam-authentication.md b/docs/layers/data/design-decisions/decide-whether-to-use-rds-iam-authentication.mdx similarity index 93% rename from docs/layers/data/design-decisions/decide-whether-to-use-rds-iam-authentication.md rename to docs/layers/data/design-decisions/decide-whether-to-use-rds-iam-authentication.mdx index 2db17b9c5..43c64cc5f 100644 --- a/docs/layers/data/design-decisions/decide-whether-to-use-rds-iam-authentication.md +++ b/docs/layers/data/design-decisions/decide-whether-to-use-rds-iam-authentication.mdx @@ -1,9 +1,10 @@ --- title: "Decide Whether to Use RDS IAM Authentication" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1176110022/REFARCH-210+-+Decide+Whether+to+Use+RDS+IAM+Authentication sidebar_position: 100 refarch_id: REFARCH-210 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # Decide Whether to Use RDS IAM Authentication diff --git a/docs/layers/data/design-decisions/todo-decide-on-rds-aurora-serverless-requirements.md b/docs/layers/data/design-decisions/todo-decide-on-rds-aurora-serverless-requirements.mdx similarity index 61% rename from docs/layers/data/design-decisions/todo-decide-on-rds-aurora-serverless-requirements.md rename to docs/layers/data/design-decisions/todo-decide-on-rds-aurora-serverless-requirements.mdx index 36ee01b4d..e919e6cec 100644 --- a/docs/layers/data/design-decisions/todo-decide-on-rds-aurora-serverless-requirements.md +++ b/docs/layers/data/design-decisions/todo-decide-on-rds-aurora-serverless-requirements.mdx @@ -1,9 +1,11 @@ --- title: "(TODO) Decide on RDS Aurora Serverless Requirements" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1178009637/REFARCH-472+-+%28TODO%29+Decide+on+RDS+Aurora+Serverless+Requirements sidebar_position: 100 refarch_id: REFARCH-472 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; + # (TODO) Decide on RDS Aurora Serverless Requirements diff --git a/docs/layers/data/design-decisions/todo-decide-on-rds-instance-requirements.md b/docs/layers/data/design-decisions/todo-decide-on-rds-instance-requirements.mdx similarity index 88% rename from docs/layers/data/design-decisions/todo-decide-on-rds-instance-requirements.md rename to docs/layers/data/design-decisions/todo-decide-on-rds-instance-requirements.mdx index 50b6459b7..19ce10a81 100644 --- a/docs/layers/data/design-decisions/todo-decide-on-rds-instance-requirements.md +++ b/docs/layers/data/design-decisions/todo-decide-on-rds-instance-requirements.mdx @@ -1,9 +1,10 @@ --- title: "(TODO) Decide on RDS Instance Requirements" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1184661520/REFARCH-477+-+%28TODO%29+Decide+on+RDS+Instance+Requirements sidebar_position: 100 refarch_id: REFARCH-477 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # (TODO) Decide on RDS Instance Requirements diff --git a/docs/layers/data/tutorials/how-to-enable-cross-region-backups-in-aws-backup.md b/docs/layers/data/tutorials/how-to-enable-cross-region-backups-in-aws-backup.mdx similarity index 93% rename from docs/layers/data/tutorials/how-to-enable-cross-region-backups-in-aws-backup.md rename to docs/layers/data/tutorials/how-to-enable-cross-region-backups-in-aws-backup.mdx index 53ab12fc9..4945a5bd4 100644 --- a/docs/layers/data/tutorials/how-to-enable-cross-region-backups-in-aws-backup.md +++ b/docs/layers/data/tutorials/how-to-enable-cross-region-backups-in-aws-backup.mdx @@ -1,8 +1,10 @@ --- title: "Enable Cross-Region Backups in AWS-Backup" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1190952961/How+to+Enable+Cross-Region+Backups+in+AWS-Backup sidebar_position: 100 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; + # How to Enable Cross-Region Backups in AWS-Backup diff --git a/docs/layers/data/tutorials/how-to-migrate-rds-snapshots.md b/docs/layers/data/tutorials/how-to-migrate-rds-snapshots.mdx similarity index 99% rename from docs/layers/data/tutorials/how-to-migrate-rds-snapshots.md rename to docs/layers/data/tutorials/how-to-migrate-rds-snapshots.mdx index d278c6643..05dc443c1 100644 --- a/docs/layers/data/tutorials/how-to-migrate-rds-snapshots.md +++ b/docs/layers/data/tutorials/how-to-migrate-rds-snapshots.mdx @@ -2,6 +2,8 @@ title: "Migrate RDS Snapshots" sidebar_position: 100 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # How to Migrate RDS Snapshots Across AWS Organizations diff --git a/docs/layers/ecs/deploy-clusters.mdx b/docs/layers/ecs/deploy-clusters.mdx index 34a0b814c..516f79032 100644 --- a/docs/layers/ecs/deploy-clusters.mdx +++ b/docs/layers/ecs/deploy-clusters.mdx @@ -1,9 +1,10 @@ --- -title: "Deploy Clusters" +title: "Deploying the ECS Platform" +sidebar_label: "Deploy Clusters" sidebar_position: 10 --- - -# Deploying the ECS Platform +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Quick Start @@ -16,9 +17,7 @@ sidebar_position: 10 ## Requirements -In order to deploy ECS, Networking must be fully deployed and functional. In particular, the user deploying the cluster -must have a working VPN connection to the targeted account. See -[the network documentation](https://docs.cloudposse.com/reference-architecture/setup/network/) for details. +In order to deploy ECS, Networking must be fully deployed and functional. In particular, the user deploying the cluster must have a working VPN connection to the targeted account. See [the network documentation](https://docs.cloudposse.com/reference-architecture/setup/network/) for details. All deployment steps below assume that the environment has been successfully set up with the following steps. @@ -45,21 +44,15 @@ atmos vendor pull --component ecs-service ### Deploy -ECS provisioning includes deploying certificate requirements, the default ECS cluster, and Echo Server. Echo Server is a -basic service used to validate a successful cluster deployed and is an example of an ECS service. Find ECS Service -definitions under `catalog/stacks/ecs-services`. +ECS provisioning includes deploying certificate requirements, the default ECS cluster, and Echo Server. Echo Server is a basic service used to validate a successful cluster deployed and is an example of an ECS service. Find ECS Service definitions under `catalog/stacks/ecs-services`. -To provision each cluster, these components need to be deployed in order. The included Atmos Workflows will carry out -this deployment in the proper order, but any of these step can be run outside of a workflow if desired. +To provision each cluster, these components need to be deployed in order. The included Atmos Workflows will carry out this deployment in the proper order, but any of these step can be run outside of a workflow if desired. See the ecs workflow (`stacks/workflows/ecs.yaml`) for each individual deployment step. #### Deploy ACM Certificates -First deploy all required ACM certificates for each ECS cluster. These certificates validate the given service domain. -You can deploy these certificates before associating the given Route 53 Hosted Zone with the purchased domain in your -chosen Domain Registrar, but the certificate will not be ISSUED until the registered domain and Hosted Zone are -connected. +First deploy all required ACM certificates for each ECS cluster. These certificates validate the given service domain. You can deploy these certificates before associating the given Route 53 Hosted Zone with the purchased domain in your chosen Domain Registrar, but the certificate will not be ISSUED until the registered domain and Hosted Zone are connected. Run the following Atmos Workflow to deploy every required ACM certificate for ECS. diff --git a/docs/layers/ecs/design-decisions/decide-on-ecs-load-balancer-requirements.md b/docs/layers/ecs/design-decisions/decide-on-ecs-load-balancer-requirements.mdx similarity index 77% rename from docs/layers/ecs/design-decisions/decide-on-ecs-load-balancer-requirements.md rename to docs/layers/ecs/design-decisions/decide-on-ecs-load-balancer-requirements.mdx index 2e6151903..7e3c01bec 100644 --- a/docs/layers/ecs/design-decisions/decide-on-ecs-load-balancer-requirements.md +++ b/docs/layers/ecs/design-decisions/decide-on-ecs-load-balancer-requirements.mdx @@ -2,6 +2,8 @@ title: "Decide on ECS load balancer requirements" refarch_id: REFARCH-414 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # Decide on ECS load balancer requirements diff --git a/docs/layers/ecs/design-decisions/decide-on-the-application-service-log-destination-for-ecs.md b/docs/layers/ecs/design-decisions/decide-on-the-application-service-log-destination-for-ecs.mdx similarity index 96% rename from docs/layers/ecs/design-decisions/decide-on-the-application-service-log-destination-for-ecs.md rename to docs/layers/ecs/design-decisions/decide-on-the-application-service-log-destination-for-ecs.mdx index 2668aebcc..b0d9d147b 100644 --- a/docs/layers/ecs/design-decisions/decide-on-the-application-service-log-destination-for-ecs.md +++ b/docs/layers/ecs/design-decisions/decide-on-the-application-service-log-destination-for-ecs.mdx @@ -2,6 +2,8 @@ title: "Decide on the Application Service Log Destination for ECS" refarch_id: REFARCH-484 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # Decide on the Application Service Log Destination for ECS diff --git a/docs/layers/ecs/ecs.mdx b/docs/layers/ecs/ecs.mdx index 36e5a9b40..4755f8cea 100644 --- a/docs/layers/ecs/ecs.mdx +++ b/docs/layers/ecs/ecs.mdx @@ -1,28 +1,26 @@ --- -title: "ECS" +title: "ECS Foundational Platform" +sidebar_label: "ECS" sidebar_class_name: hidden --- +import ReactPlayer from "react-player"; +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; -# ECS Foundational Platform - -Elastic Container Service (ECS) is a fully-managed container orchestration service provided by Amazon Web Services (AWS) -that simplifies the process of deploying, managing, and scaling containerized applications. ECS makes it easy to run and -manage Docker containers on AWS infrastructure, providing a secure and scalable platform for your applications. -import ReactPlayer from "react-player"; +Elastic Container Service (ECS) is a fully-managed container orchestration service provided by Amazon Web Services (AWS) that simplifies the process of deploying, managing, and scaling containerized applications. ECS makes it easy to run and manage Docker containers on AWS infrastructure, providing a secure and scalable platform for your applications. - +
+ +
AI generated voice
+
## The Problem -The emergence of Docker necessitated the development of container management solutions, with Kubernetes being one of the -most widely adopted options. However, Kubernetes is often considered overly complex for smaller scale operations, akin -to using a nuclear reactor to charge a phone. In such scenarios, Elastic Container Service (ECS) is a more practical -choice for deploying applications with speed and efficiency. +The emergence of Docker necessitated the development of container management solutions, with Kubernetes being one of the most widely adopted options. However, Kubernetes is often considered overly complex for smaller scale operations, akin to using a nuclear reactor to charge a phone. In such scenarios, Elastic Container Service (ECS) is a more practical choice for deploying applications with speed and efficiency. With ECS there is no need to upgrade the underlying platform. Unlike EKS which requires consistent upgrades to stay -current, ECS is a managed service that is always up to date. This means that you can focus on your application and not -the underlying platform. +current, ECS is a managed service that is always up to date. This means that you can focus on your application and not the underlying platform. ## Our Solution @@ -34,8 +32,7 @@ The [`ecs` component] is used to deploy an ECS cluster and an associated load ba #### Application Load Balancer (ALB) -Through stack configuration you can determine your domains, subdomains, and the number of instances to deploy. The -component also supports the deployment of a bastion host, which can be used to access containers on the ECS Cluster. +Through stack configuration you can determine your domains, subdomains, and the number of instances to deploy. The component also supports the deployment of a bastion host, which can be used to access containers on the ECS Cluster. ```yaml alb_configuration: @@ -50,9 +47,7 @@ alb_configuration: #### Autoscaling -The cluster component has the ability to scale with a variety of options. Fargate provides a serverless way of scaling. -Spot instances provide a cheaper way to run instances than on demand ec2. you can mix these options to provide a cost -effective and scalable solution. +The cluster component has the ability to scale with a variety of options. Fargate provides a serverless way of scaling. Spot instances provide a cheaper way to run instances than on demand ec2. you can mix these options to provide a cost effective and scalable solution. ```yaml name: ecs @@ -68,8 +63,7 @@ capacity_providers_ec2: The [`ecs-service` component] is used to deploy an ECS service. This includes the task and the service definition. -By default we also support datadog logging and metrics. This can be disabled by setting `datadog_agent_sidecar_enabled` -to false. +By default we also support datadog logging and metrics. This can be disabled by setting `datadog_agent_sidecar_enabled` to false. ```yaml datadog_agent_sidecar_enabled: false @@ -79,8 +73,7 @@ datadog_agent_sidecar_enabled: false ### How do I add a new service to an existing ECS cluster? -Add a new instance of the `ecs-service` component to your stack configuration. The component will automatically detect -the ECS cluster and add the service to it. +Add a new instance of the `ecs-service` component to your stack configuration. The component will automatically detect the ECS cluster and add the service to it. ### How can I add AWS Policies to my ECS Tasks? @@ -93,8 +86,7 @@ task_policy_arns: ### How can I inject secrets into my ECS Service? -Use the `map_secrets` variable which maps a environment variable key to an SSM param store key. This will inject the -value of the SSM param store key into the environment variable. +Use the `map_secrets` variable which maps a environment variable key to an SSM param store key. This will inject the value of the SSM param store key into the environment variable. ```yaml map_secrets: @@ -103,7 +95,6 @@ map_secrets: ### How can we create Self Hosted Runners for GitHub with ECS? -If we are not deploying EKS for our platform, it doesnt make much sense to configure EKS solely for self-hosted runners. -Instead we deploy an EC2 Autoscaling Group in AWS and connect those instances to GitHub. +If we are not deploying EKS for our platform, it doesnt make much sense to configure EKS solely for self-hosted runners. Instead we deploy an EC2 Autoscaling Group in AWS and connect those instances to GitHub. For more on GitHub Runners in an ASG, see [`github-runners`](/components/library/aws/github-runners/). diff --git a/docs/layers/ecs/provision-services.mdx b/docs/layers/ecs/provision-services.mdx index ebe01f69c..5ba760ad0 100644 --- a/docs/layers/ecs/provision-services.mdx +++ b/docs/layers/ecs/provision-services.mdx @@ -1,9 +1,11 @@ --- -title: "Provision Services" +title: "Provisioing Services on the ECS Platform" +sidebar_label: "Provision Services" sidebar_position: 20 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; -# Provisioing Services on the ECS Platform ## Quick Start @@ -13,9 +15,7 @@ sidebar_position: 20 ### Deploy Echo Server -Once the cluster is up and running, continue with the first ECS service deployment. We deploy Echo Server as an example -and to validate a given cluster. This deploys two ECS services: one private and one public. The private deployment -should only be accessible by VPN. +Once the cluster is up and running, continue with the first ECS service deployment. We deploy Echo Server as an example and to validate a given cluster. This deploys two ECS services: one private and one public. The private deployment should only be accessible by VPN. Run the following Atmos Workflow to deploy `ecs/platform/service/echo-server` and `ecs/platform/service/echo-server-private` to every cluster. @@ -24,16 +24,14 @@ Run the following Atmos Workflow to deploy `ecs/platform/service/echo-server` an atmos workflow deploy/echo-server -f ecs ``` -Validate each cluster deployment with Echo Server and the targeted service domain. The following URL should return a -success message for each stage's public deployment: +Validate each cluster deployment with Echo Server and the targeted service domain. The following URL should return a success message for each stage's public deployment: 1. `plat-sandbox`: https://echo-server.public-platform.use1.sandbox.plat.acme-svc.com/ 1. `plat-dev`: https://echo-server.public-platform.use1.dev.plat.acme-svc.com/ 1. `plat-staging`: https://echo-server.public-platform.use1.staging.plat.acme-svc.com/ 1. `plat-prod`: https://echo-server.public-platform.use1.prod.plat.acme-svc.com/ -Each of the following should time out if not connected to the VPN. Verify these are not publicly accessible. Then -connect to the VPN to successfully load the endpoint. +Each of the following should time out if not connected to the VPN. Verify these are not publicly accessible. Then connect to the VPN to successfully load the endpoint. 1. `plat-sandbox`: https://echo-server.private-platform.use1.sandbox.plat.acme-svc.com/ 1. `plat-dev`: https://echo-server.private-platform.use1.dev.plat.acme-svc.com/ diff --git a/docs/layers/ecs/tutorials/how-to-setup-vanity-domains-on-alb-ecs.md b/docs/layers/ecs/tutorials/how-to-setup-vanity-domains-on-alb-ecs.mdx similarity index 97% rename from docs/layers/ecs/tutorials/how-to-setup-vanity-domains-on-alb-ecs.md rename to docs/layers/ecs/tutorials/how-to-setup-vanity-domains-on-alb-ecs.mdx index 18eb9f33c..a8fb494fa 100644 --- a/docs/layers/ecs/tutorials/how-to-setup-vanity-domains-on-alb-ecs.md +++ b/docs/layers/ecs/tutorials/how-to-setup-vanity-domains-on-alb-ecs.mdx @@ -6,11 +6,10 @@ tags: - alb - ecs --- - -```mdx-code-block +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -``` # How to Setup ECS Vanity Domains on an existing ALB used for Service Discovery Domains diff --git a/docs/layers/eks/deploy-clusters.mdx b/docs/layers/eks/deploy-clusters.mdx index 76b817ddc..bca3e932e 100644 --- a/docs/layers/eks/deploy-clusters.mdx +++ b/docs/layers/eks/deploy-clusters.mdx @@ -1,9 +1,10 @@ --- -title: "Deploy Clusters" +title: "Deploying the EKS Platform" +sidebar_label: "Deploy Clusters" sidebar_position: 20 --- - -# Deploying the EKS Platform +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Quick Start diff --git a/docs/layers/eks/design-decisions/decide-on-eks-node-pool-architecture.md b/docs/layers/eks/design-decisions/decide-on-eks-node-pool-architecture.mdx similarity index 97% rename from docs/layers/eks/design-decisions/decide-on-eks-node-pool-architecture.md rename to docs/layers/eks/design-decisions/decide-on-eks-node-pool-architecture.mdx index 968501bbf..3c4c28fc7 100644 --- a/docs/layers/eks/design-decisions/decide-on-eks-node-pool-architecture.md +++ b/docs/layers/eks/design-decisions/decide-on-eks-node-pool-architecture.mdx @@ -2,6 +2,8 @@ title: "Decide on EKS Node Pool Architecture" refarch_id: REFARCH-236 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # Decide on EKS Node Pool Architecture diff --git a/docs/layers/eks/design-decisions/decide-on-email-address-for-cert-manager-support-emails.md b/docs/layers/eks/design-decisions/decide-on-email-address-for-cert-manager-support-emails.mdx similarity index 84% rename from docs/layers/eks/design-decisions/decide-on-email-address-for-cert-manager-support-emails.md rename to docs/layers/eks/design-decisions/decide-on-email-address-for-cert-manager-support-emails.mdx index 5c93e22e7..09f008d27 100644 --- a/docs/layers/eks/design-decisions/decide-on-email-address-for-cert-manager-support-emails.md +++ b/docs/layers/eks/design-decisions/decide-on-email-address-for-cert-manager-support-emails.mdx @@ -2,6 +2,8 @@ title: "Decide on email address for cert-manager support emails" refarch_id: REFARCH-202 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # Decide on email address for cert-manager support emails diff --git a/docs/layers/eks/design-decisions/decide-on-helm-chart-repository-strategy.md b/docs/layers/eks/design-decisions/decide-on-helm-chart-repository-strategy.mdx similarity index 96% rename from docs/layers/eks/design-decisions/decide-on-helm-chart-repository-strategy.md rename to docs/layers/eks/design-decisions/decide-on-helm-chart-repository-strategy.mdx index 9d2a2c242..14e8206de 100644 --- a/docs/layers/eks/design-decisions/decide-on-helm-chart-repository-strategy.md +++ b/docs/layers/eks/design-decisions/decide-on-helm-chart-repository-strategy.mdx @@ -2,6 +2,8 @@ title: "Decide on Helm Chart Repository Strategy" refarch_id: REFARCH-207 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # Decide on Helm Chart Repository Strategy diff --git a/docs/layers/eks/design-decisions/decide-on-host-os-flavor-for-eks.md b/docs/layers/eks/design-decisions/decide-on-host-os-flavor-for-eks.mdx similarity index 95% rename from docs/layers/eks/design-decisions/decide-on-host-os-flavor-for-eks.md rename to docs/layers/eks/design-decisions/decide-on-host-os-flavor-for-eks.mdx index 9e2b9df89..d4a42103e 100644 --- a/docs/layers/eks/design-decisions/decide-on-host-os-flavor-for-eks.md +++ b/docs/layers/eks/design-decisions/decide-on-host-os-flavor-for-eks.mdx @@ -2,6 +2,8 @@ title: "Decide on Host OS Flavor for EKS" refarch_id: REFARCH-49 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # Decide on Host OS Flavor for EKS diff --git a/docs/layers/eks/design-decisions/decide-on-kubernetes-ingress-controller-s.md b/docs/layers/eks/design-decisions/decide-on-kubernetes-ingress-controller-s.mdx similarity index 90% rename from docs/layers/eks/design-decisions/decide-on-kubernetes-ingress-controller-s.md rename to docs/layers/eks/design-decisions/decide-on-kubernetes-ingress-controller-s.mdx index 9522f9bff..9a75204ad 100644 --- a/docs/layers/eks/design-decisions/decide-on-kubernetes-ingress-controller-s.md +++ b/docs/layers/eks/design-decisions/decide-on-kubernetes-ingress-controller-s.mdx @@ -2,6 +2,8 @@ title: "Decide on Kubernetes Ingress Controller(s)" refarch_id: REFARCH-300 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # Decide on Kubernetes Ingress Controller(s) diff --git a/docs/layers/eks/eks.mdx b/docs/layers/eks/eks.mdx index 94f5ea350..b7e84505f 100644 --- a/docs/layers/eks/eks.mdx +++ b/docs/layers/eks/eks.mdx @@ -1,9 +1,10 @@ --- -title: "EKS" +title: "EKS Foundational Platform" +sidebar_label: "EKS" sidebar_class_name: hidden --- - -# EKS Foundational Platform +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; Amazon EKS is a managed Kubernetes service to run Kubernetes in the AWS cloud and on-premises data centers. In the cloud, Amazon EKS automatically manages the availability and scalability of the Kubernetes control plane nodes diff --git a/docs/layers/eks/foundational-platform.mdx b/docs/layers/eks/foundational-platform.mdx index 4083e52dd..8d8762775 100644 --- a/docs/layers/eks/foundational-platform.mdx +++ b/docs/layers/eks/foundational-platform.mdx @@ -1,9 +1,10 @@ --- -title: "Foundational Platform" +title: "EKS as a Foundational Platform" +sidebar_label: "Foundational Platform" sidebar_position: 10 --- - -# EKS as a Foundational Platform +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; +Before we start deploying any infrastructure, we must first make key design decisions regarding the foundation of our architecture. + + +### Review Design Decisions + +Review each of the following design decisions and record your decisions now. We will need the results of these decisions +going forward. + + + +:::tip + +When working with Cloud Posse as part of our [Jumpstart](/jumpstart), we will review each of these decisions on the +[Cloud Posse Kick Off](/learn/jumpstart/kick-off/). + +::: diff --git a/docs/layers/foundation/foundation.mdx b/docs/layers/foundation/foundation.mdx index 64c4e2834..52d48337f 100644 --- a/docs/layers/foundation/foundation.mdx +++ b/docs/layers/foundation/foundation.mdx @@ -1,8 +1,10 @@ --- +title: Getting Started sidebar_class_name: hidden --- - -# Getting Started +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; +import ReactPlayer from "react-player"; ## Problem @@ -29,9 +31,10 @@ Reference Architecture. ## Introduction to Toolset -import ReactPlayer from "react-player"; - - +
+ +
AI generated voice
+
## Checklist diff --git a/docs/layers/foundation/foundational-decisions.mdx b/docs/layers/foundation/foundational-decisions.mdx deleted file mode 100644 index b74633fd6..000000000 --- a/docs/layers/foundation/foundational-decisions.mdx +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Foundational Decisions -sidebar_position: 00 ---- - -# Foundational Design Decisions - -Before we start deploying any infrastructure, we must first make a number of decisions for the foundation of our -architecture. - -:::tip - -When working with Cloud Posse as part of our [Jumpstart](/jumpstart), we will review each of these decisions on the -[Cloud Posse Kick Off](/learn/jumpstart/kick-off/). - -::: - -### Review [Design Decisions](/layers/foundation/design-decisions) - -Review each of the following design decisions and record your decisions now. We will need the results of these decisions -going forward. - -- [ ] [Decide on Namespace Abbreviation](/layers/foundation/design-decisions/decide-on-namespace-abbreviation/) -- [ ] [Decide on Infrastructure Repository Name](/layers/foundation/design-decisions/decide-on-infrastructure-repository-name/) -- [ ] [Decide on Email Address Format for AWS Accounts](/layers/accounts/design-decisions/decide-on-email-address-format-for-aws-accounts/) -- [ ] [Decide on IdP](/layers/identity/design-decisions/decide-on-idp/) -- [ ] [Decide on IdP Integration Method](/layers/identity/design-decisions/decide-on-idp-integration) -- [ ] [Decide on Primary AWS Region and Secondary AWS Region](/layers/network-and-dns/design-decisions/decide-on-primary-aws-region/) -- [ ] [Decide on CIDR Allocation Strategy](/layers/network-and-dns/design-decisions/decide-on-cidr-allocation/) -- [ ] [Decide on Service Discovery Domain](/layers/network-and-dns/design-decisions/decide-on-service-discovery-domain/) -- [ ] [Decide on Vanity Domain](/layers/network-and-dns/design-decisions/decide-on-vanity-branded-domain/) -- [ ] [Decide on Release Engineering Strategy](/layers/application-cicd/design-decisions/decide-on-release-engineering-strategy/) diff --git a/docs/layers/github-actions/eks-github-actions-controller.mdx b/docs/layers/github-actions/eks-github-actions-controller.mdx index aece1356d..cd847e8e5 100644 --- a/docs/layers/github-actions/eks-github-actions-controller.mdx +++ b/docs/layers/github-actions/eks-github-actions-controller.mdx @@ -1,4 +1,9 @@ -# [EKS] GitHub Action Runner Controller +--- +title: "[EKS] GitHub Action Runner Controller" +sidebar_label: "Actions Runner Controller (EKS)" +--- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; By default, GitHub Actions are run in the cloud on hosted machines, but we can opt to use "Self-Hosted" GitHub Action Runners instead. Historically, we've deployed an Auto Scaling Group that gives each run a dedicated and customized diff --git a/docs/reference/integrations/github/github-oidc-with-aws.md b/docs/layers/github-actions/github/github-oidc-with-aws.mdx similarity index 97% rename from docs/reference/integrations/github/github-oidc-with-aws.md rename to docs/layers/github-actions/github/github-oidc-with-aws.mdx index 8a68a79f5..7a9a88c04 100644 --- a/docs/reference/integrations/github/github-oidc-with-aws.md +++ b/docs/layers/github-actions/github/github-oidc-with-aws.mdx @@ -1,10 +1,11 @@ --- -title: "GitHub OIDC with AWS" +title: "How to use GitHub OIDC with AWS" +sidebar_label: "GitHub OIDC with AWS" sidebar_position: 10 custom_edit_url: https://github.com/cloudposse/refarch-scaffold/tree/main/docs/docs/how-to-guides/integrations/github/github-oidc-with-aws.md --- - -# How to use GitHub OIDC with AWS +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; GitHub OIDC (OpenID Connect) for AWS refers to the integration between GitHub as an identity provider using OpenID Connect and AWS services. This integration allows users to use their GitHub credentials to authenticate and access AWS resources securely. By configuring GitHub as an OIDC provider in AWS Identity and Access Management (IAM), organizations can establish a federated identity model. This enables GitHub users to sign in to AWS using their GitHub credentials, streamlining access management and eliminating the need for separate AWS-specific usernames and passwords. The integration also provides a centralized way to manage access permissions and enables Single Sign-On (SSO) capabilities, enhancing security and user experience in the AWS environment. Organizations can configure OIDC settings in AWS, including client IDs, client secrets, and the GitHub OIDC discovery URL, to establish a trust relationship between GitHub and AWS. For the most accurate and up-to-date information, it's recommended to check the official documentation of GitHub and AWS. diff --git a/docs/reference/integrations/github/github.md b/docs/layers/github-actions/github/github.mdx similarity index 94% rename from docs/reference/integrations/github/github.md rename to docs/layers/github-actions/github/github.mdx index adabbb023..63671f4aa 100644 --- a/docs/reference/integrations/github/github.md +++ b/docs/layers/github-actions/github/github.mdx @@ -1,10 +1,10 @@ --- title: "GitHub" +sidebar_label: "GitHub" sidebar_position: 10 -custom_edit_url: https://github.com/cloudposse/refarch-scaffold/tree/main/docs/docs/how-to-guides/integrations/github/github.md --- - -# GitHub +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; GitHub can serve as a central platform for hosting infrastructure code written in Atmos and Terraform, and it can seamlessly integrate with GitHub Actions to automate workflows associated with these infrastructure-as-code (IaC) tools. diff --git a/docs/layers/github-actions/philips-labs-github-runners.mdx b/docs/layers/github-actions/philips-labs-github-runners.mdx index 76a82de09..aba5707cf 100644 --- a/docs/layers/github-actions/philips-labs-github-runners.mdx +++ b/docs/layers/github-actions/philips-labs-github-runners.mdx @@ -1,4 +1,9 @@ -# Philips Labs GitHub Action Runners +--- +title: Philips Labs GitHub Action Runners +sidebar_label: Philips Labs Action Runners +--- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; If we are not deploying EKS, it's not worth the additional effort to set up Self-Hosted runners on EKS. Instead, we deploy Self-Hosted runners on EC2 instances. These are managed by an API Gateway and Lambda function that will diff --git a/docs/layers/gitops/03-gitops.md b/docs/layers/gitops/03-gitops.mdx similarity index 95% rename from docs/layers/gitops/03-gitops.md rename to docs/layers/gitops/03-gitops.mdx index 1902e43a6..1420b8839 100644 --- a/docs/layers/gitops/03-gitops.md +++ b/docs/layers/gitops/03-gitops.mdx @@ -1,4 +1,9 @@ -# GitOps +--- +title: "GitOps" +sidebar_label: "GitOps" +--- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Quick Start @@ -29,10 +34,10 @@ The `gitops` stack config depends on the following GitHub variables: * `ATMOS_CONFIG_PATH` - The path to the Atmos config file Please set the following GitHub variables in the repository settings: - -1. Open the repository [settings](https://github.com/acme/infra-acme/settings/variables/actions) + +1. Open the repository [settings](https://github.com/acme/infra-acme/settings/variables/actions) 2. Set variable `ATMOS_VERSION` to the `1.63.0` value -3. Set variable `ATMOS_CONFIG_PATH` to the `./rootfs/usr/local/etc/atmos/` value +3. Set variable `ATMOS_CONFIG_PATH` to the `./rootfs/usr/local/etc/atmos/` value ### Authentication Prerequisites diff --git a/docs/layers/gitops/gitops.mdx b/docs/layers/gitops/gitops.mdx index 715f2332c..7596c4878 100644 --- a/docs/layers/gitops/gitops.mdx +++ b/docs/layers/gitops/gitops.mdx @@ -1,8 +1,9 @@ --- title: "Quick Start" +sidebar_label: "GitOps" sidebar_class_name: hidden --- - -# GitOps +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; removed this page because it errors out without addition work. copy and fix this page from refarch-scaffold fundamentals diff --git a/docs/layers/identity/aws-saml.mdx b/docs/layers/identity/aws-saml.mdx index 02f5b3bb8..cdcd6c342 100644 --- a/docs/layers/identity/aws-saml.mdx +++ b/docs/layers/identity/aws-saml.mdx @@ -1,9 +1,10 @@ --- -title: "Connect with AWS SAML" +title: "Using AWS SAML to Access AWS" +sidebar_label: "AWS SAML" sidebar_position: 20 --- - -# Using AWS SAML to Access AWS +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; As an alternative to AWS SSO, the AWS SAML creates an Identity Provider (IdP) to authenticate with AWS via a federated identity. You can use this federated identity to connect directly to a given AWS Team. diff --git a/docs/layers/identity/aws-sso.mdx b/docs/layers/identity/aws-sso.mdx index 5ff32a327..417783979 100644 --- a/docs/layers/identity/aws-sso.mdx +++ b/docs/layers/identity/aws-sso.mdx @@ -1,9 +1,10 @@ --- -title: "Connect with AWS Identity Center" +title: "AWS Identity Center (SSO) ClickOps" +sidebar_label: "Connect with AWS Identity Center" sidebar_position: 10 --- - -# AWS Identity Center (SSO) ClickOps +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Prerequisites diff --git a/docs/layers/identity/centralized-terraform-access.mdx b/docs/layers/identity/centralized-terraform-access.mdx index 39ba90943..19470f9f5 100644 --- a/docs/layers/identity/centralized-terraform-access.mdx +++ b/docs/layers/identity/centralized-terraform-access.mdx @@ -1,9 +1,10 @@ --- -title: "Understand Terraform Access" +title: "Centralized access management for Terraform" +sidebar_label: "Understand Terraform Access" sidebar_position: 00 --- - -# Centralized access management for Terraform +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; very similar monitoring requirements because we filter for customers who match our delivery model. The actual fine-tuning of it will be specific to the customer. Our goal with this ADR is to identify the reusable, standard SLI/SLO for our customers that we can readily implement time and time again. diff --git a/docs/layers/monitoring/datadog/how-to-create-a-synthetic-and-slo.md b/docs/layers/monitoring/datadog/how-to-create-a-synthetic-and-slo.mdx similarity index 91% rename from docs/layers/monitoring/datadog/how-to-create-a-synthetic-and-slo.md rename to docs/layers/monitoring/datadog/how-to-create-a-synthetic-and-slo.mdx index 9d565d098..61ba5b82e 100644 --- a/docs/layers/monitoring/datadog/how-to-create-a-synthetic-and-slo.md +++ b/docs/layers/monitoring/datadog/how-to-create-a-synthetic-and-slo.mdx @@ -1,10 +1,10 @@ --- -title: "Create a Synthetic and SLO" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1291190303/How+to+create+a+Synthetic+and+SLO +title: "How to create a Synthetic and SLO" +sidebar_label: "Create a Synthetic and SLO" sidebar_position: 100 --- - -# How to create a Synthetic and SLO +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem After adding a service you often have synthetic checks to determine its health and check KPIs. We also might have a business need for a specific uptime or value of a KPI. In order to do that we need to create synthetics and SLOs. diff --git a/docs/layers/monitoring/datadog/how-to-monitor-a-new-service.md b/docs/layers/monitoring/datadog/how-to-monitor-a-new-service.mdx similarity index 87% rename from docs/layers/monitoring/datadog/how-to-monitor-a-new-service.md rename to docs/layers/monitoring/datadog/how-to-monitor-a-new-service.mdx index f610b4b45..896c9fd0b 100644 --- a/docs/layers/monitoring/datadog/how-to-monitor-a-new-service.md +++ b/docs/layers/monitoring/datadog/how-to-monitor-a-new-service.mdx @@ -1,12 +1,13 @@ --- -title: "Monitor a new Service" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1295876536/How+to+Monitor+a+new+Service +title: "How to Monitor a new Service" +sidebar_label: "Monitor a new Service" sidebar_position: 100 --- - -# How to Monitor a new Service +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem + When onboarding a new service we need some monitors to ensure its in a healthy status. ## Solution diff --git a/docs/layers/monitoring/datadog/how-to-pass-tags-along-to-datadog.md b/docs/layers/monitoring/datadog/how-to-pass-tags-along-to-datadog.mdx similarity index 94% rename from docs/layers/monitoring/datadog/how-to-pass-tags-along-to-datadog.md rename to docs/layers/monitoring/datadog/how-to-pass-tags-along-to-datadog.mdx index 2005f0772..59fc5d26d 100644 --- a/docs/layers/monitoring/datadog/how-to-pass-tags-along-to-datadog.md +++ b/docs/layers/monitoring/datadog/how-to-pass-tags-along-to-datadog.mdx @@ -1,10 +1,10 @@ --- -title: "Passing Tags" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1288962522/How+to+Pass+Tags+Along+to+Datadog +title: "How to Pass Tags Along to Datadog" +sidebar_label: "Passing Tags" sidebar_position: 100 --- - -# How to Pass Tags Along to Datadog +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem Tags are a great approach to describing who owns what services, and who should respond to different incidents related to those services. In order for to be able to act on the information, we need to ensure it’s passed along to datadog. Depending on if something is running on Kubernetes or infrastructure like RDS or an ALB, the way we tag (or label) things will differ. diff --git a/docs/layers/monitoring/datadog/how-to-provision-and-tune-datadog-monitors-by-stage.md b/docs/layers/monitoring/datadog/how-to-provision-and-tune-datadog-monitors-by-stage.mdx similarity index 94% rename from docs/layers/monitoring/datadog/how-to-provision-and-tune-datadog-monitors-by-stage.md rename to docs/layers/monitoring/datadog/how-to-provision-and-tune-datadog-monitors-by-stage.mdx index 6e860d10d..a191e8881 100644 --- a/docs/layers/monitoring/datadog/how-to-provision-and-tune-datadog-monitors-by-stage.md +++ b/docs/layers/monitoring/datadog/how-to-provision-and-tune-datadog-monitors-by-stage.mdx @@ -1,12 +1,13 @@ --- -title: "Monitors by Stage" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1201438874/How+to+Provision+and+Tune+Datadog+Monitors+by+Stage +title: "How to Provision and Tune Datadog Monitors by Stage" +sidebar_label: "Monitors by Stage" sidebar_position: 100 --- - -# How to Provision and Tune Datadog Monitors by Stage +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem + Datadog is a powerful platform with many ways of being configured. No one size fits all. Some companies choose to run with multiple datadog organizations, while others choose to consolidate in one account. Some companies want to adjust the thresholds at a service level, while others at the stage level. Multiple configurations exist and choosing the right one depends on what you want to accomplish. ## Solution @@ -21,6 +22,7 @@ Monitoring happens at every layer of your infrastructure. We should strive to pu ### Application Monitors + Application monitors should be provisioned to monitor anything not caught by the underlying layers (e.g. application-specific behavior). See [How to Use Multiple Infrastructure Repositories with Spacelift?](/reference-architecture/how-to-guides/integrations/spacelift/how-to-use-multiple-infrastructure-repositories-with-spacelift) for one approach to manage monitors using terraform. @@ -30,6 +32,7 @@ See [https://github.com/FairwindsOps/astro](https://github.com/FairwindsOps/astr [https://github.com/FairwindsOps/astro/blob/master/conf-example.yml](https://github.com/FairwindsOps/astro/blob/master/conf-example.yml) ### Platform Monitors by Stage + In general, we should strive for delivering platform-level monitors that apply to all services operating on the platform, rather than one-off monitors for individual applications. Of course, there will always be exceptions - just use this as a guideline. Here’s an example of setting up alerts for a production-tier and non-production-tier. @@ -64,5 +67,3 @@ components: datadog_synthetics_config_paths: [] ``` - - diff --git a/docs/layers/monitoring/datadog/how-to-setup-datadog-cluster-checks-and-network-monitors-for-ext.md b/docs/layers/monitoring/datadog/how-to-setup-datadog-cluster-checks-and-network-monitors-for-ext.mdx similarity index 90% rename from docs/layers/monitoring/datadog/how-to-setup-datadog-cluster-checks-and-network-monitors-for-ext.md rename to docs/layers/monitoring/datadog/how-to-setup-datadog-cluster-checks-and-network-monitors-for-ext.mdx index 708fd2a69..d777817ef 100644 --- a/docs/layers/monitoring/datadog/how-to-setup-datadog-cluster-checks-and-network-monitors-for-ext.md +++ b/docs/layers/monitoring/datadog/how-to-setup-datadog-cluster-checks-and-network-monitors-for-ext.mdx @@ -1,12 +1,13 @@ --- -title: "Cluster Checks and Network Monitors" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1295974434/How+to+Setup+Datadog+Cluster+Checks+and+Network+Monitors+for+External+URLs+of+Applications +title: "How to Setup Datadog Cluster Checks and Network Monitors for External URLs of Applications" +sidebar_label: "Cluster Checks and Network Monitors" sidebar_position: 100 --- - -# How to Setup Datadog Cluster Checks and Network Monitors for External URLs of Applications +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem + We often want a lightweight way to ensure our endpoints remain healthy. In kubernetes this requires that a loadbalancer be setup with the right annotations and certs to allow traffic to your application. This creates dependencies on cert-manager and other platform tools. The Health Check of a kubernetes app will always use the local IP, which doesn’t really test your networking. We need a way to test that your apps are still ready to receive requests. ## Solution @@ -32,6 +33,7 @@ clusterAgent: ``` ### External URLs + We then need to set particular helm values for each installation of the agent in each cluster. the external URL checks must be written into the agent configuration and cannot be dynamically loaded by annotations. CloudPosse Datadog Agent now supports **Cluster Checks** this via `this pr` @@ -39,6 +41,7 @@ CloudPosse Datadog Agent now supports **Cluster Checks** this via `this pr` Upgrade to the latest and add your network checks as yaml. This follows the same configuration as monitors. Where checks are deep merged and templated, they can be configured per environment. ## Datadog Monitors + After your Cluster Checks are setup we need to create monitors for them.
@@ -86,7 +89,3 @@ https-checks: ```
- - - - diff --git a/docs/layers/monitoring/datadog/how-to-sign-up-for-datadog.md b/docs/layers/monitoring/datadog/how-to-sign-up-for-datadog.mdx similarity index 94% rename from docs/layers/monitoring/datadog/how-to-sign-up-for-datadog.md rename to docs/layers/monitoring/datadog/how-to-sign-up-for-datadog.mdx index dcb5fd052..29f0957f3 100644 --- a/docs/layers/monitoring/datadog/how-to-sign-up-for-datadog.md +++ b/docs/layers/monitoring/datadog/how-to-sign-up-for-datadog.mdx @@ -1,15 +1,17 @@ --- -title: "Sign Up for Datadog" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1209335952 +title: "How to Sign Up for Datadog?" +sidebar_label: "Sign Up for Datadog" sidebar_position: 100 --- - -# How to Sign Up for Datadog? +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem + You’ve been asked to sign up for DataDog, but you're not quite sure which plans and features you need. ## Solution + Review the [https://www.datadoghq.com/pricing/](https://www.datadoghq.com/pricing/) :::tip @@ -20,6 +22,7 @@ After signing up, if you require child organizations, make sure to request it be [https://docs.datadoghq.com/account_management/multi_organization/](https://docs.datadoghq.com/account_management/multi_organization/) (see [Decide on How to Restrict Access to Metrics and Logs in Datadog](/reference-architecture/fundamentals/design-decisions/foundational-monitoring-platform/decide-on-how-to-restrict-access-to-metrics-and-logs-in-datadog)) ### Recommended Features + - [https://www.datadoghq.com/blog/private-synthetic-monitoring/](https://www.datadoghq.com/blog/private-synthetic-monitoring/) - [https://docs.datadoghq.com/logs/](https://docs.datadoghq.com/logs/) @@ -35,11 +38,13 @@ After signing up, if you require child organizations, make sure to request it be - [https://docs.datadoghq.com/database_monitoring/](https://docs.datadoghq.com/database_monitoring/) ### Pricing Gotchas + - Commit to a certain number of hosts per month for cheaper pricing - If using spot instances, you may be charged for multiple hosts. For instance, you may use a spot instance for an EKS node, the node is replaced with another spot instance, and Datadog now charges for 2 hosts instead of 1 host for that month. ### Enterprise Plan + Many features are restricted to Enterprise Plans. :::caution @@ -61,6 +66,7 @@ Custom Roles are an enterprise only feature. [https://docs.datadoghq.com/account - Advanced Administrative Tools ### Pro Plan + The Pro Plan is the minimum acceptable plan that adds Alerts, Container Monitoring, SAML and Custom Metrics. - Unlimited Alerts @@ -78,6 +84,7 @@ The Pro Plan is the minimum acceptable plan that adds Alerts, Container Monitori - Outlier Detection ## Related Design Decisions + - [Decide on External Monitoring Solution](/reference-architecture/fundamentals/design-decisions/foundational-monitoring-platform/decide-on-external-monitoring-solution) - [Decide on Log Retention and Durability Architecture](/reference-architecture/fundamentals/design-decisions/foundational-benchmark-compliance/decide-on-log-retention-and-durability-architecture) diff --git a/docs/layers/monitoring/datadog/how-to-use-datadog-metrics-for-horizontal-pod-autoscaling-hpa.md b/docs/layers/monitoring/datadog/how-to-use-datadog-metrics-for-horizontal-pod-autoscaling-hpa.mdx similarity index 95% rename from docs/layers/monitoring/datadog/how-to-use-datadog-metrics-for-horizontal-pod-autoscaling-hpa.md rename to docs/layers/monitoring/datadog/how-to-use-datadog-metrics-for-horizontal-pod-autoscaling-hpa.mdx index ff0bb039b..9f04453fc 100644 --- a/docs/layers/monitoring/datadog/how-to-use-datadog-metrics-for-horizontal-pod-autoscaling-hpa.md +++ b/docs/layers/monitoring/datadog/how-to-use-datadog-metrics-for-horizontal-pod-autoscaling-hpa.mdx @@ -1,10 +1,10 @@ --- -title: "Horizontal Pod Autoscaling (HPA)" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1197834268 +title: "How to use Datadog Metrics for Horizontal Pod Autoscaling (HPA)" +sidebar_label: "Horizontal Pod Autoscaling (HPA)" sidebar_position: 100 --- - -# How to use Datadog Metrics for Horizontal Pod Autoscaling (HPA) +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem diff --git a/docs/layers/monitoring/design-decisions/decide-on-datadog-account-strategy.md b/docs/layers/monitoring/design-decisions/decide-on-datadog-account-strategy.mdx similarity index 96% rename from docs/layers/monitoring/design-decisions/decide-on-datadog-account-strategy.md rename to docs/layers/monitoring/design-decisions/decide-on-datadog-account-strategy.mdx index 0fc7ecc01..1255eee19 100644 --- a/docs/layers/monitoring/design-decisions/decide-on-datadog-account-strategy.md +++ b/docs/layers/monitoring/design-decisions/decide-on-datadog-account-strategy.mdx @@ -1,11 +1,11 @@ --- title: "Decide on Datadog Account Strategy" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1417805916/REFARCH-539+-+Decide+on+Datadog+Account+Strategy +sidebar_label: "Decide on Datadog Account Strategy" sidebar_position: 100 refarch_id: REFARCH-539 --- - -# Decide on Datadog Account Strategy +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Context and Problem Statement diff --git a/docs/layers/monitoring/design-decisions/decide-on-datadog-log-forwarding-requirements.md b/docs/layers/monitoring/design-decisions/decide-on-datadog-log-forwarding-requirements.mdx similarity index 70% rename from docs/layers/monitoring/design-decisions/decide-on-datadog-log-forwarding-requirements.md rename to docs/layers/monitoring/design-decisions/decide-on-datadog-log-forwarding-requirements.mdx index 04cb95b26..b6bd80d66 100644 --- a/docs/layers/monitoring/design-decisions/decide-on-datadog-log-forwarding-requirements.md +++ b/docs/layers/monitoring/design-decisions/decide-on-datadog-log-forwarding-requirements.mdx @@ -1,18 +1,19 @@ --- -title: "Decide on Datadog Log Forwarding Requirements" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1278738446/REFARCH-521+-+Decide+on+Datadog+Log+Forwarding+Requirements +title: "Decide on Datadog Account Strategy" +sidebar_label: "Datadog Log Forwarding" sidebar_position: 100 refarch_id: REFARCH-521 --- - -# Decide on Datadog Log Forwarding Requirements +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Context and Problem Statement + Datadog supports log ingestion, but [it can be costly.](https://www.datadoghq.com/pricing/?product=log-management#log-management) Some companies prefer to use in-place tooling like Splunk or Sumologic instead. ## Considered Options -### Option 1 (Recommended) - Use Datadog +### Option 1 (Recommended) - Use Datadog :::tip Our Recommendation is to use Option 1 because you get a single pane of glass view into all operations diff --git a/docs/layers/monitoring/design-decisions/decide-on-datadog-private-locations.md b/docs/layers/monitoring/design-decisions/decide-on-datadog-private-locations.mdx similarity index 93% rename from docs/layers/monitoring/design-decisions/decide-on-datadog-private-locations.md rename to docs/layers/monitoring/design-decisions/decide-on-datadog-private-locations.mdx index 077475ba6..8fbce0046 100644 --- a/docs/layers/monitoring/design-decisions/decide-on-datadog-private-locations.md +++ b/docs/layers/monitoring/design-decisions/decide-on-datadog-private-locations.mdx @@ -1,13 +1,14 @@ --- title: "Decide on Datadog Private Locations" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1223426229/REFARCH-499+-+Decide+on+Datadog+Private+Locations +sidebar_label: "Datadog Private Locations" sidebar_position: 100 refarch_id: REFARCH-499 --- - -# Decide on Datadog Private Locations +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem + Datadog Private Locations are a feature that needs to be enabled in your datadog account that allows monitoring applications that aren’t accessible to the open internet. To enable private locations, we need to: @@ -19,6 +20,7 @@ To enable private locations, we need to: We can deploy the private location container to EKS. This leads to another decision: Do we deploy it once with the capability to ping the rest of the clusters' internal addresses, or do we deploy it to every cluster? ## Cost + According to [https://www.datadoghq.com/pricing/?product=synthetic-monitoring#synthetic-monitoring-is-there-any-extra-charge-for-using-private-locations](https://www.datadoghq.com/pricing/?product=synthetic-monitoring#synthetic-monitoring-is-there-any-extra-charge-for-using-private-locations), registering a new Private Location is not at an additional cost; the regular costs for synthetics still apply. > [**Is there any extra charge for using private locations?**](https://www.datadoghq.com/pricing/?product=synthetic-monitoring#synthetic-monitoring-is-there-any-extra-charge-for-using-private-locations) diff --git a/docs/layers/monitoring/design-decisions/decide-on-external-monitoring-solution.md b/docs/layers/monitoring/design-decisions/decide-on-external-monitoring-solution.mdx similarity index 92% rename from docs/layers/monitoring/design-decisions/decide-on-external-monitoring-solution.md rename to docs/layers/monitoring/design-decisions/decide-on-external-monitoring-solution.mdx index 984d49cd3..5b3143c4c 100644 --- a/docs/layers/monitoring/design-decisions/decide-on-external-monitoring-solution.md +++ b/docs/layers/monitoring/design-decisions/decide-on-external-monitoring-solution.mdx @@ -1,9 +1,11 @@ --- title: "Decide on External Monitoring Solution" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1172078755/REFARCH-111+-+Decide+on+External+Monitoring+Solution +sidebar_label: "External Monitoring Solution" sidebar_position: 100 refarch_id: REFARCH-111 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # Decide on External Monitoring Solution diff --git a/docs/layers/monitoring/design-decisions/decide-on-how-to-restrict-access-to-metrics-and-logs-in-datadog.md b/docs/layers/monitoring/design-decisions/decide-on-how-to-restrict-access-to-metrics-and-logs-in-datadog.mdx similarity index 91% rename from docs/layers/monitoring/design-decisions/decide-on-how-to-restrict-access-to-metrics-and-logs-in-datadog.md rename to docs/layers/monitoring/design-decisions/decide-on-how-to-restrict-access-to-metrics-and-logs-in-datadog.mdx index de6d169b5..1522f3bd2 100644 --- a/docs/layers/monitoring/design-decisions/decide-on-how-to-restrict-access-to-metrics-and-logs-in-datadog.md +++ b/docs/layers/monitoring/design-decisions/decide-on-how-to-restrict-access-to-metrics-and-logs-in-datadog.mdx @@ -1,23 +1,26 @@ --- title: "Decide on How to Restrict Access to Metrics and Logs in Datadog" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1171652763/REFARCH-294+-+Decide+on+How+to+Restrict+Access+to+Metrics+and+Logs+in+Datadog +sidebar_label: "ACLs for Metrics and Logs" sidebar_position: 100 refarch_id: REFARCH-294 --- - -# Decide on How to Restrict Access to Metrics and Logs in Datadog +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem + Restricting access to metrics and logs concerns organizations subject to benchmark compliance. There are a few ways this can be done with various tradeoffs. ## Solution ### Option 1: RBAC + With RBAC, Roles can be used to categorize users and define what account permissions those users have (read, modify) on resources. Any user who is associated with one or more roles receives all permissions granted by their associated roles. The more roles a user is associated with, the more access they have within a Datadog account. [https://docs.datadoghq.com/account_management/rbac/permissions/](https://docs.datadoghq.com/account_management/rbac/permissions/) #### Built-in Roles (Recommended) + By default, Datadog offers three roles, - Datadog Admin @@ -27,6 +30,7 @@ By default, Datadog offers three roles, - Datadog Read-Only #### Custom Roles + You can create [custom roles](https://docs.datadoghq.com/account_management/rbac/?tab=datadogapplication#custom-roles) to define a better mapping between your users and their permissions. :::info diff --git a/docs/layers/monitoring/design-decisions/decide-on-maintenance-page-solution.md b/docs/layers/monitoring/design-decisions/decide-on-maintenance-page-solution.mdx similarity index 91% rename from docs/layers/monitoring/design-decisions/decide-on-maintenance-page-solution.md rename to docs/layers/monitoring/design-decisions/decide-on-maintenance-page-solution.mdx index 9a77ec2d7..c7ad055ff 100644 --- a/docs/layers/monitoring/design-decisions/decide-on-maintenance-page-solution.md +++ b/docs/layers/monitoring/design-decisions/decide-on-maintenance-page-solution.mdx @@ -1,13 +1,14 @@ --- title: "Decide on Maintenance Page Solution" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1171652750/REFARCH-112+-+Decide+on+Maintenance+Page+Solution +sidebar_label: "Maintenance Page" sidebar_position: 100 refarch_id: REFARCH-112 --- - -# Decide on Maintenance Page Solution +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem +
When your sites go down, we need to be able to communicate more graciously to customers that you’re having issues than a generic “502 Bad Gateway” message. @@ -24,6 +25,7 @@ We recommend deploying a static maintenance page. The industry best practice is Some related considerations are how the maintenance page will be activated. ### Considered Options + There are a few options: ### Option 1 diff --git a/docs/layers/monitoring/design-decisions/decide-on-whether-to-use-datadog-roles.md b/docs/layers/monitoring/design-decisions/decide-on-whether-to-use-datadog-roles.mdx similarity index 79% rename from docs/layers/monitoring/design-decisions/decide-on-whether-to-use-datadog-roles.md rename to docs/layers/monitoring/design-decisions/decide-on-whether-to-use-datadog-roles.mdx index 2c639b8bc..67bd5a949 100644 --- a/docs/layers/monitoring/design-decisions/decide-on-whether-to-use-datadog-roles.md +++ b/docs/layers/monitoring/design-decisions/decide-on-whether-to-use-datadog-roles.mdx @@ -1,13 +1,14 @@ --- title: "Decide on whether to use Datadog roles" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1192722498/REFARCH-480+-+Decide+on+whether+to+use+Datadog+roles +sidebar_label: "Datadog Roles" sidebar_position: 100 refarch_id: REFARCH-480 --- - -# Decide on whether to use Datadog roles +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem + Roles can be used to restrict access to dashboards and monitors. ## Solution diff --git a/docs/layers/monitoring/grafana/07-grafana.md b/docs/layers/monitoring/grafana/07-grafana.mdx similarity index 95% rename from docs/layers/monitoring/grafana/07-grafana.md rename to docs/layers/monitoring/grafana/07-grafana.mdx index 2e8ebf381..e33f08736 100644 --- a/docs/layers/monitoring/grafana/07-grafana.md +++ b/docs/layers/monitoring/grafana/07-grafana.mdx @@ -1,4 +1,9 @@ -# Grafana +--- +title: Grafana +sidebar_label: Grafana +--- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Quick Start diff --git a/docs/layers/monitoring/grafana/grafana.mdx b/docs/layers/monitoring/grafana/grafana.mdx index 186b1f342..01121da6a 100644 --- a/docs/layers/monitoring/grafana/grafana.mdx +++ b/docs/layers/monitoring/grafana/grafana.mdx @@ -1,13 +1,14 @@ --- -title: "Amazon Managed Grafana" +title: "How to Setup Amazon Managed Grafana" +sidebar_label: "Amazon Managed Grafana" tags: - grafana - prometheus - loki - promtail --- - -# How to Setup Amazon Managed Grafana +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; The Amazon Managed Grafana is a fully managed service for Grafana used to query, visualize, and alert on your metrics, logs, and traces. Grafana provides a centralized dashboard where we can add many data sources. diff --git a/docs/layers/monitoring/monitoring.md b/docs/layers/monitoring/monitoring.mdx similarity index 98% rename from docs/layers/monitoring/monitoring.md rename to docs/layers/monitoring/monitoring.mdx index 00ca8ab64..6c59336b8 100644 --- a/docs/layers/monitoring/monitoring.md +++ b/docs/layers/monitoring/monitoring.mdx @@ -1,9 +1,10 @@ --- title: "Monitoring" +sidebar_label: "Monitoring" sidebar_class_name: hidden --- - -# Monitoring +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; Monitoring is a key component of any production system. It is important to have visibility into the health of your system and to be able to react to issues before they become problems. diff --git a/docs/layers/network-and-dns/access-network.mdx b/docs/layers/network-and-dns/access-network.mdx index 31fc6277d..4ae4ad3cb 100644 --- a/docs/layers/network-and-dns/access-network.mdx +++ b/docs/layers/network-and-dns/access-network.mdx @@ -1,26 +1,20 @@ --- -title: "Access the Network" +title: "Accessing the Network" +sidebar_label: "Access the Network" sidebar_position: 30 --- - -# Accessing the Network +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; Lastly, configure the VPN. The VPN will be provisioned in the `network` account and will leverage Transit Gateway to connect various VPCs to the VPN client. VPN deployment consists of three parts: authentication, component deployment, and client setup. -First, set up authentication. We recommend -[using AWS IAM Identity Center to authenticate users](https://aws.amazon.com/blogs/security/authenticate-aws-client-vpn-users-with-aws-single-sign-on/). -Follow only the first section included in the linked AWS blog, _Create and configure the Client VPN SAML applications in -AWS IAM Identity Center_, through downloading the _AWS IAM Identity Center SAML metadata_. Save that file under the -`ec2-client-vpn` component (`components/terraform/ec2-client-vpn`) as "aws-sso-saml-app.xml". This should match the -given document name for `saml_metadata_document` in the `ec2-client-vpn` stack catalog -(`stacks/catalog/ec2-client-vpn.yaml`) +First, set up authentication. We recommend [using AWS IAM Identity Center to authenticate users](https://aws.amazon.com/blogs/security/authenticate-aws-client-vpn-users-with-aws-single-sign-on/). Follow only the first section included in the linked AWS blog, _Create and configure the Client VPN SAML applications in AWS IAM Identity Center_, through downloading the _AWS IAM Identity Center SAML metadata_. Save that file under the `ec2-client-vpn` component (`components/terraform/ec2-client-vpn`) as "aws-sso-saml-app.xml". This should match the given document name for `saml_metadata_document` in the `ec2-client-vpn` stack catalog (`stacks/catalog/ec2-client-vpn.yaml`) Next, deploy the `ec2-client-vpn` component. This is done by running `atmos workflow deploy/vpn -f network`. -Depending on the given network configuration, you may run out of available Client VPN routes. That error will look -something like this: +Depending on the given network configuration, you may run out of available Client VPN routes. That error will look something like this: ``` ╷ @@ -39,27 +33,19 @@ allowed for the Client VPN endpoint. That said, you should already have a quota [../../stacks/orgs/acme/core/network/global-region/baseline.yaml](../../stacks/orgs/acme/core/network/global-region/baseline.yaml). You can apply that quota using `atmos terraform apply account-quotas -s core-gbl-network`. -Finally, set up the AWS VPN Client to access the VPN. -[Download the AWS VPN Client](https://aws.amazon.com/vpn/client-vpn-download/) and or install it by running -`brew install aws-client-vpn` in a regular terminal. Follow the -[AWS Documentation](https://docs.aws.amazon.com/vpn/latest/clientvpn-user/connect-aws-client-vpn-connect.html) to -complete the VPN setup. +Finally, set up the AWS VPN Client to access the VPN. [Download the AWS VPN Client](https://aws.amazon.com/vpn/client-vpn-download/) and or install it by running `brew install aws-client-vpn` in a regular terminal. Follow the +[AWS Documentation](https://docs.aws.amazon.com/vpn/latest/clientvpn-user/connect-aws-client-vpn-connect.html) to complete the VPN setup. -The Atmos Workflow `deploy/vpn` creates a local VPN configuration as `acme-core.ovpn` -(`rootfs/etc/aws-config/acme-core.ovpn`) located in the aws-config dir of `rootfs`. If it doesn't exist, create this -file using the `client_configuration` output of the `ec2-client-vpn` component, and commit it to the repo under -`rootfs/etc/aws-config/acme-core.ovpn` for future reference. +The Atmos Workflow `deploy/vpn` creates a local VPN configuration as `acme-core.ovpn` (`rootfs/etc/aws-config/acme-core.ovpn`) located in the aws-config dir of `rootfs`. If it doesn't exist, create this file using the `client_configuration` output of the `ec2-client-vpn` component, and commit it to the repo under `rootfs/etc/aws-config/acme-core.ovpn` for future reference. ``` atmos terraform output ec2-client-vpn -s core-use1-network ``` -Once you configure the AWS VPN Client, set the file as the config and connect. From there you should be able to access -resources on any subnet in the VPCs you've provisioned. +Once you configure the AWS VPN Client, set the file as the config and connect. From there you should be able to access resources on any subnet in the VPCs you've provisioned. ### Optional: Bastion hosts -If you'd like to set up bastion hosts, you can do so by running `atmos workflow deploy/bastion -f network`. This would -let you further evaluate the VPN. +If you'd like to set up bastion hosts, you can do so by running `atmos workflow deploy/bastion -f network`. This would let you further evaluate the VPN. By default, we deploy the bastion to all accounts connected to Transit Gateway. diff --git a/docs/layers/network-and-dns/connect-network.mdx b/docs/layers/network-and-dns/connect-network.mdx index 2d535e488..7b40b6d4f 100644 --- a/docs/layers/network-and-dns/connect-network.mdx +++ b/docs/layers/network-and-dns/connect-network.mdx @@ -1,9 +1,10 @@ --- -title: "Establish Connectivity" +title: "Establish Connectivity with Transit Gateway" +sidebar_label: "Establish Connectivity" sidebar_position: 10 --- - -# Establish Connectivity with Transit Gateway +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Deployment @@ -36,11 +37,7 @@ If this happens, you can safely wait a minute or two and then re-attempt the pro ### Redeploy `tgw` when Deploying a New EKS Cluster -The file `stacks/catalog/tgw/hub.yaml` and the separate `tgw/spokes` in each `stacks/org/**/global-region/network.yaml` -potentially contain references to EKS Clusters using the `eks_component_names` variable. If you add an EKS Cluster, then -you will want to look up the individual `spoke` and `hub` components that are affected. If you are using cross-region -`tgw/cross-region-hub-connector` components, you will also want to update `eks_component_names` on the regional -connections. +The file `stacks/catalog/tgw/hub.yaml` and the separate `tgw/spokes` in each `stacks/org/**/global-region/network.yaml` potentially contain references to EKS Clusters using the `eks_component_names` variable. If you add an EKS Cluster, then you will want to look up the individual `spoke` and `hub` components that are affected. If you are using cross-region `tgw/cross-region-hub-connector` components, you will also want to update `eks_component_names` on the regional connections. ``` atmos workflow deploy/tgw -f network diff --git a/docs/layers/network-and-dns/deploy-vpcs.mdx b/docs/layers/network-and-dns/deploy-vpcs.mdx index 360277f40..086b24961 100644 --- a/docs/layers/network-and-dns/deploy-vpcs.mdx +++ b/docs/layers/network-and-dns/deploy-vpcs.mdx @@ -1,12 +1,14 @@ --- -title: "Deploy VPCs" +title: "Deploying the Network" +sidebar_label: "Deploy VPCs" sidebar_position: 0 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; -# Deploying the Network - -The first step in deploying the network is to deploy the VPCs in each region. This will create the necessary foundation -for the platform to run and includes the VPC, subnets, route tables, security groups, and VPC endpoints. + +The first step in deploying the network is to deploy the VPCs in each region. This will create the necessary foundation for the platform to run and includes the VPC, subnets, route tables, security groups, and VPC endpoints. + ## Deployment @@ -22,8 +24,7 @@ Once this is done, initialize all the VPCs in every configured region by running atmos workflow deploy/vpc -f network ``` -Once all VPCs are deployed, decomission the default VPC in each region by running the following command from within the -Geodesic shell: +Once all VPCs are deployed, decomission the default VPC in each region by running the following command from within the Geodesic shell: ```bash wipe-default-vpcs diff --git a/docs/layers/network-and-dns/design-decisions/decide-on-aws-account-vpc-subnet-cidr-strategy.md b/docs/layers/network-and-dns/design-decisions/decide-on-aws-account-vpc-subnet-cidr-strategy.mdx similarity index 98% rename from docs/layers/network-and-dns/design-decisions/decide-on-aws-account-vpc-subnet-cidr-strategy.md rename to docs/layers/network-and-dns/design-decisions/decide-on-aws-account-vpc-subnet-cidr-strategy.mdx index bc8d77d54..dc1b331a1 100644 --- a/docs/layers/network-and-dns/design-decisions/decide-on-aws-account-vpc-subnet-cidr-strategy.md +++ b/docs/layers/network-and-dns/design-decisions/decide-on-aws-account-vpc-subnet-cidr-strategy.mdx @@ -1,9 +1,10 @@ --- title: "Decide on AWS Account VPC Subnet CIDR Strategy" +sidebar_label: "VPC Subnet CIDR Strategy" refarch_id: REFARCH-217 --- - -# Decide on AWS Account VPC Subnet CIDR Strategy +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem diff --git a/docs/layers/network-and-dns/design-decisions/decide-on-cidr-allocation.md b/docs/layers/network-and-dns/design-decisions/decide-on-cidr-allocation.mdx similarity index 71% rename from docs/layers/network-and-dns/design-decisions/decide-on-cidr-allocation.md rename to docs/layers/network-and-dns/design-decisions/decide-on-cidr-allocation.mdx index a6c3b3cc8..863f8ded2 100644 --- a/docs/layers/network-and-dns/design-decisions/decide-on-cidr-allocation.md +++ b/docs/layers/network-and-dns/design-decisions/decide-on-cidr-allocation.mdx @@ -1,4 +1,9 @@ -# Decide on CIDR Allocation +--- +title: Decide on CIDR Allocations +sidebar_label: CIDR Allocations +--- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; Please also read the [design decision](/learn/network/design-decisions/decide-on-aws-account-vpc-subnet-cidr-strategy/) for more information. diff --git a/docs/layers/network-and-dns/design-decisions/decide-on-client-vpn-options.md b/docs/layers/network-and-dns/design-decisions/decide-on-client-vpn-options.mdx similarity index 93% rename from docs/layers/network-and-dns/design-decisions/decide-on-client-vpn-options.md rename to docs/layers/network-and-dns/design-decisions/decide-on-client-vpn-options.mdx index a235a9b0e..ed243cc62 100644 --- a/docs/layers/network-and-dns/design-decisions/decide-on-client-vpn-options.md +++ b/docs/layers/network-and-dns/design-decisions/decide-on-client-vpn-options.mdx @@ -1,9 +1,10 @@ --- title: "Decide on Client VPN Options" +sidebar_label: "Client VPN Options" refarch_id: REFARCH-517 --- - -# Decide on Client VPN Options +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Context and Problem Statement diff --git a/docs/layers/network-and-dns/design-decisions/decide-on-hostname-scheme-for-service-discovery.md b/docs/layers/network-and-dns/design-decisions/decide-on-hostname-scheme-for-service-discovery.mdx similarity index 92% rename from docs/layers/network-and-dns/design-decisions/decide-on-hostname-scheme-for-service-discovery.md rename to docs/layers/network-and-dns/design-decisions/decide-on-hostname-scheme-for-service-discovery.mdx index 850ad26d9..65bfcd3e3 100644 --- a/docs/layers/network-and-dns/design-decisions/decide-on-hostname-scheme-for-service-discovery.md +++ b/docs/layers/network-and-dns/design-decisions/decide-on-hostname-scheme-for-service-discovery.mdx @@ -1,9 +1,10 @@ --- title: "Decide on Hostname Scheme for Service Discovery" +sidebar_label: "Hostname Scheme for Service Discovery" refarch_id: REFARCH-208 --- - -# Decide on Hostname Scheme for Service Discovery +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ### Context and Problem Statement diff --git a/docs/layers/network-and-dns/design-decisions/decide-on-how-to-support-tls.md b/docs/layers/network-and-dns/design-decisions/decide-on-how-to-support-tls.mdx similarity index 76% rename from docs/layers/network-and-dns/design-decisions/decide-on-how-to-support-tls.md rename to docs/layers/network-and-dns/design-decisions/decide-on-how-to-support-tls.mdx index bd49422bd..353e16210 100644 --- a/docs/layers/network-and-dns/design-decisions/decide-on-how-to-support-tls.md +++ b/docs/layers/network-and-dns/design-decisions/decide-on-how-to-support-tls.mdx @@ -1,9 +1,10 @@ --- title: "Decide on How to Support TLS" +sidebar_label: "How to Support TLS" refarch_id: REFARCH-494 --- - -# Decide on How to Support TLS +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Context and Problem Statement diff --git a/docs/layers/network-and-dns/design-decisions/decide-on-ipv4-and-ipv6-support.md b/docs/layers/network-and-dns/design-decisions/decide-on-ipv4-and-ipv6-support.mdx similarity index 77% rename from docs/layers/network-and-dns/design-decisions/decide-on-ipv4-and-ipv6-support.md rename to docs/layers/network-and-dns/design-decisions/decide-on-ipv4-and-ipv6-support.mdx index 5f166e6c7..cdd18045f 100644 --- a/docs/layers/network-and-dns/design-decisions/decide-on-ipv4-and-ipv6-support.md +++ b/docs/layers/network-and-dns/design-decisions/decide-on-ipv4-and-ipv6-support.mdx @@ -1,9 +1,10 @@ --- title: "Decide on IPv4 and IPv6 support" +sidebar_label: "IPv4 and IPv6" refarch_id: REFARCH-541 --- - -# Decide on IPv4 and IPv6 support +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Context and Problem Statement diff --git a/docs/layers/network-and-dns/design-decisions/decide-on-opting-into-non-default-regions.mdx b/docs/layers/network-and-dns/design-decisions/decide-on-opting-into-non-default-regions.mdx index 66ee5c66f..7fdd69777 100644 --- a/docs/layers/network-and-dns/design-decisions/decide-on-opting-into-non-default-regions.mdx +++ b/docs/layers/network-and-dns/design-decisions/decide-on-opting-into-non-default-regions.mdx @@ -1,9 +1,10 @@ --- title: "Decide on Opting Into Non-default Regions" +sidebar_label: "Opting Into Non-default Regions" refarch_id: REFARCH-392 --- - -# Decide on Opting Into Non-default Regions +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; If a Region is disabled by default, you must enable it before you can create and manage resources. It would be a pre-requisite to deploying anything in the region. diff --git a/docs/layers/network-and-dns/design-decisions/decide-on-organization-supernet-cidr-ranges.md b/docs/layers/network-and-dns/design-decisions/decide-on-organization-supernet-cidr-ranges.mdx similarity index 89% rename from docs/layers/network-and-dns/design-decisions/decide-on-organization-supernet-cidr-ranges.md rename to docs/layers/network-and-dns/design-decisions/decide-on-organization-supernet-cidr-ranges.mdx index 8830d2c60..935289c6b 100644 --- a/docs/layers/network-and-dns/design-decisions/decide-on-organization-supernet-cidr-ranges.md +++ b/docs/layers/network-and-dns/design-decisions/decide-on-organization-supernet-cidr-ranges.mdx @@ -1,9 +1,10 @@ --- title: "Decide on Organization Supernet CIDR Ranges" +sidebar_label: "Organization Supernet CIDR Ranges" refarch_id: REFARCH-240 --- - -# Decide on Organization Supernet CIDR Ranges +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem diff --git a/docs/layers/network-and-dns/design-decisions/decide-on-primary-aws-region.mdx b/docs/layers/network-and-dns/design-decisions/decide-on-primary-aws-region.mdx index 6b02431b7..7bb6cea4a 100644 --- a/docs/layers/network-and-dns/design-decisions/decide-on-primary-aws-region.mdx +++ b/docs/layers/network-and-dns/design-decisions/decide-on-primary-aws-region.mdx @@ -1,9 +1,10 @@ --- title: "Decide on Primary AWS Region" +sidebar_label: "Primary AWS Region" refarch_id: REFARCH-56 --- - -# Decide on Primary AWS Region +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; While the company might operate in multiple regions, one region should be selected as the primary region. There are certain resources that will not be geographically distributed and these should be provisioned in this default region. diff --git a/docs/layers/network-and-dns/design-decisions/decide-on-service-discovery-domain.md b/docs/layers/network-and-dns/design-decisions/decide-on-service-discovery-domain.mdx similarity index 87% rename from docs/layers/network-and-dns/design-decisions/decide-on-service-discovery-domain.md rename to docs/layers/network-and-dns/design-decisions/decide-on-service-discovery-domain.mdx index a8003d1c7..f55458c79 100644 --- a/docs/layers/network-and-dns/design-decisions/decide-on-service-discovery-domain.md +++ b/docs/layers/network-and-dns/design-decisions/decide-on-service-discovery-domain.mdx @@ -1,24 +1,16 @@ --- title: "Decide on Service Discovery Domain" +sidebar_label: "Service Discovery Domain" refarch_id: REFARCH-46 --- - +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; import ReactPlayer from 'react-player' -# Decide on Service Discovery Domain - -It's important to distinguish between branded/vanity domains (e.g. `cloudposse.com`, `slack.cloudposse.com`) used by -customers and your infrastructure service discovery domains (e.g. `cloudposse.net`) used by services or internal -consumers. For example, a product might have dozens of branded domains for SEO and marketing purposes, but you'll only -have one infrastructure powering it. The service discovery domain is only for internal consumption. We get to define the -conventions for this, not marketing. 😉 The service discovery domain will always be hosted on Route53, while the vanity -domain can be hosted anywhere. +It's important to distinguish between branded/vanity domains (e.g. `cloudposse.com`, `slack.cloudposse.com`) used by customers and your infrastructure service discovery domains (e.g. `cloudposse.net`) used by services or internal consumers. For example, a product might have dozens of branded domains for SEO and marketing purposes, but you'll only have one infrastructure powering it. The service discovery domain is only for internal consumption. We get to define the conventions for this, not marketing. 😉 The service discovery domain will always be hosted on Route53, while the vanity domain can be hosted anywhere. The "service discovery domain" will be further subdivided by delegating a dedicated zone to each AWS account. For -example, we don’t share DNS zones between production and staging. Therefore each account has its own service discovery -domain (E.g. `prod.example.net`). See -[Decide on Hostname Scheme for Service Discovery](/learn/network/design-decisions/decide-on-hostname-scheme-for-service-discovery) -for more context. +example, we don’t share DNS zones between production and staging. Therefore each account has its own service discovery domain (E.g. `prod.example.net`). See [Decide on Hostname Scheme for Service Discovery](/learn/network/design-decisions/decide-on-hostname-scheme-for-service-discovery) for more context. This is a non-reversible decision, so we recommend taking the time to discuss with the team what they like the best. @@ -26,7 +18,9 @@ This is a non-reversible decision, so we recommend taking the time to discuss wi ### Length of Domain -:::tip Our recommendation is to keep it short and simple. +:::tip + +Our recommendation is to keep it short and simple. ::: diff --git a/docs/layers/network-and-dns/design-decisions/decide-on-transit-gateway-requirements.md b/docs/layers/network-and-dns/design-decisions/decide-on-transit-gateway-requirements.mdx similarity index 92% rename from docs/layers/network-and-dns/design-decisions/decide-on-transit-gateway-requirements.md rename to docs/layers/network-and-dns/design-decisions/decide-on-transit-gateway-requirements.mdx index 254c44d01..a914757c6 100644 --- a/docs/layers/network-and-dns/design-decisions/decide-on-transit-gateway-requirements.md +++ b/docs/layers/network-and-dns/design-decisions/decide-on-transit-gateway-requirements.mdx @@ -1,9 +1,10 @@ --- title: "Decide on Transit Gateway Requirements" +sidebar_label: "Transit Gateway Requirements" refarch_id: REFARCH-487 --- - -# Decide on Transit Gateway Requirements +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Context and Problem Statement diff --git a/docs/layers/network-and-dns/design-decisions/decide-on-vanity-branded-domain.md b/docs/layers/network-and-dns/design-decisions/decide-on-vanity-branded-domain.mdx similarity index 95% rename from docs/layers/network-and-dns/design-decisions/decide-on-vanity-branded-domain.md rename to docs/layers/network-and-dns/design-decisions/decide-on-vanity-branded-domain.mdx index b12224de7..689aa12d5 100644 --- a/docs/layers/network-and-dns/design-decisions/decide-on-vanity-branded-domain.md +++ b/docs/layers/network-and-dns/design-decisions/decide-on-vanity-branded-domain.mdx @@ -1,12 +1,12 @@ --- -title: "Decide on Vanity (Branded) Domain" +title: "Decide on Vanity (Branded) Domains" +sidebar_label: "Vanity (Branded) Domains" refarch_id: REFARCH-54 --- - +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; import ReactPlayer from 'react-player' -# Decide on Vanity (Branded) Domain - ## Problem We need a domain that represents your branded domain in the live environment. This will be our synthetic production diff --git a/docs/layers/network-and-dns/design-decisions/decide-on-vpc-nat-strategy.md b/docs/layers/network-and-dns/design-decisions/decide-on-vpc-nat-strategy.mdx similarity index 95% rename from docs/layers/network-and-dns/design-decisions/decide-on-vpc-nat-strategy.md rename to docs/layers/network-and-dns/design-decisions/decide-on-vpc-nat-strategy.mdx index dcdad201d..31503bade 100644 --- a/docs/layers/network-and-dns/design-decisions/decide-on-vpc-nat-strategy.md +++ b/docs/layers/network-and-dns/design-decisions/decide-on-vpc-nat-strategy.mdx @@ -1,9 +1,10 @@ --- title: "Decide on VPC NAT Strategy" +sidebar_label: "VPC NAT Strategy" refarch_id: REFARCH-523 --- - -# Decide on VPC NAT Strategy +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; **DRAFT** diff --git a/docs/layers/network-and-dns/design-decisions/decide-on-vpc-network-traffic-isolation-policy.md b/docs/layers/network-and-dns/design-decisions/decide-on-vpc-network-traffic-isolation-policy.mdx similarity index 92% rename from docs/layers/network-and-dns/design-decisions/decide-on-vpc-network-traffic-isolation-policy.md rename to docs/layers/network-and-dns/design-decisions/decide-on-vpc-network-traffic-isolation-policy.mdx index 7895eacc8..ab61b2f01 100644 --- a/docs/layers/network-and-dns/design-decisions/decide-on-vpc-network-traffic-isolation-policy.md +++ b/docs/layers/network-and-dns/design-decisions/decide-on-vpc-network-traffic-isolation-policy.mdx @@ -1,9 +1,10 @@ --- title: "Decide on VPC Network Traffic Isolation Policy" +sidebar_label: "VPC Network Traffic Isolation Policy" refarch_id: REFARCH-524 --- - -# Decide on VPC Network Traffic Isolation Policy +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Context and Problem Statement diff --git a/docs/layers/network-and-dns/design-decisions/decide-vpc-peering-requirements-e-g-to-legacy-env.md b/docs/layers/network-and-dns/design-decisions/decide-vpc-peering-requirements-e-g-to-legacy-env.mdx similarity index 92% rename from docs/layers/network-and-dns/design-decisions/decide-vpc-peering-requirements-e-g-to-legacy-env.md rename to docs/layers/network-and-dns/design-decisions/decide-vpc-peering-requirements-e-g-to-legacy-env.mdx index a41b463e4..0538d8060 100644 --- a/docs/layers/network-and-dns/design-decisions/decide-vpc-peering-requirements-e-g-to-legacy-env.md +++ b/docs/layers/network-and-dns/design-decisions/decide-vpc-peering-requirements-e-g-to-legacy-env.mdx @@ -1,9 +1,10 @@ --- -title: "Decide VPC Peering Requirements (e.g. to Legacy Env)" +title: "Decide on VPC Peering Requirements (e.g. to Legacy Env)" +sidebar_label: "VPC Peering Requirements" refarch_id: REFARCH-80 --- - -# Decide VPC Peering Requirements (e.g. to Legacy Env) +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Context and Problem Statement diff --git a/docs/layers/network-and-dns/dns-setup.mdx b/docs/layers/network-and-dns/dns-setup.mdx index a39483aa5..a5760fb65 100644 --- a/docs/layers/network-and-dns/dns-setup.mdx +++ b/docs/layers/network-and-dns/dns-setup.mdx @@ -1,20 +1,19 @@ --- -title: "Setup DNS" +title: "Setting up DNS" +sidebar_label: "Setup DNS" sidebar_position: 20 --- - -# Setting up DNS +import Note from '@site/src/components/Note'; +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Requirements Before deploying DNS, first purchase your chosen vanity and service domains in the `core-dns` account or in your chosen registrar. Refer back to the [Decide on Vanity (Branded) Domain](layers/network-and-dns/design-decisions/decide-on-vanity-branded-domain/) and [Decide on Service Discovery Domain](/layers/network-and-dns/design-decisions/decide-on-service-discovery-domain/) design decisions for more information. -When registering a new domain, we have the option of using Route53’s built-in registrar or using an existing registrar. -Many enterprise-scale organizations use MarkMonitor to manage their domain portfolio. Our convention is to use the `dns` -account as the registrar. +When registering a new domain, we have the option of using Route53’s built-in registrar or using an existing registrar. Many enterprise-scale organizations use MarkMonitor to manage their domain portfolio. Our convention is to use the `dns` account as the registrar. -**Note**, the AWS Route53 Registrar cannot be automated with Terraform, so ClickOps is still required for domain -registration. +the AWS Route53 Registrar cannot be automated with Terraform, so ClickOps is still required for domain registration. [Registering domain names using Amazon Route 53 - Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/registrar.html) @@ -24,12 +23,9 @@ ramifications as to IP/trademark defense. ## Deployment The DNS stacks are broken up into primary and delegated deployments. Primary DNS zones only start with an `NS` record -among other defaults and expect the the owner of their associated domain to add these `NS` records to whatever console -manages the respective domain. Consult the component's README (`components/terraform/dns-primary/README.md`) for more -information. +among other defaults and expect the the owner of their associated domain to add these `NS` records to whatever console manages the respective domain. Consult the component's README (`components/terraform/dns-primary/README.md`) for more information. -The delegated DNS zones insert their `NS` records into the primary DNS zone; thus they are mostly automated. Consult the -component's README `components/terraform/dns-delegated/README.md` for more information. +The delegated DNS zones insert their `NS` records into the primary DNS zone; thus they are mostly automated. Consult the component's README `components/terraform/dns-delegated/README.md` for more information. To start the dns setup, run `atmos workflow deploy/dns -f network`. This will go through creating primaries, and then follow up with establishing the delegates. @@ -74,8 +70,7 @@ atmos terraform output dns-primary -s plat-gbl-prod ### ACM -Note that each `dns-primary` component will already create its own ACM certs. These are only for the vanity domains and -won't do the more critical service domain certificates. +Note that each `dns-primary` component will already create its own ACM certs. These are only for the vanity domains and won't do the more critical service domain certificates. We use a separate instance of the `acm` component to provision the service domain certificates, which still rely on the `dns-delegated` component. Setting these up can be done quickly by running `atmos workflow deploy/acm -f network`. diff --git a/docs/layers/network-and-dns/network-and-dns.mdx b/docs/layers/network-and-dns/network-and-dns.mdx index d8408b75a..7f2bf2d1e 100644 --- a/docs/layers/network-and-dns/network-and-dns.mdx +++ b/docs/layers/network-and-dns/network-and-dns.mdx @@ -1,44 +1,35 @@ --- title: "Network and DNS" +sidebar_label: "Network and DNS" sidebar_class_name: hidden --- +import ReactPlayer from "react-player"; +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # Network and DNS -This document is intended to present Cloud Posse's approach to designing Network and DNS architectures. The contents of -this document assume that the reader is familiar with the basics of -[networking and content delivery services in AWS](https://aws.amazon.com/products/networking/). - -import ReactPlayer from "react-player"; +This document is intended to present Cloud Posse's approach to designing Network and DNS architectures. The contents of this document assume that the reader is familiar with the basics of [networking and content delivery services in AWS](https://aws.amazon.com/products/networking/). ## The Problem -There is no single solution for Network and DNS architecture. Ultimately, the right network architecture may come down -to your individual business needs. Yet often too much thought in design leads to snowflake designs that are specific to -a given business but are entirely unique, overly complex, and difficult to maintain. +There is no single solution for Network and DNS architecture. Ultimately, the right network architecture may come down to your individual business needs. Yet often too much thought in design leads to snowflake designs that are specific to a given business but are entirely unique, overly complex, and difficult to maintain. -However, all network designs have a fundamental set of requirements that we can define. All networks need some private -subnets and some public subnets. All networks need to be able to restrict access and enforce boundaries externally and -internally, and finally all networks need some way to discover services inside the network. +However, all network designs have a fundamental set of requirements that we can define. All networks need some private subnets and some public subnets. All networks need to be able to restrict access and enforce boundaries externally and internally, and finally all networks need some way to discover services inside the network. When it comes to DNS, often there is no design consideration for domain management. Companies may have hundreds or -thousands of marketing domains, e.g. for SEO, and yet have no sane method for services to discover each other using DNS. -At the same time, DNS needs some of the same boundaries as the network: services should be isolated and secure. +thousands of marketing domains, e.g. for SEO, and yet have no sane method for services to discover each other using DNS. At the same time, DNS needs some of the same boundaries as the network: services should be isolated and secure. -Furthermore, networking in a cloud environment is entirely software defined. We have the ability to do things that would -be too tedious or too difficult to achieve in physical environments. Companies still largely rely on IPv4 networks, -which have limited IP space, and we need to ensure that how we allocate networks can scale with your business and even -integrate with other third party providers. +Furthermore, networking in a cloud environment is entirely software defined. We have the ability to do things that would be too tedious or too difficult to achieve in physical environments. Companies still largely rely on IPv4 networks, which have limited IP space, and we need to ensure that how we allocate networks can scale with your business and even integrate with other third party providers. Networking and content delivery is far from trivial. There are countless designs and architectures that accomplish similar outcomes. Ultimately our goal is to ensure that whatever we implement will enable your success. ## Our Solution -As with all infrastructure design, Cloud Posse has an opinionated solution. We aim to reduce complexity where possible, -while providing secure and robust networks that are maintainable and scalable. +As with all infrastructure design, Cloud Posse has an opinionated solution. We aim to reduce complexity where possible, while providing secure and robust networks that are maintainable and scalable. We have identified the most common and reusable pattern for network architecture, so that we can define reusable building blocks for a network. We've standardized the definition of a VPC, provided distinction between marketing and @@ -53,9 +44,7 @@ other across the accounts. ### Account Isolation -As a foundational design with the AWS Organization, we have already isolated resources into accounts. This separation -creates a physical boundary between resources in AWS, including VPCs. Therefore, we can deploy a single or multiple VPCs -in an account and guarantee that resources in those subnets will not be able to access resources in other accounts. +As a foundational design with the AWS Organization, we have already isolated resources into accounts. This separation creates a physical boundary between resources in AWS, including VPCs. Therefore, we can deploy a single or multiple VPCs in an account and guarantee that resources in those subnets will not be able to access resources in other accounts. Because of this design, we recommend deploying a single VPC per account (that needs a network). Production resources will only live in the VPC in the `plat-prod` account, and unless connected, no other VPC will be able to access those diff --git a/docs/layers/security-and-compliance/11-compliance.md b/docs/layers/security-and-compliance/11-compliance.mdx similarity index 98% rename from docs/layers/security-and-compliance/11-compliance.md rename to docs/layers/security-and-compliance/11-compliance.mdx index a3705ce17..a9ba01b63 100644 --- a/docs/layers/security-and-compliance/11-compliance.md +++ b/docs/layers/security-and-compliance/11-compliance.mdx @@ -1,4 +1,9 @@ -# Compliance +--- +title: Compliance +sidebar_label: Compliance +--- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; :::caution diff --git a/docs/layers/security-and-compliance/design-decisions/decide-on-infrastructure-software-static-analysis-tools.md b/docs/layers/security-and-compliance/design-decisions/decide-on-infrastructure-software-static-analysis-tools.mdx similarity index 72% rename from docs/layers/security-and-compliance/design-decisions/decide-on-infrastructure-software-static-analysis-tools.md rename to docs/layers/security-and-compliance/design-decisions/decide-on-infrastructure-software-static-analysis-tools.mdx index 90fc45f16..b9cada7e5 100644 --- a/docs/layers/security-and-compliance/design-decisions/decide-on-infrastructure-software-static-analysis-tools.md +++ b/docs/layers/security-and-compliance/design-decisions/decide-on-infrastructure-software-static-analysis-tools.mdx @@ -1,11 +1,11 @@ --- title: "Decide on Infrastructure & Software Static Analysis Tools" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1171620075 +sidebar_label: "Infrastructure & Software Static Analysis Tools" sidebar_position: 100 refarch_id: REFARCH-331 --- - -# Decide on Infrastructure & Software Static Analysis Tools +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Infrastructure Considerations: (terraform, docker) diff --git a/docs/layers/security-and-compliance/design-decisions/decide-on-kubernetes-platform-compliance-strategy.md b/docs/layers/security-and-compliance/design-decisions/decide-on-kubernetes-platform-compliance-strategy.mdx similarity index 82% rename from docs/layers/security-and-compliance/design-decisions/decide-on-kubernetes-platform-compliance-strategy.md rename to docs/layers/security-and-compliance/design-decisions/decide-on-kubernetes-platform-compliance-strategy.mdx index 4a1b08352..181d93fc4 100644 --- a/docs/layers/security-and-compliance/design-decisions/decide-on-kubernetes-platform-compliance-strategy.md +++ b/docs/layers/security-and-compliance/design-decisions/decide-on-kubernetes-platform-compliance-strategy.mdx @@ -1,11 +1,12 @@ --- title: "Decide on Kubernetes Platform Compliance Strategy" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1171980600/REFARCH-343+-++Decide+on+Kubernetes+Platform+Compliance+Strategy +sidebar_label: "Kubernetes Platform Compliance Strategy" sidebar_position: 100 refarch_id: REFARCH-343 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; -# Decide on Kubernetes Platform Compliance Strategy Decide on a strategy for CIS Compliance/hardening on EKS. ## Considerations diff --git a/docs/layers/security-and-compliance/design-decisions/decide-on-log-retention-and-durability-architecture.md b/docs/layers/security-and-compliance/design-decisions/decide-on-log-retention-and-durability-architecture.mdx similarity index 92% rename from docs/layers/security-and-compliance/design-decisions/decide-on-log-retention-and-durability-architecture.md rename to docs/layers/security-and-compliance/design-decisions/decide-on-log-retention-and-durability-architecture.mdx index 1090ba003..0b9f63e34 100644 --- a/docs/layers/security-and-compliance/design-decisions/decide-on-log-retention-and-durability-architecture.md +++ b/docs/layers/security-and-compliance/design-decisions/decide-on-log-retention-and-durability-architecture.mdx @@ -1,18 +1,20 @@ --- title: "Decide on Log Retention and Durability Architecture" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1175978183/REFARCH-355+-+Decide+on+Log+Retention+and+Durability+Architecture +sidebar_label: "Log Retention and Durability Architecture" sidebar_position: 100 refarch_id: REFARCH-355 --- - -# Decide on Log Retention and Durability Architecture +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem + Not all logs were created equal. Some may contain PHI (Protected Health Information) or CHD (Card Holder Data) while others are simply HTTP request logs. Depending on regional jurisdiction (E.g. Europe), there can be other requirements (E.g. [GDPR on AWS](https://docs.aws.amazon.com/whitepapers/latest/navigating-gdpr-compliance/monitoring-and-logging.html)). We need to identify the log destinations to discuss how to handle them. ### Recommendations + - Use 90 days unless the compliance framework stipulates differently (e.g. PCI/DSS) - Use 60 days in the standard S3 storage tier and then transfer to glacier for the last 30 days. @@ -20,6 +22,7 @@ We need to identify the log destinations to discuss how to handle them. ## Considerations ### Which Logs are in Scope? + - **Cloud Trails** (AWS API logs) - **CloudWatch** Logs (platform logs) @@ -37,6 +40,7 @@ We need to identify the log destinations to discuss how to handle them. - **Application logs** (the events emitted from your applications) ### How are logs handled? + For everything in scope, we need to address: - Where should logs be aggregated (e.g. S3 bucket in audit account, datadog)? @@ -56,6 +60,7 @@ For everything in scope, we need to address: - What’s the tolerance for the latency of accessing log events (e.g. can it be hours or needs to be within seconds)? ### References + - [https://docs.aws.amazon.com/whitepapers/latest/navigating-gdpr-compliance/monitoring-and-logging.html](https://docs.aws.amazon.com/whitepapers/latest/navigating-gdpr-compliance/monitoring-and-logging.html) - [https://www.pcidssguide.com/what-are-the-pci-dss-log-retention-requirements/](https://www.pcidssguide.com/what-are-the-pci-dss-log-retention-requirements/) diff --git a/docs/layers/security-and-compliance/design-decisions/decide-on-strategy-for-hardened-base-amis.md b/docs/layers/security-and-compliance/design-decisions/decide-on-strategy-for-hardened-base-amis.mdx similarity index 96% rename from docs/layers/security-and-compliance/design-decisions/decide-on-strategy-for-hardened-base-amis.md rename to docs/layers/security-and-compliance/design-decisions/decide-on-strategy-for-hardened-base-amis.mdx index cc180ff0d..e088e612c 100644 --- a/docs/layers/security-and-compliance/design-decisions/decide-on-strategy-for-hardened-base-amis.md +++ b/docs/layers/security-and-compliance/design-decisions/decide-on-strategy-for-hardened-base-amis.mdx @@ -1,13 +1,14 @@ --- title: "Decide on Strategy for Hardened Base AMIs" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1171980616/REFARCH-345+-+Decide+on+Strategy+for+Hardened+Base+AMIs +sidebar_label: "Strategy for Hardened Base AMIs" sidebar_position: 100 refarch_id: REFARCH-345 --- - -# Decide on Strategy for Hardened Base AMIs +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem + When critical CVEs come out, they should be promptly remediated. If we rely strictly on upstream AMIs, we have little control over the time to remediate as we’re dependent on third parties to remediate the vulnerabilities and their failure to do so will jeopardize our ability to meet commitments. Many compliance frameworks require host-level hardening and the ability to demonstrate something along the lines of [https://www.cisecurity.org/controls/continuous-vulnerability-management/](https://www.cisecurity.org/controls/continuous-vulnerability-management/). Laws, regulations, standards, or contractual agreements may require an even higher priority or shorter timeline for remediation. For example, to comply with the [Payment Card Industry Data Security Standard (PCI DSS)](https://www.pcisecuritystandards.org/document_library), vulnerabilities in any PCI environment: @@ -19,6 +20,7 @@ Many compliance frameworks require host-level hardening and the ability to demon See [Decide on Technical Benchmark Framework](/reference-architecture/fundamentals/design-decisions/foundational-benchmark-compliance/decide-on-technical-benchmark-framework) ## Solution + We need a solution that covers both EKS (for customers using it) and for standalone EC2 instances where applicable. Additionally, regardless of the solution, we’ll also need to instrument the process for rolling out the changes. See [How to Enable Spacelift Drift Detection](/reference-architecture/how-to-guides/integrations/spacelift/how-to-enable-spacelift-drift-detection) for a nice way to automatically update AMIs using data sources. ### Use CIS or Not? @@ -26,6 +28,7 @@ We need a solution that covers both EKS (for customers using it) and for standal > CIS benchmarks are internationally recognized as security standards for defending IT systems and data against cyberattacks. Used by thousands of businesses, they offer prescriptive guidance for establishing a secure baseline configuration.The CIS Foundation is the most recognized industry standard for hardening OS images, however, they have not yet published the CIS standard for container-optimized OS. The traditional CIS benchmarks are for full-blown OSs with a different set of concerns that do not apply to a container-optimized OS. What CIS has defined are [the best practices for hardening EKS as a platform](https://aws.amazon.com/de/blogs/containers/introducing-cis-amazon-eks-benchmark/) and that standard is covered by `kube-bench`. So by running `kube-bench` on a cluster we would be able to validate if Bottlerocket meets the CIS standard for nodes managed by Kubernetes. While this is not the same as "certification", it might be good enough for benchmark compliance. ### Use Existing Hardened Image + - AWS does not provide turnkey CIS-compliant base AMIs (third-party vendors only). - Bottlerocket is more secure but is still not _technically_ CIS-compliant out of the box @@ -38,6 +41,7 @@ We need a solution that covers both EKS (for customers using it) and for standal - [CIS provides marketplace images](https://aws.amazon.com/marketplace/seller-profile?id=dfa1e6a8-0b7b-4d35-a59c-ce272caee4fc), but these add $0.02/hour. ### DIY Hardened Images + - Build our own AMIs based on something like Bottlerocket or Amazon Linux and do our own hardening. - Any hardening we do would necessitate the implementation of the packer configurations and pipelines for managing it. @@ -45,9 +49,11 @@ We need a solution that covers both EKS (for customers using it) and for standal - Create GitHub Action pipeline to build packer images and distribute them to enabled regions ### Cloud-Init Patching + With `cloud-init` we can patch the system at runtime. This has the benefit of not requiring us to manage any complicated factory for building AMIs for multiple regions but violates the principle of immutable infrastructure. ### AWS Systems Manager Patch Manager + With AWS Systems Manager can apply patch documents to running systems based on policies, but violates the principle of immutable infrastructure. diff --git a/docs/layers/security-and-compliance/design-decisions/decide-on-technical-benchmark-framework.md b/docs/layers/security-and-compliance/design-decisions/decide-on-technical-benchmark-framework.mdx similarity index 85% rename from docs/layers/security-and-compliance/design-decisions/decide-on-technical-benchmark-framework.md rename to docs/layers/security-and-compliance/design-decisions/decide-on-technical-benchmark-framework.mdx index 15c194c4a..4b400dc35 100644 --- a/docs/layers/security-and-compliance/design-decisions/decide-on-technical-benchmark-framework.md +++ b/docs/layers/security-and-compliance/design-decisions/decide-on-technical-benchmark-framework.mdx @@ -1,11 +1,11 @@ --- title: "Decide on Technical Benchmark Framework" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1171620109/REFARCH-470+-+Decide+on+Technical+Benchmark+Framework +sidebar_label: "Technical Benchmark Framework" sidebar_position: 100 refarch_id: REFARCH-470 --- - -# Decide on Technical Benchmark Framework +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Benchmark Considerations diff --git a/docs/layers/security-and-compliance/design-decisions/decide-on-waf-requirements-strategy.md b/docs/layers/security-and-compliance/design-decisions/decide-on-waf-requirements-strategy.mdx similarity index 92% rename from docs/layers/security-and-compliance/design-decisions/decide-on-waf-requirements-strategy.md rename to docs/layers/security-and-compliance/design-decisions/decide-on-waf-requirements-strategy.mdx index 838d352aa..c5bf9f7c2 100644 --- a/docs/layers/security-and-compliance/design-decisions/decide-on-waf-requirements-strategy.md +++ b/docs/layers/security-and-compliance/design-decisions/decide-on-waf-requirements-strategy.mdx @@ -1,13 +1,14 @@ --- title: "Decide on WAF Requirements/Strategy" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1176010839 +sidebar_label: "WAF Requirements/Strategy" sidebar_position: 100 refarch_id: REFARCH-384 --- - -# Decide on WAF Requirements/Strategy +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem + ALBs have very limited capabilities to fend off attacks by themselves. Using Security Groups is not a scalable solution. [The number of inbound/outbound rules is limited to a max of 120 (60 ea)](https://docs.aws.amazon.com/vpc/latest/userguide/amazon-vpc-limits.html#vpc-limits-security-groups). To thwart any sort of Denial of Service (DoS) attack, more tools are required. Moreover, not all attacks are as easily identified as DoS attacks. Other threat vectors include SQL injection, XSS, etc. The older your applications, the more external dependencies you have, the greater the attack surface area. ## Solution diff --git a/docs/layers/security-and-compliance/security-and-compliance.mdx b/docs/layers/security-and-compliance/security-and-compliance.mdx index a1173c4cf..db79bd9e8 100644 --- a/docs/layers/security-and-compliance/security-and-compliance.mdx +++ b/docs/layers/security-and-compliance/security-and-compliance.mdx @@ -1,6 +1,7 @@ --- title: "Security and Compliance" +sidebar_label: "Security and Compliance" sidebar_class_name: hidden --- - -# Security and Compliance +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; diff --git a/docs/layers/security-and-compliance/tutorials/enable-guardduty-for-eks-protection.md b/docs/layers/security-and-compliance/tutorials/enable-guardduty-for-eks-protection.mdx similarity index 60% rename from docs/layers/security-and-compliance/tutorials/enable-guardduty-for-eks-protection.md rename to docs/layers/security-and-compliance/tutorials/enable-guardduty-for-eks-protection.mdx index 98a12a94b..d30ffba85 100644 --- a/docs/layers/security-and-compliance/tutorials/enable-guardduty-for-eks-protection.md +++ b/docs/layers/security-and-compliance/tutorials/enable-guardduty-for-eks-protection.mdx @@ -1,16 +1,18 @@ --- -title: "GuardDuty for EKS" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1265893397/REFARCH-516+-+Enable+GuardDuty+for+EKS+Protection +title: "Enable GuardDuty for EKS Protection" +sidebar_label: "GuardDuty for EKS" sidebar_position: 100 refarch_id: REFARCH-516 --- - -# Enable GuardDuty for EKS Protection +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem -The new feature, GuardDuty for EKS Protection expands coverage to continuously monitor and profile Amazon Elastic Kubernetes Service (EKS) workload activity to identify malicious or suspicious behavior representing potential threats to container workloads. + +The new feature, GuardDuty for EKS Protection, expands coverage to continuously monitor and profile Amazon Elastic Kubernetes Service (EKS) workload activity to identify malicious or suspicious behavior representing potential threats to container workloads. ## Solution + Enable GuardDuty for EKS Protection in the `security` account via click ops. :::tip diff --git a/docs/layers/spacelift/03-spacelift.md b/docs/layers/spacelift/03-spacelift.mdx similarity index 97% rename from docs/layers/spacelift/03-spacelift.md rename to docs/layers/spacelift/03-spacelift.mdx index 801835ab9..c5e8d22a2 100644 --- a/docs/layers/spacelift/03-spacelift.md +++ b/docs/layers/spacelift/03-spacelift.mdx @@ -1,4 +1,10 @@ -# Spacelift +--- +title: Spacelift +sidebar_label: Spacelift +description: Spacelift is a continuous delivery platform that allows you to automate your Terraform workflows. +--- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Quick Start diff --git a/docs/layers/spacelift/design-decisions/decide-on-how-spacelift-will-use-external-private-modules.md b/docs/layers/spacelift/design-decisions/decide-on-how-spacelift-will-use-external-private-modules.mdx similarity index 94% rename from docs/layers/spacelift/design-decisions/decide-on-how-spacelift-will-use-external-private-modules.md rename to docs/layers/spacelift/design-decisions/decide-on-how-spacelift-will-use-external-private-modules.mdx index 38c523bb8..6f4505d0f 100644 --- a/docs/layers/spacelift/design-decisions/decide-on-how-spacelift-will-use-external-private-modules.md +++ b/docs/layers/spacelift/design-decisions/decide-on-how-spacelift-will-use-external-private-modules.mdx @@ -1,11 +1,12 @@ --- title: "Decide on how Spacelift will use external private modules" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1365737481/REFARCH-535+-+Decide+on+how+Spacelift+will+use+external+private+modules +sidebar_label: "Spacelift with external private modules" sidebar_position: 100 refarch_id: REFARCH-535 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; -# Decide on how Spacelift will use external private modules **Date**: **19 Oct 2021** ## Status diff --git a/docs/layers/spacelift/design-decisions/decide-on-spacelift-administrative-stack-auto-deployment.md b/docs/layers/spacelift/design-decisions/decide-on-spacelift-administrative-stack-auto-deployment.mdx similarity index 94% rename from docs/layers/spacelift/design-decisions/decide-on-spacelift-administrative-stack-auto-deployment.md rename to docs/layers/spacelift/design-decisions/decide-on-spacelift-administrative-stack-auto-deployment.mdx index 19819e6df..fc3ca4b0c 100644 --- a/docs/layers/spacelift/design-decisions/decide-on-spacelift-administrative-stack-auto-deployment.md +++ b/docs/layers/spacelift/design-decisions/decide-on-spacelift-administrative-stack-auto-deployment.mdx @@ -1,18 +1,20 @@ --- title: "Decide on Spacelift Administrative Stack Auto-deployment" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1171980545/REFARCH-410+-+Decide+on+Spacelift+Administrative+Stack+Auto-deployment +sidebar_label: "Spacelift Administrative Stack Auto-deployment" sidebar_position: 100 refarch_id: REFARCH-410 --- - -# Decide on Spacelift Administrative Stack Auto-deployment +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem + Spacelift (and for that matter, pretty much any CI/CD platform including Atlantis) will only run workflows that have been configured to run on the platform (e.g. there is no auto-discovery of stacks). While systems like GitHub Actions will automatically run workflows in a branch or Pull Request from any repo, Spacelift by design does not do this for security reasons, since that would mean any rogue repo or branch could modify infrastructure. In order for the stack to run in spacelift, the configuration needs to be merged into `main` and confirmed (e.g. applied). Frequently, users forget about this, so after merging to main the infrastructure stack is not confirmed and then they are left scratching their heads why their stack didn’t run. ## Context + There are 2 kinds of Spacelift stacks: administrative stacks and component stacks (which are created by an admin stack). The “infrastructure” stack is an _administrative stack_ that deploys and manages component stacks. This means this stack has special permissions to manage spacelift itself, but actually no credentials to manage AWS (or other services). In the screenshot, you can see that the stack is _Administrative_ on the status line under Resources. diff --git a/docs/layers/spacelift/design-decisions/decide-on-spacelift-worker-pool-architecture.md b/docs/layers/spacelift/design-decisions/decide-on-spacelift-worker-pool-architecture.mdx similarity index 94% rename from docs/layers/spacelift/design-decisions/decide-on-spacelift-worker-pool-architecture.md rename to docs/layers/spacelift/design-decisions/decide-on-spacelift-worker-pool-architecture.mdx index 84fbbf5f0..114287665 100644 --- a/docs/layers/spacelift/design-decisions/decide-on-spacelift-worker-pool-architecture.md +++ b/docs/layers/spacelift/design-decisions/decide-on-spacelift-worker-pool-architecture.mdx @@ -1,16 +1,18 @@ --- title: "Decide on Spacelift Worker Pool Architecture" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1182597207/REFARCH-475+-+Decide+on+Spacelift+Worker+Pool+Architecture +sidebar_label: "Spacelift Worker Pool Architecture" sidebar_position: 100 refarch_id: REFARCH-475 --- - -# Decide on Spacelift Worker Pool Architecture +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem + In order to provision infrastructure, we need to sufficient IAM permissions (e.g. Service Accounts) for Terraform to modify infrastructure. If we give it too much power, very bad things can happen; if we don’t give it enough, then we have no way to run automation in an unattended fashion. In an ideal world, Spacelift would use the credentials of the person making the changes, but that is not the case and this is not a problem unique to Spacelift (e.g. Terraform Cloud, Atlantis, all work this way). Instead, Terraform runs with the permissions granted to the Spacelift runners and we use Rego policies to control what a user can or cannot do. ## Context + Spacelift can use workers run Terraform inside your VPCs much like GitHub Action runners. These workers are then provisioned with IAM service account profiles that determine what Spacelift can or cannot do. :::caution diff --git a/docs/layers/spacelift/spacelift.mdx b/docs/layers/spacelift/spacelift.mdx index ea3c81356..fee70f3bc 100644 --- a/docs/layers/spacelift/spacelift.mdx +++ b/docs/layers/spacelift/spacelift.mdx @@ -4,6 +4,8 @@ sidebar_class_name: hidden tags: - spacelift --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # TODO diff --git a/docs/layers/spacelift/tutorials/how-to-destroy-a-component-using-atmos-or-spacelift.md b/docs/layers/spacelift/tutorials/how-to-destroy-a-component-using-atmos-or-spacelift.mdx similarity index 98% rename from docs/layers/spacelift/tutorials/how-to-destroy-a-component-using-atmos-or-spacelift.md rename to docs/layers/spacelift/tutorials/how-to-destroy-a-component-using-atmos-or-spacelift.mdx index a7d4427f8..884d86799 100644 --- a/docs/layers/spacelift/tutorials/how-to-destroy-a-component-using-atmos-or-spacelift.md +++ b/docs/layers/spacelift/tutorials/how-to-destroy-a-component-using-atmos-or-spacelift.mdx @@ -1,12 +1,13 @@ --- -title: "Destroy a Component" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1245020165/How+to+Destroy+a+Component+using+%60atmos%60+or+Spacelift +title: "How to Destroy a Component using `atmos` or Spacelift" +sidebar_label: "Destroy a Component" sidebar_position: 100 --- - -# How to Destroy a Component using `atmos` or Spacelift +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem + You want to destroy a component that was provisioned with terraform (i.e. its is no longer needed or for development purposes want to destroy and recreate it). There are a few different ways to destroy a component in a stack using `atmos` or Spacelift, depending on what you want to achieve. It’s important to understand the tradeoffs and why there isn’t just one way of doing it. diff --git a/docs/layers/spacelift/tutorials/how-to-develop-with-spacelift-and-atmos.md b/docs/layers/spacelift/tutorials/how-to-develop-with-spacelift-and-atmos.mdx similarity index 96% rename from docs/layers/spacelift/tutorials/how-to-develop-with-spacelift-and-atmos.md rename to docs/layers/spacelift/tutorials/how-to-develop-with-spacelift-and-atmos.mdx index bd2c8e7fe..f8ce24eb7 100644 --- a/docs/layers/spacelift/tutorials/how-to-develop-with-spacelift-and-atmos.md +++ b/docs/layers/spacelift/tutorials/how-to-develop-with-spacelift-and-atmos.mdx @@ -1,12 +1,13 @@ --- -title: "Develop with Atmos" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1176010979/How+to+Develop+with+Spacelift+and+Atmos +title: "How to Develop with Spacelift and Atmos" +sidebar_label: "Develop with Spacelift" sidebar_position: 100 --- - -# How to Develop with Spacelift and Atmos +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem + - Spacelift is great for day-2 operations, such as making changes to existing components and changing settings, but it’s not so great for the execution of workflow needed to bring up an entire stack or modify lots of components within a single Pull Request. - Atmos is very convenient for development but doesn’t provide the team collaboration benefits, policy controls, audit trails & accounting that we get when we use Spacelift diff --git a/docs/layers/spacelift/tutorials/how-to-enable-spacelift-drift-detection.md b/docs/layers/spacelift/tutorials/how-to-enable-spacelift-drift-detection.mdx similarity index 92% rename from docs/layers/spacelift/tutorials/how-to-enable-spacelift-drift-detection.md rename to docs/layers/spacelift/tutorials/how-to-enable-spacelift-drift-detection.mdx index 5d948e52e..065ff8a3d 100644 --- a/docs/layers/spacelift/tutorials/how-to-enable-spacelift-drift-detection.md +++ b/docs/layers/spacelift/tutorials/how-to-enable-spacelift-drift-detection.mdx @@ -1,10 +1,10 @@ --- -title: "Drift Detection" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1184301057/How+to+Enable+Spacelift+Drift+Detection +title: "How to Enable Spacelift Drift Detection" +sidebar_label: "Drift Detection" sidebar_position: 100 --- - -# How to Enable Spacelift Drift Detection +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem diff --git a/docs/layers/spacelift/tutorials/how-to-manage-explicit-component-dependencies-with-spacelift.md b/docs/layers/spacelift/tutorials/how-to-manage-explicit-component-dependencies-with-spacelift.mdx similarity index 90% rename from docs/layers/spacelift/tutorials/how-to-manage-explicit-component-dependencies-with-spacelift.md rename to docs/layers/spacelift/tutorials/how-to-manage-explicit-component-dependencies-with-spacelift.mdx index 5f81b631a..1edf5dc90 100644 --- a/docs/layers/spacelift/tutorials/how-to-manage-explicit-component-dependencies-with-spacelift.md +++ b/docs/layers/spacelift/tutorials/how-to-manage-explicit-component-dependencies-with-spacelift.mdx @@ -1,10 +1,10 @@ --- -title: "Component Dependencies" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1191313474/How+to+Manage+Explicit+Component+Dependencies+with+Spacelift +title: "How to Manage Explicit Component Dependencies with Spacelift" +sidebar_label: "Component Dependencies" sidebar_position: 100 --- - -# How to Manage Explicit Component Dependencies with Spacelift +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem @@ -17,8 +17,8 @@ Use labels in Spacelift to define the dependencies between components ::: -:::info -NOTE: Our spacelift module will automatically derive dependencies based on `imports` , which means that and stack configuration (E.g. in `catalog/*`) that is imported by any other stack configuration, is now an implicit (or derived) dependency of that stack. So that means that when that upstream file that is imported is modified, it will also trigger an plan of any stack that imports it. +:::note +Our spacelift module will automatically derive dependencies based on `imports` , which means that and stack configuration (E.g. in `catalog/*`) that is imported by any other stack configuration, is now an implicit (or derived) dependency of that stack. So that means that when that upstream file that is imported is modified, it will also trigger an plan of any stack that imports it. - For example, if you modify `globals.yaml`, since that file is imported by every single stack, it will trigger every single stack to plan. @@ -32,8 +32,7 @@ The Rego policy is defined here [https://github.com/cloudposse/terraform-spaceli For details, see PR that implemented it [https://github.com/cloudposse/terraform-provider-utils/pull/43](https://github.com/cloudposse/terraform-provider-utils/pull/43)) -:::caution -**Processing** **Dependencies** +:::caution Processing Dependencies Spacelift can only operate on dependency relationships within a single commit. There’s no way to express a dependency relationship for what should happen between multiple commits, e.g. multiple Pull Requests are merged around the same time and requiring components in one stack be applied before other stacks is not possible. diff --git a/docs/layers/spacelift/tutorials/how-to-scale-spacelift-runners.md b/docs/layers/spacelift/tutorials/how-to-scale-spacelift-runners.mdx similarity index 97% rename from docs/layers/spacelift/tutorials/how-to-scale-spacelift-runners.md rename to docs/layers/spacelift/tutorials/how-to-scale-spacelift-runners.mdx index 7cf7ce809..d38ef8226 100644 --- a/docs/layers/spacelift/tutorials/how-to-scale-spacelift-runners.md +++ b/docs/layers/spacelift/tutorials/how-to-scale-spacelift-runners.mdx @@ -1,12 +1,13 @@ --- -title: "Scale Spacelift Runners" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1249050678/How+to+Scale+Spacelift+Runners +title: "How to Scale Spacelift Runners" +sidebar_label: "Scale Spacelift Runners" sidebar_position: 100 --- - -# How to Scale Spacelift Runners +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem + There are hundreds or thousands of proposed runs pending in Spacelift. Autoscaling will eventually scale up to handle capacity, but want faster turn around time. ## Solution diff --git a/docs/layers/spacelift/tutorials/how-to-sign-up.md b/docs/layers/spacelift/tutorials/how-to-sign-up.mdx similarity index 98% rename from docs/layers/spacelift/tutorials/how-to-sign-up.md rename to docs/layers/spacelift/tutorials/how-to-sign-up.mdx index aed77cf44..c891b9c4d 100644 --- a/docs/layers/spacelift/tutorials/how-to-sign-up.md +++ b/docs/layers/spacelift/tutorials/how-to-sign-up.mdx @@ -1,12 +1,13 @@ --- title: "How to Sign Up" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1185382459/How+to+Sign+Up+for+Spacelift +sidebar_label: "How to Sign Up for Spacelift" sidebar_position: 0 --- - -# How to Sign Up for Spacelift +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem + You’ve been asked to signup for the Spacelift service and you’re not sure which plan to choose or where to go next. You have questions on pricing and want to better understand your options. You already use GitHub Actions, or some other CI/CD platform and want to understand why you need yet another platform. ## Solution @@ -17,9 +18,11 @@ Signup for any trial Spacelift account and it will automatically be enabled as a ::: ### Why do we need Spacelift? + See [Use Spacelift for GitOps with Terraform](/reference-architecture/reference/adrs/use-spacelift-for-gitops-with-terraform) to learn why. ### Why do we need an Enterprise Agreement? + For Cloud Posse engagements, you’ll need to have the **Enterprise-tier** agreement which enables these features. - **“Self-hosted private worker pools”** which will execute `terraform plan/apply` on the EC2 instances that we provision and control, not on the Spacelift cloud -- better, or required in many cases, for security and compliance. @@ -150,7 +153,7 @@ Sign up for Spacelift after the cold start components and `vpc` component have b 9. Finally, click `Create Policy` -``` +```rego package spacelift # See https://docs.spacelift.io/concepts/policy/login-policy for implementation details. # Note: Login policies don't affect GitHub organization or SSO admins. diff --git a/docs/layers/spacelift/tutorials/how-to-use-multiple-infrastructure-repositories-with-spacelift.md b/docs/layers/spacelift/tutorials/how-to-use-multiple-infrastructure-repositories-with-spacelift.mdx similarity index 89% rename from docs/layers/spacelift/tutorials/how-to-use-multiple-infrastructure-repositories-with-spacelift.md rename to docs/layers/spacelift/tutorials/how-to-use-multiple-infrastructure-repositories-with-spacelift.mdx index dc3fd83dd..12c439e94 100644 --- a/docs/layers/spacelift/tutorials/how-to-use-multiple-infrastructure-repositories-with-spacelift.md +++ b/docs/layers/spacelift/tutorials/how-to-use-multiple-infrastructure-repositories-with-spacelift.mdx @@ -1,10 +1,10 @@ --- -title: "Multiple Infrastructure Repositories" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1182367758 +title: "How to Use Multiple Infrastructure Repositories with Spacelift" +sidebar_label: "Multiple Infrastructure Repositories" sidebar_position: 100 --- - -# How to Use Multiple Infrastructure Repositories with Spacelift +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem @@ -25,7 +25,7 @@ This strategy is useful in combination with deploying infrastructure code for en In the following snippet, we’re deploying a component named `snowflake` defined in the `snowflake` repository under the `terraform` folder from the `main` branch. -``` +```yaml components: terraform: snowflake: diff --git a/docs/layers/spacelift/tutorials/how-to-use-spacectl.md b/docs/layers/spacelift/tutorials/how-to-use-spacectl.mdx similarity index 87% rename from docs/layers/spacelift/tutorials/how-to-use-spacectl.md rename to docs/layers/spacelift/tutorials/how-to-use-spacectl.mdx index e1c2a119f..3a5c2b3e6 100644 --- a/docs/layers/spacelift/tutorials/how-to-use-spacectl.md +++ b/docs/layers/spacelift/tutorials/how-to-use-spacectl.mdx @@ -1,12 +1,13 @@ --- -title: "Spacectl" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1261601332/How+to+use+Spacectl +title: "How to use Spacectl" +sidebar_label: "Spacectl" sidebar_position: 100 --- - -# How to use Spacectl +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Problem + You have many stacks that you need to manipulate in some way that the Spacelift Web UI doesn’t support or makes very cumbersome to do one by one. For example, maybe the stacks are pointing to the wrong `HEAD` commit. You need to get some data out of Spacelift for reporting purposes. @@ -24,13 +25,13 @@ See docs [https://github.com/spaceone-dev/spacectl](https://github.com/spaceone- ### Install -``` +```shell ⨠ apt install -y spacectl -qq ``` ### Setup a profile -``` +```shell ⨠ spacectl profile login acme Enter Spacelift endpoint (eg. https://unicorn.app.spacelift.io/): https://acme.app.spacelift.io Select credentials type: 1 for API key, 2 for GitHub access token: 1 @@ -40,13 +41,13 @@ Enter API key secret: ### Listing stacks -``` +```shell spacectl stack list ``` Grab all the stack ids (use the JSON output to avoid bad chars) -``` +```shell spacectl stack list --output json | jq -r '.[].id' > stacks.txt ``` @@ -56,7 +57,7 @@ If the latest commit for each stack is desired, run something like this. NOTE: remove the `echo` to remove the dry-run functionality -``` +```shell cat stacks.txt | while read stack; do echo $stack && echo spacectl stack set-current-commit --sha snip --id $stack; done diff --git a/docs/learn/.gitkeep b/docs/learn/.gitkeep deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/learn/cloudposse-mindset/cloudposse-mindset.mdx b/docs/learn/cloudposse-mindset/cloudposse-mindset.mdx index 3485cc6a1..da198965c 100644 --- a/docs/learn/cloudposse-mindset/cloudposse-mindset.mdx +++ b/docs/learn/cloudposse-mindset/cloudposse-mindset.mdx @@ -1,7 +1,6 @@ --- id: cloudposse-mindset -title: "Cloud Posse Mindset" +title: "Understanding the Cloud Posse Mindset" +sidebar_label: "Cloud Posse Mindset" sidebar_position: 1 --- - -# Understanding the Cloud Posse Mindset diff --git a/docs/learn/index.md b/docs/learn/index.mdx similarity index 78% rename from docs/learn/index.md rename to docs/learn/index.mdx index ab27ce71f..e763632ad 100644 --- a/docs/learn/index.md +++ b/docs/learn/index.mdx @@ -3,18 +3,20 @@ title: "Reference Architecture Overview" sidebar_position: 2 sidebar_label: "Reference Architecture" --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; -# Reference Architecture Overview + +This is Cloud Posse's commercial implementation of a Reference Architecture using [Atmos](https://atmos.tools) together with the vast ecosystem of Cloud Posse modules following our SweetOps methodology. + -This is the documentation corresponding to our proprietary _Reference Architecture_. Every engagement is derived from this project plan and tailored to the customer’s needs. This space is an resource to document and share knowledge for working with this reference architecture. While we intend for portions of this documentation to make their way into [our public documentation](https://github.com/cloudposse/docs), we need to be able to share information in a timely manner with all of our customers. Please respect our [Code of Conduct](/reference-architecture/reference/code-of-conduct). +SweetOps is a methodology for building modern, secure infrastructure on top of Amazon Web Services (AWS) backed entirely by Infrastructure as Code. It provides a toolset, library of reusable Infrastructure as Code (IaC), and opinionated patterns to help you bootstrap robust cloud-native architectures. Built-in an Open Source first fashion by [Cloud Posse](https://cloudposse.com/) together with our customers, it is utilized by many high stakes startups to ensure their cloud infrastructure is an advantage instead of a liability. -Have an issue? Make sure to check out our [Troubleshooting](/reference-architecture/reference/troubleshooting) guide for fixes to common issues. - -## What is our Reference Architecture? +In short, SweetOps makes working in the DevOps world _**Sweeeeet!**_ -This is our commercial implementation of a Reference Architecture using the vast ecosystem of Cloud Posse modules following our SweetOps methodology. SweetOps is a methodology for building modern, secure infrastructure on top of Amazon Web Services (AWS) backed entirely by Infrastructure as Code. It provides a toolset, library of reusable Infrastructure as Code (IaC), and opinionated patterns to help you bootstrap robust cloud-native architectures. Built-in an Open Source first fashion by [Cloud Posse](https://cloudposse.com/) together with our customers, it is utilized by many high stakes startups to ensure their cloud infrastructure is an advantage instead of a liability. +This is the documentation corresponding to our proprietary _Reference Architecture_. Every engagement is derived from this project plan and tailored to the customer’s needs. This space is an resource to document and share knowledge for working with this reference architecture. Please respect our [Code of Conduct](/reference-architecture/reference/code-of-conduct). -In short, SweetOps makes working in the DevOps world _**Sweeeeet!**_ +Have an issue? Make sure to check out our [Troubleshooting](/reference-architecture/reference/troubleshooting) guide for fixes to common issues. ## Who is this documentation for? diff --git a/docs/learn/jumpstart/support.md b/docs/learn/jumpstart/support.mdx similarity index 96% rename from docs/learn/jumpstart/support.md rename to docs/learn/jumpstart/support.mdx index 81d5133e7..5db54de69 100644 --- a/docs/learn/jumpstart/support.md +++ b/docs/learn/jumpstart/support.mdx @@ -1,11 +1,9 @@ --- title: "Support" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1175847876/Support +sidebar_label: "Support" sidebar_position: 90 -custom_edit_url: https://github.com/cloudposse/refarch-scaffold/tree/main/docs/docs/support.md --- -# Support Here are the best ways to get support. ## Paid Support diff --git a/docs/learn/jumpstart/how-to-provision-shared-slack-channels.md b/docs/learn/jumpstart/tutorials/how-to-provision-shared-slack-channels.mdx similarity index 81% rename from docs/learn/jumpstart/how-to-provision-shared-slack-channels.md rename to docs/learn/jumpstart/tutorials/how-to-provision-shared-slack-channels.mdx index 38684dbf4..34c2a0905 100644 --- a/docs/learn/jumpstart/how-to-provision-shared-slack-channels.md +++ b/docs/learn/jumpstart/tutorials/how-to-provision-shared-slack-channels.mdx @@ -1,15 +1,14 @@ --- -title: "Shared Slack Channels" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1170636836/How+to+Provision+Shared+Slack+Channels +title: "How to Provision Shared Slack Channels" +sidebar_label: "Shared Slack Channels" sidebar_position: 100 -custom_edit_url: https://github.com/cloudposse/refarch-scaffold/tree/main/docs/docs/how-to-guides/integrations/how-to-provision-shared-slack-channels.md --- - -# How to Provision Shared Slack Channels +import Note from '@site/src/components/Note' +import Intro from '@site/src/components/Intro' ## Problem -Collaborating effectively between teams requires rapid back and forth communication. Email threads grow unwieldy and adding members to threads so they get all the context is difficult. Email as a medium is in general more insecure (e.g. more easily susceptible to phishing attacks). Email forums are for long-form communication, not the sort we’re accustomed to when needing to get quick answers. +Collaborating effectively between teams requires rapid back-and-forth communication. Email threads grow unwieldy and adding members to threads so they get all the context is difficult. Email as a medium is in general more insecure (e.g. more easily susceptible to phishing attacks). Email forums are for long-form communication, not the sort we’re accustomed to when needing to get quick answers. ## Solution @@ -27,7 +26,7 @@ The official Slack Connect documentation: [https://slack.com/help/articles/11500 2. Give it a name, usually of the partner, customer or vendor, followed by `-general` since there may be future channels shared down the road. After clicking the “share outside ...” checkbox, the title of the dialg changes to “Slack Connect” which what Slack calls shared channels. -**NOTE**: all members can rename the channel on their end without affecting the local name of the channel. This means you should name the channel following your organization’s conventions. +all members can rename the channel on their end without affecting the local name of the channel. This means you should name the channel following your organization’s conventions.
diff --git a/docs/resources/offboarding-cloudposse.md b/docs/learn/jumpstart/tutorials/offboarding-cloudposse.mdx similarity index 91% rename from docs/resources/offboarding-cloudposse.md rename to docs/learn/jumpstart/tutorials/offboarding-cloudposse.mdx index d27dd8680..f5da2ecb2 100644 --- a/docs/resources/offboarding-cloudposse.md +++ b/docs/learn/jumpstart/tutorials/offboarding-cloudposse.mdx @@ -1,14 +1,11 @@ --- title: "Offboarding Cloud Posse" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1267990561/Offboarding+Cloud+Posse +sidebar_label: "Offboarding Cloud Posse" sidebar_position: 100 -custom_edit_url: https://github.com/cloudposse/refarch-scaffold/tree/main/docs/docs/reference/offboarding-cloudposse.md --- -# Offboarding Cloud Posse - ### Problem -- Your company is ready to take over all operations and needs to restrict Cloud Posse’s access to mission-critical environments for regulatory compliance (e.g. for HIPAA compliance). +- Your company is ready to take over all operations and needs to restrict Cloud Posse’s access to mission-critical environments for regulatory compliance (e.g. for HIPAA compliance). - Your engagement with Cloud Posse is coming to an end and you need to shut down entirely Cloud Posse’s access to all environments or you are pausing the engagement @@ -16,7 +13,7 @@ custom_edit_url: https://github.com/cloudposse/refarch-scaffold/tree/main/docs/d ## Solution -### AWS +### AWS #### **Option 1:** Restrict Federated IAM Access to Some Accounts @@ -32,7 +29,7 @@ After disabling all Federated IAM access, you have the option to issue Cloud Pos #### **Option 4**: Issue IAM User Accounts :::caution -We strongly discourage this approach as it’s generally an anti-pattern to bypass SSO and introduces new requirements for offboarding team members. +We strongly discourage this approach as it’s generally an anti-pattern to bypass SSO and introduces new requirements for offboarding team members. ::: @@ -79,8 +76,8 @@ We recommend keeping open channels of communication between our teams. That way All customer channels are managed via Slack Connect. Some channels may be owned by your team, others by our team. If you desire to close the connection, ask your Slack administrator to remove our organization from the slack connection. -See: -- [Removing Orgs from Slack Connect](https://slack.com/help/articles/360026489273-Remove-organizations-from-a-Slack-Connect-channel-) +See: +- [Removing Orgs from Slack Connect](https://slack.com/help/articles/360026489273-Remove-organizations-from-a-Slack-Connect-channel-) - [Removing external members from channels](https://slack.com/help/articles/5682545991443-Slack-Connect--Manage-external-people-#remove-external-people) ### Datadog @@ -97,9 +94,9 @@ Some customers have added our team directly to their Atlassian products. Make su ### 1password -1Password vaults may be shared between our teams. Sometimes customers add Cloud Posse to their vaults, other times customers were added to vaults controlled by Cloud Posse. +1Password vaults may be shared between our teams. Sometimes customers add Cloud Posse to their vaults, other times customers were added to vaults controlled by Cloud Posse. -At the end of an engagement, we recommend to stop sharing vaults. +At the end of an engagement, we recommend to stop sharing vaults. #### Customer Managed Vaults diff --git a/docs/reference/.gitkeep b/docs/reference/.gitkeep deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/reference/LICENSE.mdx b/docs/reference/LICENSE.mdx new file mode 100644 index 000000000..88e14a81b --- /dev/null +++ b/docs/reference/LICENSE.mdx @@ -0,0 +1,55 @@ +--- +title: "License" +sidebar_label: "License" +slug: license +description: "This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License." +tags: +- license +- opl +- open publication license +sidebar_position: 900 +--- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; + + + This material may only be distributed subject to the terms and conditions set forth in the *[Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-nc-sa/4.0/)* or later with the restrictions noted below (the latest version of the license is presently available at [Creative Commons v4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/)). + +
+ + + + +
+ + + + +- **Attribution** You must attribute the work in the manner specified by the author or licensor. + +- **Noncommercial** The licensor permits others to copy, distribute and transmit the work. In return, licensees may not use the work for commercial purposes — unless they get the licensor's permission. + +- **Share Alike** The licensor permits others to distribute derivative works only under the same license or one compatible with the one that governs the licensor's work. + + + +## Copyright + +Copyright 2017-2024 © Cloud Posse, LLC. + +## Distribution + +Distribution of the work or derivative of the work in any standard (paper) book form for commercial purposes is prohibited unless prior permission is obtained from the copyright holder. + +Distribution of substantively modified versions of this document is prohibited without the explicit permission of the copyright holder. + +## Trademarks + +All other trademarks referenced herein are the property of their respective owners. + +:::important + +This documentation is provided (and copyrighted) by Cloud Posse, LLC and is released via the [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-nc-sa/4.0/). + +The copyright holder has added the further requirement that Distribution of substantively modified versions of this document is prohibited without the explicit permission of the copyright holder. +::: diff --git a/docs/reference/integrations/integrations.md b/docs/reference/integrations/integrations.md deleted file mode 100644 index 68152fa69..000000000 --- a/docs/reference/integrations/integrations.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: "Integrations" -sidebar_position: 10 -custom_edit_url: https://github.com/cloudposse/refarch-scaffold/tree/main/docs/docs/how-to-guides/integrations/integrations.md ---- - -# Integrations - - -Integrations involve connecting various third-party tools and services with AWS services to enhance and extend functionality. Tools like Datadog, Spacelift, and Opsgenie can provide additional capabilities in areas such as monitoring, infrastructure as code (IaC), and incident response. - -1. Datadog: - - - *Purpose:* Datadog is a monitoring and analytics platform that helps organizations gain insights into the performance of their applications, infrastructure, and services. - - *Integration Features:* - - *Monitoring:* Datadog can be integrated with AWS services to collect and analyze metrics, logs, and traces, providing comprehensive visibility into the AWS environment. - - *Alerting:* Datadog enables the creation of custom alerts based on AWS metrics, helping teams proactively identify and respond to issues. - - *Dashboards:* Integration allows the creation of dashboards that aggregate data from various AWS services, offering a unified view of the entire infrastructure. - -2. Spacelift: - - - *Purpose:* Spacelift is a platform that focuses on automating and managing infrastructure as code (IaC) workflows. - - *Integration Features:* - - Infrastructure Automation:* Spacelift integrates with AWS CloudFormation or HashiCorp Terraform to automate the provisioning and management of AWS resources. - - Workflow Management:* Spacelift allows the definition and execution of IaC workflows, enabling version-controlled, collaborative infrastructure changes. - - Policy Enforcement:* Integration with Spacelift can enforce best practices and compliance policies for AWS infrastructure deployments. - -3. Opsgenie: - - - *Purpose:* Opsgenie is an incident management and alerting platform that helps teams respond to and resolve incidents efficiently. - - *Integration Features:* - - *Alerting:* Opsgenie integrates with AWS CloudWatch or other monitoring tools to receive alerts and incidents from AWS services. - - *Incident Response:* When an incident occurs, Opsgenie can automatically notify the appropriate teams, escalate incidents, and provide a centralized platform for collaboration and communication. - - *AWS Service Integration:* Opsgenie supports direct integrations with specific AWS services, allowing for seamless incident management for services like AWS Lambda, EC2, and more. - -These integrations collectively enhance the AWS experience by providing additional functionalities, improving visibility, and automating various aspects of the development and operations lifecycle. Integrating tools such as these and more allow organizations to leverage and extend a comprehensive set of capabilities for monitoring, infrastructure management, and incident response within their AWS environment. diff --git a/docs/reference/integrations/okta/okta.md b/docs/reference/integrations/okta/okta.md deleted file mode 100644 index 8e80220c4..000000000 --- a/docs/reference/integrations/okta/okta.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: "Okta" -sidebar_position: 10 -tags: - - okta ---- - -Okta - -1. AWS Single Sign-On (AWS SSO): - -- AWS SSO is a service that simplifies access management for AWS accounts and applications. It enables users to sign in to AWS once and access multiple AWS accounts and applications without the need to re-enter credentials. -Integration Steps: -- To use Okta as an identity provider for AWS SSO, administrators typically need to configure the integration within the AWS Management Console. -This involves setting up a new AWS SSO instance, connecting it to Okta, and specifying the Okta users or groups that should have access to AWS resources. - -2. SAML-Based Authentication: - -- The integration between Okta and AWS SSO often relies on the Security Assertion Markup Language (SAML) for authentication and authorization. -SAML enables the exchange of authentication and authorization data between Okta and AWS, allowing users to log in once to Okta and gain access to AWS resources without additional logins. - - -3. User Provisioning: - -- AWS SSO can be configured to automatically provision and de-provision user accounts based on changes in the Okta directory. This helps keep user access in sync with changes made in the Okta environment. -Access Policies: -- AWS SSO allows administrators to define fine-grained access policies, specifying which AWS accounts and services users from Okta can access. This is done through AWS SSO permission sets. - - -4. Multi-Factor Authentication (MFA): - -- Organizations using Okta for authentication with AWS SSO can enhance security by enforcing multi-factor authentication (MFA) for added identity verification. - -5. Single Sign-On Experience: - -- Once configured, users can experience single sign-on when accessing AWS resources. They log in to their Okta account and seamlessly gain access to AWS without needing to provide credentials again. -Logging and Auditing: - -AWS SSO provides logging and auditing capabilities, allowing organizations to track user access to AWS resources and monitor security-related events. -It's important to note that the specifics of the integration process may be subject to updates or changes, so it's recommended to refer to the official AWS documentation and Okta documentation for the most accurate and up-to-date information based on your current date. diff --git a/docs/resources/LICENSE.mdx b/docs/resources/LICENSE.mdx deleted file mode 100644 index 5bd3b8a4e..000000000 --- a/docs/resources/LICENSE.mdx +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: "License" -slug: license -description: "This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License." -tags: -- license -- opl -- open publication license -sidebar_position: 900 ---- - -## Copyright - -Copyright 2017-2024 © Cloud Posse, LLC. - -## License - -
- - - - -
- -This material may only be distributed subject to the terms and conditions set forth in the *[Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-nc-sa/4.0/)* or later with the restrictions noted below (the latest version of the license is presently available at [Creative Commons v4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/)). - -**Attribution** You must attribute the work in the manner specified by the author or licensor. - -**Noncommercial** The licensor permits others to copy, distribute and transmit the work. In return, licensees may not use the work for commercial purposes — unless they get the licensor's permission. - -**Share Alike** The licensor permits others to distribute derivative works only under the same license or one compatible with the one that governs the licensor's work. - - -## Distribution - -Distribution of the work or derivative of the work in any standard (paper) book form for commercial purposes is prohibited unless prior permission is obtained from the copyright holder. - -Distribution of substantively modified versions of this document is prohibited without the explicit permission of the copyright holder. - -## Trademarks - -All other trademarks referenced herein are the property of their respective owners. - -:::caution - -This documentation is provided (and copyrighted) by Cloud Posse, LLC and is released via the [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-nc-sa/4.0/). - -The copyright holder has added the further requirement that Distribution of substantively modified versions of this document is prohibited without the explicit permission of the copyright holder. -::: diff --git a/docs/resources/adrs/adrs.md b/docs/resources/adrs/adrs.md deleted file mode 100644 index 4a2fb7f1e..000000000 --- a/docs/resources/adrs/adrs.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: "Architectural Design Records (ADRs)" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1176076972 -sidebar_position: 10 -custom_edit_url: https://github.com/cloudposse/refarch-scaffold/tree/main/docs/docs/reference/adrs/reference/adrs.md ---- - -# Architectural Design Records (ADRs) -These are the records for why Cloud Posse made various decisions in the design of the Reference Architecture. These decisions may differ from what your organization has decided as a result of going through the [Design Decisions](/reference-architecture/design-decisions) process. - -Send requests for additional documentation in the `#refarch-docs` channel. - -## Records - -- [Use Confluence for Customer Documentation](/reference-architecture/reference/adrs/use-confluence-for-customer-documentation) -- [Use Spacelift for GitOps with Terraform](/reference-architecture/reference/adrs/use-spacelift-for-gitops-with-terraform) -- [Use SSM over ASM for Infrastructure](/reference-architecture/reference/adrs/use-ssm-over-asm-for-infrastructure) -- [Use OpsGenie for Incident Management](/reference-architecture/reference/adrs/use-opsgenie-for-incident-management) -- [Use Terraform Provider Block with compatibility for Role ARNs and Profiles](/reference-architecture/reference/adrs/use-terraform-provider-block-with-compatibility-for-role-arns-an) -- [Use Basic Provider Block for Root-level Components](/reference-architecture/reference/adrs/use-basic-provider-block-for-root-level-components) -- [Use Terraform to Manage Helm Releases](/reference-architecture/reference/adrs/use-terraform-to-manage-helm-releases) -- [Use Environment Variables for Configuration (12 Factor)](/reference-architecture/reference/adrs/use-environment-variables-for-configuration-12-factor) -- [Use One OpsGenie Integration per Team](/reference-architecture/reference/adrs/use-one-opsgenie-integration-per-team) -- [Use API Gateway REST API vs HTTP API](/reference-architecture/reference/adrs/use-api-gateway-rest-api-vs-http-api) -- [Use Vendoring in Atmos](/reference-architecture/reference/adrs/use-vendoring-in-atmos) -- [Use Folder Structure for Compliance Components](/reference-architecture/reference/adrs/use-folder-structure-for-compliance-components) -- [Proposed: Use ISO-8601 Date Index for ADRs](/reference-architecture/reference/adrs/proposed-use-iso-8601-date-index-for-adrs) -- [Proposed: Use AWS Federated IAM over AWS SSO](/reference-architecture/reference/adrs/proposed-use-aws-federated-iam-over-aws-sso) -- [Proposed: Use Defaults for Components](/reference-architecture/reference/adrs/proposed-use-defaults-for-components) -- [Proposed: Use Atmos Registry](/reference-architecture/reference/adrs/proposed-use-atmos-registry) -- [Proposed: Atmos Workflows v2](/reference-architecture/reference/adrs/proposed-atmos-workflows-v2) -- [Proposed: Use Strict Provider Pinning in Components](/reference-architecture/reference/adrs/proposed-use-strict-provider-pinning-in-components) -- [Proposed: Use Private and Public Hosted Zones](/reference-architecture/reference/adrs/proposed-use-private-and-public-hosted-zones) -- [Proposed: Spacelift Admin Stack Architecture](/reference-architecture/reference/adrs/proposed-spacelift-admin-stack-architecture) -- [Proposed: Use Mixins to DRY-up Components](/reference-architecture/reference/adrs/proposed-use-mixins-to-dry-up-components) -- [Proposed: Use Multiple Terraform State Bucket Backends](/reference-architecture/reference/adrs/proposed-use-multiple-terraform-state-bucket-backends) -- [Proposed: Use GitHub Actions with Atmos](/reference-architecture/reference/adrs/proposed-use-github-actions-with-atmos) -- [Proposed: Use More Flexible Resource Labels](/reference-architecture/reference/adrs/proposed-use-more-flexible-resource-labels) -- [Proposed: Use Global Filename Convention](/reference-architecture/reference/adrs/proposed-use-global-filename-convention) -- [Use IPAM for IP Address Management and Allocation](/reference-architecture/reference/adrs/use-ipam-for-ip-address-management-and-allocation) -- [Proposal: Use Stack Filesystem Layout That Follows AWS Organization Conventions](/reference-architecture/reference/adrs/proposal-use-stack-filesystem-layout-that-follows-aws-organizati) -- [Proposed: Distribution Method for GitHub Actions](/reference-architecture/reference/adrs/proposed-distribution-method-for-github-actions) - -## Recently Updated - - diff --git a/docs/resources/adrs/adrs.mdx b/docs/resources/adrs/adrs.mdx new file mode 100644 index 000000000..9cdc4f587 --- /dev/null +++ b/docs/resources/adrs/adrs.mdx @@ -0,0 +1,14 @@ +--- +title: "Architectural Design Records (ADRs)" +sidebar_label: "Architectural Design Records" +sidebar_position: 1 +--- +import DocCardList from '@theme/DocCardList' + +These are the records of why Cloud Posse made various decisions in the design of the Reference Architecture. These decisions may differ from what your organization has decided due to going through the [Design Decisions](/reference-architecture/design-decisions) process. + +Send requests for additional documentation in the `#refarch` channel. + +## Records + + diff --git a/docs/resources/adrs/proposal-use-stack-filesystem-layout-that-follows-aws-organizati.md b/docs/resources/adrs/proposal-use-stack-filesystem-layout-that-follows-aws-organizati.mdx similarity index 91% rename from docs/resources/adrs/proposal-use-stack-filesystem-layout-that-follows-aws-organizati.md rename to docs/resources/adrs/proposal-use-stack-filesystem-layout-that-follows-aws-organizati.mdx index aa3b8fed3..25904fd19 100644 --- a/docs/resources/adrs/proposal-use-stack-filesystem-layout-that-follows-aws-organizati.md +++ b/docs/resources/adrs/proposal-use-stack-filesystem-layout-that-follows-aws-organizati.mdx @@ -1,11 +1,9 @@ --- title: "Proposal: Use Stack Filesystem Layout That Follows AWS Organization Conventions" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1333395457/Proposal%3A+Use+Stack+Filesystem+Layout+That+Follows+AWS+Organization+Conventions +sidebar_label: "Use Stack Filesystem Layout That Follows AWS Organization Conventions" sidebar_position: 200 -custom_edit_url: https://github.com/cloudposse/refarch-scaffold/tree/main/docs/docs/reference/adrs/proposal-use-stack-filesystem-layout-that-follows-aws-organizati.md --- -# Proposal: Use Stack Filesystem Layout That Follows AWS Organization Conventions **Date**: **27 May 2022** :::info Needs Update! @@ -17,9 +15,11 @@ The content in this ADR may be out-of-date and needing an update. For questions, ::: ## Status + **DRAFT** ## Decision + Use Option 4: Use an organization directory. ## Problem diff --git a/docs/resources/adrs/proposed-atmos-workflows-v2.md b/docs/resources/adrs/proposed-atmos-workflows-v2.mdx similarity index 100% rename from docs/resources/adrs/proposed-atmos-workflows-v2.md rename to docs/resources/adrs/proposed-atmos-workflows-v2.mdx diff --git a/docs/resources/adrs/proposed-distribution-method-for-github-actions.md b/docs/resources/adrs/proposed-distribution-method-for-github-actions.mdx similarity index 100% rename from docs/resources/adrs/proposed-distribution-method-for-github-actions.md rename to docs/resources/adrs/proposed-distribution-method-for-github-actions.mdx diff --git a/docs/resources/adrs/proposed-spacelift-admin-stack-architecture.md b/docs/resources/adrs/proposed-spacelift-admin-stack-architecture.mdx similarity index 100% rename from docs/resources/adrs/proposed-spacelift-admin-stack-architecture.md rename to docs/resources/adrs/proposed-spacelift-admin-stack-architecture.mdx diff --git a/docs/resources/adrs/proposed-use-atmos-registry.md b/docs/resources/adrs/proposed-use-atmos-registry.mdx similarity index 100% rename from docs/resources/adrs/proposed-use-atmos-registry.md rename to docs/resources/adrs/proposed-use-atmos-registry.mdx diff --git a/docs/resources/adrs/proposed-use-aws-federated-iam-over-aws-sso.md b/docs/resources/adrs/proposed-use-aws-federated-iam-over-aws-sso.mdx similarity index 100% rename from docs/resources/adrs/proposed-use-aws-federated-iam-over-aws-sso.md rename to docs/resources/adrs/proposed-use-aws-federated-iam-over-aws-sso.mdx diff --git a/docs/resources/adrs/proposed-use-defaults-for-components.md b/docs/resources/adrs/proposed-use-defaults-for-components.mdx similarity index 100% rename from docs/resources/adrs/proposed-use-defaults-for-components.md rename to docs/resources/adrs/proposed-use-defaults-for-components.mdx diff --git a/docs/resources/adrs/proposed-use-github-actions-with-atmos.md b/docs/resources/adrs/proposed-use-github-actions-with-atmos.mdx similarity index 100% rename from docs/resources/adrs/proposed-use-github-actions-with-atmos.md rename to docs/resources/adrs/proposed-use-github-actions-with-atmos.mdx diff --git a/docs/resources/adrs/proposed-use-global-filename-convention.md b/docs/resources/adrs/proposed-use-global-filename-convention.mdx similarity index 100% rename from docs/resources/adrs/proposed-use-global-filename-convention.md rename to docs/resources/adrs/proposed-use-global-filename-convention.mdx diff --git a/docs/resources/adrs/proposed-use-iso-8601-date-index-for-adrs.md b/docs/resources/adrs/proposed-use-iso-8601-date-index-for-adrs.mdx similarity index 100% rename from docs/resources/adrs/proposed-use-iso-8601-date-index-for-adrs.md rename to docs/resources/adrs/proposed-use-iso-8601-date-index-for-adrs.mdx diff --git a/docs/resources/adrs/proposed-use-mixins-to-dry-up-components.md b/docs/resources/adrs/proposed-use-mixins-to-dry-up-components.mdx similarity index 100% rename from docs/resources/adrs/proposed-use-mixins-to-dry-up-components.md rename to docs/resources/adrs/proposed-use-mixins-to-dry-up-components.mdx diff --git a/docs/resources/adrs/proposed-use-more-flexible-resource-labels.md b/docs/resources/adrs/proposed-use-more-flexible-resource-labels.mdx similarity index 100% rename from docs/resources/adrs/proposed-use-more-flexible-resource-labels.md rename to docs/resources/adrs/proposed-use-more-flexible-resource-labels.mdx diff --git a/docs/resources/adrs/proposed-use-multiple-terraform-state-bucket-backends.md b/docs/resources/adrs/proposed-use-multiple-terraform-state-bucket-backends.mdx similarity index 100% rename from docs/resources/adrs/proposed-use-multiple-terraform-state-bucket-backends.md rename to docs/resources/adrs/proposed-use-multiple-terraform-state-bucket-backends.mdx diff --git a/docs/resources/adrs/proposed-use-private-and-public-hosted-zones.md b/docs/resources/adrs/proposed-use-private-and-public-hosted-zones.mdx similarity index 100% rename from docs/resources/adrs/proposed-use-private-and-public-hosted-zones.md rename to docs/resources/adrs/proposed-use-private-and-public-hosted-zones.mdx diff --git a/docs/resources/adrs/proposed-use-strict-provider-pinning-in-components.md b/docs/resources/adrs/proposed-use-strict-provider-pinning-in-components.mdx similarity index 100% rename from docs/resources/adrs/proposed-use-strict-provider-pinning-in-components.md rename to docs/resources/adrs/proposed-use-strict-provider-pinning-in-components.mdx diff --git a/docs/resources/adrs/use-api-gateway-rest-api-vs-http-api.md b/docs/resources/adrs/use-api-gateway-rest-api-vs-http-api.mdx similarity index 100% rename from docs/resources/adrs/use-api-gateway-rest-api-vs-http-api.md rename to docs/resources/adrs/use-api-gateway-rest-api-vs-http-api.mdx diff --git a/docs/resources/adrs/use-basic-provider-block-for-root-level-components.md b/docs/resources/adrs/use-basic-provider-block-for-root-level-components.mdx similarity index 100% rename from docs/resources/adrs/use-basic-provider-block-for-root-level-components.md rename to docs/resources/adrs/use-basic-provider-block-for-root-level-components.mdx diff --git a/docs/resources/adrs/use-confluence-for-customer-documentation.md b/docs/resources/adrs/use-confluence-for-customer-documentation.mdx similarity index 100% rename from docs/resources/adrs/use-confluence-for-customer-documentation.md rename to docs/resources/adrs/use-confluence-for-customer-documentation.mdx diff --git a/docs/resources/adrs/use-environment-variables-for-configuration-12-factor.md b/docs/resources/adrs/use-environment-variables-for-configuration-12-factor.mdx similarity index 100% rename from docs/resources/adrs/use-environment-variables-for-configuration-12-factor.md rename to docs/resources/adrs/use-environment-variables-for-configuration-12-factor.mdx diff --git a/docs/resources/adrs/use-folder-structure-for-compliance-components.md b/docs/resources/adrs/use-folder-structure-for-compliance-components.mdx similarity index 100% rename from docs/resources/adrs/use-folder-structure-for-compliance-components.md rename to docs/resources/adrs/use-folder-structure-for-compliance-components.mdx diff --git a/docs/resources/adrs/use-ipam-for-ip-address-management-and-allocation.md b/docs/resources/adrs/use-ipam-for-ip-address-management-and-allocation.mdx similarity index 100% rename from docs/resources/adrs/use-ipam-for-ip-address-management-and-allocation.md rename to docs/resources/adrs/use-ipam-for-ip-address-management-and-allocation.mdx diff --git a/docs/resources/adrs/use-one-opsgenie-integration-per-team.md b/docs/resources/adrs/use-one-opsgenie-integration-per-team.mdx similarity index 100% rename from docs/resources/adrs/use-one-opsgenie-integration-per-team.md rename to docs/resources/adrs/use-one-opsgenie-integration-per-team.mdx diff --git a/docs/resources/adrs/use-opsgenie-for-incident-management.md b/docs/resources/adrs/use-opsgenie-for-incident-management.mdx similarity index 100% rename from docs/resources/adrs/use-opsgenie-for-incident-management.md rename to docs/resources/adrs/use-opsgenie-for-incident-management.mdx diff --git a/docs/resources/adrs/use-spacelift-for-gitops-with-terraform.md b/docs/resources/adrs/use-spacelift-for-gitops-with-terraform.mdx similarity index 100% rename from docs/resources/adrs/use-spacelift-for-gitops-with-terraform.md rename to docs/resources/adrs/use-spacelift-for-gitops-with-terraform.mdx diff --git a/docs/resources/adrs/use-ssm-over-asm-for-infrastructure.md b/docs/resources/adrs/use-ssm-over-asm-for-infrastructure.mdx similarity index 100% rename from docs/resources/adrs/use-ssm-over-asm-for-infrastructure.md rename to docs/resources/adrs/use-ssm-over-asm-for-infrastructure.mdx diff --git a/docs/resources/adrs/use-terraform-provider-block-with-compatibility-for-role-arns-an.md b/docs/resources/adrs/use-terraform-provider-block-with-compatibility-for-role-arns-an.mdx similarity index 100% rename from docs/resources/adrs/use-terraform-provider-block-with-compatibility-for-role-arns-an.md rename to docs/resources/adrs/use-terraform-provider-block-with-compatibility-for-role-arns-an.mdx diff --git a/docs/resources/adrs/use-terraform-to-manage-helm-releases.md b/docs/resources/adrs/use-terraform-to-manage-helm-releases.mdx similarity index 100% rename from docs/resources/adrs/use-terraform-to-manage-helm-releases.md rename to docs/resources/adrs/use-terraform-to-manage-helm-releases.mdx diff --git a/docs/resources/adrs/use-vendoring-in-atmos.md b/docs/resources/adrs/use-vendoring-in-atmos.mdx similarity index 100% rename from docs/resources/adrs/use-vendoring-in-atmos.md rename to docs/resources/adrs/use-vendoring-in-atmos.mdx diff --git a/docs/resources/architecture-diagrams.md b/docs/resources/architecture-diagrams.mdx similarity index 87% rename from docs/resources/architecture-diagrams.md rename to docs/resources/architecture-diagrams.mdx index 660e30721..b07fd09f9 100644 --- a/docs/resources/architecture-diagrams.md +++ b/docs/resources/architecture-diagrams.mdx @@ -1,16 +1,17 @@ --- title: "Architecture Diagrams" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1176109758/Architecture+Diagrams -sidebar_position: 100 -custom_edit_url: https://github.com/cloudposse/refarch-scaffold/tree/main/docs/docs/reference/architecture-diagrams.md +sidebar_label: "Architecture Diagrams" +sidebar_position: 1 --- +import Intro from '@site/src/components/Intro'; -# Architecture Diagrams + We provide a number of boilerplate architecture diagrams. Think of them as templates that can be copied and used throughout your organization. Reach out to Cloud Posse PMs if you’d like a copy of any one of them. + ## Available Diagrams -Don’t see the diagram you need? Let us know via the `#refarch-docs` channel. +Don’t see the diagram you need? Let us know via the `#refarch` channel. ## 4 Layers of Infrastructure diff --git a/docs/resources/aws/aws-access-control-architecture.md b/docs/resources/aws/aws-access-control-architecture.mdx similarity index 99% rename from docs/resources/aws/aws-access-control-architecture.md rename to docs/resources/aws/aws-access-control-architecture.mdx index 002ff3a2f..a8dcd8a2c 100644 --- a/docs/resources/aws/aws-access-control-architecture.md +++ b/docs/resources/aws/aws-access-control-architecture.mdx @@ -1,8 +1,9 @@ --- title: "Access Control Architecture" sidebar_position: 100 -custom_edit_url: https://github.com/cloudposse/refarch-scaffold/tree/main/docs/docs/reference/aws/aws-access-control-architecture.md --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # Access Control Architecture diff --git a/docs/resources/aws/aws-access-control-evolution.md b/docs/resources/aws/aws-access-control-evolution.mdx similarity index 99% rename from docs/resources/aws/aws-access-control-evolution.md rename to docs/resources/aws/aws-access-control-evolution.mdx index 5ed9b7458..4ed8ffb59 100644 --- a/docs/resources/aws/aws-access-control-evolution.md +++ b/docs/resources/aws/aws-access-control-evolution.mdx @@ -1,8 +1,10 @@ --- title: "Access Control Evolution" sidebar_position: 100 -custom_edit_url: https://github.com/cloudposse/refarch-scaffold/tree/main/docs/docs/reference/aws/aws-access-control-evolution.md --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; + # Access Control Evolution ## Overview diff --git a/docs/resources/aws/aws-access-control.md b/docs/resources/aws/aws-access-control.mdx similarity index 94% rename from docs/resources/aws/aws-access-control.md rename to docs/resources/aws/aws-access-control.mdx index b5532c7b5..c73024067 100644 --- a/docs/resources/aws/aws-access-control.md +++ b/docs/resources/aws/aws-access-control.mdx @@ -1,9 +1,9 @@ --- title: "AWS Access Control" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1298628675/AWS+Access+Control sidebar_position: 100 -custom_edit_url: https://github.com/cloudposse/refarch-scaffold/tree/main/docs/docs/reference/aws/aws-access-control.md --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # AWS Access Control With the exception of “root accounts” (beyond the scope of this article), all access to AWS resources is controlled by [AWS Identity and Access Management](https://aws.amazon.com/iam/), usually referred to by its initials IAM (pronounced “I am”). People accessing AWS resources in the normal course of duty, in any of the configurations recommended and supported by Cloud Posse, exclusively access AWS resources by “assuming” IAM [Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html). diff --git a/docs/resources/aws/aws-feature-requests-and-limitations.md b/docs/resources/aws/aws-feature-requests-and-limitations.mdx similarity index 93% rename from docs/resources/aws/aws-feature-requests-and-limitations.md rename to docs/resources/aws/aws-feature-requests-and-limitations.mdx index a7bab526e..502d335b2 100644 --- a/docs/resources/aws/aws-feature-requests-and-limitations.md +++ b/docs/resources/aws/aws-feature-requests-and-limitations.mdx @@ -1,9 +1,9 @@ --- title: "AWS Feature Requests and Limitations" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1171193857/AWS+Feature+Requests+and+Limitations sidebar_position: 100 -custom_edit_url: https://github.com/cloudposse/refarch-scaffold/tree/main/docs/docs/reference/aws/aws-feature-requests-and-limitations.md --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # AWS Feature Requests and Limitations @@ -12,7 +12,7 @@ custom_edit_url: https://github.com/cloudposse/refarch-scaffold/tree/main/docs/d **Use-case:** turnkey CloudFormation template to create a secure stack without requiring DNS or email validation (difficult to obtain in enterprise environments) -Resources like RDS clusters/instances and Elasticache Redis support TLS out-of-the-box without a dependency on ACM. Load balancers should support the same to facilitate end-to-end encryption by default. For example, origins fronted by a CDN do not need any sort of branded/vanity hostnames and would suffice with an [amazonaws.com](http://amazonaws.com) TLS certificate. +Resources like RDS clusters/instances and Elasticache Redis support TLS out-of-the-box without a dependency on ACM. Load balancers should support the same to facilitate end-to-end encryption by default. For example, origins fronted by a CDN do not need any sort of branded/vanity hostnames and would suffice with an [amazonaws.com](http://amazonaws.com) TLS certificate. ### Facilitate AWS Account Automation **Use-case:** e2e automation of AWS accounts (full SDLC) @@ -21,9 +21,9 @@ AWS accounts are today treated as scarce quantities and pets. Net-new AWS accoun Once accounts are created, they cannot be easily destroyed and require human intervention. This precludes e2e CI/CD testing of account automation. -Account email addresses are one-time-use. After destroying an account, it cannot be recreated using the same email address, requiring a roundabout way of first renaming the address on-file before destroying. +Account email addresses are one-time-use. After destroying an account, it cannot be recreated using the same email address, requiring a roundabout way of first renaming the address on-file before destroying. -AWS already has the concept of Organizations with master accounts and child accounts. This could be extended to allow for automation accounts, which would inherit limits from parent accounts (or perhaps take a fraction of the parent account’s limit) when they are created and restore the limits to the parent account when they are deleted. Similar to KMS keys, they could pass through a frozen stage where they have a limited lifespan where they can be revived, but preferably, accounts less than 1 day old could be deleted immediately. +AWS already has the concept of Organizations with master accounts and child accounts. This could be extended to allow for automation accounts, which would inherit limits from parent accounts (or perhaps take a fraction of the parent account’s limit) when they are created and restore the limits to the parent account when they are deleted. Similar to KMS keys, they could pass through a frozen stage where they have a limited lifespan where they can be revived, but preferably, accounts less than 1 day old could be deleted immediately. ### [Launched] Managed Prometheus-compatible Time Series Database @@ -32,7 +32,7 @@ AWS Launched Amazon Managed Service for Prometheus which provides highly availab ::: -~~AWS provides a time series service called Timestream, but it does not support a format compatible with Prometheus. Prometheus~~ [~~won’t support it~~](https://github.com/prometheus/prometheus/issues/5086) ~~out-of-the-box. Given that Prometheus is the most popular open source monitoring framework, this would be a big win and a great way to increase adoption for Timestream.~~ +~~AWS provides a time series service called Timestream, but it does not support a format compatible with Prometheus. Prometheus~~ [~~won’t support it~~](https://github.com/prometheus/prometheus/issues/5086) ~~out-of-the-box. Given that Prometheus is the most popular open source monitoring framework, this would be a big win and a great way to increase adoption for Timestream.~~
@@ -44,25 +44,25 @@ One specific example, we cannot create CloudWatch Metrics or Alarms on the Appli ### Better CDK documentation -We understand documentation is hard, and there is voluminous documentation for the CDK, but at the same time, the documentation is largely at a very low level that leaves a lot of gaps. For example [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-attribute-deletionpolicy.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-attribute-deletionpolicy.html) explains that `AWS::EC2::Volume` supports a DeletionPolicy of Snapshot, but we have been stumped about how to use that in conjunction with an EC2 instance set to “delete on termination” an EBS data volume, to the point where we are not even sure it is truly supported. +We understand documentation is hard, and there is voluminous documentation for the CDK, but at the same time, the documentation is largely at a very low level that leaves a lot of gaps. For example [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-attribute-deletionpolicy.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-attribute-deletionpolicy.html) explains that `AWS::EC2::Volume` supports a DeletionPolicy of Snapshot, but we have been stumped about how to use that in conjunction with an EC2 instance set to “delete on termination” an EBS data volume, to the point where we are not even sure it is truly supported. -Similarly, we could not find examples about how to set up, using the Python CDK, a stack that has CloudWatch metrics and alarms that would monitor instance metrics for EC2 instances launched as part of an AutoScaling Group. All we could find were alarms on the AutoScaling Group itself, such as `autoscaling:EC2_INSTANCE_LAUNCH_ERROR`. +Similarly, we could not find examples about how to set up, using the Python CDK, a stack that has CloudWatch metrics and alarms that would monitor instance metrics for EC2 instances launched as part of an AutoScaling Group. All we could find were alarms on the AutoScaling Group itself, such as `autoscaling:EC2_INSTANCE_LAUNCH_ERROR`. We found [this note](https://docs.aws.amazon.com/cdk/api/latest/docs/aws-autoscaling-readme.html#future-work) but disagreed about what it means: `Future Work: CloudWatch Events (impossible to add currently as the AutoScalingGroup ARN is necessary to make this rule and this cannot be accessed from CloudFormation).` -Does that mean we also cannot set up CloudWatch Metrics and Alarms? +Does that mean we also cannot set up CloudWatch Metrics and Alarms? Here is another [random example](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-cloudwatch.CreateAlarmOptions.html#evaluatelowsamplecountpercentile): `evaluateLowSampleCountPercentile` is a `string` that “specifies whether to evaluate the data and potentially change the alarm state if there are too few data points to be statistically significant.” Why is that a `string`? How is the string interpreted? I would expect it to be a boolean given the variable name. ### Account Limit operations should be available via API -Currently, AWS does not provide a generally available way to alert when limits are reached. This is adverse to providing an ultimately stable platform for your customers. Reaching limits is something that can happen when you least expect it and lead to forced outages. AWS needs to make it easier to programmatically increase these limits (e.g. via an API we can call from terraform) and trigger alerts when thresholds are met. +Currently, AWS does not provide a generally available way to alert when limits are reached. This is adverse to providing an ultimately stable platform for your customers. Reaching limits is something that can happen when you least expect it and lead to forced outages. AWS needs to make it easier to programmatically increase these limits (e.g. via an API we can call from terraform) and trigger alerts when thresholds are met. [https://aws.amazon.com/solutions/implementations/limit-monitor/](https://aws.amazon.com/solutions/implementations/limit-monitor/) -[https://github.com/awslabs/aws-limit-monitor](https://github.com/awslabs/aws-limit-monitor) +[https://github.com/awslabs/aws-limit-monitor](https://github.com/awslabs/aws-limit-monitor)
@@ -70,15 +70,15 @@ Currently, AWS does not provide a generally available way to alert when limits a **~~Use-case~~**~~: building containers with “Docker in Docker” with Jenkins on managed node groups~~ -[https://github.com/aws/containers-roadmap/issues/596](https://github.com/aws/containers-roadmap/issues/596) ~~~~ +[https://github.com/aws/containers-roadmap/issues/596](https://github.com/aws/containers-roadmap/issues/596) ~~~~ -~~Also want to be able to set Kubernetes node labels and taints at instance launch.~~ +~~Also want to be able to set Kubernetes node labels and taints at instance launch.~~ ### Next Generation AWS VPC CNI Plugin **Use-case:** achieve higher container density per node -[https://github.com/aws/containers-roadmap/issues/398](https://github.com/aws/containers-roadmap/issues/398) +[https://github.com/aws/containers-roadmap/issues/398](https://github.com/aws/containers-roadmap/issues/398) The problem is that our customers frequently run less CPU-intensive workloads and could achieve greater efficiency and economies of scale by packing more containers on an instance. EKS restricts the number of pods per node implicitly by limiting the number of ENIs. In order to run more pods, a larger instance is required that supports more ENIs, but then the instances are underutilized. In the end, it feels like a backhanded way of forcing customers to pay for more than they need - like enterprise software licensing charging per core. @@ -92,7 +92,7 @@ The problem is that Edge Lambdas once provisioned can take hours if not days to ### CloudFront Distributions are Too Slow to Modify -Use-case: +Use-case: ### [Launched] DNSSEC on Route53 @@ -104,7 +104,7 @@ Use-case: Something needs to be done with Network Load Balancer TCP health checks. The health checks easily overload origin servers when they fail. It is bad enough that the health check interval cannot be configured and that when healthy we are getting an average of 120 health checks per minute, but when they fail the number skyrockets to ~3,000 per minute. The linked issue has details. -[https://github.com/kubernetes/ingress-nginx/issues/5425](https://github.com/kubernetes/ingress-nginx/issues/5425) +[https://github.com/kubernetes/ingress-nginx/issues/5425](https://github.com/kubernetes/ingress-nginx/issues/5425) ## Bugs @@ -112,7 +112,7 @@ These are some bugs that affect us. The bugs might be mitigated by the Terraform `Error: Creating CloudWatch Log Group failed: ResourceAlreadyExistsException: The specified log group already exists: The CloudWatch Log Group '/aws/eks/eg-test-eks-cluster/cluster' already exists` -[https://github.com/cloudposse/terraform-aws-eks-cluster/issues/67](https://github.com/cloudposse/terraform-aws-eks-cluster/issues/67) +[https://github.com/cloudposse/terraform-aws-eks-cluster/issues/67](https://github.com/cloudposse/terraform-aws-eks-cluster/issues/67) This is happening because EKS Cluster gets destroyed after Terraform deletes the Cloudwatch Log Group. The `AmazonEKSServicePolicy` IAM policy (that is assigned to EKS Cluster role by default within this module) has permissions to `CreateLogGroup` and anything else needed to continue logging correctly. When the Terraform destroys the Cloudwatch Log Group, the EKS Cluster that is running recreates it. Then, when you run Terraform Apply again, the Cloudwatch Log Group doesn't exist in your state anymore (because the Terraform actually destroyed it) and the Terraform doesn't know this resource created outside him. diff --git a/docs/resources/aws/aws-region-codes.md b/docs/resources/aws/aws-region-codes.mdx similarity index 93% rename from docs/resources/aws/aws-region-codes.md rename to docs/resources/aws/aws-region-codes.mdx index 54e78703e..699f87a98 100644 --- a/docs/resources/aws/aws-region-codes.md +++ b/docs/resources/aws/aws-region-codes.mdx @@ -1,9 +1,9 @@ --- title: "AWS Region Codes" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1195114534/AWS+Region+Codes sidebar_position: 100 -custom_edit_url: https://github.com/cloudposse/refarch-scaffold/tree/main/docs/docs/reference/aws/aws-region-codes.md --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # AWS Region Codes diff --git a/docs/resources/aws/aws-restricting-admin-access.md b/docs/resources/aws/aws-restricting-admin-access.mdx similarity index 98% rename from docs/resources/aws/aws-restricting-admin-access.md rename to docs/resources/aws/aws-restricting-admin-access.mdx index 22618e80a..c9e2ca558 100644 --- a/docs/resources/aws/aws-restricting-admin-access.md +++ b/docs/resources/aws/aws-restricting-admin-access.mdx @@ -1,8 +1,9 @@ --- title: "Restricting Admin Access to Sensitive Accounts" sidebar_position: 100 -custom_edit_url: https://github.com/cloudposse/refarch-scaffold/tree/main/docs/docs/reference/aws/aws-restricting-admin-access.md --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # Restricting Admin Access to Sensitive Accounts diff --git a/docs/resources/aws/aws.md b/docs/resources/aws/aws.mdx similarity index 96% rename from docs/resources/aws/aws.md rename to docs/resources/aws/aws.mdx index 41c6e116e..be40cafdd 100644 --- a/docs/resources/aws/aws.md +++ b/docs/resources/aws/aws.mdx @@ -1,9 +1,9 @@ --- title: "AWS" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1201373197/AWS -sidebar_position: 10 -custom_edit_url: https://github.com/cloudposse/refarch-scaffold/tree/main/docs/docs/reference/aws/aws.md +sidebar_position: 4 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # AWS diff --git a/docs/resources/aws/dynamic-terraform-roles.md b/docs/resources/aws/dynamic-terraform-roles.mdx similarity index 99% rename from docs/resources/aws/dynamic-terraform-roles.md rename to docs/resources/aws/dynamic-terraform-roles.mdx index a6d0d2d17..d83ff9179 100644 --- a/docs/resources/aws/dynamic-terraform-roles.md +++ b/docs/resources/aws/dynamic-terraform-roles.mdx @@ -1,8 +1,9 @@ --- title: "Dynamic Terraform Roles" -custom_edit_url: https://github.com/cloudposse/refarch-scaffold/tree/main/docs/docs/reference/aws/dynamic-terraform-roles.md sidebar_position: 100 --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; # Dynamic Terraform Roles diff --git a/docs/resources/conventions.md b/docs/resources/conventions.mdx similarity index 99% rename from docs/resources/conventions.md rename to docs/resources/conventions.mdx index c7da464c6..12e1285d9 100644 --- a/docs/resources/conventions.md +++ b/docs/resources/conventions.mdx @@ -1,13 +1,12 @@ --- title: "Conventions" -confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1201831992/Conventions +sidebar_label: "Conventions" sidebar_position: 100 -custom_edit_url: https://github.com/cloudposse/refarch-scaffold/tree/main/docs/docs/reference/conventions.md --- - +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; import ReactPlayer from 'react-player' -# Conventions Here’s a summary of all of our conventions across Terraform, Stacks, Catalogs, etc. ## SweetOps Conventions diff --git a/docs/resources/glossary/12-factor.md b/docs/resources/glossary/12-factor.mdx similarity index 100% rename from docs/resources/glossary/12-factor.md rename to docs/resources/glossary/12-factor.mdx diff --git a/docs/resources/glossary/_category_.json b/docs/resources/glossary/_category_.json index 07d78fb1d..e80a48111 100644 --- a/docs/resources/glossary/_category_.json +++ b/docs/resources/glossary/_category_.json @@ -1,6 +1,6 @@ { "label": "Glossary", - "position": 60, + "position": 3, "link": { "type": "generated-index", "description": "Glossary of definitions" diff --git a/docs/resources/glossary/acm.md b/docs/resources/glossary/acm.mdx similarity index 100% rename from docs/resources/glossary/acm.md rename to docs/resources/glossary/acm.mdx diff --git a/docs/resources/glossary/ami.md b/docs/resources/glossary/ami.mdx similarity index 100% rename from docs/resources/glossary/ami.md rename to docs/resources/glossary/ami.mdx diff --git a/docs/resources/glossary/anti-pattern.md b/docs/resources/glossary/anti-pattern.mdx similarity index 100% rename from docs/resources/glossary/anti-pattern.md rename to docs/resources/glossary/anti-pattern.mdx diff --git a/docs/resources/glossary/availability-zone.md b/docs/resources/glossary/availability-zone.mdx similarity index 100% rename from docs/resources/glossary/availability-zone.md rename to docs/resources/glossary/availability-zone.mdx diff --git a/docs/resources/glossary/aws-vault.md b/docs/resources/glossary/aws-vault.mdx similarity index 100% rename from docs/resources/glossary/aws-vault.md rename to docs/resources/glossary/aws-vault.mdx diff --git a/docs/resources/glossary/aws.md b/docs/resources/glossary/aws.mdx similarity index 100% rename from docs/resources/glossary/aws.md rename to docs/resources/glossary/aws.mdx diff --git a/docs/resources/glossary/bastion.md b/docs/resources/glossary/bastion.mdx similarity index 100% rename from docs/resources/glossary/bastion.md rename to docs/resources/glossary/bastion.mdx diff --git a/docs/resources/glossary/best-practices.md b/docs/resources/glossary/best-practices.mdx similarity index 100% rename from docs/resources/glossary/best-practices.md rename to docs/resources/glossary/best-practices.mdx diff --git a/docs/resources/glossary/beyondcorp.md b/docs/resources/glossary/beyondcorp.mdx similarity index 100% rename from docs/resources/glossary/beyondcorp.md rename to docs/resources/glossary/beyondcorp.mdx diff --git a/docs/resources/glossary/build-harness.md b/docs/resources/glossary/build-harness.mdx similarity index 100% rename from docs/resources/glossary/build-harness.md rename to docs/resources/glossary/build-harness.mdx diff --git a/docs/resources/glossary/business-logic.md b/docs/resources/glossary/business-logic.mdx similarity index 100% rename from docs/resources/glossary/business-logic.md rename to docs/resources/glossary/business-logic.mdx diff --git a/docs/resources/glossary/chamber.md b/docs/resources/glossary/chamber.mdx similarity index 100% rename from docs/resources/glossary/chamber.md rename to docs/resources/glossary/chamber.mdx diff --git a/docs/resources/glossary/change-control.md b/docs/resources/glossary/change-control.mdx similarity index 100% rename from docs/resources/glossary/change-control.md rename to docs/resources/glossary/change-control.mdx diff --git a/docs/resources/glossary/chart-registry.md b/docs/resources/glossary/chart-registry.mdx similarity index 100% rename from docs/resources/glossary/chart-registry.md rename to docs/resources/glossary/chart-registry.mdx diff --git a/docs/resources/glossary/cicd.md b/docs/resources/glossary/cicd.mdx similarity index 100% rename from docs/resources/glossary/cicd.md rename to docs/resources/glossary/cicd.mdx diff --git a/docs/resources/glossary/cli.md b/docs/resources/glossary/cli.mdx similarity index 100% rename from docs/resources/glossary/cli.md rename to docs/resources/glossary/cli.mdx diff --git a/docs/resources/glossary/clickops.md b/docs/resources/glossary/clickops.mdx similarity index 100% rename from docs/resources/glossary/clickops.md rename to docs/resources/glossary/clickops.mdx diff --git a/docs/resources/glossary/cloudfront.md b/docs/resources/glossary/cloudfront.mdx similarity index 100% rename from docs/resources/glossary/cloudfront.md rename to docs/resources/glossary/cloudfront.mdx diff --git a/docs/resources/glossary/cloudposse.md b/docs/resources/glossary/cloudposse.mdx similarity index 100% rename from docs/resources/glossary/cloudposse.md rename to docs/resources/glossary/cloudposse.mdx diff --git a/docs/resources/glossary/cloudtrail.md b/docs/resources/glossary/cloudtrail.mdx similarity index 100% rename from docs/resources/glossary/cloudtrail.md rename to docs/resources/glossary/cloudtrail.mdx diff --git a/docs/resources/glossary/cloudwatch-logs.md b/docs/resources/glossary/cloudwatch-logs.mdx similarity index 100% rename from docs/resources/glossary/cloudwatch-logs.md rename to docs/resources/glossary/cloudwatch-logs.mdx diff --git a/docs/resources/glossary/cloudwatch.md b/docs/resources/glossary/cloudwatch.mdx similarity index 100% rename from docs/resources/glossary/cloudwatch.md rename to docs/resources/glossary/cloudwatch.mdx diff --git a/docs/resources/glossary/cmp.md b/docs/resources/glossary/cmp.mdx similarity index 100% rename from docs/resources/glossary/cmp.md rename to docs/resources/glossary/cmp.mdx diff --git a/docs/resources/glossary/code-build.md b/docs/resources/glossary/code-build.mdx similarity index 100% rename from docs/resources/glossary/code-build.md rename to docs/resources/glossary/code-build.mdx diff --git a/docs/resources/glossary/code-deploy.md b/docs/resources/glossary/code-deploy.mdx similarity index 100% rename from docs/resources/glossary/code-deploy.md rename to docs/resources/glossary/code-deploy.mdx diff --git a/docs/resources/glossary/code-pipeline.md b/docs/resources/glossary/code-pipeline.mdx similarity index 100% rename from docs/resources/glossary/code-pipeline.md rename to docs/resources/glossary/code-pipeline.mdx diff --git a/docs/resources/glossary/code-review.md b/docs/resources/glossary/code-review.mdx similarity index 100% rename from docs/resources/glossary/code-review.md rename to docs/resources/glossary/code-review.mdx diff --git a/docs/resources/glossary/codefresh.md b/docs/resources/glossary/codefresh.mdx similarity index 100% rename from docs/resources/glossary/codefresh.md rename to docs/resources/glossary/codefresh.mdx diff --git a/docs/resources/glossary/continuous-delivery.md b/docs/resources/glossary/continuous-delivery.mdx similarity index 100% rename from docs/resources/glossary/continuous-delivery.md rename to docs/resources/glossary/continuous-delivery.mdx diff --git a/docs/resources/glossary/continuous-integration.md b/docs/resources/glossary/continuous-integration.mdx similarity index 100% rename from docs/resources/glossary/continuous-integration.md rename to docs/resources/glossary/continuous-integration.mdx diff --git a/docs/resources/glossary/crud.md b/docs/resources/glossary/crud.mdx similarity index 100% rename from docs/resources/glossary/crud.md rename to docs/resources/glossary/crud.mdx diff --git a/docs/resources/glossary/curl-bash.md b/docs/resources/glossary/curl-bash.mdx similarity index 100% rename from docs/resources/glossary/curl-bash.md rename to docs/resources/glossary/curl-bash.mdx diff --git a/docs/resources/glossary/declarative.md b/docs/resources/glossary/declarative.mdx similarity index 100% rename from docs/resources/glossary/declarative.md rename to docs/resources/glossary/declarative.mdx diff --git a/docs/resources/glossary/dev-shm.md b/docs/resources/glossary/dev-shm.mdx similarity index 100% rename from docs/resources/glossary/dev-shm.md rename to docs/resources/glossary/dev-shm.mdx diff --git a/docs/resources/glossary/docker-bash.md b/docs/resources/glossary/docker-bash.mdx similarity index 100% rename from docs/resources/glossary/docker-bash.md rename to docs/resources/glossary/docker-bash.mdx diff --git a/docs/resources/glossary/docker-compose.md b/docs/resources/glossary/docker-compose.mdx similarity index 100% rename from docs/resources/glossary/docker-compose.md rename to docs/resources/glossary/docker-compose.mdx diff --git a/docs/resources/glossary/docker-image.md b/docs/resources/glossary/docker-image.mdx similarity index 100% rename from docs/resources/glossary/docker-image.md rename to docs/resources/glossary/docker-image.mdx diff --git a/docs/resources/glossary/docker-registry.md b/docs/resources/glossary/docker-registry.mdx similarity index 100% rename from docs/resources/glossary/docker-registry.md rename to docs/resources/glossary/docker-registry.mdx diff --git a/docs/resources/glossary/dockerfile.md b/docs/resources/glossary/dockerfile.mdx similarity index 100% rename from docs/resources/glossary/dockerfile.md rename to docs/resources/glossary/dockerfile.mdx diff --git a/docs/resources/glossary/dry.md b/docs/resources/glossary/dry.mdx similarity index 100% rename from docs/resources/glossary/dry.md rename to docs/resources/glossary/dry.mdx diff --git a/docs/resources/glossary/e2e.md b/docs/resources/glossary/e2e.mdx similarity index 100% rename from docs/resources/glossary/e2e.md rename to docs/resources/glossary/e2e.mdx diff --git a/docs/resources/glossary/eb.md b/docs/resources/glossary/eb.mdx similarity index 100% rename from docs/resources/glossary/eb.md rename to docs/resources/glossary/eb.mdx diff --git a/docs/resources/glossary/ecr.md b/docs/resources/glossary/ecr.mdx similarity index 100% rename from docs/resources/glossary/ecr.md rename to docs/resources/glossary/ecr.mdx diff --git a/docs/resources/glossary/ecs-agent.md b/docs/resources/glossary/ecs-agent.mdx similarity index 100% rename from docs/resources/glossary/ecs-agent.md rename to docs/resources/glossary/ecs-agent.mdx diff --git a/docs/resources/glossary/ecs-service.md b/docs/resources/glossary/ecs-service.mdx similarity index 100% rename from docs/resources/glossary/ecs-service.md rename to docs/resources/glossary/ecs-service.mdx diff --git a/docs/resources/glossary/ecs-task.md b/docs/resources/glossary/ecs-task.mdx similarity index 100% rename from docs/resources/glossary/ecs-task.md rename to docs/resources/glossary/ecs-task.mdx diff --git a/docs/resources/glossary/ecs.md b/docs/resources/glossary/ecs.mdx similarity index 100% rename from docs/resources/glossary/ecs.md rename to docs/resources/glossary/ecs.mdx diff --git a/docs/resources/glossary/environment-variable.md b/docs/resources/glossary/environment-variable.mdx similarity index 100% rename from docs/resources/glossary/environment-variable.md rename to docs/resources/glossary/environment-variable.mdx diff --git a/docs/resources/glossary/executable-documentation.md b/docs/resources/glossary/executable-documentation.mdx similarity index 100% rename from docs/resources/glossary/executable-documentation.md rename to docs/resources/glossary/executable-documentation.mdx diff --git a/docs/resources/glossary/fuse.md b/docs/resources/glossary/fuse.mdx similarity index 100% rename from docs/resources/glossary/fuse.md rename to docs/resources/glossary/fuse.mdx diff --git a/docs/resources/glossary/geodesic-module.md b/docs/resources/glossary/geodesic-module.mdx similarity index 100% rename from docs/resources/glossary/geodesic-module.md rename to docs/resources/glossary/geodesic-module.mdx diff --git a/docs/resources/glossary/geodesic-shell.md b/docs/resources/glossary/geodesic-shell.mdx similarity index 100% rename from docs/resources/glossary/geodesic-shell.md rename to docs/resources/glossary/geodesic-shell.mdx diff --git a/docs/resources/glossary/geodesic.md b/docs/resources/glossary/geodesic.mdx similarity index 100% rename from docs/resources/glossary/geodesic.md rename to docs/resources/glossary/geodesic.mdx diff --git a/docs/resources/glossary/git-workflow.md b/docs/resources/glossary/git-workflow.mdx similarity index 100% rename from docs/resources/glossary/git-workflow.md rename to docs/resources/glossary/git-workflow.mdx diff --git a/docs/resources/glossary/goofys.md b/docs/resources/glossary/goofys.mdx similarity index 100% rename from docs/resources/glossary/goofys.md rename to docs/resources/glossary/goofys.mdx diff --git a/docs/resources/glossary/hcl.md b/docs/resources/glossary/hcl.mdx similarity index 100% rename from docs/resources/glossary/hcl.md rename to docs/resources/glossary/hcl.mdx diff --git a/docs/resources/glossary/helm-chart.md b/docs/resources/glossary/helm-chart.mdx similarity index 100% rename from docs/resources/glossary/helm-chart.md rename to docs/resources/glossary/helm-chart.mdx diff --git a/docs/resources/glossary/helm-tiller.md b/docs/resources/glossary/helm-tiller.mdx similarity index 100% rename from docs/resources/glossary/helm-tiller.md rename to docs/resources/glossary/helm-tiller.mdx diff --git a/docs/resources/glossary/helm.md b/docs/resources/glossary/helm.mdx similarity index 100% rename from docs/resources/glossary/helm.md rename to docs/resources/glossary/helm.mdx diff --git a/docs/resources/glossary/iam.md b/docs/resources/glossary/iam.mdx similarity index 100% rename from docs/resources/glossary/iam.md rename to docs/resources/glossary/iam.mdx diff --git a/docs/resources/glossary/iap.md b/docs/resources/glossary/iap.mdx similarity index 100% rename from docs/resources/glossary/iap.md rename to docs/resources/glossary/iap.mdx diff --git a/docs/resources/glossary/imperative.md b/docs/resources/glossary/imperative.mdx similarity index 100% rename from docs/resources/glossary/imperative.md rename to docs/resources/glossary/imperative.mdx diff --git a/docs/resources/glossary/infrastructure-as-code.md b/docs/resources/glossary/infrastructure-as-code.mdx similarity index 100% rename from docs/resources/glossary/infrastructure-as-code.md rename to docs/resources/glossary/infrastructure-as-code.mdx diff --git a/docs/resources/glossary/infrastructure.md b/docs/resources/glossary/infrastructure.mdx similarity index 100% rename from docs/resources/glossary/infrastructure.md rename to docs/resources/glossary/infrastructure.mdx diff --git a/docs/resources/glossary/ingress-controller.md b/docs/resources/glossary/ingress-controller.mdx similarity index 100% rename from docs/resources/glossary/ingress-controller.md rename to docs/resources/glossary/ingress-controller.mdx diff --git a/docs/resources/glossary/init-terraform.md b/docs/resources/glossary/init-terraform.mdx similarity index 100% rename from docs/resources/glossary/init-terraform.md rename to docs/resources/glossary/init-terraform.mdx diff --git a/docs/resources/glossary/interpolation.md b/docs/resources/glossary/interpolation.mdx similarity index 100% rename from docs/resources/glossary/interpolation.md rename to docs/resources/glossary/interpolation.mdx diff --git a/docs/resources/glossary/jq.md b/docs/resources/glossary/jq.mdx similarity index 100% rename from docs/resources/glossary/jq.md rename to docs/resources/glossary/jq.mdx diff --git a/docs/resources/glossary/kanban.md b/docs/resources/glossary/kanban.mdx similarity index 100% rename from docs/resources/glossary/kanban.md rename to docs/resources/glossary/kanban.mdx diff --git a/docs/resources/glossary/kms.md b/docs/resources/glossary/kms.mdx similarity index 100% rename from docs/resources/glossary/kms.md rename to docs/resources/glossary/kms.mdx diff --git a/docs/resources/glossary/kops.md b/docs/resources/glossary/kops.mdx similarity index 100% rename from docs/resources/glossary/kops.md rename to docs/resources/glossary/kops.mdx diff --git a/docs/resources/glossary/kpi.md b/docs/resources/glossary/kpi.mdx similarity index 100% rename from docs/resources/glossary/kpi.md rename to docs/resources/glossary/kpi.mdx diff --git a/docs/resources/glossary/kubectl.md b/docs/resources/glossary/kubectl.mdx similarity index 100% rename from docs/resources/glossary/kubectl.md rename to docs/resources/glossary/kubectl.mdx diff --git a/docs/resources/glossary/kubernetes.md b/docs/resources/glossary/kubernetes.mdx similarity index 100% rename from docs/resources/glossary/kubernetes.md rename to docs/resources/glossary/kubernetes.mdx diff --git a/docs/resources/glossary/lambda.md b/docs/resources/glossary/lambda.mdx similarity index 100% rename from docs/resources/glossary/lambda.md rename to docs/resources/glossary/lambda.mdx diff --git a/docs/resources/glossary/layer-7.md b/docs/resources/glossary/layer-7.mdx similarity index 100% rename from docs/resources/glossary/layer-7.md rename to docs/resources/glossary/layer-7.mdx diff --git a/docs/resources/glossary/mfa.md b/docs/resources/glossary/mfa.mdx similarity index 100% rename from docs/resources/glossary/mfa.md rename to docs/resources/glossary/mfa.mdx diff --git a/docs/resources/glossary/monorepo.md b/docs/resources/glossary/monorepo.mdx similarity index 100% rename from docs/resources/glossary/monorepo.md rename to docs/resources/glossary/monorepo.mdx diff --git a/docs/resources/glossary/oce.md b/docs/resources/glossary/oce.mdx similarity index 100% rename from docs/resources/glossary/oce.md rename to docs/resources/glossary/oce.mdx diff --git a/docs/resources/glossary/osi.md b/docs/resources/glossary/osi.mdx similarity index 100% rename from docs/resources/glossary/osi.md rename to docs/resources/glossary/osi.mdx diff --git a/docs/resources/glossary/paas.md b/docs/resources/glossary/paas.mdx similarity index 100% rename from docs/resources/glossary/paas.md rename to docs/resources/glossary/paas.mdx diff --git a/docs/resources/glossary/pagerduty.md b/docs/resources/glossary/pagerduty.mdx similarity index 100% rename from docs/resources/glossary/pagerduty.md rename to docs/resources/glossary/pagerduty.mdx diff --git a/docs/resources/glossary/parameter-store.md b/docs/resources/glossary/parameter-store.mdx similarity index 100% rename from docs/resources/glossary/parameter-store.md rename to docs/resources/glossary/parameter-store.mdx diff --git a/docs/resources/glossary/pingdom.md b/docs/resources/glossary/pingdom.mdx similarity index 100% rename from docs/resources/glossary/pingdom.md rename to docs/resources/glossary/pingdom.mdx diff --git a/docs/resources/glossary/polyrepo.md b/docs/resources/glossary/polyrepo.mdx similarity index 100% rename from docs/resources/glossary/polyrepo.md rename to docs/resources/glossary/polyrepo.mdx diff --git a/docs/resources/glossary/rds.md b/docs/resources/glossary/rds.mdx similarity index 100% rename from docs/resources/glossary/rds.md rename to docs/resources/glossary/rds.mdx diff --git a/docs/resources/glossary/release-engineering.md b/docs/resources/glossary/release-engineering.mdx similarity index 100% rename from docs/resources/glossary/release-engineering.md rename to docs/resources/glossary/release-engineering.mdx diff --git a/docs/resources/glossary/root-module.md b/docs/resources/glossary/root-module.mdx similarity index 100% rename from docs/resources/glossary/root-module.md rename to docs/resources/glossary/root-module.mdx diff --git a/docs/resources/glossary/s3-bucket.md b/docs/resources/glossary/s3-bucket.mdx similarity index 100% rename from docs/resources/glossary/s3-bucket.md rename to docs/resources/glossary/s3-bucket.mdx diff --git a/docs/resources/glossary/s3.md b/docs/resources/glossary/s3.mdx similarity index 100% rename from docs/resources/glossary/s3.md rename to docs/resources/glossary/s3.mdx diff --git a/docs/resources/glossary/s3fs.md b/docs/resources/glossary/s3fs.mdx similarity index 100% rename from docs/resources/glossary/s3fs.md rename to docs/resources/glossary/s3fs.mdx diff --git a/docs/resources/glossary/saas.md b/docs/resources/glossary/saas.mdx similarity index 100% rename from docs/resources/glossary/saas.md rename to docs/resources/glossary/saas.mdx diff --git a/docs/resources/glossary/sandbox.md b/docs/resources/glossary/sandbox.mdx similarity index 100% rename from docs/resources/glossary/sandbox.md rename to docs/resources/glossary/sandbox.mdx diff --git a/docs/resources/glossary/sdlc.md b/docs/resources/glossary/sdlc.mdx similarity index 100% rename from docs/resources/glossary/sdlc.md rename to docs/resources/glossary/sdlc.mdx diff --git a/docs/resources/glossary/semver.md b/docs/resources/glossary/semver.mdx similarity index 100% rename from docs/resources/glossary/semver.md rename to docs/resources/glossary/semver.mdx diff --git a/docs/resources/glossary/sidekick-containers.md b/docs/resources/glossary/sidekick-containers.mdx similarity index 100% rename from docs/resources/glossary/sidekick-containers.md rename to docs/resources/glossary/sidekick-containers.mdx diff --git a/docs/resources/glossary/sla.md b/docs/resources/glossary/sla.mdx similarity index 100% rename from docs/resources/glossary/sla.md rename to docs/resources/glossary/sla.mdx diff --git a/docs/resources/glossary/slack.md b/docs/resources/glossary/slack.mdx similarity index 100% rename from docs/resources/glossary/slack.md rename to docs/resources/glossary/slack.mdx diff --git a/docs/resources/glossary/sme.md b/docs/resources/glossary/sme.mdx similarity index 100% rename from docs/resources/glossary/sme.md rename to docs/resources/glossary/sme.mdx diff --git a/docs/resources/glossary/sns.md b/docs/resources/glossary/sns.mdx similarity index 100% rename from docs/resources/glossary/sns.md rename to docs/resources/glossary/sns.mdx diff --git a/docs/resources/glossary/ssm.md b/docs/resources/glossary/ssm.mdx similarity index 100% rename from docs/resources/glossary/ssm.md rename to docs/resources/glossary/ssm.mdx diff --git a/docs/resources/glossary/sso.md b/docs/resources/glossary/sso.mdx similarity index 100% rename from docs/resources/glossary/sso.md rename to docs/resources/glossary/sso.mdx diff --git a/docs/resources/glossary/stage.md b/docs/resources/glossary/stage.mdx similarity index 100% rename from docs/resources/glossary/stage.md rename to docs/resources/glossary/stage.mdx diff --git a/docs/resources/glossary/synthetic-monitoring.md b/docs/resources/glossary/synthetic-monitoring.mdx similarity index 100% rename from docs/resources/glossary/synthetic-monitoring.md rename to docs/resources/glossary/synthetic-monitoring.mdx diff --git a/docs/resources/glossary/technical-debt.md b/docs/resources/glossary/technical-debt.mdx similarity index 100% rename from docs/resources/glossary/technical-debt.md rename to docs/resources/glossary/technical-debt.mdx diff --git a/docs/resources/glossary/terraform.md b/docs/resources/glossary/terraform.mdx similarity index 100% rename from docs/resources/glossary/terraform.md rename to docs/resources/glossary/terraform.mdx diff --git a/docs/resources/glossary/topology.md b/docs/resources/glossary/topology.mdx similarity index 100% rename from docs/resources/glossary/topology.md rename to docs/resources/glossary/topology.mdx diff --git a/docs/resources/glossary/unlimited-staging-environments.md b/docs/resources/glossary/unlimited-staging-environments.mdx similarity index 100% rename from docs/resources/glossary/unlimited-staging-environments.md rename to docs/resources/glossary/unlimited-staging-environments.mdx diff --git a/docs/resources/glossary/vpc.md b/docs/resources/glossary/vpc.mdx similarity index 100% rename from docs/resources/glossary/vpc.md rename to docs/resources/glossary/vpc.mdx diff --git a/docs/resources/glossary/wikiops.md b/docs/resources/glossary/wikiops.mdx similarity index 100% rename from docs/resources/glossary/wikiops.md rename to docs/resources/glossary/wikiops.mdx diff --git a/docs/resources/glossary/yaml.md b/docs/resources/glossary/yaml.mdx similarity index 100% rename from docs/resources/glossary/yaml.md rename to docs/resources/glossary/yaml.mdx diff --git a/docs/resources/glossary/yq.md b/docs/resources/glossary/yq.mdx similarity index 100% rename from docs/resources/glossary/yq.md rename to docs/resources/glossary/yq.mdx diff --git a/docs/resources/legacy/code-of-conduct.md b/docs/resources/legacy/code-of-conduct.mdx similarity index 100% rename from docs/resources/legacy/code-of-conduct.md rename to docs/resources/legacy/code-of-conduct.mdx diff --git a/docs/resources/legacy/demo-applications.md b/docs/resources/legacy/demo-applications.mdx similarity index 100% rename from docs/resources/legacy/demo-applications.md rename to docs/resources/legacy/demo-applications.mdx diff --git a/docs/resources/legacy/fundamentals/atmos.md b/docs/resources/legacy/fundamentals/atmos.mdx similarity index 100% rename from docs/resources/legacy/fundamentals/atmos.md rename to docs/resources/legacy/fundamentals/atmos.mdx diff --git a/docs/resources/legacy/fundamentals/building-blocks.md b/docs/resources/legacy/fundamentals/building-blocks.mdx similarity index 100% rename from docs/resources/legacy/fundamentals/building-blocks.md rename to docs/resources/legacy/fundamentals/building-blocks.mdx diff --git a/docs/resources/legacy/fundamentals/concepts.md b/docs/resources/legacy/fundamentals/concepts.mdx similarity index 100% rename from docs/resources/legacy/fundamentals/concepts.md rename to docs/resources/legacy/fundamentals/concepts.mdx diff --git a/docs/resources/legacy/fundamentals/geodesic.md b/docs/resources/legacy/fundamentals/geodesic.mdx similarity index 100% rename from docs/resources/legacy/fundamentals/geodesic.md rename to docs/resources/legacy/fundamentals/geodesic.mdx diff --git a/docs/resources/legacy/fundamentals/introduction.md b/docs/resources/legacy/fundamentals/introduction.mdx similarity index 100% rename from docs/resources/legacy/fundamentals/introduction.md rename to docs/resources/legacy/fundamentals/introduction.mdx diff --git a/docs/resources/legacy/fundamentals/leapp.md b/docs/resources/legacy/fundamentals/leapp.mdx similarity index 100% rename from docs/resources/legacy/fundamentals/leapp.md rename to docs/resources/legacy/fundamentals/leapp.mdx diff --git a/docs/resources/legacy/fundamentals/philosophy.md b/docs/resources/legacy/fundamentals/philosophy.mdx similarity index 100% rename from docs/resources/legacy/fundamentals/philosophy.md rename to docs/resources/legacy/fundamentals/philosophy.mdx diff --git a/docs/resources/legacy/fundamentals/stacks.md b/docs/resources/legacy/fundamentals/stacks.mdx similarity index 100% rename from docs/resources/legacy/fundamentals/stacks.md rename to docs/resources/legacy/fundamentals/stacks.mdx diff --git a/docs/resources/legacy/fundamentals/terraform.md b/docs/resources/legacy/fundamentals/terraform.mdx similarity index 100% rename from docs/resources/legacy/fundamentals/terraform.md rename to docs/resources/legacy/fundamentals/terraform.mdx diff --git a/docs/resources/legacy/helm.md b/docs/resources/legacy/helm.mdx similarity index 100% rename from docs/resources/legacy/helm.md rename to docs/resources/legacy/helm.mdx diff --git a/docs/resources/legacy/how-to-integrate-statuspage.md b/docs/resources/legacy/how-to-integrate-statuspage.mdx similarity index 100% rename from docs/resources/legacy/how-to-integrate-statuspage.md rename to docs/resources/legacy/how-to-integrate-statuspage.mdx diff --git a/docs/resources/legacy/howto/geodesic/authenticate-with-aws-vault.md b/docs/resources/legacy/howto/geodesic/authenticate-with-aws-vault.mdx similarity index 100% rename from docs/resources/legacy/howto/geodesic/authenticate-with-aws-vault.md rename to docs/resources/legacy/howto/geodesic/authenticate-with-aws-vault.mdx diff --git a/docs/resources/legacy/howto/geodesic/authenticate-with-leapp.md b/docs/resources/legacy/howto/geodesic/authenticate-with-leapp.mdx similarity index 100% rename from docs/resources/legacy/howto/geodesic/authenticate-with-leapp.md rename to docs/resources/legacy/howto/geodesic/authenticate-with-leapp.mdx diff --git a/docs/resources/legacy/howto/updating-modules-for-terraform-14.md b/docs/resources/legacy/howto/updating-modules-for-terraform-14.mdx similarity index 100% rename from docs/resources/legacy/howto/updating-modules-for-terraform-14.md rename to docs/resources/legacy/howto/updating-modules-for-terraform-14.mdx diff --git a/docs/resources/legacy/intro.md b/docs/resources/legacy/intro.mdx similarity index 100% rename from docs/resources/legacy/intro.md rename to docs/resources/legacy/intro.mdx diff --git a/docs/resources/legacy/kubernetes.md b/docs/resources/legacy/kubernetes.mdx similarity index 100% rename from docs/resources/legacy/kubernetes.md rename to docs/resources/legacy/kubernetes.mdx diff --git a/docs/resources/legacy/learning-resources.md b/docs/resources/legacy/learning-resources.mdx similarity index 100% rename from docs/resources/legacy/learning-resources.md rename to docs/resources/legacy/learning-resources.mdx diff --git a/docs/resources/legacy/lens.md b/docs/resources/legacy/lens.mdx similarity index 100% rename from docs/resources/legacy/lens.md rename to docs/resources/legacy/lens.mdx diff --git a/docs/resources/legacy/operational-readiness.md b/docs/resources/legacy/operational-readiness.mdx similarity index 100% rename from docs/resources/legacy/operational-readiness.md rename to docs/resources/legacy/operational-readiness.mdx diff --git a/docs/resources/legacy/remote-developer-environments-comparative-analysis-of-tools.md b/docs/resources/legacy/remote-developer-environments-comparative-analysis-of-tools.mdx similarity index 100% rename from docs/resources/legacy/remote-developer-environments-comparative-analysis-of-tools.md rename to docs/resources/legacy/remote-developer-environments-comparative-analysis-of-tools.mdx diff --git a/docs/reference/integrations/spotinst/how-to-tune-spotinst-parameters-for-eks.md b/docs/resources/legacy/spotinst/how-to-tune-spotinst-parameters-for-eks.mdx similarity index 100% rename from docs/reference/integrations/spotinst/how-to-tune-spotinst-parameters-for-eks.md rename to docs/resources/legacy/spotinst/how-to-tune-spotinst-parameters-for-eks.mdx diff --git a/docs/reference/integrations/spotinst/spotinst.md b/docs/resources/legacy/spotinst/spotinst.mdx similarity index 100% rename from docs/reference/integrations/spotinst/spotinst.md rename to docs/resources/legacy/spotinst/spotinst.mdx diff --git a/docs/resources/legacy/stacks.md b/docs/resources/legacy/stacks.mdx similarity index 100% rename from docs/resources/legacy/stacks.md rename to docs/resources/legacy/stacks.mdx diff --git a/docs/resources/legacy/troubleshooting.md b/docs/resources/legacy/troubleshooting.mdx similarity index 100% rename from docs/resources/legacy/troubleshooting.md rename to docs/resources/legacy/troubleshooting.mdx diff --git a/docs/resources/legacy/tutorials/atmos-getting-started.md b/docs/resources/legacy/tutorials/atmos-getting-started.mdx similarity index 100% rename from docs/resources/legacy/tutorials/atmos-getting-started.md rename to docs/resources/legacy/tutorials/atmos-getting-started.mdx diff --git a/docs/resources/legacy/tutorials/geodesic-getting-started.md b/docs/resources/legacy/tutorials/geodesic-getting-started.mdx similarity index 100% rename from docs/resources/legacy/tutorials/geodesic-getting-started.md rename to docs/resources/legacy/tutorials/geodesic-getting-started.mdx diff --git a/docs/resources/legacy/terraform-in-depth/_category_.json b/docs/resources/terraform-in-depth/_category_.json similarity index 100% rename from docs/resources/legacy/terraform-in-depth/_category_.json rename to docs/resources/terraform-in-depth/_category_.json diff --git a/docs/resources/legacy/terraform-in-depth/terraform-count-vs-for-each.md b/docs/resources/terraform-in-depth/terraform-count-vs-for-each.mdx similarity index 98% rename from docs/resources/legacy/terraform-in-depth/terraform-count-vs-for-each.md rename to docs/resources/terraform-in-depth/terraform-count-vs-for-each.mdx index 849464e71..e98f92838 100644 --- a/docs/resources/legacy/terraform-in-depth/terraform-count-vs-for-each.md +++ b/docs/resources/terraform-in-depth/terraform-count-vs-for-each.mdx @@ -11,21 +11,24 @@ categories: - "Terraform" - "Terraform in Depth" --- +import Intro from '@site/src/components/Intro'; +import Note from '@site/src/components/Note'; +import PillBox from '@site/src/components/PillBox'; -![Terraform](/assets/08bcd99-terraform.png) - -# Terraform in Depth +Terraform in Depth + This article is part of our "Terraform in Depth" series, where we dive into the details of Terraform that require a deeper understanding and longer explanation than are required for our other Terraform articles. -## Count vs For Each - When you are dynamically creating multiple instances of a resource in Terraform, you have two options: `count` and `for_each`. Both of these options allow you to create multiple instances of a resource, but they have different use cases and different implications for your Terraform code. + + +![Terraform](/assets/08bcd99-terraform.png) There are 2 key considerations when using `count` or `for_each`: @@ -37,7 +40,9 @@ There are 2 key considerations when using `count` or `for_each`: they have moved to a new address. Using `for_each` usually avoids this issue. This is discussed further below. -The tl;dr: Use `for_each` when possible, and `count` when you can't use `for_each`. + +Use `for_each` when possible, and `count` when you can't use `for_each`. + ### Background: Terraform Resource Addressing diff --git a/docs/resources/legacy/terraform-in-depth/terraform-in-depth.md b/docs/resources/terraform-in-depth/terraform-in-depth.mdx similarity index 64% rename from docs/resources/legacy/terraform-in-depth/terraform-in-depth.md rename to docs/resources/terraform-in-depth/terraform-in-depth.mdx index 17e8b0a2d..5552beb66 100644 --- a/docs/resources/legacy/terraform-in-depth/terraform-in-depth.md +++ b/docs/resources/terraform-in-depth/terraform-in-depth.mdx @@ -1,8 +1,10 @@ --- -title: "Category Introduction" +title: "Terraform in Depth" +sidebar_label: "Terraform in Depth" description: "Deep dive into Terraform implementation details and pitfalls" slug: "terraform-in-depth" sidebar_position: 1 +sidebar_class_name: hidden tags: - "Best Practices" - "Terraform" @@ -10,10 +12,13 @@ categories: - "Community Resources" - "Terraform" --- +import Intro from '@site/src/components/Intro' -![Terraform](/assets/08bcd99-terraform.png) + +In this section, we dive into advanced details of Terraform that require a deeper understanding of Terraform and longer explanation than are required for the other articles. + -# Terraform in Depth +![Terraform](/assets/08bcd99-terraform.png) We provide a lot of information about how to use Terraform and write Terraform code elsewhere on this site: @@ -21,6 +26,3 @@ We provide a lot of information about how to use Terraform and write Terraform c - [Terraform Best Practices](/reference/best-practices/terraform-best-practices.md) - [Terraform Tips and Tricks](/reference/best-practices/terraform-tips-tricks.md) -In the articles in this section, we dive into advanced details of Terraform -that require a deeper understanding of Terraform and longer explanation than -are required for the other articles. diff --git a/docs/resources/legacy/terraform-in-depth/terraform-unknown-at-plan-time.md b/docs/resources/terraform-in-depth/terraform-unknown-at-plan-time.mdx similarity index 98% rename from docs/resources/legacy/terraform-in-depth/terraform-unknown-at-plan-time.md rename to docs/resources/terraform-in-depth/terraform-unknown-at-plan-time.mdx index fd098ef63..f3fa55da9 100644 --- a/docs/resources/legacy/terraform-in-depth/terraform-unknown-at-plan-time.md +++ b/docs/resources/terraform-in-depth/terraform-unknown-at-plan-time.mdx @@ -11,10 +11,13 @@ categories: - "Terraform" - "Terraform in Depth" --- +import Intro from '@site/src/components/Intro'; +import Note from '@site/src/components/Note'; +import PillBox from '@site/src/components/PillBox'; -![Terraform](/assets/08bcd99-terraform.png) +Terraform in Depth -# Terraform in Depth +![Terraform](/assets/08bcd99-terraform.png) This article is part of our [Terraform in Depth](/category/terraform-in-depth) series, where we dive into diff --git a/docs/best-practices/docker-tips-tricks.md b/docs/tips-and-tricks/docker-tips-tricks.mdx similarity index 93% rename from docs/best-practices/docker-tips-tricks.md rename to docs/tips-and-tricks/docker-tips-tricks.mdx index 8d579c86c..f628b89dd 100644 --- a/docs/best-practices/docker-tips-tricks.md +++ b/docs/tips-and-tricks/docker-tips-tricks.mdx @@ -1,10 +1,13 @@ --- title: Docker Tips & Tricks +sidebar_label: Docker description: "Here's a collection of some nice little hacks for docker." tags: - Docker - tips-and-tricks --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; Here's a collection of some nice little hacks for docker. A lot of them are related to house keeping. diff --git a/docs/resources/legacy/github-actions.md b/docs/tips-and-tricks/github-actions.mdx similarity index 91% rename from docs/resources/legacy/github-actions.md rename to docs/tips-and-tricks/github-actions.mdx index bb65164d8..dbc5ee1af 100644 --- a/docs/resources/legacy/github-actions.md +++ b/docs/tips-and-tricks/github-actions.mdx @@ -1,29 +1,30 @@ --- -title: "GitHub Actions" +title: "GitHub Actions Tips & Tricks" +sidebar_label: "GitHub Actions" confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1187741784/GitHub+Actions sidebar_position: 100 custom_edit_url: https://github.com/cloudposse/refarch-scaffold/tree/main/docs/docs/reference/github-actions.md --- - -# GitHub Actions +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ## Related Components -- [github-runners](/components/library/aws/github-runners/) +- [github-runners](/components/library/aws/github-runners/) ## Security -[https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository) +[https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository) -[https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions) +[https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions) ## Tips & Tricks ### Write Complex Steps in `github-script` -Rather than try some impossible concoction of YAML, use typescript to define your CI/CD logic. +Rather than try some impossible concoction of YAML, use typescript to define your CI/CD logic. [https://github.com/actions/github-script](https://github.com/actions/github-script) ### Easily Write Files in Workflows -The `1arp/create-a-file-action` action is convenient for writing files. +The `1arp/create-a-file-action` action is convenient for writing files. ``` - name: Create ${{ steps.vars.outputs.argocd_app_root }}/config.yaml @@ -42,7 +43,7 @@ The `1arp/create-a-file-action` action is convenient for writing files. :::info **GitHub Enterprise** users can now use private actions natively within the organization. -[https://github.blog/changelog/2022-01-21-share-github-actions-within-your-enterprise/](https://github.blog/changelog/2022-01-21-share-github-actions-within-your-enterprise/) +[https://github.blog/changelog/2022-01-21-share-github-actions-within-your-enterprise/](https://github.blog/changelog/2022-01-21-share-github-actions-within-your-enterprise/) ::: @@ -53,7 +54,7 @@ The `1arp/create-a-file-action` action is convenient for writing files. repository: acme/actions path: ./.github/actions token: ${{ secrets.CROSS_REPO_TOKEN }} - + - name: Hello World uses: ./.github/actions/hello-world id: hello-world @@ -84,7 +85,7 @@ on: ## Known Limitations -There are a lot of _non-obvious_ limitations when working with GitHub Actions. Here are the ones we’ve been bit by in developing workflows. Also, make sure to check out the [Public Roadmap](https://github.com/orgs/github/projects/4247/views/2?filterQuery=label%3Aactions) for GHA. +There are a lot of _non-obvious_ limitations when working with GitHub Actions. Here are the ones we’ve been bit by in developing workflows. Also, make sure to check out the [Public Roadmap](https://github.com/orgs/github/projects/4247/views/2?filterQuery=label%3Aactions) for GHA. ### Roadmap Items @@ -102,19 +103,19 @@ These are some roadmap items we’re excited to see implemented: - Set in GitHub Actions running on self-hosted runner hangs indefinitely. Nothing meaningful in logs. The issue may be due to higher resource requirements for the `summerwind/actions-runner-dind` GHA runner. Increasing the resources may resolve the issue. -- Not all event types will run off of branches. Learn more here [https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows](https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows) +- Not all event types will run off of branches. Learn more here [https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows](https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows) - A single workflow cannot build and then `use` the derived docker image. Docker image must exist before workflow is started. -- Workflow approval steps are a GitHub Enterprise feature. [https://docs.github.com/en/actions/managing-workflow-runs/reviewing-deployments](https://docs.github.com/en/actions/managing-workflow-runs/reviewing-deployments) +- Workflow approval steps are a GitHub Enterprise feature. [https://docs.github.com/en/actions/managing-workflow-runs/reviewing-deployments](https://docs.github.com/en/actions/managing-workflow-runs/reviewing-deployments) - GitHub Actions can only be used from public repos unless using GitHub Enterprise with an “enterprise” account to support `internal` (not “private”) repositories. To use in private repos, you need to `git clone` the repo and `use` the local path to the action. -[https://github.blog/changelog/2022-01-21-share-github-actions-within-your-enterprise/](https://github.blog/changelog/2022-01-21-share-github-actions-within-your-enterprise/) +[https://github.blog/changelog/2022-01-21-share-github-actions-within-your-enterprise/](https://github.blog/changelog/2022-01-21-share-github-actions-within-your-enterprise/) [https://github.com/github/roadmap/issues/254](https://github.com/github/roadmap/issues/254) [https://github.com/github/roadmap/issues/74](https://github.com/github/roadmap/issues/74) -- GitHub Actions cron jobs automatically disable after 60 days of inactivity (no new commits) [https://docs.github.com/en/actions/managing-workflow-runs/disabling-and-enabling-a-workflow](https://docs.github.com/en/actions/managing-workflow-runs/disabling-and-enabling-a-workflow) +- GitHub Actions cron jobs automatically disable after 60 days of inactivity (no new commits) [https://docs.github.com/en/actions/managing-workflow-runs/disabling-and-enabling-a-workflow](https://docs.github.com/en/actions/managing-workflow-runs/disabling-and-enabling-a-workflow) - The `GITHUB_TOKEN` is scoped to only permit operations on the _current_ repo of the GitHub Action workflow @@ -125,9 +126,9 @@ These are some roadmap items we’re excited to see implemented: ### Composite Actions - ~~Composite actions do not support~~ `if` conditional. [https://github.com/actions/runner/issues/834](https://github.com/actions/runner/issues/834) -Update! Released 2021-11-09 [https://github.blog/changelog/2021-11-09-github-actions-conditional-execution-of-steps-in-actions/](https://github.blog/changelog/2021-11-09-github-actions-conditional-execution-of-steps-in-actions/) +Update! Released 2021-11-09 [https://github.blog/changelog/2021-11-09-github-actions-conditional-execution-of-steps-in-actions/](https://github.blog/changelog/2021-11-09-github-actions-conditional-execution-of-steps-in-actions/) -- Composite actions do not support post-run capabilities [https://github.community/t/no-post-run-capability-for-composite-actions/139046/4](https://github.community/t/no-post-run-capability-for-composite-actions/139046/4) +- Composite actions do not support post-run capabilities [https://github.community/t/no-post-run-capability-for-composite-actions/139046/4](https://github.community/t/no-post-run-capability-for-composite-actions/139046/4) - ~~Composite actions cannot call other composite actions~~ [https://github.com/actions/runner/issues/862](https://github.com/actions/runner/issues/862) @@ -136,9 +137,9 @@ Update! Released 2021-11-09 [https://github.blog/changelog/2021-11-09-github-act - [https://github.com/actions/runner/issues/1348](https://github.com/actions/runner/issues/1348) -### Shared Workflows +### Shared Workflows -- GitHub Actions shared workflows can only be private in GitHub Enterprise using an `internal` (not `private`) repo.. [https://docs.github.com/en/actions/learn-github-actions/reusing-workflows](https://docs.github.com/en/actions/learn-github-actions/reusing-workflows) +- GitHub Actions shared workflows can only be private in GitHub Enterprise using an `internal` (not `private`) repo.. [https://docs.github.com/en/actions/learn-github-actions/reusing-workflows](https://docs.github.com/en/actions/learn-github-actions/reusing-workflows) - Private reusable workflows is in the GitHub Roadmap [https://github.com/github/roadmap/issues/51](https://github.com/github/roadmap/issues/51) @@ -156,7 +157,7 @@ Update! Released 2021-11-09 [https://github.blog/changelog/2021-11-09-github-act - Helpful github actions by ReviewDog [https://github.com/reviewdog/reviewdog](https://github.com/reviewdog/reviewdog) -- `deployment` documentation [https://docs.github.com/en/rest/reference/deployments](https://docs.github.com/en/rest/reference/deployments) , [https://docs.github.com/en/rest/reference/deployments#create-a-deployment](https://docs.github.com/en/rest/reference/deployments#create-a-deployment) +- `deployment` documentation [https://docs.github.com/en/rest/reference/deployments](https://docs.github.com/en/rest/reference/deployments) , [https://docs.github.com/en/rest/reference/deployments#create-a-deployment](https://docs.github.com/en/rest/reference/deployments#create-a-deployment) - [GitHub Actions Public Roadmap](https://github.com/orgs/github/projects/4247/views/2?filterQuery=label%3Aactions) diff --git a/docs/best-practices/terraform-tips-tricks.md b/docs/tips-and-tricks/terraform.mdx similarity index 96% rename from docs/best-practices/terraform-tips-tricks.md rename to docs/tips-and-tricks/terraform.mdx index 612970c5b..1a125e889 100644 --- a/docs/best-practices/terraform-tips-tricks.md +++ b/docs/tips-and-tricks/terraform.mdx @@ -1,11 +1,14 @@ --- title: "Terraform Tips & Tricks" +sidebar_label: "Terraform" description: "A small collection of helpful hints" tags: - terraform - "Tips & Tricks" - git --- +import Intro from '@site/src/components/Intro'; +import KeyPoints from '@site/src/components/KeyPoints'; ![Terraform](/assets/a1f105a-terraform.png) diff --git a/sidebars.js b/sidebars.js index 2b2581f4a..defc7762c 100644 --- a/sidebars.js +++ b/sidebars.js @@ -336,11 +336,15 @@ module.exports = { label: 'Terraform Components', className: 'sidebar-title', collapsible: true, - collapsed: true, + collapsed: false, + link: { + type: 'doc', + id: 'generated/components/index' + }, items: [ { type: 'autogenerated', - dirName: 'generated/components/library/aws', + dirName: 'generated/components/library', } ] }, @@ -349,7 +353,11 @@ module.exports = { label: 'Terraform Modules', className: 'sidebar-title', collapsible: true, - collapsed: true, + collapsed: false, + link: { + type: 'doc', + id: 'generated/modules/index' + }, items: [ { type: 'autogenerated', @@ -363,6 +371,10 @@ module.exports = { className: 'sidebar-title', collapsible: true, collapsed: true, + link: { + type: 'doc', + id: 'generated/github-actions/index' + }, items: [ { type: 'autogenerated', @@ -375,7 +387,7 @@ module.exports = { label: 'Resources', className: 'sidebar-title', collapsible: true, - collapsed: true, + collapsed: false, items: [ { type: 'autogenerated', @@ -395,7 +407,8 @@ module.exports = { items: [ 'community/slack', 'community/office-hours', 'community/contact-us', - 'community/support' ] + 'community/support', + 'community/faq' ] }, { type: 'category', diff --git a/src/css/custom.css b/src/css/custom.css index d0b5982d5..cdee0dbf0 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -111,7 +111,6 @@ table tr td { aspect-ratio: 16/9 !important; } - div > ul > li > a.table-of-contents__link.toc-highlight { font-weight: 600; } @@ -260,8 +259,7 @@ aside.col.col--3 { --ifm-col-width: calc(2.5 / 12 * 100%); } - -article { +div > article { min-height: 70vh; } @@ -272,3 +270,7 @@ article { .join-slack { background: #000; } + +.hidden { + display: none; +} diff --git a/src/css/figure.css b/src/css/figure.css new file mode 100644 index 000000000..90ffdf612 --- /dev/null +++ b/src/css/figure.css @@ -0,0 +1,13 @@ +figure figcaption { + font-size: 0.8em; + color: #666; + text-align: left; + font-style: italic; + margin-top: 0.4em; + line-height: 0.7em; +} + + +figure > div { + box-shadow: var(--ifm-alert-shadow); +} diff --git a/src/css/navbar.css b/src/css/navbar.css index 869c5046b..ec2ca998a 100644 --- a/src/css/navbar.css +++ b/src/css/navbar.css @@ -45,3 +45,7 @@ html[data-theme='dark'] nav.navbar { li > ul.menu__list { margin-left: 1em; } + +aside.theme-doc-sidebar-container button.button.button--secondary { + border: none; +} diff --git a/src/theme/DocCard/index.js b/src/theme/DocCard/index.js index 3eaa45c67..8805249ae 100644 --- a/src/theme/DocCard/index.js +++ b/src/theme/DocCard/index.js @@ -2,14 +2,33 @@ import React from 'react'; import clsx from 'clsx'; import Link from '@docusaurus/Link'; import { - findFirstCategoryLink, + findFirstSidebarItemLink, useDocById, } from '@docusaurus/theme-common/internal'; +import {usePluralForm} from '@docusaurus/theme-common'; import isInternalUrl from '@docusaurus/isInternalUrl'; import {translate} from '@docusaurus/Translate'; +import Heading from '@theme/Heading'; import styles from './styles.module.css'; +function useCategoryItemsPlural() { + const {selectMessage} = usePluralForm(); + return (count) => + selectMessage( + count, + translate( + { + message: '1 item|{count} items', + id: 'theme.docs.DocCard.categoryDescription.plurals', + description: + 'The default description for a category card in the generated index about how many items this category includes', + }, + {count}, + ), + ); +} function CardContainer({href, children}) { return ( + @@ -20,25 +39,12 @@ function CardContainer({href, children}) { function CardLayout({href, icon, title, description}) { return ( -

+ {icon} {title} -

- {description && ( -

- {description} -

- )} - - ); -} -function ImageCardLayout({href, icon, title, description}) { - return ( - -

- {title} -

+ {description && (

); } @@ -80,31 +79,14 @@ function CardLink({item}) { href={item.href} icon={icon} title={item.label} - description={doc?.description} - /> - ); -} -function ImageCardLink({item, image}) { - const doc = useDocById(item.docId ?? undefined); - return ( - ); } export default function DocCard({item}) { switch (item.type) { case 'link': - if(item.href.startsWith('/components/library/') || item.href.startsWith('/modules/library/')) { - return - } else if(item.href.startsWith('/github-actions/library/')) { - return - } else { - return ; - } + return ; case 'category': return ; default: diff --git a/src/theme/DocCard/styles.module.css b/src/theme/DocCard/styles.module.css index 1a4f84007..4f7ad27f4 100644 --- a/src/theme/DocCard/styles.module.css +++ b/src/theme/DocCard/styles.module.css @@ -1,9 +1,3 @@ -/** - * Copyright 2023 Cloud Posse, LLC - * - * This software is based on Docusaurus: Copyright 2022 - 2023 Facebook, Inc - */ - .cardContainer { --ifm-link-color: var(--ifm-color-emphasis-800); --ifm-link-hover-color: var(--ifm-color-emphasis-700); diff --git a/src/theme/DocCardList/index.js b/src/theme/DocCardList/index.js new file mode 100644 index 000000000..b82d975b0 --- /dev/null +++ b/src/theme/DocCardList/index.js @@ -0,0 +1,27 @@ +import React from 'react'; +import clsx from 'clsx'; +import { + useCurrentSidebarCategory, + filterDocCardListItems, +} from '@docusaurus/theme-common'; +import DocCard from '@theme/DocCard'; +function DocCardListForCurrentSidebarCategory({className}) { + const category = useCurrentSidebarCategory(); + return ; +} +export default function DocCardList(props) { + const {items, className} = props; + if (!items) { + return ; + } + const filteredItems = filterDocCardListItems(items); + return ( +

+ {filteredItems.map((item, index) => ( +
+ +
+ ))} +
+ ); +}