Модуль registry: Custom Resources

RegistryConfig

Short names: rcfg

Scope: Cluster
Version: v1alpha1

Описывает результирующую конфигурацию хранилища образов контейнеров кластера.

В штатном режиме объект рендерится модулем из ModuleConfig/registry. Объект — контракт, а не собственность Deckhouse: администратор может править его напрямую, когда оператор Deckhouse недоступен, и правка применяется на лету контроллером хранилища образов контейнеров и синкером хранилища, без перегенерации helm.

Используется единственный объект с именем registry.

• spec

  объект

  Обязательный параметр

  • spec.mode

    строка

    Управляет ли модуль путём загрузки образов.

    • Managed — модуль владеет путём загрузки и создаёт свои компоненты.
    • Unmanaged — модуль не владеет ничем, компоненты не создаются.

    По умолчанию: Managed

    Допустимые значения: Managed, Unmanaged

  • spec.primary

    объект

    Единственный авторитетный источник образов компонентов Deckhouse.

    Дополнительные хранилища образов контейнеров объявляются отдельными объектами RegistryUpstream. Несколько разных Primary не поддерживается: тогда были бы неоднозначны и «полон ли кеш», и «из чего наполняется кеш в air-gap».

    • spec.primary.upstream

      объект

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

      Если не задан, кластер считается air-gap: внутрикластерный кеш становится авторитетным и наполняется извне командой d8 mirror push. Отсутствие параметра требует storage.cache: true.

      • spec.primary.upstream.auth

        объект

        Ключи доступа к хранилищу образов контейнеров.

        Чувствительные данные. Ключи хранятся внутри объекта, а не по ссылке на секрет, — так агент на узле остаётся самодостаточным при недоступном API-сервере. Ограничивайте доступ к ресурсам хранилища образов контейнеров соответствующим образом.

        • spec.primary.upstream.auth.auth

          строка

          Заранее закодированное значение base64("username:password").

          Имеет приоритет над username и password, если задано.

        • spec.primary.upstream.auth.password

          строка

          Пароль для базовой аутентификации.

        • spec.primary.upstream.auth.username

          строка

          Имя пользователя для базовой аутентификации.

      • spec.primary.upstream.ca

        строка

        PEM-сертификат удостоверяющего центра для проверки хранилища образов контейнеров при scheme: HTTPS.

        Если не задан, используется системное хранилище доверенных сертификатов.

      • spec.primary.upstream.host

        строка

        Обязательный параметр

        Хост хранилища образов контейнеров, опционально с портом.

        Пример:

        host: registry.deckhouse.io
        

      • spec.primary.upstream.mirrors

        массив объектов

        Дополнительные адреса, отдающие тот же контент, что и основное хранилище образов контейнеров, — для отказоустойчивости и балансировки.

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

        • spec.primary.upstream.mirrors.auth

          объект

          Ключи доступа к зеркалу.

          Чувствительные данные. См. primary.upstream.auth.

          • spec.primary.upstream.mirrors.auth.auth

            строка

            Заранее закодированное значение base64("username:password").

          • spec.primary.upstream.mirrors.auth.password

            строка

            Пароль для базовой аутентификации.

          • spec.primary.upstream.mirrors.auth.username

            строка

            Имя пользователя для базовой аутентификации.

        • spec.primary.upstream.mirrors.ca

          строка

          PEM-сертификат удостоверяющего центра для проверки зеркала.

        • spec.primary.upstream.mirrors.host

          строка

          Обязательный параметр

          Хост зеркала, опционально с портом.

          Пример:

          host: registry-mirror.example.com
          

        • spec.primary.upstream.mirrors.path

          строка

          Префикс пути к репозиторию внутри зеркала.

        • spec.primary.upstream.mirrors.scheme

          строка

          Протокол подключения к зеркалу.

          По умолчанию: HTTPS

          Допустимые значения: HTTP, HTTPS

      • spec.primary.upstream.path

        строка

        Префикс пути к репозиторию внутри хранилища образов контейнеров.

        Пример:

        path: "/deckhouse/ee"
        

      • spec.primary.upstream.scheme

        строка

        Протокол подключения к хранилищу образов контейнеров.

        Используйте HTTP только для незащищённых доверенных хранилищ образов контейнеров.

        По умолчанию: HTTPS

        Допустимые значения: HTTP, HTTPS

  • spec.storage

    объект

    Настройки внутрикластерного кеша хранилища образов контейнеров.

    • spec.storage.cache

      булевый

      Идут ли загрузки через внутрикластерный кеш на master-узлах.

      Это первая из двух осей конфигурации. Вторая — задан ли primary.upstream. Вместе они заменяют прежнюю стейт-машину режимов:

      • cache: false с заданным upstream — агент форвардит загрузки напрямую в upstream, хранилище не нужно.
      • cache: true с заданным upstream — сквозной кеш, наполняется из upstream.
      • cache: true без upstream — air-gap: кеш авторитетен и наполняется командой d8 mirror push.

      По умолчанию: false

    • spec.storage.garbageCollection

      объект

      When the cache reclaims the disk taken by releases the cluster has moved past.

      Nothing else ever removes anything: every release adds a slice of the repository, so a cluster that lives for years fills its store and then stops being able to pull.

      A collection puts one replica read-only for as long as it takes. That replica keeps serving every image it holds; what it cannot do is store the result of a cache miss, or accept a d8 mirror push. Only one replica collects at a time.

      • spec.storage.garbageCollection.enabled

        булевый

        Whether the cache reclaims its disk at all.

      • spec.storage.garbageCollection.schedule

        строка

        A five-field cron expression, in the replicas’ own time zone.

        Defaults to a night hour, or to the start of the master node group’s maintenance window when one is set.

    • spec.storage.size

      строка

      Размер персистентного хранилища под кеш.

      Шаблон: ^[0-9]+(\.[0-9]+)?(E|P|T|G|M|k|Ei|Pi|Ti|Gi|Mi|Ki)?$

      Пример:

      size: 50Gi
      

    • spec.storage.source

      объект

      Набор образов, который должен оказаться в кеше.

      Обязателен в air-gap: без upstream, к которому можно откатиться, полнота должна быть вычислимой, прежде чем отдавать образы только из кеша.

      • spec.storage.source.bundleRef

        строка

        Имя набора образов, например bundle, залитого командой d8 mirror push.

        Пример:

        bundleRef: d8-mirror-bundle
        

      • spec.storage.source.expectedDigests

        целочисленный

        Количество уникальных дайджестов в наборе.

        Допустимые значения: 0 <= X

        Пример:

        expectedDigests: 459
        

