Установка

Инсталлятор Deckhouse доступен в виде образа контейнера и основан на утилите dhctl, в задачи которой входят:

• Создание и настройка объектов в облачной инфраструктуре с помощью Terraform;
• Установка необходимых пакетов ОС на узлах (в том числе установка пакетов Kubernetes);
• Установка Deckhouse;
• Создание, настройка узлов кластера Kubernetes;
• Поддержание состояния кластера в соответствии с описанной конфигурацией.

Варианты установки Deckhouse:

• В поддерживаемом облаке. Утилита dhctl автоматически создает и настраивает все необходимые ресурсы, включая виртуальные машины, развертывает Kubernetes-кластер и устанавливает Deckhouse. Полный список поддерживаемых облачных провайдеров доступен в разделе Кластер Kubernetes.

• На серверах bare-metal или в неподдерживаемых облаках. В этом варианте dhctl выполняет настройку сервера или виртуальной машины, развертывает Kubernetes-кластер с одним master-узлом и устанавливает Deckhouse. Для добавления дополнительных узлов в кластер можно воспользоваться готовыми скриптами настройки.

• В существующем Kubernetes-кластере. Если Kubernetes-кластер уже развернут, dhctl устанавливает Deckhouse, интегрируя его с текущей инфраструктурой.

Подготовка инфраструктуры

Перед установкой убедитесь в следующем:

• Для кластеров на bare-metal и в неподдерживаемых облаках: сервер использует операционную систему из списка поддерживаемых ОС или совместимую с ним, а также доступен по SSH через ключ.

• Для поддерживаемых облаков: имеются необходимые квоты для создания ресурсов и подготовлены параметры доступа к облачной инфраструктуре (зависят от конкретного провайдера).

• Для всех вариантов установки: настроен доступ к container registry с образами Deckhouse (registry.deckhouse.io или registry.deckhouse.ru).

Подготовка конфигурации

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

1. YAML-файл конфигурации установки. Этот файл содержит основные параметры для настройки Deckhouse, включая информацию о кластерных компонентах, сетевых настройках и интеграциях.

2. YAML-файл дополнительных ресурсов. Используется для автоматического создания необходимых ресурсов после успешной установки Deckhouse, таких как пользовательские модули, настройки кластерных узлов или специфические политики.

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

Файл конфигурации установки

YAML-файл конфигурации установки содержит параметры нескольких ресурсов (манифесты):

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

   Основные настройки, задаваемые в этом ресурсе:

   • Параметры размещения компонентов;
   • Используемый StorageClass (параметры хранилища);
   • Параметры доступа к container registry;
   • Шаблон DNS-имен;
   • Другие важные параметры, без которых Deckhouse не сможет корректно функционировать.
2. ClusterConfiguration — общие параметры кластера, такие как версия control plane, сетевые настройки, параметры CRI и т. д.

   Этот ресурс требуется использовать только в случае, если Deckhouse устанавливается с предварительным развертыванием кластера Kubernetes. Если Deckhouse устанавливается в уже существующий кластер, этот ресурс не нужен.

3. StaticClusterConfiguration — параметры для кластеров Kubernetes, развертываемых на серверах bare-metal или виртуальных машинах в неподдерживаемых облаках.

   Этот ресурс требуется использовать только в случае, если Deckhouse устанавливается с предварительным развертыванием кластера Kubernetes. Если Deckhouse устанавливается в уже существующий кластер, этот ресурс не нужен.

4. <CLOUD_PROVIDER>ClusterConfiguration — набор ресурсов, содержащих параметры конфигурации поддерживаемых облачных провайдеров. Включает такие параметры, как:

   • Настройки доступа к облачной инфраструктуре (параметры аутентификации);
   • Тип и параметры схемы размещения ресурсов;
   • Сетевые параметры;
   • Настройки создаваемых групп узлов.

   Список ресурсов конфигурации поддерживаемых облачных провайдеров:

   • AWSClusterConfiguration — Amazon Web Services;
   • AzureClusterConfiguration — Microsoft Azure;
   • GCPClusterConfiguration — Google Cloud Platform;
   • OpenStackClusterConfiguration — OpenStack;
   • VsphereClusterConfiguration — VMware vSphere;
   • VCDClusterConfiguration — VMware Cloud Director;
   • YandexClusterConfiguration — Yandex Cloud;
   • ZvirtClusterConfiguration — zVirt.

5. ModuleConfig — набор ресурсов, содержащих параметры конфигурации встроенных модулей Deckhouse.

   Если кластер изначально создается с узлами, выделенными для определенных типов нагрузки (например, системные узлы или узлы для мониторинга), рекомендуется в конфигурации модулей, использующих тома постоянного хранилища явно задавать параметр nodeSelector.

   Например, для модуля prometheus настройка указывается в параметре nodeSelector.

