Обновления платформы

Одобрение платформенных bundle, которые ClickHouse Cloud предлагает для управляемого кластера: что такое bundle, как проходит одобрение и какие привилегии оно даёт

В управляемом кластере работает небольшой платформенный слой, от которого зависят сервисы ClickHouse. ClickHouse Cloud предлагает обновления для этого слоя, однако исполнитель ничего не применяет, пока вы не одобрите каждое из них своими учётными данными кластера.

​

Что такое обновление платформы

Платформенный слой состоит из трех компонентов: контроллер снимков, ClickHouse operator и коллекторы мониторинга. Устанавливаются они именно в этом порядке, поскольку каждому следующему нужны определения пользовательских ресурсов предыдущего. Сервисы используют класс хранилища с именем gp3-encrypted (зашифрованные тома gp3), который поставляется вместе с ними.

Bundle платформы — это манифест, который ClickHouse Cloud формирует для вашей среды. Он фиксирует версии чартов и образов этих компонентов и указывает registry, из которого они загружаются. Каждый bundle идентифицируется по sha256 этого манифеста. ClickHouse Cloud отправляет его исполнителю по командному каналу, а исполнитель подготавливает его к вашему одобрению.

Bundle применяется в две части:

• Часть с разрешениями — это все, что предоставляет или ограничивает доступ: Namespaces, CustomResourceDefinitions, ServiceAccounts, ClusterRoles и ClusterRoleBindings, Roles и RoleBindings, конфигурации webhook и допуска, PriorityClasses, а также класс хранилища. Применяете ее только вы, под своими учетными данными, командой clicklink clctl platform approve.
• Часть с рабочими нагрузками — это то, что запускается: Deployments, Services, ConfigMaps, Secrets, Jobs и PodDisruptionBudgets. Исполнитель применяет ее от выделенной identity pcm-platform, которая может записывать только ресурсы этих Kind и ничего больше, и только пока действителен кратковременный token, выпущенный при вашем одобрении.

Исполнитель никогда не применяет bundle, который вы не одобрили. Он отклоняет синхронизацию платформы, если часть с разрешениями отсутствует, если ее sha256 отличается от одобренного или если срок действия token истек. В сообщении об отказе указывается, что требуется одобрение, и приводится sha256 подготовленного bundle. Создание сервиса, которому нужно определение пользовательского ресурса, отсутствующее в вашей текущей платформе, завершается неудачей точно так же — с указанием той же команды для выполнения.

​

Одобрение обновления платформы

​

Учётные данные registry

Способ authentication в registry зависит от режима распространения образов, зарегистрированного для вашего окружения:

• Прямой доступ к registry ClickHouse. Выполняйте одобрение на ВМ EC2 коннектора. И команда approve, и платформенная синхронизация исполнителя assume роль ECR puller вашего окружения с доступом только для чтения, используя учётные данные из instance metadata service EC2. Эта роль выполняет вход в registry чартов; исполнитель также применяет её для проверки наличия платформенных образов. Профили AWS, учётные данные из переменных окружения или учётные данные SSO на workstation не заменяют instance profile. Отдельные учётные данные администратора кластера, которые применяют часть с разрешениями, по-прежнему берутся из вашего kubeconfig.
• Чарты в другом registry ECR, включая ваш собственный mirror. Для входа в registry чартов используются ambient учётные данные AWS того процесса, который выполняет approve, или исполнителя. Эти учётные данные должны иметь право на чтение из этого registry.

Приведённую ниже процедуру для workstation с Kubernetes используйте только при развертываниях с зеркалированным registry и включенным одобрением платформы через Kubernetes. При прямом доступе сначала обратитесь к команде сопровождения аккаунта ClickHouse, чтобы подтвердить поддерживаемое окружение исполнения с необходимым instance profile EC2.