• status

  объект
  • status.conditions

    массив объектов

    Сводка здоровья, которую пишет контроллер хранилища образов контейнеров.

    • Valid — результирующая конфигурация согласована.
    • UpstreamValid — результат preflight-пробы Primary upstream: достижимость, приём ключей, наличие sentinel-контента. Значение False означает, что контроллер держит последний рабочий upstream и не переключился, — так испорченная лицензия или неверный адрес не роняют кластер.
    • StorageConverged — хранилище пришло в состояние, которого требует конфигурация.
    • status.conditions.lastTransitionTime

      строка

      Обязательный параметр

      Время последнего изменения состояния.

    • status.conditions.message

      строка

      Пояснение для человека.

    • status.conditions.observedGeneration

      целочисленный

      Поколение spec, для которого выставлено состояние.

    • status.conditions.reason

      строка

      Обязательный параметр

      Машиночитаемая причина состояния.

    • status.conditions.status

      строка

      Обязательный параметр

      Значение состояния.

      Допустимые значения: True, False, Unknown

    • status.conditions.type

      строка

      Обязательный параметр

      Тип состояния.

  • status.effectiveUpstream

    объект

    Upstream, который фактически действует, — не обязательно тот, что задан в конфигурации.

    Это собственная запись контроллера о последнем upstream, прошедшем preflight-пробу, и именно она делает неудачное изменение переживаемым: если ввести нерабочие ключи или переключиться на лицензию без доступа, это поле — а вместе с ним и кластер — остаётся на прежнем рабочем upstream, а состояние UpstreamValid сообщает причину.

    Оно же держит upstream во время ухода в air-gap, когда конфигурация уже говорит «нет», а кеш ещё не полон.

    Пусто означает, что никакой upstream не действует: либо кластер в air-gap, либо ничего ещё не настроено.

    • status.effectiveUpstream.ca

      строка

      PEM-сертификат удостоверяющего центра для проверки хранилища образов контейнеров.

    • status.effectiveUpstream.host

      строка

      Хост хранилища образов контейнеров, опционально с портом.

    • status.effectiveUpstream.mirrors

      массив объектов

      Дополнительные адреса, отдающие тот же контент.

      • status.effectiveUpstream.mirrors.ca

        строка

        PEM-сертификат удостоверяющего центра для проверки зеркала.

      • status.effectiveUpstream.mirrors.host

        строка

        Обязательный параметр

        Хост зеркала, опционально с портом.

      • status.effectiveUpstream.mirrors.path

        строка

        Префикс пути к репозиторию внутри зеркала.

      • status.effectiveUpstream.mirrors.scheme

        строка

        Протокол подключения к зеркалу.

        Допустимые значения: HTTP, HTTPS

    • status.effectiveUpstream.path

      строка

      Префикс пути к репозиторию внутри хранилища образов контейнеров.

    • status.effectiveUpstream.scheme

      строка

      Протокол подключения к хранилищу образов контейнеров.

      Допустимые значения: HTTP, HTTPS

  • status.effectiveUpstreamAuthDigest

    строка

    Опознаёт действующие ключи доступа, не раскрывая их.

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

  • status.observedGeneration

    целочисленный

    Поколение spec, на которое контроллер отреагировал последним.

RegistryNode

Short names: rnode

Scope: Cluster
Version: v1alpha1

Описывает полную выкладку хранилища образов контейнеров для одного узла, скомпилированную для его агента.

По одному объекту на узел, имя совпадает с именем узла, ownerReference указывает на него. Объект пишет контроллер хранилища образов контейнеров; status пишет только агент.

