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

Адрес

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

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

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

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

Управление кластерами

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

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

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

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

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

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

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

Kubernetes

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

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

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

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

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

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

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

Параметры кластера

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

Kubernetes

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

Размещение

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

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

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

• VMware Cloud Director
• VMware vSphere
• OpenStack
• Yandex 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 и Deckhouse за исключением настроек встроенных модулей Deckhouse Kubernetes Platform. Deckhouse Commander будет синхронизировать эти ресурсы.

Первичные ресурсы

Произвольные манифесты ресурсов Kubernetes и Deckhouse за исключением настроек встроенных модулей Deckhouse Kubernetes Platform. Deckhouse Commander не будет синхронизировать эти ресурсы.

Стартовая конфигурация

Здесь указывается регистри и доступ к нему (см. InitConfiguration). Также в этой секции указывается настройки встроенных модулей Deckhouse Kubernetes Platform (DKP), например, шаблон домена для служебных веб-интерфейсов, настройки TLS-сертификата или канал обновлений инсталляции DKP.

Шаблоны

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

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

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

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

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

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

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

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

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

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

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

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

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" } }
  ]
}

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

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

API интеграции и токены

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

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

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

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

Аудит

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

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