Функции от провайдеров (provider-defined functions)

Provider-defined functions (функции, определяемые провайдером) — возможность Terraform 1.8, позволяющая провайдерам добавлять собственные функции в язык выражений HCL, помимо встроенных (length, jsonencode, cidrsubnet и т.д.). Раньше набор функций был жёстко зашит в ядро Terraform; теперь провайдер может поставлять доменные функции — например, разбор ARN у AWS-провайдера. Вызов идёт по неймспейсу: provider::<локальное-имя>::<функция>(аргументы), где <локальное-имя> — имя провайдера из блока required_providers. OpenTofu поддерживает провайдерные функции с тех же версий.

Как это работает

Функция вызывается через префикс provider:::

terraform {
  required_providers {
    aws = { source = "hashicorp/aws" }
  }
}

output "account_id" {
  value = provider::aws::arn_parse(var.role_arn).account_id
}

Функция доступна только если соответствующий провайдер объявлен в required_providers и установлен (terraform init) — в отличие от встроенных функций, которые есть всегда. Например, AWS-провайдер поставляет arn_parse, arn_build и trim_iam_role_path; другие провайдеры добавляют свои функции разбора, кодирования и валидации. Набор функций зависит от версии провайдера, поэтому доступность конкретной функции стоит сверять с его CHANGELOG. Документируются такие функции не в общей документации Terraform, а на странице конкретного провайдера в Terraform Registry. На стороне разработчика провайдера функции реализуются через Terraform Plugin Framework, который отвечает за схему аргументов, типы и обработку ошибок.

Важное ограничение: провайдерные функции — чистые вычисления. Они выполняются на этапе plan, детерминированы, не ходят в API облака и не имеют побочных эффектов. Для чтения внешних данных (существующих ресурсов, справочников, состояния) по-прежнему используются data sources — функция подходит только для преобразования и валидации уже известных значений.

Когда применять

• Когда нужна доменная логика провайдера в выражениях (разбор ARN, преобразование форматов, валидация), которой нет среди встроенных функций.
• Чтобы убрать самодельные regex/split-костыли, дублирующие то, что провайдер уже умеет делать корректно.

Для универсальных операций (строки, коллекции, кодирование) — по-прежнему встроенные функции: провайдерные нужны именно там, где логика специфична для конкретной платформы, сервиса или формата данных.

Типичные ошибки

• Забыть объявить провайдер в required_providers — вызов provider::... будет неизвестен Terraform.
• Считать провайдерные функции универсальными: они привязаны к наличию и версии провайдера, конфигурацию сложнее переносить между проектами.
• Искать их в общем списке функций Terraform — смотреть надо документацию конкретного провайдера.

Связанные понятия

• Выражения и функции
• Провайдеры
• Terraform Plugin Framework
• OpenTofu — open-source форк