How do I find out all Deckhouse parameters?

Как узнать все параметры Deckhouse?

Deckhouse is configured using global settings, module settings, and various custom resources. Read more in the documentation.

Deckhouse настраивается с помощью глобальных настроек, настроек модулей и различных сustom resource’ов. Подробнее — в документации.

To view global Deckhouse settings:

Вывести глобальные настройки:

To list the status of all modules (available for Deckhouse version 1.47+):

Вывести список состояния всех модулей (доступно для Deckhouse версии 1.47+):

To get the user-authn module configuration:

Вывести настройки модуля user-authn:

How do I find the documentation for the version installed?

Как найти документацию по установленной у меня версии?

The documentation for the Deckhouse version running in the cluster is available at documentation.<cluster_domain>, where <cluster_domain> is the DNS name that matches the template defined in the modules.publicDomainTemplate parameter.

Документация запущенной в кластере версии Deckhouse доступна по адресу documentation.<cluster_domain>, где <cluster_domain> — DNS-имя в соответствии с шаблоном из параметра modules.publicDomainTemplate глобальной конфигурации.

Documentation is available when the documentation module is enabled. It is enabled by default except the Minimal bundle.

Документация доступна, если в кластере включен модуль documentation. Он включен по умолчанию, кроме варианта поставки Minimal.

Deckhouse update

Обновление Deckhouse

How to find out in which mode the cluster is being updated?

Как понять, в каком режиме обновляется кластер?

You can view the cluster update mode in the configuration of the deckhouse module. To do this, run the following command:

Посмотреть режим обновления кластера можно в конфигурации модуля deckhouse. Для этого выполните следующую команду:

Example of the output:

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

There are three possible update modes:

• Automatic + update windows are not set. The cluster will be updated after the new version appears on the corresponding release channel.
• Automatic + update windows are set. The cluster will be updated in the nearest available window after the new version appears on the release channel.
• Manual. Manual action is required to apply the update.

Существуют три возможных режима обновления:

• Автоматический + окна обновлений не заданы. Кластер обновится сразу после появления новой версии на соответствующем канале обновлений.
• Автоматический + заданы окна обновлений. Кластер обновится в ближайшее доступное окно после появления новой версии на канале обновлений.
• Ручной режим. Для применения обновления требуются ручные действия.

How do I set the desired release channel?

Как установить желаемый канал обновлений?

Change (set) the releaseChannel parameter in the deckhouse module configuration to automatically switch to another release channel.

Чтобы перейти на другой канал обновлений автоматически, нужно в конфигурации модуля deckhouse изменить (установить) параметр releaseChannel.

It will activate the mechanism of automatic stabilization of the release channel.

В этом случае включится механизм автоматической стабилизации релизного канала.

Here is an example of the deckhouse module configuration with the Stable release channel:

Пример конфигурации модуля deckhouse с установленным каналом обновлений Stable:

How do I disable automatic updates?

Как отключить автоматическое обновление?

To completely disable the Deckhouse update mechanism, remove the releaseChannel parameter in the deckhouse module configuration.

Чтобы полностью отключить механизм обновления Deckhouse, удалите в конфигурации модуля deckhouse параметр releaseChannel.

In this case, Deckhouse does not check for updates and even doesn’t apply patch releases.

В этом случае Deckhouse не проверяет обновления и даже обновление на patch-релизы не выполняется.

It is highly not recommended to disable automatic updates! It will block updates to patch releases that may contain critical vulnerabilities and bugs fixes.

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

How do I apply an update without having to wait for the update window?

Как применить обновление минуя окна обновлений?

To apply an update immediately without having to wait for the update window, set the release.deckhouse.io/apply-now : "true" annotation on the DeckhouseRelease resource.

Чтобы применить обновление немедленно, не дожидаясь ближайшего окна обновлений, установите в соответствующем ресурсе DeckhouseRelease аннотацию release.deckhouse.io/apply-now: "true".

An example of a command to set the annotation to skip the update windows for version v1.56.2:

Пример команды установки аннотации пропуска окон обновлений для версии v1.56.2:

An example of a resource with the update window skipping annotation in place:

Пример ресурса с установленной аннотацией пропуска окон обновлений:

How to understand what changes the update contains and how it will affect the cluster?

Как понять, какие изменения содержит обновление и как это повлияет на работу кластера?

You can find all the information about Deckhouse versions in the list of Deckhouse releases.

Информацию о всех версиях Deckhouse можно найти в списке релизов Deckhouse.

Summary information about important changes, component version updates, and which components in the cluster will be restarted during the update process can be found in the description of the zero patch version of the release. For example, v1.46.0 for the v1.46 Deckhouse release.

Сводную информацию о важных изменениях, об обновлении версий компонентов, а также о том, какие компоненты в кластере буду перезапущены в процессе обновления, можно найти в описании нулевой patch-версии релиза. Например, v1.46.0 для релиза v1.46 Deckhouse.

A detailed list of changes can be found in the Changelog, which is referenced in each release.

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

How do I understand that the cluster is being updated?

Как понять, что в кластере идет обновление?

During the update:

• The DeckhouseUpdating alert is firing.
• The deckhouse Pod is not the Ready status. If the Pod does not go to the Ready status for a long time, then this may indicate that there are problems in the work of Deckhouse. Diagnosis is necessary.

Во время обновления:

• горит алерт DeckhouseUpdating;
• под deckhouse не в статусе Ready. Если под долго не переходит в статус Ready, это может говорить о наличии проблем в работе Deckhouse. Необходима диагностика.

How do I know that the update was successful?

Как понять, что обновление прошло успешно?

If the DeckhouseUpdating alert is resolved, then the update is complete.

Если алерт DeckhouseUpdating погас, значит, обновление завершено.

You can also check the status of Deckhouse releases.

Вы также можете проверить состояние релизов Deckhouse.

An example:

Пример:

The Deployed status of the corresponding version indicates that the switch to the corresponding version was performed (but this does not mean that it ended successfully).

Статус Deployed у соответствующей версии говорит о том, что переключение на соответствующую версию было выполнено (но это не значит, что оно закончилось успешно).

Check the status of the Deckhouse Pod:

Проверьте состояние пода Deckhouse:

• If the status of the Pod is Running, and 1/1 indicated in the READY column, the update was completed successfully.
• If the status of the Pod is Running, and 0/1 indicated in the READY column, the update is not over yet. If this goes on for more than 20-30 minutes, then this may indicate that there are problems in the work of Deckhouse. Diagnosis is necessary.
• If the status of the Pod is not Running, then this may indicate that there are problems in the work of Deckhouse. Diagnosis is necessary.

• Если статус пода Running и в колонке READY указано 1/1 — обновление закончилось успешно.
• Если статус пода Running и в колонке READY указано 0/1 — обновление еще не закончилось. Если это продолжается более 20–30 минут, это может говорить о наличии проблем в работе Deckhouse. Необходима диагностика.
• Если статус пода не Running, это может говорить о наличии проблем в работе Deckhouse. Необходима диагностика.

Possible options for action if something went wrong:

• Check Deckhouse logs using the following command:

Возможные варианты действий, если что-то пошло не так:

• Проверьте логи, используя следующую команду:

• Collect debugging information and contact technical support.
• Ask for help from the community.

• Соберите отладочную информацию и свяжитесь с технической поддержкой.
• Попросите помощи у сообщества.

How do I know that a new version is available for the cluster?

Как узнать, что для кластера доступна новая версия?

As soon as a new version of Deckhouse appears on the release channel installed in the cluster:

• The alert DeckhouseReleaseIsWaitingManualApproval fires, if the cluster uses manual update mode (the update.mode parameter is set to Manual).
• There is a new custom resource DeckhouseRelease. Use the kubectl get deckhousereleases command, to view the list of releases. If the DeckhouseRelease is in the Pending state, the specified version has not yet been installed. Possible reasons why DeckhouseRelease may be in Pending:
• Manual update mode is set (the update.mode parameter is set to Manual).
• The automatic update mode is set, and the update windows are configured, the interval of which has not yet come.
• The automatic update mode is set, update windows are not configured, but the installation of the version has been postponed for a random time due to the mechanism of reducing the load on the repository of container images. There will be a corresponding message in the status.message field of the DeckhouseRelease resource.
• The update.notification.minimalNotificationTime parameter is set, and the specified time has not passed yet.

Как только на установленном в кластере канале обновления появляется новая версия Deckhouse:

• Загорается алерт DeckhouseReleaseIsWaitingManualApproval, если кластер использует ручной режим обновлений (параметр update.mode установлен в Manual).
• Появляется новый custom resource DeckhouseRelease. Используйте команду kubectl get deckhousereleases, чтобы посмотреть список релизов. Если DeckhouseRelease новой версии находится в состоянии Pending, указанная версия еще не установлена. Возможные причины, при которых DeckhouseRelease может находиться в Pending:
• Установлен ручной режим обновлений (параметр update.mode установлен в Manual).
• Установлен автоматический режим обновлений и настроены окна обновлений, интервал которых еще не наступил.
• Установлен автоматический режим обновлений, окна обновлений не настроены, но применение версии отложено на случайный период времени из-за механизма снижения нагрузки на репозиторий образов контейнеров. В поле status.message ресурса DeckhouseRelease будет соответствующее сообщение.
• Установлен параметр update.notification.minimalNotificationTime и указанное в нем время еще не прошло.

How do I get information about the upcoming update in advance?

Как заранее получать информацию о предстоящем обновлении?

You can get information in advance about updating minor versions of Deckhouse on the release channel in the following ways:

• Configure manual update mode. In this case, when a new version appears on the release channel, the alert DeckhouseReleaseIsWaitingManualApproval will fire and a new custom resource DeckhouseRelease will appear in the cluster.
• Configure automatic update mode and specify the minimum time in the minimalNotificationTime parameter for which the update will be postponed. In this case, when a new version appears on the release channel, a new custom resource DeckhouseRelease will appear in the cluster. And if you specify a URL in the update.notification.webhook parameter, then the webhook will be called additionally.

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

• Настроить ручной режим обновлений. В этом случае при появлении новой версии на канале обновлений загорится алерт DeckhouseReleaseIsWaitingManualApproval и в кластере появится новый custom resource DeckhouseRelease.
• Настроить автоматический режим обновлений и указать минимальное время в параметре minimalNotificationTime, на которое будет отложено обновление. В этом случае при появлении новой версии на канале обновлений в кластере появится новый custom resource DeckhouseRelease. А если указать URL в параметре update.notification.webhook, дополнительно произойдет вызов webhook’а.

How do I find out which version of Deckhouse is on which release channel?

Как узнать, какая версия Deckhouse находится на каком канале обновлений?

Information about which version of Deckhouse is on which release channel can be obtained at https://flow.deckhouse.io.

Информацию о том, какая версия Deckhouse находится на каком канале обновлений, можно получить на https://flow.deckhouse.io.

How does automatic Deckhouse update work?

Как работает автоматическое обновление Deckhouse?

Every minute Deckhouse checks a new release appeared in the release channel specified by the releaseChannel parameter.

При указании в конфигурации модуля deckhouse параметра releaseChannel Deckhouse будет каждую минуту проверять данные о релизе на канале обновлений.

When a new release appears on the release channel, Deckhouse downloads it and creates CustomResource DeckhouseRelease.

При появлении нового релиза Deckhouse скачивает его в кластер и создает custom resource DeckhouseRelease.

After creating a DeckhouseRelease custom resource in a cluster, Deckhouse updates the deckhouse Deployment and sets the image tag to a specified release tag according to selected update mode and update windows (automatic at any time by default).

После появления custom resource’а DeckhouseRelease в кластере Deckhouse выполняет обновление на соответствующую версию согласно установленным параметрам обновления (по умолчанию — автоматически, в любое время).

To get list and status of all releases use the following command:

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

Patch releases (e.g., an update from version 1.30.1 to version 1.30.2) ignore update windows settings and apply as soon as they are available.

Patch-релизы (например, обновление на версию 1.30.2 при установленной версии 1.30.1) устанавливаются без учета режима и окон обновления, то есть при появлении на канале обновления patch-релиза он всегда будет установлен.

What happens when the release channel changes?

Что происходит при смене канала обновлений?

• When switching to a more stable release channel (e.g., from Alpha to EarlyAccess), Deckhouse downloads release data from the release channel (the EarlyAccess release channel in the example) and compares it with the existing DeckhouseReleases:
• Deckhouse deletes later releases (by semver) that have not yet been applied (with the Pending status).
• if the latest releases have been already Deployed, then Deckhouse will hold the current release until a later release appears on the release channel (on the EarlyAccess release channel in the example).
• When switching to a less stable release channel (e.g., from EarlyAcess to Alpha), the following actions take place:
• Deckhouse downloads release data from the release channel (the Alpha release channel in the example) and compares it with the existing DeckhouseReleases.
• Then Deckhouse performs the update according to the update parameters.

• При смене канала обновлений на более стабильный (например, с Alpha на EarlyAccess) Deckhouse скачивает данные о релизе (в примере — из канала EarlyAccess) и сравнивает их с данными из существующих в кластере custom resouce’ов DeckhouseRelease:
• Более поздние релизы, которые еще не были применены (в статусе Pending), удаляются.
• Если более поздние релизы уже применены (в статусе Deployed), смены релиза не происходит. В этом случае Deckhouse останется на таком релизе до тех пор, пока на канале обновлений EarlyAccess не появится более поздний релиз.
• При смене канала обновлений на менее стабильный (например, с EarlyAcess на Alpha):
• Deckhouse скачивает данные о релизе (в примере — из канала Alpha) и сравнивает их с данными из существующих в кластере custom resource’ов DeckhouseRelease.
• Затем Deckhouse выполняет обновление согласно установленным параметрам обновления.

What do I do if Deckhouse fails to retrieve updates from the release channel?

Что делать, если Deckhouse не получает обновлений из канала обновлений?

• Make sure that the desired release channel is configured.
• Make sure that the DNS name of the Deckhouse container registry is resolved correctly.

• Проверьте, что настроен нужный канал обновлений.
• Проверьте корректность разрешения DNS-имени хранилища образов Deckhouse.

Retrieve and compare the IP addresses of the Deckhouse container registry (registry.deckhouse.io) on one of the nodes and in the Deckhouse pod. They should match. Here is how you can retrieve the IP address of the Deckhouse container registry on a node:

Получите и сравните IP-адреса хранилища образов Deckhouse (registry.deckhouse.ru) на одном из узлов и в поде Deckhouse. Они должны совпадать.

shell $ getent ahosts registry.deckhouse.io 46.4.145.194 STREAM registry.deckhouse.io 46.4.145.194 DGRAM 46.4.145.194 RAW

Пример получения IP-адреса хранилища образов Deckhouse на узле:

Here is how you can retrieve the IP address of the Deckhouse container registry in a pod: shell $ kubectl -n d8-system exec -ti deploy/deckhouse -c deckhouse – getent ahosts registry.deckhouse.io 46.4.145.194 STREAM registry.deckhouse.io 46.4.145.194 DGRAM registry.deckhouse.io

If the retrieved IP addresses do not match, inspect the DNS settings on the host. Specifically, check the list of domains in the search parameter of the /etc/resolv.conf file (it affects name resolution in the Deckhouse pod). If the search parameter of the /etc/resolv.conf file includes a domain where wildcard record resolution is configured, it may result in incorrect resolution of the IP address of the Deckhouse container registry (see example).

shell $ getent ahosts registry.deckhouse.ru 185.193.90.38 STREAM registry.deckhouse.ru 185.193.90.38 DGRAM 185.193.90.38 RAW

In the example below, DNS settings produce different results when resolving names on the host and in the Kubernetes pod:

• The /etc/resolv.conf file on the node:

Пример получения IP-адреса хранилища образов Deckhouse в поде Deckhouse: shell $ kubectl -n d8-system exec -ti deploy/deckhouse -c deckhouse – getent ahosts registry.deckhouse.ru 185.193.90.38 STREAM registry.deckhouse.ru 185.193.90.38 DGRAM registry.deckhouse.ru

Если полученные IP-адреса не совпадают, проверьте настройки DNS на узле. В частности, обратите внимание на список доменов в параметре search файла /etc/resolv.conf (он влияет на разрешение имен в поде Deckhouse). Если в параметре search файла /etc/resolv.conf указан домен, в котором настроено разрешение wildcard-записей, это может привести к неверному разрешению IP-адреса хранилища образов Deckhouse (см. пример).

text nameserver 10.0.0.10 search company.my

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

• Пример файла /etc/resolv.conf на узле:

Note that the ndot parameter defaults to 1 (options ndots:1) on the node. But in Kubernetes pods, the ndot parameter is set to 5. Therefore, the logic for resolving DNS names with 5 dots or less in the name is different on the host and in the pod.

text nameserver 10.0.0.10 search company.my

• The company.my DNS zone is configured to resolve wildcard records *.company.my to 10.0.0.100. That is, any DNS name in the company.my zone for which there is no specific DNS entry is resolved to 10.0.0.100.

Обратите внимание, что по умолчанию на узле параметр ndot равен 1 (options ndots:1). Но в подах Kubernetes параметр ndot равен 5. Таким образом, логика разрешения DNS-имен, имеющих в имени 5 точек и менее, различается на узле и в поде.

In this case, subject to the search parameter specified in the /etc/resolv.conf file, when accessing the registry.deckhouse.io address on the node, the system will try to obtain the IP address for the registry.deckhouse.io name (it treats it as a fully qualified name given the default setting of options ndots:1).

