Настройка интеграции с HashiCorp Vault в профиле кластера
Настройка интеграции с Vault в клиентских кластерах с типовой конфигурацией через ClusterProfile.
Введение
В платформе «Штурвал» доступно управление профилями клиентских кластеров (ClusterProfile), которые позволяют заранее определить YAML-манифесты для применения при инициализации кластера.
Вы можете задать в конфигурации ClusterProfile типовую интеграцию с HashiCorp Vault для новых создаваемых клиентских кластеров. В качестве механизма синхронизации секретов между Vault и Kubernetes в этой инструкции используется vault-secrets-operator. Helm чарт vault-secrets-operator поставляется отдельным бандлом.
Инструкция описывает сценарий, в котором:
- для новых клиентских кластеров администратор заранее создает профиль кластера (
ClusterProfile) с необходимыми манифестами для настройки интеграции с Vault в процессе развертывания кластера.
Обратите внимание! Когда клиентский кластер развернут, для итоговой интеграции с Vault потребуется:
- настройка метода аутентификации на стороне Vault;
- создание кастомного ресурса
VaultAuthс параметрами метода аутентификации в кластере.
См. Настройка интеграции с Vault в развёрнутом кластере
Предусловия
- сервер HashiCorp Vault развёрнут и хранилище Vault разблокировано (unsealed), известен адрес сервера Vault;
- при необходимости использования TLS при подключении к Vault получите CA-сертификат, которым подписан сертификат сервера Vault;
- бандл с
vault-secrets-operatorполучен и загружен в зеркало. Подробнее о добавлении пакетов и образов в зеркало на странице Работа с патчами.
Шаг 1. Сконфигурируйте ClusterProfile
Для преднастройки интеграции через ClusterProfile подготовьте манифесты и создайте ClusterProfile вручную или одним запуском, запустив Bash-скрипт.
Шаг 1.1 Подготовьте манифесты ShturvalServiceConfig, Secret и VaultConnection
Первым шагом подготовьте манифесты, которые будут добавлены в профиль кластера:
- два манифеста
ShturvalServiceConfigсервисаvault-secrets-operator; - кастомный ресурс
VaultConnection; - Secret с CA-сертификатом Vault, если требуется установка TLS-соединения при подключении к Vault.
Создание ресурсов ShturvalServiceConfig разворачивает сервис в кластере.
apiVersion: ops.shturval.tech/v1beta1
kind: ShturvalServiceConfig
metadata:
name: vault-secrets-operator
spec:
dependency:
- vault-secrets-operator-crds
mode: auto
namespace: vault-operator
chart: vault-secrets-operator
reponame: shturval
version: 2.14.0
apiVersion: ops.shturval.tech/v1beta1
kind: ShturvalServiceConfig
metadata:
name: vault-secrets-operator-crds
spec:
mode: auto
namespace: vault-operator
chart: vault-secrets-operator-crds
reponame: shturval
version: 2.14.0
VaultConnection задаёт параметры подключения к серверу Vault.
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultConnection
metadata:
name: vault-connection-name
namespace: vault-operator
spec:
address: https://vault.ip-11-12-13-14.shturval.link
caCertSecretRef: vault-ca
skipTLSVerify: false
Описание используемых параметров VaultConnection:
| Поле | Тип | Описание |
|---|---|---|
address |
string | Адрес вашего сервера Vault |
caCertSecretRef |
string | Имя Secret с CA-сертификатом для подключения к Vault. Если skipTLSVerify установлен в false, манифест этого Secret необходимо заранее добавить в профиль кластера для создания в неймспейсе, где будет создан VaultConnection |
skipTLSVerify |
boolean | Отключить проверку TLS-сертификата Vault. Если указано false, требуется Secret, заданный в caCertSecretRef |
Если в VaultConnection указано skipTLSVerify: false, заранее подготовьте Secret с CA-сертификатом Vault. Secret должен быть создан в том же неймспейсе, что и VaultConnection, а его имя должно быть указано в параметре caCertSecretRef.
apiVersion: v1
kind: Secret
metadata:
name: vault-ca
namespace: vault-operator
type: Opaque
data:
ca.crt: <CA-encoded-base64>
Шаг 1.2. Создайте ClusterProfile
Профиль кластера можно создать одним из двух способов:
- в графическом интерфейсе платформы;
- с помощью CLI без использования графического интерфейса.
Подробнее о способах настройки и использования профилей на странице Профили кластеров.
Где настраивать: Платформа → Профили конфигурации → Создать профиль.
Скриншот: переход с вкладки «Платформа»

