Доступ к API Yandex Cloud из кластера Managed Service for Kubernetes с помощью федерации сервисных аккаунтов Identity and Access Management

В Managed Service for Kubernetes реализована интеграция с федерациями сервисных аккаунтов Identity and Access Management.

Федерации сервисных аккаунтов (Workload Identity Federation) позволяют настроить связь между внешними системами и Yandex Cloud по протоколу OpenID Connect (OIDC). За счет этого внешние системы могут выполнять действия с ресурсами Yandex Cloud от имени сервисных аккаунтов IAM без использования авторизованных ключей. Это более безопасный способ, минимизирующий риск утечки учетных данных и возможность несанкционированного доступа.

При включении опции Managed Service for Kubernetes автоматически создает для конкретного кластера OIDC-провайдер и предоставляет следующие параметры для интеграции с федерациями сервисных аккаунтов:

• URL эмитента.
• URL набора ключей JWKS.

В этом руководстве для примера показано, как получить значение секрета Yandex Lockbox со стороны кластера Managed Service for Kubernetes от имени сервисного аккаунта Identity and Access Management.

Аналогичным образом можно выполнить любое действие через Yandex Cloud CLI, Terraform, SDK или API.

Чтобы с помощью федерации сервисных аккаунтов настроить доступ к секрету Yandex Lockbox из кластера Managed Service for Kubernetes через API Yandex Cloud:

1. Подготовьте облако к работе.
2. Настройте кластер Managed Service for Kubernetes.
3. Создайте федерацию сервисных аккаунтов.
4. Подготовьте сервисный аккаунт IAM.
5. Подготовьте сервисный аккаунт Kubernetes.
6. Привяжите сервисный аккаунт IAM к федерации.
7. Создайте секрет Yandex Lockbox.
8. Проверьте работу интеграции.

Если созданные ресурсы вам больше не нужны, удалите их.

Подготовьте облако к работеПодготовьте облако к работе

Зарегистрируйтесь в Yandex Cloud и создайте платежный аккаунт:

1. Перейдите в консоль управления, затем войдите в Yandex Cloud или зарегистрируйтесь.
2. На странице Yandex Cloud Billing убедитесь, что у вас подключен платежный аккаунт, и он находится в статусе ACTIVE или TRIAL_ACTIVE. Если платежного аккаунта нет, создайте его и привяжите к нему облако.

Если у вас есть активный платежный аккаунт, вы можете создать или выбрать каталог, в котором будет работать ваша инфраструктура, на странице облака.

Подробнее об облаках и каталогах.

Необходимые платные ресурсыНеобходимые платные ресурсы

В стоимость поддержки инфраструктуры входят:

• Плата за вычислительные ресурсы и диски узлов кластера Managed Service for Kubernetes (см. тарифы Yandex Compute Cloud).
• Плата за использование мастера Managed Service for Kubernetes и исходящий трафик (см. тарифы Managed Service for Kubernetes).
• Плата за публичные IP-адреса кластера Managed Service for Kubernetes (см. тарифы Yandex Virtual Private Cloud).
• Плата за хранение секрета и запросы к нему (см. тарифы Yandex Lockbox).

Настройте кластер Managed Service for KubernetesНастройте кластер Managed Service for Kubernetes

1. Если у вас еще нет кластера Managed Service for Kubernetes:

   1. Создайте кластер.

      Совет

      Чтобы использовать контроллер DaemonSet yc-metadata-server на узлах для автоматического обмена токенов сервисного аккаунта Kubernetes на IAM-токен, создайте кластер в релизном канале RAPID.

      Для остальных релизных каналов доступен ручной обмен токенов сервисного аккаунта Kubernetes на IAM-токен.

   2. Создайте группу узлов.

   3. Настройте группы безопасности для кластера и группы узлов.

2. Для доступа к API Yandex Cloud у узлов кластера должен быть доступ в интернет. Убедитесь, что узлам кластера назначены публичные IP-адреса, или в подсети, где размещаются узлы, настроен NAT-шлюз или NAT-инстанс. Также убедитесь, что правилами группы безопасности разрешен весь исходящий трафик для узлов кластера.

