# Конфигурация Terraform CLI: terraformrc, env vars, TF_LOG

_Основы Terraform · TerraformLab Knowledge Base_

**TL;DR:** Поведение Terraform CLI настраивается через файл ~/.terraformrc и
переменные окружения TF_*. Здесь, кеш плагинов, TF_LOG для дебага,
TF_VAR_* для переменных, TF_CLI_ARGS для глобальных флагов.


## Где Terraform читает настройки

Поведение CLI настраивается в двух местах:

1. **Файл `~/.terraformrc`** (Linux/macOS) или `%APPDATA%\terraform.rc`
   (Windows). HCL-формат. Читается один раз при запуске любой
   команды.
2. **Переменные окружения `TF_*`.** Читаются при каждом запуске
   terraform. Имеют приоритет над `terraformrc` там, где значения
   пересекаются.

Эти файлы, про CLI, не про конфигурацию проекта. В них нет ресурсов
и нет state. Это «как мне удобно работать с terraform», а не «что
terraform создаёт».

## `~/.terraformrc`, что туда обычно кладут

```hcl
plugin_cache_dir   = "$HOME/.terraform.d/plugin-cache"
disable_checkpoint = true

credentials "app.terraform.io" {
  token = "..."
}
```

- `plugin_cache_dir`, общая папка для скачанных плагинов на все
  проекты. Без неё каждый `terraform init` скачивает провайдеры
  заново в локальную `.terraform/`, и у тебя дублируются гигабайты.
  С кешем `init` для нового проекта занимает секунды.
- `disable_checkpoint = true` отключает фоновую проверку «есть ли
  новая версия Terraform». Не критично, но в офлайн-сетях избавляет
  от шума.
- `credentials`, токен для приватных registry (Terraform Cloud,
  Spacelift). В учебном курсе обычно не нужно.

Папку под `plugin_cache_dir` нужно создать самому: `mkdir -p
~/.terraform.d/plugin-cache`.

## Переменные окружения

### Управление выводом и поведением

- **`TF_LOG`**, уровень логирования. Значения: `TRACE`, `DEBUG`,
  `INFO`, `WARN`, `ERROR`. При `DEBUG` видны все HTTP-вызовы к
  провайдеру. Главный инструмент дебага, когда `apply` падает с
  непонятной ошибкой:
  ```bash
  TF_LOG=DEBUG terraform apply 2> debug.log
  ```
- **`TF_LOG_PATH`**, куда писать лог. Если не задан, лог идёт в
  stderr.
- **`TF_INPUT=0`**, отключить интерактивные вопросы (для CI).
- **`TF_IN_AUTOMATION=true`**, сообщает terraform, что он в
  pipeline. Сокращает вывод и убирает подсказки про следующие шаги.

### Передача переменных в HCL

- **`TF_VAR_имя`**, задать значение переменной `variable "имя"` из
  HCL. Пример:
  ```bash
  export TF_VAR_bucket_name="my-bucket-from-env"
  terraform plan
  ```
- **`TF_CLI_ARGS`**, добавить флаги к любой команде. Пример: чтобы
  всегда передавать `-input=false` в любой запуск, не дописывая в
  каждом вызове:
  ```bash
  export TF_CLI_ARGS="-input=false"
  ```
- **`TF_CLI_ARGS_plan`**, `TF_CLI_ARGS_apply` и т.д. То же самое,
  но только для конкретной команды.

### Управление кешем и backend

- **`TF_DATA_DIR`**, где терраформ создаёт `.terraform/`. По
  умолчанию, рядом с `.tf`-файлами; можно вынести в `/tmp/`, если
  проект на read-only ФС.
- **`TF_CLI_CONFIG_FILE`**, путь к альтернативному
  `terraformrc`-файлу. Полезно, если в CI нужен один файл
  конфигурации, а локально, другой.

## TF_LOG, как пользоваться

Самый ходовой сценарий: `terraform apply` падает с
«`Error: failed to get versions...`» без подробностей. Запускаешь
то же самое с DEBUG:

```bash
TF_LOG=DEBUG TF_LOG_PATH=./tf.log terraform apply
```

В `tf.log` будет полный HTTP-разговор: на какой URL пошёл, какой
ответ получил, на каком этапе провайдер сломался. Часто видно, что
упёрся в прокси, упёрся в DNS или получил 429 от регистра.

Уровни:

| Уровень | Когда использовать |
|---------|--------------------|
| `ERROR` | только ошибки. Дефолт без флага. |
| `WARN`  | + warnings (deprecated, retries). |
| `INFO`  | + базовые шаги (init, plan, apply фазы). |
| `DEBUG` | + HTTP-вызовы. Самый полезный для повседневной отладки. |
| `TRACE` | + внутренности (раскрытие graph, parsing). Многословный, нужен редко. |

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

- **`TF_VAR_имя` чувствителен к регистру.** `TF_VAR_Region`
  подставится в переменную `Region`, а не `region`. Лучше держать
  имена переменных строчными.
- **`TF_CLI_ARGS` склеивается с реальными флагами.** Если в env
  стоит `TF_CLI_ARGS="-no-color"`, и ты запускаешь
  `terraform plan -no-color`, провайдер увидит два `-no-color`, это
  обычно безвредно, но при дубликате значимых флагов поведение
  непредсказуемо.
- **`plugin_cache_dir` не лочит версии.** Кеш просто избавляет от
  скачивания. Версии всё равно фиксирует [[tf-lockfile|lockfile]].
- **TF_LOG может вывести секреты.** В DEBUG-логе видны заголовки и
  тела HTTP-запросов. Не публикуй сырой лог в issue, фильтруй
  `Authorization`, `*_token`, `*_key`.
- **`~/.terraformrc` и проектная `provider`-конфигурация, про
  разное.** В terraformrc нет регионов и не указываются ресурсы;
  регион ставится в [[tf-provider-block|блок provider]].


## Команды

```bash
TF_LOG=DEBUG terraform apply 2> tf-debug.log
```
Запустить apply с детальным логом в файл. Самый частый дебаг-приём.

```bash
export TF_VAR_region=eu-central-1 && terraform plan
```
Передать переменную через env. Удобно для CI и одноразовых запусков, не загромождая -var-flags.

```bash
mkdir -p ~/.terraform.d/plugin-cache
```
Создать папку под общий кеш плагинов перед тем, как прописать `plugin_cache_dir` в terraformrc.

```bash
terraform -version
```
Показывает версию terraform и список текущих провайдеров. Первое, что просят в любом issue.


## См. также

- [terraform init: первая команда в любом проекте](/terraform/kb/tf-init.md)
- [.terraform.lock.hcl: фиксация версий провайдеров](/terraform/kb/tf-lockfile.md)
- [Backend в Terraform: где живёт state](/terraform/kb/tf-init-backends.md)
- [Version constraints в Terraform: required_version и провайдеры](/terraform/kb/tf-version-constraints.md)