Объект плоский и, если не считать одной намеренной ссылки, самодостаточный: сертификаты удостоверяющих центров и маршруты лежат внутри, агент держит полную копию на диске и продолжает отдавать образы по ней при недоступном API-сервере — а в этот момент разыменовывать уже нечего. Исключение — учётные данные: они не лежат внутри, а названы (auth.secretRef указывает на секрет, в который их разрешает модуль). Именно это позволяет читать объект каждому узлу, не выдавая при этом каждому узлу все учётные данные реестров кластера. По той же причине контроллер компилирует все принятые RegistryUpstream в spec.additionalRoutes, вместо того чтобы агент следил за N объектами: согласованность многих объектов при недоступном API гарантировать нельзя.

Объект не содержит per-node секретов. Всё в нём — глобальная конфигурация, одинаковая на каждом узле. Именно поэтому его безопасно читать всей группе system:nodes, через которую агент получает доступ по kubeconfig kubelet’а.

• spec

  объект

  Обязательный параметр

  • spec.additionalRoutes

    массив объектов

    Принятые объекты RegistryUpstream, скомпилированные контроллером.

    Всегда транзит, никогда не кешируется: агент проксирует загрузку и передаёт её потоком, не записывая на диск.

    • spec.additionalRoutes.auth

      объект

      Где хранятся ключи доступа к этому эндпоинту.

      Указаны ссылкой, а не значением. Ресурс кластерного уровня, а роль узлового агента привязана к группе system:nodes, поэтому ключ, записанный здесь, был бы доступен через API kubelet’у любого узла — включая ключи к хранилищу образов контейнеров, откуда этот узел ничего не тянет. Компонент, который это читает, разрешает ссылку один раз и сохраняет результат, поэтому продолжает работать и при недоступном API-сервере.

      • spec.additionalRoutes.auth.secretRef

        объект

        Секрет с ключами доступа и ключ внутри него.

        • spec.additionalRoutes.auth.secretRef.key

          строка

          Обязательный параметр

          Ключ внутри него. Один секрет содержит все разрешённые модулем ключи доступа, по принадлежности.

        • spec.additionalRoutes.auth.secretRef.name

          строка

          Обязательный параметр

          Имя секрета в неймспейсе d8-system.

    • spec.additionalRoutes.ca

      строка

      PEM-сертификат удостоверяющего центра для проверки upstream.

    • spec.additionalRoutes.host

      строка

      Обязательный параметр

      Хост upstream, опционально с портом.

      Пример:

      host: registry-vendor.example.com
      

    • spec.additionalRoutes.match

      строка

      Обязательный параметр

      Хост хранилища образов контейнеров, который перехватывается на этом узле.

      Пример:

      match: images.virtualization.example.com
      

    • spec.additionalRoutes.mirrors

      массив объектов

      Дополнительные адреса, отдающие тот же контент.

      • spec.additionalRoutes.mirrors.auth

        объект

        Где хранятся ключи доступа к этому эндпоинту.

        Указаны ссылкой, а не значением. Ресурс кластерного уровня, а роль узлового агента привязана к группе system:nodes, поэтому ключ, записанный здесь, был бы доступен через API kubelet’у любого узла — включая ключи к хранилищу образов контейнеров, откуда этот узел ничего не тянет. Компонент, который это читает, разрешает ссылку один раз и сохраняет результат, поэтому продолжает работать и при недоступном API-сервере.

        • spec.additionalRoutes.mirrors.auth.secretRef

          объект

          Секрет с ключами доступа и ключ внутри него.

          • spec.additionalRoutes.mirrors.auth.secretRef.key

            строка

            Обязательный параметр

            Ключ внутри него. Один секрет содержит все разрешённые модулем ключи доступа, по принадлежности.

          • spec.additionalRoutes.mirrors.auth.secretRef.name

            строка

            Обязательный параметр

            Имя секрета в неймспейсе d8-system.

      • spec.additionalRoutes.mirrors.ca

        строка

        PEM-сертификат удостоверяющего центра для проверки зеркала.

      • spec.additionalRoutes.mirrors.host

        строка

        Обязательный параметр

        Хост зеркала, опционально с портом.

      • spec.additionalRoutes.mirrors.path

        строка

        Префикс пути к репозиторию внутри зеркала.

      • spec.additionalRoutes.mirrors.scheme

        строка

        Протокол подключения к зеркалу.

        По умолчанию: HTTPS

        Допустимые значения: HTTP, HTTPS

    • spec.additionalRoutes.path

      строка

      Префикс пути к репозиторию внутри upstream.

    • spec.additionalRoutes.scheme

      строка

      Протокол подключения к upstream.

      По умолчанию: HTTPS

      Допустимые значения: HTTP, HTTPS

  • spec.backends

    массив объектов

    Источники основного набора образов, по приоритету.

    При включённом кеше это хранилище, а за ним upstream как запасной путь, пока кеш наполняется; запись upstream уходит из выкладки, когда кластер уходит в air-gap. При выключенном кеше — только upstream.

    • spec.backends.auth

      объект

      Где хранятся ключи доступа к этому эндпоинту.

      Указаны ссылкой, а не значением. Ресурс кластерного уровня, а роль узлового агента привязана к группе system:nodes, поэтому ключ, записанный здесь, был бы доступен через API kubelet’у любого узла — включая ключи к хранилищу образов контейнеров, откуда этот узел ничего не тянет. Компонент, который это читает, разрешает ссылку один раз и сохраняет результат, поэтому продолжает работать и при недоступном API-сервере.

      • spec.backends.auth.secretRef

        объект

        Секрет с ключами доступа и ключ внутри него.

        • spec.backends.auth.secretRef.key

          строка

          Обязательный параметр

          Ключ внутри него. Один секрет содержит все разрешённые модулем ключи доступа, по принадлежности.

        • spec.backends.auth.secretRef.name

          строка

          Обязательный параметр

          Имя секрета в неймспейсе d8-system.

    • spec.backends.ca

      строка

      PEM-сертификат удостоверяющего центра для проверки бэкенда.

    • spec.backends.host

      строка

      Обязательный параметр

      Хост бэкенда, опционально с портом.

      Пример:

      host: registry.d8-system.svc:5001
      

    • spec.backends.mirrors

      массив объектов

      Дополнительные адреса, отдающие тот же контент; используются при отказе.

      • spec.backends.mirrors.auth

        объект

        Где хранятся ключи доступа к этому эндпоинту.

        Указаны ссылкой, а не значением. Ресурс кластерного уровня, а роль узлового агента привязана к группе system:nodes, поэтому ключ, записанный здесь, был бы доступен через API kubelet’у любого узла — включая ключи к хранилищу образов контейнеров, откуда этот узел ничего не тянет. Компонент, который это читает, разрешает ссылку один раз и сохраняет результат, поэтому продолжает работать и при недоступном API-сервере.

        • spec.backends.mirrors.auth.secretRef

          объект

          Секрет с ключами доступа и ключ внутри него.

          • spec.backends.mirrors.auth.secretRef.key

            строка

            Обязательный параметр

            Ключ внутри него. Один секрет содержит все разрешённые модулем ключи доступа, по принадлежности.

          • spec.backends.mirrors.auth.secretRef.name

            строка

            Обязательный параметр

            Имя секрета в неймспейсе d8-system.

      • spec.backends.mirrors.ca

        строка

        PEM-сертификат удостоверяющего центра для проверки зеркала.

      • spec.backends.mirrors.host

        строка

        Обязательный параметр

        Хост зеркала, опционально с портом.

      • spec.backends.mirrors.path

        строка

        Префикс пути к репозиторию внутри зеркала.

      • spec.backends.mirrors.scheme

        строка

        Протокол подключения к зеркалу.

        По умолчанию: HTTPS

        Допустимые значения: HTTP, HTTPS

    • spec.backends.name

      строка

      Обязательный параметр

      Роль бэкенда.

      • Storage — внутрикластерный кеш.
      • Upstream — Primary upstream: либо единственный бэкенд, либо запасной путь, пока наполняется кеш.

      Допустимые значения: Storage, Upstream

    • spec.backends.path

      строка

      Префикс пути к репозиторию внутри бэкенда.

    • spec.backends.scheme

      строка

      Протокол подключения к бэкенду.

      По умолчанию: HTTPS

      Допустимые значения: HTTP, HTTPS

  • spec.cache

    булевый

    Ось кеша для этого узла.

    true — агент идёт во внутрикластерное хранилище, false — напрямую в Primary upstream.