3. Настройте интеграцию с федерацией сервисных аккаунтов для кластера и группы узлов:

   Консоль управления

   CLI

   Terraform

   API

   1. В консоли управления выберите каталог, в котором размещен кластер.
   2. Перейдите в сервис Managed Service for Kubernetes.
   3. Напротив кластера нажмите и выберите Редактировать.
   4. В поле Управление идентификацией и доступом включите федерацию сервисных аккаунтов.
   5. Нажмите Сохранить.
   6. На обзорной странице кластера в блоке Управление идентификацией и доступом скопируйте значения параметров URL эмитента и URL набора ключей JWKS. Они понадобятся для дальнейшей интеграции.
   7. Перейдите на вкладку Группы узлов.
   8. Напротив группы узлов нажмите и выберите Редактировать.
   9. В поле Управление идентификацией и доступом включите федерацию сервисных аккаунтов.
   10. Нажмите Сохранить.

   Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), установите и инициализируйте его.

   По умолчанию используется каталог, указанный при создании профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду yc config set folder-id <идентификатор_каталога>. Также для любой команды вы можете указать другой каталог с помощью параметров --folder-name или --folder-id.

   1. Включите поддержку интеграции с федерацией сервисных аккаунтов в кластере:

      yc managed-kubernetes cluster update \
        --id <идентификатор_кластера> \
        --enable-workload-identity-federation
      

      Результат:

      done (3s)
      ...
      workload_identity_federation:
        enabled: true
        issuer: https://storage.yandexcloud.kz/mk8s-oidc/v1/clusters/catc7433801j********
        jwks_uri: https://storage.yandexcloud.kz/mk8s-oidc/v1/clusters/catc7433801j********/jwks.json
      

      Скопируйте значения параметров workload_identity_federation.issuer и workload_identity_federation.jwks_uri. Они понадобятся для дальнейшей интеграции.

   2. Включите поддержку интеграции с федерацией сервисных аккаунтов в группе узлов:

      yc managed-kubernetes node-group update \
        --id <идентификатор_группы_узлов> \
        --enable-workload-identity-federation
      

      Результат:

      done (12s)
      ...
      workload_identity_federation:
        enabled: true
      

   Terraform позволяет быстро создать облачную инфраструктуру в Yandex Cloud и управлять ею с помощью файлов конфигураций. В файлах конфигураций хранится описание инфраструктуры на языке HCL (HashiCorp Configuration Language). При изменении файлов конфигураций Terraform автоматически определяет, какая часть вашей конфигурации уже развернута, что следует добавить или удалить.

   Terraform распространяется под лицензией Business Source License, а провайдер Yandex Cloud для Terraform — под лицензией MPL-2.0.

   Подробную информацию о ресурсах провайдера смотрите в документации на сайте Terraform или в зеркале.

   Если у вас еще нет Terraform, установите его и настройте провайдер Yandex Cloud.

   1. В конфигурационном файле Terraform добавьте в манифест кластера блок workload_identity_federation:

      resource "yandex_kubernetes_cluster" "my_cluster" {
      ...
        workload_identity_federation {
          enabled = true
        }
      }
      

   2. В конфигурационном файле Terraform добавьте в манифест группы узлов блок workload_identity_federation:

      resource "yandex_kubernetes_node_group" "my_node_group" {
      ...
        workload_identity_federation {
          enabled = true
        }
      }
      

   3. Проверьте корректность конфигурационных файлов.

      1. В командной строке перейдите в каталог, в котором расположены актуальные конфигурационные файлы Terraform с планом инфраструктуры.

      2. Выполните команду:

         terraform validate
         

         Если в файлах конфигурации есть ошибки, Terraform на них укажет.

   4. Подтвердите изменение ресурсов.

      1. Выполните команду для просмотра планируемых изменений:

         terraform plan
         

         Если конфигурации ресурсов описаны верно, в терминале отобразится список изменяемых ресурсов и их параметров. Это проверочный этап: ресурсы не будут изменены.

      2. Если вас устраивают планируемые изменения, внесите их:

         1. Выполните команду:

            terraform apply
            

         2. Подтвердите изменение ресурсов.

         3. Дождитесь завершения операции.

   5. Получите URL эмитента (issuer) и URL набора ключей JWKS (jwks_uri) для настройки федерации сервисных аккаунтов с помощью источника данных Terraform yandex_kubernetes_cluster.

      Также вы можете узнать эти параметры в консоли управления, с помощью CLI или API.

   1. Воспользуйтесь методом REST API update для ресурса Cluster или вызовом gRPC API ClusterService/Update.

      Примечание

      Ниже перечислены параметры для тела запроса к REST API. Чтобы указать параметр в вызове gRPC API, преобразуйте его имя из lowerCamelCase в snake_case. Например, параметр minResourcePresetId преобразуется в min_resource_preset_id.

      Передайте в запросе:

      • Идентификатор кластера в параметре clusterId.

      • Параметр updateMask со значением workloadIdentityFederation.enabled.

        Важно

        Метод API переопределит все параметры изменяемого объекта, которые не были явно переданы в запросе, на значения по умолчанию. Чтобы избежать этого, перечислите настройки, которые вы хотите изменить, в параметре updateMask (одной строкой через запятую).

      • Параметр workloadIdentityFederation со значением "enabled": "true".

      Скопируйте из ответа значения параметров workloadIdentityFederation.issuer и workloadIdentityFederation.jwksUri. Они понадобятся в дальнейшем.

   2. Воспользуйтесь методом REST API update для ресурса NodeGroup или вызовом gRPC API NodeGroupService/Update.

      Передайте в запросе:

      • Идентификатор группы узлов в параметре nodeGroupId.
      • Параметр updateMask со значением workloadIdentityFederation.enabled.
      • Параметр workloadIdentityFederation со значением "enabled": "true".

