# Version Constraints

Version constraints allow you to specify required Atmos version ranges in your `atmos.yaml` configuration, ensuring consistent behavior across teams, CI/CD pipelines, and different environments.

## Overview

When your configuration relies on specific Atmos features or behaviors, version constraints ensure that:

- Team members use compatible Atmos versions
- CI/CD pipelines fail early if the wrong version is installed
- Newer configurations don't silently fail on older Atmos versions
- Breaking changes are caught before causing confusing errors

## Configuration

Add a `version.constraint` section to your `atmos.yaml`:

**File:** `atmos.yaml`

```yaml
version:
  constraint:
    require: ">=1.100.0"
    enforcement: "fatal"
    message: "Please upgrade Atmos to use this configuration."
```

- **`version.constraint.require`**

  A semver constraint string specifying the required Atmos version(s). Uses the same syntax as Terraform version constraints. Multiple constraints are comma-separated and combined with AND logic.
- **`version.constraint.enforcement`**

  Controls behavior when the constraint is not satisfied:
  - **`fatal` (default)**
    Exit immediately with error code 1
  - **`warn`**
    Show a warning but continue execution
  - **`silent`**
    Skip validation entirely (useful for debugging)
- **`version.constraint.message`**

  Optional custom message displayed when the constraint fails. Use this to provide team-specific upgrade instructions or context.

## Constraint Syntax

Version constraints use [hashicorp/go-version](https://github.com/hashicorp/go-version) syntax, which is the same as Terraform:

| Constraint | Meaning | Example |
|------------|---------|---------|
| `>=1.2.3` | Greater than or equal | `>=1.100.0` |
| `<=1.2.3` | Less than or equal | `<=1.200.0` |
| `>1.2.3` | Greater than (exclusive) | `>1.99.0` |
| `<1.2.3` | Less than (exclusive) | `<2.0.0` |
| `1.2.3` | Exact version | `1.200.0` |
| `!=1.2.3` | Not equal (exclude version) | `!=1.150.0` |
| `~>1.2` | Pessimistic (>=1.2.0, \<2.0.0) | `~>1.100` |
| `~>1.2.3` | Pessimistic (>=1.2.3, \<1.3.0) | `~>1.100.0` |
| Multiple | Comma-separated AND | `>=1.100.0, <2.0.0` |

### Pessimistic Constraint Operator

The pessimistic constraint operator `~>` allows only the rightmost version component to increment:

- `~>1.100` allows `1.100.0`, `1.150.0`, `1.200.0`, but not `2.0.0`
- `~>1.100.0` allows `1.100.0`, `1.100.1`, `1.100.9`, but not `1.101.0`

## Examples

### Minimum Version Requirement

Ensure users have at least version 1.100.0:

**File:** `atmos.yaml`

```yaml
version:
  constraint:
    require: ">=1.100.0"
```

### Version Range

Require a specific major version range:

**File:** `atmos.yaml`

```yaml
version:
  constraint:
    require: ">=1.100.0, <2.0.0"
    enforcement: "fatal"
    message: |
      This configuration requires Atmos 1.x.

      To upgrade: brew upgrade atmos
      Or download from: https://github.com/cloudposse/atmos/releases
```

### Exclude Problematic Version

Skip a version with known issues:

**File:** `atmos.yaml`

```yaml
version:
  constraint:
    require: ">=1.100.0, !=1.150.0, <2.0.0"
```

### Soft Requirement (Warning Only)

Warn about unsupported versions without blocking execution:

**File:** `atmos.yaml`

```yaml
version:
  constraint:
    require: ">=1.100.0, <1.150.0"
    enforcement: "warn"
    message: |
      You are using an untested Atmos version.
      This configuration is validated against Atmos 1.100.0-1.149.x.
      Proceed at your own risk.
```

### Combined with Version Checking

Use both version constraints and update checking:

**File:** `atmos.yaml`

```yaml
version:
  # Check for new releases periodically
  check:
    enabled: true
    frequency: "24h"

  # Require minimum version
  constraint:
    require: ">=1.100.0"
    enforcement: "fatal"
```

## Environment Variable Override

Override the enforcement level at runtime using `ATMOS_VERSION_ENFORCEMENT`:

```bash
# Downgrade to warning
ATMOS_VERSION_ENFORCEMENT=warn atmos terraform plan

# Disable validation entirely
ATMOS_VERSION_ENFORCEMENT=silent atmos terraform plan
```

**Precedence order:**

1. `ATMOS_VERSION_ENFORCEMENT` environment variable (highest)
2. `version.constraint.enforcement` in `atmos.yaml`
3. Default value `"fatal"` (lowest)

## Error Messages

### Fatal Constraint Violation

When enforcement is `fatal` and the constraint is not satisfied:

```shell
# Error

**Error:** version constraint not satisfied

## Explanation

This configuration requires Atmos version >=1.100.0, but you are running 1.50.0

## Hints

💡 Please upgrade: https://atmos.tools/install

## Context

• required=>=1.100.0 current=1.50.0
```

### Warning

When enforcement is `warn`:

```shell
⚠ Atmos version constraint not satisfied
  Required: >=1.100.0, <2.0.0
  Current:  2.0.0

This stack configuration is tested with Atmos 1.x.
```

### Invalid Constraint Syntax

Invalid constraint syntax is always a fatal error:

```shell
# Error

**Error:** invalid version constraint

## Hints

💡 Please use valid semver constraint syntax
💡 Reference: https://github.com/hashicorp/go-version

## Context

• constraint=invalid>>2.0
```

## Best Practices

1. **Start with minimum version** - Use `>=X.Y.Z` to ensure feature availability
2. **Add upper bound for stability** - Use `<X.0.0` to avoid unexpected breaking changes
3. **Use `warn` during migrations** - Soft-enforce constraints while teams upgrade
4. **Provide clear messages** - Include upgrade instructions specific to your organization
5. **Test in CI first** - Validate constraint behavior before enforcing on developers