1. Найдите подготовленный пакет

   ClickHouse Cloud в первую очередь отправляет каждый предлагаемый bundle исполнителю. Исполнитель помещает его в качестве pending bundle и сообщает его sha256 в heartbeat. В каждый момент времени существует один подготовленный bundle; более новое предложение заменяет его. После этого исполнитель отклоняет синхронизацию и записывает failed-команду, результат которой завершается командой для выполнения.

   clicklink clctl commands list --status failed --action sync_platform
   

   Поле result заканчивается строкой run: clctl platform approve (pending bundle sha <sha256>). В Kubernetes подсказка выглядит так: run: clctl platform approve --secret-namespace <connector-namespace> (pending bundle sha <sha256>). Если при создании не нашлось нужного определения пользовательского ресурса, появляется та же строка clctl platform approve. Она встречается и в самой неуспешной команде, и в ошибке, которую выводит clicklink clctl instances create --wait. Кроме того, о предложенном обновлении платформы вам сообщает команда сопровождения аккаунта ClickHouse.

   Прежде чем подтверждать, изучите подготовленный bundle. В нем содержится manifest и его sha256.

   Linux VM

   Исполнитель размещает bundle в виде файла рядом со своими access bundles на хосте коннектора:

   sudo cat /etc/clicklink/access/executor/platform-pending.json
   

   Kubernetes

   Под исполнителя размещает bundle на своем томе состояния и отдает его через локальный API. Откройте проброс порта и прочитайте его:

   CONNECTOR_NAMESPACE='clicklink'   # пространство имен коннектора, выбранное при инициализации
   kubectl -n "${CONNECTOR_NAMESPACE}" port-forward deployment/clicklink-connector-executor 9999:9999 &
   curl -s http://127.0.0.1:9999/v1/platform/pending
   

   Пока не поступит первое предложение, API отвечает кодом 404 с сообщением no platform bundle is staged. Оставьте проброс порта открытым — он понадобится на следующем шаге.

2. Выполните approve

   approve без флагов читает подготовленный bundle и вычисляет его hash, поэтому вы одобряете ровно то, что получил executor. Команда рендерит каждый chart точно так же, как это сделает executor, и применяет часть с разрешениями в выбранном вами kube-контексте. При необходимости она создаёт identity pcm-platform и выпускает для неё token. Никаких запросов к вашей connector endpoint при этом не выполняется.

   Для approve нужен kube-контекст с правами cluster-admin на управляемом кластере (--context <name>, если в вашем kubeconfig несколько контекстов), а также registry credentials для используемого в вашей среде режима распространения образов. --dry-run рендерит и выводит часть с разрешениями, ничего не применяя и не выпуская; при этом ему всё равно нужен доступ к registry для рендеринга charts.

   Linux VM

   Выполните на хосте коннектора от имени root — там, где executor подготовил bundle:

   sudo clicklink clctl platform approve --config /etc/clicklink/config.yaml
   

   approve записывает token в /etc/clicklink/access/executor/_platform, рядом с остальными credentials исполнителя. Новый bundle собирается рядом с действующим и подменяет его только после того, как его token создан, поэтому неудачное одобрение оставляет всё ещё действительный token нетронутым.

   Kubernetes

   При развертывании с зеркалированным registry и включенным подтверждением платформы в Kubernetes approve читает подготовленный bundle через проброс порта из предыдущего шага. Token-bundle доставляется как Secret в пространство имен коннектора, которое chart монтирует в под. Запускайте команду с рабочей станции, чей kubeconfig имеет доступ к кластеру, имея при себе копию конфигурации коннектора и доступ к registry. Chart рендерит конфигурацию в ConfigMap исполнителя; approve использует её только для prefix пространства имен и не читает из неё никаких credentials.

   CONNECTOR_NAMESPACE='clicklink'   # пространство имен коннектора, выбранное при init
   kubectl -n "${CONNECTOR_NAMESPACE}" get configmap clicklink-connector-executor \
     -o jsonpath='{.data.config\.yaml}' > clicklink-config.yaml
   clicklink clctl platform approve --config clicklink-config.yaml \
     --secret-namespace "${CONNECTOR_NAMESPACE}"
   

   По умолчанию approve читает подготовленный bundle по адресу http://127.0.0.1:9999; укажите --endpoint, если ваш проброс порта использует другой локальный порт. Без проброса порта команда прерывается и выводит команду kubectl port-forward, которую нужно выполнить. Bundle попадает в Secret clicklink-platform-bundle (изменить можно через --secret-name, в соответствии со значением executor.platformBundleSecret в chart). Под исполнителя увидит его после того, как Кубелет обновит mount, — примерно в течение минуты.