Создайте федерацию сервисных аккаунтовСоздайте федерацию сервисных аккаунтов

yc iam workload-identity oidc federation create \
  --name <имя_федерации> \
  --issuer "<URL_эмитента>" \
  --audiences "<URL_эмитента>" \
  --jwks-url "<URL_набора_ключей_JWKS>"

id: aje2c4qv19lf********
name: test-iam-federation
folder_id: b1gfq9pe6rd2********
enabled: true
audiences:
  - https://storage.yandexcloud.kz/mk8s-oidc/v1/clusters/c49i54tk66ob********
issuer: https://storage.yandexcloud.kz/mk8s-oidc/v1/clusters/c49i54tk66ob********
jwks_url: https://storage.yandexcloud.kz/mk8s-oidc/v1/clusters/c49i54tk66ob********/jwks.json
created_at: "2024-12-28T16:04:31.530652473Z"

Подготовьте сервисный аккаунт IAMПодготовьте сервисный аккаунт IAM

1. Создайте сервисный аккаунт IAM:

   Консоль управления

   CLI

   Terraform

   API

   1. В консоли управления выберите каталог, в котором размещен секрет Yandex Lockbox.
   2. Перейдите в сервис Identity and Access Management.
   3. Нажмите Создать сервисный аккаунт.
   4. Введите имя сервисного аккаунта, например sa-lockbox.
   5. Нажмите Создать.
   6. Выберите созданный сервисный аккаунт и сохраните его идентификатор, он понадобится в дальнейшем.

   Выполните команду:

   yc iam service-account create --name sa-lockbox
   

   Результат:

   done (2s)
   id: aje7s96nvmdp********
   folder_id: b1gsm0k26v1l********
   created_at: "2026-03-12T12:16:01Z"
   name: sa-lockbox
   

   Сохраните идентификатор сервисного аккаунта IAM, он понадобится в дальнейшем.

   1. Опишите в конфигурационном файле параметры ресурсов, которые необходимо создать:

      resource "yandex_iam_service_account" "sa" {
        name        = "<имя_сервисного_аккаунта>"
        folder_id   = "<идентификатор_каталога>"
      }
      

      Где:

      • name — имя сервисного аккаунта, например sa-lockbox.
      • folder_id — идентификатор каталога.

   2. Проверьте корректность конфигурационных файлов.

      1. В командной строке перейдите в каталог, в котором расположены актуальные конфигурационные файлы Terraform с планом инфраструктуры.

      2. Выполните команду:

         terraform validate
         

         Если в файлах конфигурации есть ошибки, Terraform на них укажет.

   3. Подтвердите создание ресурсов.

      1. Выполните команду для просмотра планируемых изменений:

         terraform plan
         

         Если конфигурации ресурсов описаны верно, в терминале отобразится список изменяемых ресурсов и их параметров. Это проверочный этап: ресурсы не будут изменены.

      2. Если вас устраивают планируемые изменения, внесите их:

         1. Выполните команду:

            terraform apply
            

         2. Подтвердите изменение ресурсов.

         3. Дождитесь завершения операции.

      Сохраните идентификатор сервисного аккаунта IAM, он понадобится в дальнейшем.

   Воспользуйтесь методом REST API create для ресурса ServiceAccount или вызовом gRPC API ServiceAccountService/Create.

