Стадия жизненного цикла модуля: General Availability

Чтобы использовать ContainerdV2 в качестве container runtime на узлах кластера, ОС на виртуальных машинах должны соответствовать следующим требованиям:

  • ядро Linux версии 5.8 и новее, за исключением диапазонов 6.12.0–6.12.28 или 6.14.0–6.14.6 (эти версии подвержены уязвимости CVE-2025-37999 в EROFS);
  • поддержка CgroupsV2;
  • systemd версии 244 и новее;
  • поддержка модуля ядра erofs.

Подробнее — в документации.

На виртуальных машинах должен быть установлен пакет cloud-init. После запуска виртуальной машины должны быть запущены следующие службы, связанные с этим пакетом:

  • cloud-config.service;
  • cloud-final.service;
  • cloud-init.service.

Провайдер поддерживает работу только с одним диском в шаблоне виртуальной машины. Убедитесь, что шаблон содержит только один диск.

Создание сервисного аккаунта

Чтобы Deckhouse Platform (DP) могла управлять ресурсами в облаке Yandex Cloud, необходимо создать сервисный аккаунт и выдать ему права на редактирование. Подробная инструкция по созданию сервисного аккаунта в Yandex Cloud доступна в документации провайдера. Далее представлена краткая последовательность необходимых действий:

  1. Создайте пользователя с именем deckhouse:

    yc iam service-account create --name deckhouse
    

    В ответ вернутся параметры пользователя:

    id: <USER_ID>
    folder_id: <FOLDER_ID>
    created_at: "YYYY-MM-DDTHH:MM:SSZ"
    name: deckhouse
    
  2. Назначьте необходимые роли вновь созданному пользователю для своего облака:

    yc resource-manager folder add-access-binding --id <FOLDER_ID> --role compute.editor --subject serviceAccount:<USER_ID>
    yc resource-manager folder add-access-binding --id <FOLDER_ID> --role vpc.admin --subject serviceAccount:<USER_ID>
    yc resource-manager folder add-access-binding --id <FOLDER_ID> --role load-balancer.editor --subject serviceAccount:<USER_ID>
    
  3. Создайте JSON-файл с параметрами авторизации пользователя в облаке. В дальнейшем с помощью этих данных будет происходить авторизация в облаке:

    yc iam key create --service-account-name deckhouse --output deckhouse-sa-key.json
    

Для нового кластера может потребоваться увеличение квот. При необходимости также зарезервируйте публичный IP-адрес, как описано в разделе «Резервирование публичного IP-адреса».

Секрет с учётными данными

Ключ сервисного аккаунта хранится не в ModuleConfig, а в отдельном секрете. Провайдер читает его при запуске компонентов, которые обращаются к API Yandex Cloud.

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

  • имя d8-credentials, неймспейс d8-cloud-provider-yandex;
  • тип cloud-provider.deckhouse.io/credentials;
  • поле authScheme со значением serviceAccount;
  • поле secret с содержимым JSON-ключа сервисного аккаунта.
apiVersion: v1
kind: Secret
metadata:
  name: d8-credentials
  namespace: d8-cloud-provider-yandex
type: cloud-provider.deckhouse.io/credentials
stringData:
  authScheme: serviceAccount
  secret: |
    <SERVICE_ACCOUNT_JSON>

Замените <SERVICE_ACCOUNT_JSON> на содержимое файла deckhouse-sa-key.json.

Чтобы сменить учётные данные, обновите поле secret:

d8 k -n d8-cloud-provider-yandex edit secret d8-credentials

В схеме размещения WithNATInstance API-ключ для мониторинга NAT-инстанса хранится во втором секрете d8-credentials-exporter в том же неймспейсе. У него поле authScheme со значением apiToken, а ключ записан в поле secret.

В кластерах, переведённых на ModuleConfig, ключ сервисного аккаунта переносится в секрет d8-credentials из параметра provider.serviceAccountJSON ресурса YandexClusterConfiguration. API-ключ мониторинга переносится в секрет d8-credentials-exporter из параметра withNATInstance.exporterAPIKey.

Квоты

При заказе нового кластера необходимо увеличить квоты в консоли Yandex Cloud.

Рекомендованные значения квот при создании нового кластера:

  • Количество виртуальных процессоров: 64.
  • Общий объем SSD-дисков: 2000 ГБ.
  • Количество виртуальных машин: 25.
  • Общий объем RAM виртуальных машин: 256 ГБ.

Интеграция с Yandex Cloud

Начиная с DP 1.77, для новых кластеров в Yandex Cloud по умолчанию используется CNI cilium. В существующих кластерах текущая конфигурация CNI сохраняется.

Для новых кластеров на всех узлах требуется ядро Linux версии 5.8 или новее. Также убедитесь, что правила межсетевого экрана разрешают межузловой UDP-трафик, необходимый для работы Cilium VXLAN.

