Система плагинов

TerraCi использует систему плагинов на этапе компиляции по аналогии с database/sql в Go. Плагины регистрируются через init() и blank-импорты при сборке.

Встроенные плагины

Плагин	Назначение	Нужна конфигурация
git	Определение изменённых модулей через git diff	Нет
gitlab	Генерация GitLab CI пайплайнов и MR-комментарии	Да (наличие секции активирует)
github	Генерация GitHub Actions воркфлоу и PR-комментарии	Да (наличие секции активирует)
summary	Публикация сводных комментариев в MR/PR	Нет (включён по умолчанию)
cost	Оценка стоимости облачных ресурсов (AWS)	Да (providers.aws.enabled: true)
policy	Проверка политик через встроенный OPA	Да (enabled: true)
tfupdate	Разрешение зависимостей Terraform и синхронизация lock-файлов	Да (enabled: true)

Политики активации

Каждый плагин имеет политику активации, определяющую когда он участвует в текущем запуске.

Всегда активен

Плагин git не требует конфигурации. Он обеспечивает определение изменённых модулей для режима --changed-only и доступен всегда.

Активируется при наличии конфига

Плагины gitlab и github активируются при наличии соответствующей секции в extensions:. Удаление секции отключает плагин:

extensions:
  gitlab:      # наличие этой секции включает плагин
    image: { name: hashicorp/terraform:1.6 }

Активен по умолчанию

Плагин summary включён по умолчанию. Он публикует сводку планов в MR/PR. Можно отключить явно:

extensions:
  summary:
    enabled: false   # отключить

Требует явного включения

Плагины cost, policy и tfupdate требуют явной активации:

extensions:
  cost:
    providers:
      aws:
        enabled: true

  policy:
    enabled: true
    sources:
      - type: path
        path: policies

  tfupdate:
    enabled: true
    policy:
      bump: minor

Определение CI-провайдера

TerraCi автоматически определяет активный CI-провайдер:

1. TERRACI_PROVIDER -- явное указание:

   TERRACI_PROVIDER=gitlab terraci generate -o pipeline.yml

2. Переменные окружения -- GITLAB_CI=true выбирает GitLab, GITHUB_ACTIONS=true выбирает GitHub
3. Единственный активный провайдер -- если активен только один CI-провайдер, он используется автоматически

Если настроено несколько провайдеров и окружение не определено, TerraCi возвращает ошибку с рекомендацией задать TERRACI_PROVIDER.

Возможности плагинов

Плагины реализуют один или несколько интерфейсов-возможностей. Registry lifecycle facades владеют discovery; авторы плагинов только реализуют контракты интерфейсов:

Возможность	Назначение	Плагины
CommandProvider	CLI-субкоманды (terraci cost, terraci local-exec и т.д.)	cost, policy, summary, tfupdate, localexec
PipelineContributor	Добавление шагов/джобов в pipeline IR	cost, policy, summary, tfupdate
InitContributor	Поля формы для terraci init	gitlab, github, cost, policy, summary, tfupdate
PipelineGeneratorFactory	Создание provider-specific генератора из immutable pipeline IR (NewGenerator(*pipeline.IR))	gitlab, github
CommentServiceFactory	Создание сервиса MR/PR комментариев	gitlab, github
EnvDetector	Определение CI-окружения по переменным среды	gitlab, github
CIInfoProvider	Имя провайдера, ID пайплайна, SHA коммита	gitlab, github
ChangeDetectionProvider	SDK-возможность, встраивающая plugin-agnostic workflow.ChangeDetector для VCS diff	git
Preflightable	Дешёвая валидация при старте	gitlab, github, git, cost, policy, tfupdate
VersionProvider	Информация о версии для terraci version	policy
KVCacheProvider	KV-кэш бэкенд по имени	inmemcache
BlobStoreProvider	Бэкенд blob/object store (NewBlobStore(ctx, appCtx, opts))	diskblob

Один плагин может реализовывать несколько возможностей. Например, cost реализует CommandProvider (команда terraci cost), PipelineContributor (шаг оценки стоимости в пайплайне), InitContributor (переключатель в мастере init) и Preflightable (валидация конфига); estimator runtime строится лениво внутри самого плагина.

Жизненный цикл плагина

Каждый плагин проходит одинаковый жизненный цикл:

