# Terraform Stacks, нативная multi-stack оркестрация

_Advanced · TerraformLab Knowledge Base_

**TL;DR:** Terraform Stacks, фича HCP Terraform (2024), частично закрывает то
что делал Terragrunt. Один stack = множество components, между ними
явные dependencies, deployment с разными inputs делает развёртывание
N сред из одной конфигурации. Сейчас Cloud-only (HCP Terraform),
open-source CLI, в работе. Кому нужно сегодня: либо HCP Terraform,
либо ждать, либо использовать Terragrunt.


## Что это и в каком виде доступно

Stacks, попытка HashiCorp сделать нативный multi-stack orchestrator,
закрыть нишу Terragrunt'а в самом Terraform. Анонс 2024, публичный
beta в 2025.

На момент написания: **HCP Terraform-only**. Open-source CLI с
поддержкой Stacks, в работе. Тех, кто на open-source Terraform
для них Terragrunt остаётся.

Если ты уже в HCP Terraform / Terraform Cloud, Stacks серьёзно
расссматривай для multi-env / multi-region setups.

## Концепции

| Термин | Что значит |
|---|---|
| **Component** | Один Terraform-модуль с своим state'ом. Building block. |
| **Stack** | Набор components с явными dependencies между ними. |
| **Deployment** | Inputs для components, разворачивающие конкретный env. |
| **Stack definition** | `*.tfstack.hcl` файл, описывающий components. |
| **Deployment file** | `*.tfdeploy.hcl` файл, описывающий deployments. |

## Минимальная структура

```
my-stack/
├── components.tfstack.hcl   # definition
├── deployments.tfdeploy.hcl # deployments
├── network/                  # component 1 (Terraform module)
│   └── main.tf
└── app/                      # component 2
    └── main.tf
```

`components.tfstack.hcl`:

```hcl
component "network" {
  source = "./network"

  inputs = {
    cidr_block = var.cidr_block
  }

  providers = {
    aws = provider.aws.this
  }
}

component "app" {
  source = "./app"

  inputs = {
    vpc_id    = component.network.vpc_id
    subnet_ids = component.network.subnet_ids
  }

  providers = {
    aws = provider.aws.this
  }
}

variable "cidr_block" {
  type = string
}

required_providers {
  aws = {
    source  = "hashicorp/aws"
    version = "~> 5.60"
  }
}

provider "aws" "this" {
  config {
    region = var.region
  }
}

variable "region" {
  type = string
}
```

`deployments.tfdeploy.hcl`:

```hcl
deployment "us_east_1_dev" {
  inputs = {
    cidr_block = "10.0.0.0/16"
    region     = "us-east-1"
  }
}

deployment "us_east_1_prod" {
  inputs = {
    cidr_block = "10.1.0.0/16"
    region     = "us-east-1"
  }
}

deployment "eu_west_1_prod" {
  inputs = {
    cidr_block = "10.2.0.0/16"
    region     = "eu-west-1"
  }
}
```

Три deployments из одной stack-definition. Каждая управляет своими
network+app, изолированные state'ы.

## Что важно

- **Components имеют свои state'ы.** Один component = один state.
  Между component'ами явные cross-stack deps через outputs.
- **Deployments, это «инстансы» stack'а.** Три deployments = три
  параллельные инфры.
- **Один config, N сред.** Нет copy-paste, нет шести `terragrunt.hcl`.
- **HCP оркестрирует apply.** Сам понимает граф deps между components,
  apply'ит в правильном порядке.

## Сравнение с Terragrunt

| | Stacks | Terragrunt |
|---|---|---|
| Где живёт | HCP Terraform (Cloud) | OSS, local или CI |
| HCL-диалект | новый (`.tfstack.hcl`, `.tfdeploy.hcl`) | свой (`.terragrunt.hcl`) |
| Cross-stack deps | через `component.X.output` | через `dependency` блок |
| Apply orchestration | HCP automatic | Terragrunt run-all |
| State | HCP-managed | любой backend |
| Cost | Платный HCP | Free OSS |
| Maturity | Beta-ish 2025 | Production proven |

Stacks потенциально cleaner. Terragrunt, есть сегодня и работает.

## Когда переезжать на Stacks

- **Уже на HCP Terraform.** Бесплатно интегрируется в workflow.
- **Многоокружения, многорегионы.** Это его use-case.
- **Команда не любит Terragrunt-DSL.** Stacks ближе к нативному HCL.

Когда **не** переезжать:

- На open-source Terraform, пока нет.
- Маленький проект, overkill.
- Используешь Terragrunt и не сломано, не чини.

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

- **Двоится HCL-стек.** `.tf` + `.tfstack.hcl` + `.tfdeploy.hcl`, три
  разных файла-типа для одного проекта. Reviewer и тулчейн должны
  знать оба.

- **HCP-lock-in.** Без HCP Stacks не запустишь. Перевозить обратно в
  open-source, refactor.

- **Изменения схемы.** Stacks ещё развиваются; синтаксис может
  меняться между релизами HCP.

- **CLI парность.** HCP-CLI команды для Stacks отличаются от обычного
  `terraform`. `tcli stack ...` и т.д. Команды учить заново.

- **Open-source CLI обещан, но дат нет.** Если planning на 6 месяцев
  вперёд, заложи риск, что в OSS не появится.

- **Не заменяет Terragrunt 1:1.** Например, Terragrunt-specific фичи
  (custom hooks, `before_hook`/`after_hook`) в Stacks нет, orchestration
  делает HCP.


## Команды

```bash
terraform stacks init
```
Bootstrap stack-проекта (HCP CLI).

```bash
terraform stacks plan -deployment us_east_1_dev
```
Plan на конкретный deployment.

```bash
terraform stacks apply -deployment us_east_1_prod
```
Apply, HCP orchestration.


## См. также

- [Terragrunt, DRY-обёртка над Terraform](/terraform/kb/tf-terragrunt.md)
- [Большой state, иерархия, blast-radius, naming](/terraform/kb/tf-large-scale-state.md)
- [CDKTF, Terraform на TypeScript/Python](/terraform/kb/tf-cdktf.md)