Для улучшения работы сайта мы используем файлы cookies. Оставаясь на сайте, вы соглашаетесь с политикой обработки персональных данных.

Движки секретов. Kubernetes (API)

Этот движок может использовать внешние сертификаты X.509 в рамках TLS или для проверки подписей. Проверка подписей с использованием сертификатов X.509, в которых применяется SHA-1, устарела и больше не совместима без обходных решений.

В данном разделе представлена документация по API для движка секретов Kubernetes StarVault. Чтобы узнать больше о его использовании и работе, смотрите документацию по движку секретов Kubernetes.

Данная документация предполагает, что движок секретов Kubernetes подключен по пути /kubernetes в StarVault. Поскольку возможна активация движков секретов в любом месте, убедитесь, что ваши API-запросы соответствуют вашему конфигу.

1. Настройка конфигурации

Этот эндпоинт настраивает плагин с необходимой информацией для доступа к API Kubernetes и аутентификации с его помощью.

Метод Путь

POST

/kubernetes/config

1.1. Параметры

  • kubernetes_host (string: "https://$KUBERNETES_SERVICE_HOST:KUBERNETES_SERVICE_PORT_HTTPS") - URL API Kubernetes для подключения. Обязателен к указанию, если стандартные переменные окружения подподов KUBERNETES_SERVICE_HOST или KUBERNETES_SERVICE_PORT_HTTPS не установлены.

  • kubernetes_ca_cert (string: "") - PEM-кодированный сертификат CA для проверки сертификата сервера API Kubernetes. По умолчанию берется сертификат CA из локального пода по пути /var/run/secrets/kubernetes.io/serviceaccount/ca.crt, если он существует, иначе - корневой CA хоста.

  • service_account_jwt (string: "") - JSON Web Token сервисного аккаунта, используемый движком секретов для управления учетными данными Kubernetes. По умолчанию берется JWT локального пода по пути /var/run/secrets/kubernetes.io/serviceaccount/token, если он есть.

  • disable_local_ca_jwt (bool: false) - отключает использование сертификата CA и JWT сервисного аккаунта по умолчанию при работе в Kubernetes.

