Руководство пользователя

Адрес

Если шаблон публичных доменов в кластере %s.example.com, то в веб-приложение можно зайти по адресу https://commander.example.com

Рабочие пространства

Работа с сущностями Deckhouse Commander проводится в рамках рабочих пространств. Рабочие пространства можно создавать, менять им название. В будущем доступ в рабочие пространства можно будет детально контролировать.

Пользователи управляют кластерами, шаблонами кластеров и инвентарем в рамках рабочего пространства. Также в рамках пространства выпускают токен доступа к API. Видимость объектов для такого токена будет ограничена только тем, что находится в рабочем пространстве.

Кластеры

Мы рекомендуем устанавливать Deckhouse Commander в управляющем кластере. Этот кластер должен служить цели централизованного управления и сбора информации со всей прикладной инфраструктуры, в том числе с прикладных кластеров. Кластеры, которыми управляет Deckhouse Commander, мы называем прикладными. Deckhouse Commander является источником истины для конфигурации кластеров. Далее мы рассмотрим, как это реализуется на практике.

Конфигурация кластера

Конфигурация кластера состоит из нескольких секций:

1. Входные параметры формируются на основе схемы входных параметров шаблона кластера
2. Хранилище образов – выбираем хранилище образов, из которого будет установлен кластер Deckhouse
3. Раздел «Инфраструктура»
   1. Kubernetes — ClusterConfiguration
   2. Размещение — <Provider>ClusterConfiguration или StaticClusterConfiguration
   3. Параметры SSH — подключение к мастер-узлам кластера
4. Раздел «Kubernetes» — произвольное количество вкладок с манифестами Kubernetes

Параметры кластера (входные параметры)

Это пользовательская конфигурация шаблона для пользователя шаблона. См. Входные параметры.

Хранилище образов

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

Хранилище образов является обязательным параметром конфигурации кластера.

По умолчанию в инсталляции Deckhouse Commander доступно для выбора хранилище образов управляющего кластера инсталляции.

Параметры хранилища образов

Имя

Произвольное имя хранилища образов, отображаемое в списке хранилищ образов. Обязательный параметр.

Адрес хранилища образов

Адрес хранилища образов с образами Deckhouse — URL для доступа к хранилищу образов. Обязательный параметр. Пример: registry.deckhouse.ru/deckhouse/ee.

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

Авторизация

Все данные необходимые для авторизации в указанном хранилище образов. Указывается имя пользователя и пароль, либо в поле Auth вставляется значение строкой в base64-кодировке (формат соответствует полю auth в стандартном docker config). Дополнительно в зависимости от настроек авторизации хранилища образов может потребоваться указать email.

Протокол доступа к хранилищу образов

Выбрать протокол доступа к хранилищу образов: HTTPS или HTTP.

Самоподписанный сертификат

Загрузить файл или указать текстом сертификат в случае если указанное хранилище образов использует самоподписанный сертификат.

Управление хранилищами образов

Добавление хранилищ образов осуществляется на экране создания или редактирования кластера во вкладке «Хранилище образов», а также во вкладке «Хранилище образов» в «Инвентаре». Чтобы добавить новое хранилище образов нужно заполнить его параметры (см. параметры хранилища образов).

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

Удаление хранилищ образов также осуществляется на экране создания или редактирования кластера во вкладке «Хранилище образов» и во вкладке «Хранилище образов» в «Инвентаре». Нельзя удалить хранилище образов если оно используется хотя бы в одном активном кластере.

Изменение хранилища образов кластера

Для существующих кластеров, управляемых DKP версии 1.72 и выше, доступна возможность изменить хранилище образов через интерфейс во вкладке «Хранилище образов» (конфигурация модуля registry производится автоматически, исходя из параметров выбранного хранилища образов в Deckhouse Commander).

При переключении кластера на другой режим следить за состоянием переключения можно в веб-интерфейсе администрирования кластера: Администрирование / Системные пространства имён / d8-system / Конфигурация / Secrets / registry-state.

Следующие conditions в секрете registry-state означают успешное переключение:

- lastTransitionTime: "..."
  message: |-
    Mode: Default
    registry.mycompany.org: all 163 items are checked
  reason: Ready
  status: "True"
  type: RegistryContainsRequiredImages