2. Назначьте сервисному аккаунту роль lockbox.payloadViewer на каталог:

   Консоль управления

   CLI

   Terraform

   API

   1. В консоли управления выберите каталог, в котором создан сервисный аккаунт.
   2. Перейдите на вкладку Права доступа.
   3. Нажмите Настроить доступ.
   4. В открывшемся окне выберите раздел Сервисные аккаунты.
   5. Выберите сервисный аккаунт, созданный ранее.
   6. Нажмите Добавить роль и выберите роль lockbox.payloadViewer.
   7. Нажмите Сохранить.

   Выполните команду, указав идентификаторы каталога и сервисного аккаунта:

   yc resource-manager folder add-access-binding <идентификатор_каталога> \
     --role lockbox.payloadViewer \
     --subject serviceAccount:<идентификатор_сервисного_аккаунта>
   

   1. Опишите в конфигурационном файле параметры ресурсов, которые необходимо создать:

      resource "yandex_resourcemanager_folder_iam_member" "lockbox" {
        folder_id   = "<идентификатор_каталога>"
        role        = "lockbox.payloadViewer"
        member      = "serviceAccount:<идентификатор_сервисного_аккаунта>"
      }
      

      Где:

      • folder_id — идентификатор каталога.
      • role — назначаемая роль, например lockbox.payloadViewer.
      • member — идентификатор сервисного аккаунта, которому назначается роль. Указывается в виде serviceAccount:<идентификатор_сервисного_аккаунта>.

   2. Проверьте корректность конфигурационных файлов.

      1. В командной строке перейдите в каталог, в котором расположены актуальные конфигурационные файлы Terraform с планом инфраструктуры.

      2. Выполните команду:

         terraform validate
         

         Если в файлах конфигурации есть ошибки, Terraform на них укажет.

   3. Подтвердите создание ресурсов.

      1. Выполните команду для просмотра планируемых изменений:

         terraform plan
         

         Если конфигурации ресурсов описаны верно, в терминале отобразится список изменяемых ресурсов и их параметров. Это проверочный этап: ресурсы не будут изменены.

      2. Если вас устраивают планируемые изменения, внесите их:

         1. Выполните команду:

            terraform apply
            

         2. Подтвердите изменение ресурсов.

         3. Дождитесь завершения операции.

   Воспользуйтесь методом REST API UpdateAccessBindings для ресурса Folder или вызовом gRPC API FolderService/UpdateAccessBindings.

Подготовьте сервисный аккаунт KubernetesПодготовьте сервисный аккаунт Kubernetes

1. Подключитесь к кластеру Managed Service for Kubernetes с помощью kubectl.

2. Создайте манифест сервисного аккаунта Kubernetes service-account.yaml со следующим содержимым:

   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: wlif
     annotations:
       yandex.cloud/federated-yc-service-account-id: <идентификатор_сервисного_аккаунта_IAM>
   

3. Примените манифест:

   kubectl apply -f service-account.yaml
   

4. Чтобы проверить созданный ресурс ServiceAccount, выполните команду:

   kubectl describe serviceaccount wlif
   

   Результат:

   Name:                wlif
   Namespace:           default
   ...
   

5. Сохраните значения полей Name и Namespace, они понадобятся в дальнейшем.

Привяжите сервисный аккаунт IAM к федерацииПривяжите сервисный аккаунт IAM к федерации

yc iam workload-identity federated-credential create \
  --service-account-id <идентификатор_сервисного_аккаунта_IAM> \
  --federation-id <идентификатор_федерации> \
  --external-subject-id "system:serviceaccount:<пространство_имен>:<имя_сервисного_аккаунта_Kubernetes>"

id: aje401v1sup8********
service_account_id: ajek7v5j65cg********
federation_id: aje2c4qv19lf********
external_subject_id: system:serviceaccount:default:wlif
created_at: "2024-12-28T16:33:47.057632267Z"

Создайте секрет Yandex LockboxСоздайте секрет Yandex Lockbox

yc lockbox secret create \
  --name <имя_секрета> \
  --payload "<массив_с_содержимым_секрета>" \

done (1s)
id: e6qduvprvcon********
folder_id: b1gsm0k26v1l********
created_at: "2026-03-12T13:02:15.543Z"
name: MY_SECRET
status: ACTIVE
current_version:
  id: e6qr13mvsl8t********
  secret_id: e6qduvprvcon********
  created_at: "2026-03-12T13:02:15.543Z"
  status: ACTIVE
  payload_entry_keys:
    - test-secret

Проверьте работу интеграцииПроверьте работу интеграции

1. Подключитесь к кластеру Managed Service for Kubernetes с помощью kubectl.

2. Создайте манифест тестового пода pod.yaml со следующим содержимым:

   apiVersion: v1
   kind: Pod
   metadata:
     name: test-wlif
   spec:
     containers:
       - image: nginx
         name: nginx
     serviceAccountName: wlif
   

   Где spec:serviceAccountName — имя сервисного аккаунта Kubernetes, созданного ранее.

3. Примените манифест:

   kubectl apply -f pod.yaml
   

