From ce5e0e89986e81d92f6dd72f47c0f85ed4b9cf50 Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Sat, 1 Jun 2024 11:38:09 -0500 Subject: [PATCH 001/151] reorganize sidebar to help the user on their journey --- atmos.yaml | 2 +- examples/quick-start/atmos.yaml | 2 +- .../rootfs/usr/local/etc/atmos/atmos.yaml | 2 +- examples/tests/atmos.yaml | 2 +- .../rootfs/usr/local/etc/atmos/atmos.yaml | 2 +- pkg/atlantis/atmos.yaml | 2 +- pkg/aws/atmos.yaml | 2 +- pkg/component/atmos.yaml | 2 +- pkg/describe/atmos.yaml | 2 +- pkg/generate/atmos.yaml | 2 +- pkg/spacelift/atmos.yaml | 2 +- pkg/validate/atmos.yaml | 2 +- pkg/vender/atmos.yaml | 2 +- pkg/workflow/atmos.yaml | 2 +- website/docs/cli/commands/commands.mdx | 1 + website/docs/cli/configuration.mdx | 6 +- website/docs/{reference => cli}/schemas.mdx | 0 website/docs/{reference => cli}/versioning.md | 0 website/docs/core-concepts/core-concepts.mdx | 1 + .../remote-state-backend.mdx | 0 .../remote-state.mdx | 0 .../terraform-backends.mdx | 0 .../terraform-providers.mdx | 0 .../terraform-workspaces.mdx | 0 .../{reference => }/glossary/_category_.json | 0 .../glossary/abstract-component.md | 0 .../docs/{reference => }/glossary/catalog.md | 0 .../glossary/component-instance.md | 0 .../{reference => }/glossary/component.md | 0 .../glossary/concrete-component.md | 0 .../{reference => }/glossary/environment.md | 0 .../docs/{reference => }/glossary/imports.md | 0 .../docs/{reference => }/glossary/index.mdx | 0 .../{reference => }/glossary/inheritance.md | 0 .../{reference => }/glossary/integration.md | 0 .../glossary/kubernetes-namespace.mdx | 0 .../docs/{reference => }/glossary/library.md | 0 .../docs/{reference => }/glossary/mixins.md | 0 .../glossary/multiple-inheritance.md | 0 .../{reference => }/glossary/namespace.md | 0 .../{reference => }/glossary/parent-stack.md | 0 .../glossary/real-component.md | 0 .../glossary/spacelift-stack.md | 0 .../glossary/stack-manifest.md | 0 .../docs/{reference => }/glossary/stack.mdx | 0 .../docs/{reference => }/glossary/stage.md | 0 .../docs/{reference => }/glossary/tenant.md | 0 .../glossary/terraform-child-module.md | 0 .../{reference => }/glossary/vendoring.md | 0 website/docs/integrations/integrations.mdx | 1 + website/docs/introduction/cheatsheet.mdx | 2 +- website/docs/introduction/features.md | 2 +- website/docs/quick-start/configure-cli.mdx | 4 +- .../docs/quick-start/configure-validation.mdx | 8 +- website/docs/quick-start/next-steps.md | 2 +- website/docs/troubleshooting/debugging.md | 1 + website/docs/troubleshooting/errors.mdx | 4 +- .../docs/troubleshooting/troubleshooting.mdx | 14 -- website/docusaurus.config.js | 23 ++- website/sidebars.js | 160 +++++++++++++++++- website/src/css/custom.css | 29 ++++ 61 files changed, 227 insertions(+), 59 deletions(-) rename website/docs/{reference => cli}/schemas.mdx (100%) rename website/docs/{reference => cli}/versioning.md (100%) rename website/docs/core-concepts/{components => terraform}/remote-state-backend.mdx (100%) rename website/docs/core-concepts/{components => terraform}/remote-state.mdx (100%) rename website/docs/core-concepts/{components => terraform}/terraform-backends.mdx (100%) rename website/docs/core-concepts/{components => terraform}/terraform-providers.mdx (100%) rename website/docs/core-concepts/{components => terraform}/terraform-workspaces.mdx (100%) rename website/docs/{reference => }/glossary/_category_.json (100%) rename website/docs/{reference => }/glossary/abstract-component.md (100%) rename website/docs/{reference => }/glossary/catalog.md (100%) rename website/docs/{reference => }/glossary/component-instance.md (100%) rename website/docs/{reference => }/glossary/component.md (100%) rename website/docs/{reference => }/glossary/concrete-component.md (100%) rename website/docs/{reference => }/glossary/environment.md (100%) rename website/docs/{reference => }/glossary/imports.md (100%) rename website/docs/{reference => }/glossary/index.mdx (100%) rename website/docs/{reference => }/glossary/inheritance.md (100%) rename website/docs/{reference => }/glossary/integration.md (100%) rename website/docs/{reference => }/glossary/kubernetes-namespace.mdx (100%) rename website/docs/{reference => }/glossary/library.md (100%) rename website/docs/{reference => }/glossary/mixins.md (100%) rename website/docs/{reference => }/glossary/multiple-inheritance.md (100%) rename website/docs/{reference => }/glossary/namespace.md (100%) rename website/docs/{reference => }/glossary/parent-stack.md (100%) rename website/docs/{reference => }/glossary/real-component.md (100%) rename website/docs/{reference => }/glossary/spacelift-stack.md (100%) rename website/docs/{reference => }/glossary/stack-manifest.md (100%) rename website/docs/{reference => }/glossary/stack.mdx (100%) rename website/docs/{reference => }/glossary/stage.md (100%) rename website/docs/{reference => }/glossary/tenant.md (100%) rename website/docs/{reference => }/glossary/terraform-child-module.md (100%) rename website/docs/{reference => }/glossary/vendoring.md (100%) delete mode 100644 website/docs/troubleshooting/troubleshooting.mdx diff --git a/atmos.yaml b/atmos.yaml index daf33b02d..1e99c28b8 100644 --- a/atmos.yaml +++ b/atmos.yaml @@ -310,7 +310,7 @@ schemas: # Supports both absolute and relative paths base_path: "stacks/schemas/opa" # JSON Schema to validate Atmos manifests - # https://atmos.tools/reference/schemas/ + # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ # https://atmos.tools/quick-start/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json diff --git a/examples/quick-start/atmos.yaml b/examples/quick-start/atmos.yaml index b5d527c0c..fde70db91 100644 --- a/examples/quick-start/atmos.yaml +++ b/examples/quick-start/atmos.yaml @@ -243,7 +243,7 @@ schemas: # Supports both absolute and relative paths base_path: "stacks/schemas/opa" # JSON Schema to validate Atmos manifests - # https://atmos.tools/reference/schemas/ + # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ # https://atmos.tools/quick-start/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json diff --git a/examples/quick-start/rootfs/usr/local/etc/atmos/atmos.yaml b/examples/quick-start/rootfs/usr/local/etc/atmos/atmos.yaml index 4a46b977a..cc1844af8 100644 --- a/examples/quick-start/rootfs/usr/local/etc/atmos/atmos.yaml +++ b/examples/quick-start/rootfs/usr/local/etc/atmos/atmos.yaml @@ -244,7 +244,7 @@ schemas: # Supports both absolute and relative paths base_path: "stacks/schemas/opa" # JSON Schema to validate Atmos manifests - # https://atmos.tools/reference/schemas/ + # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ # https://atmos.tools/quick-start/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json diff --git a/examples/tests/atmos.yaml b/examples/tests/atmos.yaml index 4335d6a3b..0309a2dad 100644 --- a/examples/tests/atmos.yaml +++ b/examples/tests/atmos.yaml @@ -337,7 +337,7 @@ schemas: # Supports both absolute and relative paths base_path: "stacks/schemas/opa" # JSON Schema to validate Atmos manifests - # https://atmos.tools/reference/schemas/ + # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ # https://atmos.tools/quick-start/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json diff --git a/examples/tests/rootfs/usr/local/etc/atmos/atmos.yaml b/examples/tests/rootfs/usr/local/etc/atmos/atmos.yaml index 99429c306..ae696f375 100644 --- a/examples/tests/rootfs/usr/local/etc/atmos/atmos.yaml +++ b/examples/tests/rootfs/usr/local/etc/atmos/atmos.yaml @@ -585,7 +585,7 @@ schemas: # Supports both absolute and relative paths base_path: "stacks/schemas/opa" # JSON Schema to validate Atmos manifests - # https://atmos.tools/reference/schemas/ + # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ # https://atmos.tools/quick-start/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json diff --git a/pkg/atlantis/atmos.yaml b/pkg/atlantis/atmos.yaml index 06c09412f..a9711dfcf 100644 --- a/pkg/atlantis/atmos.yaml +++ b/pkg/atlantis/atmos.yaml @@ -320,7 +320,7 @@ schemas: # Supports both absolute and relative paths base_path: "stacks/schemas/opa" # JSON Schema to validate Atmos manifests - # https://atmos.tools/reference/schemas/ + # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ # https://atmos.tools/quick-start/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json diff --git a/pkg/aws/atmos.yaml b/pkg/aws/atmos.yaml index 74678242d..f27996a66 100644 --- a/pkg/aws/atmos.yaml +++ b/pkg/aws/atmos.yaml @@ -320,7 +320,7 @@ schemas: # Supports both absolute and relative paths base_path: "stacks/schemas/opa" # JSON Schema to validate Atmos manifests - # https://atmos.tools/reference/schemas/ + # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ # https://atmos.tools/quick-start/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json diff --git a/pkg/component/atmos.yaml b/pkg/component/atmos.yaml index 06c09412f..a9711dfcf 100644 --- a/pkg/component/atmos.yaml +++ b/pkg/component/atmos.yaml @@ -320,7 +320,7 @@ schemas: # Supports both absolute and relative paths base_path: "stacks/schemas/opa" # JSON Schema to validate Atmos manifests - # https://atmos.tools/reference/schemas/ + # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ # https://atmos.tools/quick-start/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json diff --git a/pkg/describe/atmos.yaml b/pkg/describe/atmos.yaml index 06c09412f..a9711dfcf 100644 --- a/pkg/describe/atmos.yaml +++ b/pkg/describe/atmos.yaml @@ -320,7 +320,7 @@ schemas: # Supports both absolute and relative paths base_path: "stacks/schemas/opa" # JSON Schema to validate Atmos manifests - # https://atmos.tools/reference/schemas/ + # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ # https://atmos.tools/quick-start/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json diff --git a/pkg/generate/atmos.yaml b/pkg/generate/atmos.yaml index 06c09412f..a9711dfcf 100644 --- a/pkg/generate/atmos.yaml +++ b/pkg/generate/atmos.yaml @@ -320,7 +320,7 @@ schemas: # Supports both absolute and relative paths base_path: "stacks/schemas/opa" # JSON Schema to validate Atmos manifests - # https://atmos.tools/reference/schemas/ + # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ # https://atmos.tools/quick-start/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json diff --git a/pkg/spacelift/atmos.yaml b/pkg/spacelift/atmos.yaml index 06c09412f..a9711dfcf 100644 --- a/pkg/spacelift/atmos.yaml +++ b/pkg/spacelift/atmos.yaml @@ -320,7 +320,7 @@ schemas: # Supports both absolute and relative paths base_path: "stacks/schemas/opa" # JSON Schema to validate Atmos manifests - # https://atmos.tools/reference/schemas/ + # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ # https://atmos.tools/quick-start/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json diff --git a/pkg/validate/atmos.yaml b/pkg/validate/atmos.yaml index 06c09412f..a9711dfcf 100644 --- a/pkg/validate/atmos.yaml +++ b/pkg/validate/atmos.yaml @@ -320,7 +320,7 @@ schemas: # Supports both absolute and relative paths base_path: "stacks/schemas/opa" # JSON Schema to validate Atmos manifests - # https://atmos.tools/reference/schemas/ + # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ # https://atmos.tools/quick-start/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json diff --git a/pkg/vender/atmos.yaml b/pkg/vender/atmos.yaml index 06c09412f..a9711dfcf 100644 --- a/pkg/vender/atmos.yaml +++ b/pkg/vender/atmos.yaml @@ -320,7 +320,7 @@ schemas: # Supports both absolute and relative paths base_path: "stacks/schemas/opa" # JSON Schema to validate Atmos manifests - # https://atmos.tools/reference/schemas/ + # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ # https://atmos.tools/quick-start/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json diff --git a/pkg/workflow/atmos.yaml b/pkg/workflow/atmos.yaml index 06c09412f..a9711dfcf 100644 --- a/pkg/workflow/atmos.yaml +++ b/pkg/workflow/atmos.yaml @@ -320,7 +320,7 @@ schemas: # Supports both absolute and relative paths base_path: "stacks/schemas/opa" # JSON Schema to validate Atmos manifests - # https://atmos.tools/reference/schemas/ + # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ # https://atmos.tools/quick-start/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json diff --git a/website/docs/cli/commands/commands.mdx b/website/docs/cli/commands/commands.mdx index ba73797b8..d75ac2c06 100644 --- a/website/docs/cli/commands/commands.mdx +++ b/website/docs/cli/commands/commands.mdx @@ -2,6 +2,7 @@ title: Atmos CLI Commands sidebar_position: 3 sidebar_label: Commands +sidebar_class_name: hidden description: Atmos CLI Commands id: commands label: Commands diff --git a/website/docs/cli/configuration.mdx b/website/docs/cli/configuration.mdx index fb5f37866..2855ecfa5 100644 --- a/website/docs/cli/configuration.mdx +++ b/website/docs/cli/configuration.mdx @@ -682,7 +682,7 @@ schemas: # Supports both absolute and relative paths base_path: "stacks/schemas/opa" # JSON Schema to validate Atmos manifests - # https://atmos.tools/reference/schemas/ + # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ # https://atmos.tools/quick-start/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json @@ -698,7 +698,7 @@ schemas: :::tip For more information, refer to: -- [Atmos Manifests Validation](/reference/schemas) +- [Atmos Manifests Validation](/cli/schemas) - [Atmos Component Validation](/core-concepts/components/validation) ::: @@ -1052,7 +1052,7 @@ setting `ATMOS_STACKS_BASE_PATH` to a path in `/localhost` to your local develop | ATMOS_WORKFLOWS_BASE_PATH | workflows.base_path | Base path to Atmos workflows | | ATMOS_SCHEMAS_JSONSCHEMA_BASE_PATH | schemas.jsonschema.base_path | Base path to JSON schemas for component validation | | ATMOS_SCHEMAS_OPA_BASE_PATH | schemas.opa.base_path | Base path to OPA policies for component validation | -| ATMOS_SCHEMAS_ATMOS_MANIFEST | schemas.atmos.manifest | Path to JSON Schema to validate Atmos stack manifests. For more details, refer to [Atmos Manifest JSON Schema](/reference/schemas) | +| ATMOS_SCHEMAS_ATMOS_MANIFEST | schemas.atmos.manifest | Path to JSON Schema to validate Atmos stack manifests. For more details, refer to [Atmos Manifest JSON Schema](/cli/schemas) | | ATMOS_LOGS_FILE | logs.file | The file to write Atmos logs to. Logs can be written to any file or any standard file descriptor, including `/dev/stdout`, `/dev/stderr` and `/dev/null`). If omitted, `/dev/stdout` will be used | | ATMOS_LOGS_LEVEL | logs.level | Logs level. Supported log levels are `Trace`, `Debug`, `Info`, `Warning`, `Off`. If the log level is set to `Off`, Atmos will not log any messages (note that this does not prevent other tools like Terraform from logging) | | ATMOS_SETTINGS_LIST_MERGE_STRATEGY | settings.list_merge_strategy | Specifies how lists are merged in Atmos stack manifests. The following strategies are supported: `replace`, `append`, `merge` | diff --git a/website/docs/reference/schemas.mdx b/website/docs/cli/schemas.mdx similarity index 100% rename from website/docs/reference/schemas.mdx rename to website/docs/cli/schemas.mdx diff --git a/website/docs/reference/versioning.md b/website/docs/cli/versioning.md similarity index 100% rename from website/docs/reference/versioning.md rename to website/docs/cli/versioning.md diff --git a/website/docs/core-concepts/core-concepts.mdx b/website/docs/core-concepts/core-concepts.mdx index cf8d07912..bd935a859 100644 --- a/website/docs/core-concepts/core-concepts.mdx +++ b/website/docs/core-concepts/core-concepts.mdx @@ -2,6 +2,7 @@ title: Core Concepts sidebar_position: 3 sidebar_label: Core Concepts +sidebar_class_name: hidden description: Atmos Core Concepts id: core-concepts --- diff --git a/website/docs/core-concepts/components/remote-state-backend.mdx b/website/docs/core-concepts/terraform/remote-state-backend.mdx similarity index 100% rename from website/docs/core-concepts/components/remote-state-backend.mdx rename to website/docs/core-concepts/terraform/remote-state-backend.mdx diff --git a/website/docs/core-concepts/components/remote-state.mdx b/website/docs/core-concepts/terraform/remote-state.mdx similarity index 100% rename from website/docs/core-concepts/components/remote-state.mdx rename to website/docs/core-concepts/terraform/remote-state.mdx diff --git a/website/docs/core-concepts/components/terraform-backends.mdx b/website/docs/core-concepts/terraform/terraform-backends.mdx similarity index 100% rename from website/docs/core-concepts/components/terraform-backends.mdx rename to website/docs/core-concepts/terraform/terraform-backends.mdx diff --git a/website/docs/core-concepts/components/terraform-providers.mdx b/website/docs/core-concepts/terraform/terraform-providers.mdx similarity index 100% rename from website/docs/core-concepts/components/terraform-providers.mdx rename to website/docs/core-concepts/terraform/terraform-providers.mdx diff --git a/website/docs/core-concepts/components/terraform-workspaces.mdx b/website/docs/core-concepts/terraform/terraform-workspaces.mdx similarity index 100% rename from website/docs/core-concepts/components/terraform-workspaces.mdx rename to website/docs/core-concepts/terraform/terraform-workspaces.mdx diff --git a/website/docs/reference/glossary/_category_.json b/website/docs/glossary/_category_.json similarity index 100% rename from website/docs/reference/glossary/_category_.json rename to website/docs/glossary/_category_.json diff --git a/website/docs/reference/glossary/abstract-component.md b/website/docs/glossary/abstract-component.md similarity index 100% rename from website/docs/reference/glossary/abstract-component.md rename to website/docs/glossary/abstract-component.md diff --git a/website/docs/reference/glossary/catalog.md b/website/docs/glossary/catalog.md similarity index 100% rename from website/docs/reference/glossary/catalog.md rename to website/docs/glossary/catalog.md diff --git a/website/docs/reference/glossary/component-instance.md b/website/docs/glossary/component-instance.md similarity index 100% rename from website/docs/reference/glossary/component-instance.md rename to website/docs/glossary/component-instance.md diff --git a/website/docs/reference/glossary/component.md b/website/docs/glossary/component.md similarity index 100% rename from website/docs/reference/glossary/component.md rename to website/docs/glossary/component.md diff --git a/website/docs/reference/glossary/concrete-component.md b/website/docs/glossary/concrete-component.md similarity index 100% rename from website/docs/reference/glossary/concrete-component.md rename to website/docs/glossary/concrete-component.md diff --git a/website/docs/reference/glossary/environment.md b/website/docs/glossary/environment.md similarity index 100% rename from website/docs/reference/glossary/environment.md rename to website/docs/glossary/environment.md diff --git a/website/docs/reference/glossary/imports.md b/website/docs/glossary/imports.md similarity index 100% rename from website/docs/reference/glossary/imports.md rename to website/docs/glossary/imports.md diff --git a/website/docs/reference/glossary/index.mdx b/website/docs/glossary/index.mdx similarity index 100% rename from website/docs/reference/glossary/index.mdx rename to website/docs/glossary/index.mdx diff --git a/website/docs/reference/glossary/inheritance.md b/website/docs/glossary/inheritance.md similarity index 100% rename from website/docs/reference/glossary/inheritance.md rename to website/docs/glossary/inheritance.md diff --git a/website/docs/reference/glossary/integration.md b/website/docs/glossary/integration.md similarity index 100% rename from website/docs/reference/glossary/integration.md rename to website/docs/glossary/integration.md diff --git a/website/docs/reference/glossary/kubernetes-namespace.mdx b/website/docs/glossary/kubernetes-namespace.mdx similarity index 100% rename from website/docs/reference/glossary/kubernetes-namespace.mdx rename to website/docs/glossary/kubernetes-namespace.mdx diff --git a/website/docs/reference/glossary/library.md b/website/docs/glossary/library.md similarity index 100% rename from website/docs/reference/glossary/library.md rename to website/docs/glossary/library.md diff --git a/website/docs/reference/glossary/mixins.md b/website/docs/glossary/mixins.md similarity index 100% rename from website/docs/reference/glossary/mixins.md rename to website/docs/glossary/mixins.md diff --git a/website/docs/reference/glossary/multiple-inheritance.md b/website/docs/glossary/multiple-inheritance.md similarity index 100% rename from website/docs/reference/glossary/multiple-inheritance.md rename to website/docs/glossary/multiple-inheritance.md diff --git a/website/docs/reference/glossary/namespace.md b/website/docs/glossary/namespace.md similarity index 100% rename from website/docs/reference/glossary/namespace.md rename to website/docs/glossary/namespace.md diff --git a/website/docs/reference/glossary/parent-stack.md b/website/docs/glossary/parent-stack.md similarity index 100% rename from website/docs/reference/glossary/parent-stack.md rename to website/docs/glossary/parent-stack.md diff --git a/website/docs/reference/glossary/real-component.md b/website/docs/glossary/real-component.md similarity index 100% rename from website/docs/reference/glossary/real-component.md rename to website/docs/glossary/real-component.md diff --git a/website/docs/reference/glossary/spacelift-stack.md b/website/docs/glossary/spacelift-stack.md similarity index 100% rename from website/docs/reference/glossary/spacelift-stack.md rename to website/docs/glossary/spacelift-stack.md diff --git a/website/docs/reference/glossary/stack-manifest.md b/website/docs/glossary/stack-manifest.md similarity index 100% rename from website/docs/reference/glossary/stack-manifest.md rename to website/docs/glossary/stack-manifest.md diff --git a/website/docs/reference/glossary/stack.mdx b/website/docs/glossary/stack.mdx similarity index 100% rename from website/docs/reference/glossary/stack.mdx rename to website/docs/glossary/stack.mdx diff --git a/website/docs/reference/glossary/stage.md b/website/docs/glossary/stage.md similarity index 100% rename from website/docs/reference/glossary/stage.md rename to website/docs/glossary/stage.md diff --git a/website/docs/reference/glossary/tenant.md b/website/docs/glossary/tenant.md similarity index 100% rename from website/docs/reference/glossary/tenant.md rename to website/docs/glossary/tenant.md diff --git a/website/docs/reference/glossary/terraform-child-module.md b/website/docs/glossary/terraform-child-module.md similarity index 100% rename from website/docs/reference/glossary/terraform-child-module.md rename to website/docs/glossary/terraform-child-module.md diff --git a/website/docs/reference/glossary/vendoring.md b/website/docs/glossary/vendoring.md similarity index 100% rename from website/docs/reference/glossary/vendoring.md rename to website/docs/glossary/vendoring.md diff --git a/website/docs/integrations/integrations.mdx b/website/docs/integrations/integrations.mdx index a56884425..e8b9c034c 100644 --- a/website/docs/integrations/integrations.mdx +++ b/website/docs/integrations/integrations.mdx @@ -2,6 +2,7 @@ title: Integrations sidebar_position: 6 sidebar_label: Integrations +sidebar_class_name: hidden command description: Atmos supports many native Atmos integrations. They extend the core functionality of Atmos. id: integrations --- diff --git a/website/docs/introduction/cheatsheet.mdx b/website/docs/introduction/cheatsheet.mdx index baf94bc46..4f4cc8a29 100644 --- a/website/docs/introduction/cheatsheet.mdx +++ b/website/docs/introduction/cheatsheet.mdx @@ -3,7 +3,7 @@ id: cheatsheet slug: /cheatsheet title: Atmos Cheatsheet sidebar_label: Cheatsheet -sidebar_position: 2 +sidebar_position: 5 --- import Link from '@docusaurus/Link' import Card from '@site/src/components/Card' diff --git a/website/docs/introduction/features.md b/website/docs/introduction/features.md index 5b3da6643..cc3cb6c99 100644 --- a/website/docs/introduction/features.md +++ b/website/docs/introduction/features.md @@ -2,7 +2,7 @@ slug: /features title: Atmos Features sidebar_label: Features -sidebar_position: 1 +sidebar_position: 2 --- Atmos streamlines Terraform orchestration, environment, and configuration management, offering developers and DevOps a set of diff --git a/website/docs/quick-start/configure-cli.mdx b/website/docs/quick-start/configure-cli.mdx index 3e2e0a13b..d25bafb85 100644 --- a/website/docs/quick-start/configure-cli.mdx +++ b/website/docs/quick-start/configure-cli.mdx @@ -104,7 +104,7 @@ schemas: # Supports both absolute and relative paths base_path: "stacks/schemas/opa" # JSON Schema to validate Atmos manifests - # https://atmos.tools/reference/schemas/ + # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ # https://atmos.tools/quick-start/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json @@ -171,5 +171,5 @@ to [CLI Configuration](/cli/configuration). - `commands` - configuration for [Atmos Custom Commands](/core-concepts/custom-commands) - `schemas` - [JSON Schema](https://json-schema.org/) and [OPA Policy](https://www.openpolicyagent.org/) configurations for: - - [Atmos Manifests Validation](/reference/schemas) + - [Atmos Manifests Validation](/cli/schemas) - [Atmos Components Validation](/core-concepts/components/validation) diff --git a/website/docs/quick-start/configure-validation.mdx b/website/docs/quick-start/configure-validation.mdx index a39f4e045..eac7cca09 100644 --- a/website/docs/quick-start/configure-validation.mdx +++ b/website/docs/quick-start/configure-validation.mdx @@ -4,7 +4,7 @@ sidebar_position: 7 sidebar_label: Configure Validation --- -Atmos supports [Atmos Manifests Validation](/reference/schemas) and [Atmos Components Validation](/core-concepts/components/validation) +Atmos supports [Atmos Manifests Validation](/cli/schemas) and [Atmos Components Validation](/core-concepts/components/validation) using [JSON Schema](https://json-schema.org/) and [OPA Policies](https://www.openpolicyagent.org/). :::tip @@ -43,7 +43,7 @@ schemas: # Supports both absolute and relative paths base_path: "stacks/schemas/opa" # JSON Schema to validate Atmos manifests - # https://atmos.tools/reference/schemas/ + # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ # https://atmos.tools/quick-start/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json @@ -78,7 +78,7 @@ Complete the following steps to configure Atmos manifest validation: in [`stacks/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json`](https://github.com/cloudposse/atmos/blob/master/examples/quick-start/stacks/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json) - Configure the `schemas.atmos.manifest` section in the `atmos.yaml` [CLI config file](/cli/configuration) as described - in [Atmos Manifests Validation using JSON Schema](/reference/schemas) + in [Atmos Manifests Validation using JSON Schema](/cli/schemas) ```yaml title="atmos.yaml" # Validation schemas (for validating atmos stacks and components) @@ -106,7 +106,7 @@ Complete the following steps to configure Atmos manifest validation: For more information, refer to: -- [Atmos Manifests Validation using JSON Schema](/reference/schemas) +- [Atmos Manifests Validation using JSON Schema](/cli/schemas) - [atmos validate stacks](/cli/commands/validate/stacks) ::: diff --git a/website/docs/quick-start/next-steps.md b/website/docs/quick-start/next-steps.md index ccc8cd2b2..8bb69b467 100644 --- a/website/docs/quick-start/next-steps.md +++ b/website/docs/quick-start/next-steps.md @@ -21,4 +21,4 @@ Here are some of the major differentiators of Atmos: * [Custom Commands](/core-concepts/custom-commands) * [Component Inheritance & Multiple Inheritance](/core-concepts/components/inheritance) * [JSON Schema & OPA Policy Enforcement](/core-concepts/components/validation) -* [Atmos Manifest JSON Schema](/reference/schemas) +* [Atmos Manifest JSON Schema](/cli/schemas) diff --git a/website/docs/troubleshooting/debugging.md b/website/docs/troubleshooting/debugging.md index 4c18d7f69..1d78f5394 100644 --- a/website/docs/troubleshooting/debugging.md +++ b/website/docs/troubleshooting/debugging.md @@ -2,6 +2,7 @@ title: Debugging sidebar_position: 2 sidebar_label: Debugging +sidebar_class_name: hidden --- :::note diff --git a/website/docs/troubleshooting/errors.mdx b/website/docs/troubleshooting/errors.mdx index bfe553d8d..5135076ad 100644 --- a/website/docs/troubleshooting/errors.mdx +++ b/website/docs/troubleshooting/errors.mdx @@ -1,7 +1,7 @@ --- -title: Errors +title: Common Errors sidebar_position: 1 -sidebar_label: Errors +sidebar_label: Common Errors --- ## Common Mistakes diff --git a/website/docs/troubleshooting/troubleshooting.mdx b/website/docs/troubleshooting/troubleshooting.mdx deleted file mode 100644 index 64a7145d5..000000000 --- a/website/docs/troubleshooting/troubleshooting.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Troubleshooting -sidebar_position: 9 -sidebar_label: Troubleshooting -description: Troubleshooting -id: troubleshooting ---- - -# Troubleshooting - - -import DocCardList from "@theme/DocCardList"; - - diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 7b3ced105..029a0717d 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -117,37 +117,34 @@ const config = { type: 'doc', docId: 'introduction/index', position: 'left', - label: 'Docs', + label: 'Learn', }, { to: '/cli', position: 'left', - label: 'CLI' + label: 'Reference' }, { type: 'dropdown', label: 'Community', - position: 'right', + position: 'left', items: [ { - label: 'GitHub Discussions', - href: 'https://ask.sweetops.com/', - }, - { - label: 'Community', - href: 'https://sweetops.com/', + label: 'Weekly Office Hours', + href: 'https://cloudposse.com/office-hours/', }, { - label: 'Slack', - href: 'https://slack.sweetops.com/', + label: 'Slack Community', + href: 'https://slack.cloudposse.com/', }, { label: 'Slack Archives', href: 'https://archive.sweetops.com/atmos/', }, { - label: 'Office Hours', - href: 'https://cloudposse.com/office-hours/', + label: 'Contributing', + type: 'doc', + docId: 'contributing/contributing', }, ], }, diff --git a/website/sidebars.js b/website/sidebars.js index 330b8413e..b8c1a5b04 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -12,16 +12,168 @@ // @ts-check module.exports = { + tutorials: [ + { + type: 'category', + label: 'Tutorials Index Page', + link: { + type: 'doc', + id: 'tutorials/tutorials' + }, + items: [ + { + type: 'autogenerated', + dirName: 'tutorials', + } + ] + } + ], + contributing: [ + { + type: 'category', + label: 'Contributing Index Page', + link: { + type: 'doc', + id: 'contributing/contributing' + }, + items: [ + { + type: 'autogenerated', + dirName: 'contributing', + } + ] + } + ], docs: [ + { - type: 'autogenerated', - dirName: '.', + type: 'category', + label: 'Get Started', + className: 'sidebar-title', + collapsible: false, + collapsed: false, + items: [ + { + type: 'autogenerated', + dirName: 'introduction', + }, + { + type: 'category', + label: 'Quick Start', + collapsible: true, + collapsed: false, + items: [ + { + type: 'autogenerated', + dirName: 'quick-start', + }, + ] + }, + ] }, + + ,/* + { + type: 'html', + value: 'Core Concepts', + className: 'sidebar-title', + },*/ + { + type: 'category', + label: 'Learn Atmos', + className: 'sidebar-title', + collapsible: false, + collapsed: false, + items: [ + { + type: 'autogenerated', + dirName: 'core-concepts', + }, + { + type: 'category', + label: 'Design Patterns', + collapsible: true, + collapsed: true, + items: [ + { + type: 'autogenerated', + dirName: 'design-patterns', + }, + ] + }, + { + type: 'category', + label: 'Trouble Shooting', + collapsible: true, + collapsed: true, + items: [ + { + type: 'autogenerated', + dirName: 'troubleshooting', + }, + ] + } + ] + } ], cli: [ { - type: 'autogenerated', - dirName: 'cli', + type: 'category', + label: 'Configuration', + className: 'sidebar-title', + collapsible: false, + collapsed: false, + items: [ + { + type: 'autogenerated', + dirName: 'cli', + }, + ] + }, + + { + type: 'category', + label: 'Commands', + className: 'sidebar-title', + collapsible: false, + collapsed: false, + link: {type: 'doc', id: 'cli/commands/commands'}, + items: [ + { + type: 'autogenerated', + dirName: 'cli/commands', + }, + ] + }, + { + type: 'category', + label: 'Integrations', + className: 'sidebar-title', + collapsible: false, + collapsed: false, + link: {type: 'doc', id: 'integrations/integrations'}, + items: [ + { + type: 'autogenerated', + dirName: 'integrations', + }, + ] }, + { + type: 'category', + label: 'Reference', + className: 'sidebar-title', + collapsible: false, + collapsed: false, + items: [ + { + type: 'autogenerated', + dirName: 'reference', + }, + ] + }, + + + ] }; diff --git a/website/src/css/custom.css b/website/src/css/custom.css index 9b173d35e..d0fc622ee 100644 --- a/website/src/css/custom.css +++ b/website/src/css/custom.css @@ -101,6 +101,35 @@ nav.navbar { } */ +li.sidebar-title > div > a.menu__link { + text-transform: uppercase; + color: #b1b1b1; +} + +li.sidebar-title { + border-top: 1px solid #6666663b; + padding-top: 1.2em; + margin-top: 1.2em; +} + +li.sidebar-title:first-child { + border-top: none; + margin-top: inherit; +} + +li.sidebar-title.menu__list-item:not(:first-child) { + margin-top: 1.2em !important; +} + +li.sidebar-title > ul:first .menu__list .menu__list { + padding-left: 0; +} + +.sidebar-title > ul.menu__list { + margin-left: 0; + padding-left: 0; +} + .menu__caret:before { background: var(--ifm-menu-link-sublist-icon) 50% / 2rem 1.5rem; } From 3c4d58520a05726fa8a0084bf180162e624f2fac Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Sat, 1 Jun 2024 15:12:23 -0500 Subject: [PATCH 002/151] Another big sweep of reorganization --- README.md | 6 +- README.yaml | 6 +- atmos.yaml | 2 +- cmd/cmd_utils.go | 2 +- examples/quick-start/atmos.yaml | 2 +- .../rootfs/usr/local/etc/atmos/atmos.yaml | 2 +- .../stacks/orgs/acme/_defaults.yaml | 2 +- examples/tests/atmos.yaml | 2 +- .../rootfs/usr/local/etc/atmos/atmos.yaml | 2 +- internal/exec/validate_stacks.go | 2 +- pkg/atlantis/atmos.yaml | 2 +- pkg/aws/atmos.yaml | 2 +- pkg/component/atmos.yaml | 2 +- pkg/describe/atmos.yaml | 2 +- pkg/generate/atmos.yaml | 2 +- pkg/spacelift/atmos.yaml | 2 +- pkg/validate/atmos.yaml | 2 +- pkg/vender/atmos.yaml | 2 +- pkg/workflow/atmos.yaml | 2 +- .../cheatsheet.mdx => cheatsheets/common.mdx} | 6 +- .../components.mdx} | 45 +---- website/docs/cheatsheets/stacks.mdx | 84 ++++++++++ .../vendoring.mdx} | 6 +- .../commands/describe/describe-component.mdx | 10 +- .../cli/commands/validate/validate-stacks.mdx | 2 +- .../docs/cli/commands/vendor/vendor-pull.mdx | 2 +- website/docs/cli/commands/version.mdx | 2 +- website/docs/cli/configuration.mdx | 4 +- .../component-oriented-programming.md | 4 +- .../core-concepts/components/components.mdx | 120 +------------- .../terraform/backends.mdx} | 6 +- .../components/terraform/journey.mdx} | 76 ++------- .../terraform/providers.mdx} | 6 +- .../terraform/remote-state-backend.mdx | 16 +- .../terraform/remote-state.mdx | 0 .../components/terraform/terraform.mdx | 81 +++++++++ .../terraform/workspaces.mdx} | 4 +- .../custom-commands/custom-commands.mdx | 3 +- .../components.mdx} | 12 +- .../core-concepts/describing/describing.mdx | 18 ++ .../stacks.mdx} | 4 +- website/docs/core-concepts/stacks/catalogs.md | 2 +- .../stacks/define-components.mdx | 138 ++++++++++++++++ website/docs/core-concepts/stacks/imports.mdx | 10 +- .../inheritance.mdx} | 4 +- .../overrides.mdx} | 6 +- website/docs/core-concepts/stacks/stacks.mdx | 10 +- .../docs/core-concepts/stacks/templating.mdx | 12 +- .../components.mdx} | 4 +- .../validation.mdx => validating/stacks.mdx} | 6 +- .../components.mdx} | 4 +- .../core-concepts/vendoring/vendoring.mdx | 5 +- .../core-concepts/workflows/workflows.mdx | 4 +- .../design-patterns/abstract-component.mdx | 2 +- .../design-patterns/component-inheritance.mdx | 4 +- .../design-patterns/component-overrides.mdx | 2 +- .../docs/design-patterns/design-patterns.mdx | 2 +- .../partial-component-configuration.mdx | 4 +- .../github-actions/atmos-terraform-plan.mdx | 155 ++++++++++++++---- .../github-actions/setup-atmos.mdx | 2 +- website/docs/introduction/faq.mdx | 4 +- website/docs/introduction/index.mdx | 2 +- website/docs/introduction/use-cases.md | 6 +- .../{ => advanced}/add-custom-commands.mdx | 0 .../docs/quick-start/advanced/advanced.mdx | 42 +++++ .../{ => advanced}/configure-cli.mdx | 10 +- .../{ => advanced}/configure-repository.md | 4 +- .../configure-terraform-backend.mdx | 4 +- .../{ => advanced}/configure-validation.mdx | 10 +- .../{ => advanced}/create-atmos-stacks.mdx | 4 +- .../{ => advanced}/create-workflows.mdx | 0 .../{ => advanced}/final-notes.mdx | 0 .../quick-start/{ => advanced}/next-steps.md | 6 +- .../quick-start/{ => advanced}/provision.md | 4 +- .../{ => advanced}/vendor-components.mdx | 2 +- website/docs/quick-start/install-atmos.mdx | 1 + website/docs/quick-start/introduction.md | 31 +--- website/docs/reference/alternatives.md | 51 +++++- website/docusaurus.config.js | 8 +- website/sidebars.js | 16 +- .../components/screengrabs/atmos-version.html | 2 +- website/src/pages/index.js | 2 +- 82 files changed, 718 insertions(+), 424 deletions(-) rename website/docs/{introduction/cheatsheet.mdx => cheatsheets/common.mdx} (98%) rename website/docs/{core-concepts/components/component-cheatsheet.mdx => cheatsheets/components.mdx} (71%) create mode 100644 website/docs/cheatsheets/stacks.mdx rename website/docs/{core-concepts/vendoring/cheatsheet.mdx => cheatsheets/vendoring.mdx} (96%) rename website/docs/core-concepts/{terraform/terraform-backends.mdx => components/terraform/backends.mdx} (99%) rename website/docs/{reference/terraform-limitations.md => core-concepts/components/terraform/journey.mdx} (72%) rename website/docs/core-concepts/{terraform/terraform-providers.mdx => components/terraform/providers.mdx} (96%) rename website/docs/core-concepts/{ => components}/terraform/remote-state-backend.mdx (95%) rename website/docs/core-concepts/{ => components}/terraform/remote-state.mdx (100%) create mode 100644 website/docs/core-concepts/components/terraform/terraform.mdx rename website/docs/core-concepts/{terraform/terraform-workspaces.mdx => components/terraform/workspaces.mdx} (98%) rename website/docs/core-concepts/{components/describe-component.mdx => describing/components.mdx} (81%) create mode 100644 website/docs/core-concepts/describing/describing.mdx rename website/docs/core-concepts/{stacks/describe-stacks.mdx => describing/stacks.mdx} (99%) create mode 100644 website/docs/core-concepts/stacks/define-components.mdx rename website/docs/core-concepts/{components/component-inheritance.mdx => stacks/inheritance.mdx} (99%) rename website/docs/core-concepts/{components/component-overrides.mdx => stacks/overrides.mdx} (98%) rename website/docs/core-concepts/{components/component-validation.mdx => validating/components.mdx} (99%) rename website/docs/core-concepts/{stacks/validation.mdx => validating/stacks.mdx} (95%) rename website/docs/core-concepts/{components/component-vendoring.md => vendoring/components.mdx} (99%) rename website/docs/quick-start/{ => advanced}/add-custom-commands.mdx (100%) create mode 100644 website/docs/quick-start/advanced/advanced.mdx rename website/docs/quick-start/{ => advanced}/configure-cli.mdx (94%) rename website/docs/quick-start/{ => advanced}/configure-repository.md (98%) rename website/docs/quick-start/{ => advanced}/configure-terraform-backend.mdx (98%) rename website/docs/quick-start/{ => advanced}/configure-validation.mdx (93%) rename website/docs/quick-start/{ => advanced}/create-atmos-stacks.mdx (98%) rename website/docs/quick-start/{ => advanced}/create-workflows.mdx (100%) rename website/docs/quick-start/{ => advanced}/final-notes.mdx (100%) rename website/docs/quick-start/{ => advanced}/next-steps.md (80%) rename website/docs/quick-start/{ => advanced}/provision.md (92%) rename website/docs/quick-start/{ => advanced}/vendor-components.mdx (99%) diff --git a/README.md b/README.md index 677c43035..cef44f3d1 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ Its strength in managing [DRY configurations at scale](https://atmos.tools/core- [design patterns](https://atmos.tools/design-patterns/), comprehensive [documentation](https://atmos.tools/), and a [passionate community](https://slack.cloudposse.com/), making it a versatile [tool for both startups and enterprises](https://cloudposse.com/). Atmos is extensible to accommodate any tooling, including enterprise-scale Terraform, and includes -[policy controls](https://atmos.tools/core-concepts/components/validation), [vendoring](https://atmos.tools/core-concepts/vendoring/), +[policy controls](https://atmos.tools/core-concepts/validating/components), [vendoring](https://atmos.tools/core-concepts/vendoring/), and [GitOps capabilities](https://atmos.tools/integrations/github-actions) out of the box. Everything is open source and free. ## Screenshots @@ -105,11 +105,11 @@ strength in the cloud infrastructure and DevOps domains: configuration, bypassing the need for further code development. - **Efficient Multi-Region Deployments:** Atmos facilitates streamlined multi-region deployments by enabling businesses to define baseline configurations with [stacks](https://atmos.tools/core-concepts/stacks/) and extend them across regions with DRY principles through - [imports](https://atmos.tools/core-concepts/stacks/imports) and [inheritance](https://atmos.tools/core-concepts/components/inheritance). + [imports](https://atmos.tools/core-concepts/stacks/imports) and [inheritance](https://atmos.tools/core-concepts/stacks/inheritance). - **Compliant Infrastructure for Regulated Industries:** Atmos empowers DevOps and SecOps teams to create vetted configurations that comply with SOC2, HIPAA, HITRUST, PCI, and other regulatory standards. These configurations can then be efficiently shared and reused across the organization via [service catalogs](https://atmos.tools/core-concepts/stacks/catalogs), [component libraries](https://atmos.tools/core-concepts/components/library), - [vendoring](https://atmos.tools/core-concepts/vendoring), and [OPA policies](https://atmos.tools/core-concepts/components/validation), + [vendoring](https://atmos.tools/core-concepts/vendoring), and [OPA policies](https://atmos.tools/core-concepts/validating/components), simplifying the process of achieving and maintaining rigorous compliance. - **Empowering Teams with Self-Service Infrastructure:** Allows teams to manage their infrastructure needs independently, using predefined templates and policies. diff --git a/README.yaml b/README.yaml index 5200e89f3..a7e3471a5 100644 --- a/README.yaml +++ b/README.yaml @@ -46,7 +46,7 @@ description: |- [design patterns](https://atmos.tools/design-patterns/), comprehensive [documentation](https://atmos.tools/), and a [passionate community](https://slack.cloudposse.com/), making it a versatile [tool for both startups and enterprises](https://cloudposse.com/). Atmos is extensible to accommodate any tooling, including enterprise-scale Terraform, and includes - [policy controls](https://atmos.tools/core-concepts/components/validation), [vendoring](https://atmos.tools/core-concepts/vendoring/), + [policy controls](https://atmos.tools/core-concepts/validating/components), [vendoring](https://atmos.tools/core-concepts/vendoring/), and [GitOps capabilities](https://atmos.tools/integrations/github-actions) out of the box. Everything is open source and free. introduction: |- @@ -101,11 +101,11 @@ introduction: |- configuration, bypassing the need for further code development. - **Efficient Multi-Region Deployments:** Atmos facilitates streamlined multi-region deployments by enabling businesses to define baseline configurations with [stacks](https://atmos.tools/core-concepts/stacks/) and extend them across regions with DRY principles through - [imports](https://atmos.tools/core-concepts/stacks/imports) and [inheritance](https://atmos.tools/core-concepts/components/inheritance). + [imports](https://atmos.tools/core-concepts/stacks/imports) and [inheritance](https://atmos.tools/core-concepts/stacks/inheritance). - **Compliant Infrastructure for Regulated Industries:** Atmos empowers DevOps and SecOps teams to create vetted configurations that comply with SOC2, HIPAA, HITRUST, PCI, and other regulatory standards. These configurations can then be efficiently shared and reused across the organization via [service catalogs](https://atmos.tools/core-concepts/stacks/catalogs), [component libraries](https://atmos.tools/core-concepts/components/library), - [vendoring](https://atmos.tools/core-concepts/vendoring), and [OPA policies](https://atmos.tools/core-concepts/components/validation), + [vendoring](https://atmos.tools/core-concepts/vendoring), and [OPA policies](https://atmos.tools/core-concepts/validating/components), simplifying the process of achieving and maintaining rigorous compliance. - **Empowering Teams with Self-Service Infrastructure:** Allows teams to manage their infrastructure needs independently, using predefined templates and policies. diff --git a/atmos.yaml b/atmos.yaml index 1e99c28b8..5b23908c0 100644 --- a/atmos.yaml +++ b/atmos.yaml @@ -312,7 +312,7 @@ schemas: # JSON Schema to validate Atmos manifests # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ - # https://atmos.tools/quick-start/configure-validation/ + # https://atmos.tools/quick-start/advanced/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json # https://json-schema.org/draft/2020-12/release-notes # https://www.schemastore.org/json diff --git a/cmd/cmd_utils.go b/cmd/cmd_utils.go index e59ef46d5..93188ca75 100644 --- a/cmd/cmd_utils.go +++ b/cmd/cmd_utils.go @@ -383,5 +383,5 @@ func printMessageToUpgradeToAtmosLatestRelease(latestVersion string) { u.PrintMessage("https://github.com/cloudposse/atmos/releases\n") u.PrintMessageInColor("Install Atmos:\n", c2) - u.PrintMessage("https://atmos.tools/quick-start/install-atmos\n") + u.PrintMessage("https://atmos.tools/install\n") } diff --git a/examples/quick-start/atmos.yaml b/examples/quick-start/atmos.yaml index fde70db91..7a64972c1 100644 --- a/examples/quick-start/atmos.yaml +++ b/examples/quick-start/atmos.yaml @@ -245,7 +245,7 @@ schemas: # JSON Schema to validate Atmos manifests # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ - # https://atmos.tools/quick-start/configure-validation/ + # https://atmos.tools/quick-start/advanced/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json # https://json-schema.org/draft/2020-12/release-notes # https://www.schemastore.org/json diff --git a/examples/quick-start/rootfs/usr/local/etc/atmos/atmos.yaml b/examples/quick-start/rootfs/usr/local/etc/atmos/atmos.yaml index cc1844af8..8c15f64a5 100644 --- a/examples/quick-start/rootfs/usr/local/etc/atmos/atmos.yaml +++ b/examples/quick-start/rootfs/usr/local/etc/atmos/atmos.yaml @@ -246,7 +246,7 @@ schemas: # JSON Schema to validate Atmos manifests # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ - # https://atmos.tools/quick-start/configure-validation/ + # https://atmos.tools/quick-start/advanced/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json # https://json-schema.org/draft/2020-12/release-notes # https://www.schemastore.org/json diff --git a/examples/quick-start/stacks/orgs/acme/_defaults.yaml b/examples/quick-start/stacks/orgs/acme/_defaults.yaml index e513fa021..c9dbc7776 100644 --- a/examples/quick-start/stacks/orgs/acme/_defaults.yaml +++ b/examples/quick-start/stacks/orgs/acme/_defaults.yaml @@ -29,7 +29,7 @@ terraform: atmos_component_description: "{{ strings.Title .atmos_component }} component {{ .vars.name | strings.Quote }} provisioned in the stack {{ .atmos_stack | strings.Quote }}" # Terraform backend configuration - # https://atmos.tools/core-concepts/components/terraform-backends + # https://atmos.tools/core-concepts/components/terraform/backends # https://developer.hashicorp.com/terraform/language/settings/backends/configuration # backend_type: cloud # s3, cloud # backend: diff --git a/examples/tests/atmos.yaml b/examples/tests/atmos.yaml index 0309a2dad..21233bea1 100644 --- a/examples/tests/atmos.yaml +++ b/examples/tests/atmos.yaml @@ -339,7 +339,7 @@ schemas: # JSON Schema to validate Atmos manifests # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ - # https://atmos.tools/quick-start/configure-validation/ + # https://atmos.tools/quick-start/advanced/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json # https://json-schema.org/draft/2020-12/release-notes # https://www.schemastore.org/json diff --git a/examples/tests/rootfs/usr/local/etc/atmos/atmos.yaml b/examples/tests/rootfs/usr/local/etc/atmos/atmos.yaml index ae696f375..ee24167f4 100644 --- a/examples/tests/rootfs/usr/local/etc/atmos/atmos.yaml +++ b/examples/tests/rootfs/usr/local/etc/atmos/atmos.yaml @@ -587,7 +587,7 @@ schemas: # JSON Schema to validate Atmos manifests # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ - # https://atmos.tools/quick-start/configure-validation/ + # https://atmos.tools/quick-start/advanced/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json # https://json-schema.org/draft/2020-12/release-notes # https://www.schemastore.org/json diff --git a/internal/exec/validate_stacks.go b/internal/exec/validate_stacks.go index ab231d6b6..8088bd3ff 100644 --- a/internal/exec/validate_stacks.go +++ b/internal/exec/validate_stacks.go @@ -325,7 +325,7 @@ func checkComponentStackMap(componentStackMap map[string]map[string][]string) ([ "Consider the following solutions to fix the issue:\n"+ "- Ensure that the same instance of the Atmos '%[1]s' component in the stack '%[2]s' is only defined once (in one YAML stack manifest file)\n"+ "- When defining multiple instances of the same component in the stack, ensure each has a unique name\n"+ - "- Use multiple-inheritance to combine multiple configurations together (refer to https://atmos.tools/core-concepts/components/inheritance)\n\n", + "- Use multiple-inheritance to combine multiple configurations together (refer to https://atmos.tools/core-concepts/stacks/inheritance)\n\n", componentName, stackName, strings.Join(stackManifests, ", "), diff --git a/pkg/atlantis/atmos.yaml b/pkg/atlantis/atmos.yaml index a9711dfcf..b057d5ed8 100644 --- a/pkg/atlantis/atmos.yaml +++ b/pkg/atlantis/atmos.yaml @@ -322,7 +322,7 @@ schemas: # JSON Schema to validate Atmos manifests # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ - # https://atmos.tools/quick-start/configure-validation/ + # https://atmos.tools/quick-start/advanced/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json # https://json-schema.org/draft/2020-12/release-notes # https://www.schemastore.org/json diff --git a/pkg/aws/atmos.yaml b/pkg/aws/atmos.yaml index f27996a66..47ee281ae 100644 --- a/pkg/aws/atmos.yaml +++ b/pkg/aws/atmos.yaml @@ -322,7 +322,7 @@ schemas: # JSON Schema to validate Atmos manifests # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ - # https://atmos.tools/quick-start/configure-validation/ + # https://atmos.tools/quick-start/advanced/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json # https://json-schema.org/draft/2020-12/release-notes # https://www.schemastore.org/json diff --git a/pkg/component/atmos.yaml b/pkg/component/atmos.yaml index a9711dfcf..b057d5ed8 100644 --- a/pkg/component/atmos.yaml +++ b/pkg/component/atmos.yaml @@ -322,7 +322,7 @@ schemas: # JSON Schema to validate Atmos manifests # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ - # https://atmos.tools/quick-start/configure-validation/ + # https://atmos.tools/quick-start/advanced/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json # https://json-schema.org/draft/2020-12/release-notes # https://www.schemastore.org/json diff --git a/pkg/describe/atmos.yaml b/pkg/describe/atmos.yaml index a9711dfcf..b057d5ed8 100644 --- a/pkg/describe/atmos.yaml +++ b/pkg/describe/atmos.yaml @@ -322,7 +322,7 @@ schemas: # JSON Schema to validate Atmos manifests # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ - # https://atmos.tools/quick-start/configure-validation/ + # https://atmos.tools/quick-start/advanced/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json # https://json-schema.org/draft/2020-12/release-notes # https://www.schemastore.org/json diff --git a/pkg/generate/atmos.yaml b/pkg/generate/atmos.yaml index a9711dfcf..b057d5ed8 100644 --- a/pkg/generate/atmos.yaml +++ b/pkg/generate/atmos.yaml @@ -322,7 +322,7 @@ schemas: # JSON Schema to validate Atmos manifests # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ - # https://atmos.tools/quick-start/configure-validation/ + # https://atmos.tools/quick-start/advanced/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json # https://json-schema.org/draft/2020-12/release-notes # https://www.schemastore.org/json diff --git a/pkg/spacelift/atmos.yaml b/pkg/spacelift/atmos.yaml index a9711dfcf..b057d5ed8 100644 --- a/pkg/spacelift/atmos.yaml +++ b/pkg/spacelift/atmos.yaml @@ -322,7 +322,7 @@ schemas: # JSON Schema to validate Atmos manifests # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ - # https://atmos.tools/quick-start/configure-validation/ + # https://atmos.tools/quick-start/advanced/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json # https://json-schema.org/draft/2020-12/release-notes # https://www.schemastore.org/json diff --git a/pkg/validate/atmos.yaml b/pkg/validate/atmos.yaml index a9711dfcf..b057d5ed8 100644 --- a/pkg/validate/atmos.yaml +++ b/pkg/validate/atmos.yaml @@ -322,7 +322,7 @@ schemas: # JSON Schema to validate Atmos manifests # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ - # https://atmos.tools/quick-start/configure-validation/ + # https://atmos.tools/quick-start/advanced/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json # https://json-schema.org/draft/2020-12/release-notes # https://www.schemastore.org/json diff --git a/pkg/vender/atmos.yaml b/pkg/vender/atmos.yaml index a9711dfcf..b057d5ed8 100644 --- a/pkg/vender/atmos.yaml +++ b/pkg/vender/atmos.yaml @@ -322,7 +322,7 @@ schemas: # JSON Schema to validate Atmos manifests # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ - # https://atmos.tools/quick-start/configure-validation/ + # https://atmos.tools/quick-start/advanced/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json # https://json-schema.org/draft/2020-12/release-notes # https://www.schemastore.org/json diff --git a/pkg/workflow/atmos.yaml b/pkg/workflow/atmos.yaml index a9711dfcf..b057d5ed8 100644 --- a/pkg/workflow/atmos.yaml +++ b/pkg/workflow/atmos.yaml @@ -322,7 +322,7 @@ schemas: # JSON Schema to validate Atmos manifests # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ - # https://atmos.tools/quick-start/configure-validation/ + # https://atmos.tools/quick-start/advanced/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json # https://json-schema.org/draft/2020-12/release-notes # https://www.schemastore.org/json diff --git a/website/docs/introduction/cheatsheet.mdx b/website/docs/cheatsheets/common.mdx similarity index 98% rename from website/docs/introduction/cheatsheet.mdx rename to website/docs/cheatsheets/common.mdx index 4f4cc8a29..f7a2a7b73 100644 --- a/website/docs/introduction/cheatsheet.mdx +++ b/website/docs/cheatsheets/common.mdx @@ -1,9 +1,9 @@ --- -id: cheatsheet +id: common slug: /cheatsheet title: Atmos Cheatsheet -sidebar_label: Cheatsheet -sidebar_position: 5 +sidebar_label: Overview +sidebar_position: 1 --- import Link from '@docusaurus/Link' import Card from '@site/src/components/Card' diff --git a/website/docs/core-concepts/components/component-cheatsheet.mdx b/website/docs/cheatsheets/components.mdx similarity index 71% rename from website/docs/core-concepts/components/component-cheatsheet.mdx rename to website/docs/cheatsheets/components.mdx index 2baa84f66..bf4d96cdc 100644 --- a/website/docs/core-concepts/components/component-cheatsheet.mdx +++ b/website/docs/cheatsheets/components.mdx @@ -1,7 +1,8 @@ --- -id: cheatsheet -title: Component Cheatsheet -sidebar_label: Cheatsheet +id: components +title: Components Cheatsheet +descriptions: Cheatsheet for managing components in Atmos +sidebar_label: Using Components sidebar_position: 2 --- import Link from '@docusaurus/Link' @@ -26,43 +27,6 @@ import CardGroup from '@site/src/components/CardGroup' └── staging.yaml ``` - - ```yaml - import: - - catalog/something - vars: - key: value - components: - terraform: - $component: - vars: - foo: "bar" - ``` - - - - ```yaml - terraform: - overrides: - env: {} - settings: {} - vars: {} - command: "opentofu" - ``` - - - ```yaml - terraform: - components: - $component: - settings: - spacelift: - # The `autodeploy` setting was overridden with the value - # from `terraform.overrides.settings.spacelift.autodeploy` - autodeploy: true - workspace_enabled: true - ``` - @@ -104,4 +68,3 @@ import CardGroup from '@site/src/components/CardGroup' ``` - diff --git a/website/docs/cheatsheets/stacks.mdx b/website/docs/cheatsheets/stacks.mdx new file mode 100644 index 000000000..d8f376930 --- /dev/null +++ b/website/docs/cheatsheets/stacks.mdx @@ -0,0 +1,84 @@ +--- +id: stacks +title: Stacks Cheatsheet +descriptions: Cheatsheet for configuring components in stacks with Atmos +sidebar_label: Defining Stacks +sidebar_position: 3 +--- +import Link from '@docusaurus/Link' +import Card from '@site/src/components/Card' +import CardGroup from '@site/src/components/CardGroup' + + + + ``` + ├── atmos.yaml + ├── components + │   └── myapp + │   ├── main.tf + │   ├── outputs.tf + │   └── variables.tf + └── stacks + ├── catalog + │   └── myapp.yaml + └── deploy + ├── dev.yaml + ├── prod.yaml + └── staging.yaml + ``` + + + ```yaml + import: + - catalog/something + vars: + key: value + components: + terraform: + $component: + vars: + foo: "bar" + ``` + + + + ```yaml + terraform: + overrides: + env: {} + settings: {} + vars: {} + command: "opentofu" + ``` + + + ```yaml + terraform: + components: + $component: + settings: + spacelift: + # The `autodeploy` setting was overridden with the value + # from `terraform.overrides.settings.spacelift.autodeploy` + autodeploy: true + workspace_enabled: true + ``` + + + + + + ```shell + atmos list components + ``` + + + ```shell + atmos validate component $component -s $stack + atmos validate component $component -s $stack --schema-type jsonschema --schema-path $component.json + atmos validate component $component -s $stack --schema-type opa --schema-path $component.rego + atmos validate component $component -s $stack --schema-type opa --schema-path $component.rego --module-paths catalog + atmos validate component $component -s $stack --timeout 15 + ``` + + diff --git a/website/docs/core-concepts/vendoring/cheatsheet.mdx b/website/docs/cheatsheets/vendoring.mdx similarity index 96% rename from website/docs/core-concepts/vendoring/cheatsheet.mdx rename to website/docs/cheatsheets/vendoring.mdx index f5ff7cb7b..cecd1554f 100644 --- a/website/docs/core-concepts/vendoring/cheatsheet.mdx +++ b/website/docs/cheatsheets/vendoring.mdx @@ -1,8 +1,8 @@ --- -id: cheatsheet +id: vendoring title: Vendoring Cheatsheet -sidebar_label: Cheatsheet -sidebar_position: 2 +sidebar_label: Vendoring Components +sidebar_position: 4 --- import Card from '@site/src/components/Card' diff --git a/website/docs/cli/commands/describe/describe-component.mdx b/website/docs/cli/commands/describe/describe-component.mdx index 01cb3fa68..abfb3c44d 100644 --- a/website/docs/cli/commands/describe/describe-component.mdx +++ b/website/docs/cli/commands/describe/describe-component.mdx @@ -102,7 +102,7 @@ The output contains the following sections: - `env` - a map of ENV variables defined for the Atmos component -- `inheritance` - component's [inheritance chain](/core-concepts/components/inheritance) +- `inheritance` - component's [inheritance chain](/core-concepts/stacks/inheritance) - `metadata` - component's metadata config @@ -129,7 +129,7 @@ The output contains the following sections: - `deps` - a list of component stack dependencies where the _final_ values of all component configurations are defined (after the deep-merging and processing all the inheritance chains and all the base components) -- `overrides` - a map of overrides for the component. Refer to [Component Overrides](/core-concepts/components/overrides) for more details +- `overrides` - a map of overrides for the component. Refer to [Component Overrides](/core-concepts/stacks/overrides) for more details - `providers` - a map of provider configurations for the component @@ -138,10 +138,10 @@ The output contains the following sections: The difference between the `imports`, `deps_all` and `deps` outputs is as follows: - `imports` shows all imports in the stack for all components. This can be useful in GitHub actions and - in [OPA validation policies](/core-concepts/components/validation) to check whether an import is allowed in the stack or not + in [OPA validation policies](/core-concepts/validating/components) to check whether an import is allowed in the stack or not - `deps_all` shows all component stack dependencies (imports and root-level stacks) where any configuration for the component is present. - This also can be useful in GitHub Actions and [OPA validation policies](/core-concepts/components/validation) to check whether a user or a team + This also can be useful in GitHub Actions and [OPA validation policies](/core-concepts/validating/components) to check whether a user or a team is allowed to import a particular config file for the component in the stack - `deps` shows all the component stack dependencies where the __FINAL__ values from all the component sections are defined @@ -149,7 +149,7 @@ The difference between the `imports`, `deps_all` and `deps` outputs is as follow to detect only the affected files that the component depends on. `deps` is usually a much smaller list than `deps_all` and can differ from it in the following ways: - - An Atmos component can inherit configurations from many base components, see [Component Inheritance](/core-concepts/components/inheritance), and + - An Atmos component can inherit configurations from many base components, see [Component Inheritance](/core-concepts/stacks/inheritance), and import those base component configurations - The component can override all the default variables from the base components, and the final values are not dependent on the base component diff --git a/website/docs/cli/commands/validate/validate-stacks.mdx b/website/docs/cli/commands/validate/validate-stacks.mdx index fed318211..ec7525de6 100644 --- a/website/docs/cli/commands/validate/validate-stacks.mdx +++ b/website/docs/cli/commands/validate/validate-stacks.mdx @@ -67,7 +67,7 @@ This command validates Atmos stack manifests and checks the following: ensure each has a unique name - Use multiple-inheritance to combine multiple configurations together - (refer to https://atmos.tools/core-concepts/components/inheritance) + (refer to https://atmos.tools/core-concepts/stacks/inheritance) ``` diff --git a/website/docs/cli/commands/vendor/vendor-pull.mdx b/website/docs/cli/commands/vendor/vendor-pull.mdx index cf3cd0fda..716b8ce0d 100644 --- a/website/docs/cli/commands/vendor/vendor-pull.mdx +++ b/website/docs/cli/commands/vendor/vendor-pull.mdx @@ -92,7 +92,7 @@ Refer to [`Atmos Vendoring`](/core-concepts/vendoring) for more details file names/paths (double-star/globstar `**` is supported as well). :::tip -Refer to [`Atmos Component Vendoring`](/core-concepts/components/vendoring) for more details +Refer to [`Atmos Component Vendoring`](/core-concepts/vendoring/components) for more details ::: ## Vendoring from OCI Registries diff --git a/website/docs/cli/commands/version.mdx b/website/docs/cli/commands/version.mdx index 8eaa5f20a..4d0dab1fa 100644 --- a/website/docs/cli/commands/version.mdx +++ b/website/docs/cli/commands/version.mdx @@ -28,7 +28,7 @@ This will show the CLI version. :::tip To find the latest version of Atmos, go to the [releases](https://github.com/cloudposse/atmos/releases) page on GitHub. -For help with installing the latest version of Atmos, check out our [installation](/quick-start/install-atmos) page. +For help with installing the latest version of Atmos, check out our [installation](/install) page. :::
diff --git a/website/docs/cli/configuration.mdx b/website/docs/cli/configuration.mdx index 2855ecfa5..faa247fba 100644 --- a/website/docs/cli/configuration.mdx +++ b/website/docs/cli/configuration.mdx @@ -684,7 +684,7 @@ schemas: # JSON Schema to validate Atmos manifests # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ - # https://atmos.tools/quick-start/configure-validation/ + # https://atmos.tools/quick-start/advanced/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json # https://json-schema.org/draft/2020-12/release-notes atmos: @@ -699,7 +699,7 @@ schemas: :::tip For more information, refer to: - [Atmos Manifests Validation](/cli/schemas) -- [Atmos Component Validation](/core-concepts/components/validation) +- [Atmos Component Validation](/core-concepts/validating/components) :::
diff --git a/website/docs/core-concepts/components/component-oriented-programming.md b/website/docs/core-concepts/components/component-oriented-programming.md index daca01edd..efe16d008 100644 --- a/website/docs/core-concepts/components/component-oriented-programming.md +++ b/website/docs/core-concepts/components/component-oriented-programming.md @@ -10,10 +10,10 @@ implementing and composing loosely-coupled independent components into systems. Atmos supports the following concepts and principles of **Component-Oriented Programming (COP)**: -- [Single Inheritance](/core-concepts/components/inheritance#single-inheritance) - when an Atmos component inherits the configuration properties from +- [Single Inheritance](/core-concepts/stacks/inheritance#single-inheritance) - when an Atmos component inherits the configuration properties from another Atmos component -- [Multiple Inheritance](/core-concepts/components/inheritance#multiple-inheritance) - when an Atmos component inherits from more than one Atmos +- [Multiple Inheritance](/core-concepts/stacks/inheritance#multiple-inheritance) - when an Atmos component inherits from more than one Atmos component - Dynamic Polymorphism - ability to use and override base component(s) properties diff --git a/website/docs/core-concepts/components/components.mdx b/website/docs/core-concepts/components/components.mdx index 86848b2fd..7f78d7975 100644 --- a/website/docs/core-concepts/components/components.mdx +++ b/website/docs/core-concepts/components/components.mdx @@ -1,7 +1,7 @@ --- title: Atmos Components sidebar_position: 1 -sidebar_label: Components +sidebar_label: Build Components description: Components are opinionated building blocks of infrastructure as code that solve one specific problem or use-case. --- @@ -61,128 +61,16 @@ component. The configuration of a component is stored in a Stack configuration. :::info Disambiguation -- **Terraform Component** is a [Terraform Root Module](https://developer.hashicorp.com/terraform/language/modules#the-root-module) +- **Terraform Component** is a simply a [Terraform Root Module](https://developer.hashicorp.com/terraform/language/modules#the-root-module) that consists of the resources defined in the `.tf` files in a working directory (e.g. [components/terraform/infra/vpc](https://github.com/cloudposse/atmos/tree/master/examples/tests/components/terraform/infra/vpc)) -- **Atmos Component** provides configuration (variables and other settings) for a type of component (e.g. a Terraform component) and is defined in one or more YAML stack config - files (which are called [Atmos stacks](/core-concepts/stacks)) - +- **Component Configuration** provides configuration (variables and other settings) for a type of component (e.g. a Terraform component) + and is defined in one or more YAML stack config files (which are called [Atmos stacks](/core-concepts/stacks)) :::
-The schema of an Atmos Component in an Atmos Stack is as follows: - -```yaml -components: - terraform: - # the slug of the component - example: - - # configuration specific to atmos - metadata: - # Components can be of type "real" (default) or "abstract" - type: real - # This is the directory path of the component. - # In this example, we're referencing a component in the `components/terraform/stable/example` folder. - component: stable/example - - # We can leverage multiple inheritance to sequentially deep merge multiple configurations - inherits: - - example-defaults - - # Settings are where we store configuration related to integrations. - # It's a freeform map; anything can be placed here. - settings: - spacelift: { } - - # Define the terraform variables, which will get deep-merged and exported to a `.tfvars` file by atmos. - vars: - enabled: true - name: superduper - nodes: 10 -``` - -### Component Attributes - -#### vars - -The `vars` section is a free-form map. Use [component validation](/core-concepts/components/validation) to enforce policies. - -#### vars.namespace - -This is an *optional* [`terraform-null-label`](https://github.com/cloudposse/terraform-null-label) convention. - -The namespace of all stacks. Typically, there will be one namespace for the organization. - -Example: - -```yaml -vars: - namespace: acme -``` - -#### vars.tenant - -This is an *optional* [`terraform-null-label`](https://github.com/cloudposse/terraform-null-label) convention. - -In a multi-tenant configuration, the tenant represents a single `tenant`. By convention, we typically -recommend that every tenant have its own Organizational Unit (OU). - -Example: - -```yaml -vars: - tenant: platform -``` - -#### vars.stage - -This is an *optional* [`terraform-null-label`](https://github.com/cloudposse/terraform-null-label) convention. - -The `stage` is where workloads run. See our [glossary](/terms) for disambiguation. - -Example: - -```yaml -vars: - # Production stage - stage: prod -``` - -#### vars.environment - -This is an *optional* [`terraform-null-label`](https://github.com/cloudposse/terraform-null-label) convention. - -The `environment` is used for location where things run. See our [glossary](/terms) for disambiguation. - -Example: - -```yaml - -vars: - # us-east-1 - environment: ue1 -``` - -#### metadata - -The `metadata` section extends functionality of the component. - -#### settings - -The `settings` block is a free-form map used to pass configuration information to [integrations](/integrations). - -### Types of Components - -The type of component is expressed in the `metadata.type` parameter of a given component configuration. - -There are two types of components: - -- `real` - is a ["concrete"](https://en.wikipedia.org/wiki/Concrete_class) component instance that can be provisioned -- `abstract` - a component configuration, which cannot be instantiated directly. The concept is borrowed - from ["abstract base classes"](https://en.wikipedia.org/wiki/Abstract_type) of Object-Oriented Programming ## Flavors of Components diff --git a/website/docs/core-concepts/terraform/terraform-backends.mdx b/website/docs/core-concepts/components/terraform/backends.mdx similarity index 99% rename from website/docs/core-concepts/terraform/terraform-backends.mdx rename to website/docs/core-concepts/components/terraform/backends.mdx index bf6e09d57..21eed96ea 100644 --- a/website/docs/core-concepts/terraform/terraform-backends.mdx +++ b/website/docs/core-concepts/components/terraform/backends.mdx @@ -3,7 +3,7 @@ title: Terraform Backends sidebar_position: 11 sidebar_label: Terraform Backends description: Configure Terraform Backends. -id: terraform-backends +id: backends --- import Terminal from '@site/src/components/Terminal' @@ -437,7 +437,7 @@ terraform:
:::tip -Refer to [Terraform Workspaces in Atmos](/core-concepts/components/terraform-workspaces) for more information on how +Refer to [Terraform Workspaces in Atmos](/core-concepts/components/terraform/workspaces) for more information on how Atmos calculates Terraform workspaces for components, and how workspaces can be overridden for each component. ::: @@ -448,7 +448,7 @@ Each account needs to have a separate S3 bucket, DynamoDB table, and IAM role wi (for example, the `development` Team should be able to access the Terraform backend only in the `dev` account, but not in `staging` and `prod`). Atmos supports this use-case by using deep-merging of stack manifests, [Imports](/core-concepts/stacks/imports) -and [Inheritance](/core-concepts/components/inheritance), which makes the backend configuration reusable and DRY. +and [Inheritance](/core-concepts/stacks/inheritance), which makes the backend configuration reusable and DRY. We'll split the backend config between the Organization and the accounts. diff --git a/website/docs/reference/terraform-limitations.md b/website/docs/core-concepts/components/terraform/journey.mdx similarity index 72% rename from website/docs/reference/terraform-limitations.md rename to website/docs/core-concepts/components/terraform/journey.mdx index 12e4bd70d..8b2af43a9 100644 --- a/website/docs/reference/terraform-limitations.md +++ b/website/docs/core-concepts/components/terraform/journey.mdx @@ -1,72 +1,26 @@ --- -title: Overcoming Terraform Limitations with Atmos -description: Overcoming Terraform Limitations with Atmos -sidebar_label: Overcoming Terraform Limitations +title: The Typical Terraform Journey +description: Learn about the typical Terraform journey when not using Atmos. +sidebar_label: Maturity Path sidebar_position: 6 +id: journey --- -# Overcoming Terraform Limitations with Atmos +# The Path to Atmos -To better understand the rationale behind Atmos's design, it may be helpful to hear about our experiences with Terraform—a tool integral to our development processes. Let's explore the challenges and constraints we faced using Terraform, which paved the way for creating Atmos. +To better understand the rationale behind Atmos's design, it may be helpful to hear about our experiences with Terraform—a tool +integral to our development processes at [Cloud Posse](https://cloudposse.com). Let's explore the challenges and constraints +we faced using Terraform, which paved the way for creating Atmos. -## What is Terraform? +Every team has a natural progression of Terraform adoption that follows a similar path and matures along the way. -Terraform is a command-line utility that processes infrastructure configurations in ["HashiCorp's Configuration Language" ("HCL")](https://en.wikipedia.org/wiki/HCL) to orchestrate infrastructure provisioning. Its chief role is to delineate and structure infrastructure definitions. - -Terraform's HCL started strictly as a configuration language, not a markup or programming language, although has evolved considerably over the years. HCL is backward compatible with JSON, although it's not a strict superset of JSON. HCL is more human-friendly and readable, while JSON is often used for machine-generated configurations. This means you can write Terraform configurations in HCL or JSON, and Terraform will understand them. This feature is particularly useful for generating configurations programmatically or integration with systems that already use JSON. +Every advancement in tool adoption is accompanied by new challenges, introducing complexities that are justified by the evolution's benefits. +Indeed, the true value of these evolutions often only becomes clear once we're faced with the intricate challenges they address. +Here's what a typical path of adoption looks like for organizations adopting Terraform. -## How has Terraform HCL Evolved? - -As Terraform progressed and HCL evolved, notably from version _0.12_ onwards, HCL began incorporating fetatures typical of programming languages (albeit without a debugger!). This shift enriched infrastructure definitions, positioning HCL more as a [domain-specific programming language](https://en.wikipedia.org/wiki/Domain-specific_language) for defining infrastructure than strictly a configuration language (aka data interchange formats like JSON). As a result, the complexity of configuring Terraform projects has risen, while Terraform's inherent capabilities to be configured haven't evolved at the same pace. - -- **Rich Expressions:** Introduced a richer expression syntax, removing the need for interpolations. - -- **For Loops and Conditionals:** Added for expressions and conditional expressions. - -- **Type System:** Introduced a more explicit type system for input and output values. - -## Why is additional tooling needed when using Terraform? - -**Every foundational tool begins simply.** - -As users grow more advanced and their ambitions expand, the need for advanced tooling emerges. These shifts demonstrate that core technologies naturally progress, spawning more advanced constructs to tackle increased intricacies and enhance efficiency -- all while retaining their core essence. Just as CSS, JavaScript, Docker, Helm, and many other tools have evolved to include higher-order utilities, Terraform, too, benefits from additional orchestration tools, given the complexities and challenges users face at different stages of adoption. - -Examples of tools like these are numerous, like - -- **CSS has Sass:** Sass provides more expressive styling capabilities, variables, and functions, making stylesheets more maintainable and organized, especially for large projects. -- **JavaScript has TypeScript:** TypeScript brings static typing to JavaScript, improving code robustness, aiding in catching errors at compile-time, and better supporting large-scale applications. -- **Docker has Docker Compose:** Docker Compose simplifies the management and orchestration of multi-container Docker applications, making it easier to define, run, and scale services collectively. -- **Helm charts have Helmfiles.** While Helm charts define the blueprints of Kubernetes services, Helmfiles enable better orchestration, management, and deployment of multiple charts, similar to coordinating various instruments in a symphony. -- **Kubernetes manifests have Kustomize:** Kustomize allows customization of Kubernetes manifests without changing their original form, facilitating dynamic configurations tailored to specific deployment scenarios. - -When considering Terraform in the context of large-scale organizations or enterprises, it's clear that Terraform and its inherent language don't address all challenges. With thousands of components spread across hundreds of accounts, cloud providers and managed by a vast number of DevOps engineers and developers, the complexity becomes overwhelming and difficult to manage. - -A lot of the same challenges faced by CSS, Javascript, Docker, Helm and Kubernetes also exist in Terraform as well. - -- Making modules more maintainable and organized, especially for large projects -- Better support for large-scale service-oriented architectures -- Easier ways to define, run, and scale services collectively -- Better orchestration, management, and deployment of multiple services - -Here's a more exhaustive list: - -- **Lack of DRY Configurations**: Terraform does not inherently support hierarchical configurations. There's no support for [deep merging configurations](https://github.com/hashicorp/terraform/issues/24987), making manual `varfile` maintenance unscalable. This makes it more difficult to enforce organizational standards, security controls, tagging, and policies. -- **State Management**: Managing Terraform's state, especially at scale, lacks inherent strategies for handling complexities such as access controls, multi-region, and Disaster Recovery (DR). -- **Limited Modularization**: Structuring configurations modularly while promoting code reuse is cumbersome. -- **Manual Initialization**: Backend initialization, module downloads, and other setup tasks require manual steps before executing `terraform apply`. This ties into the need for some kind of workflow tool. -- **Dependency Management**: Community edition of Terraform doesn't provide any mechanisms for orchestrating dependencies among root modules. -- **Absence of Stack Management**: Organizing configurations into structured stacks isn't a built-in feature of the community edition. -- **Lack of Automatic Dependency Ordering**: Standalone Terraform doesn't inherently determine execution order based on inter-stack dependencies. -- **No Native Workflow Automation and Standardization**: Dynamic workflow executions, such as having a unified workflow both in CI/CD platforms like GitHub Actions (GHA) and locally, are not inherently supported. Workflow standardization and automation capabilities do not exist, making provisioning and management tasks more manual, or relying on custom scripts, Makefiles, or other tooling. -- **Basic Environment Management**: Managing configurations across multiple environments can become complex without higher-level tooling. - -For each of these challenges, a tailored solution is essential. Ultimately, the goal is to make Terraform more scalable, maintainable, and developer-friendly, especially in complex and large-scale environments. - -HashiCorp primarily offers foundational guidance on Terraform and pushes companies instead toward Terraform Enterprise. In fact, it's held back features from entering into the Terraform core that would make it more standalone. HashiCorp does not thoroughly address how to solve the above challenges using Terraform. While suitable for some, it may not meet the scalability demands of enterprise, especially as they embark on their Terraform adoption journey. - -## What is the natural progression of Terraform adoption? - -Every advancement in tool adoption is accompanied by new challenges, introducing complexities that are justified by the evolution's benefits. Indeed, the true value of these evolutions often only becomes clear once we're faced with the intricate challenges they address. Here's what a typical path of adoption looks like for organizations adopting Terraform. +:::tip +**TL;DR:** [You can shortcuit this entire process by using Atmos from the start.](#whats-the-solution-hello-atmos-) 😎 +::: ### **Stage 1:** Introduction to Terraform, *Hello World!* diff --git a/website/docs/core-concepts/terraform/terraform-providers.mdx b/website/docs/core-concepts/components/terraform/providers.mdx similarity index 96% rename from website/docs/core-concepts/terraform/terraform-providers.mdx rename to website/docs/core-concepts/components/terraform/providers.mdx index 92156333e..223c2e8eb 100644 --- a/website/docs/core-concepts/terraform/terraform-providers.mdx +++ b/website/docs/core-concepts/components/terraform/providers.mdx @@ -3,7 +3,7 @@ title: Terraform Providers sidebar_position: 12 sidebar_label: Terraform Providers description: Configure and override Terraform Providers. -id: terraform-providers +id: providers --- import File from '@site/src/components/File' import Terminal from '@site/src/components/Terminal' @@ -98,7 +98,7 @@ deep-merge and override all the `providers` configurations for a component in th
:::tip -Refer to [Atmos Component Inheritance](/core-concepts/components/inheritance) for more information on all types of component inheritance +Refer to [Atmos Component Inheritance](/core-concepts/stacks/inheritance) for more information on all types of component inheritance supported by Atmos ::: @@ -187,7 +187,7 @@ For example: The above example uses a list of configuration blocks for the `aws` provider. Since it's a list, by default it doesn't work with deep-merging of stacks in the -[inheritance](/core-concepts/components/inheritance) chain since list are not deep-merged, they are replaced. +[inheritance](/core-concepts/stacks/inheritance) chain since list are not deep-merged, they are replaced. If you want to use the above configuration in the inheritance chain and allow appending or merging of lists, consider configuring the `settings.list_merge_strategy` in the `atmos.yaml` CLI config file. diff --git a/website/docs/core-concepts/terraform/remote-state-backend.mdx b/website/docs/core-concepts/components/terraform/remote-state-backend.mdx similarity index 95% rename from website/docs/core-concepts/terraform/remote-state-backend.mdx rename to website/docs/core-concepts/components/terraform/remote-state-backend.mdx index ba4c13d52..6dc76a554 100644 --- a/website/docs/core-concepts/terraform/remote-state-backend.mdx +++ b/website/docs/core-concepts/components/terraform/remote-state-backend.mdx @@ -5,9 +5,9 @@ sidebar_label: Remote State Backend id: remote-state-backend --- -Atmos supports configuring [Terraform Backends](/core-concepts/components/terraform-backends) to define where +Atmos supports configuring [Terraform Backends](/core-concepts/components/terraform/backends) to define where Terraform stores its [state](https://developer.hashicorp.com/terraform/language/state), -and [Remote State](/core-concepts/components/remote-state) to get the outputs +and [Remote State](/core-concepts/components/terraform/remote-state) to get the outputs of a [Terraform component](/core-concepts/components), provisioned in the same or a different [Atmos stack](/core-concepts/stacks), and use the outputs as inputs to another Atmos component @@ -15,7 +15,7 @@ the outputs as inputs to another Atmos component Atmos also supports Remote State Backends (in the `remote_state_backend` section), which can be used to configure the following: -- Override [Terraform Backend](/core-concepts/components/terraform-backends) configuration to access the +- Override [Terraform Backend](/core-concepts/components/terraform/backends) configuration to access the remote state of a component (e.g. override the IAM role to assume, which in this case can be a read-only role) - Configure a remote state of type `static` which can be used to provide configurations for @@ -27,13 +27,13 @@ Atmos supports the `remote_state_backend` section which can be used to provide c of components. To access the remote state of components, you can override -any [Terraform Backend](/core-concepts/components/terraform-backends) +any [Terraform Backend](/core-concepts/components/terraform/backends) configuration in the `backend` section using the `remote_state_backend` section. The `remote_state_backend` section is a first-class section, and it can be defined globally at any scope (organization, tenant, account, region), or per -component, and then deep-merged using [Atmos Component Inheritance](/core-concepts/components/inheritance). +component, and then deep-merged using [Atmos Component Inheritance](/core-concepts/stacks/inheritance). For example, let's suppose we have the following S3 backend configuration for the entire organization -(refer to [AWS S3 Backend](/core-concepts/components/terraform-backends#aws-s3-backend) for more details): +(refer to [AWS S3 Backend](/core-concepts/components/terraform/backends#aws-s3-backend) for more details): ```yaml title="stacks/orgs/acme/_defaults.yaml" terraform: @@ -108,7 +108,7 @@ established systems. This can be challenging due to several factors: Atmos is easier for new organizations or "greenfield" environments because you need to architect Terraform according to our best practices to get all the benefits of Atmos. For example, when using our [Terraform components](https://github.com/cloudposse/terraform-aws-components), we frequently use -[Terraform Remote State](/core-concepts/components/remote-state) to retrieve the outputs from other components. +[Terraform Remote State](/core-concepts/components/terraform/remote-state) to retrieve the outputs from other components. This works well when you use our components but less so when you operate in a "brownfield" environment, for example, with an existing VPC, S3 bucket, or IAM role. @@ -136,7 +136,7 @@ The `vpc` Terraform component needs the outputs from the `vpc-flow-logs-bucket` configure [VPC Flow Logs](https://docs.aws.amazon.com/vpc/latest/userguide/flow-logs.html). Let's redesign the example with the `vpc` and `vpc-flow-logs-bucket` components described in -[Terraform Component Remote State](/core-concepts/components/remote-state) and configure the `static` remote state for +[Terraform Component Remote State](/core-concepts/components/terraform/remote-state) and configure the `static` remote state for the `vpc-flow-logs-bucket` component to use an existing S3 bucket. ### Configure the `vpc-flow-logs-bucket` Component diff --git a/website/docs/core-concepts/terraform/remote-state.mdx b/website/docs/core-concepts/components/terraform/remote-state.mdx similarity index 100% rename from website/docs/core-concepts/terraform/remote-state.mdx rename to website/docs/core-concepts/components/terraform/remote-state.mdx diff --git a/website/docs/core-concepts/components/terraform/terraform.mdx b/website/docs/core-concepts/components/terraform/terraform.mdx new file mode 100644 index 000000000..280d51c10 --- /dev/null +++ b/website/docs/core-concepts/components/terraform/terraform.mdx @@ -0,0 +1,81 @@ +--- +title: Terraform Root Modules +sidebar_position: 3 +sidebar_label: Terraform Root Modules +description: Learn why Atmos can change how you think about the Terraform modules that you use to build your infrastructure. +id: terraform +slug: /terraform +--- +import DocCardList from "@theme/DocCardList"; + +# Terraform Core Concepts + +Atmos can change how you think about the Terraform modules that you use to build your infrastructure. + +When you design a cloud architectures with Atmos, you will first break it apart into pieces called components. +Then, you will define the terraform "root modules" for each of your components. +To make them highly reusable, they should serve a "single purpose" so that they are the smallest possible +unit of infrastructure managed in the software development lifecycle. +Finally, you will connect your components together with stacks, so that everything comes together. + +In this tutorial, we’ll guide you through the thought process of building Terraform "root modules" that are suitable for use as components. + +You're about discover a new way to think about terraform... + +## What is Terraform? + +Terraform is a command-line utility that processes infrastructure configurations in ["HashiCorp's Configuration Language" ("HCL")](https://en.wikipedia.org/wiki/HCL) to orchestrate infrastructure provisioning. Its chief role is to delineate and structure infrastructure definitions. + +Terraform's HCL started strictly as a configuration language, not a markup or programming language, although has evolved considerably over the years. HCL is backward compatible with JSON, although it's not a strict superset of JSON. HCL is more human-friendly and readable, while JSON is often used for machine-generated configurations. This means you can write Terraform configurations in HCL or JSON, and Terraform will understand them. This feature is particularly useful for generating configurations programmatically or integration with systems that already use JSON. + +## How has Terraform HCL Evolved? + +As Terraform progressed and HCL evolved, notably from version _0.12_ onwards, HCL began incorporating fetatures typical of programming languages (albeit without a debugger!). This shift enriched infrastructure definitions, positioning HCL more as a [domain-specific programming language](https://en.wikipedia.org/wiki/Domain-specific_language) for defining infrastructure than strictly a configuration language (aka data interchange formats like JSON). As a result, the complexity of configuring Terraform projects has risen, while Terraform's inherent capabilities to be configured haven't evolved at the same pace. + +- **Rich Expressions:** Introduced a richer expression syntax, removing the need for interpolations. + +- **For Loops and Conditionals:** Added for expressions and conditional expressions. + +- **Type System:** Introduced a more explicit type system for input and output values. + +## Why is additional tooling needed when using Terraform? + +**Every foundational tool begins simply.** + +As users grow more advanced and their ambitions expand, the need for advanced tooling emerges. These shifts demonstrate that core technologies naturally progress, spawning more advanced constructs to tackle increased intricacies and enhance efficiency -- all while retaining their core essence. Just as CSS, JavaScript, Docker, Helm, and many other tools have evolved to include higher-order utilities, Terraform, too, benefits from additional orchestration tools, given the complexities and challenges users face at different stages of adoption. + +Examples of tools like these are numerous, like + +- **CSS has Sass:** Sass provides more expressive styling capabilities, variables, and functions, making stylesheets more maintainable and organized, especially for large projects. +- **JavaScript has React:** React brings component-based architecture to JavaScript, enhancing the creation of interactive UIs, improving code reusability, and better supporting the development of large-scale applications. +- **Docker has Docker Compose:** Docker Compose simplifies the management and orchestration of multi-container Docker applications, making it easier to define, run, and scale services collectively. +- **Helm charts have Helmfiles:** While Helm charts define the blueprints of Kubernetes services, Helmfiles enable better orchestration, management, and deployment of multiple charts, similar to coordinating various instruments in a symphony. +- **Kubernetes manifests have Kustomize:** Kustomize allows customization of Kubernetes manifests without changing their original form, facilitating dynamic configurations tailored to specific deployment scenarios. + +When considering Terraform in the context of large-scale organizations or enterprises, it's clear that Terraform and its inherent language don't address all challenges. With thousands of components spread across hundreds of accounts, cloud providers and managed by a vast number of DevOps engineers and developers, the complexity becomes overwhelming and difficult to manage. + +A lot of the same challenges faced by CSS, Javascript, Docker, Helm and Kubernetes also exist in Terraform as well. + +- Making modules more maintainable and organized, especially for large projects +- Better support for large-scale service-oriented architectures +- Easier ways to define, run, and scale services collectively +- Better orchestration, management, and deployment of multiple services + +Here's a more exhaustive list: + +- **Lack of DRY Configurations**: Terraform does not inherently support hierarchical configurations. There's no support for [deep merging configurations](https://github.com/hashicorp/terraform/issues/24987), making manual `varfile` maintenance unscalable. This makes it more difficult to enforce organizational standards, security controls, tagging, and policies. +- **State Management**: Managing Terraform's state, especially at scale, lacks inherent strategies for handling complexities such as access controls, multi-region, and Disaster Recovery (DR). +- **Limited Modularization**: Structuring configurations modularly while promoting code reuse is cumbersome. +- **Manual Initialization**: Backend initialization, module downloads, and other setup tasks require manual steps before executing `terraform apply`. This ties into the need for some kind of workflow tool. +- **Dependency Management**: Community edition of Terraform doesn't provide any mechanisms for orchestrating dependencies among root modules. +- **Absence of Stack Management**: Organizing configurations into structured stacks isn't a built-in feature of the community edition. +- **Lack of Automatic Dependency Ordering**: Standalone Terraform doesn't inherently determine execution order based on inter-stack dependencies. +- **No Native Workflow Automation and Standardization**: Dynamic workflow executions, such as having a unified workflow both in CI/CD platforms like GitHub Actions (GHA) and locally, are not inherently supported. Workflow standardization and automation capabilities do not exist, making provisioning and management tasks more manual, or relying on custom scripts, Makefiles, or other tooling. +- **Basic Environment Management**: Managing configurations across multiple environments can become complex without higher-level tooling. + +For each of these challenges, a tailored solution is essential. Ultimately, the goal is to make Terraform more scalable, maintainable, and developer-friendly, especially in complex and large-scale environments. + +HashiCorp primarily offers foundational guidance on Terraform and pushes companies instead toward Terraform Enterprise. In fact, it's held back features from entering into the Terraform core that would make it more standalone. HashiCorp does not thoroughly address how to solve the above challenges using Terraform. While suitable for some, it may not meet the scalability demands of enterprise, especially as they embark on their Terraform adoption journey. + + + diff --git a/website/docs/core-concepts/terraform/terraform-workspaces.mdx b/website/docs/core-concepts/components/terraform/workspaces.mdx similarity index 98% rename from website/docs/core-concepts/terraform/terraform-workspaces.mdx rename to website/docs/core-concepts/components/terraform/workspaces.mdx index 278efff11..e0c71ea18 100644 --- a/website/docs/core-concepts/terraform/terraform-workspaces.mdx +++ b/website/docs/core-concepts/components/terraform/workspaces.mdx @@ -3,7 +3,7 @@ title: Terraform Workspaces sidebar_position: 10 sidebar_label: Terraform Workspaces description: Terraform Workspaces. -id: terraform-workspaces +id: workspaces --- import File from '@site/src/components/File' import Terminal from '@site/src/components/Terminal' @@ -199,7 +199,7 @@ The following context tokens are supported by the `metadata.terraform_workspace_ :::tip For more information on Atmos base and derived components, and to understand the `{base-component}` token, -refer to [Atmos Component Inheritance](/core-concepts/components/inheritance) +refer to [Atmos Component Inheritance](/core-concepts/stacks/inheritance) :::
diff --git a/website/docs/core-concepts/custom-commands/custom-commands.mdx b/website/docs/core-concepts/custom-commands/custom-commands.mdx index f6e337d27..878bbf269 100644 --- a/website/docs/core-concepts/custom-commands/custom-commands.mdx +++ b/website/docs/core-concepts/custom-commands/custom-commands.mdx @@ -1,7 +1,6 @@ --- title: Atmos Custom Commands -sidebar_label: Custom Commands -sidebar_position: 5 +sidebar_label: Implement Custom Commands id: custom-commands --- diff --git a/website/docs/core-concepts/components/describe-component.mdx b/website/docs/core-concepts/describing/components.mdx similarity index 81% rename from website/docs/core-concepts/components/describe-component.mdx rename to website/docs/core-concepts/describing/components.mdx index ab64f9873..2df376fad 100644 --- a/website/docs/core-concepts/components/describe-component.mdx +++ b/website/docs/core-concepts/describing/components.mdx @@ -1,16 +1,16 @@ --- -title: Describe Component +title: Describe Components sidebar_position: 4 -sidebar_label: Describing +sidebar_label: Components description: Describe a component in a stack to view the fully deep-merged configuration -id: describing +id: component --- Describing components is helpful to understand what the final, fully computed and deep-merged configuration of an [Atmos component](/core-concepts/components) will look like across any number of [Atmos stacks](/core-concepts/stacks). The more [DRY a configuration is due to imports](/core-concepts/stacks/imports), the -more [derived the configuration is due to inheritance](/core-concepts/components/inheritance), the harder it may be to understand what the final +more [derived the configuration is due to inheritance](/core-concepts/stacks/inheritance), the harder it may be to understand what the final component configuration will be. For example, if we wanted to understand what the final configuration looks like for a "vpc" component running in the "production" stack in the @@ -22,8 +22,8 @@ atmos describe component vpc -s ue2-prod
-For more powerful filtering options, consider [describing stacks](/core-concepts/stacks/describing) instead. +For more powerful filtering options, consider [describing stacks](/core-concepts/describing/stacks) instead. -The other helpful use-case for describing components and stacks is when developing polices for [validation](/core-concepts/components/validation) of +The other helpful use-case for describing components and stacks is when developing polices for [validation](/core-concepts/validating/components) of [Atmos components](/core-concepts/components) and [Atmos stacks](/core-concepts/stacks). OPA policies can enforce what is or is not permitted. Everything in the output can be validated using policies that you develop. diff --git a/website/docs/core-concepts/describing/describing.mdx b/website/docs/core-concepts/describing/describing.mdx new file mode 100644 index 000000000..8b0cfd245 --- /dev/null +++ b/website/docs/core-concepts/describing/describing.mdx @@ -0,0 +1,18 @@ +--- +title: Describe Configuration +sidebar_position: 3 +sidebar_label: Describe Configuration +description: Describing your configuration so you understand what's happening. +id: describing +--- +import DocCardList from "@theme/DocCardList"; + +# Describing Configuration + +Atmos is a framework for defining cloud architectures in YAML. +Configurations are defined in Stacks, which define the settings for small units infrastructure called Components like VPCs, Clusters, and Databases. +Atmos lets you combine components into reusable, nestable Stacks using Imports. +Everything from simple web sites to full blown multi-account/multi-subscription cloud architectures can be broken down into components. +In this chapter, you’ll learn to create, customize, and conditionally display the configuration of Atmos components. + + diff --git a/website/docs/core-concepts/stacks/describe-stacks.mdx b/website/docs/core-concepts/describing/stacks.mdx similarity index 99% rename from website/docs/core-concepts/stacks/describe-stacks.mdx rename to website/docs/core-concepts/describing/stacks.mdx index 228baf6a5..3f96274d9 100644 --- a/website/docs/core-concepts/stacks/describe-stacks.mdx +++ b/website/docs/core-concepts/describing/stacks.mdx @@ -1,8 +1,8 @@ --- title: Describe Stacks sidebar_position: 4 -sidebar_label: Describing -id: describing +sidebar_label: Stacks +id: stacks description: Describe stacks to view the fully deep-merged configuration --- import Terminal from '@site/src/components/Terminal' diff --git a/website/docs/core-concepts/stacks/catalogs.md b/website/docs/core-concepts/stacks/catalogs.md index 97b8811df..7447c86e0 100644 --- a/website/docs/core-concepts/stacks/catalogs.md +++ b/website/docs/core-concepts/stacks/catalogs.md @@ -1,7 +1,7 @@ --- title: Stack Catalogs sidebar_position: 3 -sidebar_label: Catalogs +sidebar_label: Build Catalogs id: catalogs description: Catalogs are how to organize all Stack configurations for easy imports. --- diff --git a/website/docs/core-concepts/stacks/define-components.mdx b/website/docs/core-concepts/stacks/define-components.mdx new file mode 100644 index 000000000..ec152fdf1 --- /dev/null +++ b/website/docs/core-concepts/stacks/define-components.mdx @@ -0,0 +1,138 @@ +--- +title: Define Component Configurations in Stacks +sidebar_position: 2 +sidebar_label: Define Components +id: define-components +--- + +## Component Schema + +To configure a Component in a [Stack](/core-concepts/stacks), A Component consists of the infrastructure as code business logic (e.g. a Terraform "root" module) as well as the configuration of that +component. The configuration of a component is stored in a Stack configuration. + +
+ +:::info Disambiguation + +- **Terraform Component** is a simply a [Terraform Root Module](https://developer.hashicorp.com/terraform/language/modules#the-root-module) + that consists of the resources defined in the `.tf` files in a working directory + (e.g. [components/terraform/infra/vpc](https://github.com/cloudposse/atmos/tree/master/examples/tests/components/terraform/infra/vpc)) + +- **Component Configuration** provides configuration (variables and other settings) for a type of component (e.g. a Terraform component) + and is defined in one or more YAML stack config files (which are called [Atmos stacks](/core-concepts/stacks)) +::: + +
+ + +The schema of an Atmos Component in an Atmos Stack is as follows: + +```yaml +components: + terraform: + # the slug of the component + example: + + # configuration specific to atmos + metadata: + # Components can be of type "real" (default) or "abstract" + type: real + # This is the directory path of the component. + # In this example, we're referencing a component in the `components/terraform/stable/example` folder. + component: stable/example + + # We can leverage multiple inheritance to sequentially deep merge multiple configurations + inherits: + - example-defaults + + # Settings are where we store configuration related to integrations. + # It's a freeform map; anything can be placed here. + settings: + spacelift: { } + + # Define the terraform variables, which will get deep-merged and exported to a `.tfvars` file by atmos. + vars: + enabled: true + name: superduper + nodes: 10 +``` + +### Component Attributes + +#### vars + +The `vars` section is a free-form map. Use [component validation](/core-concepts/validating/components) to enforce policies. + +#### vars.namespace + +This is an *optional* [`terraform-null-label`](https://github.com/cloudposse/terraform-null-label) convention. + +The namespace of all stacks. Typically, there will be one namespace for the organization. + +Example: + +```yaml +vars: + namespace: acme +``` + +#### vars.tenant + +This is an *optional* [`terraform-null-label`](https://github.com/cloudposse/terraform-null-label) convention. + +In a multi-tenant configuration, the tenant represents a single `tenant`. By convention, we typically +recommend that every tenant have its own Organizational Unit (OU). + +Example: + +```yaml +vars: + tenant: platform +``` + +#### vars.stage + +This is an *optional* [`terraform-null-label`](https://github.com/cloudposse/terraform-null-label) convention. + +The `stage` is where workloads run. See our [glossary](/terms) for disambiguation. + +Example: + +```yaml +vars: + # Production stage + stage: prod +``` + +#### vars.environment + +This is an *optional* [`terraform-null-label`](https://github.com/cloudposse/terraform-null-label) convention. + +The `environment` is used for location where things run. See our [glossary](/terms) for disambiguation. + +Example: + +```yaml + +vars: + # us-east-1 + environment: ue1 +``` + +#### metadata + +The `metadata` section extends functionality of the component. + +#### settings + +The `settings` block is a free-form map used to pass configuration information to [integrations](/integrations). + +### Types of Components + +The type of component is expressed in the `metadata.type` parameter of a given component configuration. + +There are two types of components: + +- `real` - is a ["concrete"](https://en.wikipedia.org/wiki/Concrete_class) component instance that can be provisioned +- `abstract` - a component configuration, which cannot be instantiated directly. The concept is borrowed + from ["abstract base classes"](https://en.wikipedia.org/wiki/Abstract_type) of Object-Oriented Programming diff --git a/website/docs/core-concepts/stacks/imports.mdx b/website/docs/core-concepts/stacks/imports.mdx index 130a7473e..c82ffab40 100644 --- a/website/docs/core-concepts/stacks/imports.mdx +++ b/website/docs/core-concepts/stacks/imports.mdx @@ -1,7 +1,7 @@ --- title: Stack Imports -sidebar_position: 5 -sidebar_label: Imports +sidebar_position: 3 +sidebar_label: Import Other Stacks id: imports --- import File from '@site/src/components/File' @@ -9,7 +9,7 @@ import File from '@site/src/components/File' Imports are how we reduce duplication of configurations by creating reusable baselines. The imports should be thought of almost like blueprints. Once a reusable catalog of Stacks exists, robust architectures can be easily created simply by importing those blueprints. -Imports may be used in Stack configurations together with [inheritance](/core-concepts/components/inheritance) +Imports may be used in Stack configurations together with [inheritance](/core-concepts/stacks/inheritance) and [mixins](/core-concepts/stacks/mixins) to produce an exceptionally DRY configuration in a way that is logically organized and easier to maintain for your team. @@ -402,5 +402,5 @@ for [EKS blue-green deployment](https://aws.amazon.com/blogs/containers/kubernet ## Related -- [Configure CLI](/quick-start/configure-cli) -- [Create Atmos Stacks](/quick-start/create-atmos-stacks) +- [Configure CLI](/quick-start/advanced/configure-cli) +- [Create Atmos Stacks](/quick-start/advanced/create-atmos-stacks) diff --git a/website/docs/core-concepts/components/component-inheritance.mdx b/website/docs/core-concepts/stacks/inheritance.mdx similarity index 99% rename from website/docs/core-concepts/components/component-inheritance.mdx rename to website/docs/core-concepts/stacks/inheritance.mdx index f697dad53..0f7302267 100644 --- a/website/docs/core-concepts/components/component-inheritance.mdx +++ b/website/docs/core-concepts/stacks/inheritance.mdx @@ -1,7 +1,7 @@ --- title: Component Inheritance -sidebar_position: 7 -sidebar_label: Inheritance +sidebar_position: 4 +sidebar_label: Inherit Configurations id: inheritance --- import File from '@site/src/components/File' diff --git a/website/docs/core-concepts/components/component-overrides.mdx b/website/docs/core-concepts/stacks/overrides.mdx similarity index 98% rename from website/docs/core-concepts/components/component-overrides.mdx rename to website/docs/core-concepts/stacks/overrides.mdx index 3f8da0082..ed4f60c4f 100644 --- a/website/docs/core-concepts/components/component-overrides.mdx +++ b/website/docs/core-concepts/stacks/overrides.mdx @@ -1,7 +1,7 @@ --- title: Component Overrides -sidebar_position: 9 -sidebar_label: Overrides +sidebar_position: 5 +sidebar_label: Override Configuration description: Use the 'Component Overrides' pattern to modify components' configuration and behavior in the current scope. id: overrides --- @@ -66,7 +66,7 @@ manifests for the same top-level stack.
:::tip -Refer to [Atmos Component Inheritance](/core-concepts/components/inheritance) for more information on all types of component inheritance +Refer to [Atmos Component Inheritance](/core-concepts/stacks/inheritance) for more information on all types of component inheritance supported by Atmos ::: diff --git a/website/docs/core-concepts/stacks/stacks.mdx b/website/docs/core-concepts/stacks/stacks.mdx index 7e332397e..e55a3b9f0 100644 --- a/website/docs/core-concepts/stacks/stacks.mdx +++ b/website/docs/core-concepts/stacks/stacks.mdx @@ -1,15 +1,15 @@ --- title: Atmos Stacks -sidebar_position: 2 -sidebar_label: Stacks +sidebar_position: 1 +sidebar_label: Configure Stacks description: Stacks are a way to express the complete infrastructure needed for an environment id: stacks --- import File from '@site/src/components/File' -Stacks are a way to express the complete infrastructure needed for an environment. Think of a Stack like an architectural "Blueprint" composed -of one or more [Components](/core-concepts/components) and defined using a [standardized YAML configuration](#schema). +Stacks define the complete configuration of an environment. Think of a Stack like an architectural "Blueprint" composed +of one or more [Components](/core-concepts/components) configurations and defined using a [standardized YAML configuration](#schema). This abstraction layer helps to automate the orchestration and deployment of loosely coupled [components](/core-concepts/components), such as Terraform "root" modules. They enable scalable infrastructure-as-code configurations, allowing environments to inherit from one or more common bases (child stacks) by importing configuration that gets deep-merged, thus minimizing config duplication and manual effort. Each stack uses a simple schema that provides a declarative description of your various environments. This approach empowers you to separate your infrastructure’s environment configuration settings from the code it manages (e.g., Terraform components). @@ -53,7 +53,7 @@ various [design patterns](/design-patterns/). ## Schema -A Stack file contains a manifest defined in YAML that follows a simple, extensible schema. In fact, every Stack file follows exactly the same schema, and every setting in the configuration is optional. Enforcing a consistent schema ensures we can easily [import and deep-merge](/core-concepts/stacks/imports) configurations and use [inheritance](/core-concepts/components/inheritance) to achieve DRY configuration. +A Stack file contains a manifest defined in YAML that follows a simple, extensible schema. In fact, every Stack file follows exactly the same schema, and every setting in the configuration is optional. Enforcing a consistent schema ensures we can easily [import and deep-merge](/core-concepts/stacks/imports) configurations and use [inheritance](/core-concepts/stacks/inheritance) to achieve DRY configuration. ```yaml diff --git a/website/docs/core-concepts/stacks/templating.mdx b/website/docs/core-concepts/stacks/templating.mdx index e30b77b55..1bd95efe3 100644 --- a/website/docs/core-concepts/stacks/templating.mdx +++ b/website/docs/core-concepts/stacks/templating.mdx @@ -1,7 +1,7 @@ --- title: Stack Manifest Templating sidebar_position: 7 -sidebar_label: Templating +sidebar_label: Template Configurations id: templating --- import File from '@site/src/components/File' @@ -23,7 +23,7 @@ Atmos supports many different ways of configuring and using `Go` templates: - In [Atmos Custom Commands](/core-concepts/custom-commands) - In [Atmos Vendoring](/core-concepts/vendoring) -- In [Atmos Component Vendoring](/core-concepts/components/vendoring) +- In [Atmos Component Vendoring](/core-concepts/vendoring/components) - In [Imports](/core-concepts/stacks/imports) - In [Stack Manifests](/core-concepts/stacks) @@ -36,7 +36,7 @@ These templates are processed in different phases and use different context: exposing all the component sections that are returned by the `atmos describe component -s ` CLI command -- `Go` templates in [Atmos Vendoring](/core-concepts/vendoring) and [Atmos Component Vendoring](/core-concepts/components/vendoring) +- `Go` templates in [Atmos Vendoring](/core-concepts/vendoring) and [Atmos Component Vendoring](/core-concepts/vendoring/components) are processed when the CLI command [`atmos vendor pull`](/cli/commands/vendor/pull) is executed. The templates in the vendoring manifests support the `{{.Version}}` variable, and the execution context is provided in the `version` attribute @@ -68,7 +68,7 @@ Templating in Atmos stack manifests can be configured in the following places: - In the `settings.templates.settings` section in [Atmos stack manifests](/core-concepts/stacks). The `settings.templates.settings` section can be defined globally per organization, tenant, account, or per component. - Atmos deep-merges the configurations from all scopes into the final result using [inheritance](/core-concepts/components/inheritance). + Atmos deep-merges the configurations from all scopes into the final result using [inheritance](/core-concepts/stacks/inheritance). ### Configuring Templating in `atmos.yaml` CLI Config File @@ -220,7 +220,7 @@ To be able to use the `env` function from both templating engines, you can do on Templating in Atmos can also be configured in the `settings.templates.settings` section in stack manifests. The `settings.templates.settings` section can be defined globally per organization, tenant, account, or per component. -Atmos deep-merges the configurations from all scopes into the final result using [inheritance](/core-concepts/components/inheritance). +Atmos deep-merges the configurations from all scopes into the final result using [inheritance](/core-concepts/stacks/inheritance). The schema is the same as `templates.settings` in the `atmos.yaml` [CLI config file](/cli/configuration), except the following settings are not supported in the `settings.templates.settings` section: @@ -269,7 +269,7 @@ settings: Atmos deep-merges the configurations from the `settings.templates.settings` section in [Atmos stack manifests](/core-concepts/stacks) -with the `templates.settings` section in `atmos.yaml` [CLI config file](/cli/configuration) using [inheritance](/core-concepts/components/inheritance). +with the `templates.settings` section in `atmos.yaml` [CLI config file](/cli/configuration) using [inheritance](/core-concepts/stacks/inheritance). The `settings.templates.settings` section in [Atmos stack manifests](/core-concepts/stacks) takes precedence over the `templates.settings` section in `atmos.yaml` [CLI config file](/cli/configuration), allowing you to define the global diff --git a/website/docs/core-concepts/components/component-validation.mdx b/website/docs/core-concepts/validating/components.mdx similarity index 99% rename from website/docs/core-concepts/components/component-validation.mdx rename to website/docs/core-concepts/validating/components.mdx index b24e0952e..eafe30f4a 100644 --- a/website/docs/core-concepts/components/component-validation.mdx +++ b/website/docs/core-concepts/validating/components.mdx @@ -1,9 +1,9 @@ --- title: Component Validation sidebar_position: 2 -sidebar_label: Validation +sidebar_label: Components description: Use JSON Schema and OPA policies to validate Components. -id: validation +id: components --- import Terminal from '@site/src/components/Terminal' diff --git a/website/docs/core-concepts/stacks/validation.mdx b/website/docs/core-concepts/validating/stacks.mdx similarity index 95% rename from website/docs/core-concepts/stacks/validation.mdx rename to website/docs/core-concepts/validating/stacks.mdx index 72e663b10..95a4f0bce 100644 --- a/website/docs/core-concepts/stacks/validation.mdx +++ b/website/docs/core-concepts/validating/stacks.mdx @@ -1,9 +1,9 @@ --- title: Stack Validation sidebar_position: 2 -sidebar_label: Validation +sidebar_label: Stacks description: Validate all Stack configurations and YAML syntax. -id: validation +id: stacks --- import Terminal from '@site/src/components/Terminal' @@ -57,7 +57,7 @@ The command checks and validates the following: ensure each has a unique name - Use multiple-inheritance to combine multiple configurations together - (refer to https://atmos.tools/core-concepts/components/inheritance) + (refer to https://atmos.tools/core-concepts/stacks/inheritance) ``` diff --git a/website/docs/core-concepts/components/component-vendoring.md b/website/docs/core-concepts/vendoring/components.mdx similarity index 99% rename from website/docs/core-concepts/components/component-vendoring.md rename to website/docs/core-concepts/vendoring/components.mdx index ab62b6579..1b4d3a6e2 100644 --- a/website/docs/core-concepts/components/component-vendoring.md +++ b/website/docs/core-concepts/vendoring/components.mdx @@ -1,9 +1,9 @@ --- title: Component Vendoring sidebar_position: 3 -sidebar_label: Vendoring +sidebar_label: Components description: Use Component Vendoring to make copies of 3rd-party components in your own repo. -id: vendoring +id: components --- Atmos natively supports the concept of "vendoring", which is making a copy of 3rd-party components or other dependencies in your own repo. diff --git a/website/docs/core-concepts/vendoring/vendoring.mdx b/website/docs/core-concepts/vendoring/vendoring.mdx index 5bbc50107..d897d6dcb 100644 --- a/website/docs/core-concepts/vendoring/vendoring.mdx +++ b/website/docs/core-concepts/vendoring/vendoring.mdx @@ -1,10 +1,11 @@ --- title: Vendoring description: Use Atmos vendoring to make copies of 3rd-party components, stacks, and other artifacts in your own repo. -sidebar_position: 4 -sidebar_label: Vendoring +sidebar_position: 14 +sidebar_label: Vendor Dependencies id: vendoring --- +import File from '@site/src/components/File' Atmos natively supports "vendoring," a practice that involves replicating 3rd-party components, stacks, and artifacts within your own repository. This feature is particularly beneficial for managing dependencies in software like Terraform, which do not support pulling root modules remotely diff --git a/website/docs/core-concepts/workflows/workflows.mdx b/website/docs/core-concepts/workflows/workflows.mdx index 6123dbbf8..406aa06fc 100644 --- a/website/docs/core-concepts/workflows/workflows.mdx +++ b/website/docs/core-concepts/workflows/workflows.mdx @@ -1,7 +1,7 @@ --- title: Workflows -sidebar_position: 3 -sidebar_label: Workflows +sidebar_position: 12 +sidebar_label: Automate Workflows --- import File from '@site/src/components/File' diff --git a/website/docs/design-patterns/abstract-component.mdx b/website/docs/design-patterns/abstract-component.mdx index 9366c25e9..29f038d42 100644 --- a/website/docs/design-patterns/abstract-component.mdx +++ b/website/docs/design-patterns/abstract-component.mdx @@ -228,4 +228,4 @@ being deployed by 'metadata.type: abstract' attribute ## References - [Component-Oriented Programming](/core-concepts/components/component-oriented-programming) -- [Component Inheritance](/core-concepts/components/inheritance) +- [Component Inheritance](/core-concepts/stacks/inheritance) diff --git a/website/docs/design-patterns/component-inheritance.mdx b/website/docs/design-patterns/component-inheritance.mdx index b1eb29636..9139b3a97 100644 --- a/website/docs/design-patterns/component-inheritance.mdx +++ b/website/docs/design-patterns/component-inheritance.mdx @@ -16,7 +16,7 @@ properties of the base component(s) and overriding only some fields specific to properties of the base component(s), allowing creating very DRY configurations that are built upon existing components. :::note -Atmos supports many different types on component inheritance. Refer to [Component Inheritance](/core-concepts/components/inheritance) for +Atmos supports many different types on component inheritance. Refer to [Component Inheritance](/core-concepts/stacks/inheritance) for more details. ::: @@ -187,4 +187,4 @@ components: ## References - [Component-Oriented Programming](/core-concepts/components/component-oriented-programming) -- [Component Inheritance](/core-concepts/components/inheritance) +- [Component Inheritance](/core-concepts/stacks/inheritance) diff --git a/website/docs/design-patterns/component-overrides.mdx b/website/docs/design-patterns/component-overrides.mdx index b6798a3c8..21e8faa18 100644 --- a/website/docs/design-patterns/component-overrides.mdx +++ b/website/docs/design-patterns/component-overrides.mdx @@ -16,7 +16,7 @@ This is achieved by using the `overrides` section in Atmos stack manifests.
:::tip -Refer to [Component Overrides](/core-concepts/components/overrides) for more information on the `overrides` section +Refer to [Component Overrides](/core-concepts/stacks/overrides) for more information on the `overrides` section ::: ## Use-cases diff --git a/website/docs/design-patterns/design-patterns.mdx b/website/docs/design-patterns/design-patterns.mdx index ce9d2f284..d233c1409 100644 --- a/website/docs/design-patterns/design-patterns.mdx +++ b/website/docs/design-patterns/design-patterns.mdx @@ -1,7 +1,7 @@ --- title: Atmos Design Patterns sidebar_position: 5 -sidebar_label: Design Patterns +sidebar_label: Use Design Patterns description: Atmos Design Patterns. Elements of Reusable Infrastructure Configuration id: design-patterns --- diff --git a/website/docs/design-patterns/partial-component-configuration.mdx b/website/docs/design-patterns/partial-component-configuration.mdx index 25fcff8b2..feab4257f 100644 --- a/website/docs/design-patterns/partial-component-configuration.mdx +++ b/website/docs/design-patterns/partial-component-configuration.mdx @@ -13,7 +13,7 @@ manifests to manage, modify and apply them separately and independently in one t The mechanism is similar to [Partial Classes in C#](https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/partial-classes-and-methods). -This is not the same as Atmos [Component Inheritance](/core-concepts/components/inheritance) where more than one Atmos components +This is not the same as Atmos [Component Inheritance](/core-concepts/stacks/inheritance) where more than one Atmos components take part in the inheritance chain. The **Partial Component Configuration** pattern deals with just one Atmos component with its configuration split across a few configuration files. @@ -200,7 +200,7 @@ import: # Import the mixin for the required Kubernetes version to define the k8s version and addon versions for the EKS cluster in this stack. # This is an example of partial component configuration in Atmos where the config for the component is split across many Atmos stack manifests (stack config files). # It's similar to Partial Classes in C# (https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/partial-classes-and-methods). - # This is not the same as 'Atmos Component Inheritance' (https://atmos.tools/core-concepts/components/inheritance) + # This is not the same as 'Atmos Component Inheritance' (https://atmos.tools/core-concepts/stacks/inheritance) # where more than one Atmos component participates in the inheritance chain. - catalog/eks/clusters/mixins/k8s-1-27 ``` diff --git a/website/docs/integrations/github-actions/atmos-terraform-plan.mdx b/website/docs/integrations/github-actions/atmos-terraform-plan.mdx index 3d443d303..0737c5196 100644 --- a/website/docs/integrations/github-actions/atmos-terraform-plan.mdx +++ b/website/docs/integrations/github-actions/atmos-terraform-plan.mdx @@ -4,8 +4,6 @@ sidebar_position: 40 sidebar_label: Terraform Plan --- -import File from '@site/src/components/File' - The Cloud Posse GitHub Action for "Atmos Terraform Plan" simplifies provisioning Terraform from within GitHub using workflows. Understand precisely what to expect from running a `terraform plan` from directly within the GitHub UI for any Pull Request. Given any component and stack in an Atmos supported infrastructure environment, [`github-action-atmos-terraform-plan`](https://github.com/cloudposse/github-action-atmos-terraform-plan) will run `atmos terraform plan`, generate a Terraform [planfile](https://developer.hashicorp.com/terraform/tutorials/automation/automate-terraform), store this planfile in an S3 Bucket with metadata in DynamodDB, and finally format the Terraform Plan result as part of a [GitHub Workflow Job Summary](https://github.blog/2022-05-09-supercharging-github-actions-with-job-summaries/). @@ -37,7 +35,7 @@ Furthermore, when a resource is marked for deletion, the Plan Summary will inclu ![Example Destroy](/img/github-actions/destroy.png) -## Usage Example +## Usage In this example, the action is triggered when certain events occur, such as a manual workflow dispatch or the opening, synchronization, or reopening of a pull request, specifically on the main branch. It specifies specific permissions related to assuming roles in AWS. Within the "plan" job, the "component" and "stack" are hardcoded (`foobar` and `plat-ue2-sandbox`). In practice, these are usually derived from another action. @@ -47,36 +45,131 @@ We recommend combining this action with the [`affected-stacks`](/integrations/gi ::: - + +```yaml + # .github/workflows/atmos-terraform-plan.yaml + name: "atmos-terraform-plan" + on: + pull_request: + types: + - opened + - synchronize + - reopened + branches: + - main + # These permissions are required for GitHub to assume roles in AWS + permissions: + id-token: write + contents: read + jobs: + plan: + runs-on: ubuntu-latest + steps: + - name: Plan Atmos Component + uses: cloudposse/github-action-atmos-terraform-plan@v1 + with: + component: "foobar" + stack: "plat-ue2-sandbox" + atmos-gitops-config-path: ./.github/config/atmos-gitops.yaml +``` + +with the following configuration as an example: + ```yaml -name: "atmos-terraform-plan" -on: - pull_request: - types: - - opened - - synchronize - - reopened - branches: - - main -# These permissions are required for GitHub to assume roles in AWS -permissions: - id-token: write - contents: read -jobs: - plan: - runs-on: ubuntu-latest - steps: - - name: Plan Atmos Component - uses: cloudposse/github-action-atmos-terraform-plan@v2 - with: - component: "foobar" - stack: "plat-ue2-sandbox" - sha: ${{ github.sha }} - atmos-config-path: ./rootfs/usr/local/etc/atmos/ - atmos-version: 1.63.0 + # .github/config/atmos-gitops.yaml + atmos-config-path: ./rootfs/usr/local/etc/atmos/ + atmos-version: 1.65.0 + aws-region: us-east-2 + enable-infracost: false + group-by: .stack_slug | split("-") | [.[0], .[2]] | join("-") + sort-by: .stack_slug + terraform-apply-role: arn:aws:iam::yyyyyyyyyyyy:role/cptest-core-gbl-identity-gitops + terraform-plan-role: arn:aws:iam::yyyyyyyyyyyy:role/cptest-core-gbl-identity-gitops + terraform-state-bucket: cptest-core-ue2-auto-gitops + terraform-state-role: arn:aws:iam::xxxxxxxxxxxx:role/cptest-core-ue2-auto-gitops-gha + terraform-state-table: cptest-core-ue2-auto-gitops + terraform-version: 1.65.0 ``` - ## Requirements -This action has the requirements as [Github Actions](/integrations/github-actions/). Use the same S3 Bucket, DynamoDB table, IAM Roles and config described there. +This GitHub Action depends on a few resources: +* **S3 bucket** for storing planfiles +* **DynamoDB table** for retrieving metadata about planfiles +* **2x IAM roles** for "planning" and accessing the "state" bucket + +### S3 Bucket + +This action can use any S3 Bucket to keep track of your planfiles. Just ensure the bucket is properly locked down since planfiles may contain secrets. + +For example, [vendor in](/core-concepts/vendoring/components) the [`s3-component`](https://docs.cloudposse.com/components/library/aws/s3-bucket/), then using an [Atmos stack configuration](/core-concepts/stacks/), define a bucket using the [`s3-bucket` component](https://github.com/cloudposse/terraform-aws-components/tree/main/modules/s3-bucket) with this catalog configuration: + +```yaml +import: + - catalog/s3-bucket/defaults + +components: + terraform: + # S3 Bucket for storing Terraform Plans + gitops/s3-bucket: + metadata: + component: s3-bucket + inherits: + - s3-bucket/defaults + vars: + name: gitops-plan-storage + allow_encrypted_uploads_only: false +``` + + +Assign this S3 Bucket ARN to the `terraform-plan-bucket` input. + +### DynamoDB Table + +Similarly, a simple DynamoDB table can be provisioned using our [`dynamodb` component](https://docs.cloudposse.com/components/library/aws/dynamodb/). Set the **Hash Key** and create a **Global Secondary Index** as follows: + +```yaml +import: + - catalog/dynamodb/defaults + +components: + terraform: + # DynamoDB table used to store metadata for Terraform Plans + gitops/dynamodb: + metadata: + component: dynamodb + inherits: + - dynamodb/defaults + vars: + name: gitops-plan-storage + # This key (case-sensitive) is required for the cloudposse/github-action-terraform-plan-storage action + hash_key: id + range_key: "" + # Only these 2 attributes are required for creating the GSI, + # but there will be several other attributes on the table itself + dynamodb_attributes: + - name: 'createdAt' + type: 'S' + - name: 'pr' + type: 'N' + # This GSI is used to Query the latest plan file for a given PR. + global_secondary_index_map: + - name: pr-createdAt-index + hash_key: pr + range_key: createdAt + projection_type: ALL + non_key_attributes: [] + read_capacity: null + write_capacity: null + # Auto delete old entries + ttl_enabled: true + ttl_attribute: ttl +``` + +Pass the ARN of this table as the input to the `terraform-plan-table` of the [`cloudposse/github-action-atmos-terraform-plan`](https://github.com/cloudposse/github-action-atmos-terraform-plan) GitHub Action. + +### IAM Access Roles + +First create an access role for storing and retrieving planfiles from the S3 Bucket and DynamoDB table. We deploy this role using the [`gitops` component](https://docs.cloudposse.com/components/library/aws/gitops/). Assign this role ARN to the `terraform-state-role` input. + +Next, create a role for GitHub workflows to use to plan and apply Terraform. We typically create an "AWS Team" with our [`aws-teams` component](https://docs.cloudposse.com/components/library/aws/aws-teams/), and then allow this team to assume `terraform` in the delegated accounts with our [`aws-team-roles` component](https://docs.cloudposse.com/components/library/aws/aws-team-roles/). Assign this role ARN to the `terraform-plan-role` input diff --git a/website/docs/integrations/github-actions/setup-atmos.mdx b/website/docs/integrations/github-actions/setup-atmos.mdx index c225615b7..0004d8a33 100644 --- a/website/docs/integrations/github-actions/setup-atmos.mdx +++ b/website/docs/integrations/github-actions/setup-atmos.mdx @@ -8,7 +8,7 @@ import File from '@site/src/components/File' The Cloud Posse GitHub Action to "Setup Atmos" simplifies your GitHub Action Workflows. -Easily integrate Atmos into your GitHub Action workflows using [`github-action-setup-atmos`](https://github.com/cloudposse/github-action-setup-atmos). To simplify your workflows, we offer a [GitHub Action](https://github.com/cloudposse/github-action-setup-atmos) that streamlines the process of [installing Atmos](/quick-start/install-atmos). +Easily integrate Atmos into your GitHub Action workflows using [`github-action-setup-atmos`](https://github.com/cloudposse/github-action-setup-atmos). To simplify your workflows, we offer a [GitHub Action](https://github.com/cloudposse/github-action-setup-atmos) that streamlines the process of [installing Atmos](/install). We provide a [GitHub Action](https://github.com/cloudposse/github-action-setup-atmos) to make that easier for CI/CD applications. diff --git a/website/docs/introduction/faq.mdx b/website/docs/introduction/faq.mdx index e37158415..d0c198d0e 100644 --- a/website/docs/introduction/faq.mdx +++ b/website/docs/introduction/faq.mdx @@ -2,7 +2,7 @@ slug: /faq title: Atmos FAQ sidebar_label: FAQ -sidebar_position: 3 +sidebar_position: 4 --- @@ -66,7 +66,7 @@ and offers an easy exit strategy by [generating and committing these files](/cli #### Atmos provides prescriptive guidance on operating Terraform at scale -Furthermore, Atmos delivers prescriptive guidance on [design patterns](/design-patterns/) and [component architecture](/core-concepts/components/component-oriented-programming) for Terraform root modules, establishing itself as an opinionated framework designed to enhance Terraform's capabilities. It offers [advanced features](/core-concepts/components/inheritance) tailored for both straightforward and intricate deployment scenarios. Essentially acting as a comprehensive framework, Atmos is exceptionally well-suited for complex, regulated enterprise environments. Its robust support for [Stack manifests](/core-concepts/stacks) underscores its versatility as a tool, enabling precise and effortless infrastructure management and orchestration across various scales and complexities. +Furthermore, Atmos delivers prescriptive guidance on [design patterns](/design-patterns/) and [component architecture](/core-concepts/components/component-oriented-programming) for Terraform root modules, establishing itself as an opinionated framework designed to enhance Terraform's capabilities. It offers [advanced features](/core-concepts/stacks/inheritance) tailored for both straightforward and intricate deployment scenarios. Essentially acting as a comprehensive framework, Atmos is exceptionally well-suited for complex, regulated enterprise environments. Its robust support for [Stack manifests](/core-concepts/stacks) underscores its versatility as a tool, enabling precise and effortless infrastructure management and orchestration across various scales and complexities. ### Can Atmos be used together with Terragrunt? diff --git a/website/docs/introduction/index.mdx b/website/docs/introduction/index.mdx index c26a38d6f..ac6d6b907 100644 --- a/website/docs/introduction/index.mdx +++ b/website/docs/introduction/index.mdx @@ -17,7 +17,7 @@ import Link from '@docusaurus/Link' Use Atmos to easily compose complex architectures based on Terraform with very [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) configuration. Concepts like [Stacks](/core-concepts/stacks) and [Components](/core-concepts/components) -help you overcome most of [Terraform's limitations](/reference/terraform-limitations/) +help you overcome most of [Terraform's limitations](/core-concepts/components/terraform/journey) by using [established conventions](/core-concepts) and proven [design patterns](/design-patterns/). #### Are you tired of doing Terraform the old way? Try the new way. diff --git a/website/docs/introduction/use-cases.md b/website/docs/introduction/use-cases.md index 54a9f840c..79bf3ba61 100644 --- a/website/docs/introduction/use-cases.md +++ b/website/docs/introduction/use-cases.md @@ -3,7 +3,7 @@ title: Atmos Use-Cases id: use-cases slug: /use-cases sidebar_label: Use-cases -sidebar_position: 2 +sidebar_position: 3 --- Atmos has consistently demonstrated its effectiveness in addressing these key use-cases, showcasing its adaptability and @@ -13,8 +13,8 @@ strength in the cloud infrastructure and DevOps domains: projects or stages of development. - **Cross-Platform Cloud Architectures.**
Ideal for businesses that need to manage the configuration of services across AWS, GCP, Azure, etc., to build a cohesive system. - **Multi-Tenant Systems for SaaS.**
Perfect for SaaS companies looking to host multiple customers within a unified infrastructure. Simply define a baseline tenant configuration once, and then seamlessly onboard new tenants by reusing this baseline through pure configuration, bypassing the need for further code development. -- **Efficient Multi-Region Deployments.**
Atmos facilitates streamlined multi-region deployments by enabling businesses to define baseline configurations with [stacks](/core-concepts/stacks/) and extend them across regions with DRY principles through [imports](/core-concepts/stacks/imports) and [inheritance](/core-concepts/components/inheritance). -- **Compliant Infrastructure for Regulated Industries.**
Atmos empowers DevOps and SecOps teams to create vetted configurations that comply with SOC2, HIPAA, HITRUST, PCI, and other regulatory standards. These configurations can then be efficiently shared and reused across the organization via [service catalogs](/core-concepts/stacks/catalogs), [component libraries](/core-concepts/components/library), [vendoring](/core-concepts/vendoring), and [OPA policies](/core-concepts/components/validation), simplifying the process of achieving and maintaining rigorous compliance. +- **Efficient Multi-Region Deployments.**
Atmos facilitates streamlined multi-region deployments by enabling businesses to define baseline configurations with [stacks](/core-concepts/stacks/) and extend them across regions with DRY principles through [imports](/core-concepts/stacks/imports) and [inheritance](/core-concepts/stacks/inheritance). +- **Compliant Infrastructure for Regulated Industries.**
Atmos empowers DevOps and SecOps teams to create vetted configurations that comply with SOC2, HIPAA, HITRUST, PCI, and other regulatory standards. These configurations can then be efficiently shared and reused across the organization via [service catalogs](/core-concepts/stacks/catalogs), [component libraries](/core-concepts/components/library), [vendoring](/core-concepts/vendoring), and [OPA policies](/core-concepts/validating/components), simplifying the process of achieving and maintaining rigorous compliance. - **Empowering Teams with Self-Service Infrastructure.**
Allows teams to manage their infrastructure needs independently, using predefined templates and policies. - **Streamlining Deployment with Service Catalogs, Landing Zones, and Blueprints:** Provides businesses the ability to craft their own ready-to-use templates and guidelines for setting up cloud environments quickly and consistently, tailored to the unique needs of the organization. diff --git a/website/docs/quick-start/add-custom-commands.mdx b/website/docs/quick-start/advanced/add-custom-commands.mdx similarity index 100% rename from website/docs/quick-start/add-custom-commands.mdx rename to website/docs/quick-start/advanced/add-custom-commands.mdx diff --git a/website/docs/quick-start/advanced/advanced.mdx b/website/docs/quick-start/advanced/advanced.mdx new file mode 100644 index 000000000..f2d93b993 --- /dev/null +++ b/website/docs/quick-start/advanced/advanced.mdx @@ -0,0 +1,42 @@ +--- +title: Advanced Tutorial +sidebar_position: 4 +sidebar_label: Advanced Tutorial +description: Take 30 minutes to learn the most important Atmos concepts. +id: advanced +--- + +# Advanced Tutorial + +Take 30 minutes to learn the most important Atmos concepts. + +:::tip + +This Quick Start guide describes the steps to configure and provision the infrastructure +from this [Quick Start](https://github.com/cloudposse/atmos/tree/master/examples/quick-start) repository. + +You can clone it and configure to your own needs. The repository should be a good start to get yourself familiar with Atmos. + +::: + +
+ +The steps to configure and provision the infrastructure are as follows: + +- [Install Atmos](/install) +- [Configure Repository](/quick-start/advanced/configure-repository) +- [Configure CLI](/quick-start/advanced/configure-cli) +- [Vendor Components](/quick-start/advanced/vendor-components) +- [Create Atmos Stacks](/quick-start/advanced/create-atmos-stacks) +- [Configure Validation](/quick-start/advanced/configure-validation) +- [Create Workflows](/quick-start/advanced/create-workflows) +- [Add Custom Commands](/quick-start/advanced/add-custom-commands) +- [Configure Terraform Backend](/quick-start/advanced/configure-terraform-backend) +- [Provision](/quick-start/advanced/provision) +- [Final Notes](/quick-start/advanced/final-notes) +- [Next Steps](/quick-start/advanced/next-steps) + + +import DocCardList from "@theme/DocCardList"; + + diff --git a/website/docs/quick-start/configure-cli.mdx b/website/docs/quick-start/advanced/configure-cli.mdx similarity index 94% rename from website/docs/quick-start/configure-cli.mdx rename to website/docs/quick-start/advanced/configure-cli.mdx index d25bafb85..dcf9ff028 100644 --- a/website/docs/quick-start/configure-cli.mdx +++ b/website/docs/quick-start/advanced/configure-cli.mdx @@ -9,7 +9,7 @@ In the previous step, we've decided on the following: - Use a monorepo to configure and provision two Terraform components into three AWS accounts and two AWS regions - The filesystem layout for the infrastructure monorepo -- To be able to use [Component Remote State](/core-concepts/components/remote-state), we put the `atmos.yaml` CLI config file +- To be able to use [Component Remote State](/core-concepts/components/terraform/remote-state), we put the `atmos.yaml` CLI config file into `/usr/local/etc/atmos/atmos.yaml` folder and set the ENV var `ATMOS_BASE_PATH` to point to the absolute path of the root of the repo Next step is to configure `atmos.yaml`. @@ -106,7 +106,7 @@ schemas: # JSON Schema to validate Atmos manifests # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ - # https://atmos.tools/quick-start/configure-validation/ + # https://atmos.tools/quick-start/advanced/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json # https://json-schema.org/draft/2020-12/release-notes atmos: @@ -127,7 +127,7 @@ to [CLI Configuration](/cli/configuration). var `ATMOS_BASE_PATH` to point to the absolute path of the root of the repo - `components.terraform.base_path` - the base path to the Terraform components (Terraform root modules). As described in - [Configure Repository](/quick-start/configure-repository), we've decided to put the Terraform components into the `components/terraform` directory, + [Configure Repository](/quick-start/advanced/configure-repository), we've decided to put the Terraform components into the `components/terraform` directory, and this setting tells Atmos where to find them. Atmos will join the base path (set in the `ATMOS_BASE_PATH` ENN var) with `components.terraform.base_path` to calculate the final path to the Terraform components @@ -144,7 +144,7 @@ to [CLI Configuration](/cli/configuration). configuration when executing `terraform plan` and `terraform apply` commands - `stacks.base_path` - the base path to the Atmos stacks. As described in - [Configure Repository](/quick-start/configure-repository), we've decided to put the stack configurations into the `stacks` directory, + [Configure Repository](/quick-start/advanced/configure-repository), we've decided to put the stack configurations into the `stacks` directory, and this setting tells Atmos where to find them. Atmos will join the base path (set in the `ATMOS_BASE_PATH` ENN var) with `stacks.base_path` to calculate the final path to the stacks @@ -172,4 +172,4 @@ to [CLI Configuration](/cli/configuration). - `schemas` - [JSON Schema](https://json-schema.org/) and [OPA Policy](https://www.openpolicyagent.org/) configurations for: - [Atmos Manifests Validation](/cli/schemas) - - [Atmos Components Validation](/core-concepts/components/validation) + - [Atmos Components Validation](/core-concepts/validating/components) diff --git a/website/docs/quick-start/configure-repository.md b/website/docs/quick-start/advanced/configure-repository.md similarity index 98% rename from website/docs/quick-start/configure-repository.md rename to website/docs/quick-start/advanced/configure-repository.md index f8988dfb3..eba7cea5f 100644 --- a/website/docs/quick-start/configure-repository.md +++ b/website/docs/quick-start/advanced/configure-repository.md @@ -42,7 +42,7 @@ Atmos separates code from configuration (separation of concerns). The code is in :::note While it's recommended to use the directory names as shown above, the `stacks` and `components` directory names and filesystem locations are -configurable in the `atmos.yaml` CLI config file. Refer to [Configure CLI](/quick-start/configure-cli) for more details. +configurable in the `atmos.yaml` CLI config file. Refer to [Configure CLI](/quick-start/advanced/configure-cli) for more details. :::
@@ -78,7 +78,7 @@ The following example provides the simplest filesystem layout that Atmos can wor ## `atmos.yaml` CLI Config File Location While placing `atmos.yaml` at the root of the repository will work for the `atmos` CLI, it will not work -for [Component Remote State](/core-concepts/components/remote-state) because it uses +for [Component Remote State](/core-concepts/components/terraform/remote-state) because it uses the [terraform-provider-utils](https://github.com/cloudposse/terraform-provider-utils) Terraform provider. Terraform executes the provider from the component's folder (e.g. `components/terraform/vpc`), and we don't want to replicate `atmos.yaml` into every component's folder. diff --git a/website/docs/quick-start/configure-terraform-backend.mdx b/website/docs/quick-start/advanced/configure-terraform-backend.mdx similarity index 98% rename from website/docs/quick-start/configure-terraform-backend.mdx rename to website/docs/quick-start/advanced/configure-terraform-backend.mdx index 2c39d7910..926824faa 100644 --- a/website/docs/quick-start/configure-terraform-backend.mdx +++ b/website/docs/quick-start/advanced/configure-terraform-backend.mdx @@ -160,7 +160,7 @@ Configuring Terraform S3 backend with Atmos consists of the three steps: ``` - Refer to [Quick Start: Configure CLI](/quick-start/configure-cli) and [CLI Configurtion](/cli/configuration) for more details. + Refer to [Quick Start: Configure CLI](/quick-start/advanced/configure-cli) and [CLI Configurtion](/cli/configuration) for more details. - Configure the S3 backend in one of the `_defaults.yaml` manifests. You can configure it for the entire Organization, or per OU/tenant, or per region, or per account. @@ -261,7 +261,7 @@ needs to have a separate S3 bucket, DynamoDB table, and IAM role with different access the Terraform backend only in the `dev` account, but not in `staging` and `prod`). Atmos supports this use-case by using deep-merging of stack manifests, [Imports](/core-concepts/stacks/imports) -and [Inheritance](/core-concepts/components/inheritance), which makes the backend configuration reusable and DRY. +and [Inheritance](/core-concepts/stacks/inheritance), which makes the backend configuration reusable and DRY. We'll split the backend config between the Organization and the accounts. diff --git a/website/docs/quick-start/configure-validation.mdx b/website/docs/quick-start/advanced/configure-validation.mdx similarity index 93% rename from website/docs/quick-start/configure-validation.mdx rename to website/docs/quick-start/advanced/configure-validation.mdx index eac7cca09..bb3b3bc81 100644 --- a/website/docs/quick-start/configure-validation.mdx +++ b/website/docs/quick-start/advanced/configure-validation.mdx @@ -4,7 +4,7 @@ sidebar_position: 7 sidebar_label: Configure Validation --- -Atmos supports [Atmos Manifests Validation](/cli/schemas) and [Atmos Components Validation](/core-concepts/components/validation) +Atmos supports [Atmos Manifests Validation](/cli/schemas) and [Atmos Components Validation](/core-concepts/validating/components) using [JSON Schema](https://json-schema.org/) and [OPA Policies](https://www.openpolicyagent.org/). :::tip @@ -45,7 +45,7 @@ schemas: # JSON Schema to validate Atmos manifests # https://atmos.tools/cli/schemas/ # https://atmos.tools/cli/commands/validate/stacks/ - # https://atmos.tools/quick-start/configure-validation/ + # https://atmos.tools/quick-start/advanced/configure-validation/ # https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json # https://json-schema.org/draft/2020-12/release-notes atmos: @@ -60,7 +60,7 @@ schemas: For more information, refer to: -- [Quick-Start: Configure CLI](/quick-start/configure-cli) +- [Quick-Start: Configure CLI](/quick-start/advanced/configure-cli) - [Atmos CLI Configuration](/cli/configuration) ::: @@ -122,7 +122,7 @@ Atmos component validation allows: * Check if the component config (including relations between different component variables) is correct to allow or deny component provisioning using [OPA Policies](https://www.openpolicyagent.org/) -To configure Atmos components validation, complete the steps described in [Atmos Components Validation](/core-concepts/components/validation). +To configure Atmos components validation, complete the steps described in [Atmos Components Validation](/core-concepts/validating/components).
@@ -130,7 +130,7 @@ To configure Atmos components validation, complete the steps described in [Atmos For more information, refer to: -- [Atmos Components Validation](/core-concepts/components/validation) +- [Atmos Components Validation](/core-concepts/validating/components) - [atmos validate component](/cli/commands/validate/component) ::: diff --git a/website/docs/quick-start/create-atmos-stacks.mdx b/website/docs/quick-start/advanced/create-atmos-stacks.mdx similarity index 98% rename from website/docs/quick-start/create-atmos-stacks.mdx rename to website/docs/quick-start/advanced/create-atmos-stacks.mdx index 4fd80d5f8..fa2f9a308 100644 --- a/website/docs/quick-start/create-atmos-stacks.mdx +++ b/website/docs/quick-start/advanced/create-atmos-stacks.mdx @@ -169,7 +169,7 @@ components:
These Atmos component manifests will be imported into the top-level Atmos stacks. The default variables (in the `vars` sections) -can be overridden in the derived Atmos components by using [Atmos Component Inheritance](/core-concepts/components/inheritance). +can be overridden in the derived Atmos components by using [Atmos Component Inheritance](/core-concepts/stacks/inheritance). ## Atmos Top-level Stacks @@ -179,7 +179,7 @@ stack config file names (stack manifest names) can be anything, and they can be For example, when executing the `atmos terraform apply vpc -s plat-ue2-dev` command, the Atmos stack `plat-ue2-dev` is specified by the `-s` flag. By looking at `name_pattern: "{tenant}-{environment}-{stage}"` -(see [Configure CLI](/quick-start/configure-cli)) and processing the tokens, Atmos knows that the first part of the stack name is `tenant`, the second +(see [Configure CLI](/quick-start/advanced/configure-cli)) and processing the tokens, Atmos knows that the first part of the stack name is `tenant`, the second part is `environment`, and the third part is `stage`. Then Atmos searches for the top-level stack manifest (in the `stacks` directory) where `tenant: plat`, `environment: ue2` and `stage: dev` are defined (inline or via imports). diff --git a/website/docs/quick-start/create-workflows.mdx b/website/docs/quick-start/advanced/create-workflows.mdx similarity index 100% rename from website/docs/quick-start/create-workflows.mdx rename to website/docs/quick-start/advanced/create-workflows.mdx diff --git a/website/docs/quick-start/final-notes.mdx b/website/docs/quick-start/advanced/final-notes.mdx similarity index 100% rename from website/docs/quick-start/final-notes.mdx rename to website/docs/quick-start/advanced/final-notes.mdx diff --git a/website/docs/quick-start/next-steps.md b/website/docs/quick-start/advanced/next-steps.md similarity index 80% rename from website/docs/quick-start/next-steps.md rename to website/docs/quick-start/advanced/next-steps.md index 8bb69b467..bb05b97d1 100644 --- a/website/docs/quick-start/next-steps.md +++ b/website/docs/quick-start/advanced/next-steps.md @@ -15,10 +15,10 @@ Here are some of the major differentiators of Atmos: * [Atmos Design Patterns](/design-patterns) * [Third-party Integrations](/integrations) * [Atmos Vendoring](/core-concepts/vendoring) -* [Component Vendoring](/core-concepts/components/vendoring) +* [Component Vendoring](/core-concepts/vendoring/components) * [Imports](/core-concepts/stacks/imports) (mixins, catalogs) * [Workflow Automation](/core-concepts/workflows) * [Custom Commands](/core-concepts/custom-commands) -* [Component Inheritance & Multiple Inheritance](/core-concepts/components/inheritance) -* [JSON Schema & OPA Policy Enforcement](/core-concepts/components/validation) +* [Component Inheritance & Multiple Inheritance](/core-concepts/stacks/inheritance) +* [JSON Schema & OPA Policy Enforcement](/core-concepts/validating/components) * [Atmos Manifest JSON Schema](/cli/schemas) diff --git a/website/docs/quick-start/provision.md b/website/docs/quick-start/advanced/provision.md similarity index 92% rename from website/docs/quick-start/provision.md rename to website/docs/quick-start/advanced/provision.md index 51be87ea4..4cd559b2b 100644 --- a/website/docs/quick-start/provision.md +++ b/website/docs/quick-start/advanced/provision.md @@ -48,7 +48,7 @@ atmos terraform apply vpc -s plat-uw2-prod
-Alternatively, you can execute the configured [Atmos workflow](/quick-start/create-workflows) to provision all the components in all the stacks: +Alternatively, you can execute the configured [Atmos workflow](/quick-start/advanced/create-workflows) to provision all the components in all the stacks: ```shell # Execute the workflow `apply-all-components` from the workflow manifest `networking` @@ -61,7 +61,7 @@ Looking at the commands above, you might have a question "How does Atmos find th Let's consider what Atmos does when executing the command `atmos terraform apply vpc -s plat-ue2-prod`: -- Atmos uses the [CLI config](/quick-start/configure-cli) `stacks.name_pattern: "{tenant}-{environment}-{stage}"` to figure out that the first part of +- Atmos uses the [CLI config](/quick-start/advanced/configure-cli) `stacks.name_pattern: "{tenant}-{environment}-{stage}"` to figure out that the first part of the stack name is `tenant`, the second part is `environment`, and the third part is `stage` - Atmos searches for the stack configuration file (in the `stacks` folder and all sub-folders) where `tenant: plat`, `environment: ue2` diff --git a/website/docs/quick-start/vendor-components.mdx b/website/docs/quick-start/advanced/vendor-components.mdx similarity index 99% rename from website/docs/quick-start/vendor-components.mdx rename to website/docs/quick-start/advanced/vendor-components.mdx index 780866736..42f5932f0 100644 --- a/website/docs/quick-start/vendor-components.mdx +++ b/website/docs/quick-start/advanced/vendor-components.mdx @@ -262,4 +262,4 @@ For this to work for both the `atmos` CLI and the Terraform `utils` provider, we
-For a complete description of how Atmos components use remote state, refer to [Component Remote State](/core-concepts/components/remote-state). +For a complete description of how Atmos components use remote state, refer to [Component Remote State](/core-concepts/components/terraform/remote-state). diff --git a/website/docs/quick-start/install-atmos.mdx b/website/docs/quick-start/install-atmos.mdx index f600d5f01..a6fcef291 100644 --- a/website/docs/quick-start/install-atmos.mdx +++ b/website/docs/quick-start/install-atmos.mdx @@ -2,6 +2,7 @@ title: Install Atmos sidebar_label: Install Atmos sidebar_position: 2 +slug: /install --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; diff --git a/website/docs/quick-start/introduction.md b/website/docs/quick-start/introduction.md index 9a68b1161..a95e11317 100644 --- a/website/docs/quick-start/introduction.md +++ b/website/docs/quick-start/introduction.md @@ -2,6 +2,9 @@ title: Quick Start Introduction sidebar_position: 1 sidebar_label: Introduction +sidebar_class_name: hidden +id: quick-start +slug: /quick-start --- # Introduction @@ -24,36 +27,10 @@ are [Terraform root modules](https://developer.hashicorp.com/terraform/language/ In many cases, with enterprise-grade infrastructures (multi-org, multi-tenant, multi-account, multi-region, multi-team), the configuration is much more complicated than the code. That's what Atmos is trying to solve - to make the configuration manageable, reusable (by -using [Imports](/core-concepts/stacks/imports), [Inheritance](/core-concepts/components/inheritance), and other +using [Imports](/core-concepts/stacks/imports), [Inheritance](/core-concepts/stacks/inheritance), and other Atmos features) and [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself), and to make the code completely generic. In this Quick Start guide, we describe how to provision infrastructure managed by Terraform into different AWS environments. The configurations for the environments are managed by Atmos.
- -:::tip - -This Quick Start guide describes the steps to configure and provision the infrastructure -from this [Quick Start](https://github.com/cloudposse/atmos/tree/master/examples/quick-start) repository. - -You can clone it and configure to your own needs. The repository should be a good start to get yourself familiar with Atmos. - -::: - -
- -The steps to configure and provision the infrastructure are as follows: - -- [Install Atmos](/quick-start/install-atmos) -- [Configure Repository](/quick-start/configure-repository) -- [Configure CLI](/quick-start/configure-cli) -- [Vendor Components](/quick-start/vendor-components) -- [Create Atmos Stacks](/quick-start/create-atmos-stacks) -- [Configure Validation](/quick-start/configure-validation) -- [Create Workflows](/quick-start/create-workflows) -- [Add Custom Commands](/quick-start/add-custom-commands) -- [Configure Terraform Backend](/quick-start/configure-terraform-backend) -- [Provision](/quick-start/provision) -- [Final Notes](/quick-start/final-notes) -- [Next Steps](/quick-start/next-steps) diff --git a/website/docs/reference/alternatives.md b/website/docs/reference/alternatives.md index b4f9fef9b..ec987d2a5 100644 --- a/website/docs/reference/alternatives.md +++ b/website/docs/reference/alternatives.md @@ -4,13 +4,54 @@ sidebar_label: Alternatives sidebar_position: 3 --- -To better understand where Atmos fits in, it may be helpful to understand some of the alternative tooling it seeks to replace. There are lots of great -tools out there and we're going through a bit of a "DevOps Rennisance" when it comes to creativity on how to automate systems. +To better understand where Atmos fits in, it may be helpful to understand some of the alternative tooling it seeks to replace. +There are lots of great tools out there and we're going through a bit of a "DevOps Rennisance" when it comes to creativity +on how to automate systems. + +## Conceptual Inspiration + +Atmos is inspired by the follow frameworks or tooling. + +### React for JavaScript + +https://react.dev/ + +[React’s](https://react.dev/) component-based architecture serves as a key inspiration for Atmos. By breaking down UIs into reusable components, React simplifies the development of complex applications. Similarly, Atmos promotes modularity in infrastructure as code, allowing components to be reused across different environments and projects. For example, in Atmos, any Terraform "root module" may be used as a component. + +### Kustomize for Kubernetes + +https://kustomize.io/ + +[Kustomize](https://kustomize.io/) introduces a template-free way to customize Kubernetes configurations, focusing on overlays and inheritance to manage configuration variations. Atmos adopts a similar approach, enabling users to import, overlay, and override configurations efficiently, thereby simplifying the management of complex infrastructure setups, all without relying on templating. + +However, due to popular demand, Atmos now supports advanced templating and data sources in addition to the original template-free configurations. Templating complicates configurations and should be used solely as an escape hatch for when the first-class concepts of imports and inheritance are insufficient. + +### Helmfile for Helm Charts + +https://helmfile.com + +[Helmfile](https://helmfile.com) manages collections of Helm charts with a declarative syntax, combining them into a "stack" for deployment to Kubernetes. It handles environmental configuration, deep merging it and evaluating templates with a Go template engine before passing the values files to Helm. + +Atmos draws from Helmfile’s ability to orchestrate multiple Helm charts, applying the concept to Terraform root modules to manage interdependencies and deployment order. It supports environmental configuration through stack configurations that define all the environmental configuration for Terraform root modules. Atmos generates the necessary Terraform `.tfvar` files, much like Helmfile generates Helm values files, ensuring consistent and efficient deployment of Terraform infrastructure. + +### Helm Charts for Configuration + +https://helm.sh/ + +[Helm Charts](https://helm.sh/) provide a packaging format for deploying applications on Kubernetes, simplifying the processes of defining, installing, and upgrading even the most complex applications. Similarly, Atmos organizes Terraform configurations into reusable, versioned modules, facilitating consistent and repeatable infrastructure deployments. + +The concept is that if your root modules are sufficiently parameterized, they function much like Helm charts. You only need to supply the appropriate values to achieve the desired configuration. + +### Vendir by Tanzu + +https://github.com/carvel-dev/vendir + +Atmos Vendoring was heavily inspired by [Vendir from VMWare Tanzu](https://github.com/carvel-dev/vendir), which served as the basis for our initial implementation. However, after using it, we realized we only needed a simpler subset of Vendir’s full functionality. Therefore, we implemented our own version using [HashiCorp’s GoGetter (MPL-2.0) library](https://github.com/hashicorp/go-getter). Additionally, we’ve added support for OCI, allowing Vendoring to pull configurations from anywhere. This advanced feature enables consistent and declarative pulling of configurations not just for components, but also for stack configurations or any dependencies you have. ## General Alternatives -There are many tools in the general category of "task runners" or "workflow automation". Here are some of the alternatives to Atmos, many of which -inspired core functionality in Atmos. +There are many tools in the general category of "task runners" or "workflow automation". +Here are some of the alternatives to Atmos, many of which inspired core functionality in Atmos. ### Make (Makefile) by Free Software Foundation @@ -64,7 +105,7 @@ Atmos is heavily inspired by the excellent schema provided by AppBuilder and has our [Custom Commands](/core-concepts/custom-commands). ::: -## Terraform Alternatives +## Terraform-specific Tooling Alternatives There are many tools explicitly designed around how to deploy with Terraform. diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 029a0717d..0c61cac16 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -40,11 +40,11 @@ const config = { [ '@docusaurus/plugin-client-redirects', { redirects: [ - /* + { - from: '/cli', - to: '/cli/configuration' - }*/ + from: '/reference/terraform-limitations', + to: '/core-concepts/components/terraform/journey' + } ], }, ], diff --git a/website/sidebars.js b/website/sidebars.js index b8c1a5b04..696986e87 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -69,6 +69,7 @@ module.exports = { }, ] }, + ] }, @@ -114,7 +115,20 @@ module.exports = { ] } ] - } + }, + { + type: 'category', + label: 'Cheat Sheets', + className: 'sidebar-title', + collapsible: false, + collapsed: false, + items: [ + { + type: 'autogenerated', + dirName: 'cheatsheets', + }, + ] + } ], cli: [ { diff --git a/website/src/components/screengrabs/atmos-version.html b/website/src/components/screengrabs/atmos-version.html index c7007cdfe..27592995d 100644 --- a/website/src/components/screengrabs/atmos-version.html +++ b/website/src/components/screengrabs/atmos-version.html @@ -17,5 +17,5 @@ https://github.com/cloudposse/atmos/releases Install Atmos: -https://atmos.tools/quick-start/install-atmos +https://atmos.tools/install diff --git a/website/src/pages/index.js b/website/src/pages/index.js index a7363e8e0..79d2097da 100644 --- a/website/src/pages/index.js +++ b/website/src/pages/index.js @@ -21,7 +21,7 @@ function Home() {

Try the Quick Start

Learn More

-

Frustrated using Terraform the old fashion way? There's a smarter option.

+

Use a component oriented framework for Terraform backed by YAML

Simplify complex architectures with DRY configuration

From e31d927fb7434a2b4bc34e10af49393a3c29d9d0 Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Sat, 1 Jun 2024 15:28:18 -0500 Subject: [PATCH 003/151] wording --- .../docs/core-concepts/components/terraform/journey.mdx | 9 ++++----- .../core-concepts/components/terraform/terraform.mdx | 6 ++---- website/docs/introduction/index.mdx | 5 +++-- website/docs/reference/reference.mdx | 1 + website/sidebars.js | 2 +- website/src/pages/index.js | 2 +- 6 files changed, 12 insertions(+), 13 deletions(-) diff --git a/website/docs/core-concepts/components/terraform/journey.mdx b/website/docs/core-concepts/components/terraform/journey.mdx index 8b2af43a9..ce558ae61 100644 --- a/website/docs/core-concepts/components/terraform/journey.mdx +++ b/website/docs/core-concepts/components/terraform/journey.mdx @@ -12,11 +12,10 @@ To better understand the rationale behind Atmos's design, it may be helpful to h integral to our development processes at [Cloud Posse](https://cloudposse.com). Let's explore the challenges and constraints we faced using Terraform, which paved the way for creating Atmos. -Every team has a natural progression of Terraform adoption that follows a similar path and matures along the way. - -Every advancement in tool adoption is accompanied by new challenges, introducing complexities that are justified by the evolution's benefits. -Indeed, the true value of these evolutions often only becomes clear once we're faced with the intricate challenges they address. -Here's what a typical path of adoption looks like for organizations adopting Terraform. +Every team progresses through a similar path when adopting Terraform, maturing over time. +Each advancement brings new challenges, adding complexities that are ultimately justified by the benefits. +Often, the true value of these evolutions becomes clear when we encounter and address these intricate challenges. +Here’s a typical adoption path for organizations using Terraform. :::tip **TL;DR:** [You can shortcuit this entire process by using Atmos from the start.](#whats-the-solution-hello-atmos-) 😎 diff --git a/website/docs/core-concepts/components/terraform/terraform.mdx b/website/docs/core-concepts/components/terraform/terraform.mdx index 280d51c10..270843893 100644 --- a/website/docs/core-concepts/components/terraform/terraform.mdx +++ b/website/docs/core-concepts/components/terraform/terraform.mdx @@ -7,15 +7,13 @@ id: terraform slug: /terraform --- import DocCardList from "@theme/DocCardList"; - -# Terraform Core Concepts Atmos can change how you think about the Terraform modules that you use to build your infrastructure. -When you design a cloud architectures with Atmos, you will first break it apart into pieces called components. +When you design cloud architectures with Atmos, you will first break it apart into pieces called components. Then, you will define the terraform "root modules" for each of your components. To make them highly reusable, they should serve a "single purpose" so that they are the smallest possible -unit of infrastructure managed in the software development lifecycle. +unit of infrastructure managed in the software development lifecycle (SDLC). Finally, you will connect your components together with stacks, so that everything comes together. In this tutorial, we’ll guide you through the thought process of building Terraform "root modules" that are suitable for use as components. diff --git a/website/docs/introduction/index.mdx b/website/docs/introduction/index.mdx index ac6d6b907..42d878695 100644 --- a/website/docs/introduction/index.mdx +++ b/website/docs/introduction/index.mdx @@ -5,15 +5,16 @@ label: Introduction sidebar_label: Introduction sidebar_position: 1 keywords: [atmos, terraform, helmfile, introduction] -title: Automated Terraform Management & Orchestration Software (ATMOS) +title: Getting Started with Atmos description: >- - Atmos is the Ultimate Terraform Environment Configuration and Orchestration Tool for DevOps to manage complex configurations with ease. + Atmos is a Component Oriented Framework and Orchestration Tool for DevOps that makes it easy to automate Terraform Environments and manage complex configurations with ease. It's compatible with Terraform and many other tools. --- import ReactPlayer from 'react-player' import Link from '@docusaurus/Link' +## Component Oriented Framework for Automated Terraform Management & Orchestration Software (ATMOS) Use Atmos to easily compose complex architectures based on Terraform with very [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) configuration. Concepts like [Stacks](/core-concepts/stacks) and [Components](/core-concepts/components) diff --git a/website/docs/reference/reference.mdx b/website/docs/reference/reference.mdx index 67d96c013..d5555f54a 100644 --- a/website/docs/reference/reference.mdx +++ b/website/docs/reference/reference.mdx @@ -2,6 +2,7 @@ title: Reference sidebar_position: 8 sidebar_label: Reference +sidebar_class_name: hidden description: Reference id: reference --- diff --git a/website/sidebars.js b/website/sidebars.js index 696986e87..8c052901e 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -175,7 +175,7 @@ module.exports = { }, { type: 'category', - label: 'Reference', + label: 'Resources', className: 'sidebar-title', collapsible: false, collapsed: false, diff --git a/website/src/pages/index.js b/website/src/pages/index.js index 79d2097da..0a7f7e8b5 100644 --- a/website/src/pages/index.js +++ b/website/src/pages/index.js @@ -21,7 +21,7 @@ function Home() {

Try the Quick Start

Learn More

-

Use a component oriented framework for Terraform backed by YAML

+

Use a Modern Component Oriented Framework for Terraform backed by YAML

Simplify complex architectures with DRY configuration

From 58ab1c99c7160a4df5a447dde4748ab1e74e512b Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Sat, 1 Jun 2024 19:38:23 -0500 Subject: [PATCH 004/151] Refactor content for vendoring --- .../core-concepts/components/components.mdx | 23 +- .../components/terraform/brownfield.mdx | 225 ++++++++++ .../components/terraform/journey.mdx | 2 +- .../terraform/remote-state-backend.mdx | 220 ---------- .../core-concepts/describing/describing.mdx | 3 +- .../component-oriented-configuration.mdx} | 8 +- .../stacks/define-components.mdx | 4 +- ...components.mdx => components-manifest.mdx} | 49 +-- .../vendoring/vendor-manifest.mdx | 399 ++++++++++++++++++ .../core-concepts/vendoring/vendoring.mdx | 375 +--------------- .../core-concepts/workflows/workflows.mdx | 18 +- website/docs/quick-start/install-atmos.mdx | 2 + website/sidebars.js | 2 +- 13 files changed, 682 insertions(+), 648 deletions(-) create mode 100644 website/docs/core-concepts/components/terraform/brownfield.mdx rename website/docs/core-concepts/{components/component-oriented-programming.md => stacks/component-oriented-configuration.mdx} (87%) rename website/docs/core-concepts/vendoring/{components.mdx => components-manifest.mdx} (73%) create mode 100644 website/docs/core-concepts/vendoring/vendor-manifest.mdx diff --git a/website/docs/core-concepts/components/components.mdx b/website/docs/core-concepts/components/components.mdx index 7f78d7975..8248642a3 100644 --- a/website/docs/core-concepts/components/components.mdx +++ b/website/docs/core-concepts/components/components.mdx @@ -8,8 +8,8 @@ description: Components are opinionated building blocks of infrastructure as cod Components are opinionated, self-contained building blocks of Infrastructure-as-Code (IAC) that solve one specific problem or use-case. Those Components are then configured inside of one or more [Stacks](/core-concepts/stacks). -Atmos was designed to be tool-agnostic, but also supports several native integrations with tools like [`terraform`](/cli/commands/terraform/usage) and [`helmfile`](/cli/commands/helmfile/usage). -A common use-case for Atmos is implementing components for [Terraform "root modules"](https://developer.hashicorp.com/terraform/language/modules#the-root-module). +The most common use-case for Atmos is using [Terraform "root modules"](https://developer.hashicorp.com/terraform/language/modules#the-root-module) as components in stacks. +But Atmos was designed to be tool-agnostic, and [custom commands](/core-concepts/custom-commands) can be made to work with Atmos. :::tip Components are things like [Terraform "root" modules](https://developer.hashicorp.com/terraform/language/modules#the-root-module), Helm Charts, Dockerfiles, or any fundamental building block of infrastructure. @@ -52,25 +52,6 @@ scalable, and reliable systems, ensuring a smooth and effective infrastructure m - **Maintain Loose Coupling Between Components.**
Avoid directly invoking one component from within another to ensure components remain loosely coupled. Specifically for Terraform components (root modules), this practice is unsupported due to the inability to define a backend in a child module, potentially leading to unexpected outcomes. It's crucial to steer clear of this approach to maintain system integrity. - **Reserve Code Generation for Emergencies.**
We generally advise against using code generation for application logic (components), because it's challenging to ensure good test coverage (e.g. with `terratest`) and no one likes to code review machine-generated boilerplate in Pull Requests. -## Component Schema - -To configure a Component in a [Stack](/core-concepts/stacks), A Component consists of the infrastructure as code business logic (e.g. a Terraform "root" module) as well as the configuration of that -component. The configuration of a component is stored in a Stack configuration. - -
- -:::info Disambiguation - -- **Terraform Component** is a simply a [Terraform Root Module](https://developer.hashicorp.com/terraform/language/modules#the-root-module) - that consists of the resources defined in the `.tf` files in a working directory - (e.g. [components/terraform/infra/vpc](https://github.com/cloudposse/atmos/tree/master/examples/tests/components/terraform/infra/vpc)) - -- **Component Configuration** provides configuration (variables and other settings) for a type of component (e.g. a Terraform component) - and is defined in one or more YAML stack config files (which are called [Atmos stacks](/core-concepts/stacks)) -::: - -
- ## Flavors of Components diff --git a/website/docs/core-concepts/components/terraform/brownfield.mdx b/website/docs/core-concepts/components/terraform/brownfield.mdx new file mode 100644 index 000000000..034c80aef --- /dev/null +++ b/website/docs/core-concepts/components/terraform/brownfield.mdx @@ -0,0 +1,225 @@ +--- +title: Brownfield Considerations +sidebar_position: 3 +sidebar_label: Brownfield Considerations +id: brownfield +--- + +The term "brownfield" comes from urban planning and refers to the redevelopment of land that was previously used and may need cleaning or modification. As it relates to infrastructure, [Brownfield development](https://en.wikipedia.org/wiki/Brownfield_(software_development)) describes development and deployment of new software +systems in the presence of existing (legacy) software applications/systems. Anytime this happens, new software architectures must take into account and coexist with the existing software. + +In the context of Atmos, brownfield development involves adopting some new techniques, practices, and integrating them into +established systems. This can be challenging due to several factors: + +- **Legacy Systems**: These are older systems that are still in use and may be harder to change. They might not even be managed with Terraform, or if they are, they might not provide outputs that are easily accessible in a conventional manner. + +- **Complex Integrations**: Existing systems might leverage entirely different toolchains, such as CloudFormation, CDK, or Pulumi. Managing integrations and dependencies across toolchains is complicated. + +- **Technical Debt**: Over time, systems naturally accumulate technical debt, which includes outdated code, inconsistent conventions or lack of naming conventions, and suboptimal decisions that were previously made for expediency. Addressing this technical debt is crucial when adopting Atmos, as it introduces practices that ensure your system remains maintainable and scalable. + + +## Brownfield Development in Atmos + +Atmos is easier for new organizations or "greenfield" environments because you need to architect Terraform according to +our best practices to get all the benefits of Atmos. For example, when using +our [Terraform components](https://github.com/cloudposse/terraform-aws-components), we frequently use +[Terraform Remote State](/core-concepts/components/terraform/remote-state) to retrieve the outputs from other components. +This works well when you use our components but less so when you operate in a "brownfield" environment, for example, +with an existing VPC, S3 bucket, or IAM role. + +But what happens if those things weren't provisioned by Atmos or predates your infrastructure? For this reason, we +support something we refer to as the `static` remote state backend. Using the static remote state backend, you can +populate a virtual state backend with the outputs as though it had been provisioned with Terraform. You can use this +technique anytime you want to use the remote state functionality in Atmos, but when the remote state was provisioned +elsewhere. + +In Atmos, brownfield development describes the process of configuring Atmos components and stacks for the +existing (already provisioned) resources, and working on and updating existing infrastructure rather than creating a new +one from scratch (which is known as "greenfield" development). The process respects the existing systems' constraints +while progressively introducing improvements and modern practices. This can ultimately lead to more robust, flexible, +and efficient systems. + + +## Hacking Remote State with `static` Backends + + +Atmos supports brownfield configuration by using the remote state of type `static`. + +Suppose that we need to provision +the [`vpc`](https://github.com/cloudposse/atmos/tree/master/examples/quick-start/components/terraform/vpc) +Terraform component and, instead of provisioning an S3 bucket for VPC Flow Logs, we want to use an existing bucket. + +The `vpc` Terraform component needs the outputs from the `vpc-flow-logs-bucket` Terraform component to +configure [VPC Flow Logs](https://docs.aws.amazon.com/vpc/latest/userguide/flow-logs.html). + +Let's redesign the example with the `vpc` and `vpc-flow-logs-bucket` components described in +[Terraform Component Remote State](/core-concepts/components/terraform/remote-state) and configure the `static` remote state for +the `vpc-flow-logs-bucket` component to use an existing S3 bucket. + +### Configure the `vpc-flow-logs-bucket` Component + +In the `stacks/catalog/vpc-flow-logs-bucket.yaml` file, add the following configuration for +the `vpc-flow-logs-bucket/defaults` Atmos component: + +```yaml title="stacks/catalog/vpc-flow-logs-bucket.yaml" +components: + terraform: + vpc-flow-logs-bucket/defaults: + metadata: + type: abstract + # Use `static` remote state to configure the attributes for an existing + # S3 bucket for VPC Flow Logs + remote_state_backend_type: static + remote_state_backend: + static: + # ARN of the existing S3 bucket + # `vpc_flow_logs_bucket_arn` is used as an input for the `vpc` component + vpc_flow_logs_bucket_arn: "arn:aws:s3::/my-vpc-flow-logs-bucket" +``` + +
+ +In the `stacks/ue2-dev.yaml` stack config file, add the following config for the `vpc-flow-logs-bucket-1` Atmos +component in the `ue2-dev` Atmos stack: + +```yaml title="stacks/ue2-dev.yaml" +# Import the base Atmos component configuration from the `catalog`. +# `import` supports POSIX-style Globs for file names/paths (double-star `**` is supported). +# File extensions are optional (if not specified, `.yaml` is used by default). +import: + - catalog/vpc-flow-logs-bucket + +components: + terraform: + vpc-flow-logs-bucket-1: + metadata: + # Point to the Terraform component in `components/terraform` folder + component: infra/vpc-flow-logs-bucket + inherits: + # Inherit all settings and variables from the + # `vpc-flow-logs-bucket/defaults` base Atmos component + - vpc-flow-logs-bucket/defaults +``` + +
+ +### Configure and Provision the `vpc` Component + +In the `components/terraform/infra/vpc/remote-state.tf` file, configure the +[remote-state](https://github.com/cloudposse/terraform-yaml-stack-config/tree/main/modules/remote-state) Terraform +module to obtain the remote state for the `vpc-flow-logs-bucket-1` Atmos component: + +```hcl title="components/terraform/infra/vpc/remote-state.tf" +module "vpc_flow_logs_bucket" { + count = local.vpc_flow_logs_enabled ? 1 : 0 + + source = "cloudposse/stack-config/yaml//modules/remote-state" + version = "1.5.0" + + # Specify the Atmos component name (defined in YAML stack config files) + # for which to get the remote state outputs + component = var.vpc_flow_logs_bucket_component_name + + # `context` input is a way to provide the information about the stack (using the context + # variables `namespace`, `tenant`, `environment`, `stage` defined in the stack config) + context = module.this.context +} +``` + +In the `components/terraform/infra/vpc/vpc-flow-logs.tf` file, configure the `aws_flow_log` resource for the `vpc` +Terraform component to use the remote state output `vpc_flow_logs_bucket_arn` from the `vpc-flow-logs-bucket-1` Atmos +component: + +```hcl title="components/terraform/infra/vpc/vpc-flow-logs.tf" +locals { + enabled = module.this.enabled + vpc_flow_logs_enabled = local.enabled && var.vpc_flow_logs_enabled +} + +resource "aws_flow_log" "default" { + count = local.vpc_flow_logs_enabled ? 1 : 0 + + # Use the remote state output `vpc_flow_logs_bucket_arn` of the `vpc_flow_logs_bucket` component + log_destination = module.vpc_flow_logs_bucket[0].outputs.vpc_flow_logs_bucket_arn + + log_destination_type = var.vpc_flow_logs_log_destination_type + traffic_type = var.vpc_flow_logs_traffic_type + vpc_id = module.vpc.vpc_id + + tags = module.this.tags +} +``` + +In the `stacks/catalog/vpc.yaml` file, add the following default config for the `vpc/defaults` Atmos component: + +```yaml title="stacks/catalog/vpc.yaml" +components: + terraform: + vpc/defaults: + metadata: + # `metadata.type: abstract` makes the component `abstract`, + # explicitly prohibiting the component from being deployed. + # `atmos terraform apply` will fail with an error. + # If `metadata.type` attribute is not specified, it defaults to `real`. + # `real` components can be provisioned by `atmos` and CI/CD like Spacelift and Atlantis. + type: abstract + # Default variables, which will be inherited and can be overridden in the derived components + vars: + public_subnets_enabled: false + nat_gateway_enabled: false + nat_instance_enabled: false + max_subnet_count: 3 + vpc_flow_logs_enabled: false + vpc_flow_logs_log_destination_type: s3 + vpc_flow_logs_traffic_type: "ALL" +``` + +
+ +In the `stacks/ue2-dev.yaml` stack config file, add the following config for the `vpc/1` Atmos component in +the `ue2-dev` stack: + +```yaml title="stacks/ue2-dev.yaml" +# Import the base component configuration from the `catalog`. +# `import` supports POSIX-style Globs for file names/paths (double-star `**` is supported). +# File extensions are optional (if not specified, `.yaml` is used by default). +import: + - catalog/vpc + +components: + terraform: + vpc/1: + metadata: + # Point to the Terraform component in `components/terraform` folder + component: infra/vpc + inherits: + # Inherit all settings and variables from the `vpc/defaults` base Atmos component + - vpc/defaults + vars: + # Define variables that are specific for this component + # and are not set in the base component + name: vpc-1 + ipv4_primary_cidr_block: 10.8.0.0/18 + # Override the default variables from the base component + vpc_flow_logs_enabled: true + vpc_flow_logs_traffic_type: "REJECT" + + # Specify the name of the Atmos component that provides configuration + # for the `infra/vpc-flow-logs-bucket` Terraform component + vpc_flow_logs_bucket_component_name: vpc-flow-logs-bucket-1 +``` + +
+ +Having the stacks configured as shown above, we can now provision the `vpc/1` Atmos component in the `ue2-dev` stack +by executing the following Atmos commands: + +```shell +atmos terraform plan vpc/1 -s ue2-dev +atmos terraform apply vpc/1 -s ue2-dev +``` + +When the commands are executed, the `vpc_flow_logs_bucket` remote-state module detects that the `vpc-flow-logs-bucket-1` +component has the `static` remote state configured, and instead of reading its remote state from the S3 state +bucket, it just returns the static values from the `remote_state_backend.static` section. +The `vpc_flow_logs_bucket_arn` is then used as an input for the `vpc` component. diff --git a/website/docs/core-concepts/components/terraform/journey.mdx b/website/docs/core-concepts/components/terraform/journey.mdx index ce558ae61..ae5b6c247 100644 --- a/website/docs/core-concepts/components/terraform/journey.mdx +++ b/website/docs/core-concepts/components/terraform/journey.mdx @@ -2,7 +2,7 @@ title: The Typical Terraform Journey description: Learn about the typical Terraform journey when not using Atmos. sidebar_label: Maturity Path -sidebar_position: 6 +sidebar_position: 2 id: journey --- diff --git a/website/docs/core-concepts/components/terraform/remote-state-backend.mdx b/website/docs/core-concepts/components/terraform/remote-state-backend.mdx index 6dc76a554..02b4bb924 100644 --- a/website/docs/core-concepts/components/terraform/remote-state-backend.mdx +++ b/website/docs/core-concepts/components/terraform/remote-state-backend.mdx @@ -86,223 +86,3 @@ deep-merges the `remote_state_backend` section with the `backend` section). When working with Terraform backends and writing/updating the state, the `terraform-backend-read-write` role will be used. But when reading the remote state of components, the `terraform-backend-read-only` role will be used. - -## Brownfield Considerations - -The term "brownfield" comes from urban planning and refers to the redevelopment of land that was previously used and may need cleaning or modification. As it relates to infrastructure, [Brownfield development](https://en.wikipedia.org/wiki/Brownfield_(software_development)) describes development and deployment of new software -systems in the presence of existing (legacy) software applications/systems. Anytime this happens, new software architectures must take into account and coexist with the existing software. - -In the context of Atmos, brownfield development involves adopting some new techniques, practices, and integrating them into -established systems. This can be challenging due to several factors: - -- **Legacy Systems**: These are older systems that are still in use and may be harder to change. They might not even be managed with Terraform, or if they are, they might not provide outputs that are easily accessible in a conventional manner. - -- **Complex Integrations**: Existing systems might leverage entirely different toolchains, such as CloudFormation, CDK, or Pulumi. Managing integrations and dependencies across toolchains is complicated. - - -- **Technical Debt**: Over time, systems naturally accumulate technical debt, which includes outdated code, inconsistent conventions or lack of naming conventions, and suboptimal decisions that were previously made for expediency. Addressing this technical debt is crucial when adopting Atmos, as it introduces practices that ensure your system remains maintainable and scalable. - - -## Brownfield Development in Atmos - -Atmos is easier for new organizations or "greenfield" environments because you need to architect Terraform according to -our best practices to get all the benefits of Atmos. For example, when using -our [Terraform components](https://github.com/cloudposse/terraform-aws-components), we frequently use -[Terraform Remote State](/core-concepts/components/terraform/remote-state) to retrieve the outputs from other components. -This works well when you use our components but less so when you operate in a "brownfield" environment, for example, -with an existing VPC, S3 bucket, or IAM role. - -But what happens if those things weren't provisioned by Atmos or predates your infrastructure? For this reason, we -support something we refer to as the `static` remote state backend. Using the static remote state backend, you can -populate a virtual state backend with the outputs as though it had been provisioned with Terraform. You can use this -technique anytime you want to use the remote state functionality in Atmos, but when the remote state was provisioned -elsewhere. - -In Atmos, brownfield development describes the process of configuring Atmos components and stacks for the -existing (already provisioned) resources, and working on and updating existing infrastructure rather than creating a new -one from scratch (which is known as "greenfield" development). The process respects the existing systems' constraints -while progressively introducing improvements and modern practices. This can ultimately lead to more robust, flexible, -and efficient systems. - -Atmos supports brownfield configuration by using the remote state of type `static`. - -## `static` Remote State for Brownfield Development - -Suppose that we need to provision -the [`vpc`](https://github.com/cloudposse/atmos/tree/master/examples/quick-start/components/terraform/vpc) -Terraform component and, instead of provisioning an S3 bucket for VPC Flow Logs, we want to use an existing bucket. - -The `vpc` Terraform component needs the outputs from the `vpc-flow-logs-bucket` Terraform component to -configure [VPC Flow Logs](https://docs.aws.amazon.com/vpc/latest/userguide/flow-logs.html). - -Let's redesign the example with the `vpc` and `vpc-flow-logs-bucket` components described in -[Terraform Component Remote State](/core-concepts/components/terraform/remote-state) and configure the `static` remote state for -the `vpc-flow-logs-bucket` component to use an existing S3 bucket. - -### Configure the `vpc-flow-logs-bucket` Component - -In the `stacks/catalog/vpc-flow-logs-bucket.yaml` file, add the following configuration for -the `vpc-flow-logs-bucket/defaults` Atmos component: - -```yaml title="stacks/catalog/vpc-flow-logs-bucket.yaml" -components: - terraform: - vpc-flow-logs-bucket/defaults: - metadata: - type: abstract - # Use `static` remote state to configure the attributes for an existing - # S3 bucket for VPC Flow Logs - remote_state_backend_type: static - remote_state_backend: - static: - # ARN of the existing S3 bucket - # `vpc_flow_logs_bucket_arn` is used as an input for the `vpc` component - vpc_flow_logs_bucket_arn: "arn:aws:s3::/my-vpc-flow-logs-bucket" -``` - -
- -In the `stacks/ue2-dev.yaml` stack config file, add the following config for the `vpc-flow-logs-bucket-1` Atmos -component in the `ue2-dev` Atmos stack: - -```yaml title="stacks/ue2-dev.yaml" -# Import the base Atmos component configuration from the `catalog`. -# `import` supports POSIX-style Globs for file names/paths (double-star `**` is supported). -# File extensions are optional (if not specified, `.yaml` is used by default). -import: - - catalog/vpc-flow-logs-bucket - -components: - terraform: - vpc-flow-logs-bucket-1: - metadata: - # Point to the Terraform component in `components/terraform` folder - component: infra/vpc-flow-logs-bucket - inherits: - # Inherit all settings and variables from the - # `vpc-flow-logs-bucket/defaults` base Atmos component - - vpc-flow-logs-bucket/defaults -``` - -
- -### Configure and Provision the `vpc` Component - -In the `components/terraform/infra/vpc/remote-state.tf` file, configure the -[remote-state](https://github.com/cloudposse/terraform-yaml-stack-config/tree/main/modules/remote-state) Terraform -module to obtain the remote state for the `vpc-flow-logs-bucket-1` Atmos component: - -```hcl title="components/terraform/infra/vpc/remote-state.tf" -module "vpc_flow_logs_bucket" { - count = local.vpc_flow_logs_enabled ? 1 : 0 - - source = "cloudposse/stack-config/yaml//modules/remote-state" - version = "1.5.0" - - # Specify the Atmos component name (defined in YAML stack config files) - # for which to get the remote state outputs - component = var.vpc_flow_logs_bucket_component_name - - # `context` input is a way to provide the information about the stack (using the context - # variables `namespace`, `tenant`, `environment`, `stage` defined in the stack config) - context = module.this.context -} -``` - -In the `components/terraform/infra/vpc/vpc-flow-logs.tf` file, configure the `aws_flow_log` resource for the `vpc` -Terraform component to use the remote state output `vpc_flow_logs_bucket_arn` from the `vpc-flow-logs-bucket-1` Atmos -component: - -```hcl title="components/terraform/infra/vpc/vpc-flow-logs.tf" -locals { - enabled = module.this.enabled - vpc_flow_logs_enabled = local.enabled && var.vpc_flow_logs_enabled -} - -resource "aws_flow_log" "default" { - count = local.vpc_flow_logs_enabled ? 1 : 0 - - # Use the remote state output `vpc_flow_logs_bucket_arn` of the `vpc_flow_logs_bucket` component - log_destination = module.vpc_flow_logs_bucket[0].outputs.vpc_flow_logs_bucket_arn - - log_destination_type = var.vpc_flow_logs_log_destination_type - traffic_type = var.vpc_flow_logs_traffic_type - vpc_id = module.vpc.vpc_id - - tags = module.this.tags -} -``` - -In the `stacks/catalog/vpc.yaml` file, add the following default config for the `vpc/defaults` Atmos component: - -```yaml title="stacks/catalog/vpc.yaml" -components: - terraform: - vpc/defaults: - metadata: - # `metadata.type: abstract` makes the component `abstract`, - # explicitly prohibiting the component from being deployed. - # `atmos terraform apply` will fail with an error. - # If `metadata.type` attribute is not specified, it defaults to `real`. - # `real` components can be provisioned by `atmos` and CI/CD like Spacelift and Atlantis. - type: abstract - # Default variables, which will be inherited and can be overridden in the derived components - vars: - public_subnets_enabled: false - nat_gateway_enabled: false - nat_instance_enabled: false - max_subnet_count: 3 - vpc_flow_logs_enabled: false - vpc_flow_logs_log_destination_type: s3 - vpc_flow_logs_traffic_type: "ALL" -``` - -
- -In the `stacks/ue2-dev.yaml` stack config file, add the following config for the `vpc/1` Atmos component in -the `ue2-dev` stack: - -```yaml title="stacks/ue2-dev.yaml" -# Import the base component configuration from the `catalog`. -# `import` supports POSIX-style Globs for file names/paths (double-star `**` is supported). -# File extensions are optional (if not specified, `.yaml` is used by default). -import: - - catalog/vpc - -components: - terraform: - vpc/1: - metadata: - # Point to the Terraform component in `components/terraform` folder - component: infra/vpc - inherits: - # Inherit all settings and variables from the `vpc/defaults` base Atmos component - - vpc/defaults - vars: - # Define variables that are specific for this component - # and are not set in the base component - name: vpc-1 - ipv4_primary_cidr_block: 10.8.0.0/18 - # Override the default variables from the base component - vpc_flow_logs_enabled: true - vpc_flow_logs_traffic_type: "REJECT" - - # Specify the name of the Atmos component that provides configuration - # for the `infra/vpc-flow-logs-bucket` Terraform component - vpc_flow_logs_bucket_component_name: vpc-flow-logs-bucket-1 -``` - -
- -Having the stacks configured as shown above, we can now provision the `vpc/1` Atmos component in the `ue2-dev` stack -by executing the following Atmos commands: - -```shell -atmos terraform plan vpc/1 -s ue2-dev -atmos terraform apply vpc/1 -s ue2-dev -``` - -When the commands are executed, the `vpc_flow_logs_bucket` remote-state module detects that the `vpc-flow-logs-bucket-1` -component has the `static` remote state configured, and instead of reading its remote state from the S3 state -bucket, it just returns the static values from the `remote_state_backend.static` section. -The `vpc_flow_logs_bucket_arn` is then used as an input for the `vpc` component. diff --git a/website/docs/core-concepts/describing/describing.mdx b/website/docs/core-concepts/describing/describing.mdx index 8b0cfd245..2cc4bf173 100644 --- a/website/docs/core-concepts/describing/describing.mdx +++ b/website/docs/core-concepts/describing/describing.mdx @@ -13,6 +13,7 @@ Atmos is a framework for defining cloud architectures in YAML. Configurations are defined in Stacks, which define the settings for small units infrastructure called Components like VPCs, Clusters, and Databases. Atmos lets you combine components into reusable, nestable Stacks using Imports. Everything from simple web sites to full blown multi-account/multi-subscription cloud architectures can be broken down into components. -In this chapter, you’ll learn to create, customize, and conditionally display the configuration of Atmos components. + +In this chapter, you’ll learn to describe all aspects of the fully-deepmerged configurations of Atmos stacks. diff --git a/website/docs/core-concepts/components/component-oriented-programming.md b/website/docs/core-concepts/stacks/component-oriented-configuration.mdx similarity index 87% rename from website/docs/core-concepts/components/component-oriented-programming.md rename to website/docs/core-concepts/stacks/component-oriented-configuration.mdx index efe16d008..4283e8a08 100644 --- a/website/docs/core-concepts/components/component-oriented-programming.md +++ b/website/docs/core-concepts/stacks/component-oriented-configuration.mdx @@ -1,11 +1,11 @@ --- -title: Component-Oriented Programming +title: Component-Oriented Configuration sidebar_position: 6 -sidebar_label: Component-Oriented Programming -id: component-oriented-programming +sidebar_label: Component-Oriented Configuration +id: component-oriented-configuration --- -[Component-Oriented Programming](https://en.wikipedia.org/wiki/Component-based_software_engineering) is a reuse-based approach to defining, +[Component-Oriented Configuration](https://en.wikipedia.org/wiki/Component-based_software_engineering) is a reuse-based approach to defining, implementing and composing loosely-coupled independent components into systems. Atmos supports the following concepts and principles of **Component-Oriented Programming (COP)**: diff --git a/website/docs/core-concepts/stacks/define-components.mdx b/website/docs/core-concepts/stacks/define-components.mdx index ec152fdf1..f64653701 100644 --- a/website/docs/core-concepts/stacks/define-components.mdx +++ b/website/docs/core-concepts/stacks/define-components.mdx @@ -7,9 +7,11 @@ id: define-components ## Component Schema -To configure a Component in a [Stack](/core-concepts/stacks), A Component consists of the infrastructure as code business logic (e.g. a Terraform "root" module) as well as the configuration of that +A Component consists of the infrastructure as code business logic (e.g. a Terraform "root" module) as well as the configuration of that component. The configuration of a component is stored in a Stack configuration. +To configure a Component in a [Stack](/core-concepts/stacks), you define the component in the `components` section of the Stack configuration. +
:::info Disambiguation diff --git a/website/docs/core-concepts/vendoring/components.mdx b/website/docs/core-concepts/vendoring/components-manifest.mdx similarity index 73% rename from website/docs/core-concepts/vendoring/components.mdx rename to website/docs/core-concepts/vendoring/components-manifest.mdx index 1b4d3a6e2..f4ace0606 100644 --- a/website/docs/core-concepts/vendoring/components.mdx +++ b/website/docs/core-concepts/vendoring/components-manifest.mdx @@ -1,45 +1,16 @@ --- -title: Component Vendoring -sidebar_position: 3 -sidebar_label: Components -description: Use Component Vendoring to make copies of 3rd-party components in your own repo. -id: components +title: Component Manifest +sidebar_position: 2 +sidebar_label: Component Manifest +description: Use Component manifests to make copies of 3rd-party components in your own repo. +id: component-manifest --- +import File from '@site/src/components/File' +import Terminal from '@site/src/components/Terminal' -Atmos natively supports the concept of "vendoring", which is making a copy of 3rd-party components or other dependencies in your own repo. -Our implementation is primarily inspired by the excellent tool by VMware Tanzu, called [`vendir`](https://github.com/vmware-tanzu/carvel-vendir). -While Atmos does not call `vendir`, it functions and supports a subset of the configuration that is very similar. +Atmos natively supports the concept of "vendoring" individual components by defining a `component.yaml` inside of the component directory. +, which is making a copy of 3rd-party components or other dependencies in your own repo. -## Use-cases - -Atmos vendoring streamlines component sharing and version control across an enterprise, enhancing efficiency and collaboration while offering the flexibility to customize and manage multiple versions of dependencies, ensuring best practices in DevOps environments. - -- **Sharing Components Across an Enterprise**: Utilize Atmos vendoring to access a centralized component library, promoting code reuse and - efficiency across teams (or business units) while enabling customization and independent version control post-vendoring. This approach enhances collaboration without sacrificing the flexibility for teams to tailor components to their specific needs or update them at their preferred pace. -- **Managing Multiple Versions of Dependencies:** Use Atmos vendoring to manage multiple versions of remote dependencies, - effectively implementing version pinning through locally controlled artifacts. By configuring a stacks component directory (e.g., `vpc/v1` or `vpc/v2`), vendoring provides maximum flexibility while still aligning with best practices in DevOps environments. -- **Reinforce Immutable Infrastructure**: Employ Atmos vendoring to store immutable infrastructure artifacts, guaranteeing that once a committed, - it remains unaltered throughout its lifecycle, ensuring stability and reliability in deployments. - -## Usage - -Atmos supports two different ways of vendoring components: - -- Using `vendor.yaml` vendoring manifest file containing a list of all dependencies. See [Vendoring](/core-concepts/vendoring/). -- Using `component.yaml` manifest file inside of a component directory. See below. - -The `vendor.yaml` vendoring manifest describes the vendoring config for all components, stacks and other artifacts for the entire infrastructure. -The file is placed into the directory from which the `atmos vendor pull` command is executed. It's the recommended way to describe vendoring -configurations. - -:::tip -Refer to [`Atmos Vendoring`](/core-concepts/vendoring) for more details -::: - -
- -The `component.yaml` vendoring manifest is used to vendor components from remote repositories. -A `component.yaml` file placed into a component's directory is used to describe the vendoring config for one component only. ## Examples @@ -47,7 +18,7 @@ A `component.yaml` file placed into a component's directory is used to describe After defining the `component.yaml` vendoring manifest, the remote component can be downloaded by running the following command: -```bash +```shell atmos vendor pull -c components/terraform/vpc ``` diff --git a/website/docs/core-concepts/vendoring/vendor-manifest.mdx b/website/docs/core-concepts/vendoring/vendor-manifest.mdx new file mode 100644 index 000000000..91595ca6c --- /dev/null +++ b/website/docs/core-concepts/vendoring/vendor-manifest.mdx @@ -0,0 +1,399 @@ +--- +title: Vendor Manifest +description: Use Atmos vendoring to make copies of 3rd-party components, stacks, and other artifacts in your own repo. +sidebar_position: 1 +sidebar_label: Vendor Manifest +id: vendor-manifest +--- +import File from '@site/src/components/File' +import Terminal from '@site/src/components/Terminal' + +The vendoring configuration is defined in the `vendor.yaml` manifest (vendor config file). +The vendoring manifest is used to make copies of 3rd-party components, stacks, and other artifacts in your own repository. +It functions a little bit like the `packages.json` file in Node.js or the `go.mod` file in Go, but for infrastructure code. + +## How it works + +Atmos searches for the vendoring manifest in the following locations, and uses the first one found: + +- In the directory from which the [`atmos vendor pull`](/cli/commands/vendor/pull) command is executed, usually in the root of the infrastructure repo + +- In the directory pointed to by the [`base_path`](/cli/configuration#base-path) setting in the [`atmos.yaml`](/cli/configuration) CLI config file + +After defining the `vendor.yaml` manifest, all the remote artifacts can be downloaded by running the following command: + +```shell +atmos vendor pull +``` + +To vendor a particular component or other artifact, execute the following command: + +```shell +atmos vendor pull -c +``` + +To vendor components and artifacts tagged with specific tags, execute the following command: + +```shell +atmos vendor pull --tags , +``` + +
+ +:::tip +Refer to [`atmos vendor pull`](/cli/commands/vendor/pull) CLI command for more details +::: + +## Vendoring Manifest + +To vendor remote artifacts, create a `vendor.yaml` file similar to the example below: + + +```yaml +apiVersion: atmos/v1 +kind: AtmosVendorConfig +metadata: + name: example-vendor-config + description: Atmos vendoring manifest +spec: + # `imports` or `sources` (or both) must be defined in a vendoring manifest + imports: + - "vendor/vendor2" + - "vendor/vendor3.yaml" + + sources: + # `source` supports the following protocols: local paths (absolute and relative), OCI (https://opencontainers.org), + # Git, Mercurial, HTTP, HTTPS, Amazon S3, Google GCP, + # and all URL and archive formats as described in https://github.com/hashicorp/go-getter. + # In 'source', Golang templates are supported https://pkg.go.dev/text/template. + # If 'version' is provided, '{{.Version}}' will be replaced with the 'version' value before pulling the files from 'source'. + # Download the component from the AWS public ECR registry (https://docs.aws.amazon.com/AmazonECR/latest/public/public-registries.html). + - component: "vpc" + source: "oci://public.ecr.aws/cloudposse/components/terraform/stable/aws/vpc:{{.Version}}" + version: "latest" + targets: + - "components/terraform/infra/vpc3" + # Only include the files that match the 'included_paths' patterns. + # If 'included_paths' is not specified, all files will be matched except those that match the patterns from 'excluded_paths'. + # 'included_paths' support POSIX-style Globs for file names/paths (double-star `**` is supported). + # https://en.wikipedia.org/wiki/Glob_(programming) + # https://github.com/bmatcuk/doublestar#patterns + included_paths: + - "**/*.tf" + - "**/*.tfvars" + - "**/*.md" + # Tags can be used to vendor component that have the specific tags + # `atmos vendor pull --tags test` + # Refer to https://atmos.tools/cli/commands/vendor/pull + tags: + - test + - networking + - component: "vpc-flow-logs-bucket" + source: "github.com/cloudposse/terraform-aws-components.git//modules/vpc-flow-logs-bucket?ref={{.Version}}" + version: "1.323.0" + targets: + - "components/terraform/infra/vpc-flow-logs-bucket/{{.Version}}" + excluded_paths: + - "**/*.yaml" + - "**/*.yml" + # Tags can be used to vendor component that have the specific tags + # `atmos vendor pull --tags networking,storage` + # Refer to https://atmos.tools/cli/commands/vendor/pull + tags: + - test + - storage + - component: "vpc-mixin-1" + source: "https://raw.githubusercontent.com/cloudposse/terraform-null-label/0.25.0/exports/context.tf" + targets: + - "components/terraform/infra/vpc3" + # Tags can be used to vendor component that have the specific tags + # `atmos vendor pull --tags test` + # Refer to https://atmos.tools/cli/commands/vendor/pull + tags: + - test + - component: "vpc-mixin-2" + # Copy a local file into a local folder (keeping the same file name) + # This `source` is relative to the current folder + source: "components/terraform/mixins/context.tf" + targets: + - "components/terraform/infra/vpc3" + # Tags can be used to vendor component that have the specific tags + # `atmos vendor pull --tags test` + # Refer to https://atmos.tools/cli/commands/vendor/pull + tags: + - test + - component: "vpc-mixin-3" + # Copy a local folder into a local folder + # This `source` is relative to the current folder + source: "components/terraform/mixins" + targets: + - "components/terraform/infra/vpc3" + # Tags can be used to vendor component that have the specific tags + # `atmos vendor pull --tags test` + # Refer to https://atmos.tools/cli/commands/vendor/pull + tags: + - test + - component: "vpc-mixin-4" + # Copy a local file into a local file with a different file name + # This `source` is relative to the current folder + source: "components/terraform/mixins/context.tf" + targets: + - "components/terraform/infra/vpc3/context-copy.tf" + # Tags can be used to vendor component that have the specific tags + # `atmos vendor pull --tags test` + # Refer to https://atmos.tools/cli/commands/vendor/pull + tags: + - test +``` + + +With this configuration, it would be possible to run the following commands: + +```shell +# atmos vendor pull +# atmos vendor pull --component vpc-mixin-1 +# atmos vendor pull -c vpc-mixin-2 +# atmos vendor pull -c vpc-mixin-3 +# atmos vendor pull -c vpc-mixin-4 +# atmos vendor pull --tags test +# atmos vendor pull --tags networking,storage +``` + + +
+ +- The `vendor.yaml` vendoring manifest supports Kubernetes-style YAML config to describe vendoring configuration for components, stacks, + and other artifacts. The file is placed into the directory from which the `atmos vendor pull` command is executed (usually the root of the repo). + +- The `source` attribute supports all protocols (local files, Git, Mercurial, HTTP, HTTPS, Amazon S3, Google GCP), and all the URL and + archive formats as described in [go-getter](https://github.com/hashicorp/go-getter), and also the `oci://` scheme to download artifacts from + [OCI registries](https://opencontainers.org). + + **IMPORTANT:** Include the `{{ .Version }}` parameter in your `source` URI to ensure the correct version of the artifact is downloaded. + For example: + + ```yaml + source: "github.com/cloudposse/terraform-aws-components.git//modules/vpc-flow-logs-bucket?ref={{.Version}}" + ``` + +- The `targets` in each source supports absolute paths and relative paths (relative to the `vendor.yaml` file). Note: if the `targets` paths + are set as relative, and if the `vendor.yaml` file is detected by Atmos using the `base_path` setting in `atmos.yaml`, the `targets` paths + will be considered relative to the `base_path`. Multiple targets can be specified. + +- `included_paths` and `excluded_paths` support [POSIX-style greedy Globs](https://en.wikipedia.org/wiki/Glob_(programming)) for filenames/paths + (double-star/globstar `**` is supported as well). + +- The `component` attribute in each source is optional. It's used in the `atmos vendor pull -- component ` command if the component is + passed in. In this case, Atmos will vendor only the specified component instead of vendoring all the artifacts configured in the `vendor.yaml` + manifest. + +- The `source` and `targets` attributes support [Go templates](https://pkg.go.dev/text/template) + and [Sprig Functions](http://masterminds.github.io/sprig/). This can be used to templatise the `source` and `targets` paths with the artifact + versions specified in the `version` attribute. + + Here's an advanced example showcasing how templates and Sprig functions can be used together with `targets`: + + ```yaml + targets: + # Vendor a component into a major-minor versioned folder like 1.2 + - "components/terraform/infra/vpc-flow-logs-bucket/{{ (first 2 (splitList \".\" .Version)) | join \".\" }}" + ``` + +- The `tags` in each source specifies a list of tags to apply to the component. This allows you to only vendor the components that have the + specified tags by executing a command `atmos vendor pull --tags ,` + +- The `imports` section defines the additional vendoring manifests that are merged into the main manifest. Hierarchical imports are supported + at many levels (one vendoring manifest can import another, which in turn can import other manifests, etc.). Atmos processes all imports and all + sources in the imported manifests in the order they are defined. + + **NOTE:** The imported file extensions are optional. If an import is defined without an extension, the `.yaml` extension is assumed and used + by default. + +
+ +:::warning + +The `glob` library that Atmos uses to download remote artifacts does not treat the double-star `**` as including sub-folders. +If the component's folder has sub-folders, and you need to vendor them, they have to be explicitly defined as in the following example. + +::: + + +```yaml title="vendor.yaml" +spec: + sources: + - component: "vpc-flow-logs-bucket" + source: "github.com/cloudposse/terraform-aws-components.git//modules/vpc-flow-logs-bucket?ref={{.Version}}" + version: "1.323.0" + targets: + - "components/terraform/vpc-flow-logs-bucket" + included_paths: + - "**/**" + # If the component's folder has the `modules` sub-folder, it needs to be explicitly defined + - "**/modules/**" +``` + + +
+ +## Hierarchical Imports in Vendoring Manifests + +Use `imports` to split the main `vendor.yaml` manifest into smaller files for maintainability, or by their roles in the infrastructure. + +For example, import separate manifests for networking, security, data management, CI/CD, and other layers: + +```yaml +imports: + - "layers/networking" + - "layers/security" + - "layers/data" + - "layers/analytics" + - "layers/firewalls" + - "layers/cicd" +``` + +Hierarchical imports are supported at many levels. For example, consider the following vendoring configurations: + + +```yaml +apiVersion: atmos/v1 +kind: AtmosVendorConfig +metadata: + name: example-vendor-config + description: Atmos vendoring manifest +spec: + imports: + - "vendor/vendor2" + - "vendor/vendor3" + + sources: + - component: "vpc" + source: "oci://public.ecr.aws/cloudposse/components/terraform/stable/aws/vpc:{{.Version}}" + version: "latest" + targets: + - "components/terraform/infra/vpc3" + - component: "vpc-flow-logs-bucket" + source: "github.com/cloudposse/terraform-aws-components.git//modules/vpc-flow-logs-bucket?ref={{.Version}}" + version: "1.323.0" + targets: + - "components/terraform/infra/vpc-flow-logs-bucket/{{.Version}}" +``` + + + + +```yaml +apiVersion: atmos/v1 +kind: AtmosVendorConfig +metadata: + name: example-vendor-config-2 + description: Atmos vendoring manifest +spec: + imports: + - "vendor/vendor4" + + sources: + - component: "my-vpc1" + source: "oci://public.ecr.aws/cloudposse/components/terraform/stable/aws/vpc:{{.Version}}" + version: "1.0.2" + targets: + - "components/terraform/infra/my-vpc1" +``` + + + +```yaml +apiVersion: atmos/v1 +kind: AtmosVendorConfig +metadata: + name: example-vendor-config-4 + description: Atmos vendoring manifest +spec: + imports: + - "vendor/vendor5" + + sources: + - component: "my-vpc4" + source: "github.com/cloudposse/terraform-aws-components.git//modules/vpc?ref={{.Version}}" + version: "1.319.0" + targets: + - "components/terraform/infra/my-vpc4" +``` + + +When you execute the `atmos vendor pull` command, Atmos processes the import chain and the sources in the imported manifests in the order they +are defined: + +- First, the main `vendor.yaml` file is read based on search paths +- The `vendor/vendor2` and `vendor/vendor3` manifests (defined in the main `vendor.yaml` file) are imported +- The `vendor/vendor2` file is processed, and the `vendor/vendor4` manifest is imported +- The `vendor/vendor4` file is processed, and the `vendor/vendor5` manifest is imported +- Etc. +- Then all the sources from all the imported manifests are processed and the artifacts are downloaded into the paths defined by the `targets` + +
+ + +```shell +> atmos vendor pull + +Processing vendor config file 'vendor.yaml' +Pulling sources for the component 'my-vpc6' from 'github.com/cloudposse/terraform-aws-components.git//modules/vpc?ref=1.315.0' into 'components/terraform/infra/my-vpc6' +Pulling sources for the component 'my-vpc5' from 'github.com/cloudposse/terraform-aws-components.git//modules/vpc?ref=1.317.0' into 'components/terraform/infra/my-vpc5' +Pulling sources for the component 'my-vpc4' from 'github.com/cloudposse/terraform-aws-components.git//modules/vpc?ref=1.319.0' into 'components/terraform/infra/my-vpc4' +Pulling sources for the component 'my-vpc1' from 'public.ecr.aws/cloudposse/components/terraform/stable/aws/vpc:1.0.2' into 'components/terraform/infra/my-vpc1' +Pulling sources for the component 'my-vpc2' from 'github.com/cloudposse/terraform-aws-components.git//modules/vpc?ref=1.320.0' into 'components/terraform/infra/my-vpc2' +Pulling sources for the component 'vpc' from 'public.ecr.aws/cloudposse/components/terraform/stable/aws/vpc:latest' into 'components/terraform/infra/vpc3' +Pulling sources for the component 'vpc-flow-logs-bucket' from 'github.com/cloudposse/terraform-aws-components.git//modules/vpc-flow-logs-bucket?ref=1.323.0' into 'components/terraform/infra/vpc-flow-logs-bucket/1.323.0' +``` + + +## Vendoring from OCI Registries + +Atmos supports vendoring from [OCI registries](https://opencontainers.org). + +To specify a repository in an OCI registry, use the `oci:///:tag` scheme. + +Artifacts from OCI repositories are downloaded as Docker image tarballs, then all the layers are processed, un-tarred and un-compressed, +and the files are written into the directories specified by the `targets` attribute of each `source`. + +For example, to vendor the `vpc` component from the `public.ecr.aws/cloudposse/components/terraform/stable/aws/vpc` +[AWS public ECR registry](https://docs.aws.amazon.com/AmazonECR/latest/public/public-registries.html), use the following `source`: + +```yaml +source: "oci://public.ecr.aws/cloudposse/components/terraform/stable/aws/vpc:latest" +``` + +The schema of a `vendor.yaml` manifest is as follows: + + +```yaml +# This is an example of how to download a Terraform component from an OCI registry (https://opencontainers.org), e.g. AWS Public ECR + +apiVersion: atmos/v1 +kind: AtmosVendorConfig +metadata: + name: example-vendor-config + description: Atmos vendoring manifest +spec: + sources: + - component: "vpc" + source: "oci://public.ecr.aws/cloudposse/components/terraform/stable/aws/vpc:{{.Version}}" + version: "latest" + targets: + - "components/terraform/infra/vpc3" + included_paths: + - "**/*.tf" + - "**/*.tfvars" + - "**/*.md" + excluded_paths: [] +``` + + +To vendor the `vpc` component, execute the following command: + + +```bash +atmos vendor pull -c vpc +``` + diff --git a/website/docs/core-concepts/vendoring/vendoring.mdx b/website/docs/core-concepts/vendoring/vendoring.mdx index d897d6dcb..9a8fb2730 100644 --- a/website/docs/core-concepts/vendoring/vendoring.mdx +++ b/website/docs/core-concepts/vendoring/vendoring.mdx @@ -2,10 +2,11 @@ title: Vendoring description: Use Atmos vendoring to make copies of 3rd-party components, stacks, and other artifacts in your own repo. sidebar_position: 14 -sidebar_label: Vendor Dependencies +sidebar_label: Vendoring id: vendoring --- import File from '@site/src/components/File' +import Terminal from '@site/src/components/Terminal' Atmos natively supports "vendoring," a practice that involves replicating 3rd-party components, stacks, and artifacts within your own repository. This feature is particularly beneficial for managing dependencies in software like Terraform, which do not support pulling root modules remotely @@ -40,368 +41,36 @@ With Atmos vendoring, you can copy components and other artifacts from the follo - Copy a local file to a local file with a different file name - Copy a local folder (all files) into a local folder -The vendoring configuration is defined in the `vendor.yaml` manifest (vendor config file). +Our implementation is primarily inspired by the excellent tool by VMware Tanzu, called [`vendir`](https://github.com/vmware-tanzu/carvel-vendir). +While Atmos does not call `vendir`, it functions and supports a subset of the configuration that is very similar. -## How it works - -Atmos searches for the vendoring manifest in the following locations, and uses the first one found: - -- In the directory from which the [`atmos vendor pull`](/cli/commands/vendor/pull) command is executed, usually in the root of the infrastructure repo - -- In the directory pointed to by the [`base_path`](/cli/configuration#base-path) setting in the [`atmos.yaml`](/cli/configuration) CLI config file - -After defining the `vendor.yaml` manifest, all the remote artifacts can be downloaded by running the following command: +## Use-cases -```bash -atmos vendor pull -``` +Atmos vendoring streamlines component sharing and version control across an enterprise, enhancing efficiency and collaboration while offering the flexibility to customize and manage multiple versions of dependencies, ensuring best practices in DevOps environments. -To vendor a particular component or other artifact, execute the following command: +- **Sharing Components Across an Enterprise**: Utilize Atmos vendoring to access a centralized component library, promoting code reuse and + efficiency across teams (or business units) while enabling customization and independent version control post-vendoring. This approach enhances collaboration without sacrificing the flexibility for teams to tailor components to their specific needs or update them at their preferred pace. +- **Managing Multiple Versions of Dependencies:** Use Atmos vendoring to manage multiple versions of remote dependencies, + effectively implementing version pinning through locally controlled artifacts. By configuring a stacks component directory (e.g., `vpc/v1` or `vpc/v2`), vendoring provides maximum flexibility while still aligning with best practices in DevOps environments. +- **Reinforce Immutable Infrastructure**: Employ Atmos vendoring to store immutable infrastructure artifacts, guaranteeing that once a committed, + it remains unaltered throughout its lifecycle, ensuring stability and reliability in deployments. -```bash -atmos vendor pull -c -``` +## Types of Vendoring -To vendor components and artifacts tagged with specific tags, execute the following command: +Atmos supports two different ways of vendoring components: -```bash -atmos vendor pull --tags , -``` +- [**Vendor Manifest**](/core-concepts/vendoring/vendor-manifest) Using `vendor.yaml` vendoring manifest file containing a list of all dependencies. +- [**Component Manifest**](/core-concepts/vendoring/component-manifest) Using `component.yaml` manifest file inside of a component directory. See below. -
+The `vendor.yaml` vendoring manifest describes the vendoring config for all components, stacks and other artifacts for the entire infrastructure. +The file is placed into the directory from which the `atmos vendor pull` command is executed. It's the recommended way to describe vendoring +configurations. :::tip -Refer to [`atmos vendor pull`](/cli/commands/vendor/pull) CLI command for more details -::: - -## Vendoring Manifest - -To vendor remote artifacts, create a `vendor.yaml` file similar to the example below: - -```yaml title="vendor.yaml" -# atmos vendor pull -# atmos vendor pull --component vpc-mixin-1 -# atmos vendor pull -c vpc-mixin-2 -# atmos vendor pull -c vpc-mixin-3 -# atmos vendor pull -c vpc-mixin-4 -# atmos vendor pull --tags test -# atmos vendor pull --tags networking,storage - -apiVersion: atmos/v1 -kind: AtmosVendorConfig -metadata: - name: example-vendor-config - description: Atmos vendoring manifest -spec: - # `imports` or `sources` (or both) must be defined in a vendoring manifest - imports: - - "vendor/vendor2" - - "vendor/vendor3.yaml" - - sources: - # `source` supports the following protocols: local paths (absolute and relative), OCI (https://opencontainers.org), - # Git, Mercurial, HTTP, HTTPS, Amazon S3, Google GCP, - # and all URL and archive formats as described in https://github.com/hashicorp/go-getter. - # In 'source', Golang templates are supported https://pkg.go.dev/text/template. - # If 'version' is provided, '{{.Version}}' will be replaced with the 'version' value before pulling the files from 'source'. - # Download the component from the AWS public ECR registry (https://docs.aws.amazon.com/AmazonECR/latest/public/public-registries.html). - - component: "vpc" - source: "oci://public.ecr.aws/cloudposse/components/terraform/stable/aws/vpc:{{.Version}}" - version: "latest" - targets: - - "components/terraform/infra/vpc3" - # Only include the files that match the 'included_paths' patterns. - # If 'included_paths' is not specified, all files will be matched except those that match the patterns from 'excluded_paths'. - # 'included_paths' support POSIX-style Globs for file names/paths (double-star `**` is supported). - # https://en.wikipedia.org/wiki/Glob_(programming) - # https://github.com/bmatcuk/doublestar#patterns - included_paths: - - "**/*.tf" - - "**/*.tfvars" - - "**/*.md" - # Tags can be used to vendor component that have the specific tags - # `atmos vendor pull --tags test` - # Refer to https://atmos.tools/cli/commands/vendor/pull - tags: - - test - - networking - - component: "vpc-flow-logs-bucket" - source: "github.com/cloudposse/terraform-aws-components.git//modules/vpc-flow-logs-bucket?ref={{.Version}}" - version: "1.323.0" - targets: - - "components/terraform/infra/vpc-flow-logs-bucket/{{.Version}}" - excluded_paths: - - "**/*.yaml" - - "**/*.yml" - # Tags can be used to vendor component that have the specific tags - # `atmos vendor pull --tags networking,storage` - # Refer to https://atmos.tools/cli/commands/vendor/pull - tags: - - test - - storage - - component: "vpc-mixin-1" - source: "https://raw.githubusercontent.com/cloudposse/terraform-null-label/0.25.0/exports/context.tf" - targets: - - "components/terraform/infra/vpc3" - # Tags can be used to vendor component that have the specific tags - # `atmos vendor pull --tags test` - # Refer to https://atmos.tools/cli/commands/vendor/pull - tags: - - test - - component: "vpc-mixin-2" - # Copy a local file into a local folder (keeping the same file name) - # This `source` is relative to the current folder - source: "components/terraform/mixins/context.tf" - targets: - - "components/terraform/infra/vpc3" - # Tags can be used to vendor component that have the specific tags - # `atmos vendor pull --tags test` - # Refer to https://atmos.tools/cli/commands/vendor/pull - tags: - - test - - component: "vpc-mixin-3" - # Copy a local folder into a local folder - # This `source` is relative to the current folder - source: "components/terraform/mixins" - targets: - - "components/terraform/infra/vpc3" - # Tags can be used to vendor component that have the specific tags - # `atmos vendor pull --tags test` - # Refer to https://atmos.tools/cli/commands/vendor/pull - tags: - - test - - component: "vpc-mixin-4" - # Copy a local file into a local file with a different file name - # This `source` is relative to the current folder - source: "components/terraform/mixins/context.tf" - targets: - - "components/terraform/infra/vpc3/context-copy.tf" - # Tags can be used to vendor component that have the specific tags - # `atmos vendor pull --tags test` - # Refer to https://atmos.tools/cli/commands/vendor/pull - tags: - - test -``` - -
- -- The `vendor.yaml` vendoring manifest supports Kubernetes-style YAML config to describe vendoring configuration for components, stacks, - and other artifacts. The file is placed into the directory from which the `atmos vendor pull` command is executed (usually the root of the repo). - -- The `source` attribute supports all protocols (local files, Git, Mercurial, HTTP, HTTPS, Amazon S3, Google GCP), and all the URL and - archive formats as described in [go-getter](https://github.com/hashicorp/go-getter), and also the `oci://` scheme to download artifacts from - [OCI registries](https://opencontainers.org). - - **IMPORTANT:** Include the `{{ .Version }}` parameter in your `source` URI to ensure the correct version of the artifact is downloaded. - For example: - - ```yaml - source: "github.com/cloudposse/terraform-aws-components.git//modules/vpc-flow-logs-bucket?ref={{.Version}}" - ``` - -- The `targets` in each source supports absolute paths and relative paths (relative to the `vendor.yaml` file). Note: if the `targets` paths - are set as relative, and if the `vendor.yaml` file is detected by Atmos using the `base_path` setting in `atmos.yaml`, the `targets` paths - will be considered relative to the `base_path`. Multiple targets can be specified. - -- `included_paths` and `excluded_paths` support [POSIX-style greedy Globs](https://en.wikipedia.org/wiki/Glob_(programming)) for filenames/paths - (double-star/globstar `**` is supported as well). - -- The `component` attribute in each source is optional. It's used in the `atmos vendor pull -- component ` command if the component is - passed in. In this case, Atmos will vendor only the specified component instead of vendoring all the artifacts configured in the `vendor.yaml` - manifest. - -- The `source` and `targets` attributes support [Go templates](https://pkg.go.dev/text/template) - and [Sprig Functions](http://masterminds.github.io/sprig/). This can be used to templatise the `source` and `targets` paths with the artifact - versions specified in the `version` attribute. - - Here's an advanced example showcasing how templates and Sprig functions can be used together with `targets`: - - ```yaml - targets: - # Vendor a component into a major-minor versioned folder like 1.2 - - "components/terraform/infra/vpc-flow-logs-bucket/{{ (first 2 (splitList \".\" .Version)) | join \".\" }}" - ``` - -- The `tags` in each source specifies a list of tags to apply to the component. This allows you to only vendor the components that have the - specified tags by executing a command `atmos vendor pull --tags ,` - -- The `imports` section defines the additional vendoring manifests that are merged into the main manifest. Hierarchical imports are supported - at many levels (one vendoring manifest can import another, which in turn can import other manifests, etc.). Atmos processes all imports and all - sources in the imported manifests in the order they are defined. - - **NOTE:** The imported file extensions are optional. If an import is defined without an extension, the `.yaml` extension is assumed and used - by default. - -
- -:::warning - -The `glob` library that Atmos uses to download remote artifacts does not treat the double-star `**` as including sub-folders. -If the component's folder has sub-folders, and you need to vendor them, they have to be explicitly defined as in the following example. - +Refer to [`Atmos Vendoring`](/core-concepts/vendoring) for more details ::: -```yaml title="vendor.yaml" -spec: - sources: - - component: "vpc-flow-logs-bucket" - source: "github.com/cloudposse/terraform-aws-components.git//modules/vpc-flow-logs-bucket?ref={{.Version}}" - version: "1.323.0" - targets: - - "components/terraform/vpc-flow-logs-bucket" - included_paths: - - "**/**" - # If the component's folder has the `modules` sub-folder, it needs to be explicitly defined - - "**/modules/**" -``` - -
- -## Hierarchical Imports in Vendoring Manifests - -Use `imports` to split the main `vendor.yaml` manifest into smaller files for maintainability, or by their roles in the infrastructure. - -For example, import separate manifests for networking, security, data management, CI/CD, and other layers: - -```yaml -imports: - - "layers/networking" - - "layers/security" - - "layers/data" - - "layers/analytics" - - "layers/firewalls" - - "layers/cicd" -``` - -Hierarchical imports are supported at many levels. For example, consider the following vendoring configurations: - -```yaml title="vendor.yaml" -apiVersion: atmos/v1 -kind: AtmosVendorConfig -metadata: - name: example-vendor-config - description: Atmos vendoring manifest -spec: - imports: - - "vendor/vendor2" - - "vendor/vendor3" - - sources: - - component: "vpc" - source: "oci://public.ecr.aws/cloudposse/components/terraform/stable/aws/vpc:{{.Version}}" - version: "latest" - targets: - - "components/terraform/infra/vpc3" - - component: "vpc-flow-logs-bucket" - source: "github.com/cloudposse/terraform-aws-components.git//modules/vpc-flow-logs-bucket?ref={{.Version}}" - version: "1.323.0" - targets: - - "components/terraform/infra/vpc-flow-logs-bucket/{{.Version}}" -``` - -```yaml title="vendor/vendor2.yaml" -apiVersion: atmos/v1 -kind: AtmosVendorConfig -metadata: - name: example-vendor-config-2 - description: Atmos vendoring manifest -spec: - imports: - - "vendor/vendor4" - - sources: - - component: "my-vpc1" - source: "oci://public.ecr.aws/cloudposse/components/terraform/stable/aws/vpc:{{.Version}}" - version: "1.0.2" - targets: - - "components/terraform/infra/my-vpc1" -``` - -```yaml title="vendor/vendor4.yaml" -apiVersion: atmos/v1 -kind: AtmosVendorConfig -metadata: - name: example-vendor-config-4 - description: Atmos vendoring manifest -spec: - imports: - - "vendor/vendor5" - - sources: - - component: "my-vpc4" - source: "github.com/cloudposse/terraform-aws-components.git//modules/vpc?ref={{.Version}}" - version: "1.319.0" - targets: - - "components/terraform/infra/my-vpc4" -``` - -When you execute the `atmos vendor pull` command, Atmos processes the import chain and the sources in the imported manifests in the order they -are defined: - -- First, the main `vendor.yaml` file is read based on search paths -- The `vendor/vendor2` and `vendor/vendor3` manifests (defined in the main `vendor.yaml` file) are imported -- The `vendor/vendor2` file is processed, and the `vendor/vendor4` manifest is imported -- The `vendor/vendor4` file is processed, and the `vendor/vendor5` manifest is imported -- Etc. -- Then all the sources from all the imported manifests are processed and the artifacts are downloaded into the paths defined by the `targets` -
-```bash -> atmos vendor pull - -Processing vendor config file 'vendor.yaml' -Pulling sources for the component 'my-vpc6' from 'github.com/cloudposse/terraform-aws-components.git//modules/vpc?ref=1.315.0' into 'components/terraform/infra/my-vpc6' -Pulling sources for the component 'my-vpc5' from 'github.com/cloudposse/terraform-aws-components.git//modules/vpc?ref=1.317.0' into 'components/terraform/infra/my-vpc5' -Pulling sources for the component 'my-vpc4' from 'github.com/cloudposse/terraform-aws-components.git//modules/vpc?ref=1.319.0' into 'components/terraform/infra/my-vpc4' -Pulling sources for the component 'my-vpc1' from 'public.ecr.aws/cloudposse/components/terraform/stable/aws/vpc:1.0.2' into 'components/terraform/infra/my-vpc1' -Pulling sources for the component 'my-vpc2' from 'github.com/cloudposse/terraform-aws-components.git//modules/vpc?ref=1.320.0' into 'components/terraform/infra/my-vpc2' -Pulling sources for the component 'vpc' from 'public.ecr.aws/cloudposse/components/terraform/stable/aws/vpc:latest' into 'components/terraform/infra/vpc3' -Pulling sources for the component 'vpc-flow-logs-bucket' from 'github.com/cloudposse/terraform-aws-components.git//modules/vpc-flow-logs-bucket?ref=1.323.0' into 'components/terraform/infra/vpc-flow-logs-bucket/1.323.0' -``` - -## Vendoring from OCI Registries - -Atmos supports vendoring from [OCI registries](https://opencontainers.org). - -To specify a repository in an OCI registry, use the `oci:///:tag` scheme. - -Artifacts from OCI repositories are downloaded as Docker image tarballs, then all the layers are processed, un-tarred and un-compressed, -and the files are written into the directories specified by the `targets` attribute of each `source`. - -For example, to vendor the `vpc` component from the `public.ecr.aws/cloudposse/components/terraform/stable/aws/vpc` -[AWS public ECR registry](https://docs.aws.amazon.com/AmazonECR/latest/public/public-registries.html), use the following `source`: - -```yaml -source: "oci://public.ecr.aws/cloudposse/components/terraform/stable/aws/vpc:latest" -``` - -The schema of a `vendor.yaml` manifest is as follows: - -```yaml -# This is an example of how to download a Terraform component from an OCI registry (https://opencontainers.org), e.g. AWS Public ECR - -apiVersion: atmos/v1 -kind: AtmosVendorConfig -metadata: - name: example-vendor-config - description: Atmos vendoring manifest -spec: - sources: - - component: "vpc" - source: "oci://public.ecr.aws/cloudposse/components/terraform/stable/aws/vpc:{{.Version}}" - version: "latest" - targets: - - "components/terraform/infra/vpc3" - included_paths: - - "**/*.tf" - - "**/*.tfvars" - - "**/*.md" - excluded_paths: [] -``` - -To vendor the `vpc` component, execute the following command: - -```bash -atmos vendor pull -c vpc -``` +The `component.yaml` vendoring manifest is used to vendor components from remote repositories. +A `component.yaml` file placed into a component's directory is used to describe the vendoring config for one component only. diff --git a/website/docs/core-concepts/workflows/workflows.mdx b/website/docs/core-concepts/workflows/workflows.mdx index 406aa06fc..5ec23557c 100644 --- a/website/docs/core-concepts/workflows/workflows.mdx +++ b/website/docs/core-concepts/workflows/workflows.mdx @@ -90,7 +90,7 @@ where: - `workflows.base_path` - the base path to Atmos workflow files -### Create Workflow Files and Define Workflows +### Create Workflow Files In `atmos.yaml`, we set `workflows.base_path` to `stacks/workflows`. The folder is relative to the root of the repository. @@ -108,6 +108,8 @@ account. You can segregate the workflow files even further, e.g. per account and service. For example, in the workflow file `stacks/workflows/workflows-dev-eks.yaml` you can define all EKS-related workflows for the `dev` account. +### Use Workflow Schema + Workflow files must confirm to the following schema: ```yaml @@ -348,17 +350,17 @@ To run this workflow, execute the following command: atmos workflow terraform-plan-test-component-override-3-all-stacks -f workflow1 ``` -## Atmos Stacks in Workflows +## Working with Atmos Stacks in Workflows -Atmos stack for the workflow commands of type `atmos` can be specified in four different ways: +The Atmos stack used by the workflow commands of type `atmos` can be specified in four different ways: -- Inline in the command itself +### Inline in the command itself ```yaml steps: - command: terraform plan test/test-component-override-2 -s tenant1-ue2-dev ``` -- In the workflow-level `stack` attribute +### In the workflow-level `stack` attribute ```yaml workflows: my-workflow: @@ -367,20 +369,22 @@ Atmos stack for the workflow commands of type `atmos` can be specified in four d - command: terraform plan test/test-component ``` -- In the step-level `stack` attribute +### In the step-level `stack` attribute ```yaml steps: - command: terraform plan test/test-component stack: tenant1-ue2-dev ``` -- On the command line +### On the command line ```console atmos workflow my-workflow -f workflow1 -s tenant1-ue2-dev ```
+### Stack Presedence + The stack defined inline in the command itself has the lowest priority, it can and will be overridden by any other stack definition. The step-level stack will override the workflow-level stack. The command line `--stack` option will override all other stacks defined in the workflow itself. You can also use any combinations of the above (e.g. specify the stack at the workflow level, then override it at the step level for some diff --git a/website/docs/quick-start/install-atmos.mdx b/website/docs/quick-start/install-atmos.mdx index a6fcef291..cbdbf60ab 100644 --- a/website/docs/quick-start/install-atmos.mdx +++ b/website/docs/quick-start/install-atmos.mdx @@ -15,6 +15,8 @@ To check what version of Atmos you have installed, just run `atmos version`. To find the latest available version of Atmos, visit the [Releases Page](https://github.com/cloudposse/atmos/releases). The latest version will always be available for download here. +## Using OS Package Managers + Atmos has native packages for macOS and every major Linux distribution. We also supply binary releases for Windows. diff --git a/website/sidebars.js b/website/sidebars.js index 8c052901e..47ab81702 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -104,7 +104,7 @@ module.exports = { }, { type: 'category', - label: 'Trouble Shooting', + label: 'Troubleshooting', collapsible: true, collapsed: true, items: [ From 6c0b5584ff60370765fd164482e8c06c6377ed39 Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Sat, 1 Jun 2024 20:05:06 -0500 Subject: [PATCH 005/151] fix colors of admonitons, add page for validating --- .../core-concepts/validating/components.mdx | 48 +++++++++---------- .../core-concepts/validating/validating.mdx | 33 +++++++++++++ website/src/css/custom.css | 9 +++- 3 files changed, 64 insertions(+), 26 deletions(-) create mode 100644 website/docs/core-concepts/validating/validating.mdx diff --git a/website/docs/core-concepts/validating/components.mdx b/website/docs/core-concepts/validating/components.mdx index eafe30f4a..d98d80eeb 100644 --- a/website/docs/core-concepts/validating/components.mdx +++ b/website/docs/core-concepts/validating/components.mdx @@ -6,9 +6,7 @@ description: Use JSON Schema and OPA policies to validate Components. id: components --- import Terminal from '@site/src/components/Terminal' - -Validation is essential for ensuring clean and correct configurations, especially in environments where multiple teams contribute -to the development and deployment processes. Atmos enhances this validation process in two significant ways with [JSON Schema](https://json-schema.org/) and [OPA](https://www.openpolicyagent.org/) policies. +import File from '@site/src/components/File' Atmos component validation allows: @@ -23,26 +21,13 @@ Refer to [atmos validate component](/cli/commands/validate/component) CLI comman ::: -## JSON Schema - -Atmos has native support for [JSON Schema](https://json-schema.org/), which can validate the schema of configurations. JSON Schema is an industry -standard and provides a vocabulary to annotate and validate JSON documents for correctness. - -This is powerful stuff: because you can define many schemas, it's possible to validate components differently for different environments or teams. - -## Open Policy Agent (OPA) - -The [Open Policy Agent](https://www.openpolicyagent.org/docs/latest/) (OPA, pronounced “oh-pa”) is another open-source industry standard that provides -a general-purpose policy engine to unify policy enforcement across your stacks. The OPA language (Rego) is a high-level declarative language for -specifying policy as code. Atmos has native support for the OPA decision-making engine to enforce policies across all the components in your stacks -(e.g. for microservice configurations). - ## Usage Atmos `validate component` command supports `--schema-path`, `--schema-type` and `--module-paths` command line arguments. If the arguments are not provided, Atmos will try to find and use the `settings.validation` section defined in the component's YAML config. -```bash + +```shell # Validate 'vpc' component using JSON Schema in the 'plat-ue2-prod' stack atmos validate component vpc -s plat-ue2-prod --schema-path vpc/validate-vpc-component.json --schema-type jsonschema @@ -64,13 +49,15 @@ atmos validate component vpc -s plat-ue2-dev # Validate 'vpc' component in the 'plat-ue2-dev' stack with a timeout of 15 seconds atmos validate component vpc -s plat-ue2-dev --timeout 15 ``` + ### Configure Component Validation In [`atmos.yaml`](https://github.com/cloudposse/atmos/blob/master/examples/quick-start/rootfs/usr/local/etc/atmos/atmos.yaml), add the `schemas` section: -```yaml title="atmos.yaml" + +```yaml # Validation schemas (for validating atmos stacks and components) schemas: # https://json-schema.org @@ -84,11 +71,13 @@ schemas: # Supports both absolute and relative paths base_path: "stacks/schemas/opa" ``` + In the component [manifest](https://github.com/cloudposse/atmos/blob/master/examples/quick-start/stacks/catalog/vpc/defaults.yaml), add the `settings.validation` section: -```yaml title="examples/quick-start/stacks/catalog/vpc/defaults.yaml" + +```yaml components: terraform: vpc: @@ -121,11 +110,13 @@ components: # Validation timeout in seconds timeout: 10 ``` + Add the following JSON Schema in the file [`stacks/schemas/jsonschema/vpc/validate-vpc-component.json`](https://github.com/cloudposse/atmos/blob/master/examples/quick-start/stacks/schemas/jsonschema/vpc/validate-vpc-component.json): -```json title="examples/quick-start/stacks/schemas/jsonschema/vpc/validate-vpc-component.json" + +```json { "$id": "vpc-component", "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -157,10 +148,12 @@ file [`stacks/schemas/jsonschema/vpc/validate-vpc-component.json`](https://githu } } ``` + Add the following Rego package in the file [`stacks/schemas/opa/catalog/constants/constants.rego`](https://github.com/cloudposse/atmos/blob/master/examples/quick-start/stacks/schemas/opa/catalog/constants/constants.rego): -```rego title="examples/quick-start/stacks/schemas/opa/catalog/constants/constants.rego" + +```rego package atmos.constants vpc_dev_max_availability_zones_error_message := "In 'dev', only 2 Availability Zones are allowed" @@ -171,10 +164,12 @@ vpc_name_regex := "^[a-zA-Z0-9]{2,20}$" vpc_name_regex_error_message := "VPC name must be a valid string from 2 to 20 alphanumeric chars" ``` + Add the following OPA policy in the file [`stacks/schemas/opa/vpc/validate-vpc-component.rego`](https://github.com/cloudposse/atmos/blob/master/examples/quick-start/stacks/schemas/opa/vpc/validate-vpc-component.rego): -```rego title="examples/quick-start/stacks/schemas/opa/vpc/validate-vpc-component.rego" + +```rego # Atmos looks for the 'errors' (array of strings) output from all OPA policies # If the 'errors' output contains one or more error messages, Atmos considers the policy failed @@ -206,6 +201,7 @@ errors[vpc_name_regex_error_message] { not re_match(vpc_name_regex, input.vars.name) } ``` +
@@ -276,10 +272,12 @@ exit status 1 Try to run the following commands to provision the component in the stacks: + ```bash atmos terraform apply vpc -s plat-ue2-prod atmos terraform apply vpc -s plat-ue2-dev ``` + Since the OPA validation policies don't pass, Atmos does not allow provisioning the component in the stacks: @@ -291,8 +289,9 @@ Since the OPA validation policies don't pass, Atmos does not allow provisioning ![atmos-validate-vpc-in-plat-ue2-dev](/img/atmos-validate-infra-vpc-in-tenant1-ue2-dev.png) -## OPA Policy Examples +## Advanced Policy Examples + ```rego # 'atmos' looks for the 'errors' (array of strings) output from all OPA policies # If the 'errors' output contains one or more error messages, 'atmos' considers the policy failed @@ -439,6 +438,7 @@ errors["'service_1_name' variable length must be greater than 10 chars"] { count(input.vars.service_1_name) <= 10 } ``` +
diff --git a/website/docs/core-concepts/validating/validating.mdx b/website/docs/core-concepts/validating/validating.mdx new file mode 100644 index 000000000..f0df768c2 --- /dev/null +++ b/website/docs/core-concepts/validating/validating.mdx @@ -0,0 +1,33 @@ +--- +title: Validating Stack Configurations +sidebar_position: 2 +sidebar_label: Validating Configurations +description: Use JSON Schema and OPA policies to validate Components. +id: validating +--- +import Terminal from '@site/src/components/Terminal' + +Validation is essential for ensuring clean and correct configurations, especially in environments where multiple teams contribute +to the development and deployment processes. Atmos enhances this validation process in two significant ways with [JSON Schema](https://json-schema.org/) and [OPA](https://www.openpolicyagent.org/) policies. + +:::tip + +Refer to [atmos validate component](/cli/commands/validate/component) CLI command for more information + +::: + +Atmos supports two types of native validation. + +## JSON Schema + +Atmos supports [JSON Schema](https://json-schema.org/) validation, which can validate the schema of configurations such as stacks, workflows, and vendoring manifests. +JSON Schema is an industry standard and provides a vocabulary to annotate and validate JSON documents for correctness. + +## Open Policy Agent (OPA) + +The [Open Policy Agent](https://www.openpolicyagent.org/docs/latest/) (OPA, pronounced “oh-pa”) is another open-source industry standard that provides +a general-purpose policy engine to unify policy enforcement across your stacks. The OPA language (Rego) is a high-level declarative language for +specifying policy as code. Atmos has native support for the OPA decision-making engine to enforce policies across all the components in your stacks +(e.g. for microservice configurations). + +This is powerful stuff: because you can define many policies, it's possible to validate components differently for different environments or teams. diff --git a/website/src/css/custom.css b/website/src/css/custom.css index d0fc622ee..b79bc4a11 100644 --- a/website/src/css/custom.css +++ b/website/src/css/custom.css @@ -195,8 +195,13 @@ article h1 { } [data-theme='dark'] .alert--secondary { - --ifm-color-secondary-contrast-background: #000; - --ifm-alert-background-color: #000; + --ifm-color-secondary-contrast-background: rgb(67 67 67 / 31%); + --ifm-alert-background-color: rgb(67 67 67 / 31%); +} + +[data-theme='dark'] .alert--info { + --ifm-color-info-contrast-background: rgb(25, 60, 71, 0.50); + --ifm-alert-background-color: rgb(25, 60, 71, 0.50); } .alert--secondary { From 0105c231d6d9d4fbdd6193dc95e8e1634224aa9c Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Sat, 1 Jun 2024 20:11:42 -0500 Subject: [PATCH 006/151] use a blueish info bg --- website/src/css/custom.css | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/src/css/custom.css b/website/src/css/custom.css index b79bc4a11..1db2c8371 100644 --- a/website/src/css/custom.css +++ b/website/src/css/custom.css @@ -195,8 +195,8 @@ article h1 { } [data-theme='dark'] .alert--secondary { - --ifm-color-secondary-contrast-background: rgb(67 67 67 / 31%); - --ifm-alert-background-color: rgb(67 67 67 / 31%); + --ifm-color-secondary-contrast-background: rgb(145 161 217 / 24%); + --ifm-alert-background-color: rgb(145 161 217 / 24%); } [data-theme='dark'] .alert--info { From cffbed94d099c2a89954bc3f3d9b02ff6c44c534 Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Sun, 2 Jun 2024 08:07:40 -0500 Subject: [PATCH 007/151] fix wording --- website/docs/cli/cli.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/cli/cli.mdx b/website/docs/cli/cli.mdx index a5765f972..e96219d38 100644 --- a/website/docs/cli/cli.mdx +++ b/website/docs/cli/cli.mdx @@ -10,7 +10,7 @@ import Screengrab from '@site/src/components/Screengrab' import Terminal from '@site/src/components/Terminal' :::note Purpose -Use this command to start an interactive UI to select an Atmos command, component and stack. Press `Enter` to execute the command for the selected +Use this command to start an interactive UI to run Atmos commands against any component or stack. Press `Enter` to execute the command for the selected stack and component ::: From c860eff877b710f840bd681bbae8ea2641412cbf Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Sun, 2 Jun 2024 10:15:19 -0500 Subject: [PATCH 008/151] add latest atmos version to nav bar. fix broken links --- .../docs/cli/commands/vendor/vendor-pull.mdx | 2 +- .../docs/core-concepts/stacks/inheritance.mdx | 2 +- .../docs/core-concepts/stacks/templating.mdx | 4 +- .../design-patterns/abstract-component.mdx | 2 +- .../design-patterns/component-inheritance.mdx | 2 +- .../github-actions/atmos-terraform-plan.mdx | 2 +- website/docs/introduction/faq.mdx | 2 +- .../docs/quick-start/advanced/next-steps.md | 2 +- website/docusaurus.config.js | 17 +++- website/package-lock.json | 85 +++++++++++++++++++ website/package.json | 1 + website/plugins/fetch-latest-release/index.js | 32 +++++++ .../plugins/fetch-latest-release/package.json | 5 ++ website/src/css/custom.css | 12 +++ website/src/theme/NavbarItem.js | 21 +++++ 15 files changed, 181 insertions(+), 10 deletions(-) create mode 100644 website/plugins/fetch-latest-release/index.js create mode 100644 website/plugins/fetch-latest-release/package.json create mode 100644 website/src/theme/NavbarItem.js diff --git a/website/docs/cli/commands/vendor/vendor-pull.mdx b/website/docs/cli/commands/vendor/vendor-pull.mdx index 716b8ce0d..c63afc066 100644 --- a/website/docs/cli/commands/vendor/vendor-pull.mdx +++ b/website/docs/cli/commands/vendor/vendor-pull.mdx @@ -92,7 +92,7 @@ Refer to [`Atmos Vendoring`](/core-concepts/vendoring) for more details file names/paths (double-star/globstar `**` is supported as well). :::tip -Refer to [`Atmos Component Vendoring`](/core-concepts/vendoring/components) for more details +Refer to [`Atmos Component Vendoring`](/core-concepts/vendoring/component-manifest) for more details ::: ## Vendoring from OCI Registries diff --git a/website/docs/core-concepts/stacks/inheritance.mdx b/website/docs/core-concepts/stacks/inheritance.mdx index 0f7302267..9726c266d 100644 --- a/website/docs/core-concepts/stacks/inheritance.mdx +++ b/website/docs/core-concepts/stacks/inheritance.mdx @@ -7,7 +7,7 @@ id: inheritance import File from '@site/src/components/File' import Terminal from '@site/src/components/Terminal' -Component Inheritance is one of the principles of [Component-Oriented Programming (COP)](/core-concepts/components/component-oriented-programming) +Component Inheritance is one of the principles of [Component-Oriented Programming (COP)](/core-concepts/stacks/component-oriented-configuration) supported by Atmos. Component Inheritance is the ability to combine multiple configurations through ordered deep-merging of configurations. The concept is borrowed from diff --git a/website/docs/core-concepts/stacks/templating.mdx b/website/docs/core-concepts/stacks/templating.mdx index 1bd95efe3..d3b170ae9 100644 --- a/website/docs/core-concepts/stacks/templating.mdx +++ b/website/docs/core-concepts/stacks/templating.mdx @@ -23,7 +23,7 @@ Atmos supports many different ways of configuring and using `Go` templates: - In [Atmos Custom Commands](/core-concepts/custom-commands) - In [Atmos Vendoring](/core-concepts/vendoring) -- In [Atmos Component Vendoring](/core-concepts/vendoring/components) +- In [Atmos Component Vendoring](/core-concepts/vendoring/component-manifest) - In [Imports](/core-concepts/stacks/imports) - In [Stack Manifests](/core-concepts/stacks) @@ -36,7 +36,7 @@ These templates are processed in different phases and use different context: exposing all the component sections that are returned by the `atmos describe component -s ` CLI command -- `Go` templates in [Atmos Vendoring](/core-concepts/vendoring) and [Atmos Component Vendoring](/core-concepts/vendoring/components) +- `Go` templates in [Atmos Vendoring](/core-concepts/vendoring) and [Atmos Component Vendoring](/core-concepts/vendoring/component-manifest) are processed when the CLI command [`atmos vendor pull`](/cli/commands/vendor/pull) is executed. The templates in the vendoring manifests support the `{{.Version}}` variable, and the execution context is provided in the `version` attribute diff --git a/website/docs/design-patterns/abstract-component.mdx b/website/docs/design-patterns/abstract-component.mdx index 29f038d42..38e825896 100644 --- a/website/docs/design-patterns/abstract-component.mdx +++ b/website/docs/design-patterns/abstract-component.mdx @@ -227,5 +227,5 @@ being deployed by 'metadata.type: abstract' attribute ## References -- [Component-Oriented Programming](/core-concepts/components/component-oriented-programming) +- [Component-Oriented Programming](/core-concepts/stacks/component-oriented-configuration) - [Component Inheritance](/core-concepts/stacks/inheritance) diff --git a/website/docs/design-patterns/component-inheritance.mdx b/website/docs/design-patterns/component-inheritance.mdx index 9139b3a97..e912b03aa 100644 --- a/website/docs/design-patterns/component-inheritance.mdx +++ b/website/docs/design-patterns/component-inheritance.mdx @@ -186,5 +186,5 @@ components: ## References -- [Component-Oriented Programming](/core-concepts/components/component-oriented-programming) +- [Component-Oriented Programming](/core-concepts/stacks/component-oriented-configuration) - [Component Inheritance](/core-concepts/stacks/inheritance) diff --git a/website/docs/integrations/github-actions/atmos-terraform-plan.mdx b/website/docs/integrations/github-actions/atmos-terraform-plan.mdx index 0737c5196..2c5e32d85 100644 --- a/website/docs/integrations/github-actions/atmos-terraform-plan.mdx +++ b/website/docs/integrations/github-actions/atmos-terraform-plan.mdx @@ -102,7 +102,7 @@ This GitHub Action depends on a few resources: This action can use any S3 Bucket to keep track of your planfiles. Just ensure the bucket is properly locked down since planfiles may contain secrets. -For example, [vendor in](/core-concepts/vendoring/components) the [`s3-component`](https://docs.cloudposse.com/components/library/aws/s3-bucket/), then using an [Atmos stack configuration](/core-concepts/stacks/), define a bucket using the [`s3-bucket` component](https://github.com/cloudposse/terraform-aws-components/tree/main/modules/s3-bucket) with this catalog configuration: +For example, [vendor in](/core-concepts/vendoring/component-manifest) the [`s3-component`](https://docs.cloudposse.com/components/library/aws/s3-bucket/), then using an [Atmos stack configuration](/core-concepts/stacks/), define a bucket using the [`s3-bucket` component](https://github.com/cloudposse/terraform-aws-components/tree/main/modules/s3-bucket) with this catalog configuration: ```yaml import: diff --git a/website/docs/introduction/faq.mdx b/website/docs/introduction/faq.mdx index d0c198d0e..f4d5223b0 100644 --- a/website/docs/introduction/faq.mdx +++ b/website/docs/introduction/faq.mdx @@ -66,7 +66,7 @@ and offers an easy exit strategy by [generating and committing these files](/cli #### Atmos provides prescriptive guidance on operating Terraform at scale -Furthermore, Atmos delivers prescriptive guidance on [design patterns](/design-patterns/) and [component architecture](/core-concepts/components/component-oriented-programming) for Terraform root modules, establishing itself as an opinionated framework designed to enhance Terraform's capabilities. It offers [advanced features](/core-concepts/stacks/inheritance) tailored for both straightforward and intricate deployment scenarios. Essentially acting as a comprehensive framework, Atmos is exceptionally well-suited for complex, regulated enterprise environments. Its robust support for [Stack manifests](/core-concepts/stacks) underscores its versatility as a tool, enabling precise and effortless infrastructure management and orchestration across various scales and complexities. +Furthermore, Atmos delivers prescriptive guidance on [design patterns](/design-patterns/) and [component architecture](/core-concepts/stacks/component-oriented-configuration) for Terraform root modules, establishing itself as an opinionated framework designed to enhance Terraform's capabilities. It offers [advanced features](/core-concepts/stacks/inheritance) tailored for both straightforward and intricate deployment scenarios. Essentially acting as a comprehensive framework, Atmos is exceptionally well-suited for complex, regulated enterprise environments. Its robust support for [Stack manifests](/core-concepts/stacks) underscores its versatility as a tool, enabling precise and effortless infrastructure management and orchestration across various scales and complexities. ### Can Atmos be used together with Terragrunt? diff --git a/website/docs/quick-start/advanced/next-steps.md b/website/docs/quick-start/advanced/next-steps.md index bb05b97d1..af380e2c1 100644 --- a/website/docs/quick-start/advanced/next-steps.md +++ b/website/docs/quick-start/advanced/next-steps.md @@ -15,7 +15,7 @@ Here are some of the major differentiators of Atmos: * [Atmos Design Patterns](/design-patterns) * [Third-party Integrations](/integrations) * [Atmos Vendoring](/core-concepts/vendoring) -* [Component Vendoring](/core-concepts/vendoring/components) +* [Component Vendoring](/core-concepts/vendoring/component-manifest) * [Imports](/core-concepts/stacks/imports) (mixins, catalogs) * [Workflow Automation](/core-concepts/workflows) * [Custom Commands](/core-concepts/custom-commands) diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 0c61cac16..593628a37 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -5,8 +5,11 @@ // https://docusaurus.io/docs/markdown-features/code-blocks#line-highlighting // https://github.com/FormidableLabs/prism-react-renderer/tree/master/packages/prism-react-renderer/src/themes +const path = require('path'); + const lightCodeTheme = require('prism-react-renderer').themes.vsDark; const darkCodeTheme = require('prism-react-renderer').themes.nightOwl; +const latestReleasePlugin = require('./plugins/fetch-latest-release'); const BASE_URL = ''; @@ -64,6 +67,9 @@ const config = { containerId: 'GTM-KQ62MGX9', }, ], + [ + path.resolve(__dirname, 'plugins', 'fetch-latest-release'), {} + ] ], presets: [ @@ -93,7 +99,6 @@ const config = { }), ], ], - themeConfig: /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ ({ @@ -113,6 +118,12 @@ const config = { height: 36 }, items: [ + { + label: `Latest Release`, + href: `https://github.com/cloudposse/atmos/releases/latest`, + position: 'left', + className: 'latest-release-link' // Add a class to identify this link + }, { type: 'doc', docId: 'introduction/index', @@ -198,6 +209,10 @@ const config = { }, }), + customFields: { + latestRelease: 'v0.0.0', // initial placeholder + }, + markdown: { mermaid: true, }, diff --git a/website/package-lock.json b/website/package-lock.json index 14938c6c9..1b5e33735 100644 --- a/website/package-lock.json +++ b/website/package-lock.json @@ -26,6 +26,7 @@ "docusaurus-plugin-image-zoom": "^2.0.0", "html-loader": "^5.0.0", "marked": "^13.0.0", + "node-fetch": "^3.3.2", "prism-react-renderer": "^2.3.1", "react": "^18.3.1", "react-dom": "^18.3.1", @@ -6407,6 +6408,14 @@ "lodash-es": "^4.17.21" } }, + "node_modules/data-uri-to-buffer": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/data-uri-to-buffer/-/data-uri-to-buffer-4.0.1.tgz", + "integrity": "sha512-0R9ikRb668HB7QDxT1vkpuUBtqc53YyAwMwGeUFKRojY/NWKvdZ+9UYtRfGmhqNbRkTSVpMbmyhXipFFv2cb/A==", + "engines": { + "node": ">= 12" + } + }, "node_modules/dayjs": { "version": "1.11.10", "resolved": "https://registry.npmjs.org/dayjs/-/dayjs-1.11.10.tgz", @@ -7312,6 +7321,28 @@ "node": ">=0.4.0" } }, + "node_modules/fetch-blob": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/fetch-blob/-/fetch-blob-3.2.0.tgz", + "integrity": "sha512-7yAQpD2UMJzLi1Dqv7qFYnPbaPx7ZfFK6PiIxQ4PfkGPyNyl2Ugx+a/umUonmKqjhM4DnfbMvdX6otXq83soQQ==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/jimmywarting" + }, + { + "type": "paypal", + "url": "https://paypal.me/jimmywarting" + } + ], + "dependencies": { + "node-domexception": "^1.0.0", + "web-streams-polyfill": "^3.0.3" + }, + "engines": { + "node": "^12.20 || >= 14.13" + } + }, "node_modules/file-loader": { "version": "6.2.0", "resolved": "https://registry.npmjs.org/file-loader/-/file-loader-6.2.0.tgz", @@ -7570,6 +7601,17 @@ "node": ">=0.4.x" } }, + "node_modules/formdata-polyfill": { + "version": "4.0.10", + "resolved": "https://registry.npmjs.org/formdata-polyfill/-/formdata-polyfill-4.0.10.tgz", + "integrity": "sha512-buewHzMvYL29jdeQTVILecSaZKnt/RJWjoZCF5OW60Z67/GmSLBkOFM7qh1PI3zFNtJbaZL5eQu1vLfazOwj4g==", + "dependencies": { + "fetch-blob": "^3.1.2" + }, + "engines": { + "node": ">=12.20.0" + } + }, "node_modules/forwarded": { "version": "0.2.0", "resolved": "https://registry.npmjs.org/forwarded/-/forwarded-0.2.0.tgz", @@ -12924,6 +12966,24 @@ "tslib": "^2.0.3" } }, + "node_modules/node-domexception": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/node-domexception/-/node-domexception-1.0.0.tgz", + "integrity": "sha512-/jKZoMpw0F8GRwl4/eLROPA3cfcXtLApP0QzLmUT/HuPCZWyB7IY9ZrMeKw2O/nFIqPQB3PVM9aYm0F312AXDQ==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/jimmywarting" + }, + { + "type": "github", + "url": "https://paypal.me/jimmywarting" + } + ], + "engines": { + "node": ">=10.5.0" + } + }, "node_modules/node-emoji": { "version": "2.1.3", "resolved": "https://registry.npmjs.org/node-emoji/-/node-emoji-2.1.3.tgz", @@ -12938,6 +12998,23 @@ "node": ">=18" } }, + "node_modules/node-fetch": { + "version": "3.3.2", + "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-3.3.2.tgz", + "integrity": "sha512-dRB78srN/l6gqWulah9SrxeYnxeddIG30+GOqK/9OlLVyLg3HPnr6SqOWTWOXKRwC2eGYCkZ59NNuSgvSrpgOA==", + "dependencies": { + "data-uri-to-buffer": "^4.0.0", + "fetch-blob": "^3.1.4", + "formdata-polyfill": "^4.0.10" + }, + "engines": { + "node": "^12.20.0 || ^14.13.1 || >=16.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/node-fetch" + } + }, "node_modules/node-forge": { "version": "1.3.1", "resolved": "https://registry.npmjs.org/node-forge/-/node-forge-1.3.1.tgz", @@ -17207,6 +17284,14 @@ "url": "https://github.com/sponsors/wooorm" } }, + "node_modules/web-streams-polyfill": { + "version": "3.3.3", + "resolved": "https://registry.npmjs.org/web-streams-polyfill/-/web-streams-polyfill-3.3.3.tgz", + "integrity": "sha512-d2JWLCivmZYTSIoge9MsgFCZrt571BikcWGYkjC1khllbTeDlGqZ2D8vD8E/lJa8WGWbb7Plm8/XJYV7IJHZZw==", + "engines": { + "node": ">= 8" + } + }, "node_modules/web-worker": { "version": "1.2.0", "resolved": "https://registry.npmjs.org/web-worker/-/web-worker-1.2.0.tgz", diff --git a/website/package.json b/website/package.json index bfb810032..cd81a52c5 100644 --- a/website/package.json +++ b/website/package.json @@ -32,6 +32,7 @@ "docusaurus-plugin-image-zoom": "^2.0.0", "html-loader": "^5.0.0", "marked": "^13.0.0", + "node-fetch": "^3.3.2", "prism-react-renderer": "^2.3.1", "react": "^18.3.1", "react-dom": "^18.3.1", diff --git a/website/plugins/fetch-latest-release/index.js b/website/plugins/fetch-latest-release/index.js new file mode 100644 index 000000000..d3bf0f726 --- /dev/null +++ b/website/plugins/fetch-latest-release/index.js @@ -0,0 +1,32 @@ +const fetch = require('node-fetch'); +//require('dotenv').config(); + +async function fetchLatestRelease() { + const response = await fetch(`https://api.github.com/repos/cloudposse/atmos/releases/latest`, { + headers: { +// 'Authorization': `token ${process.env.GITHUB_TOKEN}`, + 'Accept': 'application/vnd.github.v3+json' + } + }); + + if (!response.ok) { + throw new Error(`GitHub API responded with ${response.status}`); + } + + const release = await response.json(); + return release.tag_name; +} + +module.exports = function(context, options) { + return { + name: 'fetch-latest-release', + async loadContent() { + const latestRelease = await fetchLatestRelease(); + return { latestRelease }; + }, + async contentLoaded({ content, actions }) { + const { setGlobalData } = actions; + setGlobalData(content); + } + }; +}; diff --git a/website/plugins/fetch-latest-release/package.json b/website/plugins/fetch-latest-release/package.json new file mode 100644 index 000000000..865e68447 --- /dev/null +++ b/website/plugins/fetch-latest-release/package.json @@ -0,0 +1,5 @@ +{ + "name": "fetch-latest-release", + "version": "0.0.0", + "private": true +} diff --git a/website/src/css/custom.css b/website/src/css/custom.css index 1db2c8371..91519cbba 100644 --- a/website/src/css/custom.css +++ b/website/src/css/custom.css @@ -14,6 +14,17 @@ html[data-theme='dark'] nav.navbar { background: rgba(3, 7, 17, .75); } +.navbar-sidebar--show .navbar-sidebar { + height: 100vh; +} + +a.navbar__item.navbar__link.latest-release-link { + color: #cccccc6e; + font-size: 0.8em; + padding: 0; + margin-right: 1em; +} + .navbar__title { font-size: 2em; } @@ -22,6 +33,7 @@ html[data-theme='dark'] nav.navbar { { position: relative; bottom: 2px; + margin-right: 0; } div.atmos__effect, html[data-theme='dark'] div.navbar__logo { diff --git a/website/src/theme/NavbarItem.js b/website/src/theme/NavbarItem.js new file mode 100644 index 000000000..a9eba9e37 --- /dev/null +++ b/website/src/theme/NavbarItem.js @@ -0,0 +1,21 @@ +import React, { useEffect } from 'react'; +import OriginalNavBarItem from '@theme-original/NavbarItem'; +import useGlobalData from '@docusaurus/useGlobalData'; + +export default function NavbarItem(props) { + const globalData = useGlobalData(); + + //console.log('Global Data:', JSON.stringify(globalData['fetch-latest-release'])); + + const latestRelease = globalData['fetch-latest-release']?.default?.latestRelease || 'v0.0.0'; + + useEffect(() => { + const latestReleaseLink = document.querySelector('.latest-release-link'); + if (latestReleaseLink) { + latestReleaseLink.href = `https://github.com/cloudposse/atmos/releases/tag/${latestRelease}`; + latestReleaseLink.innerText = `${latestRelease}`; + } + }, [latestRelease]); + + return ; +} From ec4f7f52b6865e63d6d820adb7e2906f02df826e Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Sun, 2 Jun 2024 14:07:34 -0500 Subject: [PATCH 009/151] Add community pages --- website/docs/community/community.mdx | 15 +++++++++ website/docs/community/office-hours.mdx | 7 ++++ website/docs/community/slack.mdx | 31 ++++++++++++++++++ website/docs/contributing/coc.md | 2 +- website/docs/contributing/contributing.mdx | 3 +- .../docs/contributing/how-to-contribute.md | 4 +-- .../docs/core-concepts/stacks/inheritance.mdx | 2 +- .../docs/core-concepts/stacks/overrides.mdx | 2 +- website/docusaurus.config.js | 32 ++++++------------- website/sidebars.js | 19 +++++++---- website/src/css/custom.css | 14 ++++++++ 11 files changed, 96 insertions(+), 35 deletions(-) create mode 100644 website/docs/community/community.mdx create mode 100644 website/docs/community/office-hours.mdx create mode 100644 website/docs/community/slack.mdx diff --git a/website/docs/community/community.mdx b/website/docs/community/community.mdx new file mode 100644 index 000000000..4e7e36d87 --- /dev/null +++ b/website/docs/community/community.mdx @@ -0,0 +1,15 @@ +--- +title: Community +sidebar_position: 1 +sidebar_label: Community +sidebar_class_name: hidden +description: Community +id: community +--- + +# Contributing + + +import DocCardList from "@theme/DocCardList"; + + diff --git a/website/docs/community/office-hours.mdx b/website/docs/community/office-hours.mdx new file mode 100644 index 000000000..a68c0c256 --- /dev/null +++ b/website/docs/community/office-hours.mdx @@ -0,0 +1,7 @@ +--- +title: Office Hours +sidebar_position: 3 +sidebar_label: Office Hours +description: Office Hours with Cloud Posse +id: office-hours +--- diff --git a/website/docs/community/slack.mdx b/website/docs/community/slack.mdx new file mode 100644 index 000000000..3d6bf9656 --- /dev/null +++ b/website/docs/community/slack.mdx @@ -0,0 +1,31 @@ +--- +title: Slack Community +sidebar_position: 3 +sidebar_label: Slack +description: Cloud Posse's SweetOps Slack Community +id: slack +--- + +# Join our `#atmos` Community! +We welcome you to join our very active DevOps community! +There are over 9000+ members as part of our our Slack team. +Tons of members from our Open Source community have joined and it's a great way to talk with other contributors + + + +:::tip Join us on Office Hours + +We hold ["office hours" every Wednesday at 11:30am PST](/community/office-hours). + +::: diff --git a/website/docs/contributing/coc.md b/website/docs/contributing/coc.md index eec210a1a..59dde9c5e 100644 --- a/website/docs/contributing/coc.md +++ b/website/docs/contributing/coc.md @@ -1,5 +1,5 @@ --- -sidebar_position: 1 +sidebar_position: 2 title: Code of Conduct sidebar_label: Code of Conduct --- diff --git a/website/docs/contributing/contributing.mdx b/website/docs/contributing/contributing.mdx index b068c585e..fb9cfbe30 100644 --- a/website/docs/contributing/contributing.mdx +++ b/website/docs/contributing/contributing.mdx @@ -1,7 +1,8 @@ --- title: Contributing -sidebar_position: 10 +sidebar_position: 1 sidebar_label: Contributing +sidebar_class_name: hidden description: Contributing id: contributing --- diff --git a/website/docs/contributing/how-to-contribute.md b/website/docs/contributing/how-to-contribute.md index 239e7f9fd..4729909e6 100644 --- a/website/docs/contributing/how-to-contribute.md +++ b/website/docs/contributing/how-to-contribute.md @@ -1,7 +1,7 @@ --- title: How to Contribute -sidebar_position: 2 -sidebar_label: Contributing +sidebar_position: 3 +sidebar_label: How to Contribute --- Thanks for the interest in contributing to the Atmos project! diff --git a/website/docs/core-concepts/stacks/inheritance.mdx b/website/docs/core-concepts/stacks/inheritance.mdx index 9726c266d..d5f101eb6 100644 --- a/website/docs/core-concepts/stacks/inheritance.mdx +++ b/website/docs/core-concepts/stacks/inheritance.mdx @@ -1,5 +1,5 @@ --- -title: Component Inheritance +title: Inherit Configurations in Atmos Stacks sidebar_position: 4 sidebar_label: Inherit Configurations id: inheritance diff --git a/website/docs/core-concepts/stacks/overrides.mdx b/website/docs/core-concepts/stacks/overrides.mdx index ed4f60c4f..ad25d0a54 100644 --- a/website/docs/core-concepts/stacks/overrides.mdx +++ b/website/docs/core-concepts/stacks/overrides.mdx @@ -1,5 +1,5 @@ --- -title: Component Overrides +title: Override Configurations sidebar_position: 5 sidebar_label: Override Configuration description: Use the 'Component Overrides' pattern to modify components' configuration and behavior in the current scope. diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 593628a37..13b819bd6 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -136,40 +136,26 @@ const config = { label: 'Reference' }, { - type: 'dropdown', label: 'Community', position: 'left', - items: [ - { - label: 'Weekly Office Hours', - href: 'https://cloudposse.com/office-hours/', - }, - { - label: 'Slack Community', - href: 'https://slack.cloudposse.com/', - }, - { - label: 'Slack Archives', - href: 'https://archive.sweetops.com/atmos/', - }, - { - label: 'Contributing', - type: 'doc', - docId: 'contributing/contributing', - }, - ], + to: '/community' }, + // Algolia search configuration { - to: 'https://cloudposse.com/services/', - label: 'Get Help', + type: 'search', position: 'right', - className: 'button button--primary navbar-cta-button' }, { href: 'https://github.com/cloudposse/atmos', position: 'right', className: 'header-github-link', 'aria-label': 'GitHub repository', + }, + { + to: 'https://cloudposse.com/services/', + label: 'Get Help', + position: 'right', + className: 'button button--primary navbar-cta-button' } ], }, diff --git a/website/sidebars.js b/website/sidebars.js index 47ab81702..82da36f52 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -28,14 +28,21 @@ module.exports = { ] } ], - contributing: [ + community: [ + { + type: 'category', + label: 'Community', + className: 'sidebar-title', + collapsible: false, + collapsed: false, + items: [ 'community/community', 'community/slack', 'community/office-hours' ] + }, { type: 'category', - label: 'Contributing Index Page', - link: { - type: 'doc', - id: 'contributing/contributing' - }, + label: 'Contributing', + className: 'sidebar-title', + collapsible: false, + collapsed: false, items: [ { type: 'autogenerated', diff --git a/website/src/css/custom.css b/website/src/css/custom.css index 91519cbba..dfaf8ef35 100644 --- a/website/src/css/custom.css +++ b/website/src/css/custom.css @@ -203,9 +203,14 @@ article h1 { --ifm-card-background-color: #eeeeee14; --ifm-button-color: #ccc; --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3); + } +html[data-theme='dark'] { + --docsearch-searchbox-background: #121526 !important; +} + [data-theme='dark'] .alert--secondary { --ifm-color-secondary-contrast-background: rgb(145 161 217 / 24%); --ifm-alert-background-color: rgb(145 161 217 / 24%); @@ -297,6 +302,10 @@ li.menu__list-item.hidden { border-radius: 32px; } +.DocSearch-Button-Placeholder { + min-width: 200px; +} + .aa-Autocomplete { min-width: 150px; } @@ -308,6 +317,11 @@ li.menu__list-item.hidden { .navbar-cta-button { color: var(--ifm-button-color); font-weight: bolder; + order: 2; +} + +.navbar-sidebar__item menu .navbar-cta-button { + margin-left: 2em; } .navbar-cta-button:hover { From af13d7251313d5488842484761730b7407f2b4e1 Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Mon, 3 Jun 2024 12:37:11 -0500 Subject: [PATCH 010/151] Add a pillbox component. Correct usage of className. --- website/docs/community/community.mdx | 2 +- website/docs/community/office-hours.mdx | 20 ++++++++ website/docs/community/slack.mdx | 6 +-- website/docs/contributing/contributing.mdx | 2 +- website/docs/core-concepts/stacks/catalogs.md | 2 +- .../component-oriented-configuration.mdx | 3 ++ website/docs/core-concepts/stacks/imports.mdx | 4 +- website/docs/core-concepts/stacks/mixins.mdx | 3 ++ .../docs/core-concepts/stacks/overrides.mdx | 2 +- .../docs/core-concepts/stacks/templating.mdx | 3 ++ .../core-concepts/vendoring/vendoring.mdx | 2 +- .../docs/quick-start/advanced/advanced.mdx | 3 ++ website/sidebars.js | 2 +- website/src/components/File.tsx | 2 +- website/src/components/PillBox/index.css | 13 +++++ website/src/components/PillBox/index.tsx | 12 +++++ website/src/components/Terminal.tsx | 10 ++-- website/src/components/Typewriter.tsx | 2 +- website/src/css/custom.css | 4 ++ website/src/pages/index.js | 50 +++++++++---------- 20 files changed, 104 insertions(+), 43 deletions(-) create mode 100644 website/src/components/PillBox/index.css create mode 100644 website/src/components/PillBox/index.tsx diff --git a/website/docs/community/community.mdx b/website/docs/community/community.mdx index 4e7e36d87..cbd53bd85 100644 --- a/website/docs/community/community.mdx +++ b/website/docs/community/community.mdx @@ -7,7 +7,7 @@ description: Community id: community --- -# Contributing +# Community Resources import DocCardList from "@theme/DocCardList"; diff --git a/website/docs/community/office-hours.mdx b/website/docs/community/office-hours.mdx index a68c0c256..0498ad6a2 100644 --- a/website/docs/community/office-hours.mdx +++ b/website/docs/community/office-hours.mdx @@ -5,3 +5,23 @@ sidebar_label: Office Hours description: Office Hours with Cloud Posse id: office-hours --- +import Head from '@docusaurus/Head'; + + + + + +# Office Hours Registration + + + - -