Index

Документация по установке и использованию HashiCorp Vault через Banzaicloud Vault Operator.

Оглавление

Описание

Banzaicloud Vault Operator - Kubernetes оператор для управления HashiCorp Vault с дополнительными возможностями: - Автоматическая инициализация и unsealing через Kubernetes Secrets - Веб-хуки для инжекта секретов из Vault в переменные окружения подов - Автоматическая конфигурация Vault через CRD - HA кластер с автоматическим failover

Возможности

  • ✅ Kubernetes Auto-Unseal - автоматический unseal через K8s секреты
  • ✅ Secrets Injection Webhook - прозрачный инжект секретов в переменные окружения подов
  • ✅ HA режим - 3 реплики Vault с автоматическим failover
  • ✅ Декларативная конфигурация - auth методы, политики, secret engines через CRD
  • ✅ Автоматическая инициализация - Vault инициализируется автоматически при первом запуске

Текущая конфигурация

  • Operator namespace: tech-vault-operator
  • Instances namespace: tech-vault-instances
  • Storage: Longhorn (5Gi per instance, StorageClass: longhorn-vault, 3 реплики)
  • Replicas: 3 пода Vault (HA с Raft)
  • Placement: Operator на masters, Vault на любых нодах с ОБЯЗАТЕЛЬНЫМ anti-affinity
  • Auto-unseal: Kubernetes Secrets (⚠️ рекомендуется KMS для production)
  • TLS: Enabled (self-signed сертификаты)
  • NetworkPolicy: Включена изоляция сети
  • PodDisruptionBudget: minAvailable=2

Быстрый старт