• status

  объект

  Пишет только агент; сообщает факты со стороны containerd.

  Полноты хранилища здесь нет: это свойство хранилища, и живёт оно в RegistryStorage .status.replicas. Любой узел может пропатчить status любого RegistryNode, поскольку RBAC не умеет ограничивать list/watch по field selector, — поэтому ничто здесь не является несущим для пути загрузки, это наблюдаемость.

  • status.activeBackends

    массив строк

    Бэкенды, которыми агент может пользоваться в данный момент.

  • status.conditions

    массив объектов

    Детальное состояние, которое сообщает агент.

    • Reconciled — применён ли spec. Причина отличает штатное согласование от применения по дисковой копии из-за недоступности API-сервера.
    • status.conditions.lastTransitionTime

      строка

      Обязательный параметр

      Время последнего изменения состояния.

    • status.conditions.message

      строка

      Пояснение для человека.

    • status.conditions.observedGeneration

      целочисленный

      Поколение spec, для которого выставлено состояние.

    • status.conditions.reason

      строка

      Обязательный параметр

      Машиночитаемая причина состояния.

    • status.conditions.status

      строка

      Обязательный параметр

      Значение состояния.

      Допустимые значения: True, False, Unknown

    • status.conditions.type

      строка

      Обязательный параметр

      Тип состояния.

  • status.observedGeneration

    целочисленный

    Поколение spec, которое агент применил последним.

  • status.proxyListening

    булевый

    Отдаёт ли агент эндпоинт хранилища образов контейнеров.

  • status.reconciled

    булевый

    Применил ли агент тот spec, который видит сейчас.

  • status.staleStorageDataBytes

    целочисленный

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

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

    Чтобы освободить место, удалите /opt/deckhouse/registry на узле. Поля нет, пока кеш настроен, и на узле, где кеша никогда не было.