Подробнее в разделах «Требования к установке», «Сетевое взаимодействие компонентов платформы» и документации модуля cni-cilium.

Настройка групп безопасности

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

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

Не назначайте группы безопасности узлам вручную в консоли Yandex Cloud. Команда dhctl converge приводит виртуальные машины к состоянию, описанному в конфигурации кластера, и может снять такую привязку.

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

Ошибки в правилах нарушают работу кластера. Перед настройкой правил в production-кластере изучите особенности работы групп безопасности в Yandex Cloud.

Если в кластере используется cilium в режиме VXLAN, убедитесь, что группа безопасности разрешает межузловой UDP-трафик на портах, необходимых Cilium. Эти порты перечислены в разделе «Сетевое взаимодействие компонентов платформы».

Чтобы настроить правила группы безопасности:

  1. Определите облачную сеть, в которой работает кластер Deckhouse Platform.

    Название сети совпадает с параметром prefix ModuleConfig global. Его можно узнать с помощью команды:

    d8 k get mc global -o jsonpath='{.spec.settings.prefix}{"\n"}'
    

    Если значение пустое, возьмите его из устаревшего параметра cloud.prefix ресурса ClusterConfiguration (префикс перенесён в ModuleConfig global):

    d8 k get secrets -n kube-system d8-cluster-configuration -ojson | \
      jq -r '.data."cluster-configuration.yaml"' | base64 -d | grep prefix | cut -d: -f2
    
  2. В консоли Yandex Cloud выберите сервис Virtual Private Cloud и перейдите в раздел «Группы безопасности». У вас должна отображаться одна группа безопасности с пометкой Default.

    Группа безопасности по умолчанию

  3. Создайте правила согласно инструкции Yandex Cloud.

    Правила для группы безопасности

  4. Удалите правило, разрешающее любой входящий трафик (на скриншоте выше оно уже удалено), и сохраните изменения.

Интеграция с Yandex Lockbox

С помощью инструмента External Secrets Operator вы можете настроить синхронизацию секретов Yandex Lockbox с секретами кластера Deckhouse Platform.

Приведенную инструкцию следует рассматривать как Быстрый старт. Для использования интеграции в продуктивных средах ознакомьтесь со следующими ресурсами:

Инструкция по развертыванию

  1. Создайте сервисный аккаунт, необходимый для работы External Secrets Operator:

    yc iam service-account create --name eso-service-account
    
  2. Создайте авторизованный ключ для сервисного аккаунта и сохраните его в файл:

    yc iam key create --service-account-name eso-service-account --output authorized-key.json
    
  3. Назначьте сервисному аккаунту роли lockbox.editor, lockbox.payloadViewer и kms.keys.encrypterDecrypter для доступа ко всем секретам каталога:

    folder_id=<FOLDER_ID>
    yc resource-manager folder add-access-binding --id=${folder_id} --service-account-name eso-service-account --role lockbox.editor
    yc resource-manager folder add-access-binding --id=${folder_id} --service-account-name eso-service-account --role lockbox.payloadViewer
    yc resource-manager folder add-access-binding --id=${folder_id} --service-account-name eso-service-account --role kms.keys.encrypterDecrypter
    

    Для более тонкой настройки ознакомьтесь с управлением доступом в Yandex Lockbox.

  4. Установите External Secrets Operator с помощью Helm-чарта согласно инструкции.

    Обратите внимание, что вам может понадобиться задать nodeSelector, tolerations и другие параметры. Для этого используйте файл ./external-secrets/values.yaml после распаковки Helm-чарта.

    Скачайте и распакуйте чарт:

    helm pull oci://cr.yandex/yc-marketplace/yandex-cloud/external-secrets/chart/external-secrets \
      --version 0.5.5 \
      --untar
    

    Установите Helm-чарт:

    helm install -n external-secrets --create-namespace \
      --set-file auth.json=authorized-key.json \
      external-secrets ./external-secrets/
    

    Где:

    • authorized-key.json — название файла с авторизованным ключом из шага 2.
  5. Создайте хранилище секретов SecretStore, содержащее секрет sa-creds:

    d8 k -n external-secrets apply -f - <<EOF
    
    apiVersion: external-secrets.io/v1alpha1
    kind: SecretStore
    metadata:
      name: secret-store
    spec:
      provider:
        yandexlockbox:
          auth:
            authorizedKeySecretRef:
              name: sa-creds
              key: key
    EOF
    

    Где:

    • sa-creds — название Secret, содержащий авторизованный ключ. Этот секрет должен появиться после установки Helm-чарта.
    • key — название ключа в поле .data секрета выше.

