cloudposse · aknysh · Dec 5, 2025 · Dec 5, 2025
@@ -193,6 +193,7 @@ refer to [Atmos Component Inheritance](/howto/inheritance)
 
 ## References
 
+- [Component Metadata](/stacks/components/component-metadata) - Configure `terraform_workspace` and `terraform_workspace_pattern`
 - [Terraform Workspaces](https://developer.hashicorp.com/terraform/language/state/workspaces)
 - [Managing Terraform Workspaces](https://developer.hashicorp.com/terraform/cli/workspaces)
 - [Terraform Environment Variables](https://developer.hashicorp.com/terraform/cli/config/environment-variables)

@@ -22,7 +22,7 @@ Atmos supports the following concepts and principles of **Component-Oriented Pro
   component
 
 These concepts and principles are implemented and used in Atmos by combining two features: [`import`](/stacks/imports)
-and [`metadata`](/stacks/metadata) component's configuration section.
+and [`metadata`](/stacks/components/component-metadata) component's configuration section.
 
 :::info
 The mechanics of mixins and inheritance apply only to the [Stack](/learn/stacks) configurations. Atmos knows nothing about the underlying

@@ -27,7 +27,7 @@ Helmfile components support the common configuration sections:
   <dt>[`settings`](/stacks/settings)</dt>
   <dd>Integrations and metadata.</dd>
 
-  <dt>[`metadata`](/stacks/metadata)</dt>
+  <dt>[`metadata`](/stacks/components/component-metadata)</dt>
   <dd>Component behavior and inheritance.</dd>
 
   <dt>[`command`](/stacks/command)</dt>

@@ -47,7 +47,7 @@ All component types support these configuration sections:
   <dt>[`settings`](/stacks/settings)</dt>
   <dd>Integrations and custom metadata.</dd>
 
-  <dt>[`metadata`](/stacks/metadata)</dt>
+  <dt>[`metadata`](/stacks/components/component-metadata)</dt>
   <dd>Component behavior and inheritance. See [Metadata Attributes](#metadata-attributes) below.</dd>
 
   <dt>[`command`](/stacks/command)</dt>

@@ -1,10 +1,10 @@
 ---
 title: Configure Component Metadata
-sidebar_position: 13
-sidebar_label: metadata
+sidebar_position: 5
+sidebar_label: "*.metadata"
 sidebar_class_name: command
 description: Use the metadata section to control component behavior, inheritance, and deployment settings.
-id: metadata
+id: component-metadata
 ---
 import File from '@site/src/components/File'
 import Intro from '@site/src/components/Intro'
@@ -135,6 +135,70 @@ When `locked: true`:
 - Atmos will warn or prevent changes to the component
 - Useful for protecting critical infrastructure components
 
+### `terraform_workspace`
+
+Overrides the Terraform workspace name with a literal string value:
+
+```yaml
+components:
+  terraform:
+    vpc:
+      metadata:
+        terraform_workspace: "custom-workspace-name"
+```
+
+By default, Atmos calculates workspace names automatically based on the stack name. Use this field when you need explicit control over the workspace name.
+
+For detailed information about how Atmos manages Terraform workspaces, see [Workspaces](/components/terraform/workspaces).
+
+### `terraform_workspace_pattern`
+
+Overrides the Terraform workspace name using a pattern with context tokens:
+
+```yaml
+components:
+  terraform:
+    vpc:
+      metadata:
+        terraform_workspace_pattern: "{tenant}-{environment}-{stage}"
+```
+
+Supported tokens:
+- `{namespace}` - The namespace from context variables
+- `{tenant}` - The tenant from context variables
+- `{environment}` - The environment from context variables
+- `{region}` - The region from context variables
+- `{stage}` - The stage from context variables
+- `{attributes}` - The attributes from context variables
+- `{component}` - The Atmos component name
+- `{base-component}` - The base component name (from `metadata.component`)
+
+For detailed information about workspace patterns and examples, see [Workspaces](/components/terraform/workspaces).
+
+### `custom`
+
+A user extension point for storing arbitrary metadata that Atmos preserves but does not interpret:
+
+```yaml
+components:
+  terraform:
+    vpc:
+      metadata:
+        custom:
+          owner: platform-team
+          cost_center: "12345"
+          tier: critical
+```
+
+Use `custom` for:
+- Storing metadata for external tooling to consume (CI/CD pipelines, dashboards)
+- Adding labels or annotations readable via `atmos describe stacks`
+- Custom categorization that doesn't affect Atmos behavior
+
+:::note
+Unlike `vars` and `settings`, the `custom` section is **not inherited** by derived components. Each component must define its own `custom` values.
+:::
+
 ## Examples
 
 ### Multiple Instances from One Module

@@ -27,7 +27,7 @@ Packer components support the common configuration sections:
   <dt>[`settings`](/stacks/settings)</dt>
   <dd>Integrations and metadata.</dd>
 
-  <dt>[`metadata`](/stacks/metadata)</dt>
+  <dt>[`metadata`](/stacks/components/component-metadata)</dt>
   <dd>Component behavior and inheritance.</dd>
 
   <dt>[`command`](/stacks/command)</dt>

@@ -27,7 +27,7 @@ Terraform components support all common sections plus Terraform-specific options
   <dt>[`settings`](/stacks/settings)</dt>
   <dd>Integrations and metadata.</dd>
 
-  <dt>[`metadata`](/stacks/metadata)</dt>
+  <dt>[`metadata`](/stacks/components/component-metadata)</dt>
   <dd>Component behavior and inheritance.</dd>
 
   <dt>[`command`](/stacks/command)</dt>

@@ -23,7 +23,7 @@ Stack manifests support various configuration sections at different scopes:
 | [vars](/stacks/vars) | Variables passed to components | Global, component-type, component |
 | [env](/stacks/env) | Environment variables | Global, component-type, component |
 | [settings](/stacks/settings) | Integrations and metadata | Global, component-type, component |
-| [metadata](/stacks/metadata) | Component behavior and inheritance | Component only |
+| [metadata](/stacks/components/component-metadata) | Component behavior and inheritance | Component only |
 | [hooks](/stacks/hooks) | Lifecycle event handlers | Global, component-type, component |
 | [command](/stacks/command) | Override default executable | Component-type, component |
 | [backend](/stacks/backend) | Terraform state storage | Component-type, component |