# .tfvars: файлы со значениями переменных

_Переменные и outputs · TerraformLab Knowledge Base_

**TL;DR:** .tfvars, файлы со значениями переменных (HCL или JSON): terraform.tfvars и *.auto.tfvars читаются автоматически, остальные через -var-file. Главный механизм разделения «код vs конфигурация окружения».

## Формат .tfvars-файла

Это просто HCL без блоков, пары `имя_переменной = значение`:

```hcl
# prod.tfvars
env             = "prod"
region          = "us-east-1"
instance_count  = 3
enable_logging  = true

tags = {
  Project     = "my-app"
  Environment = "prod"
  ManagedBy   = "terraform"
}

azs = ["us-east-1a", "us-east-1b", "us-east-1c"]
```

Никаких `variable {}` блоков, только присваивания. Если переменной с таким именем нет в HCL, `apply` упадёт с ошибкой `undeclared variable`.

## .tfvars.json, то же в JSON

Если файлы генерируются другой программой (Jenkins, шаблонизатор), удобнее JSON:

```json
{
  "env": "prod",
  "region": "us-east-1",
  "instance_count": 3,
  "tags": {
    "Project": "my-app",
    "Environment": "prod"
  }
}
```

Имя должно заканчиваться `.tfvars.json`, не просто `.json`.

## Что автоматически подгружается

Эти файлы Terraform читает без флагов, просто потому что они лежат в корне проекта:

- `terraform.tfvars`
- `terraform.tfvars.json`
- `*.auto.tfvars` (любое имя с этим суффиксом)
- `*.auto.tfvars.json`

Порядок чтения и приоритеты, в [tf-variable-sources](/terraform/kb/tf-variable-sources.md).

## -var-file для конкретного окружения

В CI/CD обычно держат отдельные файлы:

```
envs/
  dev.tfvars
  staging.tfvars
  prod.tfvars
main.tf
```

Запускают так:

```bash
terraform plan  -var-file=envs/prod.tfvars
terraform apply -var-file=envs/prod.tfvars
```

Эти файлы **не** подгружаются автоматически (нет суффикса `auto`). Только через `-var-file`.

Можно несколько раз:

```bash
terraform plan -var-file=envs/base.tfvars -var-file=envs/prod.tfvars
```

Последний выигрывает при коллизии. Это удобный паттерн: base-значения общие, окружение их перекрывает.

## Структуры в .tfvars

HCL-формат позволяет вкладывать сложные типы:

```hcl
# databases.tfvars
databases = {
  primary = {
    engine            = "postgres"
    instance_class    = "db.t3.medium"
    allocated_storage = 100
  }
  analytics = {
    engine            = "postgres"
    instance_class    = "db.t3.small"
    allocated_storage = 200
  }
}
```

HCL прощает trailing-запятые и переводы строк, формат человеко-читаемый.

## Подводные камни

- **terraform.tfvars часто в .gitignore.** Это локальные значения разработчика, потенциально с секретами. Стандартный подход:

  ```gitignore
  terraform.tfvars
  *.auto.tfvars
  !envs/*.tfvars
  ```

  Окружения в `envs/`, коммитим (без секретов), `terraform.tfvars` и autо, игнорируем.

- **`*.auto.tfvars` грузятся ВСЕ.** Если в репо есть `dev.auto.tfvars` и `prod.auto.tfvars`, оба прочитаются автоматически, и последний по алфавиту перебьёт первый. Это **частая ловушка** в работе с окружениями. Используйте `-var-file` если хотите контроль.

- **Алфавит, это `a-z`, не приоритет.** `prod.auto.tfvars` придёт **после** `dev.auto.tfvars` (буква d < p в ASCII), но **до** `qa.auto.tfvars`. Это никак не связано с «важностью».

- **.tfvars не имеет переменных.** Внутри нельзя писать `env = var.something`. Только литеральные значения и сложные структуры.

- **JSON и HCL не смешиваются в одном файле.** Либо `.tfvars`, либо `.tfvars.json`. Но в одной директории могут быть оба формата. Terraform читает их по очереди.

- **`-var-file` не падает на отсутствующий файл.** Если в CI забыли передать файл. Terraform запросит значения интерактивно (или упадёт с `-input=false`). Поэтому обязательно `-input=false` в CI.

- **`.tfvars` не место для секретов в open-source проектах.** Даже если в .gitignore, могут случайно закоммитить, может утечь через CI-логи. Реальные секреты, в env (`TF_VAR_*`) или в secrets-manager.


## Команды

```bash
terraform plan -var-file=envs/prod.tfvars
```
Загрузить значения для конкретного окружения.

```bash
terraform plan -var-file=base.tfvars -var-file=overrides.tfvars
```
Несколько файлов: последний перебивает первый при коллизии.

```bash
ls *.tfvars *.auto.tfvars 2>/dev/null
```
Проверить, какие файлы Terraform подхватит автоматически в текущей директории.

```bash
terraform validate
```
Если в .tfvars есть значение для несуществующей переменной: validate ругнётся.


## См. также

- [Блок variable: вход в конфигурацию](/terraform/kb/tf-variable.md)
- [Откуда Terraform берёт значения переменных](/terraform/kb/tf-variable-sources.md)