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"

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.

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).

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 components from OCI registries.

To specify a repository in an OCI registry, use the oci://<registry>/<repository>:tag scheme.

Components from OCI repositories are downloaded as Docker image tarballs, then all the layers are processed, un-tarred and un-compressed, and the component's source files are written into the component's directory.

For example, to vendor the vpc component from the public.ecr.aws/cloudposse/components/terraform/stable/aws/vpc AWS public ECR registry, use the following uri:

uri: "oci://public.ecr.aws/cloudposse/components/terraform/stable/aws/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:
    uri: "oci://public.ecr.aws/cloudposse/components/terraform/stable/aws/vpc:{{.Version}}"
    version: "latest"
    included_paths:
      - "**/*.*"