Проверка работоспособности

  1. Проверьте статус External Secrets Operator:

    d8 k -n external-secrets get po
    

    Пример вывода:

    NAME                                                READY   STATUS    RESTARTS   AGE
    external-secrets-55f78c44cf-dbf6q                   1/1     Running   0          77m
    external-secrets-cert-controller-78cbc7d9c8-rszhx   1/1     Running   0          77m
    external-secrets-webhook-6d7b66758-s7v9c            1/1     Running   0          77m
    
  2. Проверьте состояние созданного хранилища секретов:

    d8 k -n external-secrets get secretstores.external-secrets.io
    

    Пример вывода:

    NAME           AGE   STATUS
    secret-store   69m   Valid
    
  3. Создайте секрет Yandex Lockbox со следующими параметрами:

    • Имя — lockbox-secret.
    • Ключ — введите неконфиденциальный идентификатор password.
    • Значение — введите конфиденциальные данные для хранения p@$$w0rd.
  4. Создайте объект ExternalSecret, указывающий на секрет lockbox-secret в хранилище secret-store:

    d8 k -n external-secrets apply -f - <<EOF
    
    apiVersion: external-secrets.io/v1alpha1
    kind: ExternalSecret
    metadata:
      name: external-secret
    spec:
      refreshInterval: 1h
      secretStoreRef:
        name: secret-store
        kind: SecretStore
      target:
        name: k8s-secret
      data:
      - secretKey: password
        remoteRef:
          key: <SECRET_ID>
          property: password
    EOF
    

    Где:

    • spec.target.name — имя нового секрета. External Secrets Operator создаст этот секрет в кластере Deckhouse Platform и поместит в него параметры секрета Yandex Lockbox lockbox-secret.
    • spec.data[].secretKey — название ключа в поле .data секрета, который создаст External Secrets Operator.
    • spec.data[].remoteRef.key — идентификатор созданного ранее секрета Yandex Lockbox lockbox-secret. Например, e6q28nvfmhu539******.
    • spec.data[].remoteRef.property — ключ, указанный ранее, для секрета Yandex Lockbox lockbox-secret.
  5. Убедитесь, что новый ключ k8s-secret содержит значение секрета lockbox-secret:

    d8 k -n external-secrets get secret k8s-secret -ojson | jq -r '.data.password' | base64 -d
    

    В выводе команды будет содержаться значение ключа password секрета lockbox-secret, созданного ранее:

    p@$$w0rd
    

Интеграция с Yandex Managed Service for Prometheus

С помощью данной интеграции вы можете использовать Yandex Managed Service for Prometheus в качестве внешнего хранилища метрик, например, для долгосрочного хранения.

Запись метрик

  1. Создайте сервисный аккаунт с ролью monitoring.editor.
  2. Создайте API-ключ для сервисного аккаунта.
  3. Создайте ресурс PrometheusRemoteWrite:

    d8 k apply -f - <<EOF
    
    apiVersion: deckhouse.io/v1
    kind: PrometheusRemoteWrite
    metadata:
      name: yc-remote-write
    spec:
      url: <URL_TO_WRITE_METRICS>
      bearerToken: <API_KEY>
    EOF
    

    Где:

    • <URL_TO_WRITE_METRICS> — URL со страницы Yandex Monitoring/Prometheus/Запись метрик.
    • <API_KEY> — API-ключ, созданный на предыдущем шаге. Например, AQVN1HHJReSrfo9jU3aopsXrJyfq_UHs********.

    Также вы можете указать дополнительные параметры в соответствии с документацией.

Подробнее с данной функциональностью можно ознакомиться в документации Yandex Cloud.

Чтение метрик через Grafana

  1. Создайте сервисный аккаунт с ролью monitoring.viewer.
  2. Создайте API-ключ для сервисного аккаунта.
  3. Создайте ресурс GrafanaAdditionalDatasource:

    d8 k apply -f - <<EOF
    
    apiVersion: deckhouse.io/v1
    kind: GrafanaAdditionalDatasource
    metadata:
      name: managed-prometheus
    spec:
      type: prometheus
      access: Proxy
      url: <URL_READING_METRICS_WITH_GRAFANA>
      basicAuth: false
      jsonData:
        timeInterval: 30s
        httpMethod: POST
        httpHeaderName1: Authorization
      secureJsonData:
        httpHeaderValue1: Bearer <API_KEY>
    EOF
    

    Где:

    • <URL_READING_METRICS_WITH_GRAFANA> — URL со страницы Yandex Monitoring/Prometheus/Чтение метрик через Grafana.
    • <API_KEY> — API-ключ, созданный на предыдущем шаге. Например, AQVN1HHJReSrfo9jU3aopsXrJyfq_UHs********.

    Также вы можете указать дополнительные параметры в соответствии с документацией.

Подробнее с данной функциональностью можно ознакомиться в документации Yandex Cloud.