- lastTransitionTime: "..."
  message: ""
  reason: ""
  status: "True"
  type: ContainerdConfigPreflightReady
- lastTransitionTime: "..."
  message: ""
  reason: ""
  status: "True"
  type: TransitionContainerdConfigReady
- lastTransitionTime: "..."
  message: ""
  reason: ""
  status: "True"
  type: InClusterProxyReady
- lastTransitionTime: "..."
  message: ""
  reason: ""
  status: "True"
  type: DeckhouseRegistrySwitchReady
- lastTransitionTime: "..."
  message: ""
  reason: ""
  status: "True"
  type: FinalContainerdConfigReady
- lastTransitionTime: "..."
  message: ""
  reason: ""
  status: "True"
  type: Ready

Следующие conditions в секрете registry-state сигнализируют об определенной ошибке переключения:

- lastTransitionTime: "..."
  message: |-
    Mode: Default
    registry.mycompany.org: 162 of 163 items processed, 1 items with errors:
    - source: module/node-manager/bashible-apiserver
      image: registry.mycompany.org/deckhouse@sha256:5e3a07df520e74842f70915c213c9da918749c39c8df6250ed51b0cb892c9211
      error: HEAD https://registry.mycompany.org/v2/deckhouse/edition/manifests/sha256:5e3a07df520e74842f70915c213c9da918749c39c8df6250ed51b0cb892c9211: unexpected status code 404 Not Found (HEAD responses have no body, use GET for details)
  reason: Processing
  status: "False"
  type: RegistryContainsRequiredImages
- lastTransitionTime: "..."
  message: Transitioning to Direct
  reason: Processing
  status: "False"
  type: Ready

Раздел «Инфраструктура»

Kubernetes

Настройки версии Kubernetes, подсети подов и сервисов. См. ClusterConfiguration.

Размещение

Особенности размещения кластера в инфраструктуре. Здесь для статического кластера конфигурация может остаться пустой.

• Статические ресурсы

Для облачных кластеров указываются особенности доступа в API облака, набор узлов, которые будут созданы автоматически и отслеживаться (в том числе master-узлы), настройки зон доступности и т.д.

• OpenStack
• VMware Cloud Director
• VMware vSphere
• Yandex Cloud
• zVirt
• Базис.DynamiX
• Huawei Cloud
• Amazon Web Services
• Google Cloud Platform
• Microsoft Azure

Параметры SSH

apiVersion: dhctl.deckhouse.io/v1
kind: SSHConfig

sshBastionHost: 10.1.2.3              # Параметры джапм-хоста, если есть.
sshBastionPort: 2233
sshBastionUser: debian

sshUser: ubuntu
sshPort: 22
sshAgentPrivateKeys:                  # Список приватных ключей,
- key: |                              # как минимум один ключ обязателен.
    -----BEGIN RSA PRIVATE KEY-----
    .............................
    -----END RSA PRIVATE KEY-----
  passphrase: qwerty123               # Пароль ключа, если ключ им защищен.

sshExtraArgs: -vvv                    # Дополнительные параметры к SSH

---

apiVersion: dhctl.deckhouse.io/v1     # Описание хостов для подключения.
kind: SSHHost                         # Как правило здесь 1 или 3 хоста отведенных
host: 172.16.0.1                      # для роли мастер-узлов статических кластеров.
---
apiVersion: dhctl.deckhouse.io/v1
kind: SSHHost
host: 172.16.0.2
---
apiVersion: dhctl.deckhouse.io/v1
kind: SSHHost
host: 172.16.0.3

Раздел «Kubernetes»

Произвольные манифесты ресурсов Kubernetes и Deckhouse. В зависимости от режима управления, будут либо форсироваться в кластере, либо создадутся один раз и в дальнейшем будут игнорироваться.

Может быть создано множество вкладок с манифестами, в каждой из которых можно задать режим управления. Это позволяет гибко управлять обязательной и рекомендуемой конфигурацией кластера.

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

Инфраструктура

Управление кластерами сводится к трём типам операций: создание, удаление и изменение кластера. В любой момент времени у кластера в Deckhouse Commander есть один из инфраструктурных статусов:

• Новый — в Deckhouse Commander создана конфигурация кластера, но сам кластер еще ожидает создания
• Ошибка конфигурации — в Deckhouse Commander создана конфигурация кластера с ошибками, поэтому сам кластер не будет создан
• Создается — Deckhouse Commander разворачивает кластер
• Готов — кластер создан, и состояние инфраструктуры соответствует заданной в Deckhouse Commander конфигурации
• Изменяется — Deckhouse Commander приводит состояние кластера к заданной конфигурация
• Ошибка изменения, ошибка создания, ошибка удаления — внутренние или внешние ошибки, возникшие на пути управления кластеров
• В архиве — кластер больше не отслеживается Deckhouse Commander, он был предварительно удален или оставлен без управления Deckhouse Commander

Deckhouse Commander выполняет операции асинхронно с помощью заданий, на основании которых проводятся операции с кластером. Операции показаны внутри кластера на вкладке «Конфигурация» → «Операции с инфраструктурой» (в том числе для статических кластеров). Для каждого задания доступен лог выполнения. Результат выполнения задания определяет инфраструктурный статус кластера.

Возможные типы операций:

• Установка — Deckhouse Commander разворачивает новый кластер по заданной конфигурации.
• Изменение — приведение инфраструктуры существующего кластера к целевому состоянию.
• Проверка — сверка текущего состояния инфраструктуры с целевой конфигурацией без внесения изменений. Запускается с заданной периодичностью.
• Удаление — удаление кластера и связанной с ним облачной инфраструктуры.
• Присоединение — взятие под управление существующего кластера, ранее созданного вне Deckhouse Commander.
• Отсоединение — снятие кластера с управления Deckhouse Commander без его удаления.

Возможные статусы операций:

• Запланировано — операция создана и ожидает свободного экземпляра менеджера кластеров.
• В работе — менеджер кластеров выполняет операцию.
• Успешно — операция завершилась штатно.
• Ошибка — операция завершилась ошибкой. Её можно повторить вручную кнопкой «Повторить попытку» на странице кластера.
• Системная ошибка — операция была нештатно прервана и не сообщила штатную ошибку выполнения. Например, был остановлен процесс dhctl или менеджера кластеров, процесс был завершён рантаймом или вытеснена реплика менеджера. После такого статуса операцию можно безопасно повторить.
• Критическая ошибка — операция была нештатно прервана на фазе, которая изменяет состояние инфраструктуры кластера. Состояние инфраструктуры кластера может быть нарушено и потребовать ручного восстановления. Как правило, такая ошибка возможна только на фазах развёртывания или изменения инфраструктуры кластера, а не конфигурации.
• Отменён, Отменяется, Ожидает отмены — операция отменена пользователем или находится в процессе отмены.
• Пропущено — операция не выполнялась, потому что её результат стал неактуален (например, её сменила более новая операция).

Инфраструктурные операции выполняются компонентом менеджер кластеров. С заданным интервалом сверки менеджер кластеров сверяет, что целевая и фактическая конфигурация инфраструктуры совпадают. И если это не так, то приводит инфраструктуру к целевому состоянию. Если в кластере выставлен ручной режим обработки, то пользователь должен вручную подтвердить вносимые изменения. В случае автоматического режима обработки кластера, подтверждение не запрашивается.

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

Kubernetes

Помимо инфраструктурного статуса у кластера также есть статус Kubernetes-конфигурации. Он говорит о том, соответствует ли кластер конфигурации манифестов для Kubernetes. Манифесты ресурсов (далее — просто «ресурсы») — часть конфигурации кластера.

Состояние конфигурации Kubernetes может иметь три статуса

• Настроен — полное соответствие
• Не настроен — расхождение конфигурации и состояния кластера
• Нет данных — данные о состояние конфигурации устарели

За соответствие кластера заданной конфигурации ресурсам отвечает компонент, который установлен внутри прикладного кластера — агент Deckhouse Commander или commander-agent (далее — просто «агент»). Агент всегда старается привести конфигурацию кластера к заданной.