1. Register    -- init() регистрирует плагин через registry.RegisterFactory()
2. Configure   -- фреймворк декодирует секцию extensions.<key> из YAML
3. Preflight   -- дешёвая валидация (определение окружения, проверка конфига)
4. Bind        -- runflow строит immutable Prepared/AppContext state
5. Execute     -- команды лениво создают plugin-local typed рантаймы по необходимости

Preflight выполняется для всех включённых плагинов до любой команды. Он должен быть быстрым и без побочных эффектов — никаких сетевых вызовов и тяжёлого state. Тяжёлая работа (API-клиенты, кеши, estimators) принадлежит plugin-local runtime builders, которые запускаются только когда команда реально требует runtime.

Кастомные плагины

Сборка через xterraci

xterraci создаёт кастомный бинарник TerraCi с дополнительными или исключёнными плагинами:

# Добавить внешний плагин
xterraci build --with github.com/your-org/terraci-plugin-slack

# Закрепить конкретную версию
xterraci build --with github.com/your-org/terraci-plugin-slack@v1.2.0

# Использовать локальный плагин во время разработки
xterraci build --with github.com/your-org/plugin=../my-plugin

# Убрать ненужные встроенные плагины
xterraci build --without cost --without policy

# Комбинировать
xterraci build \
  --with github.com/your-org/terraci-plugin-slack \
  --without cost \
  --output ./build/terraci-custom

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

xterraci build:

1. Создаёт временный Go-модуль
2. Генерирует main.go с blank-импортами выбранных плагинов
3. Выполняет go get для каждого внешнего плагина
4. Собирает бинарник через go build

Результат идентичен стандартному terraci, но с другим набором скомпилированных плагинов.

Список встроенных плагинов

xterraci list-plugins

Написание плагина

Минимальный внешний плагин:

1. Регистрация -- функция init(), вызывающая registry.RegisterFactory():

package myplugin

import (
    "github.com/edelwud/terraci/pkg/plugin"
    "github.com/edelwud/terraci/pkg/plugin/registry"
)

func init() {
    registry.RegisterFactory(func() plugin.Plugin {
        return &Plugin{
            BasePlugin: plugin.BasePlugin[*Config]{
                PluginName: "myplugin",
                PluginDesc: "My custom plugin",
                EnableMode: plugin.EnabledExplicitly,
                DefaultCfg: func() *Config { return &Config{} },
                IsEnabledFn: func(cfg *Config) bool {
                    return cfg != nil && cfg.Enabled
                },
            },
        }
    })
}

type Plugin struct {
    plugin.BasePlugin[*Config]
}

type Config struct {
    Enabled bool   `yaml:"enabled"`
    APIKey  string `yaml:"api_key"`
}

func (c *Config) Clone() *Config {
    if c == nil {
        return nil
    }
    out := *c
    return &out
}

2. Возможности -- реализуйте нужные интерфейсы:

// CommandProvider -- добавляет команду `terraci myplugin`
func (p *Plugin) Commands() []*cobra.Command {
    return []*cobra.Command{{
        Use:   "myplugin",
        Short: "Run my custom plugin",
        RunE: func(cmd *cobra.Command, _ []string) error {
            // логика плагина
            return nil
        },
    }}
}

3. Go-модуль -- опубликуйте как Go-модуль с go.mod, зависящим от github.com/edelwud/terraci.

Конвенция файлов плагина

Для крупных плагинов используйте конвенцию «один файл на возможность»:

Файл	Содержимое
plugin.go	init(), struct плагина, BasePlugin embedding
lifecycle.go	Реализация Preflightable
commands.go	CommandProvider с cobra-командами
runtime.go	Plugin-local builder для ленивого тяжёлого state
usecases.go	Оркестрация команд над типизированным рантаймом
pipeline.go	PipelineContributor — шаги/джобы
init_wizard.go	InitContributor — поля формы
output.go	Хелперы рендеринга CLI
report.go	Сборка CI-отчётов

Рабочий пример

Смотрите examples/external-plugin для полного рабочего примера плагина, добавляющего команду terraci hello.

Справочник конфигурации

Плагин	Страница конфигурации
GitLab CI	config/gitlab
GitHub Actions	config/github
Summary-комментарии	config/summary
Оценка стоимости	config/cost
Проверка политик	config/policy
Обновление зависимостей	config/tfupdate