Подготовка окружения
Перед началом работы поместите в локальный каталог окружения 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.
Настройка сертификатов зависит от выбранных параметров в файле ответов answers.yaml (подробнее — в разделе Параметры сертификатов).
Если используется 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). |