RegistryStorage

Short names: rstor

Scope: Cluster
Version: v1alpha1

Описывает, как работает внутрикластерное хранилище registry, и сообщает его фактическое состояние.

Объект пишет контроллер хранилища образов контейнеров, а читает контейнер-синкер, который перенастраивает distribution на лету. Именно этот путь позволяет смене ключей или сертификата примениться при неработающем операторе Deckhouse: он никогда не проходит через перегенерацию helm.

У объекта есть настоящий spec, а не только зеркало факта, потому что distribution нужно сообщать, что делать, а не только наблюдать за ним.

Используется единственный объект с именем registry.

• spec

  объект

  Обязательный параметр

  • spec.airGapRequested

    булевый

    Запрошена ли работа без upstream — независимо от того, отключён ли upstream уже фактически.

    Это окно перехода: air-gap запрошен, upstream ещё удерживается, чтобы кластер продолжал работать, а образы приходят через d8 mirror push, которых синкер не видит. Именно по этому признаку решается, что полноту нужно измерять чтением хранилища, а не подсчётом скопированного. Различие существенно: сквозной кеш пишет в собственное хранилище на каждом промахе, поэтому то же измерение на кеширующем кластере считало бы образы, которые кластер просто подтянул.

  • spec.auth

    строка

    Bearer-токен, защищающий хранилище.

    Чувствительные данные. Авторизация не отключается никогда — в том числе в air-gap, где кеш отдаёт образы только на чтение.

  • spec.garbageCollection

    объект

    When and whether a replica reclaims the disk taken by releases the cluster has moved past.

    Needed because nothing else ever removes anything: every release adds a slice of the repository, so a cluster that lives for years fills its store and then stops being able to pull.

    Collecting puts one replica read-only for the duration — it keeps serving every image it holds, but cannot store the result of a cache miss and cannot accept a d8 mirror push. Only one replica collects at a time, so the others are unaffected.

    • spec.garbageCollection.enabled

      булевый

      Whether replicas collect at all.

    • spec.garbageCollection.schedule

      строка

      A five-field cron expression, in the replica’s own time zone.

      Defaults to a night hour, or to the start of the master node group’s maintenance window when one is set — that being the time an operator has already declared safe for disruption.

  • spec.needSync

    булевый

    Так контроллер выдаёт синкеру задание на наполнение или репликацию.

  • spec.publish

    булевый

    Публиковать ли защищённую авторизацией точку записи (Ingress) для d8 mirror push.

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

  • spec.source

    объект

    Набор образов, который должен оказаться в хранилище.

    • spec.source.bundleRef

      строка

      Имя набора образов.

    • spec.source.expectedDigests

      целочисленный

      Количество уникальных дайджестов в наборе.

      Допустимые значения: 0 <= X

  • spec.store

    объект

    Где distribution хранит блобы.

    • spec.store.path

      строка

      Путь на узле. Константа модуля, не пользовательская настройка.

      Пример:

      path: "/opt/deckhouse/registry"
      

    • spec.store.size

      строка

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

      Шаблон: ^[0-9]+(\.[0-9]+)?(E|P|T|G|M|k|Ei|Pi|Ti|Gi|Mi|Ki)?$

  • spec.upstream

    объект

    Primary upstream, спроецированный сюда контроллером.

    Задан — сквозной кеш. Не задан — кеш авторитетен (air-gap).

    Контроллер убирает это поле только после того, как лидер полон, поэтому узлы никогда не остаются без источника образов — даже если пользователь уже убрал upstream из конфигурации.

    • spec.upstream.auth

      объект

      Где хранятся ключи доступа к этому эндпоинту.

      Указаны ссылкой, а не значением. Ресурс кластерного уровня, а роль узлового агента привязана к группе system:nodes, поэтому ключ, записанный здесь, был бы доступен через API kubelet’у любого узла — включая ключи к registry, откуда этот узел ничего не тянет. Компонент, который это читает, разрешает ссылку один раз и сохраняет результат, поэтому продолжает работать и при недоступном API-сервере.

      • spec.upstream.auth.secretRef

        объект

        Секрет с ключами доступа и ключ внутри него.

        • spec.upstream.auth.secretRef.key

          строка

          Обязательный параметр

          Ключ внутри него. Один секрет содержит все разрешённые модулем ключи доступа, по принадлежности.

        • spec.upstream.auth.secretRef.name

          строка

          Обязательный параметр

          Имя секрета в неймспейсе d8-system.

    • spec.upstream.ca

      строка

      PEM-сертификат удостоверяющего центра для проверки хранилища образов контейнеров.

    • spec.upstream.host

      строка

      Обязательный параметр

      Хост хранилища образов контейнеров, опционально с портом.

    • spec.upstream.mirrors

      массив объектов

      Дополнительные адреса, отдающие тот же контент. Синкер загружает с любого доступного и хранит один дедуплицированный набор.

      • spec.upstream.mirrors.auth

        объект

        Где хранятся ключи доступа к этому эндпоинту.

        Указаны ссылкой, а не значением. Ресурс кластерного уровня, а роль узлового агента привязана к группе system:nodes, поэтому ключ, записанный здесь, был бы доступен через API kubelet’у любого узла — включая ключи к registry, откуда этот узел ничего не тянет. Компонент, который это читает, разрешает ссылку один раз и сохраняет результат, поэтому продолжает работать и при недоступном API-сервере.

        • spec.upstream.mirrors.auth.secretRef

          объект

          Секрет с ключами доступа и ключ внутри него.

          • spec.upstream.mirrors.auth.secretRef.key

            строка

            Обязательный параметр

            Ключ внутри него. Один секрет содержит все разрешённые модулем ключи доступа, по принадлежности.

          • spec.upstream.mirrors.auth.secretRef.name

            строка

            Обязательный параметр

            Имя секрета в неймспейсе d8-system.

      • spec.upstream.mirrors.ca

        строка

        PEM-сертификат удостоверяющего центра для проверки зеркала.

      • spec.upstream.mirrors.host

        строка

        Обязательный параметр

        Хост зеркала, опционально с портом.

      • spec.upstream.mirrors.path

        строка

        Префикс пути к репозиторию внутри зеркала.

      • spec.upstream.mirrors.scheme

        строка

        Протокол подключения к зеркалу.

        По умолчанию: HTTPS

        Допустимые значения: HTTP, HTTPS

    • spec.upstream.path

      строка

      Префикс пути к репозиторию внутри хранилища образов контейнеров.

    • spec.upstream.scheme

      строка

      Протокол подключения к хранилищу образов контейнеров.

      По умолчанию: HTTPS

      Допустимые значения: HTTP, HTTPS

