Custom Components Example

This example demonstrates how to define custom component types in Atmos using custom commands.

Overview

Custom component types allow you to extend Atmos beyond the built-in component types. This example defines an example type and accesses its configuration from stack files via Go templates.

For implementation logic with conditions, loops, and reusable functions, use Atmos scripting (Starlark). A type: script step with interpreter: starlark reads the resolved configuration through ctx.component. See the Starlark custom-component walkthrough.

Structure

examples/custom-components/
├── atmos.yaml                           # Atmos configuration with custom command
├── components/
│   └── example/
│       └── deploy-app/
│           └── deploy.sh                # Example script (not executed)
└── stacks/
    ├── catalog/
    │   └── example/
    │       └── deploy-app.yaml          # Base component configuration
    └── deploy/
        └── dev.yaml                     # Stack with overrides

Usage

1. Inspect the custom component type configuration:

   atmos describe config --format=yaml --query .components.example
   

2. Run the custom command:

   cd examples/custom-components
   atmos example deploy-app --stack dev
   

3. Expected output:

   Component: deploy-app
   Stack: dev
   App: myapp
   Version: 1.0.0
   Replicas: 1
   Env: deploying v1.0.0 to us-east-1
   

How It Works

1. Custom Command Definition (atmos.yaml):

   • The example command defines a custom component type
   • Arguments and flags with provides: component and provides: stack identify which values to use
   • The component: section specifies the component type name

2. Stack Configuration (stacks/):

   • Components are defined under components.example.<name>
   • Standard Atmos inheritance and overrides work as expected

3. Template Access:

   • Steps can access component config via {{ .Component.* }}
   • All component sections are available: vars, settings, metadata, etc.

4. Environment Variables:

   • The component env section is exported as real environment variables to every step, just like the built-in terraform/helmfile/packer/ansible component types.
   • Steps (and scripts they invoke) read them directly as $APP_VERSION, $DEPLOY_REGION, etc.
   • For sensitive values, use !secret NAME in the env section so the value resolves from a secret backend and is masked in output — never inline a secret into the command string. See Passing secrets.