Deckhouse Platform в существующем кластере

Выберите редакцию Deckhouse Platform

Ниже сгенерированы рекомендованные настройки для установки Deckhouse Platform Community Edition:

  • config.yml — файл первичной конфигурации кластера. Содержит параметры инсталлятора и начальные параметры кластера.

Обратите внимание:

  • обязательные для самостоятельного заполнения параметры.
  • опциональные параметры.
  • Если вы запускаете инсталлятор под Windows, то убедитесь, что кодировка создаваемых YAML-файлов конфигурации UTF-8 (либо удалите примечания на русском языке).

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

Deckhouse Platform использует каналы обновлений (release channels), о чём вы можете подробнее узнать в документации.

# секция первичной инициализации кластера Deckhouse (InitConfiguration)
# используемая версия API Deckhouse
apiVersion: deckhouse.io/v1
# тип секции конфигурации
kind: InitConfiguration
# секция с параметрами Deckhouse
deckhouse:
  # используемый канал обновлений
  releaseChannel: Stable
  # при установке Deckhouse в существующий кластер используется вариант поставки — Minimal
  bundle: Minimal
  configOverrides:
    global:
      modules:
        # шаблон, который будет использоваться для составления адресов системных приложений в кластере
        # например, Grafana для %s.example.com будет доступна на домене grafana.example.com
        publicDomainTemplate: "%s.example.com"
        # при необходимости, укажите в массиве customTolerationKeys все taint'ы
        # к которым Deckhouse должен иметь toleration
        # далее приведен пример для случая, если нужно чтобы Deckhouse и его компоненты смогли запускаться
        # на узлах, имеющих taint SystemLoad
        # возможно, захотите изменить
        placement:
          customTolerationKeys:
          - SystemLoad
    certManagerEnabled: true
    deckhouseWebEnabled: true
# секция первичной инициализации кластера Deckhouse (InitConfiguration) # используемая версия API Deckhouse apiVersion: deckhouse.io/v1 # тип секции конфигурации kind: InitConfiguration # секция с параметрами Deckhouse deckhouse: # используемый канал обновлений releaseChannel: Stable # при установке Deckhouse в существующий кластер используется вариант поставки — Minimal bundle: Minimal configOverrides: global: modules: # шаблон, который будет использоваться для составления адресов системных приложений в кластере # например, Grafana для %s.example.com будет доступна на домене grafana.example.com publicDomainTemplate: "%s.example.com" # при необходимости, укажите в массиве customTolerationKeys все taint'ы # к которым Deckhouse должен иметь toleration # далее приведен пример для случая, если нужно чтобы Deckhouse и его компоненты смогли запускаться # на узлах, имеющих taint SystemLoad # возможно, захотите изменить placement: customTolerationKeys: - SystemLoad certManagerEnabled: true deckhouseWebEnabled: true

Про nodeSelector, taints и tolerations...

Управлять тем, на каких узлах будет запускаться ядро Deckhouse, можно с помощью указания nodeSelector/tolerations в параметре configOverrides.deckhouse конфигурации установки. Также, вы можете перечислить необходимые taint’ы узлов кластера в массиве configOverrides.global.modules.placement.customTolerationKeys, чтобы Deckhouse автоматически указывал соответствующие toleration своим компонентам.

Пример указания nodeSelector/tolerations для модуля deckhouse и списка tolerations в массиве customTolerationKeys для работы остальных компонентов Deckhouse (не копируйте этот пример без изменения в вашу конфигурацию, т.к. у вас будут другие значения):

deckhouse:
  configOverrides:
    # ...
    deckhouse:
      tolerations:
        - key: dedicated.deckhouse.io
          operator: Exists
    # ...
    global:
      modules:
        # ...
        placement:
          customTolerationKeys:
          - SystemLoad
          - app.kubernetes.io/instance

Введите лицензионный ключ

Ввести

