Модуль deckhouse-commander

Deckhouse Commander — это веб-приложение, в котором создают однотипные кластеры на базе Deckhouse Kubernetes Platform, управляют их конфигурацией и жизненным циклом.

Основные возможности

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

Скоро появятся:

• API для внешней интеграции
• Управление доступом: пользователями и ролями
• Управление проектами
• Обзор облачных ресурсов, созданных с кластером

Как включить

У модуля deckhouse-commander есть внешняя зависимость — база данных Postgres. Если используете свою базу, то задайте параметры базы в ModuleConfig/deckhouse-commander. Есть возможность использовать модуль operator-postgres, в этом случае нужно включить вначале его, а затем — сам Commander. Ниже эти варианты описаны подробнее.

Если используете свою базу

Чтобы включить модуль, создайте ModuleConfig:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: deckhouse-commander
spec:
  enabled: true
  version: 1
  settings:
    postgres:
      mode: External
      external:
        host: "..."      #
        port: "..."      #
        user: "..."      # Обязательные поля
        password: "..."  #
        db: "..."        #

Если используете модуль operator-postgres

Шаг 1: включения operator-postgres

Сначала нужно включить модуль с оператором postgres и дождаться его включения

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: operator-postgres
spec:
  enabled: true

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

kubectl -n d8-system exec -t deploy/deckhouse -c deckhouse -- deckhouse-controller queue main

Шаг 2: включить deckhouse-commander

Затем нужно включить модуль deckhouse-commander

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: deckhouse-commander
spec:
  enabled: true

Примечание к Декхаусу v1.56

Если вы только что установили Декхаус версии 1.56, то можете столкнуться с ошибкой

Warning: module name 'deckhouse-commander' is unknown for deckhouse
moduleconfig.deckhouse.io/deckhouse-commander created

В статусе модуля будет сообщение о том, что имя модуля Декхаусу неизвестно.

$ kubectl get moduleconfigs.deckhouse.io deckhouse-commander
NAME              STATE   VERSION   AGE   TYPE   STATUS
deckhouse-commander   N/A               14s   N/A    Ignored: unknown module name

Чтобы исправить ее, нужно вручную создать ресурс ModuleUpdatePolicy, который исправит проблему для всех модулей в ModuleSource/deckhouse:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleUpdatePolicy
metadata:
  name: deckhouse
spec:
  moduleReleaseSelector:
    labelSelector:
      matchLabels:
        source: deckhouse
  releaseChannel: Alpha  # замените на предпочтительный канал обновлений
  update:
    mode: Auto

Концепции

dhctl

Чтобы установить Deckhouse Kubernetes Platform вручную, используют утилиту dhctl. На вход она принимает три набора данных:

1. Конфигурацию кластера и установки кластера в виде файла, будем далее ссылаться на него под именем config.yaml.
2. Конфигурацию SSH-подключения к машине, которая станет первым мастеру-узлом. Конфигурация используется в виде ключей командной строки dhctl (есть возможность задать в виде YAML). Будем далее ссылаться на него под именем SSHConfig.
3. Необязательный набор ресурсов который нужно создать на последнем шаге установки, будем далее ссылаться на него под именем resources.yaml.

Какие логические части содержатся в этих данных?

1. config.yaml
   1. InitConfiguration — конфигурация установки кластера
   2. Ресурсы ModuleConfig — конфигурация встроенных модулей: явное включение или выключение, а так же переопределение настроек по умолчанию
   3. ClusterConfiguration — конфигурация Kubernetes: версия, подсетей подов, сервисов и т.п.
   4. Параметры размещения
      1. <Provider>ClusterConfiguration — параметры размещения кластера в облаке или API виртуализации, если Deckhouse Kubernetes Platform устанавливается не на статические ресурсы;
      2. или StaticClusterConfiguration для статического кластера
