Vendor Configuration

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 command is executed, usually in the root of the infrastructure repo

• In the directory pointed to by the base_path setting in the atmos.yaml CLI config file

After defining the vendor.yaml manifest, all the remote artifacts can be downloaded by running the following command:

atmos vendor pull

To vendor a particular component or other artifact, execute the following command:

atmos vendor pull -c <component>

To vendor components and artifacts tagged with specific tags, execute the following command:

atmos vendor pull --tags <tag1>,<tag2>

tip

Refer to atmos vendor pull CLI command for more details

Vendoring Manifest

To vendor remote artifacts, create a vendor.yaml file similar to the example below:

vendor.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.
    # See https://atmos.tools/vendor/url-syntax for complete URL syntax documentation.
    # In 'source' and 'targets', Golang templates are supported  https://pkg.go.dev/text/template.
    # Currently the fields '{{.Component}}' and '{{.Version}}' are supported.
    # 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-components/aws-vpc-flow-logs-bucket.git?ref={{.Version}}"
      version: "1.323.0"
      targets:
        - "components/terraform/infra/{{.Component}}/{{.Version}}"
      excluded_paths:
        - "**/*.yaml"
        - "**/*.yml"
      tags:
        - test
        - storage

With this configuration, it would be possible to run the following commands:

# atmos vendor pull
# atmos vendor pull --everything
# atmos vendor pull --component vpc-mixin-1
# atmos vendor pull -c vpc-mixin-2
# atmos vendor pull --tags test
# atmos vendor pull --tags networking,storage

Configuration Reference

The vendor.yaml vendoring manifest supports Kubernetes-style YAML config. The file is placed into the directory from which the atmos vendor pull command is executed (usually the root of the repo).

apiVersion

Always set to atmos/v1.

kind

Always set to AtmosVendorConfig.

metadata

Optional metadata about the vendor configuration.

• name: A name for this vendor configuration
• description: A description of what this configuration vendors

spec.sources

List of sources to vendor. Each source defines a component, its source location, version, and target paths. See Sources for complete documentation.

spec.imports

List of additional vendor manifests to import. Supports hierarchical imports at many levels. See Imports for complete documentation.