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

Адрес

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

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

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

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

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

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

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

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

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

Kubernetes

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

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

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

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

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

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

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

Создание

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

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

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

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

Обновление

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

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

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

Удаление

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

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

Второй способ удалить кластер — ручное удаление. Коммандер переместит кластер в архив, но не будет заниматься очисткой инфраструктуры. Этот способ может быть полезен, если Коммандер по каким-то причинам не может справиться с корректным удалением кластера первым способом. В этом случае кластер будет иметь статус «ошибка удаления». Пользователю предстоит вручную очистить ресурсы, которые занимал 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. Коммандер будет синхронизировать эти ресурсы.

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

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

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

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

Шаблоны

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

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

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

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

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

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

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

Ресурсы, каталоги ресурсов

Не путайте с Kubernetes-ресурсами

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

Для таких целей в Коммандере есть раздел «Ресурсы». Этот раздел состоит из каталогов ресурсов. Внутри каталогов содержатся ресурсы. Ресурсы представляют структуру данных, представимых в виде JSON-объекта. В каталоге при создании задаются имя каталога, схема ресурса и идентификатор каталога. Схема ресурса задается тем же синтаксисом и визуальным конструктором, что и входные параметры шаблона кластера. Пример схемы ресурса:

- 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 или через интерфейс загрузкой 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 Коммандера предоставляет ограниченный набор действий:

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

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

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

Аудит

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

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