• status

  объект
  • status.allReplicasFull

    булевый

    Содержат ли ожидаемый набор все реплики — тогда потеря лидера ничего не стоит.

  • status.authoritative

    булевый

    Снят ли upstream и стал ли кеш единственным источником образов.

  • status.conditions

    массив объектов

    Детальное состояние хранилища.

    • status.conditions.lastTransitionTime

      строка

      Обязательный параметр

      Время последнего изменения состояния.

    • status.conditions.message

      строка

      Пояснение для человека.

    • status.conditions.observedGeneration

      целочисленный

      Поколение spec, для которого выставлено состояние.

    • status.conditions.reason

      строка

      Обязательный параметр

      Машиночитаемая причина состояния.

    • status.conditions.status

      строка

      Обязательный параметр

      Значение состояния.

      Допустимые значения: True, False, Unknown

    • status.conditions.type

      строка

      Обязательный параметр

      Тип состояния.

  • status.fill

    объект

    Прогресс текущего задания на наполнение.

    • status.fill.filled

      целочисленный

      Сколько дайджестов записано на текущий момент.

    • status.fill.total

      целочисленный

      Сколько дайджестов ожидается.

  • status.leader

    строка

    Узел, который в данный момент держит lease лидера хранилища.

    Это не обычные выборы: за lease борется только реплика, которая держит весь ожидаемый набор образов, а реплика, которая его держит, уступает, когда набор появляется у другой. Роль лидера несимметрична — именно из него реплицируют все follower’ы, и именно его полнота открывает переход в air-gap.

    Без этого условия air-gap-кластер может застрять. d8 mirror push приходит через endpoint публикации и попадает на ту реплику, которую выбрал ingress, а не обязательно на лидера; пустому лидеру не из чего наливаться, follower’ы реплицируют его пустоту, а реплика с образами простаивает. Исключение — кластер, где полной реплики ещё нет ни одной, то есть состояние, с которого начинается любой кластер: тогда кто-то должен стать лидером, чтобы наливка вообще началась.

  • status.observedGeneration

    целочисленный

    Поколение spec, на которое контроллер отреагировал последним.

  • status.phase

    строка

    Краткая сводка состояния наполнения.

    • Idle — задание на наполнение или проверку не выполняется.
    • Filling — лидер наполняется.
    • Verifying — содержимое проверяется против spec.source.
    • Ready — лидер содержит ожидаемый набор.
    • Failed — задание на наполнение или проверку завершилось ошибкой. В этом состоянии upstream не снимается.

    Допустимые значения: Idle, Filling, Verifying, Ready, Failed

  • status.replicas

    массив объектов

    Состояние наполнения по репликам.

    Это единственное место, где сообщается полнота хранилища. RegistryNode намеренно её не несёт: полнота — свойство хранилища, а не узла.

    • status.replicas.address

      строка

      Адрес, на котором отвечает эта реплика, в виде host:port.

      Сообщает сама реплика — чтобы follower мог реплицировать с лидера, не разрешая имя узла в адрес, и чтобы синкерам вообще не требовалось читать объекты Node.

    • status.replicas.collectedAt

      строка

      When this replica last reclaimed its disk.

      Absent until it has. Reported per replica because each collects its own store, one at a time: a cluster where one replica has not collected for a month while the others have is a different problem from one where none has.

    • status.replicas.collectionError

      строка

      Why the last attempt to reclaim did not finish, empty when it did.

      Separate from error, which is about filling. A store that cannot be reclaimed still serves every image it holds, so the two say different things about how worried to be.

    • status.replicas.declaredDigests

      целочисленный

      Каков размер набора — то, из чего берётся verifiedDigests.

      Сообщается репликой, потому что размер набора знает только та реплика, которая его вычисляет, и по этому числу ничего не решается. Пока его не было, единственным знаменателем для статуса оставался spec.source.expectedDigests, который оператор указывает при объявлении air-gap и не указывает в остальных случаях — поэтому кластер с upstream всю свою самую длинную фазу показывал filled: 0, total: 0, пока копировались гигабайты. Полнота по-прежнему выражается через full, а переход в air-gap по-прежнему решается по spec.source.expectedDigests: объявление оператора не подменяется числом, которое кластер вычислил про себя.

    • status.replicas.error

      строка

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

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

    • status.replicas.full

      булевый

      Содержит ли эта реплика ожидаемый набор.

      Вычисляется по тому, что синкер фактически записал, и никогда пробой пути выдачи: на промахе сквозной кеш сам подтянул бы образ из upstream и отчитался об успехе на пустом хранилище. В air-gap самонаполнение невозможно, поэтому там честно читать каталог и сравнивать с spec.source.expectedDigests.

    • status.replicas.node

      строка

      Обязательный параметр

      Узел, на котором работает реплика.

    • status.replicas.role

      строка

      Роль реплики в репликации.

      • Leader — наполняется из upstream либо командой d8 mirror push в air-gap и раздаёт задания на репликацию.
      • Follower — наполняется от лидера заранее, поэтому потеря лидера не означает наполнения с нуля.

      Допустимые значения: Leader, Follower

    • status.replicas.source

      строка

      Реплика, от которой наполняется эта. Пусто для лидера.

    • status.replicas.store

      объект

      Сколько места на диске узла занимает хранилище этой реплики и принимает ли оно запись. Отсутствует, пока реплика не выполнила замер.

      Оба предела registry соблюдает сам, при каждой записи. Здесь те же величины в подсчёте синкера — для статуса и алертов. Размеры округлены до 16 МиБ, занятое вверх, свободное вниз, чтобы общая с узлом файловая система не переписывала статус на каждом проходе.

      • status.replicas.store.budgetBytes

        целочисленный

        storage.size из настроек модуля. Отсутствует, если параметр не задан; тогда действует только резерв.

      • status.replicas.store.filesystemCapacityBytes

        целочисленный

        Обязательный параметр

        Размер файловой системы хранилища.

      • status.replicas.store.filesystemFreeBytes

        целочисленный

        Обязательный параметр

        Свободное место на файловой системе хранилища. Если отдельного диска нет, это та же файловая система, которой пользуются kubelet и containerd.

      • status.replicas.store.reason

        строка

        Предел, из-за которого отклоняются записи.

        • BudgetExhausted — хранилище заняло всё, что разрешает storage.size;
        • ReserveExhausted — на файловой системе хранилища осталось только место, оставленное для узла.

        Допустимые значения: BudgetExhausted, ReserveExhausted

      • status.replicas.store.reserveBytes

        целочисленный

        Обязательный параметр

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

      • status.replicas.store.usedBytes

        целочисленный

        Обязательный параметр

        Сколько занимают блобы хранилища и незавершённые загрузки.

      • status.replicas.store.writable

        булевый

        Обязательный параметр

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

    • status.replicas.totalDigests

      целочисленный

      Сколько различных дайджестов эта реплика хранит всего.

      Это другая величина, чем verifiedDigests, и по ней ничего не решается. Она нужна, чтобы хранилище, содержащее больше, чем требуется этому кластеру — загруженный bundle с другими модулями, другими редакциями, аттестациями — выглядело именно так, а не как недостача относительно spec.source.expectedDigests.

    • status.replicas.verifiedDigests

      целочисленный

      Сколько дайджестов из набора подтверждено на месте.

      Набор — это то, что объявляют релизы кластера и сохраняемые модули, то есть дайджесты, известные deckhouse-controller. Поэтому это число напрямую сопоставимо с full и именно по нему принимается решение о переходе в air-gap. Всё остальное, что оказалось в хранилище, учитывается в totalDigests.

    • status.replicas.verifiedSet

      строка

      Отпечаток набора, для которого реплика в последний раз признана полной (full): версии платформы и модули кластера, каждый со своей версией и источником.

      full верен только для того набора, по которому он измерен, а набор меняется: устанавливается модуль, обновляется платформа. Значение сообщает каждая реплика вместе со своим full. Лидер сравнивает своё с набором, который нужен кластеру сейчас. Если они расходятся, лидер снимает full и перепроверяет хранилище, прежде чем на него сможет опереться переход в air-gap. full для другого набора не учитывается, когда реплики решают, кому быть лидером. Пусто, пока full не установлен.

  • status.safeToDropUpstream

    булевый

    Содержит ли лидер ожидаемый набор — это условие ухода в air-gap.

    Намеренно только лидер, а не все реплики: реплики доливаются заранее и параллельно, поэтому ожидание всех задержало бы переход, не добавив безопасности.

