Как устроена миграция на модуль registry?

Управлять путём загрузки образов в Deckhouse Platform (DP) можно двумя способами:

  • реализация v1 (DP до версии 1.77 включительно) — секция registry в ModuleConfig deckhouse с режимами Unmanaged, Direct, Proxy и Local;
  • текущая реализация — этот модуль, настраиваемый через ModuleConfig registry.

Миграция — это передача пути загрузки от реализации v1 модулю. Её не нужно запускать вручную, и отдельной команды для неё нет: модуль принимает управление автоматически после обновления кластера на DP 1.78. Единственное условие — к этому моменту реализация v1 должна освободить путь загрузки. Обе реализации настраивают на каждом узле одно и то же — из какого хранилища образов контейнеров container runtime загружает образы и с какими учётными данными, — поэтому они никогда не управляют кластером одновременно.

Что нужно сделать для передачи управления и когда — зависит от режима, в котором работает реализация v1. Режим указан в параметре settings.registry.mode ModuleConfig deckhouse:

d8 k get mc deckhouse -o jsonpath='{.spec.settings.registry.mode}'

Пустой вывод означает режим Unmanaged: настройки хранилища образов контейнеров в этом кластере никогда не задавали. Такому кластеру — как и любому другому в Unmanaged — для миграции ничего делать не нужно: передача управления произойдёт сама.

Режим Что сделать Когда
Unmanaged Ничего — передача произойдёт сама —
Direct Настроить модуль: mode: Managed с primary.upstream До обновления
Proxy Перевести кластер в Unmanaged До обновления
Local Выполнить процедуру для изолированных кластеров До обновления

Подготовьте кластер до обновления: обновление на DP 1.78 заблокировано, пока кластер работает в режиме Proxy или Local, а также в режиме Direct без настроенного ModuleConfig registry. В DP 1.78 нет ни компонентов реализации v1, ни кода, который переключает её режимы, поэтому вся подготовка выполняется на DP 1.77.

Режиму Direct переключение не требуется. Настройки модуля намеренно принимаются уже в DP 1.77: записанные до обновления, они хранятся без эффекта и срабатывают на первой итерации согласования модуля после обновления.

На узлах с containerd v1 миграция из Unmanaged или через него перезапускает containerd. Подробнее — в разделе «Перезапускается ли containerd при миграции?».

Кластер записывает, на какой реализации он фактически работает (как это проверить). Пока передача управления невозможна, обновление на DP 1.78 блокируется, и в сообщении об ошибке сказано, что сделать.

На какой реализации работает мой кластер?

Когда модуль принимает управление путём загрузки, он записывает это в секрет registry-v2-switch. Проверьте, существует ли секрет:

d8 k -n d8-system get secret registry-v2-switch >/dev/null 2>&1 \
  && echo "текущая реализация" || echo "реализация v1"

Если кластер всё ещё на реализации v1, модуль сообщает причину на каждой итерации согласования, а в кластере срабатывает алерт D8RegistryMigrationPending. Посмотреть, чего он ждёт:

d8 k -n d8-system get secret registry-state -o jsonpath='{.data.state}' | base64 -d | head

На DP 1.78 обновление удаляет секрет registry-state. Режим после этого виден в конфигурации узлов, которую реализация v1 оставила в секрете registry-bashible-config. Команда выводит только режим и адреса прокси, без учётных данных:

d8 k -n d8-system get secret registry-bashible-config -o jsonpath='{.data.config}' | base64 -d \
  | awk '/^(agent|mode):/ {print; next} /^proxyEndpoints:/ {p=1; print; next} p && /^ *- / {print; next} {p=0}'

Строка agent: в выводе или аннотация registry.deckhouse.io/installer-config-sha256 у секрета означают, что конфигурацию записала текущая реализация или установщик DP 1.78 и новее, а не реализация v1. Аннотация учитывается, только пока конфигурацию никто не менял после установщика.

Как мигрировать из режима Unmanaged?

В режиме Unmanaged реализация v1 не управляет путём загрузки, поэтому готовить нечего: передача управления произойдёт сама.

  1. Если кластер переводится в Unmanaged из другого режима, дождитесь завершения перехода. В статусе должно быть mode: Unmanaged без ожидающего целевого режима:

    d8 k -n d8-system get secret registry-state -o jsonpath='{.data.state}' | base64 -d | head
    
  2. Обновите кластер на DP 1.78 (или, если он уже обновлён, просто дождитесь следующей итерации согласования). Модуль примет управление автоматически, и источник образов не изменится: режим модуля по умолчанию — тоже Unmanaged, поэтому кластер продолжит загружать образы из того же хранилища образов контейнеров, что и раньше. Однако на узлах с containerd v1 передача управления по очереди перезапускает containerd, если реализация v1 оставила конфигурацию доступа узлов к хранилищу образов контейнеров, а включение mode: Managed на следующем шаге перезапускает его (во второй раз, если это уже сделала передача управления; см. «Перезапускается ли containerd при миграции?»).

  3. Чтобы модуль начал управлять путём загрузки, задайте mode: Managed в ModuleConfig registry и укажите хранилище образов контейнеров, из которого загружать образы. Готовая конфигурация для вашего кластера публикуется в секрете registry-suggested-config; как её применить, показано в примере «Включение модуля».

Как мигрировать из режима Direct?

В режиме Direct узлы загружают образы через внутрикластерный адрес, который обслуживает прокси реализации v1. Модуль обслуживает тот же адрес, поэтому миграция — это прямая передача адреса: переход через Unmanaged не нужен, и компоненты не перезапускаются.

  1. Настройте модуль до обновления — без этой конфигурации обновление заблокировано. Возьмите значения из секции registry.direct в ModuleConfig deckhouse: imagesRepo разделяется на host и path, учётные данные — тот же license (или username/password), плюс ca, если хранилище образов контейнеров его требует:

    apiVersion: deckhouse.io/v1alpha1
    kind: ModuleConfig
    metadata:
      name: registry
    spec:
      enabled: true
      version: 1
      settings:
        mode: Managed
        primary:
          upstream:
            scheme: HTTPS
            host: registry.deckhouse.io
            path: /deckhouse/ee
            auth:
              license: <LICENSE_KEY>
    

    DP 1.77 сохраняет эти настройки, но не действует по ним, поэтому до обновления в кластере ничего не меняется.

  2. Обновите кластер. Передача произойдёт на следующей итерации согласования модуля, и загрузка образов всё это время работает: Service и прокси реализации v1 продолжают обслуживать внутрикластерный адрес, пока агент модуля не примет его на каждом узле, и только после этого контроллер их удаляет.

  3. Следите за ходом передачи:

    d8 k -n d8-system get secret registry-v2-switch >/dev/null 2>&1 && echo "управление передано"
    d8 k get registrynode -o custom-columns='NODE:.metadata.name,READY:.status.reconciled,SERVING:.status.proxyListening'
    

    Для ориентира — порядок и масштаб событий: передача фиксируется через пару минут после старта новой версии, агент появляется на узлах ещё через несколько минут, а объекты реализации v1 удаляются вскоре после этого. Загрузка образов работает на каждом из этих этапов.

Как мигрировать из режима Proxy?

Режим Proxy держит на каждом узле собственный прокси со своими сертификатами — состояние, которое модуль перенять не может. Поэтому кластер сначала нужно перевести в Unmanaged, и сделать это можно только до обновления.

  1. В ModuleConfig deckhouse задайте registry.mode: Unmanaged, сохранив тот же адрес хранилища образов контейнеров и учётные данные. Готовые манифесты приведены в примерах переключения режимов. Все узлы будут перенастроены на загрузку напрямую из внешнего хранилища образов контейнеров, поэтому кеширование, которое давал Proxy, пропадёт до шага 4.

  2. Дождитесь завершения перехода — mode: Unmanaged без ожидающего целевого режима. Кластер, застигнутый посреди перехода, мигрировать нельзя; в статусе видно, в какой режим он ещё переключается:

    d8 k -n d8-system get secret registry-state -o jsonpath='{.data.state}' | base64 -d | head
    
  3. Обновите кластер. Передача произойдёт на следующей итерации согласования модуля, и источник образов не изменится: в режиме Unmanaged модуль тоже не управляет путём загрузки. Однако на узлах с containerd v1 передача управления по очереди перезапускает containerd, а включение mode: Managed на следующем шаге перезапускает его ещё раз (см. «Перезапускается ли containerd при миграции?»).

  4. Чтобы вернуть кеширование внутри кластера, задайте mode: Managed с storage.cache: true и тем же внешним хранилищем образов контейнеров. Учтите, что кеш модуля устроен иначе, чем Proxy: одно хранилище с репликами на master-узлах вместо прокси на каждом узле. Прежде чем включать его на кластере, где на master-узлах мало свободного места, прочитайте, как кеш наполняется и очищается.

Как мигрировать изолированный кластер из режима Local?

В режиме Local у кластера нет внешнего хранилища образов контейнеров — его роль выполняет хранилище внутри самого кластера. Поэтому стандартная процедура миграции здесь не работает: она проходит через режим Unmanaged, в котором каждый узел загружает образы напрямую из внешнего хранилища образов контейнеров, а такому кластеру загружать их неоткуда.

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

Требования к диску

Перед началом убедитесь, что на master-узлах свободно место под четыре набора образов: на пике миграции одновременно существуют три копии набора — хранилище Local, временное хранилище образов контейнеров и наполняющееся хранилище модуля, — а место под четвёртый набор нужно как запас, который узел не должен исчерпать.

Масштаб можно оценить на примере набора образов порядка 13 ГБ (платформа с модулями): он занимает около 21 ГБ во временном хранилище образов контейнеров (там хранятся два релиза — тот, на котором кластер работает, и тот, на который обновляется) и увеличивает хранилище с 13 до 21 ГБ, не считая кеша образов самого узла и системы. На master-узле со 100 ГБ диска пик составляет около 38 ГБ, а на узле с 50 ГБ та же миграция упирается в вытеснение подов.

Запас нужен не для перестраховки. Когда свободное место на master-узле заканчивается, kubelet начинает вытеснять поды и удалять образы, которые считает неиспользуемыми, — а в кластере, чьё хранилище образов контейнеров работает внутри него самого, удалённым может оказаться образ самого хранилища образов контейнеров. Тогда хранилище остаётся без процесса, который его обслуживает, а узел — без места, откуда этот образ можно загрузить. При тестировании эта взаимная блокировка продержалась 99 минут, и разрешить её удалось только ручной загрузкой образов на узел. Поэтому рассчитайте место заранее и следите за диском, пока идёт миграция.

Часть места экономится за счёт того, что образы, уже хранящиеся на дисках master-узлов, хранилище модуля проверяет и принимает на месте, а не скачивает заново (шаг 6). Но превратить два разных релиза в один набор такая проверка не может: в хранилище оказываются и релиз, на котором работал старый кластер, и релиз, на котором работает новый, — отсюда и размер пика.

Порядок действий