3. Подтвердить

   approve завершается следующим:

   Approved: <n> permission object(s) applied, platform token valid until <expiry>.
   The executor may now apply the <n> workload object(s) of this bundle inside <namespaces>.
   

   В Kubernetes добавляется третья строка: Bundle written to Secret <namespace>/<name>; the executor pod sees it once the kubelet refreshes the mount, within about a minute.

   ClickHouse Cloud повторно отправляет синхронизацию, как только следующий heartbeat исполнителя покажет подтверждение. Система ждёт до 20 минут завершения уже выполняющейся синхронизации и пропускает исполнителя, чей последний heartbeat старше 5 минут. После 3 попыток для одного bundle процесс прекращается, и команда сопровождения аккаунта ClickHouse запускает его заново. Исполнитель применяет часть, относящуюся к рабочей нагрузке, и сообщает о платформе как о synced. Отследить завершение синхронизации можно так:

   clicklink clctl commands list --action sync_platform
   

   Последняя команда sync_platform переходит в состояние completed. Исполнитель также передаёт статус платформы и версии компонентов в ClickHouse Cloud при каждом heartbeat, так что команда сопровождения аккаунта ClickHouse видит тот же результат.

​

Окно одобрения

При одобрении выпускается token для identity pcm-platform, действительный по умолчанию 2 часа (изменяется параметром --ttl). Исполнитель никогда его не продлевает. После истечения срока действия исполнитель больше не может обращаться к платформенному слою и снова отклоняет очередную синхронизацию платформы, выдавая сообщение о необходимости одобрения. Это предусмотренное поведение, не зависящее от наличия соединения: одобрение, выданное при отключённом коннекторе, всё равно истекает по собственному таймеру.

Выполните approve повторно, если:

• token истёк до завершения синхронизации;
• ClickHouse Cloud предлагает другой bundle. Подтверждённая вами sha256 записывается в ServiceAccount pcm-platform, и исполнитель отклоняет синхронизацию любого другого bundle, пока вы не подтвердите его;
• при создании сервиса сообщается об отсутствующем определении пользовательского ресурса.

Повторное одобрение того же bundle безопасно и заменяет token. Подготовленный bundle сохраняется и после синхронизации, поэтому для повторного одобрения новое предложение не требуется.

​

Что даёт одобрение

Вы применяете часть с разрешениями, поэтому она наделяется вашими полномочиями; сам исполнитель ничего из неё не применяет. approve подписывает её значением sha256 переданного bundle, и, прежде чем что-либо менять, исполнитель проверяет, что все объекты разрешений из полученного им bundle присутствуют и одобрены.

Часть с рабочими нагрузками исполнитель применяет от имени pcm-platform. Эта identity может создавать и обновлять Secrets, ConfigMaps, Services, Deployments, Jobs и PodDisruptionBudgets — только внутри пространств имен платформы, что обеспечивается политикой допуска. Она может читать объекты, необходимые для её preflight (поды, events, пространства имен, ServiceAccounts, перечисленные выше Kind разрешений). Она не может:

• записывать какой-либо Kind уровня cluster или какой-либо объект RBAC;
• выполнять escalate, bind или impersonate;
• выпускать или обновлять собственный token.

Identity исполнителя для жизненного цикла сервисов, pcm-executor, отделена от неё и ограничена пространствами имен сервисов. Она не может выполнять запись в пространства имен платформы; на её операции чтения защита по prefix не распространяется. Полный перечень обеих identities см. в разделе модель привилегий.

​

Сброс тестового кластера

Команда clicklink clctl platform reset предназначена для тестовых кластеров: она удаляет компоненты платформы, чтобы их первичную установку можно было выполнить повторно. Прежде чем что-либо менять, она выводит список кластеров ClickHouse в пространствах имен, принадлежащих этому коннектору, и прерывает работу, если существует хотя бы один сервис.

На пустом кластере она удаляет релизы платформы в порядке, обратном порядку зависимостей. Затем удаляется bundle с токеном платформы исполнителя: локальный каталог на ВМ либо Secret, указанный через --secret-namespace <connector-namespace>, в Kubernetes. CustomResourceDefinition, RBAC и класс хранилища остаются на месте. Перед следующей синхронизацией платформы снова выполните approve.

sudo clicklink clctl platform reset --bundle <manifest-file> --config /etc/clicklink/config.yaml --dry-run

reset принимает сгенерированный манифест платформы в виде файла (--bundle); подготовленный bundle он не читает. --dry-run проверяет наличие сервисов и выводит план, не внося изменений в кластер.