Skip to main content

Source

The source key in component.yaml defines where to download the component from and how to filter the files.

Schema​

spec:
source:
uri: github.com/cloudposse/terraform-aws-components.git//modules/vpc?ref={{.Version}}
version: 1.398.0
included_paths:
- "**/*.tf"
- "**/*.tfvars"
- "**/*.md"
excluded_paths:
- "**/context.tf"
identity: source-reader

Attributes​

uri

Source uri supports the following protocols: OCI (https://opencontainers.org), Git, Mercurial, HTTP, HTTPS, Amazon S3, Google GCP, and all URL and archive formats as described in go-getter.

See Vendor URL Syntax for complete URL syntax documentation.

In uri, Golang templates are supported. If version is provided, {{.Version}} will be replaced with the version value before pulling the files from uri.

To vendor a module from a Git repo, use the following format:

github.com/cloudposse/terraform-aws-ec2-instance.git//modules/name?ref={{.Version}}
version

The version of the component to vendor. This value is substituted into {{.Version}} placeholders in the uri.

identity

The name of an Atmos Auth identity used to fetch the source and its mixins. It overrides vendor.identity in atmos.yaml, and the --identity flag of atmos vendor pull overrides both. The identity's environment is applied only to the git commands that fetch this component. See identity in vendor.yaml for the details and limits.

included_paths

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/globstar ** is supported).

excluded_paths

Exclude the files that match any of the excluded_paths patterns.

excluded_paths support POSIX-style Globs for file names/paths (double-star/globstar ** is supported).

retry

Optional retry configuration for handling transient network errors during download operations. This is useful for unreliable networks or when hitting rate limits.

retry:
max_attempts: 5
initial_delay: 2s
max_delay: 60s
backoff_strategy: exponential
multiplier: 2.0
random_jitter: 0.1
max_elapsed_time: 5m
max_attempts
Maximum number of retry attempts. Default: 3
initial_delay
Initial delay before the first retry. Default: 2s
max_delay
Maximum delay between retries. Default: 30s
backoff_strategy
Strategy for increasing delay between retries. Values: exponential, linear, constant. Default: exponential
multiplier
Multiplier for exponential backoff. Default: 2.0
random_jitter
Random jitter factor (0.0-1.0) to add randomness to delays. Default: 0.1
max_elapsed_time
Maximum total time for all retry attempts. Default: 5m
constraints

Optional. Controls which upstream versions atmos vendor update may select for this component, mirroring the constraints key supported on vendor.yaml sources. See Version constraints for the full version / excluded_versions / no_prereleases schema.

spec:
source:
uri: github.com/cloudposse/terraform-aws-vpc?ref={{.Version}}
version: 1.2.3
constraints:
version: "^1.0.0"

Vendoring Components from a Monorepo​

apiVersion: atmos/v1
kind: ComponentVendorConfig
metadata:
name: vpc-flow-logs-bucket-vendor-config
description: Source and mixins config for vendoring of 'vpc-flow-logs-bucket' component
spec:
source:
uri: github.com/cloudposse/terraform-aws-components.git//modules/vpc-flow-logs-bucket?ref={{.Version}}
version: 1.398.0
included_paths:
- "**/*.tf"
- "**/*.tfvars"
- "**/*.md"
excluded_paths:
- "**/context.tf"
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.

component.yaml
spec:
source:
uri: github.com/cloudposse/terraform-aws-components.git//modules/vpc-flow-logs-bucket?ref={{.Version}}
version: 1.398.0
included_paths:
- "**/**"
# If the component's folder has the `modules` sub-folder, it needs to be explicitly defined
- "**/modules/**"

Vendoring Modules as Components​

Any terraform module can also be used as a component, provided that Atmos backend generation (auto_generate_backend_file is true) is enabled. Use this strategy when you want to use the module directly, without needing to wrap it in a component to add additional functionality. This is essentially treating a terraform child module as a root module.

To vendor a module as a component, simply create a component.yaml file stored inside the components/_type_/_name_/ folder (e.g. components/terraform/ec2-instance/component.yaml).

Note the usage of the /// in the uri, which is to vendor from the root of the remote repository.

apiVersion: atmos/v1
kind: ComponentVendorConfig
metadata:
name: ec2-instance
description: Source for vendoring of 'ec2-instance' module as a component
spec:
source:
# To vendor a module from a Git repo, use the following format: 'github.com/cloudposse/terraform-aws-ec2-instance.git///?ref={{.Version}}
uri: github.com/cloudposse/terraform-aws-ec2-instance.git///?ref={{.Version}}
version: 0.47.1
included_paths:
- "**/*.tf"
- "**/*.tfvars"
- "**/*.md"

Vendoring from OCI Registries​

Atmos supports vendoring files from any OCI image in an OCI registry. No Atmos-specific image format, repository layout, or publisher is required.

Use the oci://<registry>/<repository>:<tag> scheme. Atmos extracts image layers and copies the selected files into the component directory. Choose an image containing the files your component needs.

The following image reference is an example; replace it with an existing image:

# Example image reference: replace with the OCI image containing the files you need.
uri: "oci://registry.example.com/team/vpc:latest"

Full example:

apiVersion: atmos/v1
kind: ComponentVendorConfig
metadata:
name: stable/aws/vpc
description: Config for vendoring of the 'stable/aws/vpc' component
spec:
source:
# Example image reference: replace with the OCI image containing the files you need.
uri: "oci://registry.example.com/team/vpc:{{.Version}}"
version: "latest"
included_paths:
- "**/*.*"

Try it out​

Copy the example into a new directory and make it your own:

atmos init examples/demo-vendoring
cd demo-vendoring

Inspect the configured sources before downloading components. Pulling sources requires network access.

atmos vendor list