Установка

Инсталлятор 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 необходимо выполнить подготовку YAML-файла конфигурации установки. Этот файл содержит основные параметры для настройки Deckhouse, включая информацию о кластерных компонентах, сетевых настройках и интеграциях, а также описание ресурсов для создания после установки (настройки узлов и Ingress-контроллера).

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

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

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.

6. IngressNginxController — развертывание Ingress-контроллера.

7. NodeGroup — создание дополнительных групп узлов.

8. InstanceClass — добавление конфигурационных ресурсов.

9. ClusterAuthorizationRule, User — настройка прав и пользователей.

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:
    earlyOomEnabled: false
---
apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: prometheus
spec:
  version: 2
  enabled: true
  # Укажите, в случае использование выделенных узлов для мониторинга. 
  # settings:
  #   nodeSelector:
  #     node.deckhouse.io/group: monitoring
---
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:
   • 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/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.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 \
    --preflight-skip-all-checks 

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

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