From 322d3d9833bbb516422153332039c8bcb8c7c405 Mon Sep 17 00:00:00 2001 From: "Erik Osterman (CEO @ Cloud Posse)" Date: Wed, 31 Jul 2024 22:06:46 -0500 Subject: [PATCH] Import Content (#627) * import gitops * New TagList component * fix keyboard shortcuts when other key combinations are pressed, broken links, index pages, etc * disable console.log * remove image sizes which are frequently wrong due to bad export from confluence * add missing file, update nav * disable console log * debug failures * debug failures * debug failures * debug failures * content updates * content updates * import spacelift docs --- docs/best-practices/best-practices.mdx | 2 + docs/best-practices/developer/developer.mdx | 1 - .../developer/editor-config.mdx | 5 +- .../github-sign-your-commits-with-ssh.mdx | 4 + docs/best-practices/developer/makefile.mdx | 3 +- docs/best-practices/developer/markdown.mdx | 3 + .../developer/password-management.mdx | 3 + docs/best-practices/developer/semver.mdx | 4 +- .../github/github-feature-branches.mdx | 4 + .../github/github-pull-requests.mdx | 4 +- docs/best-practices/github/github.mdx | 4 + docs/best-practices/terraform.mdx | 8 +- docs/community/code-of-conduct.mdx | 4 +- .../contribute/automated-testing.mdx | 4 + docs/community/contribute/code-reviews.mdx | 6 +- docs/community/contribute/contribute.mdx | 3 + .../community/contribute/contributor-tips.mdx | 4 + docs/community/contribute/faq.mdx | 5 +- docs/community/contribute/our-github.mdx | 2 + docs/community/office-hours.mdx | 3 + docs/community/slack.mdx | 3 + docs/community/support.mdx | 5 +- docs/components/library/library.mdx | 15 + docs/intro/for-agencies.mdx | 18 +- docs/intro/for-developers.mdx | 11 + docs/intro/for-enterprises.mdx | 40 ++ docs/intro/for-startups.mdx | 15 +- docs/intro/for-terraform-beginners.mdx | 11 + docs/intro/for-terraform-experts.mdx | 13 + docs/intro/{index.mdx => intro.mdx} | 22 +- docs/jumpstart/action-items.mdx | 1 + docs/jumpstart/faq.mdx | 2 + docs/jumpstart/jumpstart.mdx | 14 +- docs/jumpstart/kick-off.mdx | 2 +- docs/jumpstart/onboarding.mdx | 1 + docs/jumpstart/support.mdx | 2 +- ...how-to-provision-shared-slack-channels.mdx | 15 +- .../tutorials/offboarding-cloudposse.mdx | 10 +- docs/jumpstart/tutorials/tutorials.mdx | 3 + docs/layers/accounts/accounts.mdx | 22 +- docs/layers/accounts/initialize-tfstate.mdx | 5 +- docs/layers/accounts/tutorials/cold-start.mdx | 2 +- .../how-to-create-superadmin-user.mdx | 30 +- .../how-to-set-up-aws-email-notifications.mdx | 21 +- .../decide-on-default-schedules.mdx | 3 +- .../decide-on-incident-ruleset.mdx | 1 + .../decide-on-teams-for-escalations.mdx | 1 + .../design-decisions/design-decisions.mdx | 3 +- .../alerting/{08-alerting.mdx => setup.mdx} | 0 ...rch-service-elasticsearch-requirements.mdx | 4 +- ...how-to-setup-vanity-domains-on-alb-ecs.mdx | 2 +- ...how-to-setup-vanity-domains-on-alb-eks.mdx | 2 +- .../decide-on-regional-naming-scheme.mdx | 2 +- docs/layers/foundation/toolbox.mdx | 9 +- docs/layers/github-actions/github-actions.mdx | 2 +- docs/layers/gitops/gitops.mdx | 254 +++++++- .../gitops/{03-gitops.mdx => setup.mdx} | 56 +- .../identity/{ => aws-saml}/aws-saml.mdx | 4 +- ...etup-saml-login-to-aws-from-office-365.mdx | 0 .../layers/identity/{ => aws-sso}/aws-sso.mdx | 16 +- .../how-to-setup-office-365-aws-sso.mdx | 2 +- .../{idp => aws-sso}/office365/office365.mdx | 0 .../okta/how-to-setup-okta-aws-sso.mdx | 0 .../identity/{idp => aws-sso}/okta/okta.mdx | 0 .../identity/centralized-terraform-access.mdx | 2 +- docs/layers/identity/deploy.mdx | 2 +- .../design-decisions/design-decisions.mdx | 4 +- .../docs/aws-access-control-architecture.mdx | 7 +- .../docs/aws-access-control-evolution.mdx | 3 +- .../identity/docs/aws-access-control.mdx | 1 + .../docs/aws-restricting-admin-access.mdx | 1 + docs/layers/identity/docs/docs.mdx | 1 + .../identity/docs/dynamic-terraform-roles.mdx | 2 + docs/layers/identity/how-to-log-into-aws.mdx | 6 +- docs/layers/identity/idp/idp.mdx | 7 - ...how-to-easily-switch-aws-account-roles.mdx | 50 +- .../layers/identity/tutorials/leapp/leapp.mdx | 4 +- docs/layers/monitoring/datadog/datadog.mdx | 2 +- ...er-checks-and-network-monitors-for-ext.mdx | 8 +- .../access-network.mdx | 0 .../connect-network.mdx | 0 .../deploy-vpcs.mdx | 0 ...n-aws-account-vpc-subnet-cidr-strategy.mdx | 0 .../decide-on-cidr-allocation.mdx | 0 .../decide-on-client-vpn-options.mdx | 0 ...-hostname-scheme-for-service-discovery.mdx | 0 .../decide-on-how-to-support-tls.mdx | 0 .../decide-on-ipv4-and-ipv6-support.mdx | 0 ...ide-on-opting-into-non-default-regions.mdx | 0 ...e-on-organization-supernet-cidr-ranges.mdx | 4 +- .../decide-on-primary-aws-region.mdx | 0 .../decide-on-service-discovery-domain.mdx | 0 ...decide-on-transit-gateway-requirements.mdx | 0 .../decide-on-vanity-branded-domain.mdx | 0 .../decide-on-vpc-nat-strategy.mdx | 6 +- ...n-vpc-network-traffic-isolation-policy.mdx | 0 ...peering-requirements-e-g-to-legacy-env.mdx | 0 .../design-decisions/design-decisions.mdx | 0 .../dns-setup.mdx | 2 +- .../network.mdx} | 14 +- .../tutorials/tutorials.mdx | 0 ...decide-how-to-distribute-docker-images.mdx | 0 .../decide-on-argocd-architecture.mdx | 4 +- ...on-argocd-deployment-repo-architecture.mdx | 0 .../decide-on-branching-strategy.mdx | 0 .../decide-on-customer-apps-for-migration.mdx | 0 ...-strategy-for-ephemeral-preview-enviro.mdx | 0 ...actions-workflow-organization-strategy.mdx | 0 ...decide-on-hot-fix-or-rollback-strategy.mdx | 0 .../decide-on-how-ecs-apps-are-deployed.mdx | 0 ...de-on-kubernetes-application-artifacts.mdx | 0 .../decide-on-pipeline-strategy.mdx | 8 +- ...decide-on-release-engineering-strategy.mdx | 4 +- .../decide-on-release-promotion-strategy.mdx | 0 .../decide-on-repositories-strategy.mdx | 0 ...ding-strategy-for-staging-environments.mdx | 0 ...-on-self-hosted-github-runner-strategy.mdx | 0 ...on-strategy-for-continuous-integration.mdx | 0 ...on-strategy-for-developer-environments.mdx | 0 ...for-managing-and-orchestrating-secrets.mdx | 0 ...r-preview-environments-e-g-review-apps.mdx | 2 +- ...uration-pattern-for-application-reposi.mdx | 0 .../design-decisions/design-decisions.mdx | 0 .../ecs-ecspresso/ecs-ecspresso.mdx | 0 .../ecs-ecspresso/setup.mdx | 0 .../eks-argocd/eks-argocd.mdx | 2 +- .../eks-argocd/setup.mdx | 0 .../tutorials/github-commit-notifications.mdx | 0 .../tutorials/identity-center-apps.mdx | 0 .../eks-argocd/tutorials/pats.mdx | 0 .../eks-argocd/tutorials/tutorials.mdx | 0 .../lambda/lambda.mdx | 0 .../software-delivery.mdx} | 0 .../tutorials/_category_.json | 0 .../how-to-create-a-migration-checklist.mdx | 0 ...lift-will-use-external-private-modules.mdx | 2 +- ...t-administrative-stack-auto-deployment.mdx | 4 +- ...-on-spacelift-worker-pool-architecture.mdx | 5 +- docs/layers/spacelift/faq.mdx | 102 ++++ .../spacelift/{03-spacelift.mdx => setup.mdx} | 119 ++-- docs/layers/spacelift/spacelift.mdx | 396 ++++++++++++- ...ow-to-develop-with-spacelift-and-atmos.mdx | 2 +- ...ow-to-enable-spacelift-drift-detection.mdx | 2 +- ...-component-dependencies-with-spacelift.mdx | 152 ++--- .../how-to-scale-spacelift-runners.mdx | 7 +- .../spacelift/tutorials/how-to-sign-up.mdx | 186 ++---- docs/learn/component-development/faq.mdx | 10 +- .../terraform-count-vs-for-each.mdx | 12 +- .../terraform-in-depth/terraform-in-depth.mdx | 17 +- .../terraform-unknown-at-plan-time.mdx | 13 +- docs/learn/conventions.mdx | 8 +- docs/learn/maintenance/maintenance.mdx | 1 + ...-to-define-stacks-for-multiple-regions.mdx | 140 ++--- .../how-to-document-a-new-design-decision.mdx | 4 +- .../tutorials/how-to-load-test-in-aws.mdx | 4 +- ...pendencies-in-micro-service-repositori.mdx | 4 +- .../upgrades/how-to-upgrade-atmos.mdx | 2 +- .../learn/tips-and-tricks/tips-and-tricks.mdx | 2 +- docs/modules/modules.mdx | 2 +- docs/quickstart/action-items.mdx | 2 +- docs/quickstart/faq.mdx | 2 +- docs/quickstart/kickoff.mdx | 2 +- docs/quickstart/quickstart.mdx | 3 +- docs/quickstart/support.mdx | 2 +- docs/reference/LICENSE.mdx | 4 +- docs/reference/reference.mdx | 34 +- .../use-ssm-over-asm-for-infrastructure.mdx | 2 +- ...er-structure-for-compliance-components.mdx | 2 +- .../proposed/proposed-use-atmos-registry.mdx | 2 +- ...proposed-use-github-actions-with-atmos.mdx | 4 +- docs/resources/legacy/_category_.json | 8 - .../aws-feature-requests-and-limitations.mdx | 6 +- docs/resources/legacy/demo-applications.mdx | 10 +- .../decide-on-status-page-requirements.mdx | 2 +- .../legacy/fundamentals/geodesic.mdx | 26 +- .../legacy/fundamentals/terraform.mdx | 2 +- .../legacy/how-to-integrate-statuspage.mdx | 10 +- docs/resources/legacy/howto/_category_.json | 8 - docs/resources/legacy/intro.mdx | 6 +- docs/resources/legacy/lens.mdx | 12 +- ...ow-to-tune-spotinst-parameters-for-eks.mdx | 2 +- docs/resources/legacy/spotinst/spotinst.mdx | 8 +- docs/resources/legacy/tools.mdx | 16 +- .../aws-support.mdx} | 28 +- docs/support/customer-workshops.mdx | 15 + docs/support/github-discussions.mdx | 17 + docs/support/support.mdx | 3 + docs/tags.yml | 382 ++++++++++++ docusaurus.config.js | 69 ++- .../atmos-terraform-apply-matrix.yaml | 1 + .../workflows/atmos-terraform-apply.yaml | 1 + .../workflows/atmos-terraform-dispatch.yaml | 1 + .../atmos-terraform-drift-detection.yaml | 1 + .../atmos-terraform-drift-remediation.yaml | 1 + .../atmos-terraform-plan-matrix.yaml | 1 + .../workflows/atmos-terraform-plan.yaml | 1 + .../stacks/orgs/acme/plat/spacelift.yaml | 1 + .../snippets/stacks/orgs/acme/spacelift.yaml | 1 + package-lock.json | 559 ++++++++++++++++++ package.json | 1 + plugins/custom-loaders/index.js | 48 ++ scripts/docs-collator/ComponentRenderer.py | 3 +- sidebars.js | 22 +- src/components/ActionCard/index.js | 29 +- src/components/KeyboardShortcuts/index.js | 38 ++ src/components/Step/index.css | 4 + src/components/Steps/index.module.css | 23 +- src/components/TagList/index.js | 37 ++ src/css/sidebar.css | 6 + src/theme/DocCard/index.js | 24 +- src/theme/Layout/index.js | 12 + 211 files changed, 2864 insertions(+), 702 deletions(-) create mode 100644 docs/components/library/library.mdx rename docs/intro/{index.mdx => intro.mdx} (88%) rename docs/layers/alerting/{08-alerting.mdx => setup.mdx} (100%) rename docs/layers/gitops/{03-gitops.mdx => setup.mdx} (73%) rename docs/layers/identity/{ => aws-saml}/aws-saml.mdx (96%) rename docs/layers/identity/{idp/office365 => aws-saml}/how-to-setup-saml-login-to-aws-from-office-365.mdx (100%) rename docs/layers/identity/{ => aws-sso}/aws-sso.mdx (89%) rename docs/layers/identity/{idp => aws-sso}/office365/how-to-setup-office-365-aws-sso.mdx (96%) rename docs/layers/identity/{idp => aws-sso}/office365/office365.mdx (100%) rename docs/layers/identity/{idp => aws-sso}/okta/how-to-setup-okta-aws-sso.mdx (100%) rename docs/layers/identity/{idp => aws-sso}/okta/okta.mdx (100%) delete mode 100644 docs/layers/identity/idp/idp.mdx rename docs/layers/{network-and-dns => network}/access-network.mdx (100%) rename docs/layers/{network-and-dns => network}/connect-network.mdx (100%) rename docs/layers/{network-and-dns => network}/deploy-vpcs.mdx (100%) rename docs/layers/{network-and-dns => network}/design-decisions/decide-on-aws-account-vpc-subnet-cidr-strategy.mdx (100%) rename docs/layers/{network-and-dns => network}/design-decisions/decide-on-cidr-allocation.mdx (100%) rename docs/layers/{network-and-dns => network}/design-decisions/decide-on-client-vpn-options.mdx (100%) rename docs/layers/{network-and-dns => network}/design-decisions/decide-on-hostname-scheme-for-service-discovery.mdx (100%) rename docs/layers/{network-and-dns => network}/design-decisions/decide-on-how-to-support-tls.mdx (100%) rename docs/layers/{network-and-dns => network}/design-decisions/decide-on-ipv4-and-ipv6-support.mdx (100%) rename docs/layers/{network-and-dns => network}/design-decisions/decide-on-opting-into-non-default-regions.mdx (100%) rename docs/layers/{network-and-dns => network}/design-decisions/decide-on-organization-supernet-cidr-ranges.mdx (90%) rename docs/layers/{network-and-dns => network}/design-decisions/decide-on-primary-aws-region.mdx (100%) rename docs/layers/{network-and-dns => network}/design-decisions/decide-on-service-discovery-domain.mdx (100%) rename docs/layers/{network-and-dns => network}/design-decisions/decide-on-transit-gateway-requirements.mdx (100%) rename docs/layers/{network-and-dns => network}/design-decisions/decide-on-vanity-branded-domain.mdx (100%) rename docs/layers/{network-and-dns => network}/design-decisions/decide-on-vpc-nat-strategy.mdx (90%) rename docs/layers/{network-and-dns => network}/design-decisions/decide-on-vpc-network-traffic-isolation-policy.mdx (100%) rename docs/layers/{network-and-dns => network}/design-decisions/decide-vpc-peering-requirements-e-g-to-legacy-env.mdx (100%) rename docs/layers/{network-and-dns => network}/design-decisions/design-decisions.mdx (100%) rename docs/layers/{network-and-dns => network}/dns-setup.mdx (94%) rename docs/layers/{network-and-dns/network-and-dns.mdx => network/network.mdx} (94%) rename docs/layers/{network-and-dns => network}/tutorials/tutorials.mdx (100%) rename docs/layers/{application-cicd => software-delivery}/design-decisions/decide-how-to-distribute-docker-images.mdx (100%) rename docs/layers/{application-cicd => software-delivery}/design-decisions/decide-on-argocd-architecture.mdx (99%) rename docs/layers/{application-cicd => software-delivery}/design-decisions/decide-on-argocd-deployment-repo-architecture.mdx (100%) rename docs/layers/{application-cicd => software-delivery}/design-decisions/decide-on-branching-strategy.mdx (100%) rename docs/layers/{application-cicd => software-delivery}/design-decisions/decide-on-customer-apps-for-migration.mdx (100%) rename docs/layers/{application-cicd => software-delivery}/design-decisions/decide-on-database-seeding-strategy-for-ephemeral-preview-enviro.mdx (100%) rename docs/layers/{application-cicd => software-delivery}/design-decisions/decide-on-github-actions-workflow-organization-strategy.mdx (100%) rename docs/layers/{application-cicd => software-delivery}/design-decisions/decide-on-hot-fix-or-rollback-strategy.mdx (100%) rename docs/layers/{application-cicd => software-delivery}/design-decisions/decide-on-how-ecs-apps-are-deployed.mdx (100%) rename docs/layers/{application-cicd => software-delivery}/design-decisions/decide-on-kubernetes-application-artifacts.mdx (100%) rename docs/layers/{application-cicd => software-delivery}/design-decisions/decide-on-pipeline-strategy.mdx (99%) rename docs/layers/{application-cicd => software-delivery}/design-decisions/decide-on-release-engineering-strategy.mdx (95%) rename docs/layers/{application-cicd => software-delivery}/design-decisions/decide-on-release-promotion-strategy.mdx (100%) rename docs/layers/{application-cicd => software-delivery}/design-decisions/decide-on-repositories-strategy.mdx (100%) rename docs/layers/{application-cicd => software-delivery}/design-decisions/decide-on-seeding-strategy-for-staging-environments.mdx (100%) rename docs/layers/{application-cicd => software-delivery}/design-decisions/decide-on-self-hosted-github-runner-strategy.mdx (100%) rename docs/layers/{application-cicd => software-delivery}/design-decisions/decide-on-strategy-for-continuous-integration.mdx (100%) rename docs/layers/{application-cicd => software-delivery}/design-decisions/decide-on-strategy-for-developer-environments.mdx (100%) rename docs/layers/{application-cicd => software-delivery}/design-decisions/decide-on-strategy-for-managing-and-orchestrating-secrets.mdx (100%) rename docs/layers/{application-cicd => software-delivery}/design-decisions/decide-on-strategy-for-preview-environments-e-g-review-apps.mdx (99%) rename docs/layers/{application-cicd => software-delivery}/design-decisions/decide-on-terraform-configuration-pattern-for-application-reposi.mdx (100%) rename docs/layers/{application-cicd => software-delivery}/design-decisions/design-decisions.mdx (100%) rename docs/layers/{application-cicd => software-delivery}/ecs-ecspresso/ecs-ecspresso.mdx (100%) rename docs/layers/{application-cicd => software-delivery}/ecs-ecspresso/setup.mdx (100%) rename docs/layers/{application-cicd => software-delivery}/eks-argocd/eks-argocd.mdx (99%) rename docs/layers/{application-cicd => software-delivery}/eks-argocd/setup.mdx (100%) rename docs/layers/{application-cicd => software-delivery}/eks-argocd/tutorials/github-commit-notifications.mdx (100%) rename docs/layers/{application-cicd => software-delivery}/eks-argocd/tutorials/identity-center-apps.mdx (100%) rename docs/layers/{application-cicd => software-delivery}/eks-argocd/tutorials/pats.mdx (100%) rename docs/layers/{application-cicd => software-delivery}/eks-argocd/tutorials/tutorials.mdx (100%) rename docs/layers/{application-cicd => software-delivery}/lambda/lambda.mdx (100%) rename docs/layers/{application-cicd/application-cicd.mdx => software-delivery/software-delivery.mdx} (100%) rename docs/layers/{application-cicd => software-delivery}/tutorials/_category_.json (100%) rename docs/layers/{application-cicd => software-delivery}/tutorials/how-to-create-a-migration-checklist.mdx (100%) create mode 100644 docs/layers/spacelift/faq.mdx rename docs/layers/spacelift/{03-spacelift.mdx => setup.mdx} (79%) delete mode 100644 docs/resources/legacy/_category_.json rename docs/{layers/identity/docs => resources/legacy}/aws-feature-requests-and-limitations.mdx (98%) delete mode 100644 docs/resources/legacy/howto/_category_.json rename docs/{layers/identity/docs/aws-business-roles.mdx => support/aws-support.mdx} (61%) create mode 100644 docs/support/customer-workshops.mdx create mode 100644 docs/support/github-discussions.mdx create mode 100644 docs/tags.yml create mode 100644 examples/snippets/.github/workflows/atmos-terraform-apply-matrix.yaml create mode 100644 examples/snippets/.github/workflows/atmos-terraform-apply.yaml create mode 100644 examples/snippets/.github/workflows/atmos-terraform-dispatch.yaml create mode 100644 examples/snippets/.github/workflows/atmos-terraform-drift-detection.yaml create mode 100644 examples/snippets/.github/workflows/atmos-terraform-drift-remediation.yaml create mode 100644 examples/snippets/.github/workflows/atmos-terraform-plan-matrix.yaml create mode 100644 examples/snippets/.github/workflows/atmos-terraform-plan.yaml create mode 100644 examples/snippets/stacks/orgs/acme/plat/spacelift.yaml create mode 100644 examples/snippets/stacks/orgs/acme/spacelift.yaml create mode 100644 plugins/custom-loaders/index.js create mode 100644 src/components/KeyboardShortcuts/index.js create mode 100644 src/components/TagList/index.js create mode 100644 src/theme/Layout/index.js diff --git a/docs/best-practices/best-practices.mdx b/docs/best-practices/best-practices.mdx index 5c42b8752..5e5573e20 100644 --- a/docs/best-practices/best-practices.mdx +++ b/docs/best-practices/best-practices.mdx @@ -4,6 +4,8 @@ sidebar_label: Best Practices sidebar_class_name: hidden sidebar_position: 0 description: Cloud Posse's Opinionated Reference Architecture Best Practices +tags: + - best-practices --- > Physics is the law, everything else is a recommendation. diff --git a/docs/best-practices/developer/developer.mdx b/docs/best-practices/developer/developer.mdx index 286a32c37..14605b84e 100644 --- a/docs/best-practices/developer/developer.mdx +++ b/docs/best-practices/developer/developer.mdx @@ -5,7 +5,6 @@ description: "We've written thousands of lines of code. These are our best pract tags: - best-practices - developer - - code --- import DocCardList from '@theme/DocCardList'; import Intro from '@site/src/components/Intro'; diff --git a/docs/best-practices/developer/editor-config.mdx b/docs/best-practices/developer/editor-config.mdx index a910b51ca..23d63881a 100644 --- a/docs/best-practices/developer/editor-config.mdx +++ b/docs/best-practices/developer/editor-config.mdx @@ -3,9 +3,8 @@ title: Editor Config Best Practices sidebar_label: Editor Config description: "The EditorConfig enables developers to define and maintain consistent coding styles between different editors and IDEs. It consists of a simple file format (`.editorconfig`) for defining coding styles such as tabs vs spaces. Most text editors support the format and adhere to defined styles. The config files are easily readable and they work nicely with version control systems." tags: - - code style - - formatting - - .editorconfig + - best-practices + - developer --- import Intro from '@site/src/components/Intro'; diff --git a/docs/best-practices/developer/github-sign-your-commits-with-ssh.mdx b/docs/best-practices/developer/github-sign-your-commits-with-ssh.mdx index a17fa6687..e7f87d0e2 100644 --- a/docs/best-practices/developer/github-sign-your-commits-with-ssh.mdx +++ b/docs/best-practices/developer/github-sign-your-commits-with-ssh.mdx @@ -1,6 +1,10 @@ --- title: "Sign Your GitHub Commits with SSH" sidebar_label: "Sign GitHub Commits" +tags: + - best-practices + - developer + - github --- If you are already using SSH to authenticate to GitHub, it is very easy to sign all your commits as well, as long as you have already installed Git 2.34.0 or later. (Note, there may be problems with OpenSSH 8.7. Use an earlier or later version. I have this working with OpenSSH 8.1p1.) diff --git a/docs/best-practices/developer/makefile.mdx b/docs/best-practices/developer/makefile.mdx index 03f131b75..58a1df925 100644 --- a/docs/best-practices/developer/makefile.mdx +++ b/docs/best-practices/developer/makefile.mdx @@ -3,9 +3,10 @@ title: "Makefile Best Practices" description: "We've written thousands of lines of Makefile. These are our best practices from the trenches." sidebar_label: Makefiles tags: + - developer - tool - make - - Makefile + - makefile - best-practices --- import Intro from '@site/src/components/Intro'; diff --git a/docs/best-practices/developer/markdown.mdx b/docs/best-practices/developer/markdown.mdx index a2e65185e..37184e537 100644 --- a/docs/best-practices/developer/markdown.mdx +++ b/docs/best-practices/developer/markdown.mdx @@ -2,6 +2,9 @@ title: Markdown Best Practices sidebar_label: Markdown 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." +tags: + - best-practices + - developer --- import Intro from '@site/src/components/Intro'; diff --git a/docs/best-practices/developer/password-management.mdx b/docs/best-practices/developer/password-management.mdx index 83cd95c46..286b68c7b 100644 --- a/docs/best-practices/developer/password-management.mdx +++ b/docs/best-practices/developer/password-management.mdx @@ -2,6 +2,9 @@ title: Password Management sidebar_label: Password Management description: '' +tags: + - best-practices + - developer --- We strongly advise all companies to use "1Password for Teams" as their password management solution. diff --git a/docs/best-practices/developer/semver.mdx b/docs/best-practices/developer/semver.mdx index c1695f1b6..d8701c02f 100644 --- a/docs/best-practices/developer/semver.mdx +++ b/docs/best-practices/developer/semver.mdx @@ -3,7 +3,9 @@ title: Semantic Versioning sidebar_label: Semantic Versioning description: "Software versioning is the most widely adopted scheme for assigning unique version version numbers to software releases." tags: -- semver + - semver + - best-practices + - developer --- We practice [Semantic Versioning](https://semver.org/) for all projects (e.g. GitHub Tags/Releases, Helm Charts, Terraform Modules, Docker Images). Using this versioning standard helps to reduce the entropy related to [Dependency Hell](https://en.wikipedia.org/wiki/Dependency_hell). diff --git a/docs/best-practices/github/github-feature-branches.mdx b/docs/best-practices/github/github-feature-branches.mdx index 22b169ff7..79bb33fa1 100644 --- a/docs/best-practices/github/github-feature-branches.mdx +++ b/docs/best-practices/github/github-feature-branches.mdx @@ -2,6 +2,10 @@ title: GitHub Feature Branches sidebar_label: Feature Branches description: "Use separate branches for developing specific features." +tags: + - best-practices + - developer + - github --- import Intro from '@site/src/components/Intro' diff --git a/docs/best-practices/github/github-pull-requests.mdx b/docs/best-practices/github/github-pull-requests.mdx index d330c628b..05ea0e831 100644 --- a/docs/best-practices/github/github-pull-requests.mdx +++ b/docs/best-practices/github/github-pull-requests.mdx @@ -3,7 +3,9 @@ title: GitHub Pull Requests sidebar_label: Pull Requests description: Best practices using Pull Requests on GitHub. tags: -- "Best Practices" + - best-practices + - developer + - github --- ## Submitting a Pull Request diff --git a/docs/best-practices/github/github.mdx b/docs/best-practices/github/github.mdx index fe82b5944..18f2fd8ab 100644 --- a/docs/best-practices/github/github.mdx +++ b/docs/best-practices/github/github.mdx @@ -1,6 +1,10 @@ --- title: "GitHub Best Practices" sidebar_label: "GitHub" +tags: + - best-practices + - developer + - github --- ## Use `.gitignore` diff --git a/docs/best-practices/terraform.mdx b/docs/best-practices/terraform.mdx index a5a7cd67e..8862baf62 100644 --- a/docs/best-practices/terraform.mdx +++ b/docs/best-practices/terraform.mdx @@ -2,10 +2,10 @@ title: "Terraform Best Practices" sidebar_label: "Terraform" description: "Our opinionated best-practices for Terraform" -slug: "terraform-best-practices" tags: - - "Best Practices" - - "Terraform" + - best-practices + - terraform +image: /assets/08bcd99-terraform.png --- ![Terraform](/assets/08bcd99-terraform.png) @@ -13,7 +13,7 @@ tags: These are the *opinionated* best-practices we follow at Cloud Posse. They are inspired by years of experience writing terraform and borrow on the many other helpful resources like those by [HashiCorp](https://www.terraform.io/docs/cloud/guides/recommended-practices/index.html). -See our general [Best Practices](/category/best-practices/) which also apply to Terraform. +See our general [Best Practices](/best-practices/) which also apply to Terraform. ## Variables diff --git a/docs/community/code-of-conduct.mdx b/docs/community/code-of-conduct.mdx index 08f976433..3579d5edc 100644 --- a/docs/community/code-of-conduct.mdx +++ b/docs/community/code-of-conduct.mdx @@ -2,8 +2,8 @@ title: Code of Conduct description: This is our Contributor Covenant Code of Conduct. tags: -- open-source -- agreement +- community +- code-of-conduct --- import Intro from '@site/src/components/Intro'; diff --git a/docs/community/contribute/automated-testing.mdx b/docs/community/contribute/automated-testing.mdx index 32a33ba6d..0ebca2c60 100644 --- a/docs/community/contribute/automated-testing.mdx +++ b/docs/community/contribute/automated-testing.mdx @@ -2,6 +2,10 @@ title: Terraform Automated Testing sidebar_label: Automated Testing description: 'Our automated testing strategy and resources' +tags: + - community + - contribute + - developer --- import Intro from '@site/src/components/Intro'; import Steps from '@site/src/components/Steps'; diff --git a/docs/community/contribute/code-reviews.mdx b/docs/community/contribute/code-reviews.mdx index e9aff1e15..57332bb52 100644 --- a/docs/community/contribute/code-reviews.mdx +++ b/docs/community/contribute/code-reviews.mdx @@ -2,12 +2,12 @@ title: "Code Review Guidelines" description: "Code Review Guidelines" tags: - - "Best Practices" - - "Development" + - developer + - community --- import Steps from '@site/src/components/Steps'; -Here are some of our tips for conducting *Code Reviews* the SweetOps way. If you haven't already, become familiar with our [Best Practices](/category/best-practices/) and [Terraform Best Practices](/reference/best-practices/terraform-best-practices.md). +Here are some of our tips for conducting *Code Reviews* the SweetOps way. If you haven't already, become familiar with our [Best Practices](/category/best-practices/) and [Terraform Best Practices](/best-practices/terraform). 1. Use the ["Suggest"](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/incorporating-feedback-in-your-pull-request) feature as much as possible. This makes it quick and easy for the contributor to accept or dismiss the recommendations. diff --git a/docs/community/contribute/contribute.mdx b/docs/community/contribute/contribute.mdx index 93a2e3a7e..c07543574 100644 --- a/docs/community/contribute/contribute.mdx +++ b/docs/community/contribute/contribute.mdx @@ -2,6 +2,9 @@ title: GitHub Contributors description: 'GitHub Contributors' sidebar_class_name: hidden +tags: + - community + - contribute --- ## About diff --git a/docs/community/contribute/contributor-tips.mdx b/docs/community/contribute/contributor-tips.mdx index 659dac7ae..1e27b7e79 100644 --- a/docs/community/contribute/contributor-tips.mdx +++ b/docs/community/contribute/contributor-tips.mdx @@ -2,6 +2,10 @@ title: Contributor Tips & Tricks sidebar_label: Tips & Tricks description: 'Contributor Tips & Tricks' +tags: + - tips-and-tricks + - contribute + - developer --- import Steps from '@site/src/components/Steps'; diff --git a/docs/community/contribute/faq.mdx b/docs/community/contribute/faq.mdx index 38441f89e..15fada23b 100644 --- a/docs/community/contribute/faq.mdx +++ b/docs/community/contribute/faq.mdx @@ -2,6 +2,9 @@ title: GitHub Contributors FAQ sidebar_label: FAQ description: 'GitHub Contributors FAQ' +tags: + - faq + - contribute --- ## How do I see all open Pull Requests? @@ -16,7 +19,7 @@ why something happened than blame or chastise our volunteers. ## What are your best-practices we should follow? - See our [Terraform Best Practices](/reference/best-practices/terraform-best-practices.md) and [Best Practices](/category/best-practices/). These are just some guidelines to follow and we're open to your feedback! + See our [Terraform Best Practices](/best-practices/terraform) and [Best Practices](/best-practices/). These are just some guidelines to follow and we're open to your feedback! ## What benefits do I receive as a contributor? diff --git a/docs/community/contribute/our-github.mdx b/docs/community/contribute/our-github.mdx index c91654829..f89f72c4c 100644 --- a/docs/community/contribute/our-github.mdx +++ b/docs/community/contribute/our-github.mdx @@ -2,6 +2,8 @@ title: "Our GitHub" description: "Information on how to collaborate with Cloud Posse" sidebar_position: 100 +tags: + - contribute --- import Steps from '@site/src/components/Steps'; import Note from '@site/src/components/Note'; diff --git a/docs/community/office-hours.mdx b/docs/community/office-hours.mdx index 529ae695a..0e4536505 100644 --- a/docs/community/office-hours.mdx +++ b/docs/community/office-hours.mdx @@ -4,6 +4,9 @@ sidebar_position: 3 sidebar_label: Office Hours description: Office Hours with Cloud Posse id: office-hours +tags: + - office-hours + - community --- import HubspotForm from 'react-hubspot-form' import { YouTubePlaylist } from '@codesweetly/react-youtube-playlist'; diff --git a/docs/community/slack.mdx b/docs/community/slack.mdx index dc8972a81..3c2f4314e 100644 --- a/docs/community/slack.mdx +++ b/docs/community/slack.mdx @@ -4,6 +4,9 @@ sidebar_position: 3 sidebar_label: Slack description: Cloud Posse's SweetOps Slack Community id: slack +tags: + - slack + - community --- ## Join our Slack Community! diff --git a/docs/community/support.mdx b/docs/community/support.mdx index f9c5fc155..972e95415 100644 --- a/docs/community/support.mdx +++ b/docs/community/support.mdx @@ -2,6 +2,9 @@ title: "Community Support" sidebar_label: "Support" sidebar_position: 100 +tags: + - support + - community --- # FAQ @@ -12,7 +15,7 @@ Here are some quick answers to frequently asked questions. See also our [Trouble By far, the hardest part of being an open-source company is surviving the financial reality that very few companies ever pay for open source. Any financial contribution you can make helps us continue operating as a business, and we've made this easy through GitHub sponsorships. - + ## How do I request additional documentation? diff --git a/docs/components/library/library.mdx b/docs/components/library/library.mdx new file mode 100644 index 000000000..ca3d1d011 --- /dev/null +++ b/docs/components/library/library.mdx @@ -0,0 +1,15 @@ +--- +title: Terraform Components +sidebar_label: Terraform Components +sidebar_position: 0 +sidebar_class_name: hidden +description: Libary of Terraform Root Module Components +--- +import Intro from '@site/src/components/Intro'; +import DocCardList from '@theme/DocCardList'; + + + This is a libary of reusable Terraform "root module" components. + + + diff --git a/docs/intro/for-agencies.mdx b/docs/intro/for-agencies.mdx index 22e6e0731..a50301168 100644 --- a/docs/intro/for-agencies.mdx +++ b/docs/intro/for-agencies.mdx @@ -1,14 +1,26 @@ --- -title: Solutions For Agencies -sidebar_label: For Agencies +id: agencies +title: Solutions For Agencies & Consultants +sidebar_label: For Agencies & Consultants sidebar_position: 3 sidebar_class_name: divider -description: "Standardize your delivery." +description: "Standardize your delivery" +pagination_prev: intro/enterprises +tags: +- agency --- import Intro from '@site/src/components/Intro'; +import ActionCard from '@site/src/components/ActionCard'; +import PrimaryCTA from '@site/src/components/PrimaryCTA'; As an agency, moving quickly and serving numerous customers efficiently is a constant challenge. You've likely standardized your application stack language and framework—now it's time to standardize your infrastructure too. By leveraging our reference architecture for AWS, you can focus more on solving your customers' problems and less on the details of the tooling itself. Customize it to your needs and develop common, reusable patterns across all your projects, scaling as necessary. With our component and module library, you won't need to worry about creating original Terraform code. Instead, you can immediately benefit from what's already built and supported by our community. + + + Now that you know the reference architecture will work for your customers, you're ready to get started with your first project. + + Next Step + diff --git a/docs/intro/for-developers.mdx b/docs/intro/for-developers.mdx index 9aac699b6..5747e6a6b 100644 --- a/docs/intro/for-developers.mdx +++ b/docs/intro/for-developers.mdx @@ -3,11 +3,22 @@ id: developers title: "Solutions for Application Developers" sidebar_label: "For App Developers" sidebar_position: 4 +tags: +- developers --- import Intro from '@site/src/components/Intro'; +import ActionCard from '@site/src/components/ActionCard'; +import PrimaryCTA from '@site/src/components/PrimaryCTA'; As a developer, leveraging the Cloud Posse reference architecture offers a robust framework for team collaboration, with thorough documentation and community support, saving time and effort while providing a strong foundation for your infrastructure. If you're a developer, chances are you're entering a system already utilizing the Cloud Posse reference architecture set up by others in your organization, or you're being asked for advice on managing the next generation of your infrastructure. As a developer, you know the importance of using an established framework for any project—it provides consistent conventions, comprehensive documentation, and access to a supportive community. This is exactly what we offer. By tapping into the Cloud Posse reference architecture, you're building on a robust framework with thorough documentation, saving you significant time and effort in building your infrastructure. While there may be a learning curve, once you grasp it, you'll be far ahead of any company starting from scratch. + + + + Now that you know what the reference architecture is for you, you're ready to get started with your first project. + + Next Step + diff --git a/docs/intro/for-enterprises.mdx b/docs/intro/for-enterprises.mdx index d49d58bb4..f806a74f3 100644 --- a/docs/intro/for-enterprises.mdx +++ b/docs/intro/for-enterprises.mdx @@ -4,8 +4,14 @@ title: Solutions for Enterprises sidebar_label: "For Enterprises" sidebar_position: 2 description: Adopt a framework that streamlines enterprise infrastructure +pagination_next: intro/agencies +tags: +- enterprise --- import Intro from '@site/src/components/Intro'; +import Steps from '@site/src/components/Steps'; +import ActionCard from '@site/src/components/ActionCard'; +import PrimaryCTA from '@site/src/components/PrimaryCTA'; As an enterprise, your monumental success over time has likely come at the significant cost of technical debt. As infrastructure grew organically, it's systems became complex and brittle. Many of those who built it, may no longer be around to support it. Now it's time to bring order to this chaos, thinking about the long-term success of your organization. @@ -17,4 +23,38 @@ By adopting this reference architecture for AWS and the framework it's built upo - Security & Compliance - Scalability +## Getting Started + + +1. ### Initiate a Proof of Concept (POC) + - Set up the reference architecture within your AWS organization + - Deploy a simple application to understand the setup and capabilities + - Evaluate the fit and identify any customization needs + +2. ### Assess Current Infrastructure + - Conduct an inventory of existing infrastructure + - Identify areas of technical debt and potential risks + - Map current infrastructure components to the reference architecture + +3. ### Plan the Adoption + - Develop a roadmap for the transition + - Define key milestones and deliverables + - Establish governance and compliance frameworks aligned with the reference architecture + +4. ### Pilot Phase + - Select a small, manageable project to pilot the framework + - Implement the reference architecture components and gather feedback + - Establish continuous integration and continuous deployment (CI/CD) pipelines + +5. ### Scale Implementation + - Roll out the reference architecture across multiple projects + - Train teams on new processes and tools + - Iterate on the architecture and processes based on real-world usage + + + + Now that you understand how the reference architecture can work for you, you're ready to get started with your first Proof of Concept. + + Next Step + diff --git a/docs/intro/for-startups.mdx b/docs/intro/for-startups.mdx index 70ab27438..6c37a3b55 100644 --- a/docs/intro/for-startups.mdx +++ b/docs/intro/for-startups.mdx @@ -4,13 +4,19 @@ title: Solutions for Startups sidebar_label: "For Startups" description: "From startup to scale-up with flexible support." sidebar_position: 1 +tags: [startups] --- import Intro from '@site/src/components/Intro'; import TaskList from '@site/src/components/TaskList'; import Steps from '@site/src/components/Steps'; +import ActionCard from '@site/src/components/ActionCard'; +import PrimaryCTA from '@site/src/components/PrimaryCTA'; +import TagList from '@site/src/components/TagList'; + + -As a start-up, survival is your main goal, and our reference architecture—backed by extensive experience and contributions from a thriving community—provides essential support and scalability without long-term commitments. Whether through our free, open-source ecosystem or our tailored Quick Start and Jump Start solutions, we help you navigate the risks and achieve success efficiently. +As a start-up, you need to move fast and maximize your runway. One way to do that is by reducing risk and following tried and true methods. Our reference architecture is backed by our extensive experience and contributions from a thriving community, and provides essential support and scalability without long-term commitments. Whether through [our free, open-source ecosystem](/reference) or our tailored [Quickstart](/quickstart) and [Jumpstart](/jumpstart) solutions, we help you navigate the risks and achieve success efficiently. As a start-up, whether bootstrapped or venture-backed, your primary goal is survival, which is no easy feat given that 99% of companies fail due to the inherent risks of starting from scratch. When you use our reference architecture, it's one less thing for you to worry about. With extensive experience working with a range of companies—from small, family-funded startups to $1 billion unicorns—we've developed a reference architecture that incorporates their invaluable investments and insights. These companies not only use our architecture but also actively contribute to its improvement through support and pull requests, creating a thriving ecosystem similar to those seen with Node, React, and Angular. @@ -46,3 +52,10 @@ When you're ready to scale or need additional help, we offer consulting support - [ ] **GitHub Account**: Sign up for a GitHub account if you don't already have one. - [ ] **Datadog Account** (Optional): Sign up for a Datadog account if you don't already have one. + + + + Now that you know what the reference architecture is for you, you're ready to get started with your first project. + + Next Step + diff --git a/docs/intro/for-terraform-beginners.mdx b/docs/intro/for-terraform-beginners.mdx index 4462bc689..cb64005e6 100644 --- a/docs/intro/for-terraform-beginners.mdx +++ b/docs/intro/for-terraform-beginners.mdx @@ -3,9 +3,13 @@ id: terraform-beginner title: Solutions for Terraform Beginners sidebar_label: "For Terraform Beginners" sidebar_position: 5 +tags: +- beginner --- import Intro from '@site/src/components/Intro'; import Steps from '@site/src/components/Steps'; +import ActionCard from '@site/src/components/ActionCard'; +import PrimaryCTA from '@site/src/components/PrimaryCTA'; If you're a beginner with Terraform, you're in luck. As a blank slate, you won't have any bad habits to unlearn. Trust our experience—since 2015, we've been working almost exclusively with Terraform and have distilled our insights into this reference architecture. @@ -21,3 +25,10 @@ Designed in partnership with numerous startups and enterprises, it’s flexible - Monitor everything (Datadog, Prometheus, Grafana, etc. Also, monitoring for Security & Compliance) - Upgrade & Maintain (Day-2 operations including upgrades, backups, disaster recovery, etc.) + + + + Now that you know what the reference architecture is for you, you're ready to get started with your first project. + + Next Step + diff --git a/docs/intro/for-terraform-experts.mdx b/docs/intro/for-terraform-experts.mdx index b6f336863..2342a7f82 100644 --- a/docs/intro/for-terraform-experts.mdx +++ b/docs/intro/for-terraform-experts.mdx @@ -4,9 +4,13 @@ title: Solutions for Experienced Terraformers sidebar_label: "For Terraform Experts" sidebar_position: 6 description: Cloud Posse offers flexible, efficient, and lifelong open-source infrastructure. +tags: +- expert --- import Intro from '@site/src/components/Intro'; import Steps from '@site/src/components/Steps'; +import ActionCard from '@site/src/components/ActionCard'; +import PrimaryCTA from '@site/src/components/PrimaryCTA'; Joining the Cloud Posse ecosystem provides you with a comprehensive, flexible infrastructure framework that saves years of effort and enhances efficiency, all supported for life under a permissive open-source license (APACHE2). @@ -20,6 +24,8 @@ Cloud Posse is opinionated, and that's a good thing. Our approach benefits from ## Getting Started +As an experienced Terraformer, the best place to start is by reviewing our conventions and best practices, especially as they relate to Atmos. If you come from a background that uses different tooling, such as `terragrunt`, there will be some new concepts that you'll need to learn, and they might change the way you think about Terraform. + - Start with our [Quick Start Guide](https://atmos.tools/quickstart) for Atmos, to learn the basics of the framework - Learn how to [Build your foundation](/learn) (Organization, OUs Accounts, Network & VPCs, IAM & Single Sign-On) @@ -28,3 +34,10 @@ Cloud Posse is opinionated, and that's a good thing. Our approach benefits from - Monitor everything (Datadog, Prometheus, Grafana, etc. Also, monitoring for Security & Compliance) - Upgrade & Maintain (Day-2 operations including upgrades, backups, disaster recovery, etc.) + + + + Now that you know what the reference architecture is for you, you're ready to get started with your first project. + + Next Step + diff --git a/docs/intro/index.mdx b/docs/intro/intro.mdx similarity index 88% rename from docs/intro/index.mdx rename to docs/intro/intro.mdx index 4c4f9909b..692034711 100644 --- a/docs/intro/index.mdx +++ b/docs/intro/intro.mdx @@ -18,11 +18,22 @@ import StepNumber from '@site/src/components/StepNumber'; Cloud Posse's reference architecture offers a unique, open-source approach to infrastructure, fostering a collaborative ecosystem with the industry's largest library of Terraform modules and a comprehensive framework using [Atmos](https://atmos.tools). Whether you're an experienced developer or a Terraform newbie, our tools and community are here to help you succeed without sacrificing customization. + +```mermaid +graph LR + A(Build Your Foundation) --> B(Set Up Your Platform) + B --> C(Deploy Your Apps) + C --> D(Monitor Everything) + D --> E(Upgrade &\n Maintain) + E --> E +``` + Before you jump into the Cloud Posse reference architecture, let’s review what makes it tick. Cloud Posse has been helping companies—from scrappy startups to massive enterprises—win big with Terraform. But here’s the kicker: we do things differently. Everything is based on Open Source that your team owns and operates. We're not another enterprise platform you _have_ to pay for (but [we do accept sponsorships](/community/support) and [offer support](/support)). We’re a part of a community that’s here to help you succeed. Our goal? To create a collaborative ecosystem where everyone, regardless of the company, can work together on infrastructure, so we stop reinventing the wheel. -How do we make this magic happen? First, we built the industry's largest library of Terraform modules for AWS, Datadog, and Opsgenie. Then, we crafted reusable components to give you rock-solid ways to set up your infrastructure. Finally, we wrapped it all up in a neat framework called [Atmos](https://atmos.tools) that ties everything together. +How do we make this magic happen? First, we built the industry's largest library of Terraform modules for AWS, Datadog, and Opsgenie. Then, we crafted reusable components to give you rock-solid ways to set up your infrastructure. Finally, we wrapped it all up in a neat framework using [Atmos](https://atmos.tools) that ties everything together, fully automated with GitHub Actions. + ## Solutions @@ -30,7 +41,6 @@ Whether you’re a developer with years of experience, a Terraform newbie, or a Here's why our reference architecture will work you! - ## Documentation Structure @@ -105,15 +115,13 @@ With SweetOps you can implement the following complex architectural patterns wit ## What are the alternatives? -SweetOps is similar to [Gruntwork](https://gruntwork.io/)’s Terragrunt + subscription plan, [the Terraspace framework](https://terraspace.cloud/), and [BinBash’s Leverage](https://leverage.binbash.com.ar/). +The reference archietcture is comparable to various other solutions that bundle ready-to-go Terraform "templates" and offer subscription plans for access to their modules. How does it differentiate from these solutions? 1. **It’s based 100% on Open Source**: SweetOps [is on GitHub](https://github.com/cloudposse) and is free to use with no strings attached under Apache 2.0. -2. **It’s comprehensive**: SweetOps is not only about Terraform. It provides patterns and conventions for building cloud-native platforms that are security-focused, Kubernetes or ECS-based, with comprehensive monitoring and incident management, and driven by continuous delivery. -3. **It’s community-focused**: SweetOps has [over 9500 users in Slack](https://sweetops.com/slack/), well-attended weekly [office hours](https://cloudposse.com/office-hours/), and a [budding community forum](https://ask.sweetops.com/). - - +2. **It’s comprehensive**: SweetOps is not only about Terraform. It provides a framework with conventions for building cloud-native platforms that are security-focused, Kubernetes or ECS-based, with comprehensive monitoring and incident management, and driven by continuous delivery. +3. **It’s community-focused**: SweetOps has [over 9500 users in Slack](https://sweetops.com/slack/), and well-attended weekly [office hours](https://cloudposse.com/office-hours/). diff --git a/docs/jumpstart/action-items.mdx b/docs/jumpstart/action-items.mdx index 67fa90c12..2837646a4 100644 --- a/docs/jumpstart/action-items.mdx +++ b/docs/jumpstart/action-items.mdx @@ -1,6 +1,7 @@ --- title: Action Items sidebar_label: Action Items +sidebar_position: 3 --- import Intro from '@site/src/components/Intro'; import Steps from '@site/src/components/Steps'; diff --git a/docs/jumpstart/faq.mdx b/docs/jumpstart/faq.mdx index 1a66bc8f8..df5e2da4b 100644 --- a/docs/jumpstart/faq.mdx +++ b/docs/jumpstart/faq.mdx @@ -3,6 +3,8 @@ title: FAQ sidebar_label: FAQ sidebar_position: 10 description: Frequently Asked Questions +tags: + - faq --- import Intro from '@site/src/components/Intro'; diff --git a/docs/jumpstart/jumpstart.mdx b/docs/jumpstart/jumpstart.mdx index c5cfbbb42..2e37527a2 100644 --- a/docs/jumpstart/jumpstart.mdx +++ b/docs/jumpstart/jumpstart.mdx @@ -1,14 +1,15 @@ --- -id: jumpstart title: "Get a Jumpstart with Cloud Posse" -sidebar_position: 3 +sidebar_position: 5 sidebar_class_name: hidden +pagination_next: jumpstart/kick-off --- import Intro from '@site/src/components/Intro'; import ActionCard from '@site/src/components/ActionCard'; import PrimaryCTA from '@site/src/components/PrimaryCTA'; import SecondaryCTA from '@site/src/components/SecondaryCTA'; import PillBox from '@site/src/components/PillBox'; +import Note from '@site/src/components/Note'; Done For You @@ -16,7 +17,9 @@ import PillBox from '@site/src/components/PillBox'; Our [Jumpstart accelerator](https://cloudposse.com) provides an end-to-end implementation by Cloud Posse of this reference architecture in your AWS organization, customized to your needs, with a guaranteed outcome, fixed price, predictable timeline, and a money-back guarantee. -Cloud Posse offers our complete reference architecture for free as open source, that you can implement at your own pace. The process involves a lot of steps, and it can be challenging to get everything right. + +Cloud Posse offers the complete configuration our reference architecture as perk for GitHub Sponsorship of Cloud Posse's Open Source, that you can implement at your own pace. If you prefer to "do it yourself," check out our [Quickstart](/quickstart) and start your sponsorship today! + If you need assistance, our Jumpstart service provides an end-to-end implementation in your AWS organization. We swiftly implement the reference architecture, tailored to your design decisions, with a guaranteed outcome, fixed price, timeline, and a hassle-free money-back guarantee. @@ -26,8 +29,3 @@ Cloud Posse offers our complete reference architecture for free as open source, -## GitHub Sponsorships - -Not yet ready to take the plunge with Jumpstart? You can still support Cloud Posse by sponsoring us on GitHub. As an extra bonus, we'll provide you with the final configuration of our reference architecture, tailored to your design decisions. - - diff --git a/docs/jumpstart/kick-off.mdx b/docs/jumpstart/kick-off.mdx index 3762d73d2..22d638540 100644 --- a/docs/jumpstart/kick-off.mdx +++ b/docs/jumpstart/kick-off.mdx @@ -1,7 +1,7 @@ --- title: "Kick Off with Cloud Posse" sidebar_label: "Kick Off" -sidebar_position: 1 +sidebar_position: 2 describe: Set project expectations for Jumpstarts with Cloud Posse --- import Link from '@docusaurus/Link' diff --git a/docs/jumpstart/onboarding.mdx b/docs/jumpstart/onboarding.mdx index 34a70f552..71faa00c4 100644 --- a/docs/jumpstart/onboarding.mdx +++ b/docs/jumpstart/onboarding.mdx @@ -1,6 +1,7 @@ --- title: Onboarding sidebar_label: Onboarding +sidebar_position: 4 --- import TaskList from '@site/src/components/TaskList'; diff --git a/docs/jumpstart/support.mdx b/docs/jumpstart/support.mdx index 0f2f09178..00fc91035 100644 --- a/docs/jumpstart/support.mdx +++ b/docs/jumpstart/support.mdx @@ -1,7 +1,7 @@ --- title: "Support" sidebar_label: "Getting Support" -sidebar_position: 90 +sidebar_position: 5 description: Learn about Cloud Posse’s paid and free support options --- import Intro from '@site/src/components/Intro'; diff --git a/docs/jumpstart/tutorials/how-to-provision-shared-slack-channels.mdx b/docs/jumpstart/tutorials/how-to-provision-shared-slack-channels.mdx index d9bf20cc1..98e1dd139 100644 --- a/docs/jumpstart/tutorials/how-to-provision-shared-slack-channels.mdx +++ b/docs/jumpstart/tutorials/how-to-provision-shared-slack-channels.mdx @@ -3,6 +3,9 @@ title: "How to Provision Shared Slack Channels" sidebar_label: "Shared Slack Channels" sidebar_position: 100 description: "How to provision shared Slack channels between our teams" +tags: + - tutorial + - slack --- import Note from '@site/src/components/Note' import Intro from '@site/src/components/Intro' @@ -23,25 +26,25 @@ The official Slack Connect documentation: [https://slack.com/help/articles/11500 1. Create a new Slack Channel as you would normally -
+
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. 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. -
+
3. Proceed by clicking Next. Then you’re prompted to share the channel. There are (2) ways to do this: either by clicking the “copy share link” option or by entering in the email address of _anyone_ from the other organization. The other organization’s admins will then be prompted to accept the invitation. -
+
Then you’ll see a notice like this from the Slackbot. -
+
4. After the invitation is accepted by the other organization, the inviting organization may need to re-confirm the connect request. This may appear as a notice from the `Slackbot` to the slack admins. -
+
5. Once the connection is established, any members that exist in the channel can chat publicly or via direct message (DMs). @@ -49,6 +52,6 @@ Then you’ll see a notice like this from the Slackbot. You can accept/decline slack connections from here. -
+
diff --git a/docs/jumpstart/tutorials/offboarding-cloudposse.mdx b/docs/jumpstart/tutorials/offboarding-cloudposse.mdx index 7d24c3b59..10c510ffd 100644 --- a/docs/jumpstart/tutorials/offboarding-cloudposse.mdx +++ b/docs/jumpstart/tutorials/offboarding-cloudposse.mdx @@ -3,6 +3,8 @@ title: "Offboarding Cloud Posse" sidebar_label: "Offboarding Cloud Posse" sidebar_position: 100 description: How to remove Cloud Posse's access to your systems +tags: + - tutorial --- ### Problem @@ -51,7 +53,7 @@ Revoking this team’s access from repositories should be sufficient to remove a #### Option 2: Downgrade Access Changing our team’s access to read-only will enable us to still participate in Code Reviews. -
+
### Spacelift @@ -63,11 +65,11 @@ Then remove our team’s access or any hardcoded usernames. Also, make sure to sign out any logged in sessions, by going to `https://.app.spacelift.io/settings/sessions` -
+
-
+
-
+
### Slack diff --git a/docs/jumpstart/tutorials/tutorials.mdx b/docs/jumpstart/tutorials/tutorials.mdx index ca67f936f..c186da2db 100644 --- a/docs/jumpstart/tutorials/tutorials.mdx +++ b/docs/jumpstart/tutorials/tutorials.mdx @@ -1,6 +1,9 @@ --- title: Tutorials sidebar_label: Tutorials +tags: + - tutorial + - index --- import Intro from '@site/src/components/Intro'; import DocCardList from '@theme/DocCardList'; diff --git a/docs/layers/accounts/accounts.mdx b/docs/layers/accounts/accounts.mdx index 0a4eaff5c..e92331b42 100644 --- a/docs/layers/accounts/accounts.mdx +++ b/docs/layers/accounts/accounts.mdx @@ -9,6 +9,8 @@ import ReactPlayer from "react-player"; import ActionCard from '@site/src/components/ActionCard'; import PrimaryCTA from '@site/src/components/PrimaryCTA'; import SecondaryCTA from '@site/src/components/SecondaryCTA'; +import TaskList from '@site/src/components/TaskList'; +import CategoryList from '@site/src/components/CategoryList'; This chapter presents how Cloud Posse designs and manages AWS Account architectures. We will explain how Cloud Posse provisions and manages AWS Accounts using Atmos and Terraform, 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). @@ -49,10 +51,12 @@ can be be in place to restrict what can happen in an account and by whom. We then further organize the flat account structure into organizational units. Organizational units (OUs) can then leverage things like Service Control Policies to restrict what can happen inside the accounts. -- **core**: Management accounts, such as the organizational root account or a network hub. This accounts are singletons - and will never need to be duplicated. -- **plat**: Platform accounts, such as sandbox, dev, staging, and prod. These accounts are dynamic and can be specific - to the needs of your Organizations. +
+
`core` (OU)
+
Responsible for management accounts, such as the organizational root account or a network hub. These accounts are singletons and will never need to be duplicated.
+
`plat` (OU)
+
Responsible for platform accounts, such as sandbox, dev, staging, and prod. These accounts are dynamic and can be specific to the needs of your Organizations.
+
### Account Boundaries @@ -272,6 +276,16 @@ Cloud Posse manages this process with the following components.
This component is responsible for provisioning a bucket for storing cloudtrail logs for auditing purposes
+## Design Decisions + +[Review Design Decisions](/layers/foundation/design-decisions) and record your decisions now. You will need the results of these decisions going forward. + + + + + + + Next, we'll prepare the organization to provision the Terraform State backend, followed by account provisioning. diff --git a/docs/layers/accounts/initialize-tfstate.mdx b/docs/layers/accounts/initialize-tfstate.mdx index 27ff541e8..fcd3988b3 100644 --- a/docs/layers/accounts/initialize-tfstate.mdx +++ b/docs/layers/accounts/initialize-tfstate.mdx @@ -16,7 +16,6 @@ Follow these steps to configure and initialize the Terraform state backend using | ------------------------- | ----------------------------------------- | | Configure Terraform state | `atmos workflow init/tfstate -f baseline` | - ## Setting up the Terraform State Backend This is where we configure and run Atmos. Atmos is a workflow automation tool that we will use to call Terraform which @@ -51,3 +50,7 @@ The IAM User for SuperAdmin will be granted access to Terraform State by princip update the root account ID. ::: + +## References + +- Review the [Structure of Terraform S3 State Backend Bucket](/layers/accounts/tutorials/terraform-s3-state/) diff --git a/docs/layers/accounts/tutorials/cold-start.mdx b/docs/layers/accounts/tutorials/cold-start.mdx index b57445e9e..da0e16446 100644 --- a/docs/layers/accounts/tutorials/cold-start.mdx +++ b/docs/layers/accounts/tutorials/cold-start.mdx @@ -19,7 +19,7 @@ Please take the time to read through the entire process before starting, and rea ## 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. diff --git a/docs/layers/accounts/tutorials/how-to-create-superadmin-user.mdx b/docs/layers/accounts/tutorials/how-to-create-superadmin-user.mdx index 2fd753c50..6ed7f45b1 100644 --- a/docs/layers/accounts/tutorials/how-to-create-superadmin-user.mdx +++ b/docs/layers/accounts/tutorials/how-to-create-superadmin-user.mdx @@ -81,7 +81,7 @@ The resulting entry in 1password should appear as follows: Hit save once you are done. Once the SuperAdmin credentials need to be disabled, do not forget to update the notes in this item. -
+
### Detailed Instructions @@ -91,21 +91,21 @@ be out of date as the AWS web console interface changes. 1. Login to the AWS `root` account using the root credentials from 1Password 2. Navigate to the IAM console page -
+
3. In the IAM console, select `Users` on the sidebar -4.
Click `Add users` button
+4.
Click `Add users` button
5. Enter "SuperAdmin" for `User name` and check `Programmatic access` and leave `AWS Management Console access` unchecked. Click `Next: Permissions` at the bottom right corner of the page -
+
6. Under `Set permissions` , select `Attach existing policies directly` . A list should appear, from which you should check `AdministratorAccess` . Click `Next: Tags` at the bottom right corner of the page -
+
7. Skip the tags, Click `Next: Review` at the bottom right corner of the page @@ -114,41 +114,41 @@ be out of date as the AWS web console interface changes. 9. The Success page should show you the `Access key ID` and hidden `Secret access key` which can be revealed by clicking `Show` , copy these to your secure credentials storage as you will need them shortly -
+
10. Click `Close` at the bottom right corner to return to the IAM console and select `Users` on the sidebar if it is not already selected 11. You should a list of users. Click the user name `SuperAdmin` (which should be a hyperlink) -
+
12. On the `Users -> SuperAdmin` "Summary" page, click on the `Security credentials` tab 13. In the `Sign-in credentials` section, find: `Assigned MFA device: Not assigned | Manage` and click `Manage` -
+
14. Choose `Virtual MFA device` and click `Continue` -
+
15. Press the `Show secret key` button -
+
16. Copy the key into 1Password as a AWS Credential using the “MFA” field -
+
17. Use the MFA codes from 1Password to complete the MFA setup process (you will input 2 consecutive codes) -
+
18. You should be taken back to the `Security Credentials` tab, but now the `Assigned MFA device` field should have an ARN like `arn:aws:iam:::mfa/SuperAdmin` -
+
19. Copy the ARN and keep it with the Access Key in 1Password @@ -190,7 +190,7 @@ The content by label feature displays related articles automatically, based on l ::: -|Related issues | | -| ----- | ----- | +| Related issues | | +| -------------- | --- | ``` diff --git a/docs/layers/accounts/tutorials/how-to-set-up-aws-email-notifications.mdx b/docs/layers/accounts/tutorials/how-to-set-up-aws-email-notifications.mdx index edea3bf33..d15676324 100644 --- a/docs/layers/accounts/tutorials/how-to-set-up-aws-email-notifications.mdx +++ b/docs/layers/accounts/tutorials/how-to-set-up-aws-email-notifications.mdx @@ -5,6 +5,7 @@ description: Set up AWS email notifications to Slack channel --- import Intro from '@site/src/components/Intro'; import KeyPoints from '@site/src/components/KeyPoints'; +import Steps from '@site/src/components/Steps'; Learn how to setup AWS account email notifications by routing emails from AWS accounts to a dedicated Slack channel. It covers using plus addressing for efficient email management and provides detailed steps for creating the Slack channel, generating its email address, and configuring email forwarding. @@ -31,14 +32,18 @@ address can be created. The following is an example of how to set up this channel and configure email routing to the dedicated Slack channel's email address: -1. **Create the shared Slack channel (under Slack Connect):** (see also: - [How to Provision Shared Slack Channels](/reference/how-to-provision-shared-slack-channels/) ) -
+ + 1. ## Create the shared Slack channel (under Slack Connect): + (see also: [How to Provision Shared Slack Channels](/reference/how-to-provision-shared-slack-channels/) ) + -2. **Generate the Slack channel's email address (at the top of the newly-created Slack channel):** -
+ 2. ## Generate the Slack channel's email address (at the top of the newly-created Slack channel): +
-3. **Set up email forwarding (example: G Suite / Google Workspace) in **`Google Workspace -> Settings for Gmail -> Routing -> Recipient address map`:** -
+ 3. ## Set up email forwarding (example: G Suite / Google Workspace) + in **`Google Workspace -> Settings for Gmail -> Routing -> Recipient address map`:** +
-4. Depending on your current Slack Workspace permissions, you may need to [manage incoming emails for your Slack workspace or organization](https://slack.com/help/articles/360053335433-Manage-incoming-emails-for-your-workspace-or-organization) and allow incoming email + 4. ## Manage Incoming Emails + Depending on your current Slack Workspace permissions, you may need to [manage incoming emails for your Slack workspace or organization](https://slack.com/help/articles/360053335433-Manage-incoming-emails-for-your-workspace-or-organization) and allow incoming email + diff --git a/docs/layers/alerting/design-decisions/decide-on-default-schedules.mdx b/docs/layers/alerting/design-decisions/decide-on-default-schedules.mdx index 7481ebea4..40b37ccc4 100644 --- a/docs/layers/alerting/design-decisions/decide-on-default-schedules.mdx +++ b/docs/layers/alerting/design-decisions/decide-on-default-schedules.mdx @@ -3,13 +3,14 @@ title: "Decide on Default Schedules" sidebar_label: "Default Schedules" sidebar_position: 100 refarch_id: REFARCH-520 +description: Determine the on-call schedule for teams --- ## 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. -
+
## Considered Options diff --git a/docs/layers/alerting/design-decisions/decide-on-incident-ruleset.mdx b/docs/layers/alerting/design-decisions/decide-on-incident-ruleset.mdx index c7c068744..9815bd55a 100644 --- a/docs/layers/alerting/design-decisions/decide-on-incident-ruleset.mdx +++ b/docs/layers/alerting/design-decisions/decide-on-incident-ruleset.mdx @@ -3,6 +3,7 @@ title: "Decide on Incident Ruleset" sidebar_label: "Incident Ruleset" sidebar_position: 100 refarch_id: REFARCH-519 +description: Determine the rules that make an alert an incident --- ## Context and Problem Statement diff --git a/docs/layers/alerting/design-decisions/decide-on-teams-for-escalations.mdx b/docs/layers/alerting/design-decisions/decide-on-teams-for-escalations.mdx index 71224c51e..53c5b95ec 100644 --- a/docs/layers/alerting/design-decisions/decide-on-teams-for-escalations.mdx +++ b/docs/layers/alerting/design-decisions/decide-on-teams-for-escalations.mdx @@ -3,6 +3,7 @@ title: "Decide on Teams for Escalations" sidebar_label: "Teams for Escalations" sidebar_position: 100 refarch_id: REFARCH-468 +description: Determine the teams that will be responsible for incidents --- ## Problem diff --git a/docs/layers/alerting/design-decisions/design-decisions.mdx b/docs/layers/alerting/design-decisions/design-decisions.mdx index e04e954f9..c81c2240d 100644 --- a/docs/layers/alerting/design-decisions/design-decisions.mdx +++ b/docs/layers/alerting/design-decisions/design-decisions.mdx @@ -2,12 +2,13 @@ title: Design Decisions sidebar_label: Design Decisions sidebar_position: 10 +description: Review the key design decisions for implementing incident management --- import DocCardList from '@theme/DocCardList'; import Intro from '@site/src/components/Intro'; -Review the key design decisions of for how you'll implement incident management, escalations, and alerting. + Review the key design decisions to determine how you'll implement incident management, escalations, and alerting. diff --git a/docs/layers/alerting/08-alerting.mdx b/docs/layers/alerting/setup.mdx similarity index 100% rename from docs/layers/alerting/08-alerting.mdx rename to docs/layers/alerting/setup.mdx diff --git a/docs/layers/data/design-decisions/decide-on-amazon-opensearch-service-elasticsearch-requirements.mdx b/docs/layers/data/design-decisions/decide-on-amazon-opensearch-service-elasticsearch-requirements.mdx index a6c7fd062..2a8816953 100644 --- a/docs/layers/data/design-decisions/decide-on-amazon-opensearch-service-elasticsearch-requirements.mdx +++ b/docs/layers/data/design-decisions/decide-on-amazon-opensearch-service-elasticsearch-requirements.mdx @@ -1,6 +1,6 @@ --- title: "Decide on Amazon OpenSearch Service (Elasticsearch) Requirements" -sidebar_label: "Decide on Amazon OpenSearch Service (Elasticsearch) Requirements" +sidebar_label: "Amazon OpenSearch Service (Elasticsearch) Requirements" sidebar_position: 100 refarch_id: REFARCH-362 --- @@ -50,7 +50,7 @@ cluster will have the following requirements: | **Requirement** | **Recommendation** | | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | -| EBS volume size | :::caution
The volume size is limited by the size of the instance.
[https://docs.aws.amazon.com/opensearch-service/latest/developerguide/limits.html](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/limits.html)


::: |
| +| EBS volume size | :::caution
The volume size is limited by the size of the instance.
[https://docs.aws.amazon.com/opensearch-service/latest/developerguide/limits.html](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/limits.html)


::: |
| | Number of nodes | 3 | | | Instance family for each node | Depends on use-case | | | Kibana | Whether or not Kibana is required: not required.


:::caution
If Kibana is required, we’ll need to discuss how to securely access Kibana. We recommend SAML authentication.

[https://docs.aws.amazon.com/opensearch-service/latest/developerguide/saml.html](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/saml.html)


::: | | diff --git a/docs/layers/ecs/tutorials/how-to-setup-vanity-domains-on-alb-ecs.mdx b/docs/layers/ecs/tutorials/how-to-setup-vanity-domains-on-alb-ecs.mdx index 878445276..c9df2cdb5 100644 --- a/docs/layers/ecs/tutorials/how-to-setup-vanity-domains-on-alb-ecs.mdx +++ b/docs/layers/ecs/tutorials/how-to-setup-vanity-domains-on-alb-ecs.mdx @@ -24,7 +24,7 @@ import TaskList from '@site/src/components/TaskList'; - [Understand the differences between Vanity Domains and Service Discovery Domains](/resources/legacy/learning-resources/#the-difference-between-vanity-domains-and-service-discovery-domains) - - Assumes our standard [Network Architecture](/layers/network-and-dns/) + - Assumes our standard [Network Architecture](/layers/network/) - Requires `dns-primary` & `dns-delegated` are already deployed. diff --git a/docs/layers/eks/tutorials/how-to-setup-vanity-domains-on-alb-eks.mdx b/docs/layers/eks/tutorials/how-to-setup-vanity-domains-on-alb-eks.mdx index a8e04d862..ca73f21c2 100644 --- a/docs/layers/eks/tutorials/how-to-setup-vanity-domains-on-alb-eks.mdx +++ b/docs/layers/eks/tutorials/how-to-setup-vanity-domains-on-alb-eks.mdx @@ -24,7 +24,7 @@ import TaskList from '@site/src/components/TaskList'; - [Understand the differences between Vanity Domains and Service Discovery Domains](/resources/legacy/learning-resources/#the-difference-between-vanity-domains-and-service-discovery-domains) - - Assumes our standard [Network Architecture](/layers/network-and-dns/) + - Assumes our standard [Network Architecture](/layers/network/) - Requires `dns-primary` & `dns-delegated` are already deployed. diff --git a/docs/layers/foundation/design-decisions/decide-on-regional-naming-scheme.mdx b/docs/layers/foundation/design-decisions/decide-on-regional-naming-scheme.mdx index 4f8769084..747f985a4 100644 --- a/docs/layers/foundation/design-decisions/decide-on-regional-naming-scheme.mdx +++ b/docs/layers/foundation/design-decisions/decide-on-regional-naming-scheme.mdx @@ -37,5 +37,5 @@ Here are some more examples to help understand the relationships. | 

namespace: acme
tenant: vkng
environment: ue2 # us-east-2
stage: automation
name: eks-cluster
| `acme-vkng-ue2-automation-eks-cluster` | Also, see the corresponding design decision for the -[Decide on Hostname Scheme for Service Discovery](/layers/network-and-dns/design-decisions/decide-on-hostname-scheme-for-service-discovery) +[Decide on Hostname Scheme for Service Discovery](/layers/network/design-decisions/decide-on-hostname-scheme-for-service-discovery) as this will be impacted by whatever is chosen. diff --git a/docs/layers/foundation/toolbox.mdx b/docs/layers/foundation/toolbox.mdx index b08758794..1ff52d322 100644 --- a/docs/layers/foundation/toolbox.mdx +++ b/docs/layers/foundation/toolbox.mdx @@ -8,14 +8,21 @@ import Intro from '@site/src/components/Intro'; import ActionCard from '@site/src/components/ActionCard'; import PrimaryCTA from '@site/src/components/PrimaryCTA'; import DismissibleDialog from '@site/src/components/DismissibleDialog'; +import Note from '@site/src/components/Note'; Geodesic is a powerful Linux toolbox container designed to optimize DevOps workflows by providing essential dependencies for a DevOps toolchain, ensuring consistency and efficiency across development environments without additional software installation on your workstation. It can be extended and customized to fit specific needs by creating your own `Dockerfile` based on Geodesic, allowing you to add your favorite tools and share the container with your team for a unified working environment. + + Geodesic is similar in principle to [devcontainers](https://containers.dev/). However, being a container itself, Geodesic can run anywhere containers are supported—whether on your local workstation, remotely inside clusters, or on bastion hosts. Additionally, you can use Geodesic as the base image for a devcontainer. + +
-
Geodesic in action
+
+ Geodesic in action. +
diff --git a/docs/layers/github-actions/github-actions.mdx b/docs/layers/github-actions/github-actions.mdx index 3dec2f1ef..733096711 100644 --- a/docs/layers/github-actions/github-actions.mdx +++ b/docs/layers/github-actions/github-actions.mdx @@ -8,7 +8,7 @@ import KeyPoints from '@site/src/components/KeyPoints'; import DocCardList from '@theme/DocCardList'; -GitHub Actions (GHA) are one of the cornerstones of your platform, automating everything from Terraform with Atmos to application build, test and deployment, fully integrated into AWS without any hardcoded, static credentials. + GitHub Actions (GHA) are one of the cornerstones of your platform, automating everything from Terraform with Atmos to application build, test and deployment, fully integrated into AWS without any hardcoded, static credentials. GitHub Actions offer a convenient way to achieve CI/CD automation directly on GitHub, without additional third-party services (e.g. CircleCI or Jenkins). GitHub doesn't charge extra for self-hosting runners, unlike many other platforms, making them an ideal choice for automation. Using self-hosted runners allows them to reside within your private networks, enabling you to manage resources like databases and Kubernetes clusters in private VPCs without exposing them publicly. We'll show you how to set up self-hosted runners (which are optional but recommended) and configure your IAM architecture to work with GitHub OIDC, so your Actions and workflows can assume AWS roles without relying on static credentials. diff --git a/docs/layers/gitops/gitops.mdx b/docs/layers/gitops/gitops.mdx index 7596c4878..0af251ae9 100644 --- a/docs/layers/gitops/gitops.mdx +++ b/docs/layers/gitops/gitops.mdx @@ -5,5 +5,257 @@ sidebar_class_name: hidden --- import Intro from '@site/src/components/Intro'; import KeyPoints from '@site/src/components/KeyPoints'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import ReactPlayer from 'react-player'; +import CodeBlock from '@theme/CodeBlock'; +import PartialAtmosTerraformPlan from '@site/examples/snippets/.github/workflows/atmos-terraform-plan.yaml'; +import PartialAtmosTerraformApply from '@site/examples/snippets/.github/workflows/atmos-terraform-apply.yaml'; +import PartialAtmosTerraformDispatch from '@site/examples/snippets/.github/workflows/atmos-terraform-dispatch.yaml'; +import PartialAtmosTerraformDriftDetection from '@site/examples/snippets/.github/workflows/atmos-terraform-drift-detection.yaml'; +import PartialAtmosTerraformDriftRemediation from '@site/examples/snippets/.github/workflows/atmos-terraform-drift-remediation.yaml'; +import PartialAtmosTerraformPlanMatrix from '@site/examples/snippets/.github/workflows/atmos-terraform-plan-matrix.yaml'; +import PartialAtmosTerraformApplyMatrix from '@site/examples/snippets/.github/workflows/atmos-terraform-apply-matrix.yaml'; -removed this page because it errors out without addition work. copy and fix this page from refarch-scaffold fundamentals + +GitOps is a cloud-native continuous deployment methodology that uses Git as the single source of truth for declarative infrastructure and applications. Changes to infrastructure or applications are made through Git commits, and the actual state is automatically adjusted to match the desired state expressed in the Git repository. This approach provides an audit trail for changes, simplifies rollback, and enhances collaboration and visibility across teams. + + + + +## The Problem + +Collaboration with Terraform in team environments is more difficult than traditional [release-engineering](/reference-architecture/fundamentals/release-engineering/) for web applications. Unlike containerized deployments, Terraform deployments are constantly modifying the state of infrastructure and behave a lot more like database migrations, except there are no transactions and therefore no practical way to do automated rollbacks. This means we have to be extra cautious. + +When teams start collaborating on infrastructure, the rate of change increases, and the likelihood of collisions as well. We need approval gates to control what changes and when, plus have the ability to review changes prior to deployment to make sure nothing catastrophic happens (e.g. database destroyed). Pull Requests are not enough to restrict what changes, since every Pull Request merged, changes the graph and therefore requires all other open Pull Requests to be re-validated. There's also a need to reconcile the desired state of infrastructure in Git with what is deployed; in busy team environments, a change can accidentally not be deployed or at other times, ClickOps can result in a drift between what's running and what's in code. + +Multiple platforms have emerged that solve this problem, under the general category of "Terraform Automation and Collaboration Software" or TACOS for short. Examples include Terraform Cloud, Spacelift, Env0, Scalr, and that's just a start. TACOs can easily cost tens of thousands of dollars a year and can be cost-prohibitive for certain companies. + +## Our Solution + +We've implemented [GitHub Actions](https://atmos.tools/category/github-actions) designed around our architecture and toolset. These actions run Atmos commands to generate a Terraform planfile, store the planfile in a S3 bucket with metadata in DynamoDB, and generate a plan summary on all pull requests. Then once the pull request is merged, a second workflow runs to pull that same planfile, apply it with Atmos commands, and then generate an apply summary. + +While this solution does not offer some of the more fine-grained policy controls of TACOs nor provide a centralized UI, it does provide many of the other benefits that the other solutions offer. But the overwhelming benefit is it's much cheaper and fully integrated with Cloud Posse's architecture and design. + +### Features + +* **Implements Native GitOps** with Atmos and Terraform +* **GitHub Actions** can be integrated seamlessly anywhere you need to run Terraform +* **No hardcoded credentials.** Use GitHub OIDC to assume roles. +* **Compatible with GitHub Cloud & Self-hosted Runners** for maximum flexibility. +* **Beautiful Job Summaries** don't clutter up pull requests with noisy GitHub comments +* **100% Open Source with No Platform Fees** means you can leverage your existing GitHub runners to provision infrastructure + +Expect these actions to constantly evolve as we build out these workflows. + +### Implementation + +Once the required S3 Bucket, DynamoDB table, and two separate roles to access Terraform planfiles and plan/apply Terraform are deployed, simply add your chosen [workflows](#workflows). Read the [Setup Documentation](/reference-architecture/setup/gitops/) for details on deploying the requirements. + +## Workflows + +The following GitHub Workflows should be used as examples. These are created in a given Infrastructure repository and can be modified however best suites your needs. For example, the labels we've chosen for triggering or skipping workflows are noted here as "Conventions" but can be changed however you would prefer. + +### Atmos Terraform Plan + +:::info Conventions + +Use the `no-plan` label on a Pull Request to skip this workflow. + +::: + +The Atmos Terraform Plan workflow is triggered for every affected component from the Atmos Describe Affected workflow. This workflow takes a matrix of components and stacks and creates a plan for each, using the [Atmos Terraform Plan composite action](https://github.com/cloudposse/github-action-atmos-terraform-plan). For more on the Atmos Terraform Plan composite action, see [the official atmos.tools documentation](https://atmos.tools/integrations/github-actions/atmos-terraform-plan). + +If an affected component is disabled with `terraform.settings.github.actions_enabled`, the component will show up as affected but all Terraform steps will be skipped. See [Enabling or disabling components](#enabling-or-disabling-components). + +
+atmos-terraform-plan + +{PartialAtmosTerraformPlan} + +
+ +### Atmos Terraform Apply + +:::info Conventions + +1. Use the `auto-apply` label on Pull Request to apply all plans on merge +1. Use the `no-apply` label on a Pull Request to skip _all workflows_ on merge +1. If a Pull Request has neither label, run drift detection for only the affected components and stacks. + +::: + +The Atmos Terraform Apply workflow runs on merges into main. There are two different workflows that can be triggered based on the given labels. + +If you attach the Apply label (typically `auto-apply`), this workflow will trigger the [Atmos Terraform Apply composite action](https://github.com/cloudposse/github-action-atmos-terraform-apply) for every affected component in this Pull Request. For more on the Atmos Terraform Apply composite action, see [the official atmos.tools documentation](https://atmos.tools/integrations/github-actions/atmos-terraform-apply). + +Alternatively, you can choose to merge the Pull Request _without_ labels. If the "apply" label and the "skip" label are not added, this workflow will trigger the [Atmos Drift Detection composite action](https://github.com/cloudposse/github-action-atmos-terraform-drift-detection) for only the affected components in this Pull Request. That action will create a GitHub Issue for every affected component that has unapplied changes. + +
+atmos-terraform-apply + +{PartialAtmosTerraformApply} + +
+ + +### Atmos Terraform Drift Detection + +:::info Max Opened Issues + +Drift detection is configured to open a set number of Issues at a time. See `max-opened-issues` for the `cloudposse/github-action-atmos-terraform-drift-detection` composite action. + +::: + +The Atmos Terraform Drift Detection workflow runs on a schedule. This workflow will gather _every component in every stack_ and run the [Atmos Drift Detection composite action](https://github.com/cloudposse/github-action-atmos-terraform-drift-detection) for each. + +For every stack and component included with drift detection, the workflow first triggers an Atmos Terraform Plan. + +1. If there are changes, the workflow will then create or update a GitHub Issue for the given component and stack. +2. If there are no changes, the workflow will check if there's an existing Issue. If there's an existing issue, the workflow will then mark that Issue as resolved. + +
+atmos-terraform-drift-detection + +{PartialAtmosTerraformDriftDetection} + +
+ +### Atmos Terraform Drift Remediation + +:::info Conventions + +Use the `apply` label to apply the plan for the given stack and component + +::: + +The Atmos Terraform Drift Remediation workflow is triggered from an open Github Issue when the remediation label is added to the Issue. This workflow will run the [Atmos Terraform Drift Remediation composite action](https://github.com/cloudposse/github-action-atmos-terraform-drift-remediation) for the given component and stack in the Issue. This composite action will apply Terraform using the [Atmos Terraform Apply composite action](https://github.com/cloudposse/github-action-atmos-terraform-apply) and close out the Issue if the changes are applied successfully. + +The `drift` and `remediated` labels are added to Issues by the composite action directly. The `drift` is added to all Issues created by Atmos Terraform Drift Detection. Remediation will only run on Issues that have this label. Whereas the `remediated` label is added to any Issue that has been resolved by Atmos Terraform Drift Remediation. + +
+atmos-terraform-drift-remediation + +{PartialAtmosTerraformDriftRemediation} + +
+ + +### Atmos Terraform Dispatch + +The Atmos Terraform Dispatch workflow is optionally included and is not required for any other workflow. This workflow can be triggered by workflow dispatch, will take a single stack and single component as arguments, and will run Atmos Terraform workflows for planning and applying for only the given target. + +This workflow includes a boolean option for both "Terraform Plan" and "Terraform Apply": + +1. If only "Terraform Plan" is selected, the workflow will call the [Atmos Terraform Plan Worker](./.github/workflows/atmos-terraform-plan-matrix.yaml) workflow to create a new planfile +1. If only "Terraform Apply" is selected, the workflow will call the [Atmos Terraform Apply Worker](./.github/workflows/atmos-terraform-apply-matrix.yaml) for the given branch. This action will take the latest planfile for the given stack, component, and branch and apply it. +1. If both are selected, the workflow will run both actions. This means it will create a new planfile and then immediately apply it. +1. If neither are selected, the workflow does nothing. + +
+atmos-terraform-dispatch + +{PartialAtmosTerraformDispatch} + +
+ +### Atmos Terraform Plan Matrix (Reusable) + +The Atmos Terraform Plan Matrix is reusable workflow that called by another workflows to create a terraform plan. + +
+atmos-terraform-plan-matrix + +{PartialAtmosTerraformPlanMatrix} + +
+ + +### Atmos Terraform Apply Matrix (Reusable) + +The Atmos Terraform Apply Matrix is reusable workflow called by another workflow to apply an existing plan file. + +
+atmos-terraform-apply-matrix + +{PartialAtmosTerraformApplyMatrix} + +
+ + +## References + +- [Setup Documentation](/reference-architecture/setup/gitops/) +- [Atmos integration documentation](https://atmos.tools/category/integrations/github-actions). +- [GitHub OIDC Integration with AWS](/reference-architecture/how-to-guides/integrations/github/github-oidc-with-aws/) +- [`cloudposse/github-action-atmos-terraform-plan`](https://github.com/cloudposse/github-action-atmos-terraform-plan) +- [`cloudposse/github-action-atmos-terraform-apply`](https://github.com/cloudposse/github-action-atmos-terraform-apply) +- [`cloudposse/github-action-atmos-terraform-drift-detection`](https://github.com/cloudposse/github-action-atmos-terraform-drift-detection) +- [`cloudposse/github-action-atmos-terraform-drift-remediation`](https://github.com/cloudposse/github-action-atmos-terraform-drift-remediation) +- [`gitops/s3-bucket`](/components/library/aws/s3-bucket/): Deploy a S3 Bucket using the `s3-bucket` component. This bucket holds Terraform planfiles. +- [`gitops/dynamodb`](/components/library/aws/dynamodb/): Deploy a DynamoDB table using the `dynamodb` component. This table is used to hold metadata for Terraform Plans +- [`gitops`](/components/library/aws/gitops/): Deploys an IAM Role that GitHub is able to assume via GitHub OIDC. This role has access to the bucket and table for planfiles. + +## FAQ + +### What are the included labels? + +By default, Cloud Posse includes a few labels for common use-cases. These labels are included with the top level workflows, so they can be modified as desired. + +On Pull Requests: + +1. `auto-apply` - If added, the Atmos Terraform Apply workflow will be triggered for all affected components when the Pull Request is merged. +1. `no-plan` - If added, the Atmos Terraform Plan workflow will be skipped on commits to the Pull Request, and the Atmos Apply workflow will be skipped when the Pull Request is merged. + +On Issues: + +1. `apply` - If added, the Atmos Terraform Drift Remediation workflow will be triggered for the given component and stack +1. `drift` - This label is added to all Issues created by Atmos Terraform Drift Detection. Remediation will only run on Issues that have this label. +1. `remediated` - This label is added to any Issue that has been resolved by Atmos Terraform Drift Remediation + +### Enabling or disabling components + +Components are included in the Atmos GitHub Action workflows only if they have actions enabled with the `terraform.settings.github.actions_enabled` option. + +If they do not have this setting or the value is `false`, the component may still appear in the list of affected components, but Terraform will not be run against the given component and stack. + +:::info Global Defaults + +Typically Cloud Posse sets the default value to `true` for all components and disables individual components on a case-by-case basis. + +For example in an `acme` organization, the default value could be set with `stacks/orgs/acme/_defaults.yaml`: + +```yaml +terraform: + # These settings are applied to ALL components by default but can be overwritten + settings: + github: + actions_enabled: true +``` + +And the `account` component could be disabled with `stacks/catalog/account.yaml`: + +```yaml +components: + terraform: + account: + settings: + github: + actions_enabled: false +``` + +::: + +### I cannot assume the `gitops` role from GitHub Workflows + +The following error commonly occurs when setting up `gitops` roles and permission: + +``` +Error: Could not assume role with OIDC: Not authorized to perform sts:AssumeRoleWithWebIdentity +``` + +To resolve this error, thoroughly read through each of the [Authentication Prerequisites](/reference-architecture/setup/gitops/#authentication-prerequisites) for GitOps setup. In particular, check the capitalization of `trusted_github_repos` within `aws-teams` and check the `permissions` for the workflow in GitHub. + +### How does GitHub OIDC work with AWS? + +Please see [How to use GitHub OIDC with AWS](/reference-architecture/how-to-guides/integrations/github/github-oidc-with-aws/) diff --git a/docs/layers/gitops/03-gitops.mdx b/docs/layers/gitops/setup.mdx similarity index 73% rename from docs/layers/gitops/03-gitops.mdx rename to docs/layers/gitops/setup.mdx index 1420b8839..4541c67ec 100644 --- a/docs/layers/gitops/03-gitops.mdx +++ b/docs/layers/gitops/setup.mdx @@ -1,9 +1,12 @@ --- -title: "GitOps" -sidebar_label: "GitOps" +title: "Setup GitOps with GitHub Actions" +sidebar_label: "Setup" +sidebar_position: 1 --- import Intro from '@site/src/components/Intro'; import KeyPoints from '@site/src/components/KeyPoints'; +import Steps from '@site/src/components/Steps'; +import TaskList from '@site/src/components/TaskList'; ## Quick Start @@ -30,14 +33,21 @@ If you do not wish to use Self Hosted runners, simply change the `runs-on` optio ### Set Up GitHub Variables The `gitops` stack config depends on the following GitHub variables: -* `ATMOS_VERSION` - The version of Atmos to use -* `ATMOS_CONFIG_PATH` - The path to the Atmos config file + +
+
`ATMOS_VERSION`
+
The version of Atmos to use
+
`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) -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 + + 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 + ### Authentication Prerequisites @@ -46,22 +56,22 @@ these components should already be deployed with `aws-teams`/`aws-team-roles` an but `github-oidc-provider` will likely need to deployed to several additional accounts. Verify the following to complete the authentication prerequisites. -1. The `gitops` Team is defined and deployed by `aws-teams`. -2. The `gitops` team adds a trusted relationship with the given infrastructure repo, via `trusted_github_repos`. - _Capitalization matters!_ - -```yaml -trusted_github_repos: - gitops: - - "acme/infra-acme" -``` - -3. The `aws-team-roles` default catalog allows the `gitops` team to assume the `terraform` role, including anywhere - `aws-team-roles` is overwritten (`plat-dev` and `plat-sandbox`) -4. `tfstate-backend` allows `gitops` to assume the default access role from the `core-identity` account -5. `github-oidc-provider` is deployed to every account that GitHub will be able to access. This should be every account - except `root`. -6. The workflows have adequate permission + + - The `gitops` Team is defined and deployed by `aws-teams`. + - The `gitops` team adds a trusted relationship with the given infrastructure repo, via `trusted_github_repos`. + _Capitalization matters!_ + ```yaml + trusted_github_repos: + gitops: + - "acme/infra-acme" + ``` + - The `aws-team-roles` default catalog allows the `gitops` team to assume the `terraform` role, including anywhere + `aws-team-roles` is overwritten (`plat-dev` and `plat-sandbox`) + - `tfstate-backend` allows `gitops` to assume the default access role from the `core-identity` account + - `github-oidc-provider` is deployed to every account that GitHub will be able to access. This should be every account + except `root`. + - The workflows have adequate permission + :::info GitHub Workflow Permissions diff --git a/docs/layers/identity/aws-saml.mdx b/docs/layers/identity/aws-saml/aws-saml.mdx similarity index 96% rename from docs/layers/identity/aws-saml.mdx rename to docs/layers/identity/aws-saml/aws-saml.mdx index 1b5422d7a..7dc9b2952 100644 --- a/docs/layers/identity/aws-saml.mdx +++ b/docs/layers/identity/aws-saml/aws-saml.mdx @@ -1,7 +1,7 @@ --- title: "Using AWS SAML to Access AWS" -sidebar_label: "AWS SAML" -sidebar_position: 20 +sidebar_label: "AWS SAML (Optional)" +sidebar_position: 8 description: Authenticate with AWS via a federated identity using AWS SAML. --- import Intro from '@site/src/components/Intro'; diff --git a/docs/layers/identity/idp/office365/how-to-setup-saml-login-to-aws-from-office-365.mdx b/docs/layers/identity/aws-saml/how-to-setup-saml-login-to-aws-from-office-365.mdx similarity index 100% rename from docs/layers/identity/idp/office365/how-to-setup-saml-login-to-aws-from-office-365.mdx rename to docs/layers/identity/aws-saml/how-to-setup-saml-login-to-aws-from-office-365.mdx diff --git a/docs/layers/identity/aws-sso.mdx b/docs/layers/identity/aws-sso/aws-sso.mdx similarity index 89% rename from docs/layers/identity/aws-sso.mdx rename to docs/layers/identity/aws-sso/aws-sso.mdx index f1016ef69..f807620bc 100644 --- a/docs/layers/identity/aws-sso.mdx +++ b/docs/layers/identity/aws-sso/aws-sso.mdx @@ -1,12 +1,13 @@ --- title: "AWS Identity Center (SSO) ClickOps" -sidebar_label: "Integrate AWS Identity Center" -sidebar_position: 10 +sidebar_label: "Setup Identity Center" +sidebar_position: 7 description: Setup AWS SSO with external IdPs --- import Intro from '@site/src/components/Intro'; import KeyPoints from '@site/src/components/KeyPoints'; import Steps from '@site/src/components/Steps'; +import DocCardList from '@theme/DocCardList'; This guide provides an overview of setting up AWS Identity Center (SSO) with ClickOps, detailing prerequisites and supported external identity providers. It explains how to integrate AWS SSO with providers like Azure AD, JumpCloud, Okta, and Google Workspace, including specific steps for configuring each. @@ -21,10 +22,17 @@ This guide provides an overview of setting up AWS Identity Center (SSO) with Cli 4. Enable AWS SSO + +## Common Identity Providers + +These are the instructions for the most common Identity Providers. For other providers, see the next section. + + + + ## Supported External Identity Providers -[Follow the AWS documentation for setting up an IdP integration with AWS](https://docs.aws.amazon.com/singlesignon/latest/userguide/supported-idps.html). -This list includes Azure AD, CyberArk, JumpCloud, Okta, OneLogin, and Ping Identity. For other providers, see the next +[Follow the AWS documentation for setting up an IdP integration with AWS](https://docs.aws.amazon.com/singlesignon/latest/userguide/supported-idps.html). This list includes Azure AD, CyberArk, JumpCloud, Okta, OneLogin, and Ping Identity. For other providers, see the next section. :::caution Integrating JumpCloud with AWS IAM Identity Center diff --git a/docs/layers/identity/idp/office365/how-to-setup-office-365-aws-sso.mdx b/docs/layers/identity/aws-sso/office365/how-to-setup-office-365-aws-sso.mdx similarity index 96% rename from docs/layers/identity/idp/office365/how-to-setup-office-365-aws-sso.mdx rename to docs/layers/identity/aws-sso/office365/how-to-setup-office-365-aws-sso.mdx index 28d1c38bf..6bd4eeae1 100644 --- a/docs/layers/identity/idp/office365/how-to-setup-office-365-aws-sso.mdx +++ b/docs/layers/identity/aws-sso/office365/how-to-setup-office-365-aws-sso.mdx @@ -22,7 +22,7 @@ Azure Devops has **Enterprise Apps** that are used to sign into things from your ### AWS SSO - 1. Under [https://aad.portal.azure.com/#allservices/category/All](https://aad.portal.azure.com/#allservices/category/All) go to **Enterprise Applications**
+ 1. Under [https://aad.portal.azure.com/#allservices/category/All](https://aad.portal.azure.com/#allservices/category/All) go to **Enterprise Applications**
2. Click **New Application** diff --git a/docs/layers/identity/idp/office365/office365.mdx b/docs/layers/identity/aws-sso/office365/office365.mdx similarity index 100% rename from docs/layers/identity/idp/office365/office365.mdx rename to docs/layers/identity/aws-sso/office365/office365.mdx diff --git a/docs/layers/identity/idp/okta/how-to-setup-okta-aws-sso.mdx b/docs/layers/identity/aws-sso/okta/how-to-setup-okta-aws-sso.mdx similarity index 100% rename from docs/layers/identity/idp/okta/how-to-setup-okta-aws-sso.mdx rename to docs/layers/identity/aws-sso/okta/how-to-setup-okta-aws-sso.mdx diff --git a/docs/layers/identity/idp/okta/okta.mdx b/docs/layers/identity/aws-sso/okta/okta.mdx similarity index 100% rename from docs/layers/identity/idp/okta/okta.mdx rename to docs/layers/identity/aws-sso/okta/okta.mdx diff --git a/docs/layers/identity/centralized-terraform-access.mdx b/docs/layers/identity/centralized-terraform-access.mdx index 85fd0b9f6..b24586f70 100644 --- a/docs/layers/identity/centralized-terraform-access.mdx +++ b/docs/layers/identity/centralized-terraform-access.mdx @@ -1,7 +1,7 @@ --- title: "Centralized access management for Terraform" sidebar_label: "Understand Terraform Access" -sidebar_position: 00 +sidebar_position: 2 description: "Overview of centralized access management for AWS" --- import Intro from '@site/src/components/Intro'; diff --git a/docs/layers/identity/deploy.mdx b/docs/layers/identity/deploy.mdx index 78e0775fb..857020eca 100644 --- a/docs/layers/identity/deploy.mdx +++ b/docs/layers/identity/deploy.mdx @@ -1,7 +1,7 @@ --- title: "Deploy AWS Teams and Team Roles across your AWS Organization" sidebar_label: "Deploy Roles" -sidebar_position: 30 +sidebar_position: 3 description: Provision AWS teams, integrate SSO, generate role configurations. --- import Intro from '@site/src/components/Intro'; diff --git a/docs/layers/identity/design-decisions/design-decisions.mdx b/docs/layers/identity/design-decisions/design-decisions.mdx index 599f125e5..c369aa070 100644 --- a/docs/layers/identity/design-decisions/design-decisions.mdx +++ b/docs/layers/identity/design-decisions/design-decisions.mdx @@ -1,7 +1,7 @@ --- title: Design Decisions -sidebar_label: Design Decisions -sidebar_position: 10 +sidebar_label: Review Design Decisions +sidebar_position: 1 --- import DocCardList from '@theme/DocCardList'; import Intro from '@site/src/components/Intro'; diff --git a/docs/layers/identity/docs/aws-access-control-architecture.mdx b/docs/layers/identity/docs/aws-access-control-architecture.mdx index 86fb18c46..ef57a593e 100644 --- a/docs/layers/identity/docs/aws-access-control-architecture.mdx +++ b/docs/layers/identity/docs/aws-access-control-architecture.mdx @@ -1,6 +1,7 @@ --- title: "Access Control Architecture" sidebar_position: 100 +description: Explanation dynamic terraform roles and access control --- import Intro from '@site/src/components/Intro'; import KeyPoints from '@site/src/components/KeyPoints'; @@ -120,11 +121,11 @@ Cloud Posse's reference architecture uses a number of accounts to separate out resources in this way. Here is a sample of the accounts we use:
-
plat-prod
+
`plat-prod`
Holds the production resources for the company, the ones that provide the company's services to its customers.
-
plat-dev
+
`plat-dev`
Holds the development resources for the company, the ones that are used to develop the company's services.
-
core-audit
+
`core-audit`
Holds the logs and other resources that are used to audit the other accounts.
diff --git a/docs/layers/identity/docs/aws-access-control-evolution.mdx b/docs/layers/identity/docs/aws-access-control-evolution.mdx index 4ed8ffb59..ba344d735 100644 --- a/docs/layers/identity/docs/aws-access-control-evolution.mdx +++ b/docs/layers/identity/docs/aws-access-control-evolution.mdx @@ -1,12 +1,11 @@ --- title: "Access Control Evolution" sidebar_position: 100 +description: "Understand how our access model has evolved" --- import Intro from '@site/src/components/Intro'; import KeyPoints from '@site/src/components/KeyPoints'; -# Access Control Evolution - ## Overview Unsurprisingly, Cloud Posse has evolved its approach to access control over time. diff --git a/docs/layers/identity/docs/aws-access-control.mdx b/docs/layers/identity/docs/aws-access-control.mdx index 0383cdd9c..1a16264c4 100644 --- a/docs/layers/identity/docs/aws-access-control.mdx +++ b/docs/layers/identity/docs/aws-access-control.mdx @@ -1,6 +1,7 @@ --- title: "AWS Access Control" sidebar_position: 100 +description: "How we manage access to AWS resources" --- import Intro from '@site/src/components/Intro'; import KeyPoints from '@site/src/components/KeyPoints'; diff --git a/docs/layers/identity/docs/aws-restricting-admin-access.mdx b/docs/layers/identity/docs/aws-restricting-admin-access.mdx index 4e1fe2ab1..85ba96518 100644 --- a/docs/layers/identity/docs/aws-restricting-admin-access.mdx +++ b/docs/layers/identity/docs/aws-restricting-admin-access.mdx @@ -1,5 +1,6 @@ --- title: "Restricting Admin Access to Sensitive Accounts" +sidebar_label: "Restricting Admin Access" sidebar_position: 100 --- import Intro from '@site/src/components/Intro'; diff --git a/docs/layers/identity/docs/docs.mdx b/docs/layers/identity/docs/docs.mdx index d1ddcd168..15c936eca 100644 --- a/docs/layers/identity/docs/docs.mdx +++ b/docs/layers/identity/docs/docs.mdx @@ -1,6 +1,7 @@ --- title: "Documentation" sidebar_position: 10 +sidebar_class_name: compact --- import Intro from '@site/src/components/Intro'; import KeyPoints from '@site/src/components/KeyPoints'; diff --git a/docs/layers/identity/docs/dynamic-terraform-roles.mdx b/docs/layers/identity/docs/dynamic-terraform-roles.mdx index 584cdf662..5e34ec906 100644 --- a/docs/layers/identity/docs/dynamic-terraform-roles.mdx +++ b/docs/layers/identity/docs/dynamic-terraform-roles.mdx @@ -1,5 +1,7 @@ --- title: "Dynamic Terraform Roles" +sidebar_label: "Dynamic Terraform Roles" +description: "Learn how Terraform automatically discovers roles" sidebar_position: 100 --- import Intro from '@site/src/components/Intro'; diff --git a/docs/layers/identity/how-to-log-into-aws.mdx b/docs/layers/identity/how-to-log-into-aws.mdx index d762b9c81..67f9c7b9e 100644 --- a/docs/layers/identity/how-to-log-into-aws.mdx +++ b/docs/layers/identity/how-to-log-into-aws.mdx @@ -1,7 +1,7 @@ --- title: "How to Log into AWS" sidebar_label: "Log into AWS" -sidebar_position: 50 +sidebar_position: 9 --- import Intro from '@site/src/components/Intro'; import KeyPoints from '@site/src/components/KeyPoints'; @@ -10,9 +10,11 @@ import Step from '@site/src/components/Step'; import StepNumber from '@site/src/components/StepNumber'; import Note from '@site/src/components/Note'; + We use Leapp to facilitate logging into AWS. Leapp is a tool that allows you to authenticate with your organization's Identity Provider (IdP) and then assume an IAM Role in AWS. This allows you to use your organization's SSO to authenticate with AWS. + ## Requirements @@ -152,7 +154,7 @@ The following steps are required only for initial setup. -## Use +## Usage After initial setup, quickly connect to AWS with the following steps: diff --git a/docs/layers/identity/idp/idp.mdx b/docs/layers/identity/idp/idp.mdx deleted file mode 100644 index 22c02c4a8..000000000 --- a/docs/layers/identity/idp/idp.mdx +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Identity Provider (IDP) -sidebar_label: Identity Provider (IDP) ---- -import DocCardList from '@theme/DocCardList'; - - diff --git a/docs/layers/identity/tutorials/how-to-easily-switch-aws-account-roles.mdx b/docs/layers/identity/tutorials/how-to-easily-switch-aws-account-roles.mdx index 77fa21dd7..27d51dee6 100644 --- a/docs/layers/identity/tutorials/how-to-easily-switch-aws-account-roles.mdx +++ b/docs/layers/identity/tutorials/how-to-easily-switch-aws-account-roles.mdx @@ -5,6 +5,11 @@ sidebar_position: 10 --- import Intro from '@site/src/components/Intro'; import KeyPoints from '@site/src/components/KeyPoints'; +import Steps from '@site/src/components/Steps'; + + + Learn how to switch between multiple AWS account roles using the `aws-extend-switch-roles` browser extension. Just follow the step-by-step instructions for installing the extension, configuring it with your AWS accounts, and using it to switch roles seamlessly. + ## Problem @@ -20,6 +25,7 @@ switch roles across many accounts easily from the browser. ::: + 1. Refer to the [aws-extend-switch-roles documentation](https://github.com/tilfinltd/aws-extend-switch-roles#install) to install the extension on the browser of your choice. @@ -27,36 +33,42 @@ switch roles across many accounts easily from the browser. [AWS CLI Access](https://github.com/BrightDotAi/infrastructure/blob/main/docs/authentication/onboarding.md#aws-cli-access) procedure to set up your local workstation and access the Geodesic shell. -3. From within Geodesic Shell +3. Enter the Geodesic Shell -4. If the option is available, run the `aws-accounts gen-switch-roles` command to save the `aws-extend-switch-roles` - configuration to your home directory. + + - If the option is available, run the `aws-accounts gen-switch-roles` command to save the `aws-extend-switch-roles` + configuration to your home directory. -``` -⨠ aws-accounts gen-switch-roles > /localhost/aws-extend-profiles -``` + ```shell + ⨠ aws-accounts gen-switch-roles > /localhost/aws-extend-profiles + ``` -2. If not, use this workaround + - If not, use this workaround -``` -⨠ aws-accounts gen-saml | grep -v source_profile | grep admin -C 1 | grep -v '\-\-' > /localhost/aws-extend-profiles -``` + ```shell + ⨠ aws-accounts gen-saml | \ + grep -v source_profile | \ + grep admin -C 1 | \ + grep -v '\-\-' > /localhost/aws-extend-profiles + ``` -3. If no `aws-accounts` use this `aws-gen-config` + - If no `aws-accounts` use this `aws-gen-config` -``` -⨠ aws-gen-config | grep -v source_profile | grep admin -C 1 | grep -v '\-\-' > /localhost/aws-extend-profiles -``` + ```shell + ⨠ aws-gen-config | \ + grep -v source_profile | \ + grep admin -C 1 | \ + grep -v '\-\-' > /localhost/aws-extend-profiles + ``` + 4. In your browser, left-click the `aws-extend-switch-roles` extension (light-blue icon with a key) and click on the `Configuration` option. -5. Open `~/aws-extend-profiles` in your home directory, copy its contents, and paste it into the form, then click - `Save`. +5. Open `~/aws-extend-profiles` in your home directory, copy its contents, and paste it into the form, then click `Save`. -6. Follow the - [AWS Sign-In Procedure](https://github.com/BrightDotAi/infrastructure/blob/main/docs/authentication/onboarding.md#aws-console-sign-in-via-okta-apps-dashboard) - to open the AWS Console. +6. Follow the [AWS Sign-In Procedure](https://github.com/BrightDotAi/infrastructure/blob/main/docs/authentication/onboarding.md#aws-console-sign-in-via-okta-apps-dashboard) to open the AWS Console. + You should now be able to switch IAM roles across accounts by clicking the extension in your browser and selecting the desired IAM role. diff --git a/docs/layers/identity/tutorials/leapp/leapp.mdx b/docs/layers/identity/tutorials/leapp/leapp.mdx index cc2ca8cab..562e5bdad 100644 --- a/docs/layers/identity/tutorials/leapp/leapp.mdx +++ b/docs/layers/identity/tutorials/leapp/leapp.mdx @@ -224,7 +224,7 @@ session started Below is some guidance to the Leapp documentation that applies as of the time of this writing. By the time you read this it may be out of date, but hopefully will still be of help in guiding you through the Leapp site. -
+
- The “AWS Profile” setting in Leapp must match _exactly_ the value of `$AWS_PROFILE` you found in Geodesic in the earlier step. @@ -250,7 +250,7 @@ names and their corresponding profile names. An icon for each session will appea if logged in (at least those are the current defaults for the “Light” color scheme on macOS). Just select the menu item to toggle the state. -
+
Alternately, you can select “Show” from the menu and be shown a richer UI where you can do more, but still, the main thing is that you click on a session name to change its state and the indicator shows gray for logged out and orange for diff --git a/docs/layers/monitoring/datadog/datadog.mdx b/docs/layers/monitoring/datadog/datadog.mdx index 039b81566..3600d873d 100644 --- a/docs/layers/monitoring/datadog/datadog.mdx +++ b/docs/layers/monitoring/datadog/datadog.mdx @@ -180,7 +180,7 @@ SLIs should be derived values (e.g. from KPIs) Every SLI may or may not have an SLO. An SLI may be part of one or more SLOs. -
+
Example SLIs: diff --git a/docs/layers/monitoring/datadog/tutorials/how-to-setup-datadog-cluster-checks-and-network-monitors-for-ext.mdx b/docs/layers/monitoring/datadog/tutorials/how-to-setup-datadog-cluster-checks-and-network-monitors-for-ext.mdx index c62ad6dd3..432413159 100644 --- a/docs/layers/monitoring/datadog/tutorials/how-to-setup-datadog-cluster-checks-and-network-monitors-for-ext.mdx +++ b/docs/layers/monitoring/datadog/tutorials/how-to-setup-datadog-cluster-checks-and-network-monitors-for-ext.mdx @@ -42,9 +42,9 @@ Upgrade to the latest and add your network checks as yaml. This follows the same After your Cluster Checks are setup we need to create monitors for them. -
+
-
+
:::info Http check will verify successful HTTP checks on a URL @@ -52,7 +52,7 @@ Http check will verify successful HTTP checks on a URL SSL check will verify the certificate of your URL ::: -
+
```yaml https-checks: @@ -86,4 +86,4 @@ https-checks: ok: 1 ``` -
+
diff --git a/docs/layers/network-and-dns/access-network.mdx b/docs/layers/network/access-network.mdx similarity index 100% rename from docs/layers/network-and-dns/access-network.mdx rename to docs/layers/network/access-network.mdx diff --git a/docs/layers/network-and-dns/connect-network.mdx b/docs/layers/network/connect-network.mdx similarity index 100% rename from docs/layers/network-and-dns/connect-network.mdx rename to docs/layers/network/connect-network.mdx diff --git a/docs/layers/network-and-dns/deploy-vpcs.mdx b/docs/layers/network/deploy-vpcs.mdx similarity index 100% rename from docs/layers/network-and-dns/deploy-vpcs.mdx rename to docs/layers/network/deploy-vpcs.mdx diff --git a/docs/layers/network-and-dns/design-decisions/decide-on-aws-account-vpc-subnet-cidr-strategy.mdx b/docs/layers/network/design-decisions/decide-on-aws-account-vpc-subnet-cidr-strategy.mdx similarity index 100% rename from docs/layers/network-and-dns/design-decisions/decide-on-aws-account-vpc-subnet-cidr-strategy.mdx rename to docs/layers/network/design-decisions/decide-on-aws-account-vpc-subnet-cidr-strategy.mdx diff --git a/docs/layers/network-and-dns/design-decisions/decide-on-cidr-allocation.mdx b/docs/layers/network/design-decisions/decide-on-cidr-allocation.mdx similarity index 100% rename from docs/layers/network-and-dns/design-decisions/decide-on-cidr-allocation.mdx rename to docs/layers/network/design-decisions/decide-on-cidr-allocation.mdx diff --git a/docs/layers/network-and-dns/design-decisions/decide-on-client-vpn-options.mdx b/docs/layers/network/design-decisions/decide-on-client-vpn-options.mdx similarity index 100% rename from docs/layers/network-and-dns/design-decisions/decide-on-client-vpn-options.mdx rename to docs/layers/network/design-decisions/decide-on-client-vpn-options.mdx diff --git a/docs/layers/network-and-dns/design-decisions/decide-on-hostname-scheme-for-service-discovery.mdx b/docs/layers/network/design-decisions/decide-on-hostname-scheme-for-service-discovery.mdx similarity index 100% rename from docs/layers/network-and-dns/design-decisions/decide-on-hostname-scheme-for-service-discovery.mdx rename to docs/layers/network/design-decisions/decide-on-hostname-scheme-for-service-discovery.mdx diff --git a/docs/layers/network-and-dns/design-decisions/decide-on-how-to-support-tls.mdx b/docs/layers/network/design-decisions/decide-on-how-to-support-tls.mdx similarity index 100% rename from docs/layers/network-and-dns/design-decisions/decide-on-how-to-support-tls.mdx rename to docs/layers/network/design-decisions/decide-on-how-to-support-tls.mdx diff --git a/docs/layers/network-and-dns/design-decisions/decide-on-ipv4-and-ipv6-support.mdx b/docs/layers/network/design-decisions/decide-on-ipv4-and-ipv6-support.mdx similarity index 100% rename from docs/layers/network-and-dns/design-decisions/decide-on-ipv4-and-ipv6-support.mdx rename to docs/layers/network/design-decisions/decide-on-ipv4-and-ipv6-support.mdx diff --git a/docs/layers/network-and-dns/design-decisions/decide-on-opting-into-non-default-regions.mdx b/docs/layers/network/design-decisions/decide-on-opting-into-non-default-regions.mdx similarity index 100% rename from docs/layers/network-and-dns/design-decisions/decide-on-opting-into-non-default-regions.mdx rename to docs/layers/network/design-decisions/decide-on-opting-into-non-default-regions.mdx diff --git a/docs/layers/network-and-dns/design-decisions/decide-on-organization-supernet-cidr-ranges.mdx b/docs/layers/network/design-decisions/decide-on-organization-supernet-cidr-ranges.mdx similarity index 90% rename from docs/layers/network-and-dns/design-decisions/decide-on-organization-supernet-cidr-ranges.mdx rename to docs/layers/network/design-decisions/decide-on-organization-supernet-cidr-ranges.mdx index 935289c6b..f5ec3bafc 100644 --- a/docs/layers/network-and-dns/design-decisions/decide-on-organization-supernet-cidr-ranges.mdx +++ b/docs/layers/network/design-decisions/decide-on-organization-supernet-cidr-ranges.mdx @@ -29,11 +29,11 @@ import KeyPoints from '@site/src/components/KeyPoints'; ### Example -
+
## Pro Tip Use the [https://tidalmigrations.com/subnet-builder/](https://tidalmigrations.com/subnet-builder/) with an additional overlay from CleanshotX. -
+
diff --git a/docs/layers/network-and-dns/design-decisions/decide-on-primary-aws-region.mdx b/docs/layers/network/design-decisions/decide-on-primary-aws-region.mdx similarity index 100% rename from docs/layers/network-and-dns/design-decisions/decide-on-primary-aws-region.mdx rename to docs/layers/network/design-decisions/decide-on-primary-aws-region.mdx diff --git a/docs/layers/network-and-dns/design-decisions/decide-on-service-discovery-domain.mdx b/docs/layers/network/design-decisions/decide-on-service-discovery-domain.mdx similarity index 100% rename from docs/layers/network-and-dns/design-decisions/decide-on-service-discovery-domain.mdx rename to docs/layers/network/design-decisions/decide-on-service-discovery-domain.mdx diff --git a/docs/layers/network-and-dns/design-decisions/decide-on-transit-gateway-requirements.mdx b/docs/layers/network/design-decisions/decide-on-transit-gateway-requirements.mdx similarity index 100% rename from docs/layers/network-and-dns/design-decisions/decide-on-transit-gateway-requirements.mdx rename to docs/layers/network/design-decisions/decide-on-transit-gateway-requirements.mdx diff --git a/docs/layers/network-and-dns/design-decisions/decide-on-vanity-branded-domain.mdx b/docs/layers/network/design-decisions/decide-on-vanity-branded-domain.mdx similarity index 100% rename from docs/layers/network-and-dns/design-decisions/decide-on-vanity-branded-domain.mdx rename to docs/layers/network/design-decisions/decide-on-vanity-branded-domain.mdx diff --git a/docs/layers/network-and-dns/design-decisions/decide-on-vpc-nat-strategy.mdx b/docs/layers/network/design-decisions/decide-on-vpc-nat-strategy.mdx similarity index 90% rename from docs/layers/network-and-dns/design-decisions/decide-on-vpc-nat-strategy.mdx rename to docs/layers/network/design-decisions/decide-on-vpc-nat-strategy.mdx index 31503bade..8a089e317 100644 --- a/docs/layers/network-and-dns/design-decisions/decide-on-vpc-nat-strategy.mdx +++ b/docs/layers/network/design-decisions/decide-on-vpc-nat-strategy.mdx @@ -19,7 +19,7 @@ originates from a specific set of IPs ::: -
+
#### Pros @@ -36,12 +36,12 @@ originates from a specific set of IPs ### Option 2 - One VPC per Region, Per Platform Account with Centralized NAT Gateways per AZ in Network Account -
+
The Compliant Framework for Federal and DoD Workloads in AWS GovCloud (US) advocates for a strategy like this, whereby in the Network (transit) account, there will be a DMZ with a Firewall. -
+
#### Pros diff --git a/docs/layers/network-and-dns/design-decisions/decide-on-vpc-network-traffic-isolation-policy.mdx b/docs/layers/network/design-decisions/decide-on-vpc-network-traffic-isolation-policy.mdx similarity index 100% rename from docs/layers/network-and-dns/design-decisions/decide-on-vpc-network-traffic-isolation-policy.mdx rename to docs/layers/network/design-decisions/decide-on-vpc-network-traffic-isolation-policy.mdx diff --git a/docs/layers/network-and-dns/design-decisions/decide-vpc-peering-requirements-e-g-to-legacy-env.mdx b/docs/layers/network/design-decisions/decide-vpc-peering-requirements-e-g-to-legacy-env.mdx similarity index 100% rename from docs/layers/network-and-dns/design-decisions/decide-vpc-peering-requirements-e-g-to-legacy-env.mdx rename to docs/layers/network/design-decisions/decide-vpc-peering-requirements-e-g-to-legacy-env.mdx diff --git a/docs/layers/network-and-dns/design-decisions/design-decisions.mdx b/docs/layers/network/design-decisions/design-decisions.mdx similarity index 100% rename from docs/layers/network-and-dns/design-decisions/design-decisions.mdx rename to docs/layers/network/design-decisions/design-decisions.mdx diff --git a/docs/layers/network-and-dns/dns-setup.mdx b/docs/layers/network/dns-setup.mdx similarity index 94% rename from docs/layers/network-and-dns/dns-setup.mdx rename to docs/layers/network/dns-setup.mdx index 3ed45ad7a..e4c5c8dca 100644 --- a/docs/layers/network-and-dns/dns-setup.mdx +++ b/docs/layers/network/dns-setup.mdx @@ -12,7 +12,7 @@ import StepNumber from '@site/src/components/StepNumber'; ## 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. +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/design-decisions/decide-on-vanity-branded-domain/) and [Decide on Service Discovery Domain](/layers/network/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. diff --git a/docs/layers/network-and-dns/network-and-dns.mdx b/docs/layers/network/network.mdx similarity index 94% rename from docs/layers/network-and-dns/network-and-dns.mdx rename to docs/layers/network/network.mdx index 0157cc7c0..489185f67 100644 --- a/docs/layers/network-and-dns/network-and-dns.mdx +++ b/docs/layers/network/network.mdx @@ -2,12 +2,15 @@ title: "Network and DNS" sidebar_label: "Network and DNS" sidebar_class_name: hidden +description: "Build a robust, scalable AWS Network and DNS architectures" --- import ReactPlayer from "react-player"; import Intro from '@site/src/components/Intro'; import KeyPoints from '@site/src/components/KeyPoints'; -# Network and DNS + + Learn Cloud Posse’s approach to designing robust and scalable Network and DNS architectures on AWS. We discuss our solutions to common challenges in network design, focusing on maintainability, security, and scalability. We cover essential topics such as account isolation, connecting accounts using Transit Gateway, deploying AWS Client VPN for network access, and differentiating between service and vanity domains. + 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/). @@ -124,7 +127,11 @@ On the other hand vanity domains are entirely up to the requirements of the busi thousand of domains to be associated with an application, and these domains may not follow any naming pattern or hierarchy. These are the domains used by the customer. -[The Difference between Vanity Domains and Service Discovery Domains](/reference-architecture/reference/learning-resources/#the-difference-between-vanity-domains-and-service-discovery-domains) + ### Other common DNS questions @@ -153,8 +160,7 @@ In order to add a new network region: `stacks/orgs/{{ namespace }}/{{ tenant }}/{{ stage }}/{{ region }}/network.yaml`. For example for networking, define a new VPC, connect Transit Gateway, and define Client VPN routes to the new regions. -For more, see -[How to Define Stacks for Multiple Regions](/reference-architecture/how-to-guides/tutorials/how-to-define-stacks-for-multiple-regions/) +For more, see [How to Define Stacks for Multiple Regions](/reference-architecture/how-to-guides/tutorials/how-to-define-stacks-for-multiple-regions/) ### How can we connect a legacy AWS account to our network? diff --git a/docs/layers/network-and-dns/tutorials/tutorials.mdx b/docs/layers/network/tutorials/tutorials.mdx similarity index 100% rename from docs/layers/network-and-dns/tutorials/tutorials.mdx rename to docs/layers/network/tutorials/tutorials.mdx diff --git a/docs/layers/application-cicd/design-decisions/decide-how-to-distribute-docker-images.mdx b/docs/layers/software-delivery/design-decisions/decide-how-to-distribute-docker-images.mdx similarity index 100% rename from docs/layers/application-cicd/design-decisions/decide-how-to-distribute-docker-images.mdx rename to docs/layers/software-delivery/design-decisions/decide-how-to-distribute-docker-images.mdx diff --git a/docs/layers/application-cicd/design-decisions/decide-on-argocd-architecture.mdx b/docs/layers/software-delivery/design-decisions/decide-on-argocd-architecture.mdx similarity index 99% rename from docs/layers/application-cicd/design-decisions/decide-on-argocd-architecture.mdx rename to docs/layers/software-delivery/design-decisions/decide-on-argocd-architecture.mdx index 88b3762cc..746d7f59f 100644 --- a/docs/layers/application-cicd/design-decisions/decide-on-argocd-architecture.mdx +++ b/docs/layers/software-delivery/design-decisions/decide-on-argocd-architecture.mdx @@ -56,7 +56,7 @@ While the Operator Pattern is _ideal_ in theory, the reality is less than ideal: Here are some of the most common deployment patterns we see, and some ways in which those could be addressed: -
+
1. **Deploy a** **generic application** **to Kubernetes** @@ -228,7 +228,7 @@ Required status checks to merge the pull requests: 2. Workflows in the `acme/argo cd-deploy-prd/.github/workflows/` will do linting on the kubernetes manifests (where manifests exists) -
+
Pull Requests will be predominantly machine generated by GitHub Actions. However, anyone can open a Pull Request (e.g for hotfixes), and with appropriate approvals get them deployed. diff --git a/docs/layers/application-cicd/design-decisions/decide-on-argocd-deployment-repo-architecture.mdx b/docs/layers/software-delivery/design-decisions/decide-on-argocd-deployment-repo-architecture.mdx similarity index 100% rename from docs/layers/application-cicd/design-decisions/decide-on-argocd-deployment-repo-architecture.mdx rename to docs/layers/software-delivery/design-decisions/decide-on-argocd-deployment-repo-architecture.mdx diff --git a/docs/layers/application-cicd/design-decisions/decide-on-branching-strategy.mdx b/docs/layers/software-delivery/design-decisions/decide-on-branching-strategy.mdx similarity index 100% rename from docs/layers/application-cicd/design-decisions/decide-on-branching-strategy.mdx rename to docs/layers/software-delivery/design-decisions/decide-on-branching-strategy.mdx diff --git a/docs/layers/application-cicd/design-decisions/decide-on-customer-apps-for-migration.mdx b/docs/layers/software-delivery/design-decisions/decide-on-customer-apps-for-migration.mdx similarity index 100% rename from docs/layers/application-cicd/design-decisions/decide-on-customer-apps-for-migration.mdx rename to docs/layers/software-delivery/design-decisions/decide-on-customer-apps-for-migration.mdx diff --git a/docs/layers/application-cicd/design-decisions/decide-on-database-seeding-strategy-for-ephemeral-preview-enviro.mdx b/docs/layers/software-delivery/design-decisions/decide-on-database-seeding-strategy-for-ephemeral-preview-enviro.mdx similarity index 100% rename from docs/layers/application-cicd/design-decisions/decide-on-database-seeding-strategy-for-ephemeral-preview-enviro.mdx rename to docs/layers/software-delivery/design-decisions/decide-on-database-seeding-strategy-for-ephemeral-preview-enviro.mdx diff --git a/docs/layers/application-cicd/design-decisions/decide-on-github-actions-workflow-organization-strategy.mdx b/docs/layers/software-delivery/design-decisions/decide-on-github-actions-workflow-organization-strategy.mdx similarity index 100% rename from docs/layers/application-cicd/design-decisions/decide-on-github-actions-workflow-organization-strategy.mdx rename to docs/layers/software-delivery/design-decisions/decide-on-github-actions-workflow-organization-strategy.mdx diff --git a/docs/layers/application-cicd/design-decisions/decide-on-hot-fix-or-rollback-strategy.mdx b/docs/layers/software-delivery/design-decisions/decide-on-hot-fix-or-rollback-strategy.mdx similarity index 100% rename from docs/layers/application-cicd/design-decisions/decide-on-hot-fix-or-rollback-strategy.mdx rename to docs/layers/software-delivery/design-decisions/decide-on-hot-fix-or-rollback-strategy.mdx diff --git a/docs/layers/application-cicd/design-decisions/decide-on-how-ecs-apps-are-deployed.mdx b/docs/layers/software-delivery/design-decisions/decide-on-how-ecs-apps-are-deployed.mdx similarity index 100% rename from docs/layers/application-cicd/design-decisions/decide-on-how-ecs-apps-are-deployed.mdx rename to docs/layers/software-delivery/design-decisions/decide-on-how-ecs-apps-are-deployed.mdx diff --git a/docs/layers/application-cicd/design-decisions/decide-on-kubernetes-application-artifacts.mdx b/docs/layers/software-delivery/design-decisions/decide-on-kubernetes-application-artifacts.mdx similarity index 100% rename from docs/layers/application-cicd/design-decisions/decide-on-kubernetes-application-artifacts.mdx rename to docs/layers/software-delivery/design-decisions/decide-on-kubernetes-application-artifacts.mdx diff --git a/docs/layers/application-cicd/design-decisions/decide-on-pipeline-strategy.mdx b/docs/layers/software-delivery/design-decisions/decide-on-pipeline-strategy.mdx similarity index 99% rename from docs/layers/application-cicd/design-decisions/decide-on-pipeline-strategy.mdx rename to docs/layers/software-delivery/design-decisions/decide-on-pipeline-strategy.mdx index c52b75c6e..fc5fa4857 100644 --- a/docs/layers/application-cicd/design-decisions/decide-on-pipeline-strategy.mdx +++ b/docs/layers/software-delivery/design-decisions/decide-on-pipeline-strategy.mdx @@ -227,9 +227,9 @@ Links to any supporting documentation or pages, if any ## **Security Risk Assessment** -
+
-
+
The release engineering system consists of two main components - _Github Action Cloud_ (a.k. _GHA_) and _Github Action Runners_ (a.k. _GHA-Runners_). @@ -314,11 +314,11 @@ To get this PAT with minimal required permissions follows these steps: 2. Added the user to the `Private Actions` repository with 'read-only' permissions (`https://github.com/{organization}/{repository}/settings/access`) -3.
+3.
Generate a PAT for the technical user with that level of permissions [https://github.com/settings/tokens/new](https://github.com/settings/tokens/new) -
+
4. Save the PAT as organization secret with name `GITHUB_PRIVATE_ACTIONS_PAT` (`https://github.com/organizations/{organization}/settings/secrets/actions`) diff --git a/docs/layers/application-cicd/design-decisions/decide-on-release-engineering-strategy.mdx b/docs/layers/software-delivery/design-decisions/decide-on-release-engineering-strategy.mdx similarity index 95% rename from docs/layers/application-cicd/design-decisions/decide-on-release-engineering-strategy.mdx rename to docs/layers/software-delivery/design-decisions/decide-on-release-engineering-strategy.mdx index af7299305..ff1373b2f 100644 --- a/docs/layers/application-cicd/design-decisions/decide-on-release-engineering-strategy.mdx +++ b/docs/layers/software-delivery/design-decisions/decide-on-release-engineering-strategy.mdx @@ -24,7 +24,7 @@ The Gitflow branching model consists of the following 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. -
+
### Trunk-Based Strategy @@ -35,4 +35,4 @@ The trunk-based branching model consists of the following branches: - **Main (_Trunk_) Branch:** Represents the latest development code and serves as a parent branch for feature branches. - **Feature Branches:** Created from the _Trunk_ branch, feature branches are used to develop new features or functionality. Once the feature is complete, it is merged back into the develop branch. -
+
diff --git a/docs/layers/application-cicd/design-decisions/decide-on-release-promotion-strategy.mdx b/docs/layers/software-delivery/design-decisions/decide-on-release-promotion-strategy.mdx similarity index 100% rename from docs/layers/application-cicd/design-decisions/decide-on-release-promotion-strategy.mdx rename to docs/layers/software-delivery/design-decisions/decide-on-release-promotion-strategy.mdx diff --git a/docs/layers/application-cicd/design-decisions/decide-on-repositories-strategy.mdx b/docs/layers/software-delivery/design-decisions/decide-on-repositories-strategy.mdx similarity index 100% rename from docs/layers/application-cicd/design-decisions/decide-on-repositories-strategy.mdx rename to docs/layers/software-delivery/design-decisions/decide-on-repositories-strategy.mdx diff --git a/docs/layers/application-cicd/design-decisions/decide-on-seeding-strategy-for-staging-environments.mdx b/docs/layers/software-delivery/design-decisions/decide-on-seeding-strategy-for-staging-environments.mdx similarity index 100% rename from docs/layers/application-cicd/design-decisions/decide-on-seeding-strategy-for-staging-environments.mdx rename to docs/layers/software-delivery/design-decisions/decide-on-seeding-strategy-for-staging-environments.mdx diff --git a/docs/layers/application-cicd/design-decisions/decide-on-self-hosted-github-runner-strategy.mdx b/docs/layers/software-delivery/design-decisions/decide-on-self-hosted-github-runner-strategy.mdx similarity index 100% rename from docs/layers/application-cicd/design-decisions/decide-on-self-hosted-github-runner-strategy.mdx rename to docs/layers/software-delivery/design-decisions/decide-on-self-hosted-github-runner-strategy.mdx diff --git a/docs/layers/application-cicd/design-decisions/decide-on-strategy-for-continuous-integration.mdx b/docs/layers/software-delivery/design-decisions/decide-on-strategy-for-continuous-integration.mdx similarity index 100% rename from docs/layers/application-cicd/design-decisions/decide-on-strategy-for-continuous-integration.mdx rename to docs/layers/software-delivery/design-decisions/decide-on-strategy-for-continuous-integration.mdx diff --git a/docs/layers/application-cicd/design-decisions/decide-on-strategy-for-developer-environments.mdx b/docs/layers/software-delivery/design-decisions/decide-on-strategy-for-developer-environments.mdx similarity index 100% rename from docs/layers/application-cicd/design-decisions/decide-on-strategy-for-developer-environments.mdx rename to docs/layers/software-delivery/design-decisions/decide-on-strategy-for-developer-environments.mdx diff --git a/docs/layers/application-cicd/design-decisions/decide-on-strategy-for-managing-and-orchestrating-secrets.mdx b/docs/layers/software-delivery/design-decisions/decide-on-strategy-for-managing-and-orchestrating-secrets.mdx similarity index 100% rename from docs/layers/application-cicd/design-decisions/decide-on-strategy-for-managing-and-orchestrating-secrets.mdx rename to docs/layers/software-delivery/design-decisions/decide-on-strategy-for-managing-and-orchestrating-secrets.mdx diff --git a/docs/layers/application-cicd/design-decisions/decide-on-strategy-for-preview-environments-e-g-review-apps.mdx b/docs/layers/software-delivery/design-decisions/decide-on-strategy-for-preview-environments-e-g-review-apps.mdx similarity index 99% rename from docs/layers/application-cicd/design-decisions/decide-on-strategy-for-preview-environments-e-g-review-apps.mdx rename to docs/layers/software-delivery/design-decisions/decide-on-strategy-for-preview-environments-e-g-review-apps.mdx index 9ffafdde6..a8f97f645 100644 --- a/docs/layers/application-cicd/design-decisions/decide-on-strategy-for-preview-environments-e-g-review-apps.mdx +++ b/docs/layers/software-delivery/design-decisions/decide-on-strategy-for-preview-environments-e-g-review-apps.mdx @@ -97,7 +97,7 @@ For some additional context on ArgoCD [Decide on ArgoCD Architecture](/reference - URLs will be posted to GitHub Status API to that environments are directly reachable from PRs -
+
- Do we need to secure these environments? We recommend just locking down the ALB to internal traffic and using VPN diff --git a/docs/layers/application-cicd/design-decisions/decide-on-terraform-configuration-pattern-for-application-reposi.mdx b/docs/layers/software-delivery/design-decisions/decide-on-terraform-configuration-pattern-for-application-reposi.mdx similarity index 100% rename from docs/layers/application-cicd/design-decisions/decide-on-terraform-configuration-pattern-for-application-reposi.mdx rename to docs/layers/software-delivery/design-decisions/decide-on-terraform-configuration-pattern-for-application-reposi.mdx diff --git a/docs/layers/application-cicd/design-decisions/design-decisions.mdx b/docs/layers/software-delivery/design-decisions/design-decisions.mdx similarity index 100% rename from docs/layers/application-cicd/design-decisions/design-decisions.mdx rename to docs/layers/software-delivery/design-decisions/design-decisions.mdx diff --git a/docs/layers/application-cicd/ecs-ecspresso/ecs-ecspresso.mdx b/docs/layers/software-delivery/ecs-ecspresso/ecs-ecspresso.mdx similarity index 100% rename from docs/layers/application-cicd/ecs-ecspresso/ecs-ecspresso.mdx rename to docs/layers/software-delivery/ecs-ecspresso/ecs-ecspresso.mdx diff --git a/docs/layers/application-cicd/ecs-ecspresso/setup.mdx b/docs/layers/software-delivery/ecs-ecspresso/setup.mdx similarity index 100% rename from docs/layers/application-cicd/ecs-ecspresso/setup.mdx rename to docs/layers/software-delivery/ecs-ecspresso/setup.mdx diff --git a/docs/layers/application-cicd/eks-argocd/eks-argocd.mdx b/docs/layers/software-delivery/eks-argocd/eks-argocd.mdx similarity index 99% rename from docs/layers/application-cicd/eks-argocd/eks-argocd.mdx rename to docs/layers/software-delivery/eks-argocd/eks-argocd.mdx index 556b09cd0..ae5c3cbb7 100644 --- a/docs/layers/application-cicd/eks-argocd/eks-argocd.mdx +++ b/docs/layers/software-delivery/eks-argocd/eks-argocd.mdx @@ -375,7 +375,7 @@ runs: ## References -- [ArgoCD Setup](/layers/application-cicd/eks-argocd/setup) +- [ArgoCD Setup](/layers/software-delivery/eks-argocd/setup) - [Foundation Release Engineering](/reference-architecture/fundamentals/design-decisions/foundational-release-engineering/) - [Decide on Pipeline Strategy](/reference-architecture/fundamentals/design-decisions/foundational-release-engineering/decide-on-pipeline-strategy/) diff --git a/docs/layers/application-cicd/eks-argocd/setup.mdx b/docs/layers/software-delivery/eks-argocd/setup.mdx similarity index 100% rename from docs/layers/application-cicd/eks-argocd/setup.mdx rename to docs/layers/software-delivery/eks-argocd/setup.mdx diff --git a/docs/layers/application-cicd/eks-argocd/tutorials/github-commit-notifications.mdx b/docs/layers/software-delivery/eks-argocd/tutorials/github-commit-notifications.mdx similarity index 100% rename from docs/layers/application-cicd/eks-argocd/tutorials/github-commit-notifications.mdx rename to docs/layers/software-delivery/eks-argocd/tutorials/github-commit-notifications.mdx diff --git a/docs/layers/application-cicd/eks-argocd/tutorials/identity-center-apps.mdx b/docs/layers/software-delivery/eks-argocd/tutorials/identity-center-apps.mdx similarity index 100% rename from docs/layers/application-cicd/eks-argocd/tutorials/identity-center-apps.mdx rename to docs/layers/software-delivery/eks-argocd/tutorials/identity-center-apps.mdx diff --git a/docs/layers/application-cicd/eks-argocd/tutorials/pats.mdx b/docs/layers/software-delivery/eks-argocd/tutorials/pats.mdx similarity index 100% rename from docs/layers/application-cicd/eks-argocd/tutorials/pats.mdx rename to docs/layers/software-delivery/eks-argocd/tutorials/pats.mdx diff --git a/docs/layers/application-cicd/eks-argocd/tutorials/tutorials.mdx b/docs/layers/software-delivery/eks-argocd/tutorials/tutorials.mdx similarity index 100% rename from docs/layers/application-cicd/eks-argocd/tutorials/tutorials.mdx rename to docs/layers/software-delivery/eks-argocd/tutorials/tutorials.mdx diff --git a/docs/layers/application-cicd/lambda/lambda.mdx b/docs/layers/software-delivery/lambda/lambda.mdx similarity index 100% rename from docs/layers/application-cicd/lambda/lambda.mdx rename to docs/layers/software-delivery/lambda/lambda.mdx diff --git a/docs/layers/application-cicd/application-cicd.mdx b/docs/layers/software-delivery/software-delivery.mdx similarity index 100% rename from docs/layers/application-cicd/application-cicd.mdx rename to docs/layers/software-delivery/software-delivery.mdx diff --git a/docs/layers/application-cicd/tutorials/_category_.json b/docs/layers/software-delivery/tutorials/_category_.json similarity index 100% rename from docs/layers/application-cicd/tutorials/_category_.json rename to docs/layers/software-delivery/tutorials/_category_.json diff --git a/docs/layers/application-cicd/tutorials/how-to-create-a-migration-checklist.mdx b/docs/layers/software-delivery/tutorials/how-to-create-a-migration-checklist.mdx similarity index 100% rename from docs/layers/application-cicd/tutorials/how-to-create-a-migration-checklist.mdx rename to docs/layers/software-delivery/tutorials/how-to-create-a-migration-checklist.mdx diff --git a/docs/layers/spacelift/design-decisions/decide-on-how-spacelift-will-use-external-private-modules.mdx b/docs/layers/spacelift/design-decisions/decide-on-how-spacelift-will-use-external-private-modules.mdx index abaf9db56..325337ac0 100644 --- a/docs/layers/spacelift/design-decisions/decide-on-how-spacelift-will-use-external-private-modules.mdx +++ b/docs/layers/spacelift/design-decisions/decide-on-how-spacelift-will-use-external-private-modules.mdx @@ -1,6 +1,6 @@ --- title: "Decide on how Spacelift will use external private modules" -sidebar_label: "Spacelift with external private modules" +sidebar_label: "External Private Modules" sidebar_position: 100 refarch_id: REFARCH-535 description: How to securely access to private Terraform modules in Spacelift diff --git a/docs/layers/spacelift/design-decisions/decide-on-spacelift-administrative-stack-auto-deployment.mdx b/docs/layers/spacelift/design-decisions/decide-on-spacelift-administrative-stack-auto-deployment.mdx index df1f89e3a..081670b5f 100644 --- a/docs/layers/spacelift/design-decisions/decide-on-spacelift-administrative-stack-auto-deployment.mdx +++ b/docs/layers/spacelift/design-decisions/decide-on-spacelift-administrative-stack-auto-deployment.mdx @@ -1,6 +1,6 @@ --- title: "Decide on Spacelift Administrative Stack Auto-deployment" -sidebar_label: "Spacelift Administrative Stack Auto-deployment" +sidebar_label: "Administrative Stack Auto-deployment" sidebar_position: 100 refarch_id: REFARCH-410 description: Balance auto-deployment with manual confirmation @@ -28,7 +28,7 @@ This admin stack is manually created in Spacelift (it’s how it knows about you When making changes or adding a new component to a stack configuration in Spacelift, those changes must be applied first by the administrative stack before Spacelift can do anything with it (e.g. show a terraform plan of this stack). -
+
## Considered Options diff --git a/docs/layers/spacelift/design-decisions/decide-on-spacelift-worker-pool-architecture.mdx b/docs/layers/spacelift/design-decisions/decide-on-spacelift-worker-pool-architecture.mdx index 9f1131ba2..c78153bb4 100644 --- a/docs/layers/spacelift/design-decisions/decide-on-spacelift-worker-pool-architecture.mdx +++ b/docs/layers/spacelift/design-decisions/decide-on-spacelift-worker-pool-architecture.mdx @@ -1,7 +1,8 @@ --- title: "Decide on Spacelift Worker Pool Architecture" -sidebar_label: "Spacelift Worker Pool Architecture" +sidebar_label: "Worker Pool Architecture" sidebar_position: 100 +sidebar_class_name: compact refarch_id: REFARCH-475 description: Scope Spacelift Workers for secure automation --- @@ -9,7 +10,7 @@ import Intro from '@site/src/components/Intro'; import KeyPoints from '@site/src/components/KeyPoints'; -Spacelift Workers are deployed in VPCs with scoped IAM permissions to ensure robust automation capabilities while minimizing security risks. By default, we avoid automating certain core system accounts, but this can be adjusted as needed. Review these considerations to determine the best approach for your organization. + Spacelift Workers are deployed in VPCs with scoped IAM permissions to ensure robust automation capabilities while minimizing security risks. By default, we avoid automating certain core system accounts, but this can be adjusted as needed. Review these considerations to determine the best approach for your organization. ## Problem diff --git a/docs/layers/spacelift/faq.mdx b/docs/layers/spacelift/faq.mdx new file mode 100644 index 000000000..f44545500 --- /dev/null +++ b/docs/layers/spacelift/faq.mdx @@ -0,0 +1,102 @@ +--- +title: Spacelift FAQ +sidebar_label: FAQ +--- +import Note from '@site/src/components/Note'; + +## 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. + +### Can we still use Spacelift despite Terraform licensing changes? + +:::important + +This is not a technical question. + +This is a matter of legal interpretation of the [HashiCorp BSL license (aka BUSL)](https://www.hashicorp.com/bsl) (and [binding FAQ](https://www.hashicorp.com/license-faq)), and we are not lawyers. We recommend consulting with your legal team to understand the implications of using Spacelift with Terraform. + +**Cloud Posse cannot provide legal advice on this matter.** + +::: + +It depends. +- You can use Spacelift with MPL licensed Terraform (e.g. versions including 1.5.7 and earlier) +- You can use Spacelift with all versions OpenTofu + +But you cannot use Spacelift with BSL licensed versions of Terraform. + + + +## 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. + +- This is deployed to private subnets and its IPs are allowlisted in security groups so it can manage EKS clusters, helm charts, aurora/rds cluster resources (databases, users), and other private resources. + +- **“Webhook-based audit logging”** which is used to send notifications from Spacelift to external systems like Datadog or Opsgenie. These notifications include audit login, the status of each stack, each run, etc., which is useful for compliance and stacks’ status visibility. + +- For a full breakdown of the differences, check out the [spacelift pricing](https://spacelift.io/pricing). + +This is required in order to provision any database users or schemas, manage EKS clusters on a private subnet, or in general manage any resources residing in private subnets in a VPC. The other benefit with an Enterprise Agreement is that it will fix your costs, even if you burst your Spacelift Workers. If you were on a Metered (aka “pay-as-you-go plan”), you will be charged for those bursts and that will add up to thousands per month. + +The Spacelift Enterprise 30 day trial (with an option to extend it) should be signed up to take advantage of these features. + +:::tip Referrals + +Cloud Posse has a partnership with Spacelift that can save you cost! Please reach out to Cloud Posse for a referral. + +::: + +## Who should you contact regarding Spacelift contracts and pricing? + +Reach out to Pawel Hawtry [pawelh@spacelift.io](mailto:pawelh@spacelift.io) and mention you are working with Cloud Posse. Alternatively, we’re happy to facilitate an introduction directly. + +## What if Spacelift is too expensive? + +First, make sure you understand why we chose to [Use Spacelift for GitOps with Terraform](/reference-architecture/reference/adrs/use-spacelift-for-gitops-with-terraform). + +Spacelift wants to earn your business and they only want happy customers. Work with them to reach a middle ground that makes everyone happy. + + + Alternatively, you can use our [free GitHub Actions for Atmos with Terraform](/layer/gitops). This is a great way to get started with GitOps and Terraform without any additional cost. + + +## Why can’t we start with an entry-level plan? + +(See [How to Sign Up for Spacelift](/reference-architecture/how-to-guides/integrations/spacelift) ) + +- Only enterprise plans support self-hosted workers which are required in order to manage any infrastructure provisioned inside of VPCs (E.g. Databases, non-public EKS clusters, terraform provisioners, etc). Additionally, using EC2 Instance Profiles we’re able to grant the precise roles we want to give Spacelift without any hardcoded credentials. + +- Only enterprise plans support fixed costs. Cloud is metered billing, which means if we scale up our workers temporarily to flush out a large queue of plans, they will charge for the additional workers on a monthly rate. They do not have the ability to disable this and it happens automatically. Several customers have accidentally encountered _Bill Shock_ as a result of this (we got it all sorted out for them in the end!) + +
+ +
+ +## Is Spacelift SOC2 Compliant? + +Yes, Spacelift has SOC2 Type II certification performed by an independent external auditor who confirms the effectiveness of internal controls in terms of Spacelift security, availability, processing integrity, confidentiality, and privacy of customer data. + +[https://spacelift.io/security](https://spacelift.io/security) + +Spacelift’s SOC2 Type 2 report and the pentest report from April 2021 is attached below. If anyone ever has any security-related questions, they can reach out to [@Wojciech Syrkiewicz-Trepiak](mailto:wojciechs@spacelift.io), Spacelift’s security engineer. Spacelift also has D&O and Cyber & Tech Insurance in place. + +Please reach out to Spacelift to request a report. + +## How many runners will we need? + + + it really varies based on your usage patterns and size of your infrastructure, but start with a minimum of 2-3. + + +Since Spacelift permits you to scale up for short periods of time without metering, we recommend starting with a commitment of 2-3 runners online at any time. We’ll configure your workers to autoscale up as necessary. + +### Can we consolidate multiple Spacelift Organizations under one bill? + +Yes! Spacelift can consolidate the billing. For example, if you have multiple GitHub Organizations, each one associated with a different Spacelift Organization, Spacelift can consolidate the invoice. + +### Where do we sign up? + +How you sign up depends on if you’re using GitHub or GitLab. diff --git a/docs/layers/spacelift/03-spacelift.mdx b/docs/layers/spacelift/setup.mdx similarity index 79% rename from docs/layers/spacelift/03-spacelift.mdx rename to docs/layers/spacelift/setup.mdx index 1c6a23bba..a01ece6fc 100644 --- a/docs/layers/spacelift/03-spacelift.mdx +++ b/docs/layers/spacelift/setup.mdx @@ -1,10 +1,12 @@ --- -title: Spacelift -sidebar_label: Spacelift +title: Setup +sidebar_label: Setup +sidebar_position: 1 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'; +import Steps from '@site/src/components/Steps'; ## Quick Start @@ -25,10 +27,9 @@ import KeyPoints from '@site/src/components/KeyPoints'; ### Sign Up for Spacelift -First, sign up for Spacelift. Follow these steps, and see -[the detailed documentation](https://docs.cloudposse.com/reference-architecture/how-to-guides/integrations/spacelift/) -for additional information. +First, sign up for Spacelift. Follow these steps, and see [the detailed documentation](https://docs.cloudposse.com/reference-architecture/how-to-guides/integrations/spacelift/) for additional information. + 1. Sign up [Get started with Spacelift](https://spacelift.io/free-trial) 1. Install Spacelift GitHub app into the customer GitHub organization 1. Once the app is installed into the customer GitHub organization, the GitHub organization admin will receive an @@ -49,56 +50,56 @@ for additional information. team names. 1. 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. -# Note 2: Enabling SSO requires that all users have an IdP (G Suite) account, so we'll just use -# GitHub authentication in the meantime while working with external collaborators. -# Map session input data to human friendly variables to use in policy evaluation -username := input.session.login -member_of := input.session.teams - -github_org := input.session.member - -# Define GitHub usernames of non-github_org org external collaborators with admin vs. user access -admin_collaborators := {} # case sensitive GitHub handles of additional admin collaborators - -user_collaborators := { "acme" } # case sensitive name of the github org - -# Grant admin access to github_org org members in the non cloud posse case-sensitive team -# Do not use the slug here, use the name shown in github.com/org/teams -admin { - github_org - member_of[_] == "YOUR-CASE-SENSITIVE-TEAM-NAME" -} - -# Grant admin access to github_org org members in the Cloud Posse group -# Do not use the slug here, use the name shown in github.com/org/teams -admin { - github_org - member_of[_] == "CLOUDPOSSE-CASE-SENSITIVE-TEAM-NAME" -} - -# Grant admin access to non-github_org org accounts in the admin_collaborators set -admin { - # not github_org - admin_collaborators[username] -} - -# Grant user access to accounts in the user_collaborators set -allow { - # not github_org - user_collaborators[username] -} - -# Deny access to any non-github_org org accounts who aren't defined in external collaborators sets -deny { - not github_org - not user_collaborators[username] - not admin_collaborators[username] -} -``` + ```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. + # Note 2: Enabling SSO requires that all users have an IdP (G Suite) account, so we'll just use + # GitHub authentication in the meantime while working with external collaborators. + # Map session input data to human friendly variables to use in policy evaluation + username := input.session.login + member_of := input.session.teams + + github_org := input.session.member + + # Define GitHub usernames of non-github_org org external collaborators with admin vs. user access + admin_collaborators := {} # case sensitive GitHub handles of additional admin collaborators + + user_collaborators := { "acme" } # case sensitive name of the github org + + # Grant admin access to github_org org members in the non cloud posse case-sensitive team + # Do not use the slug here, use the name shown in github.com/org/teams + admin { + github_org + member_of[_] == "YOUR-CASE-SENSITIVE-TEAM-NAME" + } + + # Grant admin access to github_org org members in the Cloud Posse group + # Do not use the slug here, use the name shown in github.com/org/teams + admin { + github_org + member_of[_] == "CLOUDPOSSE-CASE-SENSITIVE-TEAM-NAME" + } + + # Grant admin access to non-github_org org accounts in the admin_collaborators set + admin { + # not github_org + admin_collaborators[username] + } + + # Grant user access to accounts in the user_collaborators set + allow { + # not github_org + user_collaborators[username] + } + + # Deny access to any non-github_org org accounts who aren't defined in external collaborators sets + deny { + not github_org + not user_collaborators[username] + not admin_collaborators[username] + } + ``` 5. Verify Cloud Posse users have administrative access @@ -114,6 +115,8 @@ deny { `token`. 1. Also share the 26 character string next to the name of the key which gives us the `key_id`. + + ### Upload the API Key In order for the `spacelift/worker-pool` component to connect to the given Spacelift account, we need to add the @@ -138,6 +141,7 @@ atmos workflow init -f spacelift ## How To + ### Vendor Spacelift adds three components, `spacelift/worker-pool`, `spacelift/admin-stack`, and `spacelift/spaces`. Vendor these @@ -250,6 +254,9 @@ atmos workflow deploy/admin-stack -f spacelift Note that this is the only manually operation you need to perform in `geodesic` using `atmos` to create the initial admin stack. All other infrastructure stacks will be created in Spacelift by this admin stack. + + + # Related Topics ## Pull Request Workflow @@ -260,7 +267,7 @@ admin stack. All other infrastructure stacks will be created in Spacelift by thi 4. View the successful Spacelift checks in the pull request 5. Merge the pull request and check the Spacelift job -## spacectl +## How to use `spacectl`? See docs https://github.com/spacelift-io/spacectl diff --git a/docs/layers/spacelift/spacelift.mdx b/docs/layers/spacelift/spacelift.mdx index fee70f3bc..300dad96e 100644 --- a/docs/layers/spacelift/spacelift.mdx +++ b/docs/layers/spacelift/spacelift.mdx @@ -1,12 +1,402 @@ --- title: "Spacelift" +sidebar_label: "Spacelift" sidebar_class_name: hidden tags: - - spacelift + - spacelift --- import Intro from '@site/src/components/Intro'; import KeyPoints from '@site/src/components/KeyPoints'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import PartialSpaceliftRootStack from '@site/examples/snippets/stacks/orgs/acme/spacelift.yaml'; +import PartialSpaceliftTenantStack from '@site/examples/snippets/stacks/orgs/acme/plat/spacelift.yaml' +import CodeBlock from '@theme/CodeBlock'; -# TODO +GitOps is a cloud-native continuous deployment methodology that uses Git as +the single source of truth for declarative infrastructure and applications. +Changes to infrastructure or applications are made through Git commits, and +the actual state is automatically adjusted to match the desired state +expressed in the Git repository. This approach provides an audit trail for +changes, simplifies rollback, and enhances collaboration and visibility across teams. -removed this page because it errors out without addition work. copy and fix this page from refarch-scaffold fundamentals +## The Problem + +Terraform itself focuses on managing the state of infrastructure. It does not +provide a way of indexing, CI/CD, or collaborating on state. In fact, Terraform +really wants to just be a CLI tool that you run locally. The problem is that +with all our infrastructure spanning hundreds of stacks we cannot easily see +the state of our infrastructure. + +Moreover, there could be many different teams of engineers who are responsible +for different parts of the infrastructure. How do we enable them to collaborate +on the same infrastructure? You will likely need to set up permissions and roles +for that, and to future-proof those you'll need someone to govern those roles as +teams change and infrastructure evolves. + +Lastly we want a way to automate our infrastructure as code. It does little good +if code changes are not immediately reflected in the infrastructure. If several +code changes happen before infrastructure updates, you could be left with difficult +to resolve conflicts. + +## Our Solution + +Spacelift is a hosted service that indexes the state of your infrastructure +and provides a way to collaborate on it. It also provides a way to automate +gitops and will continuously monitor your infrastructure for changes at a +schedule you can configure. + +Spacelift breaks down access and gitops with policies that govern what can trigger +changes and who can either read or update infrastructure. The policies +use rego, an industry standard language for policy as code. + +Infrastructure is indexed by resource, label, status, or other facets. Dependencies +can also be created between stacks, so that changes in one stack will lock other stacks +until changes are done and then ensure that the dependent stacks are updated. + +Overall, Spacelift is a comprehensive way to make sure that your infrastructure is +easy to automate and manage. Because our solution keeps the state of your infrastructure +in S3, you also are not locked in and can use other tools to manage your infrastructure +in case either GitHub or Spacelift go down. + +## Spacelift Stack Lifecycle + +Spacelift has its own notion of a "Stack", which is a workspace for Terraform +with a slug identitifier. Stacks have a lifecycle that is triggered by events +like a git commit or a drift schedule. The lifecycle is as follows: + +```mermaid +--- +title: Basic Spacelift Stack Lifecycle +--- +stateDiagram-v2 + direction LR + [*] --> Triggered : Git Commit + Triggered --> Run + state Run { + direction LR + state if_changes <> + + [*] --> Planning + Planning --> if_changes + if_changes --> Confirm: if changes + if_changes --> Applied: if no changes + Confirm --> Applied + Applied --> [*] + } +``` + +Runs are what Spacelift uses to scope changes to a given event like a commit SHA. +Within the run, Spacelift uses a plan policy to dictate what changes require confirmation +and what changes can be applied automatically. After a run is complete, Spacelift +will evaluate other trigger policies and dependencies to determine if other stacks +need to be updated. + +## Implementation + +We have three components that implement Spacelift. The first is the `spacelift/admin-stack` component +which creates admin stacks in Spacelift. The second is the `spacelift/spaces` component +which creates Spacelift Spaces and manages policies in those Spaces. The third is the +`spacelift/worker-pool` component which creates a worker pool for Spacelift to use self-hosted +workers. + +### Global Configuration + +In order to apply common Spacelift configuration to all stacks, we need to set a few global Spacelift settings. +The `pr-comment-triggered` label will be required to trigger stacks with GitHub comments but is not required +otherwise. More on triggering Spacelift stacks to follow. + +Add the following to `stacks/orgs/NAMESPACE/_defaults.yaml`: + +```yaml + settings: + spacelift: + workspace_enabled: true # enable spacelift by default + before_apply: + - spacelift-configure-paths + before_init: + - spacelift-configure-paths + - spacelift-write-vars + - spacelift-tf-workspace + before_plan: + - spacelift-configure-paths + labels: + - pr-comment-triggered +``` + +Furthermore, specify additional tenant-specific Space configuration for both `core` and `plat` tenants. + +For example, for `core` add the following to `stacks/orgs/NAMESPACE/core/_defaults.yaml`: + +```yaml +terraform: + settings: + spacelift: + space_name: core +``` + +And for `plat` add the following to `stacks/orgs/NAMESPACE/plat/_defaults.yaml`: + +```yaml +terraform: + settings: + spacelift: + space_name: plat +``` + + +### Admin Stacks + +Spacelift allows some stacks to manage other stacks (or even itself). This is useful +for making new component instances show up in the Spacelift UI. The `spacelift/admin-stack` component +takes the `atmos.yaml` and uses it to derive what stacks need to be created in Spacelift. +By updating your atmos stacks, you'll see the changes reflected in Spacelift. + +Not all stacks are managed by Spacelift. If a management stack sees that a stack +does not have `workspace_enabled` set to true, it will be ignored by the admin stack. + +
+Managed vs. Unmanaged Components + + + + + ```yaml + components: + terraform: + vpc: + settings: + spacelift: + workspace_enabled: true + vars: + enabled: true + ``` + + + + + ```yaml + components: + terraform: + aws-sso: + settings: + spacelift: + workspace_enabled: false + vars: + enabled: true + ``` + + + + +
+ + +### Spaces + +The `spacelift/spaces` component maintains Spacelift spaces and configures all policies in those given Spaces. Policy labels can allow policies to be automatically enforced on a given group of stacks. A Spacelift Space is that group. + +We deploy `spacelift/spaces` three times. First we deploy a `root` Space for all Spacelift administrative resources, and then we deploy two more Spaces for the `plat` and `core` tenants. Spacelift exists outside of the AWS ecosystem, so we define these components as outside our standard stack organization. + +```diff ++ stacks/orgs/NAMESPACE/spacelift.yaml ++ stacks/orgs/NAMESPACE/core/spacelift.yaml ++ stacks/orgs/NAMESPACE/plat/spacelift.yaml +``` + +The `root` Space in Spacelift is responsible for deploying the root administrator stack, `admin-stack`, and the Spaces component, `spaces`. Since the root administrator stack is unique to tenants, we modify the stack context to create a unique stack slug, `root-gbl-spacelift`. + +A tenant-specific Space in Spacelift, such as `core` or `plat`, includes the administrator stack for that specific Space and _all_ components in the given tenant. This administrator stack uses `var.context_filters` to select all components in the given tenant and create Spacelift stacks for each. Similar to the root administrator stack, we again create a unique stack slug for each tenant. For example `core-gbl-spacelift` or `plat-gbl-spacelift`. + +
+Spacelift Spaces + + + {PartialSpaceliftRootStack} + + + {PartialSpaceliftTenantStack} + + +
+ +In the Spacelift UI, you should see the administrator stacks created. Typically these should look similar to the following: + +```diff ++ root-gbl-spacelift-admin-stack ++ root-gbl-spacelift-spaces ++ core-gbl-spacelift-admin-stack ++ plat-gbl-spacelift-admin-stack ++ core-ue1-auto-spacelift-worker-pool +``` + +### Worker Pools + +The `spacelift/worker-pool` component creates a worker pool for Spacelift to use. It +manages an ASG (Autoscaling Group) in AWS and the instances effectively run drift +detection and regular Spacelift stack runs. The component lives in the `auto` stage +since its considered automation infrastructure. Some common things to tweak while +working with this component include maximum instances (in-case runs are often blocked +by busy workers), and spot pricing (in-case runs are interrupted too frequently during +busy times). If you see a stack in a locked state with the run as `worker failed`, often +the instance was interrupted and the ASG events can be investigated for next steps. + +:::caution + +Spacelift Worker Pools can quickly become expensive. Spacelift bills per Worker total, and each +instance in the Auto Scaling Group can have a number of Spacelift Workers. + +By default, we set the max instance count in the Auto Scaling Group to 2 and set the number +of Spacelift Workers per instance to 1. This means that the total number of Spacelift Workers +can scale to `2 x 1 = 2`. Once you become more familiar with Spacelift, scale the workers per +instance or scale the number of instances with the `spacelift/worker-pool` catalog. + +```yaml +spacelift_agents_per_node: 1 # This is the number of Spacelift Workers for each instance +min_size: 1 # This is the minimum number of instances in the Auto Scaling Group +max_size: 2 # This is the maximum number of instances in the Auto Scaling Group +``` + +::: + +## Triggering Spacelift Runs + +Cloud Posse recommends two options to trigger Spacelift stacks. + +### Triggering with Policy Attachments + +Historically, all stacks were triggered with three `GIT_PUSH` policies: + + 1. [GIT_PUSH Global Administrator](https://github.com/cloudposse/terraform-spacelift-cloud-infrastructure-automation/blob/main/catalog/policies/git_push.administrative.rego) triggers admin stacks + 2. [GIT_PUSH Proposed Run](https://github.com/cloudposse/terraform-spacelift-cloud-infrastructure-automation/blob/main/catalog/policies/git_push.proposed-run.rego) triggers Proposed runs (typically Terraform Plan) for all non-admin stacks on Pull Requests + 3. [GIT_PUSH Tracked Run](https://github.com/cloudposse/terraform-spacelift-cloud-infrastructure-automation/blob/main/catalog/policies/git_push.tracked-run.rego) triggers Tracked runs (typically Terraform Apply) for all non-admin stacks on merges into `main` + +Attach these policies to stacks and Spacelift will trigger them on the respective git push. + +### Triggering with GitHub Comments (Preferred) + +Atmos support for `atmos describe affected` made it possible to greatly improve Spacelift's triggering workflow. Now we can add a GitHub Action to collect all affected components for a given Pull Request and add a GitHub comment to the given PR with a formatted list of the affected stacks. Then Spacelift can watch for a GitHub comment event and then trigger stacks based on that comment. + +In order to set up GitHub Comment triggers, first add the following `GIT_PUSH Plan Affected` policy to the `spaces` component. + +For example, + +```yaml title="stacks/catalog/spacelift/spaces.yaml" +components: + terraform: + spaces: + metadata: + component: spacelift/spaces + settings: + spacelift: + administrative: true + space_name: root + vars: + spaces: + root: + policies: +... + # This policy will automatically assign itself to stacks and is used to trigger stacks directly from the `cloudposse/github-action-atmos-affected-trigger-spacelift` GitHub action + # This is only used if said GitHub action is set to trigger on "comments" + "GIT_PUSH Plan Affected": + type: GIT_PUSH + labels: + - autoattach:pr-comment-triggered + body_url: https://raw.githubusercontent.com/cloudposse/terraform-spacelift-cloud-infrastructure-automation/%s/catalog/policies/push.git_comment.rego +``` + +This policy will automatically attach itself to _all_ components that have the `pr-comment-triggered` label, already defined in `stacks/orgs/NAMESPACE/_defaults.yaml` under `settings.spacelift.labels`. + +Next, create two new GitHub Action workflows: + +```diff ++ .github/workflows/atmos-trigger-spacelift-feature-branch.yaml ++ .github/workflows/atmos-trigger-spacelift-main-branch.yaml +``` + +The feature branch workflow will create a comment event in Spacelift to run a Proposed run for a given stack. Whereas the main branch workflow will create a comment event in Spacelift to run a Deploy run for those same stacks. + +#### Feature Branch + +```yaml +name: "Plan Affected Spacelift Stacks" + +on: + pull_request: + types: + - opened + - synchronize + - reopened + branches: + - main + +jobs: + context: + runs-on: ["self-hosted"] + steps: + - name: Atmos Affected Stacks Trigger Spacelift + uses: cloudposse/github-action-atmos-affected-trigger-spacelift@v1 + with: + atmos-config-path: ./rootfs/usr/local/etc/atmos + github-token: ${{ secrets.GITHUB_TOKEN }} +``` + +This will add a GitHub comment such as: + +``` +/spacelift preview plat-ue1-sandbox-foobar +``` + +#### Main Branch + +```yaml +name: "Deploy Affected Spacelift Stacks" + +on: + pull_request: + types: [closed] + branches: + - main + +jobs: + run: + if: github.event.pull_request.merged == true + runs-on: ["self-hosted"] + steps: + - name: Atmos Affected Stacks Trigger Spacelift + uses: cloudposse/github-action-atmos-affected-trigger-spacelift@v1 + with: + atmos-config-path: ./rootfs/usr/local/etc/atmos + deploy: true + github-token: ${{ secrets.GITHUB_TOKEN }} + head-ref: ${{ github.sha }}~1 +``` + +This will add a GitHub comment such as: + +``` +/spacelift deploy plat-ue1-sandbox-foobar +``` + +### Component Documentation + +- [`spacelift`](/components/library/aws/spacelift/) + +## References + +- [Spacelift Documentation](https://docs.spacelift.io/) +- [Design decision on how Spacelift will use external private modules](/reference-architecture/fundamentals/design-decisions/foundational-platform/decide-on-how-spacelift-will-use-external-private-modules/) +- [Design decision on Spacelift worker pool architecture](/reference-architecture/fundamentals/design-decisions/foundational-platform/decide-on-spacelift-worker-pool-architecture/) +- [Design decision on Spacelift administrative stack auto-deployment](/reference-architecture/fundamentals/design-decisions/foundational-platform/decide-on-spacelift-administrative-stack-auto-deployment/) +- [Implement Foundational Platform: Spacelift](/reference-architecture/setup/implement-foundational-platform-spacelift/) +- [Implement Spacelift GitOps](/reference-architecture/setup/implement-spacelift-gitops/) +- [How to sign up for Spacelift](/reference-architecture/how-to-guides/integrations/spacelift/) +- [How to destroy a component using Atmos or Spacelift](/reference-architecture/how-to-guides/integrations/spacelift/how-to-destroy-a-component-using-atmos-or-spacelift/) +- [How to scale Spacelift runners](/reference-architecture/how-to-guides/integrations/spacelift/how-to-scale-spacelift-runners/) +- [How to use spacectl](/reference-architecture/how-to-guides/integrations/spacelift/how-to-use-spacectl/) +- [How to manage explicit component dependencies with Spacelift](/reference-architecture/how-to-guides/integrations/spacelift/how-to-manage-explicit-component-dependencies-with-spacelift/) +- [How to use multiple infrastructure repositories with Spacelift](/reference-architecture/how-to-guides/integrations/spacelift/how-to-use-multiple-infrastructure-repositories-with-spacelift/) +- [How to develop with Spacelift and Atmos](/reference-architecture/how-to-guides/integrations/spacelift/how-to-develop-with-spacelift-and-atmos/) +- [How to enable Spacelift drift detection](/reference-architecture/how-to-guides/integrations/spacelift/how-to-enable-spacelift-drift-detection/) +- [Use Spacelift for GitOps with Terraform](/reference-architecture/reference/adrs/use-spacelift-for-gitops-with-terraform/) +- [Proposed Spacelift admin stack architecture](/reference-architecture/reference/adrs/proposed-spacelift-admin-stack-architecture/) diff --git a/docs/layers/spacelift/tutorials/how-to-develop-with-spacelift-and-atmos.mdx b/docs/layers/spacelift/tutorials/how-to-develop-with-spacelift-and-atmos.mdx index f8ce24eb7..7a3d06ade 100644 --- a/docs/layers/spacelift/tutorials/how-to-develop-with-spacelift-and-atmos.mdx +++ b/docs/layers/spacelift/tutorials/how-to-develop-with-spacelift-and-atmos.mdx @@ -41,7 +41,7 @@ Maintaining good Spacelift status for our stacks is **very important.** If we se Here’s the general workflow when working with infrastructure: -
+
1. Apply your changes through Spacelift where/whenever possible. (open PR → spacelift proposed run looks OK → approve & merge → spacelift plan, confirm, apply, party on) diff --git a/docs/layers/spacelift/tutorials/how-to-enable-spacelift-drift-detection.mdx b/docs/layers/spacelift/tutorials/how-to-enable-spacelift-drift-detection.mdx index 183caf93b..d7219a9c1 100644 --- a/docs/layers/spacelift/tutorials/how-to-enable-spacelift-drift-detection.mdx +++ b/docs/layers/spacelift/tutorials/how-to-enable-spacelift-drift-detection.mdx @@ -33,7 +33,7 @@ components: drift_detection_enabled: true drift_detection_reconcile: true ``` -
+
### Default Settings diff --git a/docs/layers/spacelift/tutorials/how-to-manage-explicit-component-dependencies-with-spacelift.mdx b/docs/layers/spacelift/tutorials/how-to-manage-explicit-component-dependencies-with-spacelift.mdx index 423861438..ccb409da8 100644 --- a/docs/layers/spacelift/tutorials/how-to-manage-explicit-component-dependencies-with-spacelift.mdx +++ b/docs/layers/spacelift/tutorials/how-to-manage-explicit-component-dependencies-with-spacelift.mdx @@ -5,6 +5,7 @@ sidebar_position: 100 --- import Intro from '@site/src/components/Intro'; import KeyPoints from '@site/src/components/KeyPoints'; +import Steps from '@site/src/components/Steps'; ## Problem @@ -12,12 +13,8 @@ When Spacelift deploys a component into a particular environment it doesn’t na ## Solution -:::tip -Use labels in Spacelift to define the dependencies between components - -::: - :::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. @@ -38,108 +35,113 @@ Spacelift can only operate on dependency relationships within a single commit. T ::: -### Ways to Express Dependencies with Labels +### Confifgure Dependencies Between Components with Labels + +Use labels in Spacelift to define the dependencies between components -
+
There are many ways to express dependencies. Which to use depends on what you need to accomplish. You can see the dependencies easily in the Spacelift UI by looking at the labels. Not all labels are dependencies, only the ones that begin with `deps:`or `depends-on:`. (note, the folders are created similarly by prefixing labels with `folder:`) We support globbing with `*` and `**` so you can express things like `stacks/uw2/**` to match all files recursively in the `stacks/uw2` folder. + A component can depend on any folder as part of the VCS. If a change is detected in that folder, then it will trigger a plan. Just prefix the label with `deps:` and add a `/*` at the end to match all files. ```yaml labels: -- deps:component/aurora-postgres-2/* -- deps:uw2/dev/* + - deps:component/aurora-postgres-2/* + - deps:uw2/dev/* ``` A component can express explicit dependencies on other files. ```yaml labels: -- deps:stacks/catalog/rds-defaults.yaml -- deps:stacks/globals.yaml -- deps:stacks/uw2-dev.yaml -- deps:stacks/uw2-globals.yaml -- deps:config/secrets/dev-internal-secrets.yml - + - deps:stacks/catalog/rds-defaults.yaml + - deps:stacks/globals.yaml + - deps:stacks/uw2-dev.yaml + - deps:stacks/uw2-globals.yaml + - deps:config/secrets/dev-internal-secrets.yml ``` A component can express explicit dependencies on other components in other stacks (e.g. the `vpc` component in the `uw2-dev` stack) ```yaml labels: -- depends-on:uw2-dev-vpc -- depends-on:uw2-dev-dns-delegated -- depends-on:gbl-dns-dns-primary + - depends-on:uw2-dev-vpc + - depends-on:uw2-dev-dns-delegated + - depends-on:gbl-dns-dns-primary ``` A component can express explicit dependencies on the current stack (E.g. the `vpc`) without needing to express the canonical component name. ```yaml labels: -- depends-on:vpc -- depends-on:dns-delegated -- depends-on:dns-primary + - depends-on:vpc + - depends-on:dns-delegated + - depends-on:dns-primary ``` ### Step-by-Step Process -1. You use `depends_on` in YAML like this: - -```yaml - dms-iam: - settings: - spacelift: - workspace_enabled: true - policies_by_name_enabled: - - "access.dms" - - dms-replication-instance: - settings: - spacelift: - workspace_enabled: true - depends_on: # Stack dependencies. This stack will be triggered after the parent stack finishes running - - "dms-iam" -``` - -2. When your `spacelift` component (which uses [https://github.com/cloudposse/terraform-spacelift-cloud-infrastructure-automation](https://github.com/cloudposse/terraform-spacelift-cloud-infrastructure-automation)) parses the YAML, it adds the label to the Spacelift stacks - -3. Spacelift checks the rego policy `trigger.dependencies.rego` to determine if the label exists on the stack and triggers the dependent stack(s) - -### Example - -```yaml - aurora-postgres-2: - component: aurora-postgres - settings: - spacelift: - workspace_enabled: true - autodeploy: true - labels: - - "deps:config/secrets/dev-internal-secrets.yml" - depends_on: - - vpc - - dns-delegated - - gbl-dns-dns-primary -``` - -Will associate the following labels in Spacelift with the Stack: - -```yaml -labels: - - deps:stacks/catalog/rds-defaults.yaml - - deps:stacks/globals.yaml - - deps:stacks/uw2-dev.yaml - - deps:stacks/uw2-globals.yaml - - deps:config/secrets/dev-internal-secrets.yml - - depends-on:uw2-dev-vpc - - depends-on:uw2-dev-dns-delegated - - depends-on:gbl-dns-dns-primary - - folder:component/aurora-postgres-2 - - folder:uw2/dev -``` + + + 1. You use `depends_on` in YAML like this: + + ```yaml + dms-iam: + settings: + spacelift: + workspace_enabled: true + policies_by_name_enabled: + - "access.dms" + + dms-replication-instance: + settings: + spacelift: + workspace_enabled: true + depends_on: # Stack dependencies. This stack will be triggered after the parent stack finishes running + - "dms-iam" + ``` + + 2. When your `spacelift` component (which uses [https://github.com/cloudposse/terraform-spacelift-cloud-infrastructure-automation](https://github.com/cloudposse/terraform-spacelift-cloud-infrastructure-automation)) parses the YAML, it adds the label to the Spacelift stacks + + 3. Spacelift checks the rego policy `trigger.dependencies.rego` to determine if the label exists on the stack and triggers the dependent stack(s) + + ### Example + + ```yaml + aurora-postgres-2: + component: aurora-postgres + settings: + spacelift: + workspace_enabled: true + autodeploy: true + labels: + - "deps:config/secrets/dev-internal-secrets.yml" + depends_on: + - vpc + - dns-delegated + - gbl-dns-dns-primary + ``` + + Will associate the following labels in Spacelift with the Stack: + + ```yaml + labels: + - deps:stacks/catalog/rds-defaults.yaml + - deps:stacks/globals.yaml + - deps:stacks/uw2-dev.yaml + - deps:stacks/uw2-globals.yaml + - deps:config/secrets/dev-internal-secrets.yml + - depends-on:uw2-dev-vpc + - depends-on:uw2-dev-dns-delegated + - depends-on:gbl-dns-dns-primary + - folder:component/aurora-postgres-2 + - folder:uw2/dev + ``` + ## Troubleshooting diff --git a/docs/layers/spacelift/tutorials/how-to-scale-spacelift-runners.mdx b/docs/layers/spacelift/tutorials/how-to-scale-spacelift-runners.mdx index 0f30cbe5a..ea421b26a 100644 --- a/docs/layers/spacelift/tutorials/how-to-scale-spacelift-runners.mdx +++ b/docs/layers/spacelift/tutorials/how-to-scale-spacelift-runners.mdx @@ -8,16 +8,18 @@ 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. +There are hundreds or thousands of proposed runs pending in Spacelift. Autoscaling will eventually scale up to handle capacity but want faster turnaround time. ## Solution :::note + If there are too many Spacelift runs triggered by PRs that do not require Spacelift to run at the moment. The user can add a label called `spacelift-no-trigger` on the PR to prevent Spacelift stacks from running on each commit. This label should be removed before the last commit (before approval and merge) so the Spacelift stacks can be validated. ::: :::note + To reduce Spacelift runs triggered by PRs, ensure that the `spacelift` component is using the [latest upstream module](https://github.com/cloudposse/terraform-spacelift-cloud-infrastructure-automation/releases) or `0.46.0` at the very least. This release has an updated policy that cancels previous commit runs if a new commit is pushed. ::: @@ -25,6 +27,7 @@ To reduce Spacelift runs triggered by PRs, ensure that the `spacelift` component ### Scaling EC2 Runners via Stack Configurations :::caution + While we always recommend making all changes to IaC via Pull Request, if the desire is to increase the size of the Auto Scale Group and there are hundreds or thousands of pending runs, then the Pull Request will suffer the same fate as the other runs and be blocked from execution until the other runs complete. ::: @@ -129,7 +132,7 @@ Before scaling spacelift workers down, check the “**Pending runs**” and “* ::: -
+
- Login to the AWS console for the automation account. diff --git a/docs/layers/spacelift/tutorials/how-to-sign-up.mdx b/docs/layers/spacelift/tutorials/how-to-sign-up.mdx index 092fd1b7e..b7e7e57e4 100644 --- a/docs/layers/spacelift/tutorials/how-to-sign-up.mdx +++ b/docs/layers/spacelift/tutorials/how-to-sign-up.mdx @@ -5,6 +5,7 @@ sidebar_position: 0 --- import Intro from '@site/src/components/Intro'; import KeyPoints from '@site/src/components/KeyPoints'; +import Steps from '@site/src/components/Steps'; ## Problem @@ -17,80 +18,10 @@ 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. - -- This is deployed to private subnets and its IPs are allowlisted in security groups so it can manage EKS clusters, helm charts, aurora/rds cluster resources (databases, users), and other private resources. - -- **“Webhook-based audit logging”** which is used to send notifications from Spacelift to external systems like Datadog or Opsgenie. These notifications include audit login, the status of each stack, each run, etc., which is useful for compliance and stacks’ status visibility. - -- For a full breakdown of the differences, check out the [spacelift pricing](https://spacelift.io/pricing). - -This is required in order to provision any database users or schemas, manage EKS clusters on a private subnet, or in general manage any resources residing in private subnets in a VPC. The other benefit with an Enterprise Agreement is that it will fix your costs, even if you burst your Spacelift Workers. If you were on a Metered (aka “pay-as-you-go plan”), you will be charged for those bursts and that will add up to thousands per month. - -The Spacelift Enterprise 30 day trial (with an option to extend it) should be signed up to take advantage of these features. - -:::tip Referrals - -Cloud Posse has a partnership with Spacelift that can save you cost! Please reach out to Cloud Posse for a referral. - -::: - -### Who should you contact regarding Spacelift contracts and pricing? - -Reach out to Pawel Hawtry [pawelh@spacelift.io](mailto:pawelh@spacelift.io) and mention you are working with Cloud Posse. Alternatively, we’re happy to facilitate an introduction directly. - -### What if Spacelift is too expensive? - -First, make sure you understand why we chose to [Use Spacelift for GitOps with Terraform](/reference-architecture/reference/adrs/use-spacelift-for-gitops-with-terraform). DIY is non-trivial. - -Spacelift wants your business and they only want happy customers. Work with them to reach a middle ground that makes everyone happy. - -### Why can’t we start with an entry-level plan? - -(See [How to Sign Up for Spacelift](/reference-architecture/how-to-guides/integrations/spacelift) ) - -- Only enterprise plans support self-hosted workers which are required in order to manage any infrastructure provisioned inside of VPCs (E.g. Databases, non-public EKS clusters, terraform provisioners, etc). Additionally, using EC2 Instance Profiles we’re able to grant the precise roles we want to give Spacelift without any hardcoded credentials. - -- Only enterprise plans support fixed costs. Cloud is metered billing, which means if we scale up our workers temporarily to flush out a large queue of plans, they will charge for the additional workers on a monthly rate. They do not have the ability to disable this and it happens automatically. Several customers have accidentally encountered _Bill Shock_ as a result of this (we got it all sorted out for them in the end!) - -
- -
- -### Is Spacelift SOC2 Compliant? - -Yes, Spacelift has SOC2 Type II certification performed by an independent external auditor who confirms the effectiveness of internal controls in terms of Spacelift security, availability, processing integrity, confidentiality, and privacy of customer data. - -[https://spacelift.io/security](https://spacelift.io/security) - -Spacelift’s SOC2 Type 2 report and the pentest report from April 2021 is attached below. If anyone ever has any security-related questions, they can reach out to [@Wojciech Syrkiewicz-Trepiak](mailto:wojciechs@spacelift.io), Spacelift’s security engineer. Spacelift also has D&O and Cyber & Tech Insurance in place. - -Please reach out to Spacelift to request a report. - -### How many runners will we need? - -**TL;DR:** it really varies, but start with a minimum of 2-3. - -Since Spacelift permits you to scale up for short periods of time without metering, we recommend starting with a commitment of 2-3 runners online at any time. We’ll configure your workers to autoscale up as necessary. - -### Can we consolidate multiple Spacelift Organizations under one bill? - -Yes! Spacelift can consolidate the billing. For example, if you have multiple GitHub Organizations, each one associated with a different Spacelift Organization, Spacelift can consolidate the invoice. - -### Where do we sign up? - -How you sign up depends on if you’re using GitHub or GitLab. #### GitHub Organizations -
+
[https://spacelift.io/free-trial](https://spacelift.io/free-trial) @@ -104,7 +35,7 @@ Or install it by going here: #### GitLab Organizations -
+
For organizations running GitLab, register with your work email address instead. @@ -112,11 +43,6 @@ For organizations running GitLab, register with your work email address instead. Once you’ve signed up for the Spacelift trial, we’ll configure GitLab as source control integration. To learn more about setting up the GitLab integration, see the [https://docs.spacelift.io/integrations/source-control/gitlab](https://docs.spacelift.io/integrations/source-control/gitlab) integration documentation. -### What if HashiCorp Decides to go the way of MongoDB and Elastic with Licensing? ... where does that put Spacelift? - -Spacelift is actually using Terraform the same way GitHub Actions or GitLab uses it. Spacelift does not distribute the binary and they don't link against it. So Spacelift is no different than any other system in that respect. - -Therefore, based on Spacelift’s usage pattern there should be no concern. Also, if Terraform ever becomes a tool that cannot be used in third-party automation, there is likely going to be a hard fork from the community. ## Signup Process @@ -125,6 +51,7 @@ Sign up for Spacelift after the cold start components and `vpc` component have b ::: + 1. Sign up [https://spacelift.io/free-trial](https://spacelift.io/free-trial) 2. Install [Spacelift GitHub app](https://github.com/apps/spacelift-io/installations/new) into the customer GitHub organization @@ -155,56 +82,56 @@ 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. -# Note 2: Enabling SSO requires that all users have an IdP (G Suite) account, so we'll just use -# GitHub authentication in the meantime while working with external collaborators. -# Map session input data to human friendly variables to use in policy evaluation -username := input.session.login -member_of := input.session.teams - -github_org := input.session.member - -# Define GitHub usernames of non-github_org org external collaborators with admin vs. user access -admin_collaborators := { "osterman", "aknysh", "Nuru", "nitrocode" } # case sensitive names of collaborators - -user_collaborators := { "Customer Github Org" } # case sensitive name of the github org - -# Grant admin access to github_org org members in the non cloud posse case-sensitive team -# Do not use the slug here, use the name shown in github.com/org/teams -admin { - github_org - member_of[_] == "YOUR-CASE-SENSITIVE-TEAM-NAME" -} - -# Grant admin access to github_org org members in the Cloud Posse group -# Do not use the slug here, use the name shown in github.com/org/teams -admin { - github_org - member_of[_] == "CLOUDPOSSE-CASE-SENSITIVE-TEAM-NAME" -} - -# Grant admin access to non-github_org org accounts in the admin_collaborators set -admin { - # not github_org - admin_collaborators[username] -} - -# Grant user access to accounts in the user_collaborators set -allow { - # not github_org - user_collaborators[username] -} - -# Deny access to any non-github_org org accounts who aren't defined in external collaborators sets -deny { - not github_org - not user_collaborators[username] - not admin_collaborators[username] -} -``` + ```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. + # Note 2: Enabling SSO requires that all users have an IdP (G Suite) account, so we'll just use + # GitHub authentication in the meantime while working with external collaborators. + # Map session input data to human friendly variables to use in policy evaluation + username := input.session.login + member_of := input.session.teams + + github_org := input.session.member + + # Define GitHub usernames of non-github_org org external collaborators with admin vs. user access + admin_collaborators := { "osterman", "aknysh", "Nuru", "nitrocode" } # case sensitive names of collaborators + + user_collaborators := { "Customer Github Org" } # case sensitive name of the github org + + # Grant admin access to github_org org members in the non cloud posse case-sensitive team + # Do not use the slug here, use the name shown in github.com/org/teams + admin { + github_org + member_of[_] == "YOUR-CASE-SENSITIVE-TEAM-NAME" + } + + # Grant admin access to github_org org members in the Cloud Posse group + # Do not use the slug here, use the name shown in github.com/org/teams + admin { + github_org + member_of[_] == "CLOUDPOSSE-CASE-SENSITIVE-TEAM-NAME" + } + + # Grant admin access to non-github_org org accounts in the admin_collaborators set + admin { + # not github_org + admin_collaborators[username] + } + + # Grant user access to accounts in the user_collaborators set + allow { + # not github_org + user_collaborators[username] + } + + # Deny access to any non-github_org org accounts who aren't defined in external collaborators sets + deny { + not github_org + not user_collaborators[username] + not admin_collaborators[username] + } + ``` 5. Verify Cloud Posse users have administrative access @@ -228,7 +155,10 @@ deny { 9. Also share the 16 character string next to the name of the key which gives us the `key_id`. -:::caution + + +:::important + After signing up and following the above steps, let our team know what your Spacelift account slug is and we’ll get it upgraded to an Enterprise trial via our partner channels with Spacelift. ::: diff --git a/docs/learn/component-development/faq.mdx b/docs/learn/component-development/faq.mdx index 7267299a0..7c25f0940 100644 --- a/docs/learn/component-development/faq.mdx +++ b/docs/learn/component-development/faq.mdx @@ -19,12 +19,12 @@ Developing a new component may be necessary when: Components should not include other components but instead can refer to another component's Terraform Output with `remote-state`. Components can however refer to any Terraform module -### What is the purpose of context.tf? +### What is the purpose of `context.tf`? Cloud Posse uses [`context.tf`](/reference-architecture/reference/learning-resources/#the-contexttf-pattern) to consistently set metadata across all modules and resources. -### Where should the context.tf file be copied from? +### Where should the `context.tf` file be copied from? The `context.tf` file should be copied exactly from https://raw.githubusercontent.com/cloudposse/terraform-null-label/master/exports/context.tf. @@ -46,10 +46,10 @@ that cannot be instantiated directly. ### Does Cloud Posse have automated testing for components? -We do not have automated testing for our components per se at this time. However, GitOps pipelines with Spacelift can -automate component deployment into lower environments, so that we can validate any code changes in each stage before +We do not have automated testing for our components at this time. However, GitOps pipelines with Spacelift can +automate component deployment into lower environments so that we can validate any code changes in each stage before reaching production. -Also, we do have automated tested for all Terraform modules the components built off of +Also, we do have automated tests for all Terraform modules the components built off of ([rds-cluster example](https://github.com/cloudposse/terraform-aws-rds-cluster/tree/master/test)) and static code linting for Terraform and Atmos (with a local `.github/workflows/pre-commit.yml`). diff --git a/docs/learn/component-development/terraform-in-depth/terraform-count-vs-for-each.mdx b/docs/learn/component-development/terraform-in-depth/terraform-count-vs-for-each.mdx index e98f92838..5bce2969a 100644 --- a/docs/learn/component-development/terraform-in-depth/terraform-count-vs-for-each.mdx +++ b/docs/learn/component-development/terraform-in-depth/terraform-count-vs-for-each.mdx @@ -1,15 +1,9 @@ --- +id: "terraform-count-vs-for-each" title: "Count vs For Each" description: "When to use count and when to use for_each in Terraform" -slug: "terraform-count-vs-for-each" tags: - - "Best Practices" - - "Terraform" - - "Terraform in Depth" -categories: - - "Community Resources" - - "Terraform" - - "Terraform in Depth" + - "terraform" --- import Intro from '@site/src/components/Intro'; import Note from '@site/src/components/Note'; @@ -452,4 +446,4 @@ introduces. ### Further Reading - [Error: Values Cannot Be Determined Until Apply](/reference/terraform-in-depth/terraform-unknown-at-plan-time). -- [Terraform Best Practices](/reference/best-practices/terraform-best-practices) +- [Terraform Best Practices](/best-practices/terraform) diff --git a/docs/learn/component-development/terraform-in-depth/terraform-in-depth.mdx b/docs/learn/component-development/terraform-in-depth/terraform-in-depth.mdx index 6aeead106..c98f59c63 100644 --- a/docs/learn/component-development/terraform-in-depth/terraform-in-depth.mdx +++ b/docs/learn/component-development/terraform-in-depth/terraform-in-depth.mdx @@ -1,28 +1,21 @@ --- +id: "terraform-in-depth" title: "Terraform in Depth" sidebar_label: "Terraform in Depth" description: "Deep dive into Terraform implementation details and pitfalls" -slug: "terraform-in-depth" sidebar_position: 3 -sidebar_class_name: hidden tags: - - "Best Practices" - - "Terraform" -categories: - - "Community Resources" - - "Terraform" + - "terraform" --- import Intro from '@site/src/components/Intro' +import DocCardList from '@theme/DocCardList' -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. + 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](/assets/08bcd99-terraform.png) We provide a lot of information about how to use Terraform and write Terraform code elsewhere on this site: -- [Terraform Fundamentals](/fundamentals/terraform.md) -- [Terraform Best Practices](/reference/best-practices/terraform-best-practices.md) -- [Terraform Tips and Tricks](/reference/best-practices/terraform-tips-tricks.md) - + diff --git a/docs/learn/component-development/terraform-in-depth/terraform-unknown-at-plan-time.mdx b/docs/learn/component-development/terraform-in-depth/terraform-unknown-at-plan-time.mdx index f3fa55da9..55211a85b 100644 --- a/docs/learn/component-development/terraform-in-depth/terraform-unknown-at-plan-time.mdx +++ b/docs/learn/component-development/terraform-in-depth/terraform-unknown-at-plan-time.mdx @@ -1,15 +1,10 @@ --- +id: "terraform-unknown-at-plan-time" title: "Error: Values Cannot Be Determined Until Apply" description: "Details about computed values can cause `terraform plan` to fail" -slug: "terraform-unknown-at-plan-time" tags: - - "Best Practices" - - "Terraform" - - "Terraform in Depth" -categories: - - "Community Resources" - - "Terraform" - - "Terraform in Depth" + - terraform + - development --- import Intro from '@site/src/components/Intro'; import Note from '@site/src/components/Note'; @@ -199,7 +194,7 @@ Best practice is to either use a separate boolean input (e.g. `ebs_volume_enabled`) to condition the resource creation, or to take the optional value as an element of a list and use the length of the list to determine whether to create the resource. See [Use feature flags or lists to -control optional behaviors](/reference/best-practices/terraform-best-practices/#use-feature-flags-to-enabledisable-functionality) +control optional behaviors](best-practices/terrafor/#use-feature-flags-to-enabledisable-functionality) for more information. ::: diff --git a/docs/learn/conventions.mdx b/docs/learn/conventions.mdx index fa90a0f3e..0c710445d 100644 --- a/docs/learn/conventions.mdx +++ b/docs/learn/conventions.mdx @@ -41,6 +41,12 @@ We do not recommend consuming one terraform component inside of another as that - Components should use `context.tf` [Terraform](/fundamentals/terraform). + + - Components should have a `README.md` with sample usage - Components should be well formatted (e.g. `terraform fmt`) @@ -49,7 +55,7 @@ We do not recommend consuming one terraform component inside of another as that - Components should try to upstream as much business logic as possible to child modules to promote reuse. -- Components should use strict version pinning in components and lower-bound pinning in terraform modules. See [our best practice for this](/reference/best-practices/terraform-best-practices/#use-miminum-version-pinning-on-all-providers). See [How to Keep Everything Up to Date](/reference-architecture/how-to-guides/upgrades/how-to-keep-everything-up-to-date) after pinning. See [Proposed: Use Strict Provider Pinning in Components](/reference-architecture/reference/adrs/proposed-use-strict-provider-pinning-in-components) for more context. +- Components should use strict version pinning in components and lower-bound pinning in terraform modules. See [our best practice for this](/best-practices/terraform#use-miminum-version-pinning-on-all-providers). See [How to Keep Everything Up to Date](/reference-architecture/how-to-guides/upgrades/how-to-keep-everything-up-to-date) after pinning. See [Proposed: Use Strict Provider Pinning in Components](/reference-architecture/reference/adrs/proposed-use-strict-provider-pinning-in-components) for more context. ### Stacks diff --git a/docs/learn/maintenance/maintenance.mdx b/docs/learn/maintenance/maintenance.mdx index 399ce4233..c0deb8e00 100644 --- a/docs/learn/maintenance/maintenance.mdx +++ b/docs/learn/maintenance/maintenance.mdx @@ -2,6 +2,7 @@ title: "Maintenance" sidebar_label: "Maintenance" sidebar_class_name: hidden +sidebar_position: 100 --- import Intro from '@site/src/components/Intro'; import KeyPoints from '@site/src/components/KeyPoints'; diff --git a/docs/learn/maintenance/tutorials/how-to-define-stacks-for-multiple-regions.mdx b/docs/learn/maintenance/tutorials/how-to-define-stacks-for-multiple-regions.mdx index dd1833251..4c5534c7c 100644 --- a/docs/learn/maintenance/tutorials/how-to-define-stacks-for-multiple-regions.mdx +++ b/docs/learn/maintenance/tutorials/how-to-define-stacks-for-multiple-regions.mdx @@ -6,6 +6,7 @@ sidebar_position: 100 --- import Intro from '@site/src/components/Intro'; import KeyPoints from '@site/src/components/KeyPoints'; +import Steps from '@site/src/components/Steps'; ## Problem @@ -22,77 +23,78 @@ Define one stack configuration for every region and simply import the catalog co Let’s say we want to deploy the [vpc](/components/library/aws/vpc/) into the AWS `us-east-1` and `us-west-2` regions in the `dev` account. We’ll want to customize the CIDR block, region, and availability zones used. Here’s how to do it... -1. Define a catalog entry for the common `vpc` configuration. This is where we can define our organizations best-practices for a VPC. - -``` -# stacks/catalog/vpc.yaml -components: - terraform: - vpc: - backend: - s3: - workspace_key_prefix: vpc - settings: - spacelift: - workspace_enabled: true + + 1. Define a catalog entry for the common `vpc` configuration. This is where we can define our organizations best-practices for a VPC. + + ```yaml + # stacks/catalog/vpc.yaml + components: + terraform: + vpc: + backend: + s3: + workspace_key_prefix: vpc + settings: + spacelift: + workspace_enabled: true + vars: + enabled: true + subnet_type_tag_key: acme.net/subnet/type + vpc_flow_logs_enabled: true + #vpc_flow_logs_bucket_environment_name: uw2 + vpc_flow_logs_bucket_stage_name: audit + vpc_flow_logs_bucket_tenant_name: mgmt + vpc_flow_logs_traffic_type: ALL + ``` + + 2. Now define a stack configuration for the `us-east-1` region. + + ```yaml + # stacks/ue1-dev.yaml + import: + - catalog/vpc + + # Define the global variables for this region vars: - enabled: true - subnet_type_tag_key: acme.net/subnet/type - vpc_flow_logs_enabled: true - #vpc_flow_logs_bucket_environment_name: uw2 - vpc_flow_logs_bucket_stage_name: audit - vpc_flow_logs_bucket_tenant_name: mgmt - vpc_flow_logs_traffic_type: ALL -``` - -2. Now define a stack configuration for the `us-east-1` region. - -``` -# stacks/ue1-dev.yaml -import: -- catalog/vpc - -# Define the global variables for this region -vars: - region: us-east-1 - environment: ue1 - -components: - terraform: - vpc: + region: us-east-1 + environment: ue1 + + components: + terraform: + vpc: + vars: + cidr_block: 10.1.0.0/18 + vpc_flow_logs_bucket_environment_name: ue1 + availability_zones: + - "us-east-1a" + - "us-east-1b" + - "us-east-1c" + ``` + + 3. Then repeat the process and define a stack configuration for the `us-west-2` region. + + ```yaml + # stacks/uw2-dev.yaml + import: + - catalog/vpc + + # Define the global variables for this region vars: - cidr_block: 10.1.0.0/18 - vpc_flow_logs_bucket_environment_name: ue1 - availability_zones: - - "us-east-1a" - - "us-east-1b" - - "us-east-1c" -``` - -3. Then repeat the process and define a stack configuration for the `us-west-2` region. - -``` -# stacks/uw2-dev.yaml -import: -- catalog/vpc - -# Define the global variables for this region -vars: - region: us-west-2 - environment: uw2 - -components: - terraform: - vpc: - vars: - cidr_block: 10.2.0.0/18 - vpc_flow_logs_bucket_environment_name: uw2 - availability_zones: - - "us-west-2a" - - "us-west-2b" - - "us-west-2c" -``` + region: us-west-2 + environment: uw2 + + components: + terraform: + vpc: + vars: + cidr_block: 10.2.0.0/18 + vpc_flow_logs_bucket_environment_name: uw2 + availability_zones: + - "us-west-2a" + - "us-west-2b" + - "us-west-2c" + ``` + Now use the standard [Atmos](/fundamentals/atmos) commands to plan and apply the stack configurations. - diff --git a/docs/learn/maintenance/tutorials/how-to-document-a-new-design-decision.mdx b/docs/learn/maintenance/tutorials/how-to-document-a-new-design-decision.mdx index 06a490afc..b6224a209 100644 --- a/docs/learn/maintenance/tutorials/how-to-document-a-new-design-decision.mdx +++ b/docs/learn/maintenance/tutorials/how-to-document-a-new-design-decision.mdx @@ -44,11 +44,11 @@ Undecided 3. The result should look like this: -
+
3. **After hitting “Save” you should see something that looks like this:** -
+
4. **Clicking on the title will take you to the confluence page. Add all the context there.** diff --git a/docs/learn/maintenance/tutorials/how-to-load-test-in-aws.mdx b/docs/learn/maintenance/tutorials/how-to-load-test-in-aws.mdx index ecdbef5ce..e63f2bfd7 100644 --- a/docs/learn/maintenance/tutorials/how-to-load-test-in-aws.mdx +++ b/docs/learn/maintenance/tutorials/how-to-load-test-in-aws.mdx @@ -80,7 +80,7 @@ Horizontal Pod Autoscaling requires the `metrics-server` component be deployed #### Pre-warming AWS Resources Certain resources in AWS need to be pre-warmed. Most notably, [Elastic Load Balancers still require prewarming](https://aws.amazon.com/articles/best-practices-in-evaluating-elastic-load-balancing/#pre-warming). -
+
This includes ALBs, however, we do not have any links to documentation to back that up. Reach out to Amazon to ask them to pre-warm your load balancers. Alternatively, make sure you scale your tests progressively, as ELBs scale best with a gradual increase in traffic load. ELBs do not respond well to spiky loads, and you’ll see 503s if too much traffic is directed their way too quickly. @@ -93,7 +93,7 @@ Also, consider pre-warming all database caches (e.g. RDS and Elasticache). #### Scaling AWS Resources - Make sure to raise account limits for resources as needed. -
+
- [https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-spot-limits.html](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-spot-limits.html) diff --git a/docs/learn/maintenance/tutorials/how-to-manage-terraform-dependencies-in-micro-service-repositori.mdx b/docs/learn/maintenance/tutorials/how-to-manage-terraform-dependencies-in-micro-service-repositori.mdx index 50ee60222..fb684913b 100644 --- a/docs/learn/maintenance/tutorials/how-to-manage-terraform-dependencies-in-micro-service-repositori.mdx +++ b/docs/learn/maintenance/tutorials/how-to-manage-terraform-dependencies-in-micro-service-repositori.mdx @@ -179,7 +179,7 @@ Spacelift needs access to the microservice repository in question in order to cr 4. Select the microservice repositories that will be deployed by Spacelift, in addition to the infrastructure monorepo. -
+
### Create a Spacelift Stack in the Infrastructure Monorepo pointing to the Microservice Repository @@ -206,7 +206,7 @@ At this point, your stack should be running without issues in Spacelift. In order to develop the Terraform Configuration Locally, you will need the `tfvars` JSON generated by Spacelift when the stack is created. In order to do this, create a very minimal Terraform configuration using the `infra-state.mixin.tf` (and maybe one or two resources). After the Spacelift stack is created using the administrative stack, navigate to the newly-created stack and to the `Env` tab in Spacelift: -
+
Copy the contents of `spacelift.auto.tfvars.json` and populate a file with the same name in the Terraform directory in the application repository. You will then be able to run `terraform init` and `terraform plan`. diff --git a/docs/learn/maintenance/upgrades/how-to-upgrade-atmos.mdx b/docs/learn/maintenance/upgrades/how-to-upgrade-atmos.mdx index 9cf934206..199275667 100644 --- a/docs/learn/maintenance/upgrades/how-to-upgrade-atmos.mdx +++ b/docs/learn/maintenance/upgrades/how-to-upgrade-atmos.mdx @@ -70,7 +70,7 @@ The administrative stack must have its runner image set to custom Geodesic image stacks = [for f in local.stack_config_files : trimsuffix(basename(f), ".yaml")] } ``` -
+
7. Update the file `components/terraform/spacelift/context.tf` to the latest version (take it from [https://github.com/cloudposse/terraform-null-label/blob/master/exports/context.tf](https://github.com/cloudposse/terraform-null-label/blob/master/exports/context.tf)) diff --git a/docs/learn/tips-and-tricks/tips-and-tricks.mdx b/docs/learn/tips-and-tricks/tips-and-tricks.mdx index be841ac9b..f26ae863b 100644 --- a/docs/learn/tips-and-tricks/tips-and-tricks.mdx +++ b/docs/learn/tips-and-tricks/tips-and-tricks.mdx @@ -1,7 +1,7 @@ --- title: Tips and Tricks sidebar_label: Tips and Tricks -sidebar_position: 6 +sidebar_position: 9 description: Cloud Posse's Tips and Tricks --- import Intro from '@site/src/components/Intro'; diff --git a/docs/modules/modules.mdx b/docs/modules/modules.mdx index b21fd3419..5f5da6d90 100644 --- a/docs/modules/modules.mdx +++ b/docs/modules/modules.mdx @@ -9,7 +9,7 @@ import Intro from '@site/src/components/Intro'; import DocCardList from '@theme/DocCardList'; - This is a collection of reusable Terraform Modules. In this library you'll find real-world examples of how we've implemented reusable Terraform Modules. + This is a collection of reusable Terraform Modules. In this library, you'll find real-world examples of how we've implemented reusable Terraform Modules. diff --git a/docs/quickstart/action-items.mdx b/docs/quickstart/action-items.mdx index 842a75151..7094eaab5 100644 --- a/docs/quickstart/action-items.mdx +++ b/docs/quickstart/action-items.mdx @@ -1,7 +1,7 @@ --- title: "Action Items" sidebar_label: "Action Items" -sidebar_position: 2 +sidebar_position: 3 --- import Intro from '@site/src/components/Intro'; import ActionCard from '@site/src/components/ActionCard'; diff --git a/docs/quickstart/faq.mdx b/docs/quickstart/faq.mdx index cef943b56..860c6e93c 100644 --- a/docs/quickstart/faq.mdx +++ b/docs/quickstart/faq.mdx @@ -1,7 +1,7 @@ --- title: FAQ sidebar_label: FAQ -sidebar_position: 10 +sidebar_position: 5 --- ### What is the difference between a Service Discovery Domain and a Vanity Domain? diff --git a/docs/quickstart/kickoff.mdx b/docs/quickstart/kickoff.mdx index b89f19cc6..8f4a6f983 100644 --- a/docs/quickstart/kickoff.mdx +++ b/docs/quickstart/kickoff.mdx @@ -1,7 +1,7 @@ --- title: "Kick Off with Cloud Posse" sidebar_label: "Kick Off" -sidebar_position: 1 +sidebar_position: 2 describe: Set project expectations for Jumpstarts with Cloud Posse --- import Link from '@docusaurus/Link' diff --git a/docs/quickstart/quickstart.mdx b/docs/quickstart/quickstart.mdx index 7e7253be1..0abf3f3e0 100644 --- a/docs/quickstart/quickstart.mdx +++ b/docs/quickstart/quickstart.mdx @@ -2,8 +2,9 @@ id: quickstart title: "Get a Quickstart" sidebar_label: "Get a Quickstart" -sidebar_position: 2 +sidebar_position: 1 sidebar_class_name: "hidden" +pagination_next: "quickstart/kickoff" --- import Intro from '@site/src/components/Intro'; import ActionCard from '@site/src/components/ActionCard'; diff --git a/docs/quickstart/support.mdx b/docs/quickstart/support.mdx index a732d4713..7de0923f3 100644 --- a/docs/quickstart/support.mdx +++ b/docs/quickstart/support.mdx @@ -1,7 +1,7 @@ --- title: "Support" sidebar_label: "Getting Support" -sidebar_position: 90 +sidebar_position: 4 description: Use Customer Workshops to ask questions and get support from Cloud Posse --- import Intro from '@site/src/components/Intro'; diff --git a/docs/reference/LICENSE.mdx b/docs/reference/LICENSE.mdx index 25ea4da50..78141ee16 100644 --- a/docs/reference/LICENSE.mdx +++ b/docs/reference/LICENSE.mdx @@ -1,13 +1,11 @@ --- title: "License" sidebar_label: "License" +sidebar_position: 900 slug: license description: "Documentation is licensed under the Creative Commons" tags: - license -- opl -- open publication license -sidebar_position: 900 --- import Intro from '@site/src/components/Intro'; import KeyPoints from '@site/src/components/KeyPoints'; diff --git a/docs/reference/reference.mdx b/docs/reference/reference.mdx index 339f30159..b69ab105f 100644 --- a/docs/reference/reference.mdx +++ b/docs/reference/reference.mdx @@ -1,10 +1,38 @@ --- id: reference -title: Introduction +title: Infrastructure as Code Library +sidebar_label: Library sidebar_position: 0 +sidebar_class_name: hidden --- - -## Reference +import DocCardList from '@theme/DocCardList'; Introduction to what this page is about + diff --git a/docs/resources/adrs/adopted/use-ssm-over-asm-for-infrastructure.mdx b/docs/resources/adrs/adopted/use-ssm-over-asm-for-infrastructure.mdx index d7834e7cc..24c0cab4a 100644 --- a/docs/resources/adrs/adopted/use-ssm-over-asm-for-infrastructure.mdx +++ b/docs/resources/adrs/adopted/use-ssm-over-asm-for-infrastructure.mdx @@ -83,7 +83,7 @@ After ASM was built, SSM was enhanced to provide similar capabilities, although [https://docs.aws.amazon.com/general/latest/gr/ssm.html](https://docs.aws.amazon.com/general/latest/gr/ssm.html) [https://aws.amazon.com/about-aws/whats-new/2019/04/aws_systems_manager_now_supports_use_of_parameter_store_at_higher_api_throughput/](https://aws.amazon.com/about-aws/whats-new/2019/04/aws_systems_manager_now_supports_use_of_parameter_store_at_higher_api_throughput/) -
+
### Other diff --git a/docs/resources/adrs/deprecated/use-folder-structure-for-compliance-components.mdx b/docs/resources/adrs/deprecated/use-folder-structure-for-compliance-components.mdx index d6a401c6f..466de3bd1 100644 --- a/docs/resources/adrs/deprecated/use-folder-structure-for-compliance-components.mdx +++ b/docs/resources/adrs/deprecated/use-folder-structure-for-compliance-components.mdx @@ -180,7 +180,7 @@ components: ### Option 2: Current Solution -
+
``` ### diff --git a/docs/resources/adrs/proposed/proposed-use-atmos-registry.mdx b/docs/resources/adrs/proposed/proposed-use-atmos-registry.mdx index 4999408f1..d568e0317 100644 --- a/docs/resources/adrs/proposed/proposed-use-atmos-registry.mdx +++ b/docs/resources/adrs/proposed/proposed-use-atmos-registry.mdx @@ -48,7 +48,7 @@ atmos component generate terraform/aurora-postgres \ -
+
1. It will download the component diff --git a/docs/resources/adrs/proposed/proposed-use-github-actions-with-atmos.mdx b/docs/resources/adrs/proposed/proposed-use-github-actions-with-atmos.mdx index 4c25c4529..ddda156d4 100644 --- a/docs/resources/adrs/proposed/proposed-use-github-actions-with-atmos.mdx +++ b/docs/resources/adrs/proposed/proposed-use-github-actions-with-atmos.mdx @@ -53,7 +53,7 @@ Smaller, bootstrappy startups don’t have the budget for Spacelift. There are t - Upon merge to main, trigger a GitHub `deployment` with approval step See [https://github.com/suzuki-shunsuke/tfcmt](https://github.com/suzuki-shunsuke/tfcmt) for inspiration -
+
- Include support for `terraform plan -destroy` for deleted stacks or components @@ -90,7 +90,7 @@ Smaller, bootstrappy startups don’t have the budget for Spacelift. There are t Checks UI. Each job is a component. Each step is an environment. -
+
``` name: "plan" diff --git a/docs/resources/legacy/_category_.json b/docs/resources/legacy/_category_.json deleted file mode 100644 index b89b23fac..000000000 --- a/docs/resources/legacy/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Legacy", - "position": 999, - "link": { - "type": "generated-index", - "description": "Legacy documentation yet to be sorted." - } -} diff --git a/docs/layers/identity/docs/aws-feature-requests-and-limitations.mdx b/docs/resources/legacy/aws-feature-requests-and-limitations.mdx similarity index 98% rename from docs/layers/identity/docs/aws-feature-requests-and-limitations.mdx rename to docs/resources/legacy/aws-feature-requests-and-limitations.mdx index 4a1328565..7a10933ad 100644 --- a/docs/layers/identity/docs/aws-feature-requests-and-limitations.mdx +++ b/docs/resources/legacy/aws-feature-requests-and-limitations.mdx @@ -34,7 +34,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.~~ -
+
### More flexible high-level CDK constructs @@ -64,7 +64,7 @@ Currently, AWS does not provide a generally available way to alert when limits a [https://github.com/awslabs/aws-limit-monitor](https://github.com/awslabs/aws-limit-monitor) -
+
### [Launched] EKS Managed Node Groups Custom Userdata support @@ -98,7 +98,7 @@ Use-case: [https://aws.amazon.com/about-aws/whats-new/2020/12/announcing-amazon-route-53-support-dnssec/](https://aws.amazon.com/about-aws/whats-new/2020/12/announcing-amazon-route-53-support-dnssec/) -
+
### NLB Health Checks Overwhelm Origins diff --git a/docs/resources/legacy/demo-applications.mdx b/docs/resources/legacy/demo-applications.mdx index 7345de4a1..978eb9a21 100644 --- a/docs/resources/legacy/demo-applications.mdx +++ b/docs/resources/legacy/demo-applications.mdx @@ -10,22 +10,22 @@ Here’s a list of fancy demo applications, predominantly for Kubernetes. 1. [https://github.com/GoogleCloudPlatform/microservices-demo](https://github.com/GoogleCloudPlatform/microservices-demo) (by Google) -
+
2. [https://github.com/microservices-demo/microservices-demo](https://github.com/microservices-demo/microservices-demo) (by Weaveworks) -
+
3. [https://github.com/dotnet-architecture/eShopOnContainers](https://github.com/dotnet-architecture/eShopOnContainers) (by Microsoft) -
+
4. [https://github.com/istio/istio/tree/master/samples/bookinfo](https://github.com/istio/istio/tree/master/samples/bookinfo) (by Istio)[https://github.com/kubernetes/examples](https://github.com/kubernetes/examples) -
+
5. [https://github.com/kubernetes/examples](https://github.com/kubernetes/examples) Guestbook - classic demo (by Kubernetes) -
+
diff --git a/docs/resources/legacy/design-decisions/archived-decisions/decide-on-status-page-requirements.mdx b/docs/resources/legacy/design-decisions/archived-decisions/decide-on-status-page-requirements.mdx index 90ae51759..54be7a413 100644 --- a/docs/resources/legacy/design-decisions/archived-decisions/decide-on-status-page-requirements.mdx +++ b/docs/resources/legacy/design-decisions/archived-decisions/decide-on-status-page-requirements.mdx @@ -22,6 +22,6 @@ Use [StatusPage.io](http://StatusPage.io) by Atlassian to integrate with OpsGeni - Should it pull in the availability of third-party dependencies? e.g. Twillio API -
+
diff --git a/docs/resources/legacy/fundamentals/geodesic.mdx b/docs/resources/legacy/fundamentals/geodesic.mdx index 94cabb251..3a8bc2fd3 100644 --- a/docs/resources/legacy/fundamentals/geodesic.mdx +++ b/docs/resources/legacy/fundamentals/geodesic.mdx @@ -31,8 +31,8 @@ An organization may choose to leverage all of these components or just the parts Geodesic is comprised of a large collection of open-source tools, most of them not created or maintained by Cloud Posse. (Most of them and many more can be installed individually using packages from our [`packages` repository](https://github.com/cloudposse/packages).) As such, **support for Macs with Apple chips (M1, M2, etc.) is fully not under Cloud Posse's control**, rather it -depends on each tool author updating each tool for the Apple chips, referred to as the `arm64` architecture. -**The Debian-based Geodesic is provided as a multi-architecture Docker image, supporting both Intel chips (`amd64`) and +depends on each tool author updating each tool for the Apple chips, referred to as the `arm64` architecture. +**The Debian-based Geodesic is provided as a multi-architecture Docker image, supporting both Intel chips (`amd64`) and Apple chips (`arm64`)**, but the (deprecated) Alpine-based Geodesic is only provided for Intel chips (`amd64`). The image built for `arm64` does not include a few tools that the maintainers have not yet updated for `linux/arm64`, but those tools are not widely used anymore, so your experience should be good on Apple silicon. (See the current @@ -79,11 +79,11 @@ Prior to this, all Docker images were based on Alpine only and simply tagged `VE ## Packages -
+
Central to `geodesic` is its rich support for the latest version of [the most popular packages](https://github.com/cloudposse/packages/tree/master/vendor) for DevOps. We maintain hundreds of packages that are graciously hosted by Cloud Smith. Our packages are updated nightly as soon as new releases are made available by vendors. As such, we strongly recommend version pinning packages installed via the `Dockerfile`. -Also unique about our packages is that for `kubectl` and `terraform` we distribute all major versions with `dpkg-alternative` support so they can be concurrently installed without the use of version managers. For example, to install the latest version of `kubectl` v1.28 (to match the version of the cluster it is controlling), you can install package `kubectl-1.28`. +Also unique about our packages is that for `kubectl` and `terraform` we distribute all major versions with `dpkg-alternative` support so they can be concurrently installed without the use of version managers. For example, to install the latest version of `kubectl` v1.28 (to match the version of the cluster it is controlling), you can install package `kubectl-1.28`. Package repository hosting is graciously provided by [cloudsmith](https://cloudsmith.io/). Cloudsmith is the only fully hosted, cloud-native, universal package management solution, that enables your organization to create, store and share packages in any format, to any place, with total confidence. We believe there’s a better way to manage software assets and packages, and they’re making it happen! @@ -95,7 +95,7 @@ Here’s a general filesystem layout for an infrastructure repository leveraging infrastructure/ # GitHub Repository ├── Dockerfile # Dockerfile uses `cloudposse/geodesic` as base Image ├── Makefile # Makefile to build custom Geodestic-based Docker image and install wrapper script for `geodesic` -├── README.md +├── README.md ├── components # Location for all re-usable component building blocks │ └── terraform/ # Location for all terraform (HCL) components │ └── foobar/ # Example `foobar` component @@ -106,7 +106,7 @@ infrastructure/ # GitHub Repository │ │ ├── baz/ # Submodule named `baz/` │ │ │ ├── context.tf # Submodules should use the same standard interface with `context.tf` │ │ │ ├── main.tf # Submodules should also follow HashiCorp best practices for module layout -│ │ │ ├── outputs.tf +│ │ │ ├── outputs.tf │ │ │ └── variables.tf # Submodules should define variables in `variables.tf` and not modify `context.tf` │ │ └── bar/ # Example of another submodule named `bar/` │ │ ├── context.tf @@ -155,13 +155,13 @@ infrastructure/ # GitHub Repository │ ├── account-map.yaml # Catalog entry for [account-map](/components/library/aws/account-map/) │ ├── account-settings.yaml # Catalog entry for [account-settings](/components/library/aws/account-settings/) │ ├── account.yaml # ... - │ ├── aws-team-roles.yaml - │ ├── aws-teams.yaml - │ ├── cloudtrail.yaml - │ ├── dns-delegated.yaml - │ ├── dns-primary.yaml - │ ├── ecr.yaml - │ ├── eks + │ ├── aws-team-roles.yaml + │ ├── aws-teams.yaml + │ ├── cloudtrail.yaml + │ ├── dns-delegated.yaml + │ ├── dns-primary.yaml + │ ├── ecr.yaml + │ ├── eks │ │ ├── alb-controller.yaml │ │ ├── cert-manager.yaml │ │ ├── eks.yaml diff --git a/docs/resources/legacy/fundamentals/terraform.mdx b/docs/resources/legacy/fundamentals/terraform.mdx index d142361bf..9e48d6406 100644 --- a/docs/resources/legacy/fundamentals/terraform.mdx +++ b/docs/resources/legacy/fundamentals/terraform.mdx @@ -9,7 +9,7 @@ import ReactPlayer from 'react-player' # Terraform -For the most part, we assume users have a solid grasp of `terraform`. Cloud Posse has adopted a number of conventions for how we work with `terraform` that we document here. Review [our opinionated public “best practices” as it relates to terraform](/reference/best-practices/terraform-best-practices/). +For the most part, we assume users have a solid grasp of `terraform`. Cloud Posse has adopted a number of conventions for how we work with `terraform` that we document here. Review [our opinionated public “best practices” as it relates to terraform](/best-practices/terraform). We use [Atmos](/fundamentals/atmos) together with [Stacks](/fundamentals/stacks) to call [Components](/components) that provision infrastructure with `terraform`. diff --git a/docs/resources/legacy/how-to-integrate-statuspage.mdx b/docs/resources/legacy/how-to-integrate-statuspage.mdx index 6007dd213..998fbba87 100644 --- a/docs/resources/legacy/how-to-integrate-statuspage.mdx +++ b/docs/resources/legacy/how-to-integrate-statuspage.mdx @@ -24,7 +24,7 @@ In order for these Datadog alerts to affect Statuspage components, a `cmp_[Compo For Datadog Synthetics, the component status should be either `partial_outage` or `major_outage`. It’s safer to choose the former when in doubt, because usually these components are part of larger system, and hence their outage is only a partial outage. The Major Outage status in Statuspage can be set for a component by an operator manually, at their discretion, whenever it is necessary to convey a major service disruption. -
+
For example, within `datadog-synthetics/catalog/example-api.yaml`: @@ -44,22 +44,22 @@ example-api: ### Integrate OpsGenie with Statuspage Follow the official [documentation for integrating OpsGenie and Statuspage](https://support.atlassian.com/opsgenie/docs/integrate-opsgenie-with-statuspage/). This enables bi-directional communication between OpsGenie and Statuspage. Once the two are integrated, configure the Statuspage Integration as follows: -
+
This step is done via “ClickOps”, because there is no Terraform resource for managing the Statuspage integration. The aforementioned settings allow for the Statuspage incident to be updated when the alert is modified on the OpsGenie side. -
+
Once the alert is closed in OpsGenie, the corresponding event is resolved in Statuspage. -
+
### Create OpsGenie Integration Actions for Datadog Synthetics Alerts In order for the Statuspage integration to function correctly, Integration Actions must be in place to clean up the alert message and description, and also prevent Datadog from inserting a large number of tags (in particular, since we are ) into the alert that will cause the tag count limit to be exceeded and preventing the Statuspage integration -
+
This should not be manually configured via “ClickOps”, and is instead configured using the `opsgenie-team` component (`integration` submodule). diff --git a/docs/resources/legacy/howto/_category_.json b/docs/resources/legacy/howto/_category_.json deleted file mode 100644 index becb6a8bd..000000000 --- a/docs/resources/legacy/howto/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "How-To", - "position": 40, - "link": { - "type": "generated-index", - "description": "Guides on how to solve specific problems with SweetOps via a series of easy to follow steps." - } -} diff --git a/docs/resources/legacy/intro.mdx b/docs/resources/legacy/intro.mdx index b7fc46543..6c4384685 100644 --- a/docs/resources/legacy/intro.mdx +++ b/docs/resources/legacy/intro.mdx @@ -48,13 +48,13 @@ Helm is central to how we deploy all services on kubernetes. ## Terraform -Study up on our [Best Practices](/reference/best-practices/terraform-best-practices.md) for working with terraform. Get started quickly provisioning infrastructure by referencing our [terraform-aws-components](https://github.com/cloudposse/terraform-aws-components). +Study up on our [Best Practices](/best-practices/terraform) for working with terraform. Get started quickly provisioning infrastructure by referencing our [terraform-aws-components](https://github.com/cloudposse/terraform-aws-components). ### Terraform Modules [We provide a staggering number of Terraform modules in our GitHub](https://github.com/cloudposse?q=&type=&language=hcl). This number is growing every week and we're also [accepting module contributions](/our-github.md#contributing). -Before writing your own modules, review our [Best Practices](/reference/best-practices/terraform-best-practices.md) for working with Terraform modules. +Before writing your own modules, review our [Best Practices](/best-practices/terraform) for working with Terraform modules. ## Contributing Back @@ -72,6 +72,6 @@ File issues anywhere you find the documentation lacking by going to our [docs re Join our [Slack Community](https://cloudposse.com/slack/) and speak directly with the maintainers. -We provide "white glove" DevOps support. [Get in touch](/contact-us.md) with us today! +We provide "white glove" DevOps support. [Get in touch](/community/contact-us) with us today! [Schedule Time](https://calendly.com/cloudposse/) with us. diff --git a/docs/resources/legacy/lens.mdx b/docs/resources/legacy/lens.mdx index 4933575cd..e73b89c21 100644 --- a/docs/resources/legacy/lens.mdx +++ b/docs/resources/legacy/lens.mdx @@ -21,7 +21,7 @@ Once Lens is downloaded, it needs a `kubeconfig` file to authenticate with a ser The easiest way to access this cluster from Lens is to copy the `kubeconfig` to the current system user's `~/.kubeconfig` folder which is represented as `/localhost/.kubeconfig` inside of the Geodesic shell. -#### Example +#### Example ``` set-cluster platform-use2-dev @@ -40,16 +40,16 @@ Example: ### Importing `kubeconfig` On the Catalog view, click the `+` in the bottom corner and select the config file imported in the previous step. -
+
The configs can also be synced by hovering over the `+` button and clicking “Sync kubeconfig(s)” button. -
+
### Connecting to a Cluster Click cluster within the list on the specific cluster. -
+
:::note Click the pin icon to place the cluster in the sidebar. @@ -57,8 +57,8 @@ Click the pin icon to place the cluster in the sidebar. ::: Once the cluster connects, the following screen will be available to use. -
+
-
+
diff --git a/docs/resources/legacy/spotinst/how-to-tune-spotinst-parameters-for-eks.mdx b/docs/resources/legacy/spotinst/how-to-tune-spotinst-parameters-for-eks.mdx index 6f032229d..a4329cafb 100644 --- a/docs/resources/legacy/spotinst/how-to-tune-spotinst-parameters-for-eks.mdx +++ b/docs/resources/legacy/spotinst/how-to-tune-spotinst-parameters-for-eks.mdx @@ -8,7 +8,7 @@ custom_edit_url: https://github.com/cloudposse/refarch-scaffold/tree/main/docs/d # How to Tune SpotInst Parameters for EKS ## Problem -
+
SpotInst (SaaS) replaces the need to deploy the [standard kubernetes cluster auto-scaler](https://github.com/kubernetes/autoscaler/tree/master/cluster-autoscaler), so the mechanisms of tuning the scaling parameters are different than out-of-the-box EKS clusters. The autoscaling capability is handled by the `ocean-controller` together with the Spot platform, and not by Auto Scale Groups, so there’s no ASG parameters that we can toggle. diff --git a/docs/resources/legacy/spotinst/spotinst.mdx b/docs/resources/legacy/spotinst/spotinst.mdx index a63b1fbb9..5531f225c 100644 --- a/docs/resources/legacy/spotinst/spotinst.mdx +++ b/docs/resources/legacy/spotinst/spotinst.mdx @@ -18,7 +18,7 @@ Cost management on AWS is tricky. There are reserved instances, AWS savings plan Learn more about the differences between[https://spot.io/blog/aws-spot-instances-and-diy/](https://spot.io/blog/aws-spot-instances-and-diy/) . ## Solution -
+
:::tip Use the fully managed solution for [http://spot.io](http://spot.io) of EKS clusters (and more) @@ -66,7 +66,7 @@ No, this is entirely optional. We recommend using it though because it’s the e ### Can we trust Spot.io? -
+
While every company should perform its own vendor evaluation and due diligence, it’s worth noting that [Spot.io](http://Spot.io) was acquired by NetApp. @@ -82,7 +82,7 @@ Our recommendation is to invite individual users. But if you want, a shared acco Spot instances are not covered by [AWS Savings Plans](https://aws.amazon.com/savingsplans/faq/). That said, they are not mutually exclusive, and both provide savings and benefits. -
+
Learn more [https://docs.aws.amazon.com/savingsplans/latest/userguide/what-is-savings-plans.html](https://docs.aws.amazon.com/savingsplans/latest/userguide/what-is-savings-plans.html) @@ -96,7 +96,7 @@ Spot Instances on the other hand require zero upfront commitments and provide al ### How reliable are Spot Instances? -
+
AWS provides extremely short notice of Spot Instance interruption. **A warning that is issued two minutes before Amazon EC2 stops or terminates your Spot Instance**. diff --git a/docs/resources/legacy/tools.mdx b/docs/resources/legacy/tools.mdx index f0b49ebca..f1c379e90 100644 --- a/docs/resources/legacy/tools.mdx +++ b/docs/resources/legacy/tools.mdx @@ -194,8 +194,8 @@ Use `unset` to delete each of the above variables from your environment and ensu The `build-harness` is a collection of [Makefiles](/reference/tools.mdx#make) to facilitate building stuff. It supports Golang projects, Dockerfiles, Helm charts, and much more. | | | -|:-------------|:---------------------------------------------------------------------------------------------------------------------------------------| -| GitHub Repo | https://github.com/cloudposse/build-harness/ | +| :----------- | :------------------------------------------------------------------------------------------------------------------------------------- | +| GitHub Repo | https://github.com/cloudposse/build-harness/ | | Build Status | [![Build Status](https://travis-ci.org/cloudposse/build-harness.svg)](https://travis-ci.org/cloudposse/build-harness) | | Release | [![Release](https://img.shields.io/github/release/cloudposse/build-harness.svg)](https://github.com/cloudposse/build-harness/releases) | @@ -226,7 +226,7 @@ The `/` in target names is interchangeable with the `:` in target names We leverage the `build-harness` in nearly every project on our [GitHub](/our-github.md). | Example Repo | Usage | -|:------------------------------------------------------------------------------|:---------------------------------------------------------------------------| +| :---------------------------------------------------------------------------- | :------------------------------------------------------------------------- | | [`charts`](https://github.com/cloudposse/charts/) | A collection of Helm Charts that leverages `docker/%` and `helm/%` targets | | [`terraform-null-label`](https://github.com/cloudposse/terraform-null-label/) | A terraform module that leverages `terraform/%` targets | @@ -248,8 +248,8 @@ For a complete description, check out the [official documentation](https://githu ![Geodesic Logo](/assets/638d917-geodesic-small.png) | | | -|:-------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------| -| GitHub Repo | https://github.com/cloudposse/geodesic | +| :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| GitHub Repo | https://github.com/cloudposse/geodesic | | Release | [![Release](https://img.shields.io/github/release/cloudposse/geodesic.svg)](https://github.com/cloudposse/geodesic/releases) | | Build Status | [![Build Status](https://github.com/cloudposse/geodesic/workflows/docker/badge.svg)](https://github.com/cloudposse/geodesic/actions?query=workflow%3Adocker) | @@ -268,7 +268,7 @@ At its core, Geodesic is a DevOps toolkit Linux Distro distributed via Docker fo ### Technologies | Tool | Purpose | -|:---------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------| +| :------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------- | | [`terraform`](https://github.com/hashicorp/terraform/) | for provisioning miscellaneous resources on pretty much any cloud | | [`aws-cli`](https://github.com/aws/aws-cli/) | for interacting directly with the AWS APIs (E.g. s3, ec2, rds) | | [`helm`](https://github.com/kubernetes/helm/) | for installing packages like nginx-ingress or datadog agent on the Kubernetes cluster | @@ -925,9 +925,9 @@ We use `terraform` as one of our most central tools for automating infrastructur Learn more: -1. [Our Terraform Best Practices](/reference/best-practices/terraform-best-practices.md) +1. [Our Terraform Best Practices](/best-practices/terraform) 1. [Our Terraform Modules](https://github.com/cloudposse?q=terraform-) -1. [Our Terraform Tips & Tricks](/reference/best-practices/terraform-tips-tricks.md) +1. [Our Terraform Tips & Tricks](/learn/tips-and-tricks/terraform)

diff --git a/docs/layers/identity/docs/aws-business-roles.mdx b/docs/support/aws-support.mdx similarity index 61% rename from docs/layers/identity/docs/aws-business-roles.mdx rename to docs/support/aws-support.mdx index 66f77de0e..f8e754aa7 100644 --- a/docs/layers/identity/docs/aws-business-roles.mdx +++ b/docs/support/aws-support.mdx @@ -1,13 +1,19 @@ --- -title: Key AWS Business Roles and Titles -sidebar_label: AWS Business Roles +title: Getting Support from AWS +sidebar_label: AWS Support +description: "How to get help from AWS when you need it" --- import Intro from '@site/src/components/Intro'; +import Note from '@site/src/components/Note'; -This document provides an overview of the key AWS business roles and titles that you may encounter when working with AWS. Understanding these roles can help you navigate the AWS organization and get the most out of your relationship with AWS. + There are many ways to get support from AWS, but navigating their organization can be daunting. Understanding these various roles can help you effectively navigate the AWS structure and get the most out of your relationship with AWS. + + AWS will not be able to provide support for the Cloud Posse reference architecture. If you have any questions or need support, please reach out to Cloud Posse directly. + + ### Account Manager The Account Manager is part of the AWS Sales group and their main focus is on increasing your AWS consumption, but in a good way! 🙂 Account Managers are very interested in seeing happy AWS customers and knowing at a high level as much as possible about what you want to achieve by running on AWS. Then they lookout for how they can help out on their end. Account Managers will work with APN Partners like Cloud Posse to achieve customer business objectives. @@ -26,22 +32,6 @@ While we’ve never had a customer replace their TAM, in the event you are ever AWS assigns every account a Solutions Architect. Depending on your support agreement with AWS, the SA may even be able to join our regular Design Decision calls. Typically, we see this more often with our customers who have an Enterprise Support agreement. Looping in an SA is a great way to keep AWS informed on your technology roadmap. The SAs frequently bring deep industry knowledge of what other companies in your technology sector are doing (E.g. Healthcare or Financial Services), which is helpful for validation. -### Partner Development Manager (PDM) - -The PDMs are those who Cloud Posse works within the AWS Partner Network organization (APN). It’s a dedicated person from within the AWS organization that provides us assistance across all of the partnership aspects and is our biggest AWS Advocate. Our PDM will regularly connect us with relevant teams inside of AWS, as well as provide us guidance on how to navigate the complex AWS organization. We talk regularly with our PDM he provides valuable feedback and tactical advice on how to leverage the partnership with AWS to better serve our customers. As is common practice, we may keep them informed of our progress with customers and occasionally copy them on emails sent to the AWS team, so they can help us all out. The PDM works with a technical counterpart — Partner Solution Architect. - -### Partner Management Solution Architect - -The PMSA will help to review infrastructure. Additionally, “Pricing assistance” can be requested. The PMSA is typically the contact who can help customers to calculate and assess upcoming MRR projections. - -### Partner Solution Architect (PSA) - -The PSA is our own AWS Solutions Architect that we can lean on anytime for architectural advice. As necessary, we can also loop them in on calls or emails. - -### Partner Success Manager (PSM) - -Responsible for ensuring partners are successful within a customer opportunity. - ### Product Teams (aka “Service Teams”) AWS has countless services and each one is managed by a Product Team. As necessary, as your AWS Partner we can reach out to teams so that you can learn about upcoming features, make feature requests, and even participate in betas of early features. Customers under an NDA with AWS will also be able to learn about upcoming features not yet announced. This can save your company the cost of implementing workarounds for features that are already planned to be released. diff --git a/docs/support/customer-workshops.mdx b/docs/support/customer-workshops.mdx new file mode 100644 index 000000000..93dd38891 --- /dev/null +++ b/docs/support/customer-workshops.mdx @@ -0,0 +1,15 @@ +--- +title: Customer Workshops +sidebar_label: Customer Workshops +sidebar_position: 2 +description: Get live support from Cloud Posse in Customer Workshops +--- +import Intro from '@site/src/components/Intro'; + + +Customer Workshops are 30-minute calls held twice a week and a place where you can join us to ask any questions. We’ll participate in pairing sessions, help debug any issues you face, or discuss any architectural questions that come up. + + +:::tip +Customers of our [Jumpstart](/jumpstart) or [Quickstarts](/quickstarts) have direct access to Cloud Posse through weekly customer workshops conducted via Zoom. Additionally, if your company is a GitHub sponsor of Cloud Posse's open source at the _Enterprise tier_, you are invited to attend! +::: diff --git a/docs/support/github-discussions.mdx b/docs/support/github-discussions.mdx new file mode 100644 index 000000000..efc258a9a --- /dev/null +++ b/docs/support/github-discussions.mdx @@ -0,0 +1,17 @@ +--- +title: GitHub Discussions +sidebar_label: GitHub Discussions +sidebar_position: 1 +description: Ask Questions in GitHub Discussions +--- +import Intro from '@site/src/components/Intro'; +import Note from '@site/src/components/Note'; +import PrimaryCTA from '@site/src/components/PrimaryCTA'; + + + GitHub Discussions are an excellent way to get support directly from Cloud Posse and our community. + + +We prioritize questions from our [Jumpstart](/jumpstart) and [Quickstart](quickstart) companies, but anyone is free to ask questions, and we’ll do our best to respond. + +Open GitHub Discussions diff --git a/docs/support/support.mdx b/docs/support/support.mdx index 844429f0f..2802ccac6 100644 --- a/docs/support/support.mdx +++ b/docs/support/support.mdx @@ -4,7 +4,10 @@ sidebar_label: Get Support sidebar_class_name: hidden --- import Intro from '@site/src/components/Intro'; +import DocCardList from '@theme/DocCardList'; We provide a variety of support options to help you get the most out of our Reference Architecture. + + diff --git a/docs/tags.yml b/docs/tags.yml new file mode 100644 index 000000000..dce474716 --- /dev/null +++ b/docs/tags.yml @@ -0,0 +1,382 @@ +acm: + description: AWS Certificate Manager. + label: ACM + +agreement: + description: Agreements and policies. + label: Agreement + +ami: + description: Amazon Machine Image. + label: AMI + +argocd: + description: Argo CD tool. + label: Argo CD + +atmos: + description: Atmos Framework + label: Atmos + +aws: + label: Amazon Web Services (AWS) + +aws-cli: + description: AWS Command Line Interface. + label: AWS CLI + +aws-vault: + description: AWS Vault tool. + label: AWS Vault + +az: + description: Availability Zone. + label: Availability Zone + +bastion: + description: Bastion hosts. + label: Bastion + +best-practices: + description: Best practices for development and deployment. + label: Best Practices + +beyondcorp: + description: BeyondCorp security model. + label: BeyondCorp + +build-harness: + description: Build harness tools and scripts. + label: Build Harness + +business-logic: + description: Business logic topics. + label: Business Logic + +cdn: + description: Content Delivery Network. + label: CDN + +chamber: + description: Chamber secrets management. + label: Chamber + +change-control: + description: Change control processes. + label: Change Control + +change-management: + description: Change management practices. + label: Change Management + +chart-registry: + description: Helm chart registries. + label: Chart Registry + +chartmuseum: + description: ChartMuseum tool. + label: ChartMuseum + +circleci: + description: CircleCI platform. + label: CircleCI + +cli: + description: Command Line Interface. + label: CLI + +clickops: + description: ClickOps practices. + label: ClickOps + +cloud-native: + description: Cloud native applications and practices. + label: Cloud Native + +cloudfront: + description: AWS CloudFront service. + label: CloudFront + +code: + description: Code and coding practices. + label: Code + +code-style: + description: Code style guidelines. + label: Code Style + +codebuild: + description: AWS CodeBuild service. + label: CodeBuild + +codefresh: + description: Codefresh CI/CD platform. + label: Codefresh + +codepipeline: + description: AWS CodePipeline service. + label: CodePipeline + +community: + description: Community related topics. + label: Community + +compliance: + description: Compliance topics. + label: Compliance + +component: + description: Atmos Component + label: Component + +concept: + description: Conceptual topics and explanations. + label: Concept + +configuration: + description: Configuration management. + label: Configuration + +database: + description: Database topics. + label: Database + +datadog: + description: Datadog monitoring platform. + label: Datadog + +developer: + description: Developer-related topics. + label: Developer + +development: + description: Development practices and methodologies. + label: Development + +docker: + description: Docker related topics. + label: Docker + +ec2: + description: Amazon EC2 service. + label: EC2 + +ecs: + description: Amazon ECS service. + label: ECS + +editorconfig: + description: EditorConfig configuration files. + label: .EditorConfig + +formatting: + description: Code formatting practices. + label: Formatting + +geodesic: + description: Geodesic framework. + label: Geodesic + +git: + description: Git version control system. + label: Git + +gnumakefile: + description: GNU Makefile topics. + label: GNUMakefile + +grafana: + description: Grafana monitoring platform. + label: Grafana + +helm: + description: Helm package manager. + label: Helm + +helm-chart: + description: Helm chart related topics. + label: Helm Chart + +helmfile: + description: Helmfile topics. + label: Helmfile + +heroku: + description: Heroku platform. + label: Heroku + +iac: + description: Infrastructure as Code. + label: IaC + +iam: + description: Identity and Access Management. + label: IAM + +iap: + description: Identity Aware Proxy. + label: IAP + +installer: + description: Installation guides and topics. + label: Installer + +jenkins: + description: Jenkins automation server. + label: Jenkins + +jumphost: + description: Jumphosts. + label: JumpHost + +k8s: + description: Kubernetes related topics. + label: Kubernetes + +kms: + description: Key Management Service. + label: KMS + +kops: + description: Kubernetes Operations tool. + label: Kops + +kubectl: + description: Kubernetes command line tool. + label: Kubectl + +kubernetes: + description: Kubernetes related topics. + label: Kubernetes + +layer: + description: Architecture Layer + label: Layer + +layer/network-and-dns: + description: Network and DNS Layer + label: Network and DNS + +license: + description: Licensing information. + label: License + +loki: + description: Loki logging platform. + label: Loki + +make: + description: Make and Makefile related topics. + label: Make + +makefile: + description: Makefile related topics. + label: Makefile + +module: + description: Terraform Module + label: Terraform Module + +multi-az: + description: Multi Availability Zones. + label: Multi AZ + +open-publication-license: + description: Open Publication License. + label: Open Publication License + +open-source: + description: Open-source projects and contributions. + label: Open Source + +opl: + description: Open Publication License. + label: OPL + +password-management: + description: Password management tools and practices. + label: Password Management + +pki: + description: Public Key Infrastructure. + label: PKI + +prometheus: + description: Prometheus monitoring platform. + label: Prometheus + +s3: + description: Amazon S3 related topics. + label: S3 + +secrets: + description: Secrets management. + label: Secrets + +security: + description: Security related topics. + label: Security + +semver: + description: Semantic Versioning. + label: SemVer + +spacelift: + description: Spacelift platform. + label: Spacelift + +ssh: + description: Secure Shell. + label: SSH + +ssm: + description: Systems Manager. + label: SSM + +startups: + description: Topics related to startups. + label: Startups + +task-runner: + description: Task runners and automation tools. + label: Task Runner + +terraform: + description: Terraform related topics. + label: Terraform + +tips-and-tricks: + description: Tips and tricks for various tools and practices. + label: Tips and Tricks + +tls: + description: TLS (Transport Layer Security). + label: TLS + +tool: + description: Tools and utilities. + label: Tool + +tools: + description: Tools and utilities. + label: Tools + +travisci: + description: Travis CI platform. + label: Travis CI + +tutorial: + description: Tutorials, How-Tos, and Guides. + label: Tutorial + +twelve-factor: + description: 12-factor application methodology. + label: 12 Factor + +virtual-machine-image: + description: Virtual Machine Image topics. + label: Virtual Machine Image + +yaml: + description: YAML configuration language. + label: YAML diff --git a/docusaurus.config.js b/docusaurus.config.js index 2ce02fe42..d2e98cd3b 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -12,6 +12,25 @@ const customCssFiles = fs.readdirSync(cssDirectory) .filter(file => file.endsWith('.css')) .map(file => require.resolve(path.join(cssDirectory, file))); +//https://github.com/saucelabs/elemental-next/blob/b1a325631243a13a4f3beee58a295b7b36f6574d/frontend/docusaurus.config.js#L105 +function metadataPlugin(context, options) { + return { + name: 'metadata', + async allContentLoaded({actions, allContent}) { + const {setGlobalData} = actions; + let docs = [] + allContent['docusaurus-plugin-content-docs'] + .default + .loadedVersions[0] + .docs + .filter(doc => doc.id !== undefined) + .map((doc) => docs.push(doc)); + //console.log(JSON.stringify(allContent['docusaurus-plugin-content-docs'], 2, 2, null)); + //console.log(tempFrontMatter); + setGlobalData({aggregateMetadata: docs}); + } + } +} /** @type {import('@docusaurus/types').Config} */ const config = { @@ -43,6 +62,34 @@ const config = { [ 'docusaurus-plugin-image-zoom', {}, ], + [ + '@docusaurus/plugin-ideal-image', + { + quality: 90, + max: 1030, // max resized image's size. + min: 640, // min resized image's size. if original is lower, use that size. + steps: 2, // the max number of images generated between min and max (inclusive) + disableInDev: false, + } + ], + [ + 'custom-loaders', {} + ], + metadataPlugin, + [ + "posthog-docusaurus", + { + apiKey: "phc_G3idXOACKt4vIzgRu2FVP8ORO1D2VlkeEwX9mE2jDvT", + appUrl: "https://us.i.posthog.com", + enableInDevelopment: false, // optional + }, + ], + [ + 'docusaurus-plugin-sentry', + { + DSN: 'b022344b0e7cc96f803033fff3b377ee@o56155.ingest.us.sentry.io/4507472203087872', + }, + ] ], presets: [ @@ -58,7 +105,9 @@ const config = { }, exclude: ['README.md'], showLastUpdateTime: true, - showLastUpdateAuthor: true + showLastUpdateAuthor: true, + onInlineTags: 'warn', + tags: 'tags.yml' }, theme: { customCss: customCssFiles, @@ -178,16 +227,12 @@ const config = { title: 'Community', items: [ { - label: 'Github Discussions', - href: 'https://ask.sweetops.com/', - }, - { - label: 'Community', - href: 'https://sweetops.com/', + label: 'GitHub Discussions', + href: 'https://github.com/orgs/cloudposse/discussions', }, { - label: 'Slack', - href: 'https://slack.sweetops.com/', + label: 'Slack Community', + to: '/community/slack', }, { label: 'Slack Archives', @@ -195,7 +240,7 @@ const config = { }, { label: 'Office Hours', - href: 'https://cloudposse.com/office-hours/', + to: '/community/office-hours/', }, ], }, { @@ -203,7 +248,7 @@ const config = { items: [ { label: 'Support', - href: 'https://cloudposse.com/accelerate', + to: '/support', }, { label: 'Our GitHub', @@ -211,7 +256,7 @@ const config = { }, { label: 'Contact Us', - to: '/contact-us/', + to: '/community/contact-us/', }], }], logo: { diff --git a/examples/snippets/.github/workflows/atmos-terraform-apply-matrix.yaml b/examples/snippets/.github/workflows/atmos-terraform-apply-matrix.yaml new file mode 100644 index 000000000..4f2e970e9 --- /dev/null +++ b/examples/snippets/.github/workflows/atmos-terraform-apply-matrix.yaml @@ -0,0 +1 @@ +PLACEHOLDER diff --git a/examples/snippets/.github/workflows/atmos-terraform-apply.yaml b/examples/snippets/.github/workflows/atmos-terraform-apply.yaml new file mode 100644 index 000000000..4f2e970e9 --- /dev/null +++ b/examples/snippets/.github/workflows/atmos-terraform-apply.yaml @@ -0,0 +1 @@ +PLACEHOLDER diff --git a/examples/snippets/.github/workflows/atmos-terraform-dispatch.yaml b/examples/snippets/.github/workflows/atmos-terraform-dispatch.yaml new file mode 100644 index 000000000..4f2e970e9 --- /dev/null +++ b/examples/snippets/.github/workflows/atmos-terraform-dispatch.yaml @@ -0,0 +1 @@ +PLACEHOLDER diff --git a/examples/snippets/.github/workflows/atmos-terraform-drift-detection.yaml b/examples/snippets/.github/workflows/atmos-terraform-drift-detection.yaml new file mode 100644 index 000000000..4f2e970e9 --- /dev/null +++ b/examples/snippets/.github/workflows/atmos-terraform-drift-detection.yaml @@ -0,0 +1 @@ +PLACEHOLDER diff --git a/examples/snippets/.github/workflows/atmos-terraform-drift-remediation.yaml b/examples/snippets/.github/workflows/atmos-terraform-drift-remediation.yaml new file mode 100644 index 000000000..4f2e970e9 --- /dev/null +++ b/examples/snippets/.github/workflows/atmos-terraform-drift-remediation.yaml @@ -0,0 +1 @@ +PLACEHOLDER diff --git a/examples/snippets/.github/workflows/atmos-terraform-plan-matrix.yaml b/examples/snippets/.github/workflows/atmos-terraform-plan-matrix.yaml new file mode 100644 index 000000000..4f2e970e9 --- /dev/null +++ b/examples/snippets/.github/workflows/atmos-terraform-plan-matrix.yaml @@ -0,0 +1 @@ +PLACEHOLDER diff --git a/examples/snippets/.github/workflows/atmos-terraform-plan.yaml b/examples/snippets/.github/workflows/atmos-terraform-plan.yaml new file mode 100644 index 000000000..4f2e970e9 --- /dev/null +++ b/examples/snippets/.github/workflows/atmos-terraform-plan.yaml @@ -0,0 +1 @@ +PLACEHOLDER diff --git a/examples/snippets/stacks/orgs/acme/plat/spacelift.yaml b/examples/snippets/stacks/orgs/acme/plat/spacelift.yaml new file mode 100644 index 000000000..4f2e970e9 --- /dev/null +++ b/examples/snippets/stacks/orgs/acme/plat/spacelift.yaml @@ -0,0 +1 @@ +PLACEHOLDER diff --git a/examples/snippets/stacks/orgs/acme/spacelift.yaml b/examples/snippets/stacks/orgs/acme/spacelift.yaml new file mode 100644 index 000000000..4f2e970e9 --- /dev/null +++ b/examples/snippets/stacks/orgs/acme/spacelift.yaml @@ -0,0 +1 @@ +PLACEHOLDER diff --git a/package-lock.json b/package-lock.json index cf56749ca..c095388b0 100644 --- a/package-lock.json +++ b/package-lock.json @@ -17,6 +17,7 @@ "@docusaurus/plugin-content-docs": "^3.4.0", "@docusaurus/plugin-debug": "^3.4.0", "@docusaurus/plugin-google-tag-manager": "^3.4.0", + "@docusaurus/plugin-ideal-image": "^3.4.0", "@docusaurus/preset-classic": "^3.4.0", "@docusaurus/theme-mermaid": "^3.4.0", "@excalidraw/excalidraw": "^0.17.6", @@ -2463,6 +2464,22 @@ "node": ">=18.0" } }, + "node_modules/@docusaurus/lqip-loader": { + "version": "3.4.0", + "resolved": "https://registry.npmjs.org/@docusaurus/lqip-loader/-/lqip-loader-3.4.0.tgz", + "integrity": "sha512-F//Gjqcz925zLL1l3Y3XOtQvn927GBIr9ZouvzWF4jHNKuuHBqzOPSADF5O/cT3Vq1ucPWooyhPBxYcvSGF4SA==", + "license": "MIT", + "dependencies": { + "@docusaurus/logger": "3.4.0", + "file-loader": "^6.2.0", + "lodash": "^4.17.21", + "sharp": "^0.32.3", + "tslib": "^2.6.0" + }, + "engines": { + "node": ">=18.0" + } + }, "node_modules/@docusaurus/mdx-loader": { "version": "3.4.0", "resolved": "https://registry.npmjs.org/@docusaurus/mdx-loader/-/mdx-loader-3.4.0.tgz", @@ -2710,6 +2727,38 @@ "react-dom": "^18.0.0" } }, + "node_modules/@docusaurus/plugin-ideal-image": { + "version": "3.4.0", + "resolved": "https://registry.npmjs.org/@docusaurus/plugin-ideal-image/-/plugin-ideal-image-3.4.0.tgz", + "integrity": "sha512-s8N/PRiv1R66UY+WX/2E9a+GjkRooXVcf0VJNEYA3yZ6c24Path15ivjmdMtKaSo/6OXYbejGlA4DJZ5TPLkCQ==", + "license": "MIT", + "dependencies": { + "@docusaurus/core": "3.4.0", + "@docusaurus/lqip-loader": "3.4.0", + "@docusaurus/responsive-loader": "^1.7.0", + "@docusaurus/theme-translations": "3.4.0", + "@docusaurus/types": "3.4.0", + "@docusaurus/utils-validation": "3.4.0", + "@slorber/react-ideal-image": "^0.0.12", + "react-waypoint": "^10.3.0", + "sharp": "^0.32.3", + "tslib": "^2.6.0", + "webpack": "^5.88.1" + }, + "engines": { + "node": ">=18.0" + }, + "peerDependencies": { + "jimp": "*", + "react": "^18.0.0", + "react-dom": "^18.0.0" + }, + "peerDependenciesMeta": { + "jimp": { + "optional": true + } + } + }, "node_modules/@docusaurus/plugin-sitemap": { "version": "3.4.0", "resolved": "https://registry.npmjs.org/@docusaurus/plugin-sitemap/-/plugin-sitemap-3.4.0.tgz", @@ -2762,6 +2811,30 @@ "react-dom": "^18.0.0" } }, + "node_modules/@docusaurus/responsive-loader": { + "version": "1.7.0", + "resolved": "https://registry.npmjs.org/@docusaurus/responsive-loader/-/responsive-loader-1.7.0.tgz", + "integrity": "sha512-N0cWuVqTRXRvkBxeMQcy/OF2l7GN8rmni5EzR3HpwR+iU2ckYPnziceojcxvvxQ5NqZg1QfEW0tycQgHp+e+Nw==", + "license": "BSD-3-Clause", + "dependencies": { + "loader-utils": "^2.0.0" + }, + "engines": { + "node": ">=12" + }, + "peerDependencies": { + "jimp": "*", + "sharp": "*" + }, + "peerDependenciesMeta": { + "jimp": { + "optional": true + }, + "sharp": { + "optional": true + } + } + }, "node_modules/@docusaurus/theme-classic": { "version": "3.4.0", "resolved": "https://registry.npmjs.org/@docusaurus/theme-classic/-/theme-classic-3.4.0.tgz", @@ -3358,6 +3431,21 @@ "url": "https://github.com/sindresorhus/is?sponsor=1" } }, + "node_modules/@slorber/react-ideal-image": { + "version": "0.0.12", + "resolved": "https://registry.npmjs.org/@slorber/react-ideal-image/-/react-ideal-image-0.0.12.tgz", + "integrity": "sha512-u8KiDTEkMA7/KAeA5ywg/P7YG4zuKhWtswfVZDH8R8HXgQsFcHIYU2WaQnGuK/Du7Wdj90I+SdFmajSGFRvoKA==", + "license": "MIT", + "engines": { + "node": ">= 8.9.0", + "npm": "> 3" + }, + "peerDependencies": { + "prop-types": ">=15", + "react": ">=0.14.x", + "react-waypoint": ">=9.0.2" + } + }, "node_modules/@slorber/remark-comment": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/@slorber/remark-comment/-/remark-comment-1.0.0.tgz", @@ -4580,6 +4668,12 @@ "postcss": "^8.1.0" } }, + "node_modules/b4a": { + "version": "1.6.6", + "resolved": "https://registry.npmjs.org/b4a/-/b4a-1.6.6.tgz", + "integrity": "sha512-5Tk1HLk6b6ctmjIkAcU/Ujv/1WqiDl0F0JdRCR80VsOcUlHcu7pWeWRlOqQLHfDEsVx9YH/aif5AG4ehoCtTmg==", + "license": "Apache-2.0" + }, "node_modules/babel-loader": { "version": "9.1.3", "resolved": "https://registry.npmjs.org/babel-loader/-/babel-loader-9.1.3.tgz", @@ -4721,6 +4815,72 @@ "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==", "license": "MIT" }, + "node_modules/bare-events": { + "version": "2.4.2", + "resolved": "https://registry.npmjs.org/bare-events/-/bare-events-2.4.2.tgz", + "integrity": "sha512-qMKFd2qG/36aA4GwvKq8MxnPgCQAmBWmSyLWsJcbn8v03wvIPQ/hG1Ms8bPzndZxMDoHpxez5VOS+gC9Yi24/Q==", + "license": "Apache-2.0", + "optional": true + }, + "node_modules/bare-fs": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/bare-fs/-/bare-fs-2.3.1.tgz", + "integrity": "sha512-W/Hfxc/6VehXlsgFtbB5B4xFcsCl+pAh30cYhoFyXErf6oGrwjh8SwiPAdHgpmWonKuYpZgGywN0SXt7dgsADA==", + "license": "Apache-2.0", + "optional": true, + "dependencies": { + "bare-events": "^2.0.0", + "bare-path": "^2.0.0", + "bare-stream": "^2.0.0" + } + }, + "node_modules/bare-os": { + "version": "2.4.0", + "resolved": "https://registry.npmjs.org/bare-os/-/bare-os-2.4.0.tgz", + "integrity": "sha512-v8DTT08AS/G0F9xrhyLtepoo9EJBJ85FRSMbu1pQUlAf6A8T0tEEQGMVObWeqpjhSPXsE0VGlluFBJu2fdoTNg==", + "license": "Apache-2.0", + "optional": true + }, + "node_modules/bare-path": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/bare-path/-/bare-path-2.1.3.tgz", + "integrity": "sha512-lh/eITfU8hrj9Ru5quUp0Io1kJWIk1bTjzo7JH1P5dWmQ2EL4hFUlfI8FonAhSlgIfhn63p84CDY/x+PisgcXA==", + "license": "Apache-2.0", + "optional": true, + "dependencies": { + "bare-os": "^2.1.0" + } + }, + "node_modules/bare-stream": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/bare-stream/-/bare-stream-2.1.3.tgz", + "integrity": "sha512-tiDAH9H/kP+tvNO5sczyn9ZAA7utrSMobyDchsnyyXBuUe2FSQWbxhtuHB8jwpHYYevVo2UJpcmvvjrbHboUUQ==", + "license": "Apache-2.0", + "optional": true, + "dependencies": { + "streamx": "^2.18.0" + } + }, + "node_modules/base64-js": { + "version": "1.5.1", + "resolved": "https://registry.npmjs.org/base64-js/-/base64-js-1.5.1.tgz", + "integrity": "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "license": "MIT" + }, "node_modules/batch": { "version": "0.6.1", "resolved": "https://registry.npmjs.org/batch/-/batch-0.6.1.tgz", @@ -4748,6 +4908,17 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/bl": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/bl/-/bl-4.1.0.tgz", + "integrity": "sha512-1W07cM9gS6DcLperZfFSj+bWLtaPGSOHWhPiGzXmvVJbRLdG82sH/Kn8EtW1VqWVA54AKf2h5k5BbnIbwF3h6w==", + "license": "MIT", + "dependencies": { + "buffer": "^5.5.0", + "inherits": "^2.0.4", + "readable-stream": "^3.4.0" + } + }, "node_modules/body-parser": { "version": "1.20.2", "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-1.20.2.tgz", @@ -4900,6 +5071,30 @@ "node": "^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7" } }, + "node_modules/buffer": { + "version": "5.7.1", + "resolved": "https://registry.npmjs.org/buffer/-/buffer-5.7.1.tgz", + "integrity": "sha512-EHcyIPBQ4BSGlvjB16k5KgAJ27CIsHY/2JBmCRReo48y9rQ3MaUzWX3KVlBa4U7MyX02HdVj0K7C3WaB3ju7FQ==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "license": "MIT", + "dependencies": { + "base64-js": "^1.3.1", + "ieee754": "^1.1.13" + } + }, "node_modules/buffer-from": { "version": "1.1.2", "resolved": "https://registry.npmjs.org/buffer-from/-/buffer-from-1.1.2.tgz", @@ -5161,6 +5356,12 @@ "fsevents": "~2.3.2" } }, + "node_modules/chownr": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/chownr/-/chownr-1.1.4.tgz", + "integrity": "sha512-jJ0bqzaylmJtVnNgzTeSOs8DPavpbYgEr/b0YL8/2GO3xJEhInFmhKMUnEJQjZumK7KXGFhUy89PrsJWlakBVg==", + "license": "ISC" + }, "node_modules/chrome-trace-event": { "version": "1.0.4", "resolved": "https://registry.npmjs.org/chrome-trace-event/-/chrome-trace-event-1.0.4.tgz", @@ -5307,6 +5508,19 @@ "url": "https://github.com/sponsors/wooorm" } }, + "node_modules/color": { + "version": "4.2.3", + "resolved": "https://registry.npmjs.org/color/-/color-4.2.3.tgz", + "integrity": "sha512-1rXeuUUiGGrykh+CeBdu5Ie7OJwinCgQY0bc7GCRxy5xVHy+moaqkpL/jqQq0MtQOeYcrqEz4abc5f0KtU7W4A==", + "license": "MIT", + "dependencies": { + "color-convert": "^2.0.1", + "color-string": "^1.9.0" + }, + "engines": { + "node": ">=12.5.0" + } + }, "node_modules/color-convert": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", @@ -5325,6 +5539,16 @@ "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", "license": "MIT" }, + "node_modules/color-string": { + "version": "1.9.1", + "resolved": "https://registry.npmjs.org/color-string/-/color-string-1.9.1.tgz", + "integrity": "sha512-shrVawQFojnZv6xM40anx4CkoDP+fZsw/ZerEMsW/pyzsRbElpsL/DBVW7q3ExxwusdNXI3lXpuhEZkzs8p5Eg==", + "license": "MIT", + "dependencies": { + "color-name": "^1.0.0", + "simple-swizzle": "^0.2.2" + } + }, "node_modules/colord": { "version": "2.9.3", "resolved": "https://registry.npmjs.org/colord/-/colord-2.9.3.tgz", @@ -5481,6 +5705,12 @@ "integrity": "sha512-9vAdYbHj6x2fLKC4+oPH0kFzY/orMZyG2Aj+kNylHxKGJ/Ed4dpNyAQYwJOdqO4zdM7XpVHmyejQDcQHrnuXbw==", "license": "MIT" }, + "node_modules/consolidated-events": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/consolidated-events/-/consolidated-events-2.0.2.tgz", + "integrity": "sha512-2/uRVMdRypf5z/TW/ncD/66l75P5hH2vM/GR8Jf8HLc2xnfJtmina6F6du8+v4Z2vTrMo7jC+W1tmEEuuELgkQ==", + "license": "MIT" + }, "node_modules/content-disposition": { "version": "0.5.2", "resolved": "https://registry.npmjs.org/content-disposition/-/content-disposition-0.5.2.tgz", @@ -6700,6 +6930,15 @@ "npm": "1.2.8000 || >= 1.4.16" } }, + "node_modules/detect-libc": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.0.3.tgz", + "integrity": "sha512-bwy0MGW55bG41VqxxypOsdSdGqLwXPI/focwgTYCFMbdUiBAxLg9CFzG08sz2aqzknwiX7Hkl0bQENjg8iLByw==", + "license": "Apache-2.0", + "engines": { + "node": ">=8" + } + }, "node_modules/detect-node": { "version": "2.1.0", "resolved": "https://registry.npmjs.org/detect-node/-/detect-node-2.1.0.tgz", @@ -7015,6 +7254,15 @@ "node": ">= 0.8" } }, + "node_modules/end-of-stream": { + "version": "1.4.4", + "resolved": "https://registry.npmjs.org/end-of-stream/-/end-of-stream-1.4.4.tgz", + "integrity": "sha512-+uw1inIHVPQoaVuHzRyXd21icM+cnt4CzD5rW+NC1wjOUSTOs+Te7FOv7AhN7vS9x/oIyhLP5PR1H+phQAHu5Q==", + "license": "MIT", + "dependencies": { + "once": "^1.4.0" + } + }, "node_modules/enhanced-resolve": { "version": "5.17.1", "resolved": "https://registry.npmjs.org/enhanced-resolve/-/enhanced-resolve-5.17.1.tgz", @@ -7340,6 +7588,15 @@ "url": "https://github.com/sindresorhus/execa?sponsor=1" } }, + "node_modules/expand-template": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/expand-template/-/expand-template-2.0.3.tgz", + "integrity": "sha512-XYfuKMvj4O35f/pOXLObndIRvyQ+/+6AhODh+OKWj9S9498pHHn/IMszH+gt0fBCRWMNfk1ZSp5x3AifmnI2vg==", + "license": "(MIT OR WTFPL)", + "engines": { + "node": ">=6" + } + }, "node_modules/express": { "version": "4.19.2", "resolved": "https://registry.npmjs.org/express/-/express-4.19.2.tgz", @@ -7448,6 +7705,12 @@ "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==", "license": "MIT" }, + "node_modules/fast-fifo": { + "version": "1.3.2", + "resolved": "https://registry.npmjs.org/fast-fifo/-/fast-fifo-1.3.2.tgz", + "integrity": "sha512-/d9sfos4yxzpwkDkuN7k2SqFKtYNmCTzgfEpz82x34IM9/zc8KGxQoXg1liNC/izpRM/MBdt44Nmx41ZWqk+FQ==", + "license": "MIT" + }, "node_modules/fast-glob": { "version": "3.3.2", "resolved": "https://registry.npmjs.org/fast-glob/-/fast-glob-3.3.2.tgz", @@ -7932,6 +8195,12 @@ "node": ">= 0.6" } }, + "node_modules/fs-constants": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/fs-constants/-/fs-constants-1.0.0.tgz", + "integrity": "sha512-y6OAwoSIf7FyjMIv94u+b5rdheZEjzR63GTyZJm5qh4Bi+2YgwLCcI/fPFZkL5PSixOt6ZNKm+w+Hfp/Bciwow==", + "license": "MIT" + }, "node_modules/fs-extra": { "version": "11.2.0", "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-11.2.0.tgz", @@ -8033,6 +8302,12 @@ "integrity": "sha512-KsCbYiA+MiHO3ytzdGvGt/GNde4GfG9BrrLxxc+ut2snBF9IAjrn2F5mNgHHEXdG/CfFIHOMV8Uxy4LNhxZwUA==", "license": "BSD-2-Clause" }, + "node_modules/github-from-package": { + "version": "0.0.0", + "resolved": "https://registry.npmjs.org/github-from-package/-/github-from-package-0.0.0.tgz", + "integrity": "sha512-SyHy3T1v2NUXn29OsWdxmK6RwHD+vkj3v8en8AOBZ1wBQ/hCAQ5bAQTD02kW4W9tUp/3Qh6J8r9EvntiyCmOOw==", + "license": "MIT" + }, "node_modules/github-slugger": { "version": "1.5.0", "resolved": "https://registry.npmjs.org/github-slugger/-/github-slugger-1.5.0.tgz", @@ -8952,6 +9227,26 @@ "postcss": "^8.1.0" } }, + "node_modules/ieee754": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/ieee754/-/ieee754-1.2.1.tgz", + "integrity": "sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "license": "BSD-3-Clause" + }, "node_modules/ignore": { "version": "5.3.1", "resolved": "https://registry.npmjs.org/ignore/-/ignore-5.3.1.tgz", @@ -12688,6 +12983,12 @@ "url": "https://github.com/sponsors/ljharb" } }, + "node_modules/mkdirp-classic": { + "version": "0.5.3", + "resolved": "https://registry.npmjs.org/mkdirp-classic/-/mkdirp-classic-0.5.3.tgz", + "integrity": "sha512-gKLcREMhtuZRwRAfqP3RFW+TK4JqApVBtOIftVgjuABpAtpxhPGaDcfvbhNvD0B8iD1oUr/txX35NjcaY6Ns/A==", + "license": "MIT" + }, "node_modules/mri": { "version": "1.2.0", "resolved": "https://registry.npmjs.org/mri/-/mri-1.2.0.tgz", @@ -12743,6 +13044,12 @@ "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1" } }, + "node_modules/napi-build-utils": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/napi-build-utils/-/napi-build-utils-1.0.2.tgz", + "integrity": "sha512-ONmRUqK7zj7DWX0D9ADe03wbwOBZxNAfF20PlGfCWQcD3+/MakShIHrMqx9YwPTfxDdF1zLeL+RGZiR9kGMLdg==", + "license": "MIT" + }, "node_modules/negotiator": { "version": "0.6.3", "resolved": "https://registry.npmjs.org/negotiator/-/negotiator-0.6.3.tgz", @@ -12768,6 +13075,24 @@ "tslib": "^2.0.3" } }, + "node_modules/node-abi": { + "version": "3.65.0", + "resolved": "https://registry.npmjs.org/node-abi/-/node-abi-3.65.0.tgz", + "integrity": "sha512-ThjYBfoDNr08AWx6hGaRbfPwxKV9kVzAzOzlLKbk2CuqXE2xnCh+cbAGnwM3t8Lq4v9rUB7VfondlkBckcJrVA==", + "license": "MIT", + "dependencies": { + "semver": "^7.3.5" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/node-addon-api": { + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-6.1.0.tgz", + "integrity": "sha512-+eawOlIgy680F0kBzPUNFhMZGtJ1YmqM6l4+Crf4IkImjYrO/mqPwRMh352g23uIaQKFItcQ64I7KMaJxHgAVA==", + "license": "MIT" + }, "node_modules/node-domexception": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/node-domexception/-/node-domexception-1.0.0.tgz", @@ -14069,6 +14394,60 @@ "url": "https://opencollective.com/preact" } }, + "node_modules/prebuild-install": { + "version": "7.1.2", + "resolved": "https://registry.npmjs.org/prebuild-install/-/prebuild-install-7.1.2.tgz", + "integrity": "sha512-UnNke3IQb6sgarcZIDU3gbMeTp/9SSU1DAIkil7PrqG1vZlBtY5msYccSKSHDqa3hNg436IXK+SNImReuA1wEQ==", + "license": "MIT", + "dependencies": { + "detect-libc": "^2.0.0", + "expand-template": "^2.0.3", + "github-from-package": "0.0.0", + "minimist": "^1.2.3", + "mkdirp-classic": "^0.5.3", + "napi-build-utils": "^1.0.1", + "node-abi": "^3.3.0", + "pump": "^3.0.0", + "rc": "^1.2.7", + "simple-get": "^4.0.0", + "tar-fs": "^2.0.0", + "tunnel-agent": "^0.6.0" + }, + "bin": { + "prebuild-install": "bin.js" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/prebuild-install/node_modules/tar-fs": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/tar-fs/-/tar-fs-2.1.1.tgz", + "integrity": "sha512-V0r2Y9scmbDRLCNex/+hYzvp/zyYjvFbHPNgVTKfQvVrb6guiE/fxP+XblDNR011utopbkex2nM4dHNV6GDsng==", + "license": "MIT", + "dependencies": { + "chownr": "^1.1.1", + "mkdirp-classic": "^0.5.2", + "pump": "^3.0.0", + "tar-stream": "^2.1.4" + } + }, + "node_modules/prebuild-install/node_modules/tar-stream": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/tar-stream/-/tar-stream-2.2.0.tgz", + "integrity": "sha512-ujeqbceABgwMZxEJnk2HDY2DlnUZ+9oEcb1KzTVfYHio0UE6dG71n60d8D2I4qNvleWrrXpmjpt7vZeF1LnMZQ==", + "license": "MIT", + "dependencies": { + "bl": "^4.0.3", + "end-of-stream": "^1.4.1", + "fs-constants": "^1.0.0", + "inherits": "^2.0.3", + "readable-stream": "^3.1.1" + }, + "engines": { + "node": ">=6" + } + }, "node_modules/pretty-error": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/pretty-error/-/pretty-error-4.0.0.tgz", @@ -14178,6 +14557,16 @@ "node": ">= 0.10" } }, + "node_modules/pump": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/pump/-/pump-3.0.0.tgz", + "integrity": "sha512-LwZy+p3SFs1Pytd/jYct4wpv49HiYCqd9Rlc5ZVdk0V+8Yzv6jR5Blk3TRmPL1ft69TxP0IMZGJ+WPFU2BFhww==", + "license": "MIT", + "dependencies": { + "end-of-stream": "^1.1.0", + "once": "^1.3.1" + } + }, "node_modules/punycode": { "version": "1.4.1", "resolved": "https://registry.npmjs.org/punycode/-/punycode-1.4.1.tgz", @@ -14243,6 +14632,12 @@ ], "license": "MIT" }, + "node_modules/queue-tick": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/queue-tick/-/queue-tick-1.0.1.tgz", + "integrity": "sha512-kJt5qhMxoszgU/62PLP1CJytzd2NKetjSRnyuj31fDd3Rlcz3fzlFdFLD1SItunPwyqEOkca6GbV612BWfaBag==", + "license": "MIT" + }, "node_modules/quick-lru": { "version": "5.1.1", "resolved": "https://registry.npmjs.org/quick-lru/-/quick-lru-5.1.1.tgz", @@ -14857,6 +15252,27 @@ "react-dom": "^16.0.0 || ^17.0.0 || ^18.0.0" } }, + "node_modules/react-waypoint": { + "version": "10.3.0", + "resolved": "https://registry.npmjs.org/react-waypoint/-/react-waypoint-10.3.0.tgz", + "integrity": "sha512-iF1y2c1BsoXuEGz08NoahaLFIGI9gTUAAOKip96HUmylRT6DUtpgoBPjk/Y8dfcFVmfVDvUzWjNXpZyKTOV0SQ==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.12.5", + "consolidated-events": "^1.1.0 || ^2.0.0", + "prop-types": "^15.0.0", + "react-is": "^17.0.1 || ^18.0.0" + }, + "peerDependencies": { + "react": "^15.3.0 || ^16.0.0 || ^17.0.0 || ^18.0.0" + } + }, + "node_modules/react-waypoint/node_modules/react-is": { + "version": "18.3.1", + "resolved": "https://registry.npmjs.org/react-is/-/react-is-18.3.1.tgz", + "integrity": "sha512-/LLMVyas0ljjAtoYiPqYiL8VWXzUUdThrmU5+n20DZv+a+ClRoevUzw5JxU+Ieh5/c87ytoTBV9G1FiKfNJdmg==", + "license": "MIT" + }, "node_modules/react-youtube": { "version": "10.1.0", "resolved": "https://registry.npmjs.org/react-youtube/-/react-youtube-10.1.0.tgz", @@ -15964,6 +16380,29 @@ "integrity": "sha512-y0m1JoUZSlPAjXVtPPW70aZWfIL/dSP7AFkRnniLCrK/8MDKog3TySTBmckD+RObVxH0v4Tox67+F14PdED2oQ==", "license": "MIT" }, + "node_modules/sharp": { + "version": "0.32.6", + "resolved": "https://registry.npmjs.org/sharp/-/sharp-0.32.6.tgz", + "integrity": "sha512-KyLTWwgcR9Oe4d9HwCwNM2l7+J0dUQwn/yf7S0EnTtb0eVS4RxO0eUSvxPtzT4F3SY+C4K6fqdv/DO27sJ/v/w==", + "hasInstallScript": true, + "license": "Apache-2.0", + "dependencies": { + "color": "^4.2.3", + "detect-libc": "^2.0.2", + "node-addon-api": "^6.1.0", + "prebuild-install": "^7.1.1", + "semver": "^7.5.4", + "simple-get": "^4.0.1", + "tar-fs": "^3.0.4", + "tunnel-agent": "^0.6.0" + }, + "engines": { + "node": ">=14.15.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + } + }, "node_modules/shebang-command": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz", @@ -16035,6 +16474,66 @@ "integrity": "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==", "license": "ISC" }, + "node_modules/simple-concat": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/simple-concat/-/simple-concat-1.0.1.tgz", + "integrity": "sha512-cSFtAPtRhljv69IK0hTVZQ+OfE9nePi/rtJmw5UjHeVyVroEqJXP1sFztKUy1qU+xvz3u/sfYJLa947b7nAN2Q==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "license": "MIT" + }, + "node_modules/simple-get": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/simple-get/-/simple-get-4.0.1.tgz", + "integrity": "sha512-brv7p5WgH0jmQJr1ZDDfKDOSeWWg+OVypG99A/5vYGPqJ6pxiaHLy8nxtFjBA7oMa01ebA9gfh1uMCFqOuXxvA==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "license": "MIT", + "dependencies": { + "decompress-response": "^6.0.0", + "once": "^1.3.1", + "simple-concat": "^1.0.0" + } + }, + "node_modules/simple-swizzle": { + "version": "0.2.2", + "resolved": "https://registry.npmjs.org/simple-swizzle/-/simple-swizzle-0.2.2.tgz", + "integrity": "sha512-JA//kQgZtbuY83m+xT+tXJkmJncGMTFT+C+g2h2R9uxkYIrE2yy9sgmcLhCnw57/WSD+Eh3J97FPEDFnbXnDUg==", + "license": "MIT", + "dependencies": { + "is-arrayish": "^0.3.1" + } + }, + "node_modules/simple-swizzle/node_modules/is-arrayish": { + "version": "0.3.2", + "resolved": "https://registry.npmjs.org/is-arrayish/-/is-arrayish-0.3.2.tgz", + "integrity": "sha512-eVRqCvVlZbuw3GrM63ovNSNAeA1K16kaR/LRY/92w0zxQ5/1YzwblUX652i4Xs9RwAGjW9d9y6X88t8OaAJfWQ==", + "license": "MIT" + }, "node_modules/sirv": { "version": "2.0.4", "resolved": "https://registry.npmjs.org/sirv/-/sirv-2.0.4.tgz", @@ -16267,6 +16766,20 @@ "integrity": "sha512-JPbdCEQLj1w5GilpiHAx3qJvFndqybBysA3qUOnznweH4QbNYUsW/ea8QzSrnh0vNsezMMw5bcVool8lM0gwzg==", "license": "MIT" }, + "node_modules/streamx": { + "version": "2.18.0", + "resolved": "https://registry.npmjs.org/streamx/-/streamx-2.18.0.tgz", + "integrity": "sha512-LLUC1TWdjVdn1weXGcSxyTR3T4+acB6tVGXT95y0nGbca4t4o/ng1wKAGTljm9VicuCVLvRlqFYXYy5GwgM7sQ==", + "license": "MIT", + "dependencies": { + "fast-fifo": "^1.3.2", + "queue-tick": "^1.0.1", + "text-decoder": "^1.1.0" + }, + "optionalDependencies": { + "bare-events": "^2.2.0" + } + }, "node_modules/string_decoder": { "version": "1.3.0", "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.3.0.tgz", @@ -16523,6 +17036,31 @@ "node": ">=6" } }, + "node_modules/tar-fs": { + "version": "3.0.6", + "resolved": "https://registry.npmjs.org/tar-fs/-/tar-fs-3.0.6.tgz", + "integrity": "sha512-iokBDQQkUyeXhgPYaZxmczGPhnhXZ0CmrqI+MOb/WFGS9DW5wnfrLgtjUJBvz50vQ3qfRwJ62QVoCFu8mPVu5w==", + "license": "MIT", + "dependencies": { + "pump": "^3.0.0", + "tar-stream": "^3.1.5" + }, + "optionalDependencies": { + "bare-fs": "^2.1.1", + "bare-path": "^2.1.0" + } + }, + "node_modules/tar-stream": { + "version": "3.1.7", + "resolved": "https://registry.npmjs.org/tar-stream/-/tar-stream-3.1.7.tgz", + "integrity": "sha512-qJj60CXt7IU1Ffyc3NJMjh6EkuCFej46zUqJ4J7pqYlThyd9bO0XBTmcOIhSzZJVWfsLks0+nle/j538YAW9RQ==", + "license": "MIT", + "dependencies": { + "b4a": "^1.6.4", + "fast-fifo": "^1.2.0", + "streamx": "^2.15.0" + } + }, "node_modules/terser": { "version": "5.31.3", "resolved": "https://registry.npmjs.org/terser/-/terser-5.31.3.tgz", @@ -16659,6 +17197,15 @@ "integrity": "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==", "license": "MIT" }, + "node_modules/text-decoder": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/text-decoder/-/text-decoder-1.1.1.tgz", + "integrity": "sha512-8zll7REEv4GDD3x4/0pW+ppIxSNs7H1J10IKFZsuOMscumCdM2a+toDGLPA3T+1+fLBql4zbt5z83GEQGGV5VA==", + "license": "Apache-2.0", + "dependencies": { + "b4a": "^1.6.4" + } + }, "node_modules/text-table": { "version": "0.2.0", "resolved": "https://registry.npmjs.org/text-table/-/text-table-0.2.0.tgz", @@ -16757,6 +17304,18 @@ "integrity": "sha512-xNvxJEOUiWPGhUuUdQgAJPKOOJfGnIyKySOc09XkKsgdUV/3E2zvwZYdejjmRgPCgcym1juLH3226yA7sEFJKQ==", "license": "0BSD" }, + "node_modules/tunnel-agent": { + "version": "0.6.0", + "resolved": "https://registry.npmjs.org/tunnel-agent/-/tunnel-agent-0.6.0.tgz", + "integrity": "sha512-McnNiV1l8RYeY8tBgEpuodCC1mLUdbSN+CYBL7kJsJNInOP8UjDDEwdk6Mw60vdLLrr5NHKZhMAOSrR2NZuQ+w==", + "license": "Apache-2.0", + "dependencies": { + "safe-buffer": "^5.0.1" + }, + "engines": { + "node": "*" + } + }, "node_modules/type-fest": { "version": "2.19.0", "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-2.19.0.tgz", diff --git a/package.json b/package.json index c20e13ec5..4dcd29e25 100644 --- a/package.json +++ b/package.json @@ -23,6 +23,7 @@ "@docusaurus/plugin-content-docs": "^3.4.0", "@docusaurus/plugin-debug": "^3.4.0", "@docusaurus/plugin-google-tag-manager": "^3.4.0", + "@docusaurus/plugin-ideal-image": "^3.4.0", "@docusaurus/preset-classic": "^3.4.0", "@docusaurus/theme-mermaid": "^3.4.0", "@excalidraw/excalidraw": "^0.17.6", diff --git a/plugins/custom-loaders/index.js b/plugins/custom-loaders/index.js new file mode 100644 index 000000000..2206123b6 --- /dev/null +++ b/plugins/custom-loaders/index.js @@ -0,0 +1,48 @@ +// https://stackoverflow.com/questions/74876229/how-to-tweak-docusaurus-webpack-config-for-some-react-component +// https://webpack.js.org/loaders/html-loader/ +// https://github.com/algolia/docsearch-website/blob/master/plugins/my-loaders/index.js +// https://github.com/facebook/docusaurus/issues/2097 +// https://webpack.js.org/concepts/#loaders + +const html = require('html-loader'); +const path = require('path'); + +module.exports = function (context, options) { + return { + name: 'custom-loaders', + configureWebpack(config, isServer) { + return { + /*output: { + filename: 'custom-loaders-webpack.bundle.js', + },*/ + + module: { + rules: [ + // { test: /\.txt$/, use: 'raw-loader' }, + // https://webpack.js.org/loaders/html-loader/ + { + test: /\.(html|htm)$/i, + loader: "html-loader", + options: { + minimize: { + removeComments: false, + collapseWhitespace: false, + }, + }, + }, + { + test: /\.(txt|yml|yaml|tf)$/, + use: 'raw-loader' + } + ], + }, + + resolve: { + alias: { + '@examples': path.resolve(__dirname, 'examples'), + } + } + }; + }, + }; + }; diff --git a/scripts/docs-collator/ComponentRenderer.py b/scripts/docs-collator/ComponentRenderer.py index 196d75c82..a6c2e4f35 100644 --- a/scripts/docs-collator/ComponentRenderer.py +++ b/scripts/docs-collator/ComponentRenderer.py @@ -116,7 +116,8 @@ def __render_doc(self, component, file): io.save_string_to_file(result_file, doc_content) - self.__create_indexes_for_subfolder(component) + # Breaking builds, not sure why and not adding value. Disabling. + #self.__create_indexes_for_subfolder(component) def __create_indexes_for_subfolder(self, component): for root, dirs, files in os.walk(os.path.join(self.docs_dir, component)): diff --git a/sidebars.js b/sidebars.js index a06a0088e..f24b4ecb7 100644 --- a/sidebars.js +++ b/sidebars.js @@ -27,7 +27,7 @@ module.exports = { collapsed: false, link: { type: 'doc', - id: 'intro/index' + id: 'intro/intro' }, items: [ { @@ -91,7 +91,7 @@ module.exports = { }, { type: 'category', - label: 'Learn refarch', + label: 'Learn The Concepts', className: 'sidebar-title', collapsible: false, collapsed: false, @@ -181,12 +181,12 @@ module.exports = { collapsed: true, link: { type: 'doc', - id: 'layers/network-and-dns/network-and-dns' + id: 'layers/network/network' }, items: [ { type: 'autogenerated', - dirName: 'layers/network-and-dns', + dirName: 'layers/network', } ] } @@ -327,12 +327,12 @@ module.exports = { collapsed: true, link: { type: 'doc', - id: 'layers/application-cicd/application-cicd' + id: 'layers/software-delivery/software-delivery' }, items: [ { type: 'autogenerated', - dirName: 'layers/application-cicd', + dirName: 'layers/software-delivery', } ] } @@ -419,6 +419,10 @@ module.exports = { className: 'sidebar-title', collapsible: true, collapsed: false, + link: { + type: 'doc', + id: 'best-practices/best-practices' + }, items: [ { type: 'autogenerated', @@ -430,10 +434,14 @@ module.exports = { reference: [ { type: 'category', - label: 'Reference', + label: 'Library', className: 'sidebar-title', collapsible: false, collapsed: false, + link: { + type: 'doc', + id: 'reference/reference' + }, items: [ { type: 'autogenerated', diff --git a/src/components/ActionCard/index.js b/src/components/ActionCard/index.js index e55136b41..4cd50c8c2 100644 --- a/src/components/ActionCard/index.js +++ b/src/components/ActionCard/index.js @@ -2,6 +2,8 @@ import React from 'react' import Link from '@docusaurus/Link' import PrimaryCTA from '@site/src/components/PrimaryCTA' import SecondaryCTA from '@site/src/components/SecondaryCTA' +import { useLocation } from 'react-router-dom' +import { useActivePluginAndVersion, useActiveDocContext } from '@docusaurus/plugin-content-docs/client' import './index.css' const ActionCard = ({ title = "Ready to learn this topic?", @@ -12,9 +14,30 @@ const ActionCard = ({ title = "Ready to learn this topic?", secondaryCtaText, secondaryCtaLink, children }) => { + + const location = useLocation(); + const { activePlugin, activeVersion } = useActivePluginAndVersion(); + const { activeDoc } = useActiveDocContext(); + + // Function to find the next document based on front matter pagination + const findNextDoc = () => { + if (!activeDoc || !activeDoc.frontMatter) { + return null; + } + + const { pagination_next: nextDocId } = activeDoc.frontMatter; + + if (nextDocId) { + const nextDoc = activePlugin.content.docs.find(doc => doc.id === nextDocId); + return nextDoc ? nextDoc.permalink : null; + } + + return null; + }; + // Determine primary CTA text and link - const primaryText = ctaText || primaryCtaText; - const primaryLink = ctaLink || primaryCtaLink; + const primaryText = ctaText || primaryCtaText || "Next"; + const primaryLink = ctaLink || primaryCtaLink || findNextDoc(); return (
@@ -22,7 +45,7 @@ const ActionCard = ({ title = "Ready to learn this topic?",
{children}
{primaryLink && ( - {primaryText || "Read More"} + {primaryText} )} {secondaryCtaLink && ( diff --git a/src/components/KeyboardShortcuts/index.js b/src/components/KeyboardShortcuts/index.js new file mode 100644 index 000000000..4924dadd6 --- /dev/null +++ b/src/components/KeyboardShortcuts/index.js @@ -0,0 +1,38 @@ +// src/components/KeyboardShortcuts.js +import React, { useEffect } from 'react'; + +const KeyboardShortcuts = () => { + useEffect(() => { + const handleKeyDown = (e) => { + // Avoid intercepting Command + Arrow Key combinations + if (e.metaKey) { + return; + } + + if (e.key === 'ArrowLeft') { + const buttons = document.getElementsByClassName('pagination-nav__link'); + if (buttons.length >= 1) { + buttons[0].click(); + } + } else if (e.key === 'ArrowRight') { + const buttons = document.getElementsByClassName('pagination-nav__link'); + if (buttons.length >= 2) { + buttons[1].click(); + } else if (buttons.length >= 1) { + buttons[0].click(); + } + } + }; + + document.addEventListener('keydown', handleKeyDown); + + // Clean up the event listener on component unmount + return () => { + document.removeEventListener('keydown', handleKeyDown); + }; + }, []); + + return null; +}; + +export default KeyboardShortcuts; diff --git a/src/components/Step/index.css b/src/components/Step/index.css index 7ce7c6907..42eabb511 100644 --- a/src/components/Step/index.css +++ b/src/components/Step/index.css @@ -3,6 +3,10 @@ div > .step:first-child { margin-top: 4em; } +.step img { + border-radius: 6px; +} + .step { padding-top: 3em; padding-bottom: 1em; diff --git a/src/components/Steps/index.module.css b/src/components/Steps/index.module.css index 86922aeba..0c4e4166b 100644 --- a/src/components/Steps/index.module.css +++ b/src/components/Steps/index.module.css @@ -6,13 +6,14 @@ margin-top: 2em; } -.steps li::before { +.steps > ul > li::before, .steps > ol > li::before { content: counter(list-counter); + display: inline-block; position: absolute; left: 0; - top: 0; width: 1.5em; height: 1.5em; + margin-right: 0.6em; line-height: 1.5em; border-radius: 50%; background-color: #000; /* Background color for the circle */ @@ -50,21 +51,26 @@ html[data-theme='dark'] .steps li::before { .steps ol, .steps > ul { counter-reset: list-counter; list-style: none; /* Remove default list styling */ - padding-left: 0; /* Remove default padding */ + padding-left: 0.3em; border-left: 1px solid #ccc; margin-left: 1em; } -:global(.content) .steps ol, :global(.content) .steps > ul { +:global(.content) .steps ol, :global(.content) .steps > ul, ol .steps > ul { border-left: none; + margin-left: 1.3em; } -html[data-theme='dark'] :global(.content) .steps li::before { +:global(.content) > ul { + margin-left: 1.3em; +} + +html[data-theme='dark'] :global(.content) .steps li::before, html[data-theme='dark'] ol .steps > ul > li::before { background: #666; color: #000 !important; } -:global(.content) .steps li::before { +:global(.content) .steps li::before, ol .steps > ul li::before { background: transparent; color: #000 !important; } @@ -72,15 +78,16 @@ html[data-theme='dark'] :global(.content) .steps li::before { .steps ol > li, .steps > ul > li { counter-increment: list-counter; position: relative; - left: -0.8em; + left: -1.2em; padding-left: 2.3em; /* Adjust space for the custom counter */ margin-bottom: 1.2em; /* Space between list items */ line-height: 1.6em; } .steps ol > li img, .steps > ul > li img { - padding: 2em; + margin: 2em; max-width: 100%; + border-radius: 6px; } .steps > h3 { diff --git a/src/components/TagList/index.js b/src/components/TagList/index.js new file mode 100644 index 000000000..a8c6d8af2 --- /dev/null +++ b/src/components/TagList/index.js @@ -0,0 +1,37 @@ +import React from 'react'; +import useGlobalData from '@docusaurus/useGlobalData'; + +const findItemsByTags = (items, tags) => { + // Filter documents that have all the specified tags + const filteredItems = items.filter(doc => + tags.every(tag => doc.tags.some(docTag => docTag.label === tag)) + ); + return filteredItems; +} + +const findItemsFromGlobalMetadataByTags = (tags) => { + const globalData = useGlobalData(); + let globalMetadata = globalData.metadata.default.aggregateMetadata; + //console.log(globalMetadata); + return findItemsByTags(globalMetadata, tags); +} + +const TagList = ({ tags }) => { + const items = findItemsFromGlobalMetadataByTags(tags); + //console.log(items); + return ( +
    + {items.map(item => ( +
  • + {item.permalink ? ( + {item.title} + ) : ( + item.title + )} +
    • + ))} +
+ ); +}; + +export default TagList; diff --git a/src/css/sidebar.css b/src/css/sidebar.css index 21e8c5192..aabf97b78 100644 --- a/src/css/sidebar.css +++ b/src/css/sidebar.css @@ -34,3 +34,9 @@ li.sidebar-title > ul:first .menu__list .menu__list { margin-left: 0; padding-left: 0; } + +.compact ul.menu__list { + margin-left: 0; + border-left: 1px solid #cccccc61; + margin-left: 4px; +} diff --git a/src/theme/DocCard/index.js b/src/theme/DocCard/index.js index 77316a0cb..6a032bc0a 100644 --- a/src/theme/DocCard/index.js +++ b/src/theme/DocCard/index.js @@ -1,9 +1,9 @@ import React from 'react'; import clsx from 'clsx'; import Link from '@docusaurus/Link'; +import useGlobalData from '@docusaurus/useGlobalData'; import { findFirstSidebarItemLink, - findSidebarCategory, useDocById, } from '@docusaurus/theme-common/internal'; import {usePluralForm} from '@docusaurus/theme-common'; @@ -60,21 +60,39 @@ function CardLayout({href, icon, title, description}) { ); } +const findPermalink = (items, permalink) => { + // Filter documents that have all the specified permalink + const filteredItems = items.filter(doc => + doc.permalink === permalink + ); + if (filteredItems.length === 0) { + return null; + } + return filteredItems[0]; +} + function CardCategory({item}) { const href = findFirstSidebarItemLink(item); const categoryItemsPlural = useCategoryItemsPlural(); + // Unexpected: categories that don't have a link have been filtered upfront if (!href) { return null; } + + const globalData = useGlobalData(); + const globalMetadata = globalData.metadata.default.aggregateMetadata; + const category = findPermalink(globalMetadata, href); + //console.log(category); + // Doc description is not used // https://github.com/facebook/docusaurus/issues/7598 return ( ); } diff --git a/src/theme/Layout/index.js b/src/theme/Layout/index.js new file mode 100644 index 000000000..7449e53d0 --- /dev/null +++ b/src/theme/Layout/index.js @@ -0,0 +1,12 @@ +import React from 'react'; +import Layout from '@theme-original/Layout'; +import KeyboardShortcuts from '@site/src/components/KeyboardShortcuts'; + +export default function LayoutWrapper(props) { + return ( + <> + + + + ); +}