4. Убедитесь, что созданный под перешел в статус Running:

   kubectl get pod test-wlif
   

   Результат:

   NAME        READY   STATUS    RESTARTS   AGE
   test-wlif   1/1     Running   0          1m
   

5. Войдите в контейнер:

   kubectl exec test-wlif -it -- bash
   

6. Установите вспомогательную утилиту jq:

   apt-get update >/dev/null 2>&1 && apt-get install -y jq >/dev/null 2>&1
   

7. Получите IAM-токен:

   IAMTOKEN=$(curl -s -H 'Metadata-Flavor: Google' \
     http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/token \
     | jq -r '.access_token')
   

8. Получите секрет Yandex Lockbox:

   curl -sH "Authorization: Bearer ${IAMTOKEN}" \
     "https://dpl.lockbox.api.yandexcloud.kz/lockbox/v1/secrets/<идентификатор_секрета>/payload"
   

   Результат:

   {
    "entries": [
     {
      "key": "test-secret",
      "textValue": "hello-world"
     }
    ],
    "versionId": "e6qsqiadrsnh********"
   }
   

Ручной обмен токена сервисного аккаунта Kubernetes на IAM-токенРучной обмен токена сервисного аккаунта Kubernetes на IAM-токен

1. Подключитесь к кластеру Managed Service for Kubernetes с помощью kubectl.

2. Создайте манифест тестового пода pod.yaml со следующим содержимым:

   apiVersion: v1
   kind: Pod
   metadata:
     name: test-wlif
   spec:
     containers:
       - image: nginx
         name: nginx
         volumeMounts:
           - mountPath: /var/run/secrets/tokens
             name: sa-token
     serviceAccountName: wlif
     volumes:
       - name: sa-token
         projected:
           sources:
             - serviceAccountToken:
               path: sa-token
               expirationSeconds: 7200
               audience: https://storage.yandexcloud.kz/mk8s-oidc/v1/clusters/c49i54tk66ob********
   

   Где:

   • spec:serviceAccountName — имя сервисного аккаунта Kubernetes, созданного ранее.
   • spec:volumes:projected:sources:serviceAccountToken:audience — значение Допустимые значения Audience (aud), заданное при создании федерации.

3. Примените манифест:

   kubectl apply -f pod.yaml
   

4. Убедитесь, что созданный под перешел в статус Running:

   kubectl get pod test-wlif
   

   Результат:

   NAME        READY   STATUS    RESTARTS   AGE
   test-wlif   1/1     Running   0          1m
   

5. Войдите в контейнер:

   kubectl exec test-wlif -it -- bash
   

6. Задайте необходимые переменные:

   SA_ID="<идентификатор_сервисного_аккаунта_IAM>" && \
   SECRET_ID="<идентификатор_секрета_Lockbox>" && \
   SA_TOKEN="$(cat /var/run/secrets/tokens/sa-token)"
   

   Где:

   • SA_ID — идентификатор сервисного аккаунта IAM, полученный ранее.
   • SECRET_ID — идентификатор секрета Yandex Lockbox, полученный ранее.
   • SA_TOKEN — токен сервисного аккаунта Kubernetes.

7. Установите вспомогательную утилиту jq:

   apt-get update >/dev/null 2>&1 && apt-get install -y jq >/dev/null 2>&1
   

8. Получите IAM-токен:

   IAMTOKEN=$(curl -sH "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange&requested_token_type=urn:ietf:params:oauth:token-type:access_token&audience=${SA_ID}&subject_token=${SA_TOKEN}&subject_token_type=urn:ietf:params:oauth:token-type:id_token" \
     -X POST https://kz.auth.yandex.cloud/oauth/token | jq -r '.access_token')
   

9. Получите секрет Yandex Lockbox:

   curl -sH "Authorization: Bearer ${IAMTOKEN}" \
     "https://dpl.lockbox.api.yandexcloud.kz/lockbox/v1/secrets/${SECRET_ID}/payload"
   

   Результат:

   {
    "entries": [
     {
      "key": "test-secret",
      "textValue": "hello-world"
     }
    ],
    "versionId": "e6qsqiadrsnh********"
   }
   

Как удалить созданные ресурсыКак удалить созданные ресурсы

Чтобы перестать платить за созданные ресурсы:

• Удалите секрет Yandex Lockbox.
• Удалите группу узлов Managed Service for Kubernetes.
• Удалите кластер Managed Service for Kubernetes.

См. такжеСм. также

• Федерации сервисных аккаунтов
• Получение значения секрета Yandex Lockbox на стороне пользовательской инсталляции Kubernetes