RegistryUpstream

Short names: rup

Scope: Cluster
Version: v1alpha1

Объявляет дополнительное хранилище образов контейнеров, в которое кластер маршрутизирует загрузки, помимо основного.

Это штатный способ для модуля, администратора или пользователя добавить своё хранилище образов контейнеров. Модуль создаёт объект с ownerReference на себя, поэтому объект удаляется сборщиком мусора вместе с модулем; GitOps-инструмент, ведущий ModuleConfig, не конкурирует за владение полями, потому что каждый upstream — отдельный объект.

Трафик через такие upstream — всегда транзит: агент проксирует загрузку, подставляя ключи и сертификат удостоверяющего центра, и передаёт её потоком, не записывая ни на диск, ни в кеш. Место под кеш ограничено и отдано под компоненты Deckhouse — тем более в air-gap, где кеш является единственным источником образов.

Значение match, уже занятое другим объектом, или затеняющее путь Primary, отклоняется, а не сливается молча. См. status.conflict.

• spec

  объект

  Обязательный параметр

  • spec.match

    строка

    Обязательный параметр

    Хост хранилища образов контейнеров, который перехватывается на узлах.

    Шаблон: ^[a-zA-Z0-9]([-a-zA-Z0-9]*[a-zA-Z0-9])?(\.[a-zA-Z0-9]([-a-zA-Z0-9]*[a-zA-Z0-9])?)*(:[0-9]{1,5})?$

    Пример:

    match: images.virtualization.example.com
    

  • spec.upstream

    объект

    Обязательный параметр

    Куда фактически отправляются перехваченные загрузки.

    • spec.upstream.auth

      объект

      Ключи доступа к хранилищу образов контейнеров.

      Чувствительные данные. Ключи хранятся внутри объекта, а не по ссылке на секрет, — так агент на узле остаётся самодостаточным при недоступном API-сервере.

      • spec.upstream.auth.auth

        строка

        Заранее закодированное значение base64("username:password").

        Имеет приоритет над username и password, если задано.

      • spec.upstream.auth.password

        строка

        Пароль для базовой аутентификации.

      • spec.upstream.auth.username

        строка

        Имя пользователя для базовой аутентификации.

    • spec.upstream.ca

      строка

      PEM-сертификат удостоверяющего центра для проверки хранилища образов контейнеров при scheme: HTTPS.

    • spec.upstream.host

      строка

      Обязательный параметр

      Хост хранилища образов контейнеров, опционально с портом.

      Пример:

      host: registry-vendor.example.com
      

    • spec.upstream.mirrors

      массив объектов

      Дополнительные адреса, отдающие тот же контент, что и хранилище образов контейнеров, — для отказоустойчивости.

      • spec.upstream.mirrors.auth

        объект

        Ключи доступа к зеркалу.

        Чувствительные данные. См. upstream.auth.

        • spec.upstream.mirrors.auth.auth

          строка

          Заранее закодированное значение base64("username:password").

        • spec.upstream.mirrors.auth.password

          строка

          Пароль для базовой аутентификации.

        • spec.upstream.mirrors.auth.username

          строка

          Имя пользователя для базовой аутентификации.

      • spec.upstream.mirrors.ca

        строка

        PEM-сертификат удостоверяющего центра для проверки зеркала.

      • spec.upstream.mirrors.host

        строка

        Обязательный параметр

        Хост зеркала, опционально с портом.

      • spec.upstream.mirrors.path

        строка

        Префикс пути к репозиторию внутри зеркала.

      • spec.upstream.mirrors.scheme

        строка

        Протокол подключения к зеркалу.

        По умолчанию: HTTPS

        Допустимые значения: HTTP, HTTPS

    • spec.upstream.path

      строка

      Префикс пути к репозиторию внутри хранилища образов контейнеров.

      Пример:

      path: "/virt"
      

    • spec.upstream.scheme

      строка

      Протокол подключения к хранилищу образов контейнеров.

      По умолчанию: HTTPS

      Допустимые значения: HTTP, HTTPS

• status

  объект
  • status.accepted

    булевый

    Скомпилировал ли контроллер этот upstream в выкладку по узлам.

  • status.conditions

    массив объектов

    Результат арбитража с машиночитаемой причиной.

    • Accepted — входит ли upstream в выкладку по узлам.
    • status.conditions.lastTransitionTime

      строка

      Обязательный параметр

      Время последнего изменения состояния.

    • status.conditions.message

      строка

      Пояснение для человека.

    • status.conditions.observedGeneration

      целочисленный

      Поколение spec, для которого выставлено состояние.

    • status.conditions.reason

      строка

      Обязательный параметр

      Машиночитаемая причина состояния.

    • status.conditions.status

      строка

      Обязательный параметр

      Значение состояния.

      Допустимые значения: True, False, Unknown

    • status.conditions.type

      строка

      Обязательный параметр

      Тип состояния.

  • status.conflict

    строка

    Почему объект отклонён: какой объект уже занял match, либо что match затеняет путь Primary.

    Пусто, если объект принят.

  • status.observedGeneration

    целочисленный

    Поколение spec, на которое контроллер отреагировал последним.