На странице создания профиля заполните обязательные поля. В блоке Спецификация перейдите на вкладку “Кастомные манифесты” и выберите “Создать в клиентском кластере”. Добавьте подготовленные на шаге 1 манифесты:
- два
ShturvalServiceConfig; VaultConnection;- Secret с CA-сертификатом Vault, если требуется проверка TLS-сертификата.
Скриншот: манифесты в профиле

Сохраните профиль кластера.
Чтобы использовать манифесты через ClusterProfile:
- В кластере управления в неймспейсе
kube-systemсоздайте Secret:
- с типом
Opaque; - с обязательным лейблом
cluster.shturval.tech/manifest; - с кастомным лейблом для последующего указания в профиле кластера через механизм селектора лейблов (
matchLabels); - добавьте ключи, в значении которых укажите: два манифеста
ShturvalServiceConfig, манифестVaultConnectionи манифест Secret с CA-сертификатом Vault при необходимости проверки TLS-сертификата, закодированные вbase64.
kubectl apply -f - <<EOF
apiVersion: v1
kind: Secret
type: Opaque
metadata:
name: vault-profile-manifests
namespace: kube-system
labels:
cluster.shturval.tech/manifest: ""
profile: vault
data:
ssc: base64-encoded-ShturvalServiceConfig
crd: base64-encoded-ShturvalServiceConfigCrd
vaultcasecret: base64-encoded-VaultCaSecret
vaultconnection: base64-encoded-VaultConnection
EOF
- В кластере управления в неймспейсе
kube-systemсоздайте профиль кластера, где вmatchLabelsдобавьте кастомный лейбл созданного Secret:
kubectl apply -f - <<EOF
apiVersion: cluster.shturval.tech/v1beta1
kind: ClusterProfile
metadata:
name: vault-client-cluster-profile
namespace: kube-system
spec:
customManifests:
- clientManifestsSelector:
matchLabels:
profile: vault
EOF
Обратите внимание!
- Не переопределять
default-client-cluster-profile; - изменения в
ClusterProfileне применяются автоматически к уже созданным ранее кластерам.
Обратите внимание! Перед запуском скрипта проверьте значения переменных. Скрипт автоматически формирует манифесты, создаёт Secret с ними и создаёт ClusterProfile, поэтому ошибка в параметрах может привести к созданию некорректного профиля для новых клиентских кластеров.
Перед запуском скрипта подключитесь к кластеру управления через kubeconfig.
Переменные, используемые в скрипте:
| Переменная | Значение по умолчанию | Ограничение | Описание |
|---|---|---|---|
VAULT_ADDRESS |
— | — | Адрес сервера Vault. Значение необходимо задать перед запуском скрипта |
VSO_NAMESPACE |
vault-operator |
Не переопределять | Неймспейс, в котором будет создан сервис vault-secrets-operator |
VSO_SSC_NAME |
vault-secrets-operator |
— | Имя ресурса ShturvalServiceConfig для сервиса vault-secrets-operator |
VSO_SSC_CRD_NAME |
vault-secrets-operator-crds |
— | Имя ресурса ShturvalServiceConfig для CRD сервиса vault-secrets-operator |
VSO_CHART_NAME |
vault-secrets-operator |
Не переопределять | Имя Helm-чарта сервиса vault-secrets-operator |
VSO_CRD_CHART_NAME |
vault-secrets-operator-crds |
Не переопределять | Имя Helm-чарта CRD сервиса vault-secrets-operator |
VSO_REPONAME |
shturval |
Не переопределять | Имя репозитория Helm-чарта сервиса vault-secrets-operator |
VSO_VERSION |
2.14.0 |
— | Версия Helm-чарта сервиса vault-secrets-operator |
VAULTCONNECTION_NAME |
vault-connection-name |
— | Имя ресурса VaultConnection |
VAULT_CACERT_SECRET_REF |
vault-ca |
Не переопределять | Имя Secret с CA-сертификатом кластера для подключения к Vault |
VAULT_CA_CERT_PATH |
— | — | Путь к файлу с CA-сертификатом Vault в PEM-формате. Обязателен, если VAULT_SKIP_TLS_VERIFY=false |
VAULT_SKIP_TLS_VERIFY |
false |
— | Отключить проверку TLS-сертификата Vault |
MGMT_NAMESPACE |
kube-system |
Не переопределять | Неймспейс кластера управления, где создаются Secret и ClusterProfile |
PROFILE_LABEL_VALUE |
vault |
— | Значение лейбла profile для выбора манифестов в ClusterProfile |
MANIFESTS_SECRET_NAME |
vault-profile-manifests |
— | Имя Secret, в котором хранятся base64-кодированные манифесты |
CLUSTERPROFILE_NAME |
vault-client-cluster-profile |
— | Имя создаваемого ресурса ClusterProfile |
bash /dev/stdin <<'EOF'
set -euo pipefail
: "${VAULT_ADDRESS:?Задайте VAULT_ADDRESS, например https://vault.example.shturval.link}"
VSO_NAMESPACE="${VSO_NAMESPACE:-vault-operator}"
VSO_SSC_NAME="${VSO_SSC_NAME:-vault-secrets-operator}"
VSO_SSC_CRD_NAME="${VSO_SSC_CRD_NAME:-vault-secrets-operator-crds}"
VSO_CHART_NAME="${VSO_CHART_NAME:-vault-secrets-operator}"
VSO_CRD_CHART_NAME="${VSO_CRD_CHART_NAME:-vault-secrets-operator-crds}"
VSO_REPONAME="${VSO_REPONAME:-shturval}"
VSO_VERSION="${VSO_VERSION:-2.14.0}"
VAULTCONNECTION_NAME="${VAULTCONNECTION_NAME:-vault-connection-name}"
VAULT_CACERT_SECRET_REF="${VAULT_CACERT_SECRET_REF:-vault-ca}"
VAULT_CA_CERT_PATH="${VAULT_CA_CERT_PATH:-}"
VAULT_SKIP_TLS_VERIFY="${VAULT_SKIP_TLS_VERIFY:-false}"
MGMT_NAMESPACE="${MGMT_NAMESPACE:-kube-system}"
PROFILE_LABEL_VALUE="${PROFILE_LABEL_VALUE:-vault}"
MANIFESTS_SECRET_NAME="${MANIFESTS_SECRET_NAME:-vault-profile-manifests}"
CLUSTERPROFILE_NAME="${CLUSTERPROFILE_NAME:-vault-client-cluster-profile}"
b64_oneline() {
# Для GNU coreutils используется base64 -w0, в остальных случаях переводы строк удаляются отдельно.
if base64 --help 2>/dev/null | grep -q -- ' -w'; then
base64 -w0
else
base64 | tr -d '\n'
fi
}
SSC_YAML=$(cat <<EOF2
apiVersion: ops.shturval.tech/v1beta1
kind: ShturvalServiceConfig
metadata:
name: ${VSO_SSC_NAME}
spec:
dependency:
- ${VSO_SSC_CRD_NAME}
mode: auto
namespace: ${VSO_NAMESPACE}
chart: ${VSO_CHART_NAME}
reponame: ${VSO_REPONAME}
version: ${VSO_VERSION}
EOF2
)
SSC_CRD_YAML=$(cat <<EOF2
apiVersion: ops.shturval.tech/v1beta1
kind: ShturvalServiceConfig
metadata:
name: ${VSO_SSC_CRD_NAME}
spec:
mode: auto
namespace: ${VSO_NAMESPACE}
chart: ${VSO_CRD_CHART_NAME}
reponame: ${VSO_REPONAME}
version: ${VSO_VERSION}
EOF2
)
VAULT_CACERT_LINE=""
VAULT_CA_SECRET_ENTRY=""
if [ "${VAULT_SKIP_TLS_VERIFY}" != "true" ]; then
: "${VAULT_CA_CERT_PATH:?Задайте VAULT_CA_CERT_PATH, если VAULT_SKIP_TLS_VERIFY=false}"
VAULT_CACERT_LINE=" caCertSecretRef: ${VAULT_CACERT_SECRET_REF}"
VAULT_CA_CERT_B64=$(b64_oneline < "${VAULT_CA_CERT_PATH}")
VAULT_CA_SECRET_YAML=$(cat <<EOF2
apiVersion: v1
kind: Secret
metadata:
name: ${VAULT_CACERT_SECRET_REF}
namespace: ${VSO_NAMESPACE}
type: Opaque
data:
ca.crt: ${VAULT_CA_CERT_B64}
EOF2
)
VAULT_CA_SECRET_B64=$(printf '%s' "$VAULT_CA_SECRET_YAML" | b64_oneline)
VAULT_CA_SECRET_ENTRY=" vaultcasecret: ${VAULT_CA_SECRET_B64}"
fi
VAULTCONNECTION_YAML=$(cat <<EOF2
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultConnection
metadata:
name: ${VAULTCONNECTION_NAME}
namespace: ${VSO_NAMESPACE}
spec:
address: ${VAULT_ADDRESS}
${VAULT_CACERT_LINE}
skipTLSVerify: ${VAULT_SKIP_TLS_VERIFY}
EOF2
)
SSC_B64=$(printf '%s' "$SSC_YAML" | b64_oneline)
SSC_CRD_B64=$(printf '%s' "$SSC_CRD_YAML" | b64_oneline)
VAULTCONNECTION_B64=$(printf '%s' "$VAULTCONNECTION_YAML" | b64_oneline)
kubectl apply -f - <<EOF2
apiVersion: v1
kind: Secret
type: Opaque
metadata:
name: ${MANIFESTS_SECRET_NAME}
namespace: ${MGMT_NAMESPACE}
labels:
cluster.shturval.tech/manifest: ""
profile: ${PROFILE_LABEL_VALUE}
data:
ssc: ${SSC_B64}
crd: ${SSC_CRD_B64}
${VAULT_CA_SECRET_ENTRY}
vaultconnection: ${VAULTCONNECTION_B64}
EOF2
kubectl apply -f - <<EOF2
apiVersion: cluster.shturval.tech/v1beta1
kind: ClusterProfile
metadata:
name: ${CLUSTERPROFILE_NAME}
namespace: ${MGMT_NAMESPACE}
spec:
customManifests:
- clientManifestsSelector:
matchLabels:
profile: ${PROFILE_LABEL_VALUE}
EOF2
EOF
После выполнения скрипта переходите к шагу 2.
Шаг 2. Выберите профиль при создании клиентского кластера
В графическом интерфейсе создания клиентского кластера на шаге «Основные данные» (куда перейти из детализации шагов мастера) в поле Профиль кластера выберите созданный профиль.
Скриншот: выбор профиля кластера

Что создаётся
При инициализации кластера после этапа развёртывания сервисов будут применены манифесты в клиентском кластере из профиля:
- два манифеста
ShturvalServiceConfigи развернут сервисvault-secrets-operator; - создан Secret с CA-сертификатом Vault, если он добавлен в профиль;
- создан кастомный ресурс
VaultConnection.
При развёртывании vault-secrets-operator в клиентском кластере в неймспейсе vault-operator будут созданы:
- ServiceAccount
vault-secrets-operator-controller-managerс рольюsystem:auth-delegatorдля аутентификации в Vault; - Secret
vault-secretс типомkubernetes.io/service-account-tokenс токеном и CA кластера для ServiceAccount.
Этот Secret не заменяет Secret с CA-сертификатом сервера Vault, который указывается в caCertSecretRef.