• В DNS-зоне company.my настроено разрешение wildcard-записей *.company.my в адрес 10.0.0.100. То есть любое DNS-имя в зоне company.my, для которого нет конкретной записи в DNS, разрешается в адрес 10.0.0.100.

On the other hand, when accessing registry.deckhouse.io from a Kubernetes pod, given the options ndots:5 parameter (the default one in Kubernetes) and the search parameter, the system will initially try to resolve the IP address for the registry.deckhouse.io.company.my name. The registry.deckhouse.io.company.my name will be resolved to 10.0.0.100 because the company.my DNS zone is configured to resolve wildcard records *.company.my to 10.0.0.100. As a result, the registry.deckhouse.io host and information about the available Deckhouse updates will be unreachable.

Тогда с учетом параметра search, указанного в файле /etc/resolv.conf, при обращении на адрес registry.deckhouse.ru на узле система попробует получить IP-адрес для имени registry.deckhouse.ru (так как считает его полностью определенным, учитывая настройку по умолчанию параметра options ndots:1).

При обращении же на адрес registry.deckhouse.ru из пода Kubernetes, учитывая параметры options ndots:5 (используется в Kubernetes по умолчанию) и search, система первоначально попробует получить IP-адрес для имени registry.deckhouse.ru.company.my. Имя registry.deckhouse.ru.company.my разрешится в IP-адрес 10.0.0.100, так как в DNS-зоне company.my настроено разрешение wildcard-записей *.company.my в адрес 10.0.0.100. В результате к хосту registry.deckhouse.ru будет невозможно подключиться и скачать информацию о доступных обновлениях Deckhouse.

Air-gapped environment; working via proxy and third-party registry

Закрытое окружение, работа через proxy и сторонние registry

How do I configure Deckhouse to use a third-party registry?

Как установить Deckhouse из стороннего registry?

This feature is available in Enterprise Edition only.

Доступно только в Enterprise Edition.

Deckhouse only supports Bearer authentication for container registries.

Deckhouse поддерживает работу только с Bearer token-схемой авторизации в container registry.

Tested and guaranteed to work with the following container registries: {{- registry[1].shortname }} , .

Протестирована и гарантируется работа со следующими container registry: {{- registry[1].shortname }} , .

Deckhouse can be configured to work with a third-party registry (e.g., a proxy registry inside private environments).

При установке Deckhouse можно настроить на работу со сторонним registry (например, проксирующий registry внутри закрытого контура).

Define the following parameters in the InitConfiguration resource:

Установите следующие параметры в ресурсе InitConfiguration:

• imagesRepo: <PROXY_REGISTRY>/<DECKHOUSE_REPO_PATH>/ee. The path to the Deckhouse EE image in the third-party registry, for example imagesRepo: registry.deckhouse.io/deckhouse/ee;
• registryDockerCfg: <BASE64>. Base64-encoded auth credentials of the third-party registry.

• imagesRepo: <PROXY_REGISTRY>/<DECKHOUSE_REPO_PATH>/ee — адрес образа Deckhouse EE в стороннем registry. Пример: imagesRepo: registry.deckhouse.ru/deckhouse/ee;
• registryDockerCfg: <BASE64> — права доступа к стороннему registry, зашифрованные в Base64.

Use the following registryDockerCfg if anonymous access to Deckhouse images is allowed in the third-party registry:

Если разрешен анонимный доступ к образам Deckhouse в стороннем registry, registryDockerCfg должен выглядеть следующим образом:

registryDockerCfg must be Base64-encoded.

Приведенное значение должно быть закодировано в Base64.

Use the following registryDockerCfg if authentication is required to access Deckhouse images in the third-party registry:

Если для доступа к образам Deckhouse в стороннем registry необходима аутентификация, registryDockerCfg должен выглядеть следующим образом:

• <PROXY_USERNAME> — auth username for <PROXY_REGISTRY>.
• <PROXY_PASSWORD> — auth password for <PROXY_REGISTRY>.
• <PROXY_REGISTRY> — registry address: <HOSTNAME>[:PORT].
• <AUTH_BASE64> — Base64-encoded <PROXY_USERNAME>:<PROXY_PASSWORD> auth string.

где:

registryDockerCfg must be Base64-encoded.

• <PROXY_USERNAME> — имя пользователя для аутентификации на <PROXY_REGISTRY>;
• <PROXY_PASSWORD> — пароль пользователя для аутентификации на <PROXY_REGISTRY>;
• <PROXY_REGISTRY> — адрес стороннего registry в виде <HOSTNAME>[:PORT];
• <AUTH_BASE64> — строка вида <PROXY_USERNAME>:<PROXY_PASSWORD>, закодированная в Base64.

The InitConfiguration resource provides two more parameters for non-standard third-party registry configurations:

Итоговое значение для registryDockerCfg должно быть также закодировано в Base64.

• registryCA - root CA certificate to validate the third-party registry’s HTTPS certificate (if self-signed certificates are used);
• registryScheme - registry scheme (HTTP or HTTPS). The default value is HTTPS.

Для настройки нестандартных конфигураций сторонних registry в ресурсе InitConfiguration предусмотрены еще два параметра:

• registryCA — корневой сертификат, которым можно проверить сертификат registry (если registry использует самоподписанные сертификаты);
• registryScheme — протокол доступа к registry (HTTP или HTTPS). По умолчанию — HTTPS.

Tips for configuring Nexus

The following requirements must be met if the Nexus repository manager is used:

Особенности настройки Nexus

• Docker Bearer Token Realm must be enabled (Administration -> Security -> Realms).
• Docker proxy repository must be pre-created (Administration -> Repository -> Repositories):
• Allow anonymous docker pull must be enabled. This option enables Bearer token authentication to work. Note that anonymous access won’t work unless explicitly enabled in Administration -> Security -> Anonymous Access, and the anonymous user is not granted access rights to the created repository.
• Maximum metadata age for the created repository must be set to 0.
• Access control must be configured as follows:
• The Nexus role must be created (Administration -> Security -> Roles) with the folowing permissions:
• nx-repository-view-docker-<repo>-browse
• nx-repository-view-docker-<repo>-read
• The user (Administration -> Security -> Users) must be created with the above role granted.

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

Configuration:

• Включен Docker Bearer Token Realm (Administration -> Security -> Realms).
• Создан проксирующий репозиторий Docker (Administration -> Repository -> Repositories):
• Параметр Allow anonymous docker pull для репозитория должен быть включен. Данный параметр включает поддержку авторизации с помощью Bearer-токенов, при этом анонимный доступ не будет работать, если он не был явно включен в Administration -> Security -> Anonymous Access и пользователю anonymous не были даны права на доступ к репозиторию.
• Параметр Maximum metadata age для репозитория должен быть установлен в 0.
• Должен быть настроен контроль доступа:
• Создана роль Nexus (Administration -> Security -> Roles) со следующими полномочиями:
• nx-repository-view-docker-<репозиторий>-browse
• nx-repository-view-docker-<репозиторий>-read
• Создан пользователь (Administration -> Security -> Users) с ролью, созданной выше.

• Enable Docker Bearer Token Realm (Administration -> Security -> Realms):

Настройка:

• Create a docker proxy repository (Administration -> Repository -> Repositories) pointing to the Deckhouse registry:

• Включите Docker Bearer Token Realm (Administration -> Security -> Realms):

• Fill in the fields on the Create page as follows:
• Name must contain the name of the repository you created earlier, e.g., d8-proxy.
• Repository Connectors / HTTP or Repository Connectors / HTTPS must contain a dedicated port for the created repository, e.g., 8123 or other.
• Allow anonymous docker pull must be enabled for the Bearer token authentication to work. Note that anonymous access won’t work unless explicitly enabled in Administration -> Security -> Anonymous Access and the anonymous user is not granted access rights to the created repository.
• Remote storage must be set to https://registry.deckhouse.io/.
• You can disable Auto blocking enabled and Not found cache enabled for debugging purposes, otherwise they must be enabled.
• Maximum Metadata Age must be set to 0.
• Authentication must be enabled if you plan to use Deckhouse Enterprise Edition and the related fields must be set as follows:
• Authentication Type must be set to Username.
• Username must be set to license-token.
• Password must contain your license key for Deckhouse Enterprise Edition.

• Создайте проксирующий репозиторий Docker (Administration -> Repository -> Repositories), указывающий на Deckhouse registry:

• Заполните поля страницы создания репозитория следующим образом:
• Name должно содержать имя создаваемого репозитория, например d8-proxy.
• Repository Connectors / HTTP или Repository Connectors / HTTPS должно содержать выделенный порт для создаваемого репозитория, например 8123 или иной.
• Allow anonymous docker pull должно быть включено, чтобы работала авторизация с помощью Bearer-токенов. При этом анонимный доступ не будет работать, если он не был явно включен в Administration -> Security -> Anonymous Access и пользователю anonymous не были даны права на доступ к репозиторию.
• Remote storage должно иметь значение https://registry.deckhouse.ru/.
• Auto blocking enabled и Not found cache enabled могут быть выключены для отладки; в противном случае их следует включить.
• Maximum Metadata Age должно быть равно 0.
• Если планируется использовать Deckhouse Enterprise Edition, флажок Authentication должен быть включен, а связанные поля должны быть заполнены следующим образом:
• Authentication Type должно иметь значение Username.
• Username должно иметь значение license-token.
• Password должно содержать ключ лицензии Deckhouse Enterprise Edition.

• Configure Nexus access control to allow Nexus access to the created repository:
• Create a Nexus role (Administration -> Security -> Roles) with the nx-repository-view-docker-<repo>-browse and nx-repository-view-docker-<repo>-read permissions.

• Настройте контроль доступа Nexus для доступа Deckhouse к созданному репозиторию:
• Создайте роль Nexus (Administration -> Security -> Roles) с полномочиями nx-repository-view-docker-<репозиторий>-browse и nx-repository-view-docker-<репозиторий>-read.

• Create a user with the role above granted.

• Создайте пользователя (Administration -> Security -> Users) с ролью, созданной выше.

Tips for configuring Harbor

You need to use the Proxy Cache feature of a Harbor.

Особенности настройки Harbor

• Create a Registry:
• Administration -> Registries -> New Endpoint.
• Provider: Docker Registry.
• Name — specify any of your choice.
• Endpoint URL: https://registry.deckhouse.io.
• Specify the Access ID and Access Secret for Deckhouse Enterprise Edition.

Необходимо использовать такой функционал Harbor, как Proxy Cache.

• Настройте Registry:
• Administration -> Registries -> New Endpoint.
• Provider: Docker Registry.
• Name — укажите любое, на ваше усмотрение.
• Endpoint URL: https://registry.deckhouse.ru.
• Укажите Access ID и Access Secret для Deckhouse Enterprise Edition.

• Create a new Project:
• Projects -> New Project.
• Project Name will be used in the URL. You can choose any name, for example, d8s.
• Access Level: Public.
• Proxy Cache — enable and choose the Registry, created in the previous step.

• Создайте новый проект:
• Projects -> New Project.
• Project Name будет частью URL. Используйте любой, например, d8s.
• Access Level: Public.
• Proxy Cache — включите и выберите в списке Registry, созданный на предыдущем шаге.

Thus, Deckhouse images will be available at https://your-harbor.com/d8s/deckhouse/ee:{d8s-version}.

Manually uploading images to an air-gapped registry

В результате образы Deckhouse будут доступны, например, по следующему адресу: https://your-harbor.com/d8s/deckhouse/ee:{d8s-version}.

This feature is available in Enterprise Edition only.

Ручная загрузка образов в изолированный приватный registry

1. If necessary, log in to the container registry registry.deckhouse.io using your license key.

Доступно только в Enterprise Edition.

shell docker login -u license-token registry.deckhouse.io

1. При необходимости авторизуйтесь в container registry registry.deckhouse.ru (или registry.deckhouse.io) с помощью вашего лицензионного ключа.

1. Run the Deckhouse installer version 1.58.6 or higher.

shell docker login -u license-token registry.deckhouse.ru

shell docker run -ti –pull=always -v $(pwd)/d8-images:/tmp/d8-images registry.deckhouse.io/deckhouse/ee/install:v1.58.6 bash

1. Запустите установщик Deckhouse версии 1.58.6 или выше.

Note that the directory on the host will be mounted in the installer container. This directory will contain the pulled Deckhouse tarball and generated DeckhouseReleases manifests.

shell docker run -ti –pull=always -v $(pwd)/d8-images:/tmp/d8-images registry.deckhouse.ru/deckhouse/ee/install:v1.58.6 bash

1. Pull Deckhouse images using the dhctl mirror command.

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

dhctl mirror pulls only the latest available patch versions of a minor Deckhouse release. For example, for Deckhouse 1.52, only one version, 1.52.10, will be pulled, as it is sufficient to update Deckhouse from version 1.51.

1. Скачайте образы Deckhouse в выделенную директорию, используя команду dhctl mirror.

The command below will pull Deckhouse tarballs for versions that are on the release channels (check flow.deckhouse.io for the current status of the release channels):

dhctl mirror скачивает только последнюю доступную патч-версию минорного релиза Deckhouse. Например, для Deckhouse 1.52 будет скачана только одна версия 1.52.10, т. к. этого достаточно для обновления Deckhouse с версии 1.51.

shell DHCTL_CLI_MIRROR_LICENSE=”" dhctl mirror --images-bundle-path /tmp/d8-images/d8.tar

Следующая команда скачает образы Deckhouse тех версий, которые находятся на каналах обновлений (о текущем статусе версий на каналах обновлений можно узнать на flow.deckhouse.io):

If you interrupt the download before it is finished, calling the command again will check which images have already been downloaded, and the download will continue. This will only happen if no more than 24 hours have passed since the download interruption. Use the --no-pull-resume flag, to start the download from scratch.

shell DHCTL_CLI_MIRROR_LICENSE=”" dhctl mirror --source="registry.deckhouse.ru/deckhouse/ee" --images-bundle-path /tmp/d8-images/d8.tar

To pull all Deckhouse images starting from a particular version, specify it in the --min-version parameter in the X.Y format.

Если загрузка образов будет прервана, повторный вызов команды проверит загруженные образы и продолжит загрузку с момента ее остановки. Продолжение загрузки возможно только если с момента остановки прошло не более суток. Используйте параметр --no-pull-resume, чтобы принудительно начать загрузку сначала.

For example, here is how you can pull all Deckhouse version images starting from version 1.45:

Чтобы скачать все версии Deckhouse начиная с конкретной версии, укажите ее в параметре --min-version в формате X.Y.

shell DHCTL_CLI_MIRROR_LICENSE=”" dhctl mirror --images-bundle-path /tmp/d8-images/d8.tar --min-version=1.45

Например, для загрузки всех версий Deckhouse, начиная с версии 1.45, используйте команду:

Note that --min-version parameter will be ignored if you specify version above current rock-solid channel.

shell DHCTL_CLI_MIRROR_LICENSE=”" dhctl mirror --source="registry.deckhouse.ru/deckhouse/ee" --images-bundle-path /tmp/d8-images/d8.tar --min-version=1.45

To pull Deckhouse images from a specific registry repository, specify that repository with the --source flag. The optional --source-login and --source-password flags are used to authenticate to a given registry. If they are omitted, mirroring will be performed anonymously.

Обратите внимание, параметр --min-version будет проигнорирован если вы укажете версию выше находящейся в канале обновлений rock-solid.

For example, here is how you can pull images from a third-party registry:

Чтобы загрузить образы Deckhouse из определенного репозитория registry, вы можете указать этот репозиторий с помощью флага --source. Существуют также дополнительные флаги --source-login и --source-password, используемые для аутентификации в предоставленном registry. Если они не указаны, dhctl mirror будет обращаться к registry анонимно.

shell DHCTL_CLI_MIRROR_SOURCE_LOGIN=”user” DHCTL_CLI_MIRROR_SOURCE_PASSWORD=”password” dhctl mirror –source=”corp.company.com/sys/deckhouse” –images-bundle-path /tmp/d8-images/d8.tar

Например, вот как можно загрузить образы из стороннего registry:

Note: --license flag acts as a shortcut for --source-login ($DHCTL_CLI_MIRROR_SOURCE_LOGIN and --source-password ($DHCTL_CLI_MIRROR_SOURCE_PASSWORD) flags for the Deckhouse registry. If you specify both license and login+password pair for source registry, the latter will be used.

shell DHCTL_CLI_MIRROR_SOURCE_LOGIN=”user” DHCTL_CLI_MIRROR_SOURCE_PASSWORD=”password” dhctl mirror –source=”corp.company.ru/sys/deckhouse” –images-bundle-path /tmp/d8-images/d8.tar

dhctl mirror supports digesting of the final set of Deckhouse images with the GOST R 34.11-2012 (Stribog) hash function (the --gost-digest parameter). The checksum will be logged and written to a file with the .tar.gostsum extension next to the tar-archive containing the Deckhouse images.

Параметр --license действует как сокращение для параметров --source-login ($DHCTL_CLI_MIRROR_SOURCE_LOGIN) и --source-password ($DHCTL_CLI_MIRROR_SOURCE_PASSWORD) и предназначен для использования с официальным registry Deckhouse. Если вы укажете и параметр --license, и пару логин + пароль одновременно, будет использована последняя.

1. Optional: Copy the dhctl binary from the container to the directory where Deckhouse images were pulled.

dhctl mirror поддерживает расчет контрольных сумм итогового набора образов Deckhouse в формате ГОСТ Р 34.11-2012 (Стрибог) (параметр --gost-digest). Контрольная сумма будет выведена в лог и записана в файл с расширением .tar.gostsum рядом с tar-архивом, содержащим образы Deckhouse.

shell cp /usr/bin/dhctl /tmp/d8-images/dhctl

1. Опционально: Скопируйте утилиту dhctl из контейнера в директорию со скачанными образами Deckhouse.

1. Upload the directory with the pulled Deckhouse images to a host with access to the air-gapped registry.

shell cp /usr/bin/dhctl /tmp/d8-images/dhctl

1. To continue with installation, use the dhctl binary you copied before OR repeat steps 1 and 2 for the Deckhouse installer on the host with access to the air-gapped registry. Make sure the directory with the pulled Deckhouse images is mounted into the container. Push the images to the air-gapped registry using the dhctl mirror command.

1. Передайте директорию с загруженными образами Deckhouse на хост с доступом к изолированному registry. Для продолжения установки используйте скопированную ранее утилиту dhctl или запустите установщик Deckhouse аналогично пунктам 1 и 2 на хосте с доступом к изолированному registry. Не забудьте смонтировать директорию с загруженными образами Deckhouse в контейнер установщика.

Example of pushing images from the /tmp/d8-images/d8.tar tarball:

1. Загрузите образы Deckhouse с помощью команды dhctl mirror в изолированный registry.

shell DHCTL_CLI_MIRROR_USER=”" DHCTL_CLI_MIRROR_PASS="" dhctl mirror --images-bundle-path /tmp/d8-images/d8.tar --registry="your.private.registry.com:5000/deckhouse/ee"

Пример команды для загрузки образов из файла /tmp/d8-images/d8.tar:

Please note that the images will be uploaded to the registry along the path specified in the --registry parameter (in the example above - /deckhouse/ee). Before running the command, make sure this path exists in your registry, and the account you are using has write permissions.

shell DHCTL_CLI_MIRROR_USER=”" DHCTL_CLI_MIRROR_PASS="" dhctl mirror --images-bundle-path /tmp/d8-images/d8.tar --registry="your.private.registry.com:5000/deckhouse/ee"

If your registry does not require authentication, you may omit both --registry-login and --registry-password flags as well as DHCTL_CLI_MIRROR_USER/DHCTL_CLI_MIRROR_PASS variables.

Обратите внимание, образы будут выгружены в registry по пути, указанному в параметре --registry (в примере - /deckhouse/ee). Перед запуском команды убедитесь, что этот путь существует и у используемой учетной записи есть права на запись.

1. Once pushing images to the air-gapped private registry is complete, you are ready to install Deckhouse from it. Refer to the Getting started guide.

Если ваш registry не требует авторизации, флаги --registry-login/--registry-password или переменные $DHCTL_CLI_MIRROR_USER/$DHCTL_CLI_MIRROR_PASS указывать не нужно.

To run the installer, use its image from your private registry where Deckhouse images reside, rather than from the public registry. In other words, your address should look something like your.private.registry.com:5000/deckhouse/ee/install:stable instead of registry.deckhouse.io/deckhouse/ee/install:stable.

1. После загрузки образов в изолированный registry можно переходить к установке Deckhouse. Воспользуйтесь руководством по быстрому старту.

During installation, add your registry address and authorization data to the InitConfiguration resource (the imagesRepo and registryDockerCfg parameters; you might refer to step 3 of the Getting started guide as well).

При запуске установщика используйте его образ из registry, в который ранее были загружены образы Deckhouse, а не из публичного registry. Например, используйте адрес вида your.private.registry.com:5000/deckhouse/ee/install:stable вместо registry.deckhouse.ru/deckhouse/ee/install:stable.

After installation, apply DeckhouseReleases manifests that were generated during pull operation to your cluster via kubectl as follows:

В ресурсе InitConfiguration при установке также используйте адрес вашего registry и данные авторизации (параметры imagesRepo, registryDockerCfg или шаг 3 руководства по быстрому старту).

shell kubectl apply -f $(pwd)/d8-images/deckhousereleaases.yaml

После завершения установки примените сгенерированные во время загрузки манифесты DeckhouseReleases к вашему кластеру используя kubectl:

Manually uploading images of Deckhouse modules into an isolated private registry

shell kubectl apply -f $(pwd)/d8-images/deckhousereleaases.yaml

The steps below are necessary for manually loading images of modules connected from the module source (the ModuleSource resource):

Ручная загрузка образов подключаемых модулей Deckhouse в изолированный приватный registry

1. Run Deckhouse installer version 1.56.0 or higher:

Ниже описаны шаги, необходимые для ручной загрузки образов модулей, подключаемых из источника модулей (ресурс ModuleSource):

shell docker run -ti –pull=always -v $(HOME)/d8-modules:/tmp/d8-modules -v $(HOME)/module_source.yml:/tmp/module_source.yml registry.deckhouse.io/deckhouse/ce/install:v1.58.4 bash

1. Запустите установщик Deckhouse версии 1.56.0 или выше.

Note that the directory from the host file system is mounted in the installer container. It will store module images and the ModuleSource YAML manifest describing the source of modules.

shell docker run -ti –pull=always -v $(HOME)/d8-modules:/tmp/d8-modules -v $(HOME)/module_source.yml:/tmp/module_source.yml registry.deckhouse.ru/deckhouse/ce/install:v1.58.4 bash

1. Pull module images from their source registry, defined as a ModuleSource resource, into a dedicated directory using the command dhctl mirror-modules.

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

dhctl mirror-modules pulls only versions of modules available in the module release channels at the time of copying.

1. Скачайте образы модулей из их источника, описанного в виде ресурса ModuleSource в выделенную директорию, используя команду dhctl mirror-modules.

The following command will pull module images from the source described in the ModuleSource resource located in the $HOME/module_source.yml file:

dhctl mirror-modules скачивает только версии модулей, доступные в каналах обновлений модуля на момент копирования.

shell dhctl mirror-modules -d /tmp/d8-modules -m /tmp/module_source.yml

Следующая команда скачает образы модулей из источника, описанного в ресурсе ModuleSource, находящемся в файле $HOME/module_source.yml:

1. Optional: Copy the dhctl binary from the container to the directory to which Deckhouse images were pulled.

shell dhctl mirror-modules -d /tmp/d8-modules -m /tmp/module_source.yml

shell cp /usr/bin/dhctl /tmp/d8-images/dhctl

1. Опционально: Скопируйте утилиту dhctl из контейнера в директорию со скачанными образами Deckhouse.

1. To continue with installation, use the dhctl binary you copied earlier OR repeat steps 1 and 2 for the Deckhouse installer on the host with access to the air-gapped registry. Make sure the directory with the pulled modules images is mounted into the container.

shell cp /usr/bin/dhctl /tmp/d8-modules/dhctl

1. Upload module images to the isolated registry using the dhctl mirror-modules command.

1. Передайте директорию с загруженными образами модулей на хост с доступом к изолированному registry. Для продолжения установки используйте скопированную ранее утилиту dhctl или запустите установщик Deckhouse аналогично пунктам 1 и 2 на хосте с доступом к изолированному registry. Не забудьте смонтировать директорию с загруженными образами модулей в контейнер установщика.

Below is an example of a command for pulling images from the /tmp/d8-modules directory:

1. Загрузите образы модулей в изолированный registry с помощью команды dhctl mirror-modules.

shell DHCTL_CLI_MIRROR_USER=”" DHCTL_CLI_MIRROR_PASS="" dhctl mirror-modules -d /tmp/d8-modules --registry="your.private.registry.com:5000/deckhouse-modules"

Пример команды для загрузки образов из директории /tmp/d8-modules:

Please note that the images will be uploaded to the registry along the path specified in the --registry parameter (in the example above - /deckhouse-modules). Before running the command, make sure this path exists in your registry, and the account you are using has write permissions.

shell DHCTL_CLI_MIRROR_USER=”" DHCTL_CLI_MIRROR_PASS="" dhctl mirror-modules -d /tmp/d8-modules --registry="your.private.registry.com:5000/deckhouse-modules"

If your registry does not require authentication, omit both --registry-login and --registry-password flags.

Обратите внимание, образы будут выгружены в registry по пути, указанному в параметре --registry (в примере - /deckhouse-modules). Перед запуском команды убедитесь, что этот путь существует и у используемой учетной записи есть права на запись.

1. After uploading the images to the air-gapped registry, edit the ModuleSource YAML manifest:

Если ваш registry не требует авторизации, флаги --registry-login/--registry-password указывать не нужно.

• Change the .spec.registry.repo field to the address that you specified in the --registry parameter when you uploaded the images;
• Change the .spec.registry.dockerCfg field to a base64 string with the authorization data for your registry in dockercfg format. Refer to your registry’s documentation for information on how to obtain this token.

1. После загрузки образов в изолированный registry, отредактируйте YAML-манифест ModuleSource:

1. Apply the ModuleSource manifest you got in the previous step to the cluster.

• Измените поле .spec.registry.repo на адрес, который вы указали в параметре --registry при выгрузке образов;
• Измените поле .spec.registry.dockerCfg на Base64-строку с данными для авторизации в вашем registry в формате dockercfg. Обратитесь к документации вашего registry для получения информации о том, как сгенерировать этот токен.

shell kubectl apply -f $HOME/module_source.yml

1. Примените в кластере полученный на прошлом шаге манифест ModuleSource:

Once the manifest has been applied, the modules are ready for use. For more detailed instructions on configuring and using modules, please refer to the module developer’s documentation.

shell kubectl apply -f $HOME/module_source.yml

How do I switch a running Deckhouse cluster to use a third-party registry?

После применения манифеста модули готовы к использованию. Обратитесь к документации разработчика модулей для получения дальнейших инструкций по их настройке и использованию.

Using a registry other than registry.deckhouse.io and registry.deckhouse.ru is only available in the Enterprise Edition.

Как переключить работающий кластер Deckhouse на использование стороннего registry?

To switch the Deckhouse cluster to using a third-party registry, follow these steps:

Использование registry отличных от registry.deckhouse.io и registry.deckhouse.ru доступно только в Enterprise Edition.

• Run deckhouse-controller helper change-registry inside the Deckhouse Pod with the new registry settings.
• Example:

Для переключения кластера Deckhouse на использование стороннего registry выполните следующие действия:

shell kubectl exec -ti -n d8-system deploy/deckhouse – deckhouse-controller helper change-registry –user MY-USER –password MY-PASSWORD registry.example.com/deckhouse

• Выполните команду deckhouse-controller helper change-registry из пода Deckhouse с параметрами нового registry.
• Пример запуска:

• If the registry uses a self-signed certificate, put the root CA certificate that validates the registry’s HTTPS certificate to file /tmp/ca.crt in the Deckhouse Pod and add the --ca-file /tmp/ca.crt option to the script or put the content of CA into a variable as follows:

shell kubectl exec -ti -n d8-system deploy/deckhouse – deckhouse-controller helper change-registry
–user MY-USER –password MY-PASSWORD registry.example.com/deckhouse/ee

shell $ CA_CONTENT=$(cat «EOF —–BEGIN CERTIFICATE—– CERTIFICATE —–END CERTIFICATE—– —–BEGIN CERTIFICATE—– CERTIFICATE —–END CERTIFICATE—– EOF ) $ kubectl exec -n d8-system deploy/deckhouse – bash -c “echo ‘$CA_CONTENT’ > /tmp/ca.crt && deckhouse-controller helper change-registry –ca-file /tmp/ca.crt –user MY-USER –password MY-PASSWORD registry.example.com/deckhouse/ee”

• Если registry использует самоподписные сертификаты, положите корневой сертификат соответствующего сертификата registry в файл /tmp/ca.crt в поде Deckhouse и добавьте к вызову опцию --ca-file /tmp/ca.crt, или вставьте содержимое CA в переменную, как в примере ниже:

• Wait for the Deckhouse Pod to become Ready. Restart Deckhouse Pod if it will be in ImagePullBackoff state.
• Wait for bashible to apply the new settings on the master node. The bashible log on the master node (journalctl -u bashible) should contain the message Configuration is in sync, nothing to do.
• If you want to disable Deckhouse automatic updates, remove the releaseChannel parameter from the deckhouse module configuration.
• Check if there are Pods with original registry in cluster (if there are — restart them):

shell $ CA_CONTENT=$(cat «EOF —–BEGIN CERTIFICATE—– CERTIFICATE —–END CERTIFICATE—– —–BEGIN CERTIFICATE—– CERTIFICATE —–END CERTIFICATE—– EOF ) $ kubectl exec -n d8-system deploy/deckhouse – bash -c “echo ‘$CA_CONTENT’ > /tmp/ca.crt && deckhouse-controller helper change-registry –ca-file /tmp/ca.crt –user MY-USER –password MY-PASSWORD registry.example.com/deckhouse/ee”

shell kubectl get pods -A -o json | jq ‘.items[] | select(.spec.containers[] | select((.image | contains(“deckhouse.io”)))) | .metadata.namespace + “\t” + .metadata.name’ -r

• Дождитесь перехода пода Deckhouse в статус Ready. Если под будет находиться в статусе ImagePullBackoff, перезапустите его.
• Дождитесь применения bashible новых настроек на master-узле. В журнале bashible на master-узле (journalctl -u bashible) должно появится сообщение Configuration is in sync, nothing to do.
• Если необходимо отключить автоматическое обновление Deckhouse через сторонний registry, удалите параметр releaseChannel из конфигурации модуля deckhouse.
• Проверьте, не осталось ли в кластере подов с оригинальным адресом registry:

How to bootstrap a cluster and run Deckhouse without the usage of release channels?

shell kubectl get pods -A -o json | jq ‘.items[] | select(.spec.containers[] | select((.image | contains(“deckhouse.io”)))) | .metadata.namespace + “\t” + .metadata.name’ -r

This method should only be used if there are no release channel images in your air-gapped registry.

Как создать кластер и запустить Deckhouse без использования каналов обновлений?

• If you want to install Deckhouse with automatic updates disabled:
• Use the tag of the installer image of the corresponding version. For example, use the image your.private.registry.com/deckhouse/install:v1.44.3, if you want to install release v1.44.3.
• Set the corresponding version number in the deckhouse.devBranch parameter of the InitConfiguration resource.
• Do not set the deckhouse.releaseChannel parameter of the InitConfiguration resource.
• If you want to disable automatic updates for an already installed Deckhouse (including patch release updates), then delete the releaseChannel parameter from the deckhouse module configuration.

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

Using a proxy server

• Если вы хотите установить Deckhouse с отключенным автоматическим обновлением:
• Используйте тег образа установщика соответствующей версии. Например, если вы хотите установить релиз v1.44.3, используйте образ your.private.registry.com/deckhouse/install:v1.44.3.
• Укажите соответствующий номер версии в параметре deckhouse.devBranch в ресурсе InitConfiguration.
• Не указывайте параметр deckhouse.releaseChannel в ресурсе InitConfiguration.
• Если вы хотите отключить автоматические обновления у уже установленного Deckhouse (включая обновления patch-релизов), удалите параметр releaseChannel из конфигурации модуля deckhouse.

This feature is available in Enterprise Edition only.

Использование proxy-сервера

• Prepare the VM for setting up the proxy. The machine must be accessible to the nodes that will use it as a proxy and be connected to the Internet.
• Install Squid on the server (here and further examples for Ubuntu):

Доступно только в Enterprise Edition.

shell apt-get install squid

• Подготовьте сервер (или виртуальную машину). Сервер должен быть доступен с необходимых узлов кластера, и у него должен быть выход в интернет.
• Установите Squid (здесь и далее примеры для Ubuntu):

• Create a config file:

shell apt-get install squid

shell cat «EOF > /etc/squid/squid.conf auth_param basic program /usr/lib/squid3/basic_ncsa_auth /etc/squid/passwords auth_param basic realm proxy acl authenticated proxy_auth REQUIRED http_access allow authenticated

• Создайте файл конфигурации Squid:

Choose the port you want. Below we set it to default 3128. http_port 3128

shell cat «EOF > /etc/squid/squid.conf auth_param basic program /usr/lib/squid3/basic_ncsa_auth /etc/squid/passwords auth_param basic realm proxy acl authenticated proxy_auth REQUIRED http_access allow authenticated

• Create a user for proxy-server authentication:

Choose the port you want. Below we set it to default 3128. http_port 3128

Example for the user test with the password test (be sure to change):

• Создайте пользователя и пароль для аутентификации на proxy-сервере:

shell echo “test:$(openssl passwd -crypt test)” » /etc/squid/passwords

Пример для пользователя test с паролем test (обязательно измените):

• Start squid and enable the system to start it up automatically:

shell echo “test:$(openssl passwd -crypt test)” » /etc/squid/passwords

shell systemctl restart squid systemctl enable squid

• Запустите Squid и включите его автоматический запуск при загрузке сервера:

shell systemctl restart squid systemctl enable squid

Use the proxy parameter of the ClusterConfiguration resource to configure proxy usage.

An example:

Для настройки Deckhouse на использование proxy используйте параметр proxy ресурса ClusterConfiguration.

yaml apiVersion: deckhouse.io/v1 kind: ClusterConfiguration clusterType: Cloud cloud: provider: OpenStack prefix: main podSubnetCIDR: 10.111.0.0/16 serviceSubnetCIDR: 10.222.0.0/16 kubernetesVersion: “Automatic” cri: “Containerd” clusterDomain: “cluster.local” proxy: httpProxy: “http://user:password@proxy.company.my:3128” httpsProxy: “https://user:password@proxy.company.my:8443”

Пример:

Changing the configuration

yaml apiVersion: deckhouse.io/v1 kind: ClusterConfiguration clusterType: Cloud cloud: provider: OpenStack prefix: main podSubnetCIDR: 10.111.0.0/16 serviceSubnetCIDR: 10.222.0.0/16 kubernetesVersion: “Automatic” cri: “Containerd” clusterDomain: “cluster.local” proxy: httpProxy: “http://user:password@proxy.company.my:3128” httpsProxy: “https://user:password@proxy.company.my:8443”

How do I change the configuration of a cluster?

Изменение конфигурации

The general cluster parameters are stored in the ClusterConfiguration structure.

Как изменить конфигурацию кластера?

To change the general cluster parameters, run the command:

Общие параметры кластера хранятся в структуре ClusterConfiguration.

shell kubectl -n d8-system exec -ti deploy/deckhouse – deckhouse-controller edit cluster-configuration

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

After saving the changes, Deckhouse will bring the cluster configuration to the state according to the changed configuration. Depending on the size of the cluster, this may take some time.

shell kubectl -n d8-system exec -ti deploy/deckhouse – deckhouse-controller edit cluster-configuration

How do I change the configuration of a cloud provider in a cluster?

После сохранения изменений Deckhouse приведет конфигурацию кластера к измененному состоянию. В зависимости от размеров кластера это может занять какое-то время.

Cloud provider setting of a cloud of hybrid cluster are stored in the <PROVIDER_NAME>ClusterConfiguration structure, where <PROVIDER_NAME> — name/code of the cloud provider. E.g., for an OpenStack provider, the structure will be called OpenStackClusterConfiguration.

Как изменить конфигурацию облачного провайдера в кластере?

Regardless of the cloud provider used, its settings can be changed using the following command:

Настройки используемого облачного провайдера в облачном или гибридном кластере хранятся в структуре <PROVIDER_NAME>ClusterConfiguration, где <PROVIDER_NAME> — название/код провайдера. Например, для провайдера OpenStack структура будет называться OpenStackClusterConfiguration.

shell kubectl -n d8-system exec -ti deploy/deckhouse – deckhouse-controller edit provider-cluster-configuration

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

How do I change the configuration of a static cluster?

shell kubectl -n d8-system exec -ti deploy/deckhouse – deckhouse-controller edit provider-cluster-configuration

Settings of a static cluster are stored in the StaticClusterConfiguration structure.

Как изменить конфигурацию статического кластера?

To change the settings of a static cluster, run the command:

Настройки статического кластера хранятся в структуре StaticClusterConfiguration.

shell kubectl -n d8-system exec -ti deploy/deckhouse – deckhouse-controller edit static-cluster-configuration

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

How to switch Deckhouse EE to CE?

shell kubectl -n d8-system exec -ti deploy/deckhouse – deckhouse-controller edit static-cluster-configuration

The instruction implies using the public address of the container registry: registry.deckhouse.io. Using a registry other than registry.deckhouse.io and registry.deckhouse.ru is only available in the Enterprise Edition.

Как переключить Deckhouse EE на CE?

Deckhouse CE does not support cloud clusters on OpenStack and VMware vSphere.

Инструкция подразумевает использование публичного адреса container registry: registry.deckhouse.ru. Использование registry отличных от registry.deckhouse.io и registry.deckhouse.ru доступно только в Enterprise Edition.

To switch Deckhouse Enterprise Edition to Community Edition, follow these steps:

В Deckhouse CE не поддерживается работа облачных кластеров на OpenStack и VMware vSphere.

1. Make sure that the modules used in the cluster are supported in Deckhouse CE. Disable modules that are not supported in Deckhouse CE.

Для переключения кластера Deckhouse Enterprise Edition на Community Edition выполните следующие действия:

1. Run the following command:

1. Убедитесь, что используемые в кластере модули поддерживаются в версии CE. Отключите модули, которые не поддерживаются в Deckhouse CE.

shell kubectl exec -ti -n d8-system deploy/deckhouse – deckhouse-controller helper change-registry registry.deckhouse.io/deckhouse/ce

1. Выполните следующую команду:

1. Wait for the Deckhouse Pod to become Ready:

shell kubectl exec -ti -n d8-system deploy/deckhouse – deckhouse-controller helper change-registry registry.deckhouse.ru/deckhouse/ce

shell kubectl -n d8-system get po -l app=deckhouse

1. Дождитесь перехода пода Deckhouse в статус Ready:

1. Restart Deckhouse Pod if it will be in ImagePullBackoff state:

shell kubectl -n d8-system get po -l app=deckhouse

shell kubectl -n d8-system delete po -l app=deckhouse

1. Если под будет находиться в статусе ImagePullBackoff, перезапустите его:

1. Wait for Deckhouse to restart and to complete all tasks in the queue:

shell kubectl -n d8-system delete po -l app=deckhouse

shell kubectl -n d8-system exec deploy/deckhouse – deckhouse-controller queue main | grep status:

1. Дождитесь перезапуска Deckhouse и выполнения всех задач в очереди:

Example of output when there are still jobs in the queue (length 38):

shell kubectl -n d8-system exec deploy/deckhouse – deckhouse-controller queue main | grep status:

console kubectl -n d8-system exec deploy/deckhouse – deckhouse-controller queue main | grep status: Queue ‘main’: length 38, status: ‘run first task’

Пример вывода, когда в очереди еще есть задания (length 38):

Example of output when the queue is empty (length 0):

console kubectl -n d8-system exec deploy/deckhouse – deckhouse-controller queue main | grep status: Queue ‘main’: length 38, status: ‘run first task’

console kubectl -n d8-system exec deploy/deckhouse – deckhouse-controller queue main | grep status: Queue ‘main’: length 0, status: ‘waiting for task 0s’

Пример вывода, когда очередь пуста (length 0):

1. On the master node, check the application of the new settings.

console kubectl -n d8-system exec deploy/deckhouse – deckhouse-controller queue main | grep status: Queue ‘main’: length 0, status: ‘waiting for task 0s’

The message Configuration is in sync, nothing to do should appear in the bashible systemd service log on the master node.

1. На master-узле проверьте применение новых настроек.

An example::

В журнале systemd-сервиса bashible на master-узле должно появиться сообщение Configuration is in sync, nothing to do.

console journalctl -u bashible -n 5 Jan 12 12:38:20 demo-master-0 bashible.sh[868379]: Configuration is in sync, nothing to do. Jan 12 12:38:20 demo-master-0 systemd[1]: bashible.service: Deactivated successfully. Jan 12 12:39:18 demo-master-0 systemd[1]: Started Bashible service. Jan 12 12:39:19 demo-master-0 bashible.sh[869714]: Configuration is in sync, nothing to do. Jan 12 12:39:19 demo-master-0 systemd[1]: bashible.service: Deactivated successfully.

Пример:

1. Check if there are any Pods left in the cluster with the Deckhouse EE registry address:

console journalctl -u bashible -n 5 Jan 12 12:38:20 demo-master-0 bashible.sh[868379]: Configuration is in sync, nothing to do. Jan 12 12:38:20 demo-master-0 systemd[1]: bashible.service: Deactivated successfully. Jan 12 12:39:18 demo-master-0 systemd[1]: Started Bashible service. Jan 12 12:39:19 demo-master-0 bashible.sh[869714]: Configuration is in sync, nothing to do. Jan 12 12:39:19 demo-master-0 systemd[1]: bashible.service: Deactivated successfully.

shell kubectl get pods -A -o json | jq ‘.items[] | select(.spec.containers[] | select((.image | contains(“deckhouse.io/deckhouse/ee”)))) | .metadata.namespace + “\t” + .metadata.name’ -r | sort | uniq

1. Проверьте, не осталось ли в кластере подов с адресом registry для Deckhouse EE:

Sometimes, some static Pods may remain running (for example, kubernetes-api-proxy-*). This is due to the fact that kubelet does not restart the Pod despite changing the corresponding manifest, because the image used is the same for the Deckhouse CE and EE. To make sure that the corresponding manifests have also been changed, run the following command on any master node:

shell kubectl get pods -A -o json | jq ‘.items[] | select(.spec.containers[] | select((.image | contains(“deckhouse.io/deckhouse/ee”)))) | .metadata.namespace + “\t” + .metadata.name’ -r | sort | uniq

shell grep -ri ‘deckhouse.io/deckhouse/ee’ /etc/kubernetes | grep -v backup

Иногда могут оставаться запущенными некоторые static Pod’ы (например, kubernetes-api-proxy-*). Это связанно с тем, что kubelet не перезапускает под несмотря на изменение соответствующего манифеста, так как используемый образ одинаков для Deckhouse CE и EE. Выполните на любом master-узле следующую команду, чтобы убедиться, что соответствующие манифесты также были изменены:

The output of the command should be empty.

shell grep -ri ‘deckhouse.io/deckhouse/ee’ /etc/kubernetes | grep -v backup

How to switch Deckhouse CE to EE?

Вывод команды должен быть пуст.

You will need a valid license key (you can request a trial license key if necessary).

Как переключить Deckhouse CE на EE?

The instruction implies using the public address of the container registry: registry.deckhouse.io. If you use a different container registry address, change the commands or use the instruction for switching Deckhouse to using a third-party registry.

Вам потребуется действующий лицензионный ключ (вы можете запросить временный ключ при необходимости).

To switch Deckhouse Community Edition to Enterprise Edition, follow these steps:

Инструкция подразумевает использование публичного адреса container registry: registry.deckhouse.ru. В случае использования другого адреса container registry измените команды или воспользуйтесь инструкцией по переключению Deckhouse на использование стороннего registry.

1. Run the following command:

Для переключения кластера Deckhouse Community Edition на Enterprise Edition выполните следующие действия:

shell LICENSE_TOKEN= kubectl exec -ti -n d8-system deploy/deckhouse -- deckhouse-controller helper change-registry --user license-token --password $LICENSE_TOKEN registry.deckhouse.io/deckhouse/ee

1. Выполните следующую команду:

1. Wait for the Deckhouse Pod to become Ready:

shell LICENSE_TOKEN= kubectl exec -ti -n d8-system deploy/deckhouse -- deckhouse-controller helper change-registry --user license-token --password $LICENSE_TOKEN registry.deckhouse.ru/deckhouse/ee

shell kubectl -n d8-system get po -l app=deckhouse

1. Дождитесь перехода пода Deckhouse в статус Ready:

1. Restart Deckhouse Pod if it will be in ImagePullBackoff state:

shell kubectl -n d8-system get po -l app=deckhouse

shell kubectl -n d8-system delete po -l app=deckhouse

1. Если под будет находиться в статусе ImagePullBackoff, перезапустите его:

1. Wait for Deckhouse to restart and to complete all tasks in the queue:

shell kubectl -n d8-system delete po -l app=deckhouse

shell kubectl -n d8-system exec deploy/deckhouse – deckhouse-controller queue main | grep status:

1. Дождитесь перезапуска Deckhouse и выполнения всех задач в очереди:

Example of output when there are still jobs in the queue (length 38):

shell kubectl -n d8-system exec deploy/deckhouse – deckhouse-controller queue main | grep status:

console kubectl -n d8-system exec deploy/deckhouse – deckhouse-controller queue main | grep status: Queue ‘main’: length 38, status: ‘run first task’

Пример вывода, когда в очереди еще есть задания (length 38):

Example of output when the queue is empty (length 0):

console kubectl -n d8-system exec deploy/deckhouse – deckhouse-controller queue main | grep status: Queue ‘main’: length 38, status: ‘run first task’

console kubectl -n d8-system exec deploy/deckhouse – deckhouse-controller queue main | grep status: Queue ‘main’: length 0, status: ‘waiting for task 0s’

Пример вывода, когда очередь пуста (length 0):

1. On the master node, check the application of the new settings.

console kubectl -n d8-system exec deploy/deckhouse – deckhouse-controller queue main | grep status: Queue ‘main’: length 0, status: ‘waiting for task 0s’

The message Configuration is in sync, nothing to do should appear in the bashible systemd service log on the master node.

1. На master-узле проверьте применение новых настроек.

An example:

В журнале systemd-сервиса bashible на master-узле должно появиться сообщение Configuration is in sync, nothing to do.

console journalctl -u bashible -n 5 Jan 12 12:38:20 demo-master-0 bashible.sh[868379]: Configuration is in sync, nothing to do. Jan 12 12:38:20 demo-master-0 systemd[1]: bashible.service: Deactivated successfully. Jan 12 12:39:18 demo-master-0 systemd[1]: Started Bashible service. Jan 12 12:39:19 demo-master-0 bashible.sh[869714]: Configuration is in sync, nothing to do. Jan 12 12:39:19 demo-master-0 systemd[1]: bashible.service: Deactivated successfully.

Пример:

1. Check if there are any Pods left in the cluster with the Deckhouse CE registry address:

console journalctl -u bashible -n 5 Jan 12 12:38:20 demo-master-0 bashible.sh[868379]: Configuration is in sync, nothing to do. Jan 12 12:38:20 demo-master-0 systemd[1]: bashible.service: Deactivated successfully. Jan 12 12:39:18 demo-master-0 systemd[1]: Started Bashible service. Jan 12 12:39:19 demo-master-0 bashible.sh[869714]: Configuration is in sync, nothing to do. Jan 12 12:39:19 demo-master-0 systemd[1]: bashible.service: Deactivated successfully.

shell kubectl get pods -A -o json | jq ‘.items[] | select(.spec.containers[] | select((.image | contains(“deckhouse.io/deckhouse/ce”)))) | .metadata.namespace + “\t” + .metadata.name’ -r | sort | uniq

1. Проверьте, не осталось ли в кластере подов с адресом registry для Deckhouse CE:

Sometimes, some static Pods may remain running (for example, kubernetes-api-proxy-*). This is due to the fact that kubelet does not restart the Pod despite changing the corresponding manifest, because the image used is the same for the Deckhouse CE and EE. To make sure that the corresponding manifests have also been changed, run the following command on any master node:

shell kubectl get pods -A -o json | jq ‘.items[] | select(.spec.containers[] | select((.image | contains(“deckhouse.io/deckhouse/ce”)))) | .metadata.namespace + “\t” + .metadata.name’ -r | sort | uniq

shell grep -ri ‘deckhouse.io/deckhouse/ce’ /etc/kubernetes | grep -v backup

Иногда могут оставаться запущенными некоторые static Pod’ы (например, kubernetes-api-proxy-*). Это связанно с тем, что kubelet не перезапускает под несмотря на изменение соответствующего манифеста, так как используемый образ одинаков для Deckhouse CE и EE. Выполните на любом master-узле следующую команду, чтобы убедиться, что соответствующие манифесты также были изменены:

The output of the command should be empty.

shell grep -ri ‘deckhouse.io/deckhouse/ce’ /etc/kubernetes | grep -v backup

How do I upgrade the Kubernetes version in a cluster?

Вывод команды должен быть пуст.

To upgrade the Kubernetes version in a cluster change the kubernetesVersion parameter in the ClusterConfiguration structure by making the following steps:

1. Run the command:

Как обновить версию Kubernetes в кластере?

shell kubectl -n d8-system exec -ti deploy/deckhouse – deckhouse-controller edit cluster-configuration

Чтобы обновить версию Kubernetes в кластере, измените параметр kubernetesVersion в структуре ClusterConfiguration выполнив следующие шаги:

1. Выполните команду:

1. Change the kubernetesVersion field.
2. Save the changes. Cluster nodes will start updating sequentially.
3. Wait for the update to finish. You can track the progress of the update using the kubectl get no command. The update is completed when the new version appears in the command’s output for each cluster node in the VERSION column.

shell kubectl -n d8-system exec -ti deploy/deckhouse – deckhouse-controller edit cluster-configuration

How do I run Deckhouse on a particular node?

1. Измените параметр kubernetesVersion.
2. Сохраните изменения. Узлы кластера начнут последовательно обновляться.
3. Дождитесь окончания обновления. Отслеживать ход обновления можно с помощью команды kubectl get no. Обновление можно считать завершенным, когда в выводе команды у каждого узла кластера в колонке VERSION появится обновленная версия.

Set the nodeSelector parameter of the deckhouse module and avoid setting tolerations. The necessary values will be assigned to the tolerations parameter automatically.

Как запускать Deckhouse на произвольном узле?

Use only nodes with the CloudStatic or Static type to run Deckhouse. Also, avoid using a NodeGroup containing only one node to run Deckhouse.

Для запуска Deckhouse на произвольном узле установите у модуля deckhouse соответствующий параметр nodeSelector и не задавайте tolerations. Необходимые значения tolerations в этом случае будут проставлены автоматически.

Here is an example of the module configuration:

Используйте для запуска Deckhouse только узлы с типом CloudStatic или Static. Также избегайте использования для запуска Deckhouse группы узлов (NodeGroup), содержащей только один узел.

yaml apiVersion: deckhouse.io/v1alpha1 kind: ModuleConfig metadata: name: deckhouse spec: version: 1 settings: nodeSelector: node-role.deckhouse.io/deckhouse: “”

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

yaml apiVersion: deckhouse.io/v1alpha1 kind: ModuleConfig metadata: name: deckhouse spec: version: 1 settings: nodeSelector: node-role.deckhouse.io/deckhouse: “”