Ниже сгенерированы рекомендованные настройки для установки Deckhouse Platform Enterprise Edition:

  • config.yml — файл первичной конфигурации кластера. Содержит параметры инсталлятора и начальные параметры кластера.

Обратите внимание:

  • обязательные для самостоятельного заполнения параметры.
  • опциональные параметры.
  • Если вы запускаете инсталлятор под Windows, то убедитесь, что кодировка создаваемых YAML-файлов конфигурации UTF-8 (либо удалите примечания на русском языке).

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

Deckhouse Platform использует каналы обновлений (release channels), о чём вы можете подробнее узнать в документации.

# секция первичной инициализации кластера Deckhouse (InitConfiguration)
# используемая версия API Deckhouse
apiVersion: deckhouse.io/v1
# тип секции конфигурации
kind: InitConfiguration
# секция с параметрами Deckhouse
deckhouse:
  # адрес Docker registry с образами Deckhouse
  imagesRepo: registry.deckhouse.io/deckhouse/ee
  # строка с ключом для доступа к Docker registry (сгенерировано автоматически для вашего токена доступа)
  registryDockerCfg: <YOUR_ACCESS_STRING_IS_HERE>
  # используемый канал обновлений
  releaseChannel: Stable
  # при установке Deckhouse в существующий кластер используется вариант поставки — Minimal
  bundle: Minimal
  configOverrides:
    global:
      modules:
        # шаблон, который будет использоваться для составления адресов системных приложений в кластере
        # например, Grafana для %s.example.com будет доступна на домене grafana.example.com
        publicDomainTemplate: "%s.example.com"
        # при необходимости, укажите в массиве customTolerationKeys все taint'ы
        # к которым Deckhouse должен иметь toleration
        # далее приведен пример для случая, если нужно чтобы Deckhouse и его компоненты смогли запускаться
        # на узлах, имеющих taint SystemLoad
        # возможно, захотите изменить
        placement:
          customTolerationKeys:
          - SystemLoad
    certManagerEnabled: true
    deckhouseWebEnabled: true
# секция первичной инициализации кластера Deckhouse (InitConfiguration) # используемая версия API Deckhouse apiVersion: deckhouse.io/v1 # тип секции конфигурации kind: InitConfiguration # секция с параметрами Deckhouse deckhouse: # адрес Docker registry с образами Deckhouse imagesRepo: registry.deckhouse.io/deckhouse/ee # строка с ключом для доступа к Docker registry (сгенерировано автоматически для вашего токена доступа) registryDockerCfg: <YOUR_ACCESS_STRING_IS_HERE> # используемый канал обновлений releaseChannel: Stable # при установке Deckhouse в существующий кластер используется вариант поставки — Minimal bundle: Minimal configOverrides: global: modules: # шаблон, который будет использоваться для составления адресов системных приложений в кластере # например, Grafana для %s.example.com будет доступна на домене grafana.example.com publicDomainTemplate: "%s.example.com" # при необходимости, укажите в массиве customTolerationKeys все taint'ы # к которым Deckhouse должен иметь toleration # далее приведен пример для случая, если нужно чтобы Deckhouse и его компоненты смогли запускаться # на узлах, имеющих taint SystemLoad # возможно, захотите изменить placement: customTolerationKeys: - SystemLoad certManagerEnabled: true deckhouseWebEnabled: true

Про nodeSelector, taints и tolerations...

Управлять тем, на каких узлах будет запускаться ядро Deckhouse, можно с помощью указания nodeSelector/tolerations в параметре configOverrides.deckhouse конфигурации установки. Также, вы можете перечислить необходимые taint’ы узлов кластера в массиве configOverrides.global.modules.placement.customTolerationKeys, чтобы Deckhouse автоматически указывал соответствующие toleration своим компонентам.

Пример указания nodeSelector/tolerations для модуля deckhouse и списка tolerations в массиве customTolerationKeys для работы остальных компонентов Deckhouse (не копируйте этот пример без изменения в вашу конфигурацию, т.к. у вас будут другие значения):