Агент подключается к API Deckhouse Commander и скачивает манифесты ресурсов, затем их применяет. Если в прикладном кластере удалить ресурс, который был создан агентом, то агент в течение минуты создаст ресурс заново. Если в конфигурации кластера удалить ресурс, то агент удалить ресурс в прикладном кластере. Если агент по каким-то причинам не может применить ресурс, в Deckhouse Commander Kubernetes-статус будет «не настроен».

В каждой группе Kubernetes-ресурсов можно выставить самостоятельный режим контроля конфигурации. Конфигурация «Kubernetes» никак не участвует в явной операции сверки, агент делает это в отдельном скрытом цикле. Результат работы агента представлен в отдельной таблице «Kubernetes» на странице кластера.

Помимо синхронизации конфигурации ресурсов в Kubernetes агент сообщает Deckhouse Commander данные телеметрии:

• Текущую версию Deckhouse Kubernetes Platform
• Доступность обновления на новую версию Deckhouse Kubernetes Platform
• Канал обновления Deckhouse Kubernetes Platform
• Версию Kubernetes
• Доступность системных компонентов
• Предупреждения, требующие внимания пользователя (алерты, ручное подтверждение перезагрузки узлов и т.п.)
• Основные метрики кластера: общее число ЦП, объем памяти, объем дискового хранилища и общее количество узлов.

Создание

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

По мере заполнения входных параметров, конфигурация кластера рендерится в виде YAML. Если в конфигурации обнаружатся ошибки, интерфейс Deckhouse Commander покажет их. Если сохранить новый кластер с ошибками, то его установка не будет начата до тех пор, пока ошибки не будут исправлены. Другими словами, кластер будет иметь статус «Ошибка конфигурации», а задание на установку не будет создано до тех пор, пока конфигурацию не изменят на корректную. Ошибки в конфигурации кластера могут быть вызваны как кодом шаблона, так и неверно заполненными входными параметрами.

Когда конфигурация становится валидной, создается задание на установку кластера, после чего менеджер кластеров создает кластер. Если кластер создается на заранее созданных машинах, то Deckhouse Commander конфигурирует на них компоненты Deckhouse Kubernetes Platform, после чего создает заданные ресурсы Kubernetes. Если кластер использует API облачной платформы или платформы виртуализации, то перед упомянутыми выше шагами Deckhouse Commander создает инфраструктуру. Точный набор ресурсов облака зависит от облачного провайдера.

После успешной установки кластера, Deckhouse Commander периодически будет проводить сверку его конфигурации. Если инфраструктурная конфигурация разойдется с объявленной в Deckhouse Commander, то Deckhouse Commander создаст задание на изменение инфраструктуры, чтобы привести к ее заявленному состоянию. Расхождение конфигурации может произойти как на стороне инфраструктуры, так и на стороне Deckhouse Commander. В первом случае это означает изменение в API облака, например, если что-то вручную изменили в конфигурации облачных ресурсов. Во втором случае это означает изменение конфигурации кластера, о чем мы будем говорить в следующем разделе.

Обновление

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

Когда конфигурация кластера изменяется, Deckhouse Commander создает задание на изменение инфраструктуры кластера. Агент приводит конфигурацию Kubernetes в желаемое состояние параллельно с изменением инфраструктуры.

Изменения конфигурации кластера могут привести к деструктивным изменениям инфраструктуры. Например, это может быть изменение виртуальных машин, требующих их удаления или пересоздания. Другой пример - изменение состава облачных зон доступности. Когда Deckhouse Commander обнаруживает деструктивные изменения, он не приводит эти изменения в силу до тех пор, пока пользователь не подтвердит.

Удаление

Удаление кластеров в Deckhouse Commander может быть достигнуто двумя способами. Оба способа доступны в кластере на равных условиях.

Первый способ — зачистка инфраструктуры от кластера. В этом случае Deckhouse Commander создает задание на удаление. Статические ресурсы очищаются от компонентов Deckhouse Kubernetes Platform, облачные ресурсы удаляются (например, виртуальные машины). После удаления конфигурация кластера не пропадает, кластер переходит в архив. К его конфигурации можно будет вернуться при необходимости, при этом среди активных кластеров этот кластер больше не будет числиться. Это отличает архивный кластер от активного.

