# terraform init: первая команда в любом проекте

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

**TL;DR:** terraform init скачивает плагины-провайдеры (AWS, GCP и т.д.), создаёт файл с зафиксированными версиями (lockfile) и подготавливает рабочую директорию. Без этого ни plan, ни apply не запустятся.

## Что делает `terraform init`

Когда вы пишете в файле `provider "aws" { ... }`, Terraform не умеет ходить в AWS сам по себе. Ему нужен **плагин-провайдер**, отдельная программа, которая знает, как разговаривать с AWS API.

`terraform init` делает три вещи:

1. Читает в вашем коде блок `required_providers` и смотрит, какие плагины нужны.
2. Скачивает их из реестра Terraform Registry в папку `.terraform/` рядом с вашим кодом.
3. Создаёт файл `.terraform.lock.hcl`, там зафиксированы точные версии скачанных плагинов и их хеши. См. [tf-lockfile](/terraform/kb/tf-lockfile.md).

После `init` директория готова к работе, можно запускать `plan` и `apply`.

## Когда запускать

`init` нужно запустить **первый раз** после `git clone` чужого репозитория или после создания нового проекта. Также повторно если:

- В коде поменялся `required_providers` (другой провайдер или другая версия).
- Добавился или сменился блок `backend` (где хранить state, см. [tf-init-backends](/terraform/kb/tf-init-backends.md)).
- Появился новый блок `module "..."`.

Если ничего из этого не менялось, повторно запускать `init` не нужно.

## Что появляется в директории

После первого `init`:

```
ваш-проект/
├── main.tf                      # ваш код
├── .terraform/                  # появилось после init
│   └── providers/
│       └── registry.terraform.io/
│           └── hashicorp/
│               └── aws/
│                   └── 5.60.0/
│                       └── linux_amd64/
│                           └── terraform-provider-aws_v5.60.0_x5
└── .terraform.lock.hcl          # тоже появилось
```

**Важно:**
- `.terraform/`, это кеш. Добавляйте в `.gitignore`, не коммитьте.
- `.terraform.lock.hcl`, наоборот, **обязательно коммитьте**. Это гарантия, что у коллег скачаются те же версии провайдеров.

## Полезные флаги

- `terraform init -upgrade`, обновить провайдеры до самых свежих **в рамках version constraint**. Если в коде написано `version = "~> 5.0"`, то `-upgrade` поднимет с 5.50 до 5.60, но не до 6.x.
- `terraform init -reconfigure`, переинициализировать с нуля. Нужен, когда вы поменяли настройки `backend` и Terraform спрашивает «мигрировать ли state».
- `terraform init -input=false`, не задавать интерактивных вопросов. Это режим для CI/CD.

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

- **Без интернета `init` не работает.** Плагины качаются с registry.terraform.io. В корпоративных сетях иногда настраивают зеркало через `terraform { provider_installation { ... } }` в `~/.terraformrc`, см. [tf-cli-config](/terraform/kb/tf-cli-config.md).
- **Корпоративный прокси.** Если ваш бэкенд в офисе и интернет только через прокси. Нужно переменные `HTTPS_PROXY` и `HTTP_PROXY` перед запуском.
- **Lockfile блокирует обновление.** Если `init` ругается «requested version is not the locked version», значит в lockfile стоит одна версия, а вы хотите другую. Решение, либо `init -upgrade`, либо явно поменяйте constraint.
- **Кеш в `.terraform/` зависит от ОС.** Если коллега работает на macOS, а вы на Linux, `.terraform/` нельзя просто перенести; каждый запускает `init` у себя.

## Что внутри `.terraform.lock.hcl`

Маленький файл, который выглядит примерно так:

```hcl
provider "registry.terraform.io/hashicorp/aws" {
  version     = "5.60.0"
  constraints = "~> 5.60"
  hashes = [
    "h1:abc123...",
    "h1:def456...",
  ]
}
```

Это гарантия воспроизводимости: следующий `init` поставит ровно версию 5.60.0 с ровно этими хешами. Если хеши не сошлись, `init` упадёт. Это защита от подменённых пакетов.


## Команды

```bash
terraform init
```
Базовая инициализация: скачать провайдеры, создать lockfile.

```bash
terraform init -upgrade
```
Обновить провайдеры в рамках version constraint.

```bash
terraform init -reconfigure
```
Переинициализация после смены backend: без миграции state.

```bash
TF_LOG=DEBUG terraform init
```
Если init подвисает или ругается: посмотреть подробный лог, что именно тянется и куда.


## См. также

- [HCL: язык, на котором пишут Terraform](/terraform/kb/hcl-syntax.md)
- [terraform plan: посмотреть, что Terraform собирается сделать](/terraform/kb/tf-plan.md)
- [.terraform.lock.hcl: фиксация версий провайдеров](/terraform/kb/tf-lockfile.md)
- [Version constraints в Terraform: required_version и провайдеры](/terraform/kb/tf-version-constraints.md)
- [Backend в Terraform: где живёт state](/terraform/kb/tf-init-backends.md)
- [AWS Provider: настройки и где Terraform берёт ключи](/terraform/kb/aws-provider.md)