deckhouse:
  configOverrides:
    # ...
    deckhouse:
      tolerations:
        - key: dedicated.deckhouse.io
          operator: Exists
    # ...
    global:
      modules:
        # ...
        placement:
          customTolerationKeys:
          - SystemLoad
          - app.kubernetes.io/instance

Для установки Deckhouse Platform используется Docker-образ, в который необходимо передать конфигурационные файлы.

Запустите установщик на персональном компьютере.

Linux / macOS Windows

docker run --pull=always -it -v "$PWD/config.yml:/config.yml" \
  -v "$HOME/.kube/config:/kubeconfig" registry.deckhouse.io/deckhouse/ce/install:stable bash
docker run --pull=always -it -v "$PWD/config.yml:/config.yml" \ -v "$HOME/.kube/config:/kubeconfig" registry.deckhouse.io/deckhouse/ce/install:stable bash
docker run --pull=always -it -v "%cd%\config.yml:/config.yml" -v "%userprofile%\.kube\config:/kubeconfig"  registry.deckhouse.io/deckhouse/ce/install:stable bash -c "chmod 400 /tmp/.ssh/id_rsa; bash"
docker run --pull=always -it -v "%cd%\config.yml:/config.yml" -v "%userprofile%\.kube\config:/kubeconfig" registry.deckhouse.io/deckhouse/ce/install:stable bash -c "chmod 400 /tmp/.ssh/id_rsa; bash"

Примечание:

  • В файл /kubeconfig контейнера необходимо смонтировать файл конфигурации kubectl с доступом к Kubernetes API. В руководстве предполагается, что он находится в файле .kube/config домашнего каталога пользователя.

Внутри контейнера выполните команду:

dhctl bootstrap-phase install-deckhouse --kubeconfig=/kubeconfig --config=/config.yml
dhctl bootstrap-phase install-deckhouse --kubeconfig=/kubeconfig --config=/config.yml

По окончании установки произойдёт возврат к командной строке.

Почти все готово для полноценной работы Deckhouse Platform!

Если что-то пошло не так

Кластеры некоторых провайдеров могут требовать дополнительных действий до или после установки Deckhouse.

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

Ошибки установки на этапе 'Waiting for Deckhouse to become Ready'

  • Ошибка вида:
    │ │ ┌ Waiting for Deckhouse to become Ready
    │ │ │ Deckhouse pod found: deckhouse-64649df6f9-mf6dt (Pending)
    │ │ │ Deckhouse pod found: deckhouse-64649df6f9-mf6dt (Pending)
    

    Возможная причина — в кластере нет узла с label node-role.kubernetes.io/control-plane: "", который первоначально используется в nodeSelector манифеста deployment deckhouse.

    Варианты решения:

    • Отредактировать deployment deckhouse и указать нужный nodeSelector:
      kubectl -n d8-system edit deployment/deckhouse
      
    • Удалить nodeSelector у deployment deckhouse:
      kubectl patch -n d8-system deployment deckhouse --type json -p '[{"op": "remove", "path": "/spec/template/spec/nodeSelector"}]'
      

В кластере нет Ingress-контроллера...

