Управление внутренним container registry

Возможность использования внутреннего container registry (registry) реализуется модулем registry.

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

Режимы работы с внутренним registry

Модуль registry, реализующий внутреннее хранилище, работает в следующих режимах:

• Direct — использование внутреннего registry. Обращение к внутреннему registry выполняется по фиксированному адресу registry.d8-system.svc:5001/system/deckhouse. Фиксированный адрес, при изменении параметров registry, позволяет избежать повторного скачивания образов и перезапуска компонентов. Переключение между режимами и registry выполняется через ModuleConfig deckhouse. Переключение выполняется автоматически (подробнее — в примерах переключения ниже). Архитектура режима описана в разделе «Архитектура режима Direct».
• Unmanaged — работа без использования внутреннего registry. Обращение внутри кластера выполняется напрямую к внешнему registry. Существует 2 вида режима Unmanaged:
  • Конфигурируемый — режим, управляемый с помощью модуля registry. Переключение между режимами и registry выполняется через ModuleConfig deckhouse. Переключение выполняется автоматически (подробнее — в примерах переключения ниже).
  • Неконфигурируемый (deprecated) — режим, используемый по умолчанию. Параметры конфигурации задаются при установке кластера, или при изменении в развёрнутом кластере с помощью утилиты helper change registry (deprecated).

Ограничения по работе с внутренним registry

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

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

Bootstrap кластера Deckhouse Kubernetes Platform с включенным режимом Direct не поддерживается. Кластер разворачивается с настройками для режима Unmanaged. Настройки registry во время bootstrap задаются через initConfiguration.

Конфигурация registry через moduleConfig deckhouse во время bootstrap кластера DKP не поддерживается.

Ограничения по условиям работы

Модуль registry, реализующий возможность использования внутреннего container registry, работает при соблюдении следующих условий:

• Если на узлах кластера используется CRI containerd или containerd v2. Для настройки CRI ознакомьтесь с конфигурацией ClusterConfiguration.
• Кластер полностью управляется DKP. В Managed Kubernetes кластерах он работать не будет.

Ограничения по переключению режимов

Ограничения по переключению режимов следующие:

• При первом переключении необходимо выполнить миграцию пользовательских конфигураций registry. Подробнее — в разделе «Модуль registry: FAQ».
• Переключение в неконфигурируемый режим Unmanaged доступно только из Unmanaged режима. Подробнее — в разделе «Модуль registry: FAQ».

Примеры переключения

Переключение на режим Direct

Для переключения уже работающего кластера на режим Direct выполните следующие шаги:

1. Перед переключением выполните миграцию на использование модуля registry.

2. Убедитесь, что модуль registry включен и работает. Для этого выполните следующую команду:

   d8 k get module registry -o wide
   

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

   NAME       WEIGHT ...  PHASE   ENABLED   DISABLED MESSAGE   READY
   registry   38     ...  Ready   True                         True
   

3. Убедитесь, что все master-узлы находятся в состоянии Ready и не имеют статуса SchedulingDisabled. Для этого используйте следующую команду:

   d8 k get nodes
   

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

   NAME       STATUS   ROLES                 ...
   master-0   Ready    control-plane,master  ...
   master-1   Ready    control-plane,master  ...
   master-2   Ready    control-plane,master  ...
   

   Пример вывода, когда master-узел (master-2 в примере) находится в статусе SchedulingDisabled:

   NAME       STATUS                      ROLES                 ...
   master-0   Ready    control-plane,master  ...
   master-1   Ready    control-plane,master  ...
   master-2   Ready,SchedulingDisabled    control-plane,master  ...
   

4. Проверьте, чтобы очередь Deckhouse была пустой и без ошибок:

   d8 system queue list
   

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

   Summary:
   - 'main' queue: empty.
   - 107 other queues (0 active, 107 empty): 0 tasks.
   - no tasks to handle.
   

5. Установите настройки режима Direct в ModuleConfig deckhouse. Если используется registry, отличный от registry.deckhouse.ru, ознакомьтесь с конфигурацией модуля deckhouse для корректной настройки.

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

   apiVersion: deckhouse.io/v1alpha1
   kind: ModuleConfig
   metadata:
     name: deckhouse
   spec:
     version: 1
     enabled: true
     settings:
       registry:
         mode: Direct
         direct:
           imagesRepo: registry.deckhouse.ru/deckhouse/ee
           scheme: HTTPS
           license: <LICENSE_KEY> # Замените на ваш лицензионный ключ
   

6. Проверьте статус переключения registry в секрете registry-state, используя инструкцию.

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

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

Переключение на режим Unmanaged

Для переключения уже работающего кластера на режим Unmanaged выполните следующие шаги:

1. Перед переключением выполните миграцию на использование модуля registry.

2. Убедитесь, что модуль registry включен и работает. Для этого выполните следующую команду:

   d8 k get module registry -o wide
   

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

   NAME       WEIGHT ...  PHASE   ENABLED   DISABLED MESSAGE   READY
   registry   38     ...  Ready   True                         True
   

3. Проверьте, чтобы очередь Deckhouse была пустой и без ошибок:

   d8 system queue list
   

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

   Summary:
   - 'main' queue: empty.
   - 107 other queues (0 active, 107 empty): 0 tasks.
   - no tasks to handle.
   

4. Установите настройки режима Unmanaged в ModuleConfig deckhouse. Если используется registry, отличный от 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> # Замените на ваш лицензионный ключ
   

5. Проверьте статус переключения registry в секрете registry-state, используя инструкцию.

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

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

6. При необходимости переключения на старый метод управления registry, ознакомьтесь с инструкцией.

Миграция на модуль registry

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

Для containerd v2

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

   Посмотреть текущие настройки registry можно с помощью команды:

   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

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

2. Если конфигурации присутствуют, необходимо выполнить миграцию на новый формат конфигурации registry в 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, отличный от registry.deckhouse.ru, ознакомьтесь с конфигурацией модуля deckhouse для корректной настройки.

   Посмотреть текущие настройки registry можно с помощью команды:

   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
   

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

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

   apiVersion: deckhouse.io/v1alpha1
   kind: NodeGroupConfiguration
   metadata:
     name: containerd-additional-config-auth.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
   

Миграция обратно с модуля registry

1. Переведите registry в режим Unmanaged. Если используется registry, отличный от 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. Переведите registry в неконфигурируемый режим 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 с пользовательскими конфигурациями registry.

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

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

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

Статус переключения режима 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 с пояснением.

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