# Source

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

## Schema

```yaml
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](https://github.com/hashicorp/go-getter).

  See [Vendor URL Syntax](/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).
  - https://en.wikipedia.org/wiki/Glob\_(programming)
  - https://github.com/bmatcuk/doublestar#patterns
- **`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.
  ```yaml
  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.
  ```yaml
  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

```yaml
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.
:::

```yaml title="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`](/cli/configuration/components)) 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.

```yaml
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](https://opencontainers.org). 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:

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

Full example:

```yaml
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

### demo-vendoring

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

```shell
atmos init examples/demo-vendoring
cd demo-vendoring
```

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

```shell
atmos vendor list
```

- [Installation guide](/install)
- [Explore the example](/examples/demo-vendoring)
- [Initialization and repository settings](/cli/commands/init#examples-and-source-directories)