Для работы модуля deckhouse-web, предоставляющего WEB-интерфейс к документации кластера, необходимо наличие в кластере Ingress-контроллера. Если в вашем кластере нет Ingress-контролллера, вы можете использовать модуль ingress-nginx следующим способом:

  • Включите модуль одним из следующих способов:
    • На этапе установки Deckhouse добавьте в файл config.yml в секцию deckhouse.configOverrides:
      ingressNginxEnabled: true
      
      ingressNginxEnabled: true

      Пример:

      deckhouse:
        configOverrides:
          ingressNginxEnabled: true
      
    • После установки Deckhouse, отредактируйте ConfigMap deckhouse:

      kubectl -n d8-system edit cm deckhouse
      
      kubectl -n d8-system edit cm deckhouse

      ... и добавьте:

      ingressNginxEnabled: "true"
      
      ingressNginxEnabled: "true"

      Пример:

      deckhouse:
        ingressNginxEnabled: "true"
      
  • Создайте файл ingress-nginx-controller.yml следующего содержания:

    # секция, описывающая параметры nginx ingress controller
    # используемая версия API Deckhouse
    apiVersion: deckhouse.io/v1
    kind: IngressNginxController
    metadata:
      name: nginx
    spec:
      # имя Ingress-класса для обслуживания Ingress NGINX controller
      ingressClass: nginx
      # версия Ingress-контроллера (используйте версию 1.1 с Kubernetes 1.23+)
      controllerVersion: "1.1"
      # способ поступления трафика из внешнего мира
      inlet: HostPort
      hostPort:
        httpPort: 80
        httpsPort: 443
      # описывает, на каких узлах будет находиться компонент
      # возможно, захотите изменить
      nodeSelector:
        node-role.kubernetes.io/control-plane: ""
      tolerations:
      - operator: Exists
    
    # секция, описывающая параметры nginx ingress controller # используемая версия API Deckhouse apiVersion: deckhouse.io/v1 kind: IngressNginxController metadata: name: nginx spec: # имя Ingress-класса для обслуживания Ingress NGINX controller ingressClass: nginx # версия Ingress-контроллера (используйте версию 1.1 с Kubernetes 1.23+) controllerVersion: "1.1" # способ поступления трафика из внешнего мира inlet: HostPort hostPort: httpPort: 80 httpsPort: 443 # описывает, на каких узлах будет находиться компонент # возможно, захотите изменить nodeSelector: node-role.kubernetes.io/control-plane: "" tolerations: - operator: Exists
  • Примените его, после установки Deckhouse, выполнив следующую команду:

    kubectl create -f ingress-nginx-controller.yml
    
    kubectl create -f ingress-nginx-controller.yml

Кластер в EKS AWS (Amazon Elastic Kubernetes Service)

Если вы устанавливаете Deckhouse в кластер EKS AWS (Amazon Elastic Kubernetes Service), то в запущенном контейнере инсталлятора установите aws-cli, выполнив:

apk add python3 py3-pip && pip3 install --upgrade pip && pip3 install awscli
apk add python3 py3-pip && pip3 install --upgrade pip && pip3 install awscli

Кластер в VK Cloud Solutions (MailRu Cloud Solutions)

  • В конфигурации инсталляции Deckhouse в массиве customTolerationKeys укажите taint CriticalAddonsOnly.

    Пример:

    deckhouse:
      releaseChannel: Stable
      bundle: Minimal
      configOverrides:
        global:
          modules:
            placement:
              customTolerationKeys:
              - CriticalAddonsOnly
            publicDomainTemplate: "%s.example.com"
    
  • В кластерах версии 1.21+ VK Cloud Solutions установлен Gatekeeper (OPA), который требует выставления requests и limits Pod'ам. Pod deckhouse не имеет requests/limits, остальные компоненты и модули Deckhouse получают вычисляемые параметры requests/limits в процессе работы Deckhouse.

    При просмотре событий Deployment deckhouse вы можете увидеть следующую ошибку:

    admission webhook "validation.gatekeeper.sh" denied the request: [container-must-have-limits] container <...> has no resource limits...

    Чтобы Deckhouse смог запуститься, необходимо перед установкой Deckhouse в таких кластерах добавить исключение GateKeeper (OPA) для namespace'ов компонентов Deckhouse (d8*-).

    Выполните в кластере:

    kubectl patch constraints container-must-have-limits --type json -p '[{"op": "replace", "path": "/spec/match/excludedNamespaces", "value": ["d8-*"]}]'
    
    kubectl patch constraints container-must-have-limits --type json -p '[{"op": "replace", "path": "/spec/match/excludedNamespaces", "value": ["d8-*"]}]'

