Skip to main content

Using Custom Component Types

Beyond the native component types, Atmos lets you define custom component types so you can manage any tool—AWS CDK, Pulumi, Bicep, database migrations, and more—with the same stack-based configuration system used for Terraform, Helmfile, and Packer.

CloudFormation components

Use the built-in CloudFormation component and CloudFormation commands to deploy templates. The component type is currently experimental.

Custom component types are defined through custom commands. Unlike the native types, which ship with built-in orchestration, a custom type is one you wire up yourself: you declare the type on a custom command and supply the execution steps, while Atmos handles stack resolution, inheritance, and configuration merging exactly as it does for native components.

How It Works​

Define a component.type on a custom command and tell Atmos which argument provides the component name and which provides the stack name. Atmos then looks up components.<type>.<name> from your stack manifests and exposes the fully resolved configuration via {{ .Component.* }}.

# atmos.yaml
commands:
  - name: example
    description: "Run example components"
    arguments:
      - name: component
        provides: component      # Provides the component name
        required: true
    flags:
      - name: stack
        shorthand: s
        provides: stack           # Provides the stack name
        required: true
    component:
      type: example               # Your custom component type
    steps:
      - 'echo "App: {{ .Component.vars.app_name }}"'
      - 'echo "Version: {{ .Component.vars.version }}"'

Configure the component in stack manifests just like a native type—with full imports and inheritance:

# stacks/deploy/dev.yaml
components:
  example:                        # Matches component.type
    deploy-app:
      vars:
        app_name: "myapp"
        version: "1.0.0"

Run it:

atmos example deploy-app --stack dev
# App: myapp
# Version: 1.0.0

Global vars, settings, and env are merged automatically, and a component's env section is exported as real environment variables—making it straightforward to pass secrets securely.

Implement components with Starlark​

Use Atmos scripting, based on Starlark, to implement custom components with validation, conditions, loops, and reusable functions. The interpreter ships with Atmos. Replace the command's shell steps with a type: script step:

    steps:
      - type: script
        interpreter: starlark
        script: |
          component = ctx.component
          if not component.vars.get("app_name"):
              fail("app_name is required")
          print("App: {}".format(component.vars["app_name"]))
          print("Version: {}".format(component.vars["version"]))

ctx.component provides the resolved component configuration. Use its exec() method to call tools from the component directory, and move shared logic into .star files with !include. Atmos supports tests for these functions and commands.

Here, example names the custom command and component type; script names the step type that runs the Starlark implementation.

Native vs. Custom​

AspectNative types (Terraform/Helmfile/Packer/Ansible)Custom types
OrchestrationBuilt into AtmosYou supply the steps
DefinitionAlways availableDefined via a custom command
Stack configurationcomponents.<type>.<name>components.<type>.<name>
Configuration accessNative flags/varfiles{{ .Component.* }} templates or ctx.component in Starlark

Try It​

Explore a complete, working example that defines a custom example component type and configures it through stacks.

custom-componentsView full example
atmos custom component command
00:00.0 / 00:00.0

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.
Browse all files

Related​