Настройка интеграции с 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:

  1. В кластере управления в неймспейсе 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
  1. В кластере управления в неймспейсе 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.


Что дальше