Для установки Deckhouse Platform используется Docker-образ, в который необходимо передать конфигурационные файлы.

Запустите установщик на персональном компьютере.

Linux / macOS Windows

 echo <LICENSE_TOKEN> | docker login -u license-token --password-stdin registry.deckhouse.io
docker run --pull=always -it -v "$PWD/config.yml:/config.yml" \
  -v "$HOME/.kube/config:/kubeconfig" registry.deckhouse.io/deckhouse/ee/install:stable bash
echo <LICENSE_TOKEN> | docker login -u license-token --password-stdin registry.deckhouse.io docker run --pull=always -it -v "$PWD/config.yml:/config.yml" \ -v "$HOME/.kube/config:/kubeconfig" registry.deckhouse.io/deckhouse/ee/install:stable bash

Авторизуйтесь на персональном компьютере в container image registry, введя лицензионный ключ на запрос пароля:

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

Запустите контейнер с установщиком:

docker run --pull=always -it -v "%cd%\config.yml:/config.yml" -v "%userprofile%\.kube\config:/kubeconfig" registry.deckhouse.io/deckhouse/ee/install:stable bash -c "chmod 400 /tmp/.ssh/id_rsa; bash"
docker run --pull=always -it -v "%cd%\config.yml:/config.yml" -v "%userprofile%\.kube\config:/kubeconfig" registry.deckhouse.io/deckhouse/ee/install:stable bash -c "chmod 400 /tmp/.ssh/id_rsa; bash"

Примечание:

  • В файл /kubeconfig контейнера необходимо смонтировать файл конфигурации kubectl с доступом к Kubernetes API. В руководстве предполагается, что он находится в файле .kube/config домашнего каталога пользователя.

Внутри контейнера выполните команду:

dhctl bootstrap-phase install-deckhouse --kubeconfig=/kubeconfig --config=/config.yml
dhctl bootstrap-phase install-deckhouse --kubeconfig=/kubeconfig --config=/config.yml

По окончании установки произойдёт возврат к командной строке.

Почти все готово для полноценной работы Deckhouse Platform!

Если что-то пошло не так

Кластеры некоторых провайдеров могут требовать дополнительных действий до или после установки Deckhouse.

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

Ошибки установки на этапе 'Waiting for Deckhouse to become Ready'

  • Ошибка вида:
    │ │ ┌ Waiting for Deckhouse to become Ready
    │ │ │ Deckhouse pod found: deckhouse-64649df6f9-mf6dt (Pending)
    │ │ │ Deckhouse pod found: deckhouse-64649df6f9-mf6dt (Pending)
    

    Возможная причина — в кластере нет узла с label node-role.kubernetes.io/control-plane: "", который первоначально используется в nodeSelector манифеста deployment deckhouse.

    Варианты решения:

    • Отредактировать deployment deckhouse и указать нужный nodeSelector:
      kubectl -n d8-system edit deployment/deckhouse
      
    • Удалить nodeSelector у deployment deckhouse:
      kubectl patch -n d8-system deployment deckhouse --type json -p '[{"op": "remove", "path": "/spec/template/spec/nodeSelector"}]'
      

В кластере нет Ingress-контроллера...

