VK Dev Platform logo
Помощь
Обновлена 6 ноября 2026 г. в 11:18

Подготовка окружения

Перед началом работы поместите в локальный каталог окружения devplatform_env файл kubeconfig для доступа к кластеру Kubernetes. Для production-инсталляций дополнительно понадобится приватный SSH-ключ в файле ssh_private_key для доступа к виртуальным машинам, а также TLS-сертификаты, ключи и сертификаты CA — если они нужны.

Запустите контейнер с образом Shepherd (подробнее — в разделе О Shepherd CLI):

$ docker run --rm -it -v "$PWD:/shepherd/env" shepherd:26.3.0 bash

Инициализация окружения

$ shepherd init

Команда shepherd init:

  • генерирует Inventory;
  • добавляет отсутствующие ключи в Kubernetes Secret shepherd-secrets;
  • шифрует kubeconfig и SSH-ключ (для production);
  • записывает файл состояния .shepherd_state.

Для выполнения команды нужен доступ к кластеру. При повторном запуске shepherd init уже существующие ключи Secret не перегенерируются.

Secrets и TLS-сертификаты по умолчанию хранятся в namespace shepherd.

Структура каталога после инициализации:

/shepherd/env/├── answers.yaml       # конфигурация, без открытых секретов├── inventory/         # результат генерации, не редактируйте вручную├── kubeconfig         # шифруется CLI при init├── ssh_private_key    # для prod, шифруется CLI при init├── .vault_pass        # пароль Vault, хранить защищенно└── .shepherd_state    # пространства имен и имена Secret, хэши и результаты запусков

Команда shepherd init создает .vault_pass, если файла нет. Сохраните его в защищенном хранилище на весь срок жизни окружения. Существующий пароль не заменяйте. Ограничьте права доступа к kubeconfig, SSH-ключу и .vault_pass до владельца. После shepherd init проверьте отсутствие предупреждений об ошибке шифрования.

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

$ shepherd secrets list

Сразу после первичной инициализации в списке отображаются сгенерированные секреты. Дополнительные секреты — например, учетные данные для внешнего S3-совместимого хранилища и SMTP-пароли — и TLS-сертификаты нужно добавить отдельно. Для существующей установки сначала перенесите действующие legacy-секреты (подробнее — в документе Руководство по обновлению VK Dev Platform).

Добавление секретов

В 26.3.0 учетные данные S3-хранилища не запрашиваются при shepherd init. До первого развертывания добавьте их командами:

$ shepherd secrets add all_s3_access_key_id --value$ shepherd secrets add all_s3_secret_access_key --value

Команда add используется только для отсутствующего ключа. Чтобы изменить существующее значение, используйте update без --value — команда запросит значение интерактивно:

$ shepherd secrets update all_s3_access_key_id$ shepherd secrets update all_s3_secret_access_key

CLI-команды работы с секретами обновляют файл состояния .shepherd_state.

TLS-сертификаты

Настройка сертификатов зависит от выбранных параметров в файле ответов answers.yaml (подробнее — в разделе Параметры сертификатов).

Wildcard-сертификат

Если используется wildcard-сертификат (или сертификат на домен с дополнительными SAN) без cert-manager, загрузите его:

$ shepherd certs add --wildcard --crt /shepherd/env/wildcard.crt --key /shepherd/env/wildcard.key

Если сертификаты подписаны корпоративным или частным CA, дополнительно загрузите полную цепочку CA-сертификатов:

$ shepherd certs add --wildcard --ca /shepherd/env/ca.crt

Чтобы узнать имена и заменить существующую пару, выполните команды:

$ shepherd certs list$ shepherd certs update wildcard --crt /shepherd/env/wildcard.crt --key /shepherd/env/wildcard.key

Пара сертификат/ключ заменяется вместе. Данные хранятся в Kubernetes Secret shepherd-certs в том же пространстве имен, что и shepherd-secrets. Изменения применяются к сервисам при следующем shepherd deploy.