Второй способ удалить кластер — ручное удаление. Deckhouse Commander переместит кластер в архив, но не будет заниматься очисткой инфраструктуры. Этот способ может быть полезен, если Deckhouse Commander по каким-то причинам не может справиться с корректным удалением кластера первым способом. В этом случае кластер будет иметь статус «ошибка удаления». Пользователю предстоит вручную очистить ресурсы, которые занимал Deckhouse Kubernetes Platform, а кластер переместить в архив вручную.

Перенос кластера между рабочими пространствами

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

Присоединение

Deckhouse Commander поддерживает присоединение существующих кластеров DKP. В отличие от процедуры создания кластера, для процедуры присоединения требуется уже существующий кластер.

Для присоединения существующего кластера DKP необходимо нажать на кнопку Присоединить на странице со списком кластеров, далее указать имя кластера, а также Параметры SSH для подключения к мастер-узлу.

Пример базовой конфигурации:

apiVersion: dhctl.deckhouse.io/v1
host: АДРЕС_МАСТЕР_УЗЛА
kind: SSHHost
---
apiVersion: dhctl.deckhouse.io/v1
kind: SSHConfig
sshAgentPrivateKeys:
- key: |
    -----BEGIN RSA PRIVATE KEY-----
    .............................
    -----END RSA PRIVATE KEY-----
  passphrase: qwerty123               # Пароль ключа, если ключ им защищен.
sshPort: 22
sshUser: ubuntu

После того как все необходимые параметры указаны:

1. Нажмите на кнопку Подключиться.
2. Deckhouse Commander проверит корректность конфигурации:
   • Если конфигурация корректна, он попытается подключиться к кластеру.
3. В случае успешного подключения:
   • Кластер будет сохранен в статусе Готов к присоединению.
   • Он станет доступен в общем списке кластеров.
4. Перейдите на страницу кластера.
5. Нажмите кнопку Присоединить.
6. Дождитесь завершения процедуры присоединения.
7. В случае успешного завершения процедуры:
   • Кластер перейдет в статус Готов.

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

Отсоединение

Отсоединение кластера необходимо для того, чтобы вывести его из под управления Deckhouse Commander. При этом, конфигурация кластера и Kubernetes-ресурсы больше не будут синхронизироваться, а кластер станет автономным. В последствии, такой кластер возможно будет присоединить обратно, но информация о версии шаблона, из которого он был развернут, будет утеряна.

Для отсоединения кластера необходимо перейти на страницу целевого кластера, в правом выпадающем меню операций с кластером (3 вертикальные точки) выбрать пункт Отсоединить и подтвердить свой выбор. После завершения процедуры отсоединения, кластер будет перемещён в Архив.

Шаблоны

Deckhouse Commander создан для того, чтобы управлять типовыми кластерами. Так как все секции конфигурации кластера представлены в формате YAML, шаблонизация кластеров представляет собой разметку требуемой YAML-конфигурации параметрами и описание схемы этих параметров. Для шаблонизации YAML используется синтаксис go template и набор функций sprig. Для описания схемы входных параметров используется собственный синтаксис, схожий с OpenAPI3, но при этом более простой.

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

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

Каждый кластер в Deckhouse Commander обладает конфигурацией, которая была получена из шаблона (если уже существующий кластер не был импортирован). Кластер также «помнит», на основании какого шаблона и какой его версии он сконфигурирован. Благодаря этой привязке в кластере показывается набор входных параметров кластера в виде веб-формы из заданной версии заданного шаблона.

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

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

Создание и поддержание шаблона может стать кропотливой инженерной задачей, требующей тестирования установки и обновления кластеров. Версии шаблонов во время этой работы могут накапливаться. Чтобы было проще ориентироваться в версиях, в Deckhouse Commander предусмотрена возможность оставлять комментарий для версии шаблона. Также есть возможность делать версии шаблона недоступными в интерфейсе кластера. Это может быть полезно, чтобы оградить пользователя от заведомо нерабочих версий шаблона.

Инвентарь, каталоги записей

Каталоги и записи

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

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

Во время создания каталога можно выбрать режим использования записей:

1. запись в каталоге может одновременно использоваться в нескольких кластерах
2. запись в каталоге может одновременно использоваться только в одном кластере, удаление или отсоединение кластера освобождает запись для использования в других кластерах