Для работы модуля deckhouse-web, предоставляющего WEB-интерфейс к документации кластера, необходимо наличие в кластере Ingress-контроллера. Если в вашем кластере нет Ingress-контролллера, вы можете использовать модуль ingress-nginx следующим способом:

  • Включите модуль одним из следующих способов:
    • На этапе установки Deckhouse добавьте в файл config.yml в секцию deckhouse.configOverrides:
      ingressNginxEnabled: true
      
      ingressNginxEnabled: true

      Пример:

      deckhouse:
        configOverrides:
          ingressNginxEnabled: true
      
    • После установки Deckhouse, отредактируйте ConfigMap deckhouse:

      kubectl -n d8-system edit cm deckhouse
      
      kubectl -n d8-system edit cm deckhouse

      ... и добавьте:

      ingressNginxEnabled: "true"
      
      ingressNginxEnabled: "true"

      Пример:

      deckhouse:
        ingressNginxEnabled: "true"
      
  • Создайте файл ingress-nginx-controller.yml следующего содержания:

    # секция, описывающая параметры nginx ingress controller
    # используемая версия API Deckhouse
    apiVersion: deckhouse.io/v1
    kind: IngressNginxController
    metadata:
      name: nginx
    spec:
      # имя Ingress-класса для обслуживания Ingress NGINX controller
      ingressClass: nginx
      # версия Ingress-контроллера (используйте версию 1.1 с Kubernetes 1.23+)
      controllerVersion: "1.1"
      # способ поступления трафика из внешнего мира
      inlet: HostPort
      hostPort:
        httpPort: 80
        httpsPort: 443
      # описывает, на каких узлах будет находиться компонент
      # возможно, захотите изменить
      nodeSelector:
        node-role.kubernetes.io/control-plane: ""
      tolerations:
      - operator: Exists
    
    # секция, описывающая параметры nginx ingress controller # используемая версия API Deckhouse apiVersion: deckhouse.io/v1 kind: IngressNginxController metadata: name: nginx spec: # имя Ingress-класса для обслуживания Ingress NGINX controller ingressClass: nginx # версия Ingress-контроллера (используйте версию 1.1 с Kubernetes 1.23+) controllerVersion: "1.1" # способ поступления трафика из внешнего мира inlet: HostPort hostPort: httpPort: 80 httpsPort: 443 # описывает, на каких узлах будет находиться компонент # возможно, захотите изменить nodeSelector: node-role.kubernetes.io/control-plane: "" tolerations: - operator: Exists
  • Примените его, после установки Deckhouse, выполнив следующую команду:

    kubectl create -f ingress-nginx-controller.yml
    
    kubectl create -f ingress-nginx-controller.yml

Кластер в EKS AWS (Amazon Elastic Kubernetes Service)

Если вы устанавливаете Deckhouse в кластер EKS AWS (Amazon Elastic Kubernetes Service), то в запущенном контейнере инсталлятора установите aws-cli, выполнив:

apk add python3 py3-pip && pip3 install --upgrade pip && pip3 install awscli
apk add python3 py3-pip && pip3 install --upgrade pip && pip3 install awscli

Кластер в VK Cloud Solutions (MailRu Cloud Solutions)

  • В конфигурации инсталляции Deckhouse в массиве customTolerationKeys укажите taint CriticalAddonsOnly.

    Пример:

    deckhouse:
      releaseChannel: Stable
      bundle: Minimal
      configOverrides:
        global:
          modules:
            placement:
              customTolerationKeys:
              - CriticalAddonsOnly
            publicDomainTemplate: "%s.example.com"
    
  • В кластерах версии 1.21+ VK Cloud Solutions установлен Gatekeeper (OPA), который требует выставления requests и limits Pod'ам. Pod deckhouse не имеет requests/limits, остальные компоненты и модули Deckhouse получают вычисляемые параметры requests/limits в процессе работы Deckhouse.

    При просмотре событий Deployment deckhouse вы можете увидеть следующую ошибку:

    admission webhook "validation.gatekeeper.sh" denied the request: [container-must-have-limits] container <...> has no resource limits...

    Чтобы Deckhouse смог запуститься, необходимо перед установкой Deckhouse в таких кластерах добавить исключение GateKeeper (OPA) для namespace'ов компонентов Deckhouse (d8*-).

    Выполните в кластере:

    kubectl patch constraints container-must-have-limits --type json -p '[{"op": "replace", "path": "/spec/match/excludedNamespaces", "value": ["d8-*"]}]'
    
    kubectl patch constraints container-must-have-limits --type json -p '[{"op": "replace", "path": "/spec/match/excludedNamespaces", "value": ["d8-*"]}]'