Отдельные сертификаты для сервисов

Если используются отдельные сертификаты на один домен без дополнительных SAN, добавьте их через --service <КОМПОНЕНТ>. Пример для Samsara:

$ shepherd certs add --service samsara --crt /shepherd/env/samsara.crt --key /shepherd/env/samsara.key

Аналогично добавьте CA:

$ shepherd certs add --service samsara --ca /shepherd/env/samsara-ca.crt

Полный список переменных для сертификатов можно получить командой:

$ grep -r "_certificate_crt\|_certificate_key" roles/*/README.md | grep -v "common"

Переменные сертификатов доступны для следующих компонентов:

roles/front/README.md:| front_certificate_crt | "" | Открытый ключ сертификата |roles/front/README.md:| front_certificate_key | "" | Закрытый ключ сертификата |roles/gitlab/README.md:| gitlab_certificate_crt | "" | Открытый ключ сертификата |roles/gitlab/README.md:| gitlab_certificate_key | "" | Закрытый ключ сертификата |roles/keycloak/README.md:| keycloak_certificate_crt | "" | Открытый ключ сертификата |roles/keycloak/README.md:| keycloak_certificate_key | "" | Закрытый ключ сертификата |roles/keycloak/README.md:| keycloak_admin_certificate_crt | "{{ keycloak_certificate_crt }}" | Открытый ключ сертификата admin |roles/keycloak/README.md:| keycloak_admin_certificate_key | "{{ keycloak_certificate_key }}" | Закрытый ключ сертификата admin |roles/nexus/README.md:| nexus_certificate_crt | "" | Открытый ключ сертификата |roles/nexus/README.md:| nexus_certificate_key | "" | Закрытый ключ сертификата |roles/pgadmin/README.md:| pgadmin_certificate_crt | "" | Открытый ключ сертификата |roles/pgadmin/README.md:| pgadmin_certificate_key | "" | Закрытый ключ сертификата |roles/samsara/README.md:| samsara_certificate_crt | "" | Открытый ключ сертификата |roles/samsara/README.md:| samsara_certificate_key | "" | Закрытый ключ сертификата |roles/security_manager/README.md:| security_manager_certificate_crt | "" | Содержимое сертификата |roles/security_manager/README.md:| security_manager_certificate_key | "" | Содержимое приватного ключа |roles/sonarqube/README.md:| sonarqube_certificate_crt | "" | Открытый ключ сертификата |roles/sonarqube/README.md:| sonarqube_certificate_key | "" | Закрытый ключ сертификата |roles/vector/README.md:| vector_certificate_crt            | "" | Публичный ключ сертификата. |roles/vector/README.md:| vector_certificate_key            | "" | Приватный ключ сертификата. |roles/vk_registry/README.md:| vk_registry_certificate_crt | "" | Содержимое сертификата |roles/vk_registry/README.md:| vk_registry_certificate_key | "" | Содержимое приватного ключа |

Если сертификаты компонентов подписаны разными корневыми CA, загрузите цепочки CA для каждого компонента:

$ shepherd certs add --service <КОМПОНЕНТ> --ca <ПУТЬ_ДО_CA>

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

$ grep -r "_custom_cas " roles/*/README.md | grep -v "common"

Компоненты, которым нужна настройка CA:

roles/gitlab/README.md:| gitlab_custom_cas | "" | Кастомный CA |roles/keycloak/README.md:| keycloak_custom_cas | | Открытые сертификаты Custom Certificate Authority |roles/samsara/README.md:| samsara_custom_cas | "" | Открытые сертификаты Custom Certificate Authority |roles/sonarqube/README.md:| sonarqube_custom_cas | "" | Открытые сертификаты Custom Certificate Authority |roles/vector/README.md:| vector_custom_cas | {} | Содержимое кастомных CA (ключ → PEM). |
Была ли статья полезна?