Шаги 1–4 выполняются до обновления, на DP 1.77, где ещё есть реализация v1.

  1. Запустите временный OCI-registry в собственном неймспейсе. Реализация хранилища образов контейнеров может быть любой, но оно должно отдавать TLS с сертификатом, который кластер сможет проверить, и DP не должна им управлять: что бы ни происходило с объектами модуля, временное хранилище образов контейнеров должно продолжать работать.

    Кроме того, хранилище образов контейнеров должно быть доступно по одному и тому же адресу из двух мест: на шаге 3 из него загружают образы узлы, а на шаге 6 его читает syncer модуля, работающий в поде. Сертификат должен покрывать выбранный адрес. Варианты, проверенные на одном кластере:

    Адрес С узла Из пода
    порт hostNetwork на IP самого узла (<NODE_IP>:5000) работает работает
    имя Service (<SERVICE>.<NAMESPACE>.svc:<PORT>) не разрешается работает
    NodePort на IP узла работает не работает: operation not permitted

    Используйте первый вариант: запустите хранилище образов контейнеров с hostNetwork: true на одном узле, обращайтесь к нему по IP этого узла и добавьте этот IP в SAN сертификата — тогда вся миграция пройдёт на одном адресе. Имя Service выглядит аккуратнее, но перестаёт работать на шаге 3, потому что container runtime узла не разрешает имена через кластерный DNS.

  2. Загрузите набор образов во временное хранилище образов контейнеров: сначала скачайте его командой d8 mirror pull на машине, у которой есть доступ к хранилищу образов контейнеров DP, а затем отправьте во временное хранилище образов контейнеров командой d8 mirror push. Именно эта копия набора учтена выше в расчёте места на диске.

  3. Направьте реализацию v1 на временное хранилище образов контейнеров и переведите её в Unmanaged: в ModuleConfig deckhouse задайте registry.mode: Unmanaged вместе с адресом, сертификатом CA и учётными данными временного хранилища образов контейнеров. После этого узлы начнут загружать образы из него, а хранилище Local уйдёт с пути загрузки — но его данные останутся на месте, в каталоге /opt/deckhouse/registry на master-узлах.

  4. Убедитесь, что переход завершён и образы действительно загружаются из временного хранилища образов контейнеров, — на этом шаге держится вся остальная миграция. Проверки те же, что и для любого кластера в Unmanaged:

    d8 k -n d8-system get secret registry-state -o jsonpath='{.data.state}' | base64 -d | head
    
  5. Обновите кластер на DP 1.78. Передача управления произойдёт на следующей итерации согласования, и всё это время кластер продолжит загружать образы из временного хранилища образов контейнеров. На узлах с containerd v1 передача управления по очереди перезапускает containerd, а включение mode: Managed на следующем шаге перезапускает его ещё раз (см. «Перезапускается ли containerd при миграции?»).

  6. Включите модуль: задайте mode: Managed с storage.cache: true, укажите временное хранилище образов контейнеров в качестве primary.upstream — и добавьте storage.source в том же изменении. Хранилище модуля запустится на том же пути на хосте, который использовал Local, поэтому уже имеющиеся на дисках образы не будут скачиваться заново: наполнение проверит их и дозагрузит только недостающее.

    Откладывать указание storage.source нельзя: без него не получится убрать внешнее хранилище образов контейнеров на следующем шаге, потому что конфигурация Managed без primary.upstream принимается только при заданном storage.source, — следующий шаг будет отклонён с ошибкой 'storage.source' is required when 'primary.upstream' is not set.

    В storage.source поле bundleRef — это произвольное имя набора образов, а expectedDigests — число различных дайджестов в нём. Посчитать их можно по bundle с шага 2:

    for tar in <BUNDLE_DIR>/*.tar; do tar -xOf "$tar" --wildcards '*index.json'; done |
      jq -r '.manifests[]?.digest' | sort -u | wc -l
    

    Указание storage.source не перезапускает хранилище: этот параметр не входит в конфигурацию процесса хранилища образов контейнеров. Процесс перезапустится на следующем шаге, когда будет убран upstream.

  7. Дождитесь, пока хранилище сообщит, что держит полный набор (phase: Ready и safeToDropUpstream: true), и уберите primary.upstream из ModuleConfig registry. После этого кластер снова изолирован — теперь уже на модуле. После перезапуска реплики хранилища safeToDropUpstream может оставаться false, пока синкер лидера не прочитает своё хранилище, обычно не дольше двух минут, а если первое чтение не удалось — около десяти минут:

    d8 k get registrystorage registry -o jsonpath='{.status.phase} {.status.safeToDropUpstream}{"\n"}'
    

    Удаление upstream перезапускает процесс хранилища образов контейнеров. Если после перезапуска процесс читает своё хранилище дольше нескольких десятков секунд, ресурс RegistryStorage переходит в Failed с ошибкой чтения набора образов. Это ожидаемо — дождитесь возврата в Ready.

  8. Удалите временное хранилище образов контейнеров и освободите занятый им диск.

Перезапускается ли containerd при миграции?

На узлах с containerd v1 (cri.type: Containerd) перезапускается. Узлы с containerd v2 всегда берут настройки хранилищ образов контейнеров из каталога /etc/containerd/registry.d, и containerd на них не перезапускается.

На узле с containerd v1 файл /etc/containerd/config.toml направляет containerd в каталог /etc/containerd/registry.d, только пока в кластере есть конфигурация доступа узлов к хранилищу образов контейнеров — секрет registry-bashible-config. Без этого секрета хранилище образов контейнеров описывается в самом файле, блоками mirrors и configs. В режиме Unmanaged модуль удаляет этот секрет, в том числе оставленный реализацией v1. Изменение config.toml перезапускает containerd, а за ним kubelet. Поэтому на containerd v1:

  • каждое переключение между Unmanaged и Managed, в любую сторону, перезапускает containerd один раз. При переходе из Managed в Unmanaged перезапуск происходит, когда модуль перестаёт обслуживать загрузку образов, то есть когда ни одна рабочая нагрузка больше не ссылается на внутрикластерный адрес registry.d8-system.svc:5001, а не в момент изменения ModuleConfig;
  • в кластере, где реализация v1 оставила этот секрет, containerd при миграции через Unmanaged перезапускается дважды: когда модуль берёт управление на себя после обновления и когда включается mode: Managed. Это кластер, который перед обновлением перевели из Proxy или Local в Unmanaged с заданным адресом хранилища образов контейнеров, и любой другой кластер в Unmanaged с таким адресом;
  • миграция из Direct containerd не перезапускает: конфигурация узлов сохраняется на всём пути.

Проверить, есть ли секрет, можно командой d8 k -n d8-system get secret registry-bashible-config.

containerd перезапускается не на всех узлах сразу. Изменение доходит до них обычным обновлением узла, которое ждёт подтверждения, а подтверждение по умолчанию выдаётся по одному узлу в каждой NodeGroup (см. update.maxConcurrent). Запущенные контейнеры перезапуск переживают. На обновляемом узле прерываются идущие загрузки образов (kubelet их повторит) и открытые сеансы exec, attach, port-forward и logs -f.

Что означают алерты модуля registry?

Кроме двух алертов об агенте на узле, D8RegistryStorageLeaderAbsent в изолированном кластере и D8RegistryMigrationPending, ни один из перечисленных ниже не означает, что кластер перестал загружать образы. Большинство сообщает о состоянии, в котором всё работает, но не так, как задано в конфигурации, — такое состояние легко не заметить.

D8RegistryMigrationPending
Модуль не принял управление у реализации v1, которая использовалась до DP 1.77 включительно; причина указана в алерте. Если в причине назван режим Direct, настройте модуль, как описано в разделе «Как мигрировать из режима Direct?», и модуль примет управление сам. Любая другая причина (режим Proxy или Local, переход между режимами, незаписанный режим или нечитаемое состояние) означает неподдерживаемое состояние. Кластер попадает в него только при обновлении в обход требования релиза registryImplementation: принудительным релизом, подменой образа или переходом с релиза ниже DP 1.77.1. DP 1.78 не разворачивает реализацию v1, а обновление удалило компоненты, которые управляли её сервисами на master-узлах, поэтому эти сервисы либо остановлены, либо продолжают работать без управления. Образы, которые уже есть на узле, продолжают работать, загрузка любого другого образа может завершиться ошибкой. Не меняйте ModuleConfig registry и deckhouse и не удаляйте секреты registry-* в d8-system: именно эти секреты не дают развернуть текущую реализацию рядом с тем, что оставила реализация v1. Обратитесь в техническую поддержку Deckhouse Platform. См. также раздел «На какой реализации работает мой кластер?».
D8RegistryConfigInvalid
Конфигурация отклонена; кластер продолжает работать с прежней. Причина — в .status.conditions ресурса registryconfig/registry.
D8RegistryNodeNotConverged
Агент на части узлов не применил выданную ему конфигурацию. Эти узлы продолжают загружать образы по старой конфигурации, и следующие изменения до них тоже не дойдут.
D8RegistryNodeRunningFromDisk
Агент на части узлов не смог получить из API-сервера пригодную конфигурацию и маршрутизирует загрузки по копии конфигурации на диске. Чаще всего не удаётся прочитать учётные данные, на которые ссылается конфигурация; так же выглядит чтение конфигурации, которое не удалось, когда запись статуса после него прошла, например при кратком сбое API-сервера. Этот резервный механизм работает как задуман: загрузки на таких узлах проходят успешно, поэтому больше ничто о проблеме не сообщит, — а конфигурация узлов тем временем может сколь угодно сильно отстать от кластерной. О переходе на копию агент сообщает через API-сервер, поэтому алерт не видит агент, который не может туда писать: узел, отрезанный от API-сервера, вместо этого виден как NotReady, а агент, которому отказано в доступе на узле в состоянии Ready, не виден ничем.
D8RegistryAgentNotReady
Агент на узле не готов уже 15 минут: падает при запуске, не отвечает или вовсе не запущен на узле. Пока он не вернётся, containerd на этом узле загружает образы в обход него: образы платформы и образы из registry, которым нужны учётные данные или CA кластера, не загружаются, остальные идут мимо кеша. Куда смотреть, описано в разделе «На узле не загружается образ. Куда смотреть?».
D8RegistryAgentRestartingTooOften
Агент на узле перезапустился пять раз или больше за час. Каждый перезапуск обрывает идущие на узле загрузки. Последнее состояние контейнера и лог предыдущего запуска показывают, завершился ли он сам или был перезапущен, потому что не отвечал.
D8RegistryStorageIncomplete
Часть реплик кеша не держит весь ожидаемый набор образов. Пока настроено внешнее хранилище образов контейнеров, на загрузки это не влияет, но его потерю кластер бы не пережил — и именно это блокирует переход в air-gap. Реплику, в хранилище которой registry не может писать (NotWritable), вместо него показывает D8RegistryStoreWritesRefused.
D8RegistryAirGapTransitionHeld
Вы убрали внешнее хранилище образов контейнеров из конфигурации, но модуль продолжает им пользоваться: либо кеш пока не может обслуживать кластер сам, либо отчёт лидера кеша записан не тем syncer, который работает на его узле сейчас (syncerStartedAt в статусе RegistryStorage), либо нагрузки в неймспейсах kube-system и d8-* ещё ссылаются на upstream (upstreamReferences). Это безопасный исход: отключение внешнего хранилища образов контейнеров в этот момент оставило бы узлы без источника образов. Алерт не разрешится сам, если кеш перестал наполняться, обновление нагрузок на адрес внутри кластера остановилось, под хранилища на узле лидера не Ready или в нём работает syncer, выпущенный до появления syncerStartedAt (во время обновления модуля).
D8RegistryUpstreamProbeFailing
Изменение основного внешнего хранилища образов контейнеров отклонено, и кластер продолжает пользоваться последним работавшим. Лейбл outcome различает три проблемы: unreachable — сеть или само хранилище образов контейнеров; auth — обычно истёкший лицензионный ключ; sentinel — хранилище образов контейнеров ответило и приняло учётные данные, но не содержит образов DP (обычно неверный путь репозитория).
D8RegistryUpstreamRejected
Ресурс RegistryUpstream не принят, поэтому загрузки для указанного в нём хранилища образов контейнеров не перехватываются. Лейбл reason говорит, конфликтует он с основным хранилищем образов контейнеров или с другим ресурсом, претендующим на то же имя.
D8RegistryStorageNotReclaimed
Ни одна реплика не выполняла сборку мусора неделю. Сборка — единственный механизм, который удаляет данные из хранилища, поэтому, если она остановилась, диск рано или поздно заполнится. Подробнее о сборке — в разделе «Кеш растёт. Что его чистит».
D8RegistryStoreCorrupted
Реплика хранит блобы, содержимое которых не совпадает с их digest, а ремонт, запущенный модулем автоматически, не исправил их за два часа. Загрузка затронутых образов с этой реплики не проходит. Как проверить и починить образы, описано в разделе «Как проверить и починить образы в кеше».
D8RegistryStaleCacheData
На узле лежат данные кеша, которые никто не использует. Как освободить место, описано в разделе «Как удалить с узла оставшиеся данные кеша».
D8RegistryStoreWritesRefused
Кеш на master-узле перестал принимать запись: хранилище заняло storage.size (BudgetExhausted) или дошло до места, оставленного свободным на его файловой системе (ReserveExhausted). Узлу ничего не грозит, кеш продолжает отдавать то, что в нём есть; останавливается только его наполнение. Подробнее — в разделе «Что происходит, когда хранилище кеша заполнено». NotWritable означает другое: registry не может создавать файлы в своём дереве в хранилище (docker/registry/v2 и ниже, а пока его нет — в каталоге хранилища) из-за владельца или прав каталогов, атрибута, монтирования только для чтения или модуля безопасности. Ни сборка мусора, ни больший storage.size здесь не помогут. Каталог и команду, которая это исправляет, указывает error реплики в статусе RegistryStorage.
D8RegistryStoreNearlyFull
Хранилище на master-узле заняло больше 85% от storage.size. Следующий релиз может не поместиться.
D8RegistryStoreUnbounded
Кеш включён, а storage.size не задан, поэтому единственный предел — место, оставленное свободным на файловой системе хранилища.
D8RegistryControllerDown
Ни одна реплика registry-controller не готова и не отвечает Prometheus. На загрузку образов это не влияет, но изменения конфигурации не доходят до узлов, а большинство остальных алертов модуля всё это время молчит: они читают то, что экспортирует контроллер. D8RegistryStorageLeaderAbsent и алерты миграции и вытеснения от контроллера не зависят и продолжают работать.
D8RegistryStorageLeaderAbsent
Ни одна готовая реплика кеша не сообщает, что держит Lease лидера. Кеш никто не наполняет, остальным репликам не с кого реплицировать, а d8 mirror push некуда отправлять. Узлы по-прежнему направляют загрузки в реплику, указанную лидером: при настроенном внешнем хранилище образов контейнеров загрузки идут медленнее, в изолированном кластере образы, которых ещё нет на узле, не загрузить. Если Lease registry-storage в d8-system продолжает обновляться, лидер жив, но его метрики не собираются: либо его под не готов, тогда выясните, какой из контейнеров пода не готов, либо не удаётся опрос этого пода, тогда смотрите лог его контейнера kube-rbac-proxy. Если master, на котором был лидер, потерян и не вернётся, удалите объект Node этого узла; в остальных случаях смотрите поля error реплик в статусе RegistryStorage и логи контейнера syncer. Просто неготовую реплику кеша показывает алерт KubernetesStatefulSetReplicasUnavailable модуля extended-monitoring, если он включён.
D8RegistryStorageUpdateBlocked
У кеша новая ревизия, но контроллер уже час не может заменить очередную реплику. Существующие реплики остаются запущенными, но обновление кеша не продолжается. Лейбл reason говорит, чего ждёт контроллер и нужно ли что-то делать. Подробнее — в разделе «Как обновляется кеш».

Как удалить с узла оставшиеся данные кеша?

При выключении кеша данные в директории кеша намеренно сохраняются: если включить кеш снова, он наполнится из того, что уже хранится на диске, а не будет скачивать всё заново — на медленном канале это экономит часы. Автоматическое удаление сделало бы выключение кеша необратимым, поэтому решение модуль оставляет вам: агент измеряет оставшиеся данные и поднимает алерт D8RegistryStaleCacheData.

Чтобы узнать, сколько места занимают данные, используйте команду:

d8 k get registrynodes -o custom-columns=\
NODE:.metadata.name,STALE:.status.staleStorageDataBytes

Если включать кеш обратно вы не собираетесь, удалите на узле содержимое директории кеша: /var/lib/deckhouse/registry на узле NodeGroup с systemType: DeckhouseEngine, /opt/deckhouse/registry на остальных узлах. Саму директорию оставьте: она смонтирована в агент, и после её удаления агент перестаёт видеть директорию узла. Данные, которые кеш оставит там позже, тогда не будут учтены до перезапуска агента. Для этого выполните следующие действия:

  1. Откройте на узле shell от имени root по SSH. На узле NodeGroup с systemType: DeckhouseEngine SSH нет: запустите на нём отладочный под и переключитесь в корневую файловую систему узла:

    d8 k debug node/<NODE> -it --image=<IMAGE>
    chroot /host
    
  2. Удалите данные. Команда проверяет обе директории и оставляет сами директории:

    for dir in /opt/deckhouse/registry /var/lib/deckhouse/registry; do
      [ -d "$dir" ] && du -sh "$dir" && find "$dir" -mindepth 1 -delete
    done
    

Кеш растёт. Что его чистит?

Кеш очищается во время сборки мусора, которую каждая реплика хранилища выполняет над своим хранилищем. Модуль запускает её по расписанию, когда кеш получил новый набор образов, и когда хранилище отказывает в записи; запустить её можно и вручную.

Это единственный механизм, который вообще что-то удаляет из хранилища. Каждый релиз DP добавляет новые образы, поэтому без сборки хранилище кластера, работающего долгое время, рано или поздно заполнится и перестанет принимать запись, — а изолированный кластер с заполненным хранилищем нельзя обновить.

Сборка удаляет образы релизов, которые кластер уже прошёл. Сохраняются:

  • развёрнутый релиз и предыдущий — чтобы откат не скачивал заново то, к чему откатывается;
  • всё, что новее развёрнутого релиза, — это обновление в процессе или, в изолированном кластере, релиз, загруженный намеренно;
  • все теги, которые не являются версиями: имена каналов обновлений вроде stable, плавающие теги, всё загруженное вручную. Сборщик не может знать, что они означают, поэтому не трогает их.

Также сборка удаляет блобы, на которые не ссылается ни один образ: например, оставшиеся от прерванного наполнения или от сборки, у которой не удалась очистка. Их она удаляет, даже когда удалять образы не нужно.

Сборщик намеренно осторожен. В изолированном кластере удаление ещё нужного блоба невосстановимо без повторного d8 mirror push, а хранение ненужного стоит только места на диске. Поэтому проход, который не может определить, что сохранять — например, когда не найден развёрнутый релиз, — не делает ничего вовсе.

Чтобы посмотреть состояние и расписание сборки, используйте команды:

Посмотреть последние сборки — что их запустило, чем они закончились и сколько освободили. Завершённая сборка хранится сутки:

d8 k get registryoperation -o wide

Посмотреть время последней сборки на каждой реплике и ошибки, если они были:

d8 k get registrystorage registry -o jsonpath='{.status.replicas}' | jq \
  'map({node, collectedAt, collectionError})'

Посмотреть текущее расписание сборки:

d8 k get registrystorage registry -o jsonpath='{.spec.garbageCollection}' | jq

Когда запускается сборка мусора и что происходит во время неё?

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

  • сборка мусора не начинается, пока кеш наполняется или реплицируется или пока идёт d8 mirror push, — она ждёт, пока запись закончится;
  • когда подходит очередь, реплика ещё раз проверяет хранилище: если за время ожидания началось наполнение или загрузка, она уступает очередь и снова ждёт;
  • прямо перед удалением блобов реплика проверяет хранилище ещё раз: если к этому моменту началась загрузка, блобы остаются до следующей сборки мусора;
  • пока идёт сборка мусора, реплика сама не наполняет и не реплицирует своё хранилище.

Реплика продолжает отдавать все свои образы во время сборки мусора, а при промахе кеша загружает образ из внешнего хранилища образов контейнеров. Не запускайте d8 mirror push во время сборки: сначала проверьте d8 k get registryoperation. Загрузка, начатая во время удаления блобов, может завершиться явной ошибкой, а может отчитаться об успехе и оставить образ неполным: слой, который уже был в хранилище, повторно не загружается, и сборка может его удалить. Такой образ потом не скачивается из-за отсутствующего блоба. Если загрузка пересеклась со сборкой мусора, повторите её после окончания сборки.

Одновременно сборку выполняет только одна реплика. Остальные работают как обычно.

Расписание задаётся в UTC. По умолчанию сборка назначается на ночной час, а если у NodeGroup master задано окно обслуживания — на его начало: этот час уже объявлен допустимым для перерывов. Чтобы задать своё расписание, используйте параметр storage.garbageCollection:

spec:
  settings:
    storage:
      garbageCollection:
        schedule: "0 2 * * Sun"

Нечитаемое cron-выражение отклоняется, а не угадывается, так как сборка в неожиданный час хуже, чем её отсутствие. По той же причине изменённое расписание отсчитывается от момента изменения: если время нового расписания уже прошло, сборка мусора не запускается сразу после изменения расписания. После повторного включения сборки мусора поведение аналогичное.

Сборка мусора также запускается когда все реплики получили новый набор образов: после обновления Deckhouse Platform или после включения или обновления модуля. Именно в этот момент образы, нужные только прежнему набору, становятся мусором. Выключение модуля набор не меняет: его образы хранятся на случай, если модуль включат снова.

Хранилище, которое отказывает в записи (из-за того, что вышло за бюджет или упёрлось в резерв свободного места на своей файловой системе), никогда не получит новый набор. Поэтому сборка мусора в нём запускается без ожидания: один раз на развёрнутый релиз Deckhouse Platform и снова после обновления или после того, как хранилище между делом начало принимать запись. Если такая сборка мусора завершилась ошибкой, она повторяется через четыре часа после завершения.

Каждая сборка мусора — это объект RegistryOperation с типом GarbageCollection, независимо от того, чем она инициирована. Одновременно выполняется только одна сборка мусора: срабатывание расписания во время другой сборки пропускается, а сборка для нового набора образов ждёт, пока текущая закончится.

Как оценить необходимость сборки мусора в текущий момент?

Каждая реплика хранилища оценивает, сколько освободит сборка мусора в её хранилище, и отдаёт оценку в Prometheus метрики:

  • d8_registry_storage_reclaimable_bytes — сколько байт сборка освободит сейчас. Ноль означает, что сборка ничего не освободит.
  • d8_registry_storage_reclaimable_estimated_timestamp_seconds — когда сделана оценка.

У обеих метрик есть лейбл node с узлом реплики. До первой оценки реплика их не отдаёт.

Реплика делает оценку:

  • при изменении набора образов, нужного кластеру;
  • после сборки мусора на этой реплике;
  • в остальное время раз в 30 минут, и не чаще одного раза в 5 минут.

Оценка не выполняется:

  • во время наполнения кеша;
  • во время загрузки образов в хранилище (d8 mirror push);
  • во время сборки мусора.

Поэтому при просмотре оценки обращайте внимание на её время. Хранилище, которое отказывает в записи, оценивается как обычно: именно тогда сборка мусора нужнее всего.

Чтобы увидеть оценку по всем репликам, выполните в Prometheus запрос:

d8_registry_storage_reclaimable_bytes

Как запустить сборку мусора вручную?

Чтобы запустить сборку вручную, создайте объект RegistryOperation с типом GarbageCollection:

d8 k create -f - <<EOF
apiVersion: deckhouse.io/v1alpha1
kind: RegistryOperation
metadata:
  generateName: gc-manual-
spec:
  type: GarbageCollection
  cause: Освободить место перед загрузкой нового релиза.
EOF

Она выполняется, даже если автоматическая сборка выключена. Реплики собирают мусор по одной, так же как по расписанию. Реплика начинает сборку мусора, только когда в её хранилище ничего не пишется: пока кеш наполняется или идёт d8 mirror push, реплика ждёт, а причина видна в status.replicas[].reason. Хранилище, которое отказывает в записи, не ждёт: наполнение не продолжится, пока сборка не освободит место. Реплика, которая всё ещё ждёт через час после принятия операции, завершается с причиной DeadlineExceeded. Операция, созданная во время другой, завершается с причиной AnotherOperationActive.

Для отслеживания операции и просмотра того, что удалено, используйте команду:

d8 k get registryoperation <NAME> -o jsonpath='{.status}' | jq \
  '{phase, reason, message, garbageCollection}'

Чтобы отменить операцию, в том числе уже выполняемую репликой, поставьте на неё лейбл отмены:

d8 k label registryoperation <NAME> registry.deckhouse.io/cancel=true

Всё, что было удалено до отмены операции остаётся удалённым и не восстанавливается.

Если у реплики перестаёт отвечать контейнер syncer, пока она собирает мусор или ждёт своей очереди (например, её master-узел перешёл в NotReady), реплика завершается с причиной ReplicaLost, чтобы операция не держала все следующие сборки мусора сутки:

  • реплика, которая собирала мусор, — когда она пять минут не держит Lease registry-storage-gc в неймспейсе d8-system;
  • реплика, которая ждала, — когда её узел десять минут не в состоянии Ready. Если master-узел вернулся раньше, его реплика сохраняет своё место в очереди.

Реплику, которая ждёт на узле в состоянии Ready, пока её syncer не отвечает, освобождает лейбл отмены, истечение 24 часов (причина TimedOut) или удаление операции:

d8 k delete registryoperation <NAME>

Как выключить сборку мусора?

Чтобы выключить автоматическую сборку мусора задайте значение false для параметра storage.garbageCollection:

spec:
  settings:
    storage:
      garbageCollection:
        enabled: false

Это имеет смысл только с диском, размера которого хватит при неограниченном росте хранилища. Обратите внимание: алерт D8RegistryStorageNotReclaimed всё равно сработает через неделю после последней сборки — снаружи «выключено» и «молча перестало работать» выглядят одинаково.

Сборка мусора, созданная вручную, выполняется, даже если автоматическая выключена.

Что происходит, когда хранилище кеша заполнено?

У хранилища на каждом master-узле два предела, и registry проверяет оба при каждой записи:

  • бюджет — storage.size в ModuleConfig registry, сколько хранилище может занимать;
  • резерв — сколько места на файловой системе хранилища должно оставаться свободным. Если файловая система общая с узлом, это мягкий порог выселения kubelet (10% файловой системы, не больше 40 ГиБ) плюс запас (10%, не больше 20 ГиБ). Если у хранилища свой диск (dedicatedFilesystem: true в store реплики), остаётся только запас. Оба считаются от текущего размера файловой системы, поэтому расширенный при работающем хранилище диск сдвигает резерв без перезапуска. Резерв действует при любом storage.size, в том числе незаданном.

Резерв считается от полного размера файловой системы, а свободное место — так же, как его считает kubelet: без блоков, которые файловая система держит для root. На ext4 это по умолчанию 5%, поэтому на файловой системе меньше 200 ГиБ хранилищу и всему остальному на ней достаётся около 75% диска, а не 80%. На файловой системе, выделенной под хранилище, резерв для root можно уменьшить командой tune2fs -m.

Когда достигнут любой из пределов, хранилище отклоняет новые записи и продолжает отдавать всё, что в нём есть:

  • наполнение и репликация останавливаются. Почему хранилище отказывает в записи, видно в поле store реплики (writable: false и reason, см. ниже), а в .status.replicas[].error — ошибка остановившегося наполнения или репликации;
  • d8 mirror push получает 507 Insufficient Storage с причиной и способом исправить ещё до того, как отправит данные загрузки. Блоб больше оставшегося места может быть отклонён и посреди загрузки, с ответом 500; повторите push, когда место появится;
  • при промахе кеша образ, пока настроен upstream, приходит из upstream, и узлы этого не замечают: слои, которые хранилище не может сохранить, отдаются потоком без сохранения, а запрос манифеста, который хранилище не смогло записать, завершается в хранилище ошибкой, и агент берёт образ из upstream. В изолированном кластере релиз, которого нет в хранилище, установить нельзя.

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

  • реплика копирует следующий релиз заранее, до обновления, только пока место, которое у неё осталось в бюджете и на файловой системе сверх резерва, составляет хотя бы пятую часть бюджета (или файловой системы, если storage.size не задан); иначе копирование заранее пропускается, и релиз загружается в хранилище после развёртывания. При заданном upstream это относится ко всем репликам;
  • в изолированном кластере следующий релиз приходит на лидера через d8 mirror push, а сборка мусора не удаляет ради него ни развёрнутый, ни предыдущий релиз. Остальные реплики копируют его с лидера по тому же правилу, поэтому реплика, которой не хватает места, получит релиз только после развёртывания.

Поэтому задавайте storage.size под три релиза вместе с модулями и каталогом. Хранилище держит объединение их образов: общий для релизов слой хранится один раз.

Ради места ничего не удаляется. Место освобождает сборка мусора, либо его добавляют, увеличив storage.size или диск под хранилищем.

Посмотреть состояние каждой реплики:

d8 k get registrystorage registry -o json | jq '.status.replicas[] | {node, store}'

writable: false с reason: BudgetExhausted значит, что достигнут storage.size: увеличьте его, если на диске есть место, или дождитесь, пока сборка мусора освободит то, что не нужно развёрнутым релизам. reason: ReserveExhausted значит, что закончился диск. Если файловая система общая с узлом, освободите место на узле или перенесите хранилище на отдельный диск. Если у хранилища свой диск, расширьте его или дождитесь, пока сборка мусора освободит место. reason: NotWritable — не предел: registry не может создавать файлы в хранилище, а каталог и команду, которая это исправляет, указывает .status.replicas[].error.

Диск хранилища не смонтировался. Что происходит?

Если в прошлый раз хранилище было на своём диске (dedicatedFilesystem: true), а теперь этот диск не смонтирован, например после перезагрузки, хранилище запускается на файловой системе узла и наполняется там. Реплика сообщает об этом в .status.replicas[].error, пока диска нет, и продолжает сообщать после того, как хранилище наполнилось. Реплика с ошибкой не считается полной:

  • лидером она не остаётся, пока полна другая реплика: лидером становится та;
  • если она лидер и других полных реплик нет, например на единственном master-узле, фаза RegistryStorage — Failed, и переход в air-gap ждёт;
  • через два часа срабатывает D8RegistryStorageIncomplete.

Чтобы это исправить, смонтируйте диск до запуска kubelet (в /etc/fstab без nofail) и удалите под реплики на этом узле. Чтобы оставить хранилище на файловой системе узла намеренно, удалите файл .filesystem-before в каталоге хранилища на узле, а затем под реплики:

d8 k -n d8-system delete pod -l app=registry-storage --field-selector spec.nodeName=<NODE>

На узле не загружается образ. Куда смотреть?

Начните с агента: он стоит на пути каждой загрузки на узле. Агент разворачивается в виде статического пода, поэтому доступен, даже когда кластер — нет.

Агента проверяет kubelet — по адресу, который использует container runtime, 127.0.0.1:5001, — и перезапускает его, если тот не отвечает минуту. Если агент остаётся неготовым, срабатывает D8RegistryAgentNotReady, если он постоянно перезапускается — D8RegistryAgentRestartingTooOften. Ни один из них не сообщает об агенте, который отвечает, но не может подключиться к API-серверу: такой агент готов.

Чтобы посмотреть логи агента, используйте команду:

d8 k -n kube-system logs -l component=registry-agent --tail=100

Чтобы посмотреть, какую конфигурацию агент получил и согласен ли он с кластером, используйте команду:

d8 k get registrynode <NODE> -o jsonpath='{.status}' | jq

Метрики агента — его собственный взгляд на проходящие через него загрузки. Prometheus собирает их через node exporter модуля monitoring-kubernetes: раз в 30 секунд агент записывает их в директорию textfile node exporter’а, /var/run/node-exporter-textfile/registry-agent.prom. Поэтому серии d8_registry_agent_* приходят с job="node-exporter" и именем узла в метке node, например:

sum by (node, kind, result) (rate(d8_registry_agent_requests_total[5m]))

Напрямую агент никто не опрашивает: он работает статическим подом именно потому, что должен работать при недоступном API-сервере, а kube-rbac-proxy рядом с ним аутентифицировался бы в том самом API-сервере. Без monitoring-kubernetes серии не собираются. На самом узле те же метрики вместе с метриками Go runtime агента отдаются на loopback-адресе:

ssh <NODE> 'curl -s http://127.0.0.1:4286/metrics | grep d8_registry_agent'

Конфигурация, выданная container runtime. Это один файл независимо от того, сколько registry настроено:

ssh <NODE> 'cat /etc/containerd/registry.d/_default/hosts.toml'

Если этого файла нет, агент ещё не применил конфигурацию: на узле не загрузится ничего, а причина — в логе агента. Если файл есть, а загрузки всё равно завершаются ошибкой, отказ находится за агентом — метрики выше называют, какая цель отказала и почему.

containerd может загружать образы и в обход агента, так задумано. В _default/hosts.toml нет ключа server, поэтому containerd оставляет исходное хранилище образов контейнеров последним хостом и идёт туда напрямую, если агент не отвечает или отвечает 404 либо другим кодом ошибки. Так образы из публичных хранилищ загружаются и при остановленном агенте, но прямая попытка не получает ничего из того, что добавляет агент:

  • учётных данных кластера — только pull secret самого пода, если он есть;
  • маршрутов RegistryUpstream, зеркал и кеша;
  • сертификата CA частного хранилища образов контейнеров, поэтому обращение к нему обычно завершается ошибкой x509;
  • внутрикластерного адреса: registry.d8-system.svc:5001 на узле не резолвится, поэтому образы платформы так не загрузить вообще.

Какую ошибку containerd сообщает, когда загрузка не удалась, зависит от шага, на котором она произошла, и от версии containerd. При разрешении ссылки на образ, тега или дайджеста:

  • containerd 1.7 (Containerd) сообщает первую полученную ошибку, отличную от 404. Если агент не ответил или ответил кодом ошибки, это ошибка агента, хотя прямая попытка после неё тоже была: отказ в соединении или таймаут TLS-рукопожатия с адресом агента либо код ошибки, например 502 Bad Gateway. Ошибку прямой попытки (no such host, 401, x509) containerd сообщает, только если агент ответил 404, и тогда она скрывает, что агент не нашёл образ.
  • containerd 2.2 (ContainerdV2) ставит код ошибки, отличный от 404, выше 404, а 404 — выше неудавшегося соединения; из двух ошибок одного вида он сообщает ошибку агента. Поэтому код ошибки от агента, например 502 Bad Gateway, виден всегда. Неудавшееся соединение с агентом видно, только если и прямая попытка не смогла соединиться, а неудавшееся соединение прямой попытки (no such host, x509) не видно никогда. В остальных случаях виден ответ прямой попытки: её код ошибки, например 403, или not found при её 404. Ответ агента 404 сообщается как not found, если только хранилище не ответило прямой попытке кодом ошибки.

В любом случае сначала смотрите лог и метрики агента. Если и прямая попытка отвечает 404, как для отсутствующего тега в публичном хранилище, загрузка завершается ошибкой not found. При загрузке манифеста по дайджесту, конфигурации образа и слоёв обе версии сообщают ошибку агента, какой бы она ни была, в том числе 404: слой, которого нет у агента, завершает загрузку ошибкой not found, даже если прямая попытка после этого не удалась с другой ошибкой.

Пока агент не отвечает, загрузки к тому же идут долго: на тестовом кластере с замороженным агентом загрузка образов платформы завершалась ошибкой примерно через 20 секунд (таймаут TLS-рукопожатия с агентом), а образы из публичных хранилищ приходили по прямому пути примерно через 50 секунд.

Модули из других ModuleSource: что хранит кеш и что сделать перед air-gap

Кеш хранит все модули, которые запущены в кластере, из какого бы ModuleSource они ни были установлены, и учитывает их в полноте: кластер не переходит в air-gap, пока в хранилище не хватает хотя бы одного из них.

  • Модуль, чей ModuleSource находится в реестре upstream, заливается из upstream, как и сама платформа.
  • Модуль, чей ModuleSource находится в отдельном реестре, заливается из этого реестра с учётными данными и центром сертификации, указанными в ModuleSource.

Собственные модули платформы (ModuleSource deckhouse) хранятся в system/deckhouse/modules. У каждого другого ModuleSource во внутрикластерном реестре свой путь, system/deckhouse/module-sources/<ModuleSource>: модули — в <путь>/<модуль>, список модулей — тегами самого <путь>. Путь отдельный, потому что путь платформы, пока настроен upstream, отражает upstream, и модуль другого источника с тем же именем, что у модуля платформы, был бы там заменён сборкой из upstream.

Только из этого пути узел сможет загрузить модули источника, когда upstream отключён. Но поды модуля продолжают ссылаться на реестр своего ModuleSource, пока источник не изменён. Поэтому перед отключением upstream направьте каждый такой ModuleSource на его путь, с настройками реестра собственного источника платформы:

NAME=<ModuleSource>
REGISTRY=$(d8 k get modulesource deckhouse -o json | jq -c --arg name "$NAME" \
  '.spec.registry | .repo = "registry.d8-system.svc:5001/system/deckhouse/module-sources/" + $name')
d8 k patch modulesource "$NAME" --type merge -p "{\"spec\":{\"registry\":$REGISTRY}}"

После этого образы модуля рендерятся с внутрикластерным адресом и отдаются из кеша.

Что нужно из хранилища для удаления изолированного облачного кластера?

dhctl destroy облачного кластера, провайдер которого не встроен в установщик (например, Deckhouse Virtualization Platform), использует бандл этого провайдера: в нём схемы, модули и плагины OpenTofu. dhctl берёт бандл из своего каталога загрузок (--download-dir, по умолчанию /tmp/dhctl), если он там есть, а иначе загружает из реестра, который указан в кластере. У изолированного кластера нет upstream, поэтому бандл загружается из собственного хранилища кластера через SSH-подключение dhctl к master-узлу. Если хранилище пустое или в нём нет этого образа, удаление останавливается на шаге Get cluster configuration с ошибкой MANIFEST_UNKNOWN. Проще всего запустить dhctl в контейнере, где этот бандл уже загружен, например в том, где выполнялась предыдущая операция с этим кластером. Иначе сохраняйте хранилище до удаления кластера или доставьте бандл сами: на машине с доступом к публичному реестру загрузите образ с указанным в ошибке дайджестом из репозитория образов платформы, из которого установлен кластер (например, registry.deckhouse.io/deckhouse/<edition>; system/deckhouse в адресе из ошибки — лишь имя этого репозитория в хранилище). Этот образ входит и в бандл d8 mirror этого релиза. Распакуйте образ в каталог, указанный в ошибке.

Как загрузить новый релиз Deckhouse Platform или новую версию модуля в изолированный кластер?

Когда upstream убран из конфигурации и из кластера нет доступа в интернет, новые образы попадают во внутрикластерный кеш только через d8 mirror push. Push принимает лидер кеша, остальные реплики копируют образы с него. Как только релиз оказался в кеше, кластер видит его так же, как видел бы в upstream, и обновляется по обычным правилам: по каналу обновлений, в окна обновлений, с ручным подтверждением, если оно включено.

Возвращать upstream для этого не нужно, менять storage.source тоже. Полнота кеша проверяется по набору образов, который нужен кластеру, а не по expectedDigests. Сборка мусора не удаляет релизы новее развёрнутого, поэтому загруженный релиз останется в хранилище до развёртывания.

Шаг 1. Скачайте образы на машине с доступом в интернет

Узнайте редакцию и версию Deckhouse Platform в кластере:

d8 k -n d8-system get deployment deckhouse -o json | jq -r '.metadata.annotations | {"core.deckhouse.io/edition","core.deckhouse.io/version"}'

Скачайте релизы Deckhouse Platform, начиная с минорной версии кластера. Минорные версии устанавливаются по очереди, поэтому в пакете должны быть все промежуточные, и --since-version их скачивает:

d8 mirror pull --source='registry.deckhouse.ru/deckhouse/<EDITION>' --license='<LICENSE_KEY>' \
  --since-version='<X.Y>' ./d8-bundle

Чтобы обновить только модуль, не скачивая платформу, укажите его текущую версию. Будут скачаны эта версия, более новые и версии на каналах обновлений:

d8 mirror pull --source='registry.deckhouse.ru/deckhouse/<EDITION>' --license='<LICENSE_KEY>' \
  --no-platform --include-module='<MODULE>@<VERSION>' ./d8-bundle

Как сократить объём пакета и уточнить список модулей, описано в руководстве «Обновление DP в закрытом окружении».

Перенесите пакет на машину, с которой будете выполнять d8 mirror push. Проверьте, что в хранилище кеша хватит места: при заполненном хранилище push получает 507 Insufficient Storage (подробнее — в разделе «Что происходит, когда хранилище кеша заполнено»).

Шаг 2. Проверьте эндпоинт публикации

Образы попадают в кеш только через эндпоинт публикации — Ingress registry-push в неймспейсе d8-system, который передаёт push лидеру кеша. Push, отправленный напрямую на master-узел в обход Ingress, отклоняется: порт, который там принимает запись, принимает её только от ingress-контроллера и от самого кеша (подробнее — в разделе «Чем защищены порты на master-узлах»).

Проверьте, есть ли в кластере Ingress registry-push и обслуживает ли его ingress-контроллер:

d8 k -n d8-system get ingress registry-push -o jsonpath='{.spec.ingressClassName}{"\t"}{.spec.rules[0].host}{"\n"}'
d8 k get ingressclass
  • Ingress есть, и его класс есть среди IngressClass — переходите к шагу 3.
  • Ingress есть, но его класса нет среди IngressClass — укажите в параметре ingressClass ModuleConfig registry класс существующего контроллера, после чего переходите к шагу 3.
  • Ingress нет — он создаётся, только если задан publicDomainTemplate и включён модуль cert-manager. Задайте параметр и включите модуль: Ingress появится при следующем запуске модуля registry. Если Ingress в кластере невозможен, укажите в primary.upstream доступное из кластера хранилище образов контейнеров, в котором есть нужные образы, дождитесь, пока кеш наполнится из него, и снова уберите upstream.

Команды d8 k в следующих шагах выполняются там, где есть доступ к API кластера. Если пакет лежит на другой машине, перенесите туда полученные значения.

Шаг 3. Загрузите образы

HOST=$(d8 k -n d8-system get ingress registry-push -o jsonpath='{.spec.rules[0].host}')
PUSH_SECRET=$(d8 k -n d8-system get secret registry-storage-push -o json)
d8 mirror push ./d8-bundle "$HOST/system/deckhouse" \
  --registry-login="$(echo "$PUSH_SECRET" | jq -r .data.username | base64 -d)" \
  --registry-password="$(echo "$PUSH_SECRET" | jq -r .data.password | base64 -d)"

Что нужно для загрузки:

  • Имя из $HOST разрешается в адрес ingress-контроллера на машине, с которой выполняется push.
  • Если задан whitelistSourceRanges, адрес этой машины входит в список.
  • Машина доверяет сертификату Ingress. В изолированном кластере Let’s Encrypt сертификат не выпустит, поэтому обычно используется собственный ClusterIssuer или режим CustomCertificate (параметр https). Сертификат центра сертификации, которому машина не доверяет, передайте через переменную окружения SSL_CERT_FILE.
  • У кеша есть лидер. Пока лидера нет, push отклоняется; состояние реплик смотрите в статусе RegistryStorage (подробнее — в разделе «Как посмотреть состояние внутрикластерного кеша»). Если лидер сменился во время push, например из-за перезагрузки master-узла, выполните команду ещё раз.

Не выполняйте push, пока идёт сборка мусора: сначала проверьте d8 k get registryoperation. Push, который пересёкся со сборкой, может завершиться ошибкой, а может сообщить об успехе и оставить образ неполным. Если push пересёкся со сборкой, повторите его после её окончания (подробнее — в разделе «Когда запускается сборка мусора и что происходит во время неё?»).

Шаг 4. Проверьте, что релиз дошёл до кластера

Проверьте состояние кеша. Остальные реплики копируют новый релиз с лидера до его развёртывания:

d8 k get registrystorage registry -o jsonpath='{.status}' | jq '{phase,fill,leader,allReplicasFull}'

Проверьте, что кластер увидел новый релиз Deckhouse Platform или модуля:

d8 k get deckhousereleases
d8 k get modulereleases

Дальше релиз разворачивается по настройкам обновления Deckhouse Platform и модулей.

Алерты доступности образов от extended-monitoring для внутрикластерного реестра

Когда реестром управляет модуль, все ссылки на образы в кластере указывают на registry.d8-system.svc:5001. Узлы загружают образы по этому адресу через агента узла на loopback-адресе, а не через кластерный DNS. Экспортер доступности образов модуля extended-monitoring проверяет образы из пода, где имя ищется в кластерном DNS, поэтому сообщает о каждом таком образе алертом …ImageAvailabilityUnknownError:

  • без внутрикластерного кеша или пока ни одна реплика хранилища не готова, имя из пода не резолвится: no such host;
  • с кешем имя принадлежит headless Service и резолвится в IP master-узлов, на которых работают готовые реплики хранилища. Хранилище отвечает там с сертификатом, выпущенным собственным CA модуля, которому экспортер не доверяет: x509: certificate signed by unknown authority.

С самими образами всё в порядке: то, что обнаружил бы экспортер, покрывают алерты этого модуля — D8RegistryStorageIncomplete, D8RegistryUpstreamProbeFailing, D8RegistryNodeNotConverged. Исключите внутрикластерный адрес из проверок экспортера:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: extended-monitoring
spec:
  version: 2
  settings:
    imageAvailability:
      ignoredImages:
      - 'registry\.d8-system\.svc:5001/.*'

Каждый элемент — регулярное выражение. Образы из других реестров по-прежнему проверяются.

Как посмотреть состояние внутрикластерного кеша?

Состояние кеша публикуется в статусе ресурса RegistryStorage. Для его просмотра используйте команду:

d8 k get registrystorage registry -o jsonpath='{.status}' | jq

Описание полей ответа:

  • replicas — единственное место, где сообщается информация о полноте кеша; каждая запись — отчёт реплики о самой себе. Реплика с full: true рядом с error полной не считается: full говорит о том, что она держит, а ошибка — о том, завершился ли её последний проход или перестали ли работать её хранилище образов или диск (см. leader). syncerStartedAt — время запуска синкера, записавшего запись; выставляется, когда этот синкер прочитал своё хранилище. Upstream снимается, только если в записи лидера стоит время запуска синкера, который работает в его поде сейчас.
  • leader — реплика, которая наполняется из внешнего хранилища образов контейнеров и служит источником репликации для остальных. Выборы намеренно несимметричны: когда у какой-то реплики появляется полный набор, лидер, который не может собрать его сам, уступает ей. Лидер не может собрать набор сам, если нет внешнего хранилища образов, если его последний проход завершился ошибкой, если его хранилище отказывает в записи или если он перестал продлевать lease лидера. Именно это не даёт изолированному кластеру застрять в ситуации, когда лидер пуст, а полный набор есть только у другой реплики. Лидер, который ещё собирает набор из внешнего хранилища, остаётся лидером: последователь копирует данные с него и может закончить раньше, и передача лидерства в этот момент ничего не даёт. Реплика на узле, недоступном около двух минут, в выборах не учитывается, а реплика, чьё хранилище образов перестало отвечать или чей диск перестал принимать запись, сообщает об этом в healthError и error и уступает лидерство полной реплике, если такая есть. Лидер, чьё хранилище потеряло набор (на его диске нет развёрнутого релиза или большей части выборки набора, или totalDigests не больше половины verifiedDigests), уступает лидерство реплике, полной для текущего набора, сообщает full: false и verifiedDigests: 0 и копирует набор с неё. Если такой реплики нет, он остаётся лидером, но всё равно сообщает full: false и verifiedDigests: 0 и заново наполняет набор из upstream (в изолированном кластере — снова пересчитывает своё хранилище, а набор вернётся только после нового d8 mirror push).

Какие образы лежат в кеше?

Все образы кеша по digest манифеста показывает ресурс RegistryImage группы registry.deckhouse.io. Он нигде не хранится: каждый запрос опрашивает все реплики кеша, а реплика отвечает из индекса в памяти, который перестраивает, читая своё хранилище раз в две минуты и после каждой операции. Ответ всегда актуален, а его формирование не нагружает диски master-узлов.

Примеры запросов:

d8 k get registryimages
d8 k get registryimages -o wide
d8 k get registryimages -l registry.deckhouse.io/module=prometheus
d8 k get registryimages -l registry.deckhouse.io/state=Corrupted
d8 k get registryimages -l registry.deckhouse.io/in-set=false
d8 k get registryimage sha256-<digest> -o yaml
d8 k explain registryimages

Содержание полей образа в ответе:

  • owners — все места, где используется образ: модуль и имя образа из images_digests.json, релизы Deckhouse Platform или версии модуля, которые его объявляют. Один digest может использоваться несколькими модулями, в этом случае перечислены все модули.
  • inSet — релиз или модуль кластера, в котором используется образ. Образ вне набора или оставшийся от старого релиза может быть отображен, в дальнейшем его удалит сборщик мусора. Удалить такой образ вручную нельзя.
  • state и replicas[].state — состояние образа на каждой реплике:
    • Present — у реплики есть манифест и все блобы образа;
    • Missing — образа из набора у реплики нет совсем;
    • Incomplete — у реплики есть манифест, но не хватает части блобов: такое может произойти в случае, если pull-through-кеш отдал только манифест;
    • Corrupted — один из блобов образа не совпадает со своим digest;
    • Unknown — реплика не ответила или ещё не прочитала хранилище после запуска. Если не может ответить ни одна реплика, запрос завершается ошибкой ServiceUnavailable с причиной по каждой реплике.
  • size — полный объём образа: манифест и все слои, каждый по одному разу.
  • reclaimableSize — объём освобождаемого места на реплике при удалении только этого образа.

Образ состоит из слоёв, а слой, общий для нескольких образов, хранится в одном экземпляре. Поэтому объёмы всех образов в сумме больше, чем кеш занимает на диске, а удаление одного образа освобождает только те слои, которые не использует ни один другой образ: reclaimableSize. Образы платформы делят мало слоёв, поэтому обычно значения reclaimableSize и size близки.

Счётчики по состояниям присутствуют в статусе RegistryStorage в поле replicas[].images и остаются там, пока registry-controller не работает. В это время группа registry.deckhouse.io не обслуживается: kubectl api-resources выдаёт для неё ошибку, а удаляемые неймспейсы остаются в Terminating с условием NamespaceDeletionDiscoveryFailure пока не ответит хотя бы одна реплика контроллера. Одновременно срабатывает алерт D8RegistryControllerDown.

Для чтения RegistryImage нужны права на выполнение операций get и list на registryimages группы registry.deckhouse.io. Для этого у пользователя должно быть RBACv2-право registry.view.

Какие образы занимают больше всего места?

Отсортируйте список по size или reclaimableSize. kubectl сортирует по возрастанию, поэтому самые большие образы оказываются в конце вывода, а образы без размера (например, Missing) — в начале. Сортировка сочетается с любым селектором по меткам.

# 20 самых больших образов.
d8 k get registryimages --sort-by=.size | tail -n 20
# 20 образов, которые занимают больше всего места только под себя: их слои не использует
# ни один другой образ. С -o wide видны оба объёма.
d8 k get registryimages --sort-by=.reclaimableSize -o wide | tail -n 20
# Самые большие образы вне набора — их удалит сборка мусора.
d8 k get registryimages -l registry.deckhouse.io/in-set=false --sort-by=.reclaimableSize -o wide | tail -n 20
# Образы одного модуля по размеру.
d8 k get registryimages -l registry.deckhouse.io/module=prometheus --sort-by=.size

Как проверить и починить образы в кеше?

Каждая реплика раз в час читает своё хранилище в фоне и сверяет каждый блоб с его digest. Скорость чтения около 4 МиБ/с на хранилище в 15 ГБ, максимальная скорость чтения 16 МиБ/с. Ядро сбрасывает прочитанное из страничного кеша, чтобы etcd и API-сервер на том же master-узле не реагировали на нагрузку. Загрузку образов это не блокирует. Время окончания последнего полного прохода отображается в поле RegistryStorage.status.replicas[].scrubbedAt.

Блоб, не совпадающий со своим digest, записывается в RegistryStorage.status.replicas[].corruptedBlobs, а образы, которые его используют, получают состояние Corrupted. Затем:

  • Пока образ из набора использует битый блоб, реплика не считается full. Лидер в этом случае передаёт lease реплике, у которой набор не имеет битых блобов, и узлы скачивают образы с неё.
  • Модуль создаёт RegistryOperation с типом Repair для битых блобов, как только не выполняется никакая другая операция. Repair скачивает целую копию каждого битого блоба с другой реплики или из upstream (если он доступен), сверяет её с digest и только после этого заменяет. Блоб, для которого целой копии не нашлось, остаётся как был.
  • Один Repair берёт до 50 блобов. Если он исправил не всё, Repair повторяется через четыре часа, а если битых блобов больше 50 — перезапускается со следующей партией. Через два часа срабатывает алерт D8RegistryStoreCorrupted.

Чтобы проверить хранилище вручную, создайте ресурс RegistryOperation с типом операции Verify:

apiVersion: deckhouse.io/v1alpha1
kind: RegistryOperation
metadata:
  generateName: verify-
spec:
  type: Verify
  # Необязательно: только эти образы или блобы и только эти реплики.
  verify:
    digests: ["sha256:<digest>"]
    nodes: ["<master-node>"]

Скорость чтения при этом достигает 32 МиБ/с, хранилище в 15 ГБ будет проверено примерно за восемь минут на реплику, по одной реплике за раз.

Чтобы исправить образы вручную, например после повторной загрузки релиза через d8 mirror push, создайте ресурс RegistryOperation с типом операции Repair с их digest (до 50):

apiVersion: deckhouse.io/v1alpha1
kind: RegistryOperation
metadata:
  generateName: repair-
spec:
  type: Repair
  repair:
    digests: ["sha256:<digest>"]

Repair целого образа отображает Intact, когда все блобы совпадают с digest. Результат по каждому digest — в status.replicas[].repair.digests операции. Одновременно выполняется только одна операция. Если операция была создана во время сборки мусора, она завершается с причиной AnotherOperationActive, и её нужно создать заново.

Для создания операций нужно RBACv2-право registry.edit.

Как обновляется кеш?

Новый релиз Deckhouse Platform может менять образы самого кеша — StatefulSet registry-storage в d8-system. У StatefulSet стратегия обновления OnDelete, и его реплики заменяет registry-controller: по одной, сначала последователей, лидера последним и только пока все остальные реплики готовы. Реплику на старой ревизии, которая ни разу не запускалась или находится в CrashLoopBackOff, контроллер заменяет сразу.

Заменённая реплика загружает свои новые образы уже после удаления, из того кеша, частью которого была. Поэтому контроллер заменяет реплику, только если эти образы есть кому отдать:

  • последователя — лидер продолжает работать;
  • лидера — когда у последователя есть полный набор образов. Lease затем забирает та реплика с полным набором, которая успеет первой: любой последователь, у которого он есть, или новый под лидера, который поднимается на том же узле с тем же хранилищем;
  • любую реплику — внешнее хранилище образов контейнеров, если оно у кластера есть.

Один master-узел в изолированном кластере

Если реплика одна, а внешнего хранилища образов контейнеров нет, отдать образы некому. Значит, новые образы должны оказаться на master-узле до замены реплики. Для этого модуль запускает DaemonSet registry-storage-image-holder: на каждом master-узле он запускает каждый образ пода кеша как /pause. Когда образы меняются, под DaemonSet загружает новые из работающего кеша, и, пока они запущены, kubelet не удаляет их с узла. Как только под DaemonSet на master-узле запустил все новые образы, контроллер заменяет реплику, и новый под запускается с образами, которые уже есть на узле.

Пока единственная реплика кеша перезапускается, узлы кластера не могут загружать из него образы. Продолжительность перерыва зависит от остановки старой реплики и запуска новой. Неудачные попытки загрузки kubelet повторяет с нарастающей задержкой до 5 минут. Поэтому некоторые поды могут запуститься уже после восстановления кеша, с дополнительной задержкой.

Под DaemonSet запрашивает 10m CPU и 10Mi памяти на каждый образ на каждом master-узле, всего 40m и 40Mi. DaemonSet держит образы на всех master-узлах, но контроллер опирается на него, только когда у кеша одна реплика и нет внешнего хранилища образов контейнеров.

Несколько master-узлов в изолированном кластере

Лидер заменяется последним и только после того, как у какого-то последователя появится полный набор образов. Иначе лидерство перейдёт к последователю, у которого не хватает образов, и образы, которые были только у прежнего лидера, пропадут из кластера. DaemonSet registry-storage-image-holder эту проверку не заменяет. Последователь подходит, только если его полнота проверена для того же набора, что и у лидера: после обновления, которое меняет релиз Deckhouse Platform или модули, заменённый последователь сообщает о прежнем наборе, пока не скопирует новый. Обычно это значит, что нужно подождать, пока последователь скопирует набор с лидера. Если полного набора нет у самого лидера, последователи его тоже не соберут: они копируют с лидера. Тогда обновление продолжится, только когда в кеш будут загружены релиз Deckhouse Platform и модули, которые использует кластер.

Что означает событие UpdateBlocked

Пока контроллер ждёт, он пишет в StatefulSet событие UpdateBlocked. В событии указаны реплика, причина и условие, при котором ожидание закончится. Событие пишется снова, когда меняется то, от чего зависит ожидание, а если ничего не меняется — раз в пять минут, пока ожидание длится. Посмотреть события:

d8 k -n d8-system get events --field-selector involvedObject.name=registry-storage,reason=UpdateBlocked

Та же причина — лейбл reason метрики d8_registry_storage_update_blocked. Если ожидание длится дольше часа, срабатывает алерт D8RegistryStorageUpdateBlocked:

  • HolderNotReady — реплика одна, и под DaemonSet на её master-узле ещё не запустил все новые образы. Если его под в ImagePullBackOff, какого-то образа нет в кеше: загрузите релиз Deckhouse Platform, на который обновляется кластер, командой d8 mirror push, и под DaemonSet загрузит образ при следующей попытке. Если под в CrashLoopBackOff или CreateContainerError, образ уже есть на узле, но запустить его не получается, и загрузка не поможет: причина в событиях пода. Иначе под DaemonSet ещё обновляется или загружает образы, делать ничего не нужно.
  • SingleReplicaWithoutHolder — реплика одна, а у DaemonSet registry-storage-image-holder нет пода на её master-узле. Ненадолго это нормально, пока DaemonSet создаёт под на узле. Если состояние сохраняется, выясните, почему DaemonSet не размещает под на этом узле: d8 k -n d8-system describe daemonset registry-storage-image-holder.
  • LeaderWithoutFullFollower — осталось заменить только лидера, но ни у одного последователя нет полного набора. Если набор есть у лидера, дождитесь, пока последователь закончит копирование. Если лидер сообщает, что набора у него нет, скачайте релиз Deckhouse Platform и модули, которые использует кластер, командой d8 mirror pull, как описано в руководстве по обновлению в закрытом окружении, и загрузите их в кеш командой d8 mirror push, как в шаге 2 раздела «Переход в air-gap». Если лидер ещё ничего не сообщил, сообщает об ошибке или не может определить, какой набор нужен кластеру, загрузка не поможет, а обновление продолжится только после успешного прохода лидера: смотрите журнал контейнера syncer в поде лидера.
  • LeaderNotServing — Lease хранилища указывает на master-узел, где нет работающей реплики. Он перейдёт сам, когда истечёт.
  • StorageUnknown — ресурса RegistryStorage ещё нет. Его создаёт контроллер. Если ресурс не появляется, смотрите журнал registry-controller.

Посмотреть, что делают поды DaemonSet и реплики:

d8 k -n d8-system get pods -l app=registry-storage-image-holder -o wide
d8 k get registrystorage registry -o jsonpath='{.status.replicas}' | jq

Кто может читать из внутрикластерного кеша и писать в него?

Реестр кеша принимает три учётные записи. Каждая из них ограничена путём платформы system/deckhouse и всем, что под ним: там кеш хранит платформу, её модули и модули других ModuleSource. Запрос к любому другому репозиторию отклоняется, какой бы учётной записью он ни был сделан.

Учётная запись Кто её использует Что ей разрешено
registry-ro агент на каждом узле pull; список репозиториев хранилища
registry-sync только поды самого кеша pull, push и delete: наполнение из upstream, репликация, сборка мусора
registry-rw d8 mirror push через эндпоинт публикации pull и push
  • Учётная запись для чтения есть на каждом узле, поэтому с ней нельзя изменить то, что загружают узлы.
  • Учётной записью sync в хранилище пишут изнутри кластера. Её пароль используют только поды кеша: контроллер модуля и registry-packages-proxy читают Secret registry-storage-client, в котором есть только центр сертификации, учётная запись для чтения и адреса реплик.
  • Учётная запись публикации предназначена для администратора платформы. Через неё новый релиз попадает в изолированный кластер, поэтому она может заменять образы платформы: кто может читать Secret registry-storage-push в d8-system, тот может подменить то, что загружают все узлы. Давайте доступ на чтение этого Secret только тем, кто публикует платформу. Удалять образы и получать список репозиториев хранилища эта учётная запись не может: образы удаляет сборка мусора.

Загружайте образы в путь платформы, <эндпоинт публикации>/system/deckhouse, как в примере перехода в air-gap. Загрузка в любой другой путь отклоняется.

Реализация v1

Информация ниже относится к кластеру, который всё ещё работает на реализации модуля v1 (DP до версии 1.77 включительно), настраиваемой через ModuleConfig deckhouse.

Как мигрировать на модуль registry?

Эта процедура переводит кластер с устаревшего формата (без модуля registry) на реализацию v1. Это не шаг миграции на текущую реализацию: кластеру в устаревшем формате подготовка к обновлению на DP 1.78 не нужна. См. раздел «Как устроена миграция на модуль registry».

Во время миграции, для containerd v1 будет выполнен переход на новую схему конфигурации хранилища образов контейнеров. containerd v2 использует новую схему по умолчанию. Подробнее можно ознакомиться в разделе с описанием способов конфигурации

Для containerd v2

  1. Выполните переключение на использование модуля registry. Для этого, укажите в ModuleConfig deckhouse параметры режима Unmanaged. Если используется хранилище образов контейнеров, отличное от registry.deckhouse.ru, ознакомьтесь с конфигурацией модуля deckhouse для корректной настройки.

    Посмотреть текущие настройки хранилища образов контейнеров можно с помощью команды:

    d8 k -n d8-system exec -it svc/deckhouse-leader -c deckhouse -- deckhouse-controller global values | yq e '.modulesImages.registry' -
    

    Данные настройки укажите при конфигурации Unmanaged режима:

    apiVersion: deckhouse.io/v1alpha1
    kind: ModuleConfig
    metadata:
      name: deckhouse
    spec:
      version: 1
      enabled: true
      settings:
        registry:
          mode: Unmanaged
          unmanaged:
            imagesRepo: registry.deckhouse.ru/deckhouse/ee
            scheme: HTTPS
            license: <LICENSE_KEY> # Замените на ваш лицензионный ключ
    
  2. Дождитесь завершения переключения. Пример статуса переключения:

    conditions:
    # ...
      - lastTransitionTime: "..."
        message: ""
        reason: ""
        status: "True"
        type: Ready
    hash: ..
    mode: Unmanaged
    target_mode: Unmanaged
    

Для containerd v1

  • Во время переключения containerd v1 сервис будет перезапущен.
  • Во время переключения containerd v1 будет переведен на новую схему конфигурации хранилища образов контейнеров.
  • Во время переключения, пользовательские конфигурации registry для containerd v1 будут временно недоступны.
  1. Убедитесь, что на узлах с containerd v1 отсутствуют пользовательские конфигурации хранилища образов контейнеров, расположенные в директории /etc/containerd/conf.d.

  2. Если конфигурации присутствуют, необходимо выполнить миграцию на новый формат конфигурации хранилища образов контейнеров в containerd. Для этого, необходимо добавить новые конфигурации в директорию /etc/containerd/registry.d. Данные конфигурации вступят в силу после переключения на модуль registry. Для добавления конфигураций подготовьте NodeGroupConfiguration, подробнее в разделе с описанием способов конфигурации. Пример:

    apiVersion: deckhouse.io/v1alpha1
    kind: NodeGroupConfiguration
    metadata:
      name: containerd-additional-config-auth.sh
    spec:
      # Шаг может быть любой, так как не требуется перезапуск сервиса containerd.
      weight: 0
      bundles:
        - '*'
      nodeGroups:
        - "*"
      content: |
        # Copyright 2023 Flant JSC
        #
        # Licensed under the Apache License, Version 2.0 (the "License");
        # you may not use this file except in compliance with the License.
        # You may obtain a copy of the License at
        #
        #     http://www.apache.org/licenses/LICENSE-2.0
        #
        # Unless required by applicable law or agreed to in writing, software
        # distributed under the License is distributed on an "AS IS" BASIS,
        # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
        # See the License for the specific language governing permissions and
        # limitations under the License.
           
        REGISTRY_URL=private.registry.example
    
        mkdir -p "/etc/containerd/registry.d/${REGISTRY_URL}"
        bb-sync-file "/etc/containerd/registry.d/${REGISTRY_URL}/hosts.toml" - << EOF
        [host]
          [host."https://${REGISTRY_URL}"]
            capabilities = ["pull", "resolve"]
            [host."https://${REGISTRY_URL}".auth]
              username = "username"
              password = "password"
        EOF
    
  3. Примените NodeGroupConfiguration. Дождитесь появления конфигурационных файлов в директории /etc/containerd/registry.d на всех узлах.

  4. Проверьте корректность работы конфигураций. Для этого воспользуйтесь командой:

    # Для https:
    ctr -n k8s.io images pull --hosts-dir=/etc/containerd/registry.d/ private.registry.example/registry/path:tag
    
    # Для http:
    ctr -n k8s.io images pull --hosts-dir=/etc/containerd/registry.d/ --plain-http private.registry.example/registry/path:tag
    
  5. Выполните переключение на использование модуля registry. Для этого, укажите в ModuleConfig deckhouse параметры режима Unmanaged. Если используется хранилище образов контейнеров, отличное от registry.deckhouse.ru, ознакомьтесь с конфигурацией модуля deckhouse для корректной настройки.

    Посмотреть текущие настройки хранилища образов контейнеров можно с помощью команды:

    d8 k -n d8-system exec -it svc/deckhouse-leader -c deckhouse -- deckhouse-controller global values | yq e '.modulesImages.registry' -
    

    Данные настройки укажите при конфигурации Unmanaged режима:

    apiVersion: deckhouse.io/v1alpha1
    kind: ModuleConfig
    metadata:
      name: deckhouse
    spec:
      version: 1
      enabled: true
      settings:
        registry:
          mode: Unmanaged
          unmanaged:
            imagesRepo: registry.deckhouse.ru/deckhouse/ee
            scheme: HTTPS
            license: <LICENSE_KEY> # Замените на ваш лицензионный ключ
    
  6. После применения, дождитесь в статусе переключения сообщение:

    Пример вывода:

    conditions:
    # ...
    - lastTransitionTime: "2025-08-13T15:22:34Z"
      message: |
        Check current nodes configuration
        2/2 node(s) Unready:
        - master-0: has custom toml merge containerd configuration
        - worker-5e389be0-578df-s5sm5: has custom toml merge containerd configuration
      reason: Processing
      status: "False"
      type: ContainerdConfigPreflightReady
    

    Данное сообщение означает, что на узлах имеются старые конфигурации хранилища образов контейнеров, расположенные в директории /etc/containerd/conf.d. И в данный момент переключение на новую конфигурацию containerd заблокировано. Для того чтобы разрешить переключение, необходимо удалить старые конфигурационные файлы.

  7. Удалите старые конфигурационные файлы, чтобы разрешить переключение на модуль registry. Для этого создайте NodeGroupConfiguration. Пример манифеста NodeGroupConfiguration:

    apiVersion: deckhouse.io/v1alpha1
    kind: NodeGroupConfiguration
    metadata:
      name: containerd-additional-config-auth-delete.sh
    spec:
      # Шаг должен выполниться до '032_configure_containerd.sh'
      weight: 0
      bundles:
        - '*'
      nodeGroups:
        - "*"
      content: |
        # Copyright 2023 Flant JSC
        #
        # Licensed under the Apache License, Version 2.0 (the "License");
        # you may not use this file except in compliance with the License.
        # You may obtain a copy of the License at
        #
        #     http://www.apache.org/licenses/LICENSE-2.0
        #
        # Unless required by applicable law or agreed to in writing, software
        # distributed under the License is distributed on an "AS IS" BASIS,
        # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
        # See the License for the specific language governing permissions and
        # limitations under the License.
    
        file="/etc/containerd/conf.d/old-config.toml"
    
        [ -f "$file" ] && rm -f "$file"
    
  8. После удаления старых конфигураций, убедитесь, что переключение продолжило выполняться. Пример статуса переключения:

    conditions:
    # ...
    - lastTransitionTime: "2025-08-13T16:42:09Z"
      message: ""
      reason: ""
      status: "True"
      type: ContainerdConfigPreflightReady
    
  9. Дождитесь завершения переключения. Пример статуса переключения:

    conditions:
    # ...
      - lastTransitionTime: "..."
        message: ""
        reason: ""
        status: "True"
        type: Ready
    hash: ..
    mode: Unmanaged
    target_mode: Unmanaged
    
  10. Удалите NodeGroupConfiguration, созданный на шаге удаления старых конфигурационных файлов:

    d8 k delete nodegroupconfiguration containerd-additional-config-auth-delete.sh
    

    Чтобы убедиться, что NodeGroupConfiguration удалён, используйте команду:

    d8 k get nodegroupconfiguration
    

    В списке не должно быть NodeGroupConfiguration, подлежащего удалению (в этом примере — containerd-additional-config-auth-delete.sh).

Как мигрировать обратно с модуля registry?

  • Это устаревший (deprecated) формат управления хранилищем образов контейнеров.
  • Во время переключения containerd v1 будет перезапущен.
  • Во время переключения containerd v1 будет переведен на старую схему конфигурации хранилища образов контейнеров.
  • Во время переключения, пользовательские конфигурации registry для containerd v1 будут временно недоступны.
  1. Переведите хранилище образов контейнеров в режим Unmanaged. Если используется хранилище образов контейнеров, отличное от registry.deckhouse.ru, ознакомьтесь с конфигурацией модуля deckhouse для корректной настройки.

    Пример конфигурации:

    apiVersion: deckhouse.io/v1alpha1
    kind: ModuleConfig
    metadata:
      name: deckhouse
    spec:
      version: 1
      enabled: true
      settings:
        registry:
          mode: Unmanaged
          unmanaged:
            imagesRepo: registry.deckhouse.ru/deckhouse/ee
            scheme: HTTPS
            license: <LICENSE_KEY> # Замените на ваш лицензионный ключ
    
  2. Проверьте статус переключения, используя инструкцию. Пример вывода:

    conditions:
    # ...
    - lastTransitionTime: "..."
      message: ""
      reason: ""
      status: "True"
      type: Ready
    hash: ..
    mode: Unmanaged
    target_mode: Unmanaged
    
  3. Переведите хранилище образов контейнеров в неконфигурируемый режим Unmanaged. Пример конфигурации:

    apiVersion: deckhouse.io/v1alpha1
    kind: ModuleConfig
    metadata:
      name: deckhouse
    spec:
      version: 1
      enabled: true
      settings:
        registry:
          mode: Unmanaged
    
  4. Проверьте статус переключения, используя инструкцию. Пример вывода:

    conditions:
    # ...
    - lastTransitionTime: "..."
      message: ""
      reason: ""
      status: "True"
      type: Ready
    hash: ..
    mode: Unmanaged
    target_mode: Unmanaged
    
  5. Если используется containerd v1, и в кластере применены пользовательские конфигурации registry, их необходимо заменить на старый формат. Для этого, подготовьте конфигурации хранилища образов контейнеров старого формата. Данные конфигурации на данном этапе применять не нужно. Пример конфигурации:

    apiVersion: deckhouse.io/v1alpha1
    kind: NodeGroupConfiguration
    metadata:
      name: containerd-additional-config-auth.sh
    spec:
      # Для добавления файла перед шагом '032_configure_containerd.sh'
      weight: 31
      bundles:
        - '*'
      nodeGroups:
        - "*"
      content: |
        # Copyright 2023 Flant JSC
        #
        # Licensed under the Apache License, Version 2.0 (the "License");
        # you may not use this file except in compliance with the License.
        # You may obtain a copy of the License at
        #
        #     http://www.apache.org/licenses/LICENSE-2.0
        #
        # Unless required by applicable law or agreed to in writing, software
        # distributed under the License is distributed on an "AS IS" BASIS,
        # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
        # See the License for the specific language governing permissions and
        # limitations under the License.
    
        REGISTRY_URL=private.registry.example
    
        mkdir -p /etc/containerd/conf.d
        bb-sync-file /etc/containerd/conf.d/additional_registry.toml - << EOF
        [plugins]
          [plugins."io.containerd.grpc.v1.cri"]
            [plugins."io.containerd.grpc.v1.cri".registry]
              [plugins."io.containerd.grpc.v1.cri".registry.mirrors]
                [plugins."io.containerd.grpc.v1.cri".registry.mirrors."${REGISTRY_URL}"]
                  endpoint = ["https://${REGISTRY_URL}"]
              [plugins."io.containerd.grpc.v1.cri".registry.configs]
                [plugins."io.containerd.grpc.v1.cri".registry.configs."${REGISTRY_URL}".auth]
                  username = "username"
                  password = "password"
                  # OR
                  auth = "dXNlcm5hbWU6cGFzc3dvcmQ="
        EOF
    
  6. Удалите секрет registry-bashible-config. Во время удаления, containerd v1 переключится на старый формат конфигурации containerd:

    d8 k -n d8-system delete secret registry-bashible-config
    
  7. После удаления дождитесь завершения переключения. Для отслеживания используйте инструкцию. Пример вывода:

    conditions:
    # ...
    - lastTransitionTime: "..."
      message: ""
      reason: ""
      status: "True"
      type: Ready
    hash: ..
    mode: Unmanaged
    target_mode: Unmanaged
    
  8. Если используется containerd v1, примените заготовленные этапом ранее NodeGroupConfiguration с пользовательскими конфигурациями хранилища образов контейнеров.

  9. Отключите модуль registry. Пример:

    apiVersion: deckhouse.io/v1alpha1
    kind: ModuleConfig
    metadata:
      name: registry
    spec:
      enabled: false
      settings: {}
      version: 1
    

Как посмотреть статус переключения режима registry?

Статус переключения режима хранилища образов контейнеров можно получить с помощью следующей команды:

d8 k -n d8-system -o yaml get secret registry-state | yq -C -P '.data | del .state | map_values(@base64d) | .conditions = (.conditions | from_yaml)'

Пример вывода:

conditions:
  - lastTransitionTime: "2025-07-15T12:52:46Z"
    message: 'registry.deckhouse.ru: all 157 items are checked'
    reason: Ready
    status: "True"
    type: RegistryContainsRequiredImages
  - lastTransitionTime: "2025-07-11T11:59:03Z"
    message: ""
    reason: ""
    status: "True"
    type: ContainerdConfigPreflightReady
  - lastTransitionTime: "2025-07-15T12:47:47Z"
    message: ""
    reason: ""
    status: "True"
    type: TransitionContainerdConfigReady
  - lastTransitionTime: "2025-07-15T12:52:48Z"
    message: ""
    reason: ""
    status: "True"
    type: InClusterProxyReady
  - lastTransitionTime: "2025-07-15T12:54:53Z"
    message: ""
    reason: ""
    status: "True"
    type: DeckhouseRegistrySwitchReady
  - lastTransitionTime: "2025-07-15T12:55:48Z"
    message: ""
    reason: ""
    status: "True"
    type: FinalContainerdConfigReady
  - lastTransitionTime: "2025-07-15T12:55:48Z"
    message: ""
    reason: ""
    status: "True"
    type: Ready
mode: Direct
target_mode: Direct

Вывод отображает состояние процесса переключения. Каждое условие может находиться в статусе True или False, а также содержать поле message с пояснением.

Описание условий:

Условие Описание
ContainerdConfigPreflightReady Состояние проверки конфигурации containerd. Проверяется, что на узлах отсутствуют пользовательские auth конфигурации containerd.
TransitionContainerdConfigReady Состояние подготовки конфигурации containerd в новый режим. Проверяется, что конфигурация containerd успешно подготовлена и содержит одновременно конфигурации нового и старого режима.
FinalContainerdConfigReady Состояние завершения переключения containerd в новый режим. Проверяется, что конфигурация containerd успешно применена и содержит конфигурацию нового режима.
DeckhouseRegistrySwitchReady Состояние переключения Deckhouse и его компонентов на использование нового хранилища образов контейнеров. Значение True указывает, что Deckhouse успешно переключился на сконфигурированное хранилище образов контейнеров и готов к работе.
InClusterProxyReady Состояние готовности In-Cluster Proxy. Проверяется, что In-Cluster Proxy успешно запущен и работает.
CleanupInClusterProxy Состояние очистки In-Cluster Proxy, если прокси не нужен для работы желаемого режима. Проверяется, что все ресурсы, связанные с In-Cluster Proxy, успешно удалены.
NodeServicesReady Состояние готовности Node Services Manager и Static-Pod хранилища образов контейнеров. Проверяется, что Node Services Manager успешно запущен и работает, и что Static-Pod хранилища образов контейнеров был успешно развёрнут с помощью Node Services Manager.
CleanupNodeServices Состояние очистки Node Services Manager и Static-Pod хранилища образов контейнеров, если компоненты не нужны для работы желаемого режима. Проверяется, что все ресурсы, связанные с Node Services Manager и Static-Pod хранилища образов контейнеров, успешно удалены.
RegistryContainsRequiredImages Состояние проверки хранилища образов контейнеров на наличие необходимых образов.
Ready Общее состояние готовности хранилища образов контейнеров к работе в указанном режиме. Проверяется, что все предыдущие условия выполнены и модуль готов к работе.