Первый вариант подходит для переиспользуемой конфигурации. Второй — для использования заранее подготовленной инфраструктуры. Это могут быть выделенные подсети, заранее созданные балансировщики нагрузки, виртуальные машины, доменные имена, IP-адреса и так далее. Такие данные удобно подготовить заранее и отслеживать, используются ли они и, если да, то в каких кластерах.

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

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

- key: hostname
  type: string
  title: Имя хоста
  unique: true
  pattern: ^[a-z0-9.-]+$
  identifier: true

- key: ip
  type: string
  title: IP-адрес
  format: ipv4
  unique: true
  identifier: true

Как использовать каталог в кластере

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

- key: workerMachines     # имя параметра в шаблоне
  title: Воркеры
  catalog: worker-nodes   # идентификатор каталога
  minItems: 1
  maxItems: 10

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

Импортирование данных в каталоги через API

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

{
  "name": "Рабочие хосты",
  "slug": "worker-nodes",
  "params": [
    {
      "key": "hostname",
      "type": "string",
      "title": "Имя хоста",
      "unique": true,
      "pattern": "^[a-z0-9.-]+$",
      "identifier": true
    },
    {
      "key": "ip",
      "type": "string",
      "title": "IP-адрес",
      "format": "ipv4",
      "unique": true,
      "identifier": true
    }
  ],
  "resources": [
    { "values": { "ip": "10.128.0.39", "hostname": "worker-1" } },
    { "values": { "ip": "10.128.0.47", "hostname": "worker-2" } },
    { "values": { "ip": "10.128.0.24", "hostname": "worker-3" } },
    { "values": { "ip": "10.128.0.17", "hostname": "worker-4" } },
    { "values": { "ip": "10.128.0.55", "hostname": "worker-5" } },
    { "values": { "ip": "10.128.0.49", "hostname": "worker-6" } }
  ]
}

Проекты

При использовании мультитенантности в кластерах DKP данный раздел позволяет работать с проектами, созданными в кластерах под управлением Deckhouse Commander. Подробнее о функциональности можно узнать в разделе Мультитенантность DKP.

По умолчанию раздел выключен. Чтобы включить, требуется настройка администратора: включение и выключение возможностей Deckhouse Commander.

Вся функциональность проектов в прикладных кластерах реализуется встроенной мультитенантностью DKP. Deckhouse Commander выступает управляющей надстройкой: он создаёт и обновляет в прикладных кластерах ресурсы Project, а агент применяет их в кластере.

В Deckhouse Commander различаются два типа проектов:

• Проекты типа commander — создаются и управляются из Deckhouse Commander. Только такие проекты можно редактировать и удалять через веб-интерфейс.
• Проекты типа deckhouse — это проекты DKP, созданные непосредственно в прикладном кластере и не находящиеся под управлением Deckhouse Commander. Подробнее см. Проекты типа deckhouse.

Список проектов

На странице «Проекты» отображаются все проекты рабочего пространства, доступные пользователю (см. Видимость раздела и проектов).

В списке доступны колонки:

• имя проекта — для успешно установленных проектов имя является ссылкой на веб-интерфейс проекта в прикладном кластере;
• статус — текущее состояние проекта (см. Статусы проекта);
• кластер — ссылка на страницу прикладного кластера. Ссылка активна только у пользователей с правом на просмотр раздела Кластеры; остальным отображается просто название кластера;
• описание.

Рядом с именем проекта могут отображаться служебные обозначения или иконки:

• флажок — проект типа deckhouse, контролируется Deckhouse;
• красная иконка — статус ошибки, при наведении показывается текст ошибки;
• серая информационная иконка — дополнительная информация о состоянии синхронизации с кластером.

Над списком доступны фильтры: поиск по имени, фильтр по кластеру, по типу проекта (commander / deckhouse) и по статусу. Кнопка «Сбросить» очищает все фильтры.

Для проектов типа commander в строке доступны действия:

• «Создать на основании» — открывает форму создания проекта с предзаполненными параметрами исходного проекта (удобно для выхода из коллизии имён);
• «Редактировать» — открывает форму редактирования параметров;
• «Удалить» — удаляет проект (подтверждение обязательно).