Пример тела запроса:
{
  "kubernetes_host": "https://192.168.99.100:8443",
  "kubernetes_ca_cert": "-----BEGIN CERTIFICATE-----\n.....\n-----END CERTIFICATE-----"
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/kubernetes/config

2. Чтение конфигурации

Возвращает ранее установленную конфигурацию, исключая учетные данные.

Метод Путь

GET

/kubernetes/config
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/kubernetes/config
Пример ответа:
{
  "data": {
    "kubernetes_host": "https://192.168.99.100:8443",
    "kubernetes_ca_cert": "-----BEGIN CERTIFICATE-----.....-----END CERTIFICATE-----",
    "disable_local_ca_jwt": false
  }
}

3. Удаление конфигурации

Удаляет ранее установленную конфигурацию.

Метод Путь

DELETE

/kubernetes/config
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/kubernetes/config

4. Создание роли

Роль настраивает, какие токены сервисных аккаунтов можно генерировать и какие разрешения будут прикреплены к ним. Разрешения, назначенные токену сервисного аккаунта, зависят от ролей Kubernetes, применяемых к его сервисному аккаунту.

Каждая роль движка секретов Kubernetes может работать в одном из 3 режимов. Каждый следующий режим создает больше объектов Kubernetes и поэтому требует больше разрешений для собственного сервисного аккаунта StarVault.

  • Создать токен сервисного аккаунта для существующего сервисного аккаунта - задайте service_account_name.

  • Создать сервисный аккаунт и токен, и привязать существующую роль Kubernetes - задайте kubernetes_role_name.

  • Создать роль Kubernetes, привязку роли, сервисный аккаунт и токен - задайте generated_role_rules.

Может быть установлено только одно из service_account_name, kubernetes_role_name или generated_role_rules.

Метод Путь

POST

/kubernetes/roles/:name

4.1. Параметры

  • name (string: <required>) - название роли, включенное в путь.

  • allowed_kubernetes_namespaces (array: []) - список пространств имен Kubernetes, для которых может быть сгенерировано удостоверение. При установке значения "*" все пространства разрешены. Если установлено с allowed_kubernetes_namespace_selector, условия объединяются через OR.

  • allowed_kubernetes_namespace_selector (string: "") - селектор меток для пространств имен Kubernetes, в которых можно генерировать удостоверения. Может принимать JSON или YAML объект. Значение должно быть типа LabelSelector, как на примерах ниже.

  • token_max_ttl (string: "") - максимальный TTL для сгенерированных токенов Kubernetes, в секундах или в формате строки продолжительности Go, например "1h". Если не установлено или равно 0, используется системный по умолчанию.

  • token_default_ttl (string: "") - значение TTL по умолчанию для сгенерированных токенов Kubernetes, в секундах или формате строки продолжительности Go, например "1h". Если не установлено или равно 0, используется системный по умолчанию.

  • token_default_audiences (string: "") - общие назначения для сгенерированных токенов, через запятую. Например "custom-audience-0,custom-audience-1". Если не установлено или равно "", будет использовано значение по умолчанию из Kubernetes.

  • service_account_name (string: "") - существующий сервисный аккаунт, для которого будут сгенерированы токены. Совместимо только с одним из параметров роли. При установке создаст только токен Kubernetes. Подробнее - документация по сервисным аккаунтам.

  • kubernetes_role_name (string: "") - существующая роль или кластер-роль, для привязки сгенерированного сервиса или токена. Создастся также Kubernetes роль, привязка роли и сервисный аккаунт при запросе. Подробнее - документация по Kubernetes ролям.

  • kubernetes_role_type (string: "Role") - указывает тип роли: Role или ClusterRole.

  • generated_role_rules (string: "") - правила роли или кластер-роль, используемые при генерации. Может быть в JSON или YAML. В случае установки создается весь комплект объектов Kubernetes. Значение должно содержать ключ rules с массивом объектов PolicyRule из документации Kubernetes.

  • name_template (string: "") - шаблон имени при генерации сервисных аккаунтов, ролей и привязок ролей. Если не задан, используется шаблон по умолчанию. Подробнее о шаблонах - шаблонирование имени пользователя.

  • extra_annotations (map<string|string>: nil) - дополнительные аннотации ко всем создаваемым объектам Kubernetes. Подробнее - документация по аннотациям.

  • extra_labels (map<string|string>: nil) - дополнительные метки для всех создаваемых объектов Kubernetes. Подробнее - документация по меткам.

4.2. Примеры полезных нагрузок

Пример 1 - создание токенов для существующего сервисного аккаунта:
{
  "allowed_kubernetes_namespaces": "*",
  "service_account_name": "default",
  "token_max_ttl": "24h"
}
Пример 2 - создание токенов для существующей ClusterRole:
{
  "allowed_kubernetes_namespaces": "*",
  "kubernetes_role_type": "ClusterRole",
  "kubernetes_role_name": "starvault-k8s-secrets-role"
}
Пример 3 - создание токенов для заданных правил Kubernetes роли:
{
  "allowed_kubernetes_namespaces": "*",
  "generated_role_rules": "rules:\n- apiGroups: [\"\"]\n  resources: [\"pods\"]\n  verbs: [\"list\"]\n",
}
Пример с JSON:
{
  "allowed_kubernetes_namespaces": "*",
  "generated_role_rules": "'rules': [{'apiGroups': [''],'resources': ['pods'],'verbs': ['list']}]"
}
Пример 4 - генерировать токены в пространствах имен, выбранных по меткам:
{
  "allowed_kubernetes_namespace_selector": "matchLabels:\n  stage: prod\n  sa-generator: starvault",
  "service_account_name": "default"
}
Пример с JSON:
{
  "allowed_kubernetes_namespace_selector": "'{'matchLabels':{'stage':'prod','sa-generator':'starvault'}}",
  "service_account_name": "default"
}
Пример 5 - генерировать токены в пространствах имен по меткам и по конкретным именам:
{
  "allowed_kubernetes_namespaces": "starvault-system,testing",
  "allowed_kubernetes_namespace_selector": "'{'matchLabels':{'stage':'prod','sa-generator':'starvault'}}",
  "service_account_name": "default"
}

Здесь токен можно сгенерировать для любого пространства имен, которое содержит указанные метки или называется starvault-system или testing.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/kubernetes/roles/default-role

5. Чтение роли

Возвращает ранее настроенную роль.

Метод Путь

GET

/kubernetes/roles/:name

5.1. Параметры

  • name (string: <required>) - название роли.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/kubernetes/role/default-role
Пример ответа:
{
  "data": {
    "additional_metadata": {},
    "allowed_kubernetes_namespaces": [
      "*"
    ],
    "generated_role_rules": "",
    "kubernetes_role_name": "",
    "kubernetes_role_type": "Role",
    "name": "default-role",
    "name_template": "",
    "service_account_name": "default",
    "token_default_ttl": 0,
    "token_max_ttl": 86400
  }
}

6. Получение списка ролей

Выводит все настроенные роли.

Метод Путь

LIST

/kubernetes/roles

GET

/kubernetes/roles?list=true

6.1. Параметры

  • after (string: "") - необязательный параметр для пагинации, начало после которого происходит список.

  • limit (int: 0) - количество возвращаемых записей, по умолчанию - все.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/kubernetes/roles
Пример ответа:
{
  "data": {
    "keys": ["default-role", "prod-role"]
  }
}

7. Удаление роли

Удаляет ранее настроенную роль.

Метод Путь

DELETE

/kubernetes/roles/:role

7.1. Параметры

  • role (string: <required>) - название роли.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/kubernetes/role/default-role

8. Генерация учетных данных

Создаёт токен сервисного аккаунта.

Метод Путь

POST

/kubernetes/creds/:role

8.1. Параметры

  • role (string: <required>) - название роли для генерации учетных данных.

  • kubernetes_namespace (string) - название пространства имен Kubernetes, в котором нужно сгенерировать учетные данные. Опционально, если роль StarVault настроена только на одно пространство, отличное от "*".

  • cluster_role_binding (bool: false) - если true, создаст ClusterRoleBinding для разрешения прав по всему кластеру, а не внутри пространства имен. Требует, чтобы kubernetes_role_type был ClusterRole.

  • ttl (string: "") - TTL для токена сервисного аккаунта Kubernetes, в секундах или формате продолжительности Go, например "1h". Может отличаться по факту из-за лимитов Kubernetes или системных ограничений.

  • audiences (string: "") - строка с целевыми аудиториями, разделенными запятыми. Для примера: "custom-audience-0,custom-audience-1". Если не задано, используется значение по умолчанию из конфигурации кластера.

Пример тела запроса:
{
  "kubernetes_namespace": "default",
  "ttl": "1h"
}
Пример запроса:
$ curl \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/kubernetes/creds/default-role
Пример ответа:
{
  "request_id": "58fefc6c-5195-c17a-94f2-8f889f3df57c",
  "lease_id": "kubernetes/creds/default-role/aWczfcfJ7NKUdiirJrPXIs38",
  "renewable": false,
  "lease_duration": 3600,
  "data": {
    "service_account_name": "default",
    "service_account_namespace": "default",
    "service_account_token": "eyJhbG..."
  }
}