# terraform console. REPL для выражений HCL

_Workflow · TerraformLab Knowledge Base_

**TL;DR:** `terraform console`, интерактивная REPL: вводишь выражение HCL,
получаешь значение. Можно проверить функции (`upper("foo")`), типы
(`type(var.x)`), пощупать state (`aws_s3_bucket.demo.arn`). Не меняет
ничего, только читает.


## Что делает console

`terraform console`, это REPL (Read-Eval-Print Loop). Вы вводите
выражение, Terraform его вычисляет и печатает результат. Похоже на
`python` или `node` без флагов.

Это самый недооценённый инструмент Terraform, он бесплатный, не
меняет state, не ходит в облако (кроме чтения уже-зарефрешенных
данных), но экономит часы на дебаге.

## Базовое использование

```bash
cd ~/myproject
terraform console
```

Появится приглашение:
```
>
```

Вводите выражения:
```
> 1 + 2
3
> "hello, " + "world"
"hello, world"
> upper("terraform")
"TERRAFORM"
> length([1, 2, 3, 4])
4
```

Выйти, `exit` или Ctrl+D.

## Проверка переменных и locals

```
> var.region
"us-east-1"

> local.name_prefix
"linuxlab-dev-us-east-1"

> local.common_tags
tomap({
  "Env" = "dev"
  "ManagedBy" = "terraform"
  "Project" = "linuxlab-terraform-course"
})
```

Это **самый главный use case**. Когда `locals` собирается из 5
вложенных функций, глазами разобраться нельзя. В console, один
ввод, и видно реальное значение.

## Проверка типов

Функция `type()`, спецоператор, доступный только в console:

```
> type(var.region)
string

> type(var.tags)
map of string

> type([1, 2, 3])
tuple([number, number, number])

> type(toset(["a", "b"]))
set of string
```

Полезно когда не уверен, list ли это или tuple, map ли это или
object. См. [hcl-types](/terraform/kb/hcl-types.md) для разницы.

## Доступ к state

После `apply` все созданные ресурсы доступны в console:

```
> aws_s3_bucket.demo.arn
"arn:aws:s3:::linuxlab-hello-abc123"

> aws_s3_bucket.demo.tags
tomap({
  "Owner" = "student"
})

> [for b in aws_s3_bucket.many : b.id]
[
  "linuxlab-count-0-abc",
  "linuxlab-count-1-def",
]
```

Это безопасно, никаких изменений. Просто чтение state через те же
выражения, что в HCL.

## Тестирование функций

Перед тем как писать выражение в HCL, проверьте его в console:

```
> format("%s in region %s", upper("dev"), "us-east-1")
"DEV in region us-east-1"

> merge({a = 1, b = 2}, {b = 99, c = 3})
{
  "a" = 1
  "b" = 99
  "c" = 3
}

> [for x in [1, 2, 3, 4] : x * 2 if x > 2]
[
  6,
  8,
]
```

Это **намного быстрее**, чем «правлю HCL → запускаю plan → читаю
diff → понимаю что выражение не то». Console, это unit-тест для
одной строки.

## Не-интерактивный режим, echo

Иногда нужно в скрипте получить значение одного выражения:

```bash
echo 'type(var.tags)' | terraform console
echo 'aws_s3_bucket.demo.arn' | terraform console -no-color
```

Через stdin. Удобно для CI или для документации.

## Multi-line выражения

В REPL можно ввести несколько строк, обернув в скобки:

```
> {
  name = "myapp"
  tags = {
    Owner = "platform"
  }
}
{
  "name" = "myapp"
  "tags" = {
    "Owner" = "platform"
  }
}
```

Это удобно для тестирования сложных object-литералов.

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

- **Console требует валидный конфиг.** Если в HCL ошибка (битый
  синтаксис): console не стартует. Сначала `validate`.

- **Console читает текущий state.** Если state пустой (до apply). `aws_s3_bucket.demo.arn` упадёт с «resource not found». Это
  логично: ресурса ещё нет.

- **Console не делает refresh.** Значения берутся **из state-файла
  как он есть**. Если в облаке что-то поменялось снаружи, console
  этого не увидит. Чтобы обновить: `terraform refresh` (но он опасен,
  меняет state).

- **Sensitive значения маскируются.** Если output помечен
  `sensitive = true`, в console будет `(sensitive value)`. Чтобы
  увидеть, `nonsensitive()` функция.

- **Workspace имеет значение.** Console работает в **активном
  workspace**. Если переключился на staging, видишь staging-state.
  `terraform workspace show`, текущий.

- **Console не запускает provisioners.** Никаких `local-exec`,
  никаких внешних команд. Только чистые выражения.


## Команды

```bash
terraform console
```
Запустить интерактивную REPL. Ctrl+D или exit чтобы выйти.

```bash
echo 'type(var.tags)' | terraform console
```
Не-интерактивно: получить тип одной переменной. Полезно в скриптах.

```bash
echo 'length(aws_s3_bucket.many)' | terraform console
```
Посчитать сколько ресурсов создано через count или for_each. Без захода в state list.

```bash
terraform console -no-color
```
Без ANSI-цветов. Для скриптов и логов которые не парсят escape-коды.


## См. также

- [HCL: язык, на котором пишут Terraform](/terraform/kb/hcl-syntax.md)
- [Типы данных в HCL: string, number, list, map, object](/terraform/kb/hcl-types.md)
- [Строковые функции HCL: format, join, replace, lower и другие](/terraform/kb/tf-functions-string.md)
- [Функции коллекций HCL: length, lookup, merge, concat, flatten](/terraform/kb/tf-functions-collection.md)
- [Ссылки в HCL: как читать aws_s3_bucket.demo.bucket](/terraform/kb/tf-references.md)