Набор доступных действий зависит от прав пользователя. Подробнее см. Права доступа в проектах.

Статусы проекта

В списке и на странице проекта отображается итоговый статус, объединяющий собственное состояние проекта и состояние прикладного кластера:

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

Создание проекта

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

1. На странице «Проекты» нажмите кнопку «Создать проект».

2. Выберите прикладной кластер. В списке доступны только кластера, готовые принимать проекты (в активной стадии). Проект создаётся только в одном кластере — связь один к одному.

3. Заполните параметры проекта:

   • Администраторы — пользователи и группы, получающие роль Admin в проекте. Выбираются из учётных записей, доступных в Deckhouse Commander (приходят из внешнего IdP через Dex); имя пользователя или группы можно также ввести вручную, если учётная запись в Commander ещё не появилась.
   • Ресурсные квоты — опциональное ограничение на запросы ресурсов проекта (resourceQuota.requests): CPU (число ядер или милликоры, например 1 или 500m), память (Mi, Gi, и т. п.) и хранилище (Mi, Gi, и т. п.). Если не задано ни одного значения, квота в кластере не создаётся. Если хотя бы одна квота задана, все контейнеры подов проекта обязаны явно указывать resources.requests для соответствующих ресурсов — поды без этих значений в проекте создаваться не будут.

4. Введите имя проекта. Имя должно соответствовать правилам именования namespace в Kubernetes (строчные латинские буквы, цифры и дефис). Зарезервированные системные имена (в частности, default и deckhouse) использовать нельзя. Уникальность имени проверяется в рамках выбранного кластера.

5. Нажмите кнопку «Создать».

После создания Commander помечает проект служебными лейблами и передаёт его агенту, который применяет Project в прикладном кластере. Лейбл agent.commander.deckhouse.io/prevent-tracking-adoption защищает одноимённый проект DKP, если такой уже существует в кластере, от автоматического перехвата под управление Commander.

Редактирование проекта

Чтобы изменить проект, нажмите иконку «Редактировать» в строке списка или откройте страницу проекта и перейдите на вкладку «Конфигурация».

В форме редактирования можно изменить:

• описание проекта;
• список администраторов;
• ресурсные квоты;
• имя проекта.

Смена шаблона проекта в текущем релизе не поддерживается и появится на следующих этапах развития функциональности.

Редактирование доступно только для проектов типа commander. Для проектов типа deckhouse форма редактирования не предоставляется: в будущих релизах появится возможность присоединить проект, созданный в DKP, к Deckhouse Commander и далее управлять им уже из Commander.

Просмотр проекта и веб-интерфейс

Клик по имени установленного (в статусе «Установлен») проекта в списке открывает веб-интерфейс проекта в прикладном кластере. Для проектов, ещё не применённых в кластере, имя отображается как текст.

На странице проекта доступны вкладки:

• Конфигурация — текущие параметры проекта (шаблон, администраторы, ресурсные квоты) и сообщения об ошибках применения, если они есть.
• Доступы — управление участниками проекта (см. Вкладка «Доступы»). Видна только администраторам проекта и администраторам системы. Назначать и снимать администраторов проекта может только администратор системы — через поле «Администраторы» на вкладке «Конфигурация».

Удаление проекта

Чтобы удалить проект, нажмите иконку «Удалить» в строке списка и подтвердите действие. Commander снимет с проекта служебные лейблы и запросит у агента удаление Project в прикладном кластере.

Удаление доступно только для проектов типа commander. Проекты типа deckhouse удаляются непосредственно в Deckhouse с помощью модуля multitenancy-manager.

Коллизии имён

Имя проекта должно быть уникальным в пределах прикладного кластера. Коллизия может возникнуть в двух ситуациях:

• при создании проекта в Commander уже существует проект (типа commander или deckhouse) с таким же именем в выбранном кластере — форма вернёт ошибку валидации, и сохранить проект не получится;
• проект с таким же именем появляется в прикладном кластере после создания проекта в Commander (например, создаётся напрямую в DKP) — агент не сможет применить проект, и в Commander проект перейдёт в статус Ошибка создания с описанием ошибки.

Чтобы выйти из коллизии имён:

1. Воспользуйтесь действием «Создать на основании» — откроется форма создания проекта с предзаполненными параметрами конфликтующего проекта; укажите новое имя и сохраните, а затем удалите исходный проект.
2. Либо удалите конфликтующий проект DKP непосредственно в прикладном кластере и дождитесь следующей синхронизации агента.

Лейбл agent.commander.deckhouse.io/prevent-tracking-adoption гарантирует, что агент не подхватит одноимённый проект DKP под управление Commander автоматически — коллизия явно диагностируется.

Видимость раздела и проектов

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

• в Deckhouse Commander включена функциональность проектов;
• пользователю назначена глобальная роль, дающая хотя бы verb get на ресурсе projects.

Состав проектов в списке определяется правами пользователя на ресурс projects:

• при правах только get (в том числе через роль autogenerated-projects-user) видны только проекты, в которых пользователь является участником; проекты типа deckhouse скрыты;
• при правах update и/или delete (в том числе *) видны все проекты рабочего пространства, включая проекты типа deckhouse.

Роль autogenerated-projects-user автоматически назначается всем участникам проектов, поэтому раздел «Проекты» появляется у пользователя сразу после добавления в любой проект рабочего пространства. Для создания, изменения и удаления проектов используется предустановленная роль projects-admin или собственная глобальная роль с нужным набором verbs. Подробнее о модели прав доступа см. в разделе Права доступа в проектах.

Роли в проекте

Каждому участнику проекта назначается одна из четырёх ролей. Роли кумулятивные: более высокая роль включает все права более низких и добавляет новые возможности. В прикладном кластере права применяет модуль multitenancy-manager через манифест AuthorizationRule.

Вкладка «Доступы»

Вкладка «Доступы» на странице проекта доступна:

• администратору системы с правами на projectrolebindings в этом проекте;
• администратору проекта — пользователю, назначенному в роль Admin текущего проекта.

Пользователям в ролях Editor, PrivilegedUser, User вкладка «Доступы» не видна.

На вкладке отображается таблица участников проекта с указанием роли. Строки с ролью Admin помечены значком замка и изменяются только через вкладку «Конфигурация» (поле «Администраторы») администратором системы.

Чтобы добавить участника, выполните следующие шаги:

1. Нажмите кнопку «Добавить участника».
2. Выберите роль: User, PrivilegedUser или Editor.
3. Выберите одного или нескольких пользователей либо групп.
4. Нажмите кнопку «Сохранить».

Пользователи и группы на вкладке «Доступы» выбираются из учётных записей, доступных в Deckhouse Commander (они приходят из внешнего IdP через Dex и в Commander не создаются).

Проекты типа deckhouse

Проекты типа deckhouse — это проекты DKP, созданные непосредственно в прикладном кластере и не находящиеся под управлением Deckhouse Commander. В списке проектов они помечены значком-флажком с подсказкой о том, что объект контролируется Deckhouse.

В веб-интерфейсе Deckhouse Commander для таких проектов не предусмотрены форма редактирования, удаление и вкладка «Доступы» — управление такими проектами выполняется непосредственно в Deckhouse с помощью модуля multitenancy-manager и манифеста AuthorizationRule (см. также Мультитенантность DKP).

API интеграции

API Deckhouse Commander предоставляет ограниченный набор действий:

1. Создание, изменение, удаление кластеров
2. Создание, изменение, удаление записей в каталогах
3. Чтение шаблонов
4. Чтение каталогов инвентаря
5. Создание, изменение, удаление проектов

Для доступа к API в Deckhouse Commander можно выпустить токен. Токен может иметь либо права на все возможные операции в API, либо только на чтение.

Детали реализации API описаны в разделе API интеграции

Параметры

Настройки кластера по умолчанию

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

Токены

Данный раздел предназначен для создания токенов доступа к API интеграции.

Аудит

Для всех сущностей Deckhouse Commander сохраняет историю изменений. Кластеры, шаблоны, записи, каталоги, токены доступа к API — для всех них записывается история действий и изменений, по которой можно проследить, кто, когда и какие действия совершал в Deckhouse Commander.

На данный момент эта функциональность касается лишь работы, связанной с API Deckhouse Commander. В будущем в Deckhouse Commander будет доступен аудит-лог из прикладных кластеров.