2. resources.yaml
   1. Произвольные ресурсы Kubernetes в том числе ModuleConfig для не встроенных модулей в Deckhouse Kubernetes Platform
3. SSHConfig
   1. Имя пользователя, пароль и ключ для подключения к существующей машине или той, которая будет создана в процессе создания кластера
   2. IP-адрес машины, если кластер разворачивается на статических ресурсах и адрес будущего мастер-узла известен заранее
   3. Остальные параметры можно посмотреть в справке команды dhctl, в данной документации дополнительные детали несущественны

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

Как видно, вся предоставленная конфигурация используется для того, чтобы создать кластер. Для этого используется dhctl bootstrap со вмей предоставленной конфигурацией.

Изменения, которые можно внести в кластер тем же инструментом, касаются либо параметров размещения (например, ресурсы перманентных узлов, созданных Terraform) либо параметров Kubernetes. Только настройки подключения и общие параметры кластера доступны для изменения с dhctl converge. Но изменение конфигурации платформы или дополнительные ресурсы кластера таким образом не применить.

Наконец, чтобы удалить кластер, достаточно иметь к нему подключение: операция dhctl destroy использует только SSHConfig.

Commander

Commander использует тот же набор данных для конфигурации кластеров, что и dhctl. Однако Commander добавляет возможность синхронизировать полную желаемую конфигурацию с кластером. Если представить Commander как dhctl с дополительными возможностями конфигурации, то таблица выглядела бы так:

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

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

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

Commander делит конфиграцию Deckhouse Kubernetes Platform по принципу отслеживаемости. Причемп ользователь решает какую часть конфигурации синхронизировать, а какую задать один раз при создании кластера. Как эта конфигурация выглядит с точки зрения Commander:

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

Шаблоны

Идея

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

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

Версии шаблона

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

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

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

Сложность шаблона

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

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

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

Создание шаблона

Добавить шаблон в Commander можно двумя способами: импортировать существующий (например, созданный ранее в другой инсталляции Commander) или создать с нуля. В конечном счете шаблонизированная конфигурация должна будет удовлетворять особенностями dhctl и Deckhouse Kubernetes Platform той версии, которая будет устанавливаться с помощью шаблона.

Где почерпнуть документацию для видов конфигурации

• Входные параметры
• Kubernetes
  • ClusterConfiguration
• Размещение
  • Статические ресурсы
  • Yandex Cloud
  • VMware vSphere
  • OpenStack
  • Amazon Web Services
  • Google Cloud Platform
  • Microsoft Azure
• Параметры SSH
  • См. примеры ниже
• Ресурсы
  • Произвольные манифесты ресурсов Kubernetes и Deckhouse. Commander будет синхронизировать эти ресурсы.
• Первичные ресурсы
  • Произвольные манифесты ресурсов Kubernetes и Deckhouse. Commander не будет синхронизировать эти ресурсы.
• Установка
  • InitConfiguration

Специальные переменные

В шаблонах кластеров есть несколько специальных переменных.

Необходимые манифесты

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

Параметры SSH для облачного кластера

Для облачного кластера можно использовать приватный ключ, созданный Commander, если вы не предоставляете заранее определенный ключ в образе ОС. Также в образах виртуальных машин будет создан пользователь, под которым Commander подключится к созданной машине, чтобы завести ее как master-узел.

apiVersion: dhctl.deckhouse.io/v1
kind: SSHConfig
# имя пользователя для SSH, опредеяется образом ОС в разделе «Размещение»
sshUser: ubuntu
sshPort: 22
# приватный ключ, который будет использовать для подключения к ВМ по SSH
sshAgentPrivateKeys:
- key: |
    {{ .dc_sshPrivateKey | nindent 4 }}    

Параметры SSH и ресурсы для статического кластера

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

Обратите внимание на манифесты SSHHost. Они объявляют IP-адреса, к котором у Commander есть доступ. В данном примере предполагается, что входной параметр .masterHosts — это список IP-адресов, на основании которых в конфигурации будет набор SSH-хостов. Так как это мастеры, их следует указывать в количестве 1 или 3.

