vpc-cni, kube-proxy, coredns, aws-ebs-csi-driver), а также роли IAM, ключи KMS и теги; existing-eks устанавливает только те дополнения, которые перечислены в install_addons. Затем, если целевой платформой является Helm, команда clicklink clctl init устанавливает платформенный слой на основе выходных значений и bundle платформы: Karpenter, контроллер AWS Load Balancer, класс хранилища и компоненты с закреплёнными версиями (см. раздел Инициализация коннектора из выходных значений Terraform). Для корневых модулей требуется Terraform 1.10+ или OpenTofu 1.12+, а также провайдер AWS ~> 6.0. Во всех командах на этой странице вместо terraform можно использовать tofu.
Перед началом работы
Вам потребуется:- Terraform 1.10+ или OpenTofu 1.12+, а также провайдер AWS
~> 6.0. - Учётная запись AWS с правами на создание и изменение ресурсов, необходимых для выбранного корневого модуля.
curl, инструмент для вычисления SHA-256 (sha256sumилиshasum) иcosignдля загрузки и проверки архива релиза.- Данные, полученные на этапе регистрации: значение
chart_repository_arn, обязательное для каждого корневого модуля, а также конечная точка коннектора, токен регистрации и bundle платформы, которые понадобятся для передачи вinitна завершающем этапе.
production и existing-vpc заранее продумайте, как машина, на которой запускаются clicklink clctl init и kubectl, будет получать доступ к приватному API EKS: например, через VPN, бастион, пиринговую сеть или проброс порта через SSM.
Выберите корневой модуль Terraform для своей среды
Все четыре корневых модуля выдают одинаковый вывод
VPC охватывает три зоны (
Ни один из корневых модулей не изменяет ресурсы, которые он не создавал: таблицы маршрутизации, NAT-шлюзы, конечные точки, правила групп безопасности, группы узлов, шаблоны запуска, конфигурацию кластера и ключи KMS. Оба модуля помечают частные подсети тегами
clicklink. Передача результата в clicklink clctl init происходит одинаково, какой бы из них вы ни применили.minimal
minimal ослабляет настройки публичной конечной точки, интерфейсных конечных точек, журналов потоков (flow logs), срока хранения журналов и размера системного пула. Каждая ослабленная переменная есть в обоих корневых модулях под тем же именем. Чтобы перевести любую из них на значение для продакшна, достаточно изменить terraform.tfvars и повторно выполнить apply. Единственная зона для рабочей нагрузки и отсутствие ключей KMS зафиксированы: зону подсети изменить нельзя, а в корневом модуле нет переменной для шифрования секретов EKS. Чтобы устранить эти ограничения, придётся развернуть production как новый кластер.production
VPC охватывает три зоны (availability_zone_count, от 2 до 4) с частной подсетью /19 и публичной подсетью /21 в каждой зоне, одним NAT-шлюзом на зону, шлюзовой конечной точкой S3, интерфейсными конечными точками для ECR, STS, EKS, EC2, CloudWatch Logs, SSM, SQS, KMS и ELB, а также журналами потоков VPC. Кластер EKS использует закрытую конечную точку API и аутентификацию через access entries; все типы журналов control plane записываются в группу журналов, принадлежащую корневому модулю, а Secrets шифруются управляемым клиентом ключом KMS. В кластер устанавливаются управляемые дополнения vpc-cni, kube-proxy, coredns и aws-ebs-csi-driver, а также создаётся одна системная группа узлов без taint с меткой clickhouseGroup=system (по умолчанию от двух до четырёх узлов m7g.large). Корневой модуль также создаёт ресурсы IAM для Karpenter с очередью прерываний и тегами karpenter.sh/discovery, роли IRSA для контроллера AWS Load Balancer и для исполнителя коннектора, а также ключи KMS для томов EBS и бакетов объектного хранилища.existing-vpc и existing-eks
Ни один из корневых модулей не изменяет ресурсы, которые он не создавал: таблицы маршрутизации, NAT-шлюзы, конечные точки, правила групп безопасности, группы узлов, шаблоны запуска, конфигурацию кластера и ключи KMS. Оба модуля помечают частные подсети тегами karpenter.sh/discovery=<cluster_name> и kubernetes.io/role/internal-elb=1; existing-vpc также помечает публичные подсети тегом kubernetes.io/role/elb=1, а existing-eks добавляет тег к группе безопасности кластера.Для existing-vpc в VPC уже должно быть предусмотрено следующее:- Включены поддержка DNS и DNS-имена хостов.
- От двух до четырёх частных подсетей как минимум в двух зонах доступности с отключённым параметром
map_public_ip_on_launchи маршрутизацией к NAT-шлюзу либо к интерфейсным конечным точкам для ECR, STS, EKS, EC2, CloudWatch Logs, SSM, SQS, KMS и ELB. Добавьте шлюзовую конечную точку S3: без неё трафик к объектному хранилищу будет идти через NAT-шлюзы. - Публичные подсети нужны, только если вам требуются load balancer с доступом из интернета. Если в VPC нет публичного уровня, оставьте
public_subnet_idsпустым.
existing-eks в кластере уже должны быть:- Kubernetes версии 1.34 или новее.
- Режим аутентификации
APIилиAPI_AND_CONFIG_MAP. Для кластера в режимеCONFIG_MAPплан выводит команду переключения. - IAM OIDC-провайдер для issuer кластера.
- Приватные подсети как минимум в двух зонах доступности с исходящим доступом к API AWS через NAT или интерфейсные конечные точки. По умолчанию корневой модуль определяет их по подсетям кластера, исключая те, чья таблица маршрутизации ведёт к интернет-шлюзу. Задайте
private_subnet_ids, если подсети кластера — это подсети/28, предназначенные только для плоскости управления, или если узлы должны размещаться в других подсетях. - Karpenter не установлен: этот корневой модуль сам создаёт IAM-ресурсы Karpenter и очередь прерываний. Очередь называется
<cluster_name>-clicklink, поэтому она не будет конфликтовать с очередью, оставшейся от ранее удалённой установки Karpenter. - Системные узлы без taint-ов с метками из
system_node_selector(по умолчаниюclickhouseGroup=system). Этот корневой модуль не создаёт группу узлов.
terraform plan завершится с ошибкой.Если дополнение из install_addons уже установлено и работает в самоуправляемом режиме, EKS возвращает ошибку Conflicts found when trying to apply. Задайте addon_resolve_conflicts_on_create = "OVERWRITE", чтобы управляемое дополнение заменило существующую установку, или исключите его из install_addons.Скачайте и проверьте архив релиза Terraform
Корневые сертификаты поставляются одним архивом на каждый релиз, и их версия совпадает с версией бинарного файла Перед распаковкой проверьте подпись с помощью cosign:Затем распакуйте его:Архив распаковывается в один каталог, содержащий
clicklink. Загрузите архив для текущего релиза вместе с контрольной суммой и cosign bundle:aws/production, aws/minimal, aws/existing-vpc, aws/existing-eks и aws/modules. Корневые конфигурации ссылаются на модули по пути ../modules. Не разделяйте распакованное дерево и не копируйте из него отдельные корневые конфигурации. В корневых файлах README из архива передача управления через init может быть показана без --platform-bundle; поддерживается команда из раздела инициализация коннектора из выходных данных Terraform.Настройте и примените выбранный корень
В корневом каталоге проекта скопируйте файл с примером переменных и заполните его:Для каждого корневого модуля обязательны В архиве нет lock-файла провайдеров. Команда
region, cluster_name и chart_repository_arn. cluster_name задаёт имя кластера, служит префиксом для всех ресурсов и используется как значение тега обнаружения. В production, minimal и existing-vpc оно должно содержать от 3 до 32 строчных латинских букв, цифр и дефисов, начинаться с буквы и не заканчиваться дефисом. В existing-eks указывается имя уже работающего кластера длиной до 32 символов. chart_repository_arn — это репозиторий ECR с чартом кластера ClickHouse; его предоставляет команда сопровождения аккаунта ClickHouse при регистрации. Для корневых модулей, создающих кластер, также обязателен параметр cluster_admin_principal_arns — субъекты, которые получают права администратора кластера через записи доступа EKS. Учётная запись, от имени которой запускается корневой модуль, должна входить в этот список, иначе впоследствии она не сможет подключиться к кластеру. Создатель кластера не получает доступ автоматически. Требования для отдельных корневых модулей:- Для
minimalобязателенendpoint_public_access_cidrs— список разрешённых IPv4-адресов для публичной конечной точки API. Сеть, из которой вы запускаетеinitиkubectl, должна входить в этот список. Значение/0отклоняется, если не заданоallow_public_endpoint_from_anywhere = true. Приendpoint_public_access = falseсписок может быть пустым — тогда конечная точка будет только приватной, как вproduction. - Для
existing-vpcобязательныvpc_idиprivate_subnet_ids.public_subnet_idsуказывать необязательно: он нужен для балансировщиков нагрузки, доступных из интернета. - Для
existing-eksдругих обязательных переменных нет. Вinstall_addonsперечисляются управляемые дополнения, которых нет в кластере, аebs_kms_key_arnзадаёт ключ для томов сервиса.
terraform providers lock сгенерирует его — закоммитьте этот файл в свою копию. По умолчанию состояние хранится локально. В файле versions.tf есть закомментированный блок backend "s3", который показывает, как настроить общее состояние.Конечные точки API в конфигурациях
production и existing-vpc приватные. Выполняйте init и kubectl изнутри VPC (через проброс порта SSM на системный узел, бастион, VPN или пиринговую сеть) либо явно включите публичный доступ с помощью endpoint_public_access = true и задайте список разрешённых адресов в endpoint_public_access_cidrs.Инициализируйте коннектор с помощью выходных значений Terraform
Экспортируйте выходные значения и передайте их в Корневые модули поддерживают только цель Helm. На ВМ (
init вместе с platform bundle, выполняя команду на машине, где kube-контекст указывает на новый кластер:--target systemd) команда init отклоняет --platform-bundle, а clicklink clctl platform approve --bundle устанавливает только закреплённые компоненты, поэтому в кластере не оказывается средства выделения узлов. Используйте --target systemd только для коннекторов, регистрирующих ClickHouse, который вы запускаете самостоятельно; с этими корневыми модулями такой вариант не поддерживается.--platform-bundle устанавливает то, чего нет в корневых модулях: Karpenter с EC2NodeClass и пулами узлов clickhouse-server и clickhouse-keeper, контроллер AWS Load Balancer, класс хранилища gp3-encrypted (с шифрованием ключом EBS, если он есть в выходных данных), а также компоненты платформы, закреплённые в bundle: контроллер снимков, ClickHouse operator и коллекторы мониторинга. Bundle — это манифест платформы, который ClickHouse Cloud формирует для вашего окружения; его передаёт ваша команда по работе с аккаунтом в ходе онбординга, а раздел cluster: в нём закрепляет версии Karpenter и контроллера load balancer. Для этого флага требуются --target helm, --managed и --from-terraform. Уже установленные компоненты не изменяются, поэтому команду можно безопасно запускать повторно; init выводит отчёт о том, что было установлено, что пропущено и почему. Без этого флага init регистрирует коннектор, но ничего из перечисленного не устанавливает, и кластер не сможет запустить сервис, пока эти компоненты не будут развёрнуты. Последующие обновления платформы затрагивают контроллер снимков, оператор и коллекторы; Karpenter, контроллер load balancer и класс хранилища остаются в том виде, в каком их установила init.--from-terraform принимает либо полный документ, который выводит terraform output -json, либо отдельный объект из terraform output -json clicklink. Выходные данные clicklink содержат идентификационные данные кластера (account_id, region, cluster_name, cluster_endpoint, cluster_ca), провайдер OIDC, пространство имен коннектора, роль IAM исполнителя (executor_role_arn), ключ EBS, роль узлов и очередь Karpenter, роль контроллера load balancer и system_node_selector. init считывает из файла идентификационные данные кластера и пространство имен коннектора. Команда задаёт executor_role_arn в качестве аннотации IRSA для ServiceAccount pcm-executor коннектора и назначает подам коннектора селектор узлов. Управляемые сервисы эту роль не используют: clicklink clctl executor prepare создаёт отдельную роль для каждого сервиса (по умолчанию CH-S3-<service>-<region>-00-Role), которая привязывается к сервису при его создании; см. модель привилегий.init отклоняет флаги, такие как --cluster-name или --target-namespace, если их значения расходятся с файлом, и выводит оба значения. Уберите флаг или исправьте выходные данные. Команда также отклоняет kube-контекст, если его API-сервер не совпадает с cluster_endpoint или его EKS ARN указывает на другой кластер. В выходных данных есть поле schema, сейчас равное 1. clctl отклоняет файл, если не поддерживает указанное в нём значение schema.Остальные шаги регистрации выполняются по стандартной процедуре, описанной в разделе онбординг.Ключи KMS и необходимые привилегии
production и existing-vpc создают три управляемых клиентом ключа KMS с включённой ротацией — для секретов EKS, томов EBS и бакетов объектного хранилища, если только вы не передадите ARN в kms. existing-eks создаёт ключ хранилища, если не задан storage_kms_key_arn, а для томов сервисов принимает ebs_kms_key_arn, не создавая собственный ключ. minimal не создаёт ключей вовсе; если не задан storage_kms_key_arn, его бакеты по-прежнему шифруются с помощью SSE-S3. Созданный ключ содержит один оператор для root-учётной записи аккаунта, который делегирует управление доступом IAM. Для ключа, который вы предоставляете сами, требуется такое же делегирование либо следующие привилегии в его политике ключа:
Корневые модули в любом случае подключают политики ролей IAM для ключей секретов EKS и EBS, а политику исполнителя для ключа хранилища — всякий раз, когда в корневом модуле есть ключ хранилища; политику каждой сервисной роли подключает
executor prepare. Корневые тома системных узлов хранят образы и журналы кубелета, а не данные сервисов, поэтому используют ключ EBS аккаунта по умолчанию.
Удаление инфраструктуры, управляемой Terraform
terraform destroy удаляет всё, что было создано корневым модулем. Созданные ключи KMS переходят в 30-дневный период ожидания удаления. Группы логов удаляются вместе с хранящимися в них журналами, поэтому заранее экспортируйте всё необходимое. Инстансы, запущенные Karpenter, и тома, созданные ClickHouse Operator, не отражены в Terraform state. Поэтому сначала удалите свои сервисы и Karpenter, иначе удаление VPC и роли узлов завершится ошибкой.
existing-eks не удаляет сам кластер. Удаляются роли, очередь прерываний и связанные с ней правила, запись доступа (access entry), а также добавленные модулем теги. Установленные им дополнения vpc-cni, kube-proxy и coredns выводятся из-под управления EKS, но их поды продолжают работать. Дополнение драйвера EBS CSI, если оно было установлено модулем, удаляется вместе с корневым модулем, поскольку его роль IRSA тоже уничтожается. Чтобы сохранить драйвер, перед удалением пересоздайте дополнение с собственной ролью.
При удалении снимаются все теги, добавленные этими корневыми модулями, в том числе тег kubernetes.io/role/internal-elb, существовавший ещё до применения модуля: aws_ec2_tag берёт существующий тег под своё управление. Чтобы сохранить теги, перед удалением задайте manage_subnet_tags = false (existing-vpc) или manage_discovery_tags = false (existing-eks) и выполните apply либо удалите ресурсы aws_ec2_tag из state с помощью terraform state rm.