# !version

Use `!version` to read a locked version from the active Atmos version track.

The `!version` YAML function resolves a name from `versions.lock.yaml`. It uses the stack's asserted `version.track`, then `version.track` from `atmos.yaml`, then `default`.

`!version` is a stack-manifest function — it only resolves inside stack configuration files (`stacks/**`), not in `atmos.yaml` itself. `atmos.yaml` is only consulted as a _source_ for `version.track`; it isn't processed by the same YAML-function evaluator, so `!version` there fails with an unsupported-tag error.

## Usage

```yaml
!version <name>
```

## Example

Use `!version` in a stack manifest when the whole value is the version:

### Terraform

```yaml
version:
  track: prod

components:
  terraform:
    datadog-forwarder:
      dependencies:
        tools:
          opentofu: !version opentofu
      vars:
        image:
          tag: !version dd_forwarder
```

With this lock file:

```yaml
version: 1
tracks:
  prod:
    opentofu:
      version: 1.10.6
    dd_forwarder:
      version: 5.4.5
```

Atmos resolves:

```yaml
dependencies:
  tools:
    opentofu: 1.10.6
vars:
  image:
    tag: 5.4.5
```

### Helm

`components.helm.<name>.version` is a top-level field, so a Helm chart version resolves the same way:

```yaml
version:
  track: prod

components:
  helm:
    monitoring:
      chart: prometheus-community/kube-prometheus-stack
      version: !version prometheus_chart
```

With this lock file:

```yaml
version: 1
tracks:
  prod:
    prometheus_chart:
      version: 65.1.1
```

Atmos resolves:

```yaml
version: "65.1.1"
```

## Embedded Strings

Use `{{ .version.name }}` when the version is part of a larger string:

### Terraform

```yaml
vars:
  image:
    uri: "public.ecr.aws/datadog/lambda-extension:{{ .version.dd_forwarder }}"
```

### Container

Container components use a first-class `image` field (not nested under `vars`), and it holds the full `repo:tag` reference, so the version is embedded rather than assigned with `!version`:

```yaml
components:
  container:
    api:
      image: "localhost:5001/api:{{ .version.api_image }}"
```

Use `!version` when the whole value in a stack manifest is the version. Use `{{ .version.name }}` when the version is part of a larger string.

## Pinned Entries

For entries with `pin: digest` (alias: `sha`) in their [update policy](/cli/configuration/version/managed-versions#update-policy), the two surfaces behave differently:

- **`!version name` always returns the version** (for example, `v6.1.0`) — never the digest.
- **`{{ .version.name }}`** emits the pinned form: the digest for pinned entries, the version otherwise. This is what rendered files and file managers embed.
- **`{{ .version.name.Version }}`** and **`{{ .version.name.Digest }}`** are individually addressable when you need one specific form:

```yaml
vars:
  image:
    uri: "ghcr.io/example/app@{{ .version.app.Digest }}"
    tag: "{{ .version.app.Version }}"
```

## See Also

- [Managed Versions Configuration](/cli/configuration/version/managed-versions)
- [`atmos version track`](/cli/commands/version/track)