apiVersion: dhctl.deckhouse.io/v1
kind: SSHConfig
# имя пользователя и порт для SSH, сконфигурированные на машинах
sshUser: {{ .sshUser }}
sshPort: {{ .sshPort }}
# приватный ключ, используемый на машинах, передается как входной параметр в кластер
sshAgentPrivateKeys:
- key: |
    {{ .sshPrivateKey | nindent 4 }}    

{{- range $masterHost := .masterHosts }}
---
apiVersion: dhctl.deckhouse.io/v1
kind: SSHHost
host: {{ $masterHost.ext_ip }}
{{- end }}

Commander подключится только с первому SSH-хосту в переданно списке. Этот хост станет мастер-узлом кластера. Когда Deckhouse установится на первом мастер-узле, он сможет сам добавить два оставшихся мастер-узла в кластер, если они заявлены в шаблоне. Для этого нужно сообщить Deckhouse, что машины существуют, как на них попасть, и что их нужно добавить в кластер. Для этого необходимо для двух мастеров создать StaticInstance, определить для них SSHCredentials, а также явно прописать группу узлов master с параметром spec.staticInstances.count=2, чтобы два статических мастер-узла не только были известны Deckhouse, но и были востребованы как master-узлы. Эту часть шаблона целесообразно определить в «Ресурсах». Ниже представлен код шаблона для этой задачи:

---
apiVersion: deckhouse.io/v1alpha1
kind: SSHCredentials
metadata:
  name: commander-ssh-credentials
  labels:
    heritage: deckhouse-commander
spec:
  sshPort: {{ .sshPort }}
  user: {{ .sshUser }}
  privateSSHKey: {{ .sshPrivateKey | b64enc }}

{{- if gt (len .masterHosts) 1 }}
{{-   range $masterInstance := slice .masterHosts 1 }}
---
apiVersion: deckhouse.io/v1alpha1
kind: StaticInstance
metadata:
  labels:
    type: master
    heritage: deckhouse-commander
  name: {{ $masterInstance.hostname | quote }}
spec:
  address: {{ $masterInstance.ip | quote }}
  credentialsRef:
    apiVersion: deckhouse.io/v1alpha1
    kind: SSHCredentials
    name: commander-ssh-credentials
{{-   end }}
{{- end }}

{{- if gt (len .masterHosts) 1 }}
---
apiVersion: deckhouse.io/v1
kind: NodeGroup
metadata:
  name: master
  labels:
    heritage: deckhouse-commander
spec:
  disruptions:
    approvalMode: Manual
  nodeTemplate:
    labels:
      node-role.kubernetes.io/control-plane: ""
      node-role.kubernetes.io/master: ""
    taints:
    - effect: NoSchedule
      key: node-role.kubernetes.io/master
    - effect: NoSchedule
      key: node-role.kubernetes.io/control-plane
  nodeType: Static
  staticInstances:
    count: 2
    labelSelector:
      matchLabels:
        type: master
{{- end }}

Ресурсы: модуль Commander-агента

Commander синхронизирует ресурсы с помощью модуля deckhouse-commander-agent. Этот модуль устанавливается в целевом кластере. Приложение commander-agent запрашивает актуальный список ресурсов для кластера и актуализирует их в кластере, в котором работает. Чтобы агент был корректно настроен, в ресурсах необходимо создать манифест, включающий модуль.

Обратите внимание на commanderUrl. Вам предстоит уточнить схему этого адреса: HTTP или HTTPS.

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: deckhouse-commander-agent
  labels:
    heritage: deckhouse-commander
spec:
  enabled: true
  version: 1
  settings:
    commanderUrl: 'https://{{ .dc_domain }}/agent_api/{{ .dc_clusterUUID }}'