apiVersion: deckhouse.io/v1
kind: ClusterConfiguration
clusterType: Cloud
cloud:
  provider: Azure
  prefix: cloud-demo
podSubnetCIDR: 10.111.0.0/16
serviceSubnetCIDR: 10.222.0.0/16
kubernetesVersion: "Automatic"
clusterDomain: cluster.local
---
apiVersion: deckhouse.io/v1
kind: AzureClusterConfiguration
layout: Standard
sshPublicKey: <SSH_PUBLIC_KEY>
vNetCIDR: 10.241.0.0/16
subnetCIDR: 10.241.0.0/24
masterNodeGroup:
  replicas: 3
  instanceClass:
    machineSize: Standard_D4ds_v4
    urn: Canonical:UbuntuServer:18.04-LTS:18.04.202010140
    enableExternalIP: true
provider:
  subscriptionId: <SUBSCRIPTION_ID>
  clientId: <CLIENT_ID>
  clientSecret: <CLIENT_SECRET>
  tenantId: <TENANT_ID>
  location: westeurope
---
apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: cni-flannel
spec:
  enabled: true
---
apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: deckhouse
spec:
  enabled: true
  settings:
    releaseChannel: Stable
    bundle: Default
    logLevel: Info
  version: 1
---
apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: global
spec:
  enabled: true
  settings:
    modules:
      publicDomainTemplate: "%s.k8s.example.com"
  version: 1
---
apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: node-manager
spec:
  version: 1
  enabled: true
  settings:
    allowedBundles: ["ubuntu-lts"]
---
apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: prometheus
spec:
  version: 2
  enabled: true
  # Укажите, в случае использование выделенных узлов для мониторинга. 
  # settings:
  #   nodeSelector:
  #     node.deckhouse.io/group: monitoring

Файл ресурсов установки

Необязательный YAML-файл ресурсов установки включает манифесты Kubernetes-ресурсов, которые инсталлятор применяет сразу после успешной установки Deckhouse.

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

• Развертывание Ingress-контроллера;
• Создание дополнительных групп узлов;
• Добавление конфигурационных ресурсов;
• Настройка прав и пользователей.

apiVersion: deckhouse.io/v1
kind: IngressNginxController
metadata:
  name: main
spec:
  ingressClass: "nginx"
  controllerVersion: "1.1"
  inlet: "LoadBalancer"
  nodeSelector:
    node.deckhouse.io/group: worker
---
apiVersion: deckhouse.io/v1
kind: AzureInstanceClass
metadata:
  name: worker
spec:
  machineSize: Standard_F4
---
apiVersion: deckhouse.io/v1
kind: NodeGroup
metadata:
  name: worker
spec:
  cloudInstances:
    classReference:
      kind: AzureInstanceClass
      name: worker
    maxPerZone: 3
    minPerZone: 1
    zones: ["1"]
  nodeType: CloudEphemeral
---
apiVersion: deckhouse.io/v1
kind: ClusterAuthorizationRule
metadata:
  name: admin
spec:
  subjects:
  - kind: User
    name: admin@deckhouse.io
  accessLevel: SuperAdmin
  portForwarding: true
---
apiVersion: deckhouse.io/v1
kind: User
metadata:
  name: admin
spec:
  email: admin@deckhouse.io
  password: '$2a$10$isZrV6uzS6F7eGfaNB1EteLTWky7qxJZfbogRs1egWEPuT1XaOGg2'
---
apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: deckhouse-admin
spec:
  enabled: true

Post-bootstrap-скрипт

После завершения установки Deckhouse инсталлятор предоставляет возможность выполнить пользовательский скрипт на одном из master-узлов. Такой скрипт может использоваться для:

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

Указать путь к post-bootstrap-скрипту можно с помощью параметра --post-bootstrap-script-path при запуске процесса инсталляции.

#!/usr/bin/env bash

set -e
set -o pipefail


INGRESS_NAME="nginx"


echo_err() { echo "$@" 1>&2; }

# declare the variable
lb_ip=""

# get the load balancer IP
for i in {0..100}
do
  if lb_ip="$(kubectl -n d8-ingress-nginx get svc "${INGRESS_NAME}-load-balancer" -o jsonpath='{.status.loadBalancer.ingress[0].ip}')"; then
    if [ -n "$lb_ip" ]; then
      break
    fi
  fi

  lb_ip=""

  sleep 5
done

if [ -n "$lb_ip" ]; then
  echo_err "The load balancer external IP: $lb_ip"
else
  echo_err "Could not get the external IP of the load balancer"
  exit 1
fi