Примечание: Bank-Vaults использует новый OCI registry (oci://ghcr.io/bank-vaults/helm-charts/vault-operator). Старый Helm репозиторий больше недоступен. См. vault-install-guide.md для деталей.

1. Подготовка нод

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

1
cd ../.. && make k8s-prepare-nodes

Это добавит: - На master нодах: label node-role.kubernetes.io/control-plane=true и taint node-role.kubernetes.io/control-plane:NoSchedule - На worker нодах: label node-role.kubernetes.io/worker=true

2. Установка Operator

1
2
cd infra/k8s
make vault-install-operator

Это установит Bank-Vaults Vault Operator из OCI registry.

3. Создание Vault инстанса

1
make vault-create-instance

Это автоматически создаст RBAC ресурсы и Vault кластер.

Это создаст: - StorageClass longhorn-vault - Vault кластер из 3 подов - Service для доступа к Vault - Auto-unseal секрет

Важно: Vault автоматически инициализируется и unseal'ится. Root token и unseal keys хранятся в секрете vault-unseal-keys.

4. Проверка статуса

1
make vault-status

5. Получение root token

1
make vault-unseal-keys

Архитектура

Компоненты

Компонент Namespace Расположение Описание
Vault Operator tech-vault-operator Control-plane ноды Управляет Vault инстансами
Vault Webhook tech-vault-operator Control-plane ноды Инжект секретов в поды
Vault Pods tech-vault-instances Любые ноды Vault серверы (3 реплики)

Vault Cluster

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
┌─────────────────────────────────────────┐
│  tech-vault-instances                  │
├─────────────────────────────────────────┤
│  vault-0 (Active/Standby)              │
│  ├── Vault Server                      │
│  ├── Bank-Vaults Sidecar               │
│  └── Volume: 5Gi (Longhorn)            │
│                                         │
│  vault-1 (Active/Standby)              │
│  ├── Vault Server                      │
│  ├── Bank-Vaults Sidecar               │
│  └── Volume: 5Gi (Longhorn)            │
│                                         │
│  vault-2 (Active/Standby)              │
│  ├── Vault Server                      │
│  ├── Bank-Vaults Sidecar               │
│  └── Volume: 5Gi (Longhorn)            │
└─────────────────────────────────────────┘

Auto-Unseal через Kubernetes

Vault использует Kubernetes Secrets для auto-unseal: 1. При первом запуске Vault инициализируется 2. Root token и unseal keys сохраняются в секрет vault-unseal-keys 3. При перезапуске подов Vault автоматически unseal'ится, читая ключи из секрета 4. Никаких ручных действий для unsealing не требуется

Команды

Управление

1
2
3
4
5
6
7
8
9
make vault-install-operator   # Установка оператора и webhook
make vault-create-rbac        # Создание RBAC ресурсов
make vault-create-instance    # Создание Vault кластера
make vault-status             # Статус оператора и Vault
make vault-unseal-keys        # Показать root token и unseal keys
make vault-connect            # Инструкции по подключению
make vault-raft-peers         # Список Raft кластер пиров
make vault-recreate           # Удалить и пересоздать Vault инстанс
make vault-uninstall          # Удаление (УДАЛЯЕТ ДАННЫЕ!)

Справка

1
make vault-help  # Справка по Vault командам

Конфигурация

Vault Instance

Конфигурация в manifests/vault/vault-tech.yaml:

  • Size: 3 реплики
  • Image: hashicorp/vault:1.17.2
  • Bank-Vaults: ghcr.io/bank-vaults/bank-vaults:v1.32.0
  • Storage: Raft storage на Longhorn PVC (5Gi per pod, путь /vault/file)
  • Auto-unseal: Kubernetes Secrets (полностью автоматический)
  • Service: ClusterIP (без Ingress)
  • UI: Enabled (доступ через port-forward)
  • Istio: Enabled
  • Resources: 250m-1 CPU, 256Mi-512Mi RAM per pod (vault), 100m-500m CPU, 128Mi-256Mi RAM (bank-vaults)

Secret Engines

Автоматически настраиваются через externalConfig: - KV v2 на пути secret/ - для общих секретов

Auth Methods

  • Kubernetes auth - для подов в кластере
  • Default роль: доступ к secret/* для всех подов

Policies

  • allow_secrets - read/write доступ к secret/*

Использование веб-хуков

Banzaicloud Vault Operator включает мутирующий веб-хук, который автоматически инжектит секреты из Vault в переменные окружения подов.

Принцип работы

  1. Вы создаете секрет в Vault
  2. В манифесте пода используете специальный синтаксис vault:path/to/secret#key
  3. Webhook перехватывает создание пода и заменяет значения реальными данными из Vault

Пример использования

1. Создание секрета в Vault

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Port-forward к Vault
kubectl --kubeconfig=../../kubeconfig -n tech-vault-instances port-forward svc/vault 8200:8200

# Получить root token (PowerShell)
$VAULT_TOKEN = kubectl --kubeconfig=../../kubeconfig -n tech-vault-instances get secret vault-unseal-keys -o jsonpath='{.data.vault-root}' | ForEach-Object { [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($_)) }
$env:VAULT_ADDR = "http://localhost:8200"
$env:VAULT_TOKEN = $VAULT_TOKEN
$env:VAULT_SKIP_VERIFY = "true"

# Создать секрет
vault kv put secret/database/config username="dbuser" password="supersecret"

2. Использование в Deployment

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
  namespace: tech-vault-instances
spec:
  replicas: 1
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
      annotations:
        # Включить инжект секретов для этого пода
        vault.security.banzaicloud.io/vault-addr: "http://vault:8200"
        vault.security.banzaicloud.io/vault-role: "default"
        vault.security.banzaicloud.io/vault-skip-verify: "true"
    spec:
      serviceAccountName: default
      containers:
        - name: myapp
          image: myapp:latest
          env:
            # Webhook автоматически заменит эти значения
            - name: DB_USERNAME
              value: "vault:secret/data/database/config#username"
            - name: DB_PASSWORD
              value: "vault:secret/data/database/config#password"

3. Результат

При создании пода webhook автоматически: 1. Аутентифицируется в Vault через Kubernetes auth 2. Читает секрет по указанному пути 3. Заменяет vault:secret/data/database/config#username на реальное значение dbuser 4. Инжектит значения в переменные окружения пода

Синтаксис для KV v2

Для KV v2 engine путь включает /data/:

1
2
3
4
5
# KV v2 (наш случай)
value: "vault:secret/data/myapp/config#api_key"

# Чтение вложенных JSON полей
value: "vault:secret/data/myapp/config#nested.field.value"

Дополнительные аннотации

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
annotations:
  # Адрес Vault
  vault.security.banzaicloud.io/vault-addr: "http://vault:8200"

  # Роль для аутентификации (определена в Vault)
  vault.security.banzaicloud.io/vault-role: "default"

  # Пропустить проверку TLS (для dev окружений)
  vault.security.banzaicloud.io/vault-skip-verify: "true"

  # Namespace в Vault (для Vault Enterprise)
  vault.security.banzaicloud.io/vault-namespace: "myteam"

  # Путь к Kubernetes auth
  vault.security.banzaicloud.io/vault-path: "kubernetes"

  # Игнорировать ошибки чтения (под запустится даже если секрет не найден)
  vault.security.banzaicloud.io/vault-ignore-missing-secrets: "true"

Подключение к Vault

Connection Strings

1
2
3
4
5
# Внутри кластера
vault.tech-vault-instances.svc.cluster.local:8200

# HTTP (TLS disabled для упрощения)
http://vault.tech-vault-instances.svc.cluster.local:8200

Port-forward для локального доступа

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Запустить port-forward
kubectl --kubeconfig=../../kubeconfig -n tech-vault-instances port-forward svc/vault 8200:8200

# В другом терминале (PowerShell)
$VAULT_ADDR = "http://localhost:8200"
$VAULT_TOKEN = kubectl --kubeconfig=../../kubeconfig -n tech-vault-instances get secret vault-unseal-keys -o jsonpath='{.data.vault-root}' | ForEach-Object { [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($_)) }
$env:VAULT_ADDR = $VAULT_ADDR
$env:VAULT_TOKEN = $VAULT_TOKEN
$env:VAULT_SKIP_VERIFY = "true"

vault status

Доступ к UI

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# 1. Запустить port-forward
kubectl --kubeconfig=../../kubeconfig -n tech-vault-instances port-forward svc/vault 8200:8200

# 2. Получить root token
make vault-unseal-keys

# 3. Открыть браузер
# https://localhost:8200

# 4. Войти с root token
# ⚠️ Браузер покажет предупреждение о самоподписанном SSL-сертификате - это нормально
# Нажмите "Advanced" → "Proceed to localhost"

Exec в Vault pod

1
2
3
4
5
6
7
8
# Exec в контейнер vault
kubectl --kubeconfig=../../kubeconfig -n tech-vault-instances exec -it vault-0 -c vault -- sh

# Внутри пода
export VAULT_ADDR=http://127.0.0.1:8200
export VAULT_TOKEN=$(cat /vault/secrets/vault-root)
export VAULT_SKIP_VERIFY=true
vault status

Проверка Raft кластера

1
2
3
4
5
6
# Использовать готовую команду
make vault-raft-peers

# Или вручную (PowerShell)
$TOKEN = kubectl --kubeconfig=../../kubeconfig -n tech-vault-instances get secret vault-unseal-keys -o jsonpath='{.data.vault-root}' | ForEach-Object { [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($_)) }
kubectl --kubeconfig=../../kubeconfig -n tech-vault-instances exec vault-0 -c vault -- sh -c "VAULT_SKIP_VERIFY=true VAULT_TOKEN=$TOKEN vault operator raft list-peers"

Работа с секретами

CLI примеры

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
# Создать секрет (KV v2)
vault kv put secret/myapp/config \
  api_key="12345" \
  db_password="secret"

# Прочитать секрет
vault kv get secret/myapp/config

# Прочитать конкретное поле
vault kv get -field=api_key secret/myapp/config

# Обновить секрет (создаёт новую версию)
vault kv put secret/myapp/config \
  api_key="67890" \
  db_password="newsecret"

# Посмотреть историю версий
vault kv metadata get secret/myapp/config

# Удалить последнюю версию (soft delete)
vault kv delete secret/myapp/config

# Восстановить версию
vault kv undelete -versions=1 secret/myapp/config

# Удалить навсегда
vault kv destroy -versions=1 secret/myapp/config

REST API примеры

1
2
3
4
5
6
7
8
9
# Создать секрет
curl -X POST \
  -H "X-Vault-Token: $VAULT_TOKEN" \
  -d '{"data": {"api_key": "12345"}}' \
  http://localhost:8200/v1/secret/data/myapp/config

# Прочитать секрет
curl -H "X-Vault-Token: $VAULT_TOKEN" \
  http://localhost:8200/v1/secret/data/myapp/config

Troubleshooting

Operator не запускается

1
2
3
4
5
6
7
8
# Проверить логи оператора
kubectl -n tech-vault-operator logs deployment/vault-operator

# Проверить webhook
kubectl -n tech-vault-operator logs deployment/vault-secrets-webhook

# Проверить nodeSelector
kubectl -n tech-vault-operator get deployment vault-operator -o yaml | grep -A 5 nodeSelector

Vault pods не создаются

1
2
3
4
5
6
7
8
# Проверить статус Vault CR
kubectl -n tech-vault-instances get vaults.vault.banzaicloud.com vault -o yaml

# Проверить события
kubectl -n tech-vault-instances get events --sort-by='.lastTimestamp'

# Проверить PVC
kubectl -n tech-vault-instances get pvc

Vault не инициализируется

1
2
3
4
5
6
7
8
# Проверить логи Vault pod
kubectl -n tech-vault-instances logs vault-0 -c vault

# Проверить логи bank-vaults sidecar
kubectl -n tech-vault-instances logs vault-0 -c bank-vaults

# Проверить секрет с unseal keys
kubectl -n tech-vault-instances get secret vault-unseal-keys

Vault sealed

Если Vault sealed вручную или после проблем:

1
2
3
4
5
6
# Проверить статус
kubectl -n tech-vault-instances exec vault-0 -- vault status

# Vault должен unseal'иться автоматически
# Если нет, проверьте логи bank-vaults sidecar
kubectl -n tech-vault-instances logs vault-0 -c bank-vaults

Webhook не работает

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Проверить MutatingWebhookConfiguration
kubectl get mutatingwebhookconfigurations vault-secrets-webhook

# Проверить логи webhook
kubectl -n tech-vault-operator logs deployment/vault-secrets-webhook

# Проверить сертификаты webhook
kubectl -n tech-vault-operator get secret vault-secrets-webhook

# Проверить аннотации на поде
kubectl -n <namespace> get pod <pod-name> -o yaml | grep vault.security.banzaicloud.io

Проблемы с доступом к секретам

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
# Проверить что Kubernetes auth включен
vault auth list

# Проверить роль
vault read auth/kubernetes/role/default

# Проверить политику
vault policy read allow_secrets

# Проверить что service account может аутентифицироваться
kubectl -n tech-vault-instances run vault-test --rm -it --image=vault:1.17.2 -- sh
# Внутри пода:
export VAULT_ADDR=http://vault:8200
vault write auth/kubernetes/login \
  role=default \
  jwt=$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)

Примеры использования

Пример 1: Database credentials для приложения

1
2
3
4
5
6
# Создать секрет в Vault
vault kv put secret/database/myapp \
  host="postgres.tech-postgres-databases.svc.cluster.local" \
  port="5432" \
  username="myapp_user" \
  password="strongpassword"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
# Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
  namespace: tech-vault-instances
spec:
  template:
    metadata:
      annotations:
        vault.security.banzaicloud.io/vault-addr: "http://vault:8200"
        vault.security.banzaicloud.io/vault-role: "default"
        vault.security.banzaicloud.io/vault-skip-verify: "true"
    spec:
      containers:
        - name: app
          image: myapp:latest
          env:
            - name: DB_HOST
              value: "vault:secret/data/database/myapp#host"
            - name: DB_PORT
              value: "vault:secret/data/database/myapp#port"
            - name: DB_USER
              value: "vault:secret/data/database/myapp#username"
            - name: DB_PASSWORD
              value: "vault:secret/data/database/myapp#password"

Пример 2: API ключи для внешних сервисов

1
2
3
4
5
6
# Создать секреты
vault kv put secret/external/services \
  stripe_api_key="sk_test_..." \
  sendgrid_api_key="SG...." \
  aws_access_key_id="AKIA..." \
  aws_secret_access_key="..."

1
2
3
4
5
6
7
8
9
env:
  - name: STRIPE_API_KEY
    value: "vault:secret/data/external/services#stripe_api_key"
  - name: SENDGRID_API_KEY
    value: "vault:secret/data/external/services#sendgrid_api_key"
  - name: AWS_ACCESS_KEY_ID
    value: "vault:secret/data/external/services#aws_access_key_id"
  - name: AWS_SECRET_ACCESS_KEY
    value: "vault:secret/data/external/services#aws_secret_access_key"

Пример 3: Multi-environment конфигурация

1
2
3
4
# Разные секреты для разных окружений
vault kv put secret/myapp/dev api_url="https://dev-api.example.com" api_key="dev-key"
vault kv put secret/myapp/staging api_url="https://staging-api.example.com" api_key="staging-key"
vault kv put secret/myapp/prod api_url="https://api.example.com" api_key="prod-key"

1
2
3
4
5
6
# В dev namespace
env:
  - name: API_URL
    value: "vault:secret/data/myapp/dev#api_url"
  - name: API_KEY
    value: "vault:secret/data/myapp/dev#api_key"

Best Practices

  1. Используйте отдельные роли для разных приложений с минимальными правами
  2. Версионирование секретов - KV v2 хранит историю изменений
  3. Регулярно ротируйте root token и создавайте отдельные токены для разных задач
  4. Backup - регулярно бэкапьте Longhorn volumes с Vault данными
  5. Мониторинг - настройте алерты на sealed Vault или недоступность API
  6. TLS в продакшене - включите TLS для production окружений
  7. Аудит логи - включен аудит для отслеживания доступа к секретам

Безопасность

Root Token

Root token имеет полные права на Vault. Защитите его:

1
2
3
4
5
6
7
8
# Получить root token (только при необходимости)
kubectl -n tech-vault-instances get secret vault-unseal-keys -o jsonpath='{.data.vault-root}' | base64 -d

# Revoke root token после настройки
vault token revoke <root-token>

# Создать новый root token (в случае необходимости)
vault operator generate-root

RBAC

Ограничьте доступ к namespace tech-vault-instances и секрету vault-unseal-keys.

Network Policies

Рекомендуется настроить NetworkPolicy для ограничения доступа к Vault только от нужных подов.

Безопасность

⚠️ ВАЖНО: Текущая конфигурация использует Kubernetes Secrets для auto-unseal. Это подходит для dev/test окружений, но НЕ РЕКОМЕНДУЕТСЯ для production.

Для Production обязательно:

  1. Миграция на KMS auto-unseal (AWS KMS, Azure Key Vault, GCP KMS)
  2. Ограничение использования root-токена - создавайте отдельные токены с минимальными правами
  3. Гранулярные политики доступа - не используйте secret/* для всех, создавайте отдельные политики
  4. Регулярное резервное копирование - бэкапьте Longhorn volumes с Vault данными
  5. Мониторинг и алертинг - настройте алерты на sealed Vault или недоступность API
  6. TLS сертификаты - используйте cert-manager для production сертификатов

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Проверить статус всех компонентов
make vault-status

# Проверить Raft кластер
make vault-raft-peers

# Проверить поды и их распределение по нодам
kubectl --kubeconfig=../../kubeconfig -n tech-vault-instances get pods -l app.kubernetes.io/name=vault -o wide

# Проверить PodDisruptionBudget
kubectl --kubeconfig=../../kubeconfig -n tech-vault-instances get pdb vault-pdb

Ссылки

← Назад к главной документации