outContent="{\"frontend_ips\":[\"$lb_ip\"]}"

if [ -z "$OUTPUT" ]; then
  echo_err "The OUTPUT env is empty. The result was not saved to the output file."
else
  echo "$outContent" > "$OUTPUT"
fi

Установка Deckhouse

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

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

docker run --pull=always -it [<MOUNT_OPTIONS>] registry.deckhouse.ru/deckhouse/<DECKHOUSE_REVISION>/install:<RELEASE_CHANNEL> bash

Где:

1. <DECKHOUSE_REVISION> — редакция Deckhouse, например ee — для Enterprise Edition, ce — для Community Edition и т. д.
2. <MOUNT_OPTIONS> — параметры монтирования файлов в контейнер инсталлятора, такие как:
   • SSH-ключи доступа;
   • Файл конфигурации;
   • Файл ресурсов и т. д.
3. <RELEASE_CHANNEL> — канал обновлений в формате kebab-case, который должен совпадать с указанным в config.yml:
   • alpha — для канала обновлений Alpha;
   • beta — для канала обновлений Beta;
   • early-access — для канала обновлений Early Access;
   • stable — для канала обновлений Stable;
   • rock-solid — для канала обновлений Rock Solid.

Пример команды для запуска инсталлятора Deckhouse в редакции CE:

docker run -it --pull=always \
  -v "$PWD/config.yaml:/config.yaml" \
  -v "$PWD/resources.yml:/resources.yml" \
  -v "$PWD/dhctl-tmp:/tmp/dhctl" \
  -v "$HOME/.ssh/:/tmp/.ssh/" registry.deckhouse.ru/deckhouse/ce/install:stable bash

Установка Deckhouse осуществляется в контейнере инсталлятора с помощью утилиты dhctl:

• Для запуска установки Deckhouse с развертыванием нового кластера (все случаи, кроме установки в существующий кластер) используйте команду dhctl bootstrap.
• Для установки Deckhouse в уже существующий кластер используйте команду dhctl bootstrap-phase install-deckhouse.

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

dhctl bootstrap \
  --ssh-user=<SSH_USER> --ssh-agent-private-keys=/tmp/.ssh/id_rsa \
  --config=/config.yml --config=/resources.yml

Где:

• /config.yml — файл конфигурации установки;
• /resources.yml — файл манифестов ресурсов;
• <SSH_USER> — имя пользователя для подключения по SSH к серверу;
• --ssh-agent-private-keys — файл приватного SSH-ключа для подключения по SSH.

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

Список проверок, выполняемых инсталлятором перед началом установки Deckhouse:

1. Общие проверки:
   • Значения параметров PublicDomainTemplate clusterDomain не совпадают.
   • Данные аутентификации для хранилища образов контейнеров, указанные в конфигурации установки, корректны.
   • Имя хоста соответствует следующим требованиям:
     • Длина не более 63 символов;
     • Состоит только из строчных букв;
     • Не содержит спецсимволов (допускаются символы - и ., при этом они не могут быть в начале или в конце имени).
   • На сервере (ВМ) отсутствует установленный CRI (containerd).
   • Имя хоста должно быть уникальным в пределах кластера.
2. Проверки для установки статического и гибридного кластера:
   • Указан только один параметр --ssh-host. Для статической конфигурации кластера можно задать только один IP-адрес для настройки первого master-узла.
   • Должна быть возможность подключения по SSH с использованием указанных данных аутентификации.
   • Должна быть возможность установки SSH-туннеля до сервера (или виртуальной машины) master-узла.
   • Сервер (ВМ) удовлетворяет минимальным требованиям для настройки master-узла.
   • На сервере (ВМ) для master-узла установлен Python и необходимые библиотеки.
   • Хранилище образов контейнеров доступно через прокси (если настройки прокси указаны в конфигурации установки).
   • На сервере (ВМ) для master-узла и хосте инсталлятора свободны порты, необходимые для процесса установки.
   • DNS должен разрешать localhost в IP-адрес 127.0.0.1.
   • На сервере (ВМ) пользователю доступна команда sudo.
3. Проверки для установки облачного кластера:
   • Конфигурация виртуальной машины master-узла удовлетворяет минимальным требованиям.

    dhctl bootstrap \
    --ssh-user=<SSH_USER> --ssh-agent-private-keys=/tmp/.ssh/id_rsa \
    --config=/config.yml --config=/resources.yml \
    --preflight-skip-all-checks 

Откат установки

Если установка была прервана или возникли проблемы во время установки в поддерживаемом облаке, то могут остаться ресурсы, созданные в процессе установки. Для их удаления используйте команду dhctl bootstrap-phase abort, выполнив ее в контейнере инсталлятора.