Accessing the Yandex Cloud API from a Managed Service for Kubernetes cluster using a workload identity federation in Identity and Access Management

Managed Service for Kubernetes supports integration with Identity and Access Management workload identity federations.

Workload identity federations allow you to configure a link between external systems and Yandex Cloud via the OpenID Connect (OIDC) protocol. This allows external systems to perform actions with Yandex Cloud resources under IAM service accounts without using authorized keys. This is a more secure method that minimizes the risk of credential leakage and the possibility of unauthorized access.

When this option is enabled, Managed Service for Kubernetes automatically creates an OIDC provider for the specific cluster and provides the following parameters for integration with workload identity federations:

• Issuer URL.
• JWKS key set URL.

This tutorial exemplifies getting the value of a Yandex Lockbox secret from a Managed Service for Kubernetes using an Identity and Access Management service account.

Similarly, you can perform any action via the Yandex Cloud CLI, Terraform, an SDK, or the API.

To configure access to a Yandex Lockbox secret from a Managed Service for Kubernetes cluster via the Yandex Cloud API using a workload identity federation:

1. Get your cloud ready.
2. Configure the Managed Service for Kubernetes cluster.
3. Create a workload identity federation.
4. Set up an IAM service account.
5. Set up an Kubernetes service account.
6. Link the IAM service account to the federation.
7. Create a Yandex Lockbox secret.
8. Test the integration.

If you no longer need the resources you created, delete them.

Get your cloud readyGet your cloud ready

Sign up for Yandex Cloud and create a billing account:

1. Navigate to the management console and log in to Yandex Cloud or create a new account.
2. On the Yandex Cloud Billing page, make sure you have a billing account linked and it has the ACTIVE or TRIAL_ACTIVE status. If you do not have a billing account, create one and link a cloud to it.

If you have an active billing account, you can create or select a folder for your infrastructure on the cloud page.

Learn more about clouds and folders here.

Required paid resourcesRequired paid resources

The infrastructure support cost includes:

• Fee for computing resources and disks for Managed Service for Kubernetes cluster nodes (see Yandex Compute Cloud pricing).
• Fee for using the Managed Service for Kubernetes master and outgoing traffic (see Managed Service for Kubernetes pricing).
• Fee for a Managed Service for Kubernetes cluster's public IP addresses (see Yandex Virtual Private Cloud pricing).
• Fee for storing the secret and requests to it (see Yandex Lockbox pricing).

Set up a Managed Service for Kubernetes clusterSet up a Managed Service for Kubernetes cluster

1. If you do not have a Managed Service for Kubernetes cluster yet:

   1. Create a cluster.

      Tip

      To use the yc-metadata-server DaemonSet controller on nodes for automatic exchange of Kubernetes service account tokens for an IAM token, create a cluster in the RAPID release channel.

      Other release channels support manual exchange of Kubernetes service account tokens for an IAM token.

   2. Create a node group.

   3. Set up security groups for the cluster and node group.

2. To use the Yandex Cloud API, your cluster nodes must have internet access. Make sure your cluster nodes have public IP addresses assigned to them or the subnet they reside in has a configured NAT gateway or NAT instance. Also make sure the security group rules allow unrestricted outgoing traffic for your cluster nodes.

3. Set up integration with a workload identity federation for the cluster and node group:

   Management console

   CLI

   Terraform

   API

   1. In the management console, select the folder with your cluster.
   2. Go to Managed Service for Kubernetes.
   3. Click next to the cluster and select Edit.
   4. Enable the workload identity federation in the Identity and access management field.
   5. Click Save.
   6. Under Identity and access management on the cluster overview page, copy the Issuer URL and JWKS key set URL values. You will need them to complete the integration.
   7. Navigate to the Node group tab.
   8. Click next to the node group and select Edit.
   9. Enable the workload identity federation in the Identity and access management field.
   10. Click Save.

   If you do not have the Yandex Cloud CLI yet, install and initialize it.

   The folder used by default is the one specified when creating the CLI profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command using the --folder-name or --folder-id options.

   1. Enable support for integration with workload identity federation in the cluster:

      yc managed-kubernetes cluster update \
        --id <cluster_ID> \
        --enable-workload-identity-federation
      

      Result:

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

      Copy the workload_identity_federation.issuer and workload_identity_federation.jwks_uri values. You will need them to complete the integration.

   2. Enable support for integration with workload identity federation in the node group:

      yc managed-kubernetes node-group update \
        --id <node_group_ID> \
        --enable-workload-identity-federation
      

      Result:

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

   With Terraform, you can quickly create a cloud infrastructure in Yandex Cloud and manage it using configuration files. These files store the infrastructure description written in HashiCorp Configuration Language (HCL). If you change the configuration files, Terraform automatically detects which part of your configuration is already deployed, and what should be added or removed.

   Terraform is distributed under the Business Source License. The Yandex Cloud provider for Terraform is distributed under the MPL-2.0 license.

   For more information about the provider resources, see the relevant documentation on the Terraform website or its mirror.

   If you do not have Terraform yet, install it and configure the Yandex Cloud provider.

   1. Add the workload_identity_federation section to the cluster manifest in the Terraform configuration file:

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

   2. Add the workload_identity_federation section to the node group manifest in the Terraform configuration file:

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

   3. Make sure the configuration files are correct.

      1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.

      2. Run this command:

         terraform validate
         

         Terraform will show any errors found in your configuration files.

   4. Confirm updating the resources.

      1. Run this command to view the planned changes:

         terraform plan
         

         If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.

      2. If everything looks correct, apply the changes:

         1. Run this command:

            terraform apply
            

         2. Confirm updating the resources.

         3. Wait for the operation to complete.

   5. Get the issuer URL (issuer) and the JWKS keyset URL (jwks_uri) to configure the workload identity federation using the Terraform yandex_kubernetes_cluster data source.

      You can aslo find out these parameters in the management console, using the CLI or API.

   1. Use the update REST API method for the Cluster resource or the ClusterService/Update gRPC API call.

      Note

      Below, see parameters for the REST API request body. To specify a parameter in a gRPC API call, convert its name from lower CamelCase to snake_case, e.g., minResourcePresetId becomes min_resource_preset_id.

      Provide the following in the request:

      • Cluster ID in the clusterId parameter.

      • updateMask set to workloadIdentityFederation.enabled.

        Warning

        The API method will assign default values to all the parameters of the object you are modifying unless you explicitly provide them in your request. To avoid this, list the settings you want to change in the updateMask parameter as a single comma-separated string.

      • workloadIdentityFederation set to "enabled": "true".

      Copy the workloadIdentityFederation.issuer and workloadIdentityFederation.jwksUri values from the response. You will need them later.

   2. Use the update REST API method for the NodeGroup resource or the NodeGroupService/Update gRPC API call.

      Provide the following in the request:

      • Node group ID in the nodeGroupId parameter.
      • updateMask set to workloadIdentityFederation.enabled.
      • workloadIdentityFederation set to "enabled": "true".

Create a workload identity federationCreate a workload identity federation

yc iam workload-identity oidc federation create \
  --name <federation_name> \
  --issuer "<issuer_URL>" \
  --audiences "<issuer_URL>" \
  --jwks-url "<JWKS_URL>"

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

Set up an IAM service accountSet up an IAM service account

1. Create a service account named IAM:

   Management console

   CLI

   Terraform

   API

   1. In the management console, select the folder with the Yandex Lockbox secret.
   2. Go to Identity and Access Management.
   3. Click Create service account.
   4. Specify the service account name, e.g., sa-lockbox.
   5. Click Create.
   6. Select the service account you created and save its ID, as you will need it later.

   Run this command:

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

   Result:

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

   Save the IAM service account ID for later use.

   1. In the configuration file, describe the resources you want to create:

      resource "yandex_iam_service_account" "sa" {
        name        = "<service_account_name>"
        folder_id   = "<folder_ID>"
      }
      

      Where:

      • name: Service account name, e.g., sa-lockbox.
      • folder_id: Folder ID.

   2. Make sure the configuration files are correct.

      1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.

      2. Run this command:

         terraform validate
         

         Terraform will show any errors found in your configuration files.

   3. Confirm creating the resources.

      1. Run this command to view the planned changes:

         terraform plan
         

         If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.

      2. If everything looks correct, apply the changes:

         1. Run this command:

            terraform apply
            

         2. Confirm updating the resources.

         3. Wait for the operation to complete.

      Save the IAM service account ID for later use.

   Use the create REST API method for the ServiceAccount resource or the ServiceAccountService/Create gRPC API call.

2. Assign the lockbox.payloadViewer role for the folder to the service account:

   Management console

   CLI

   Terraform

   API

   1. In the management console, select the folder where you created the service account.
   2. Navigate to the Access bindings tab.
   3. Click Configure access.
   4. In the window that opens, select Service accounts.
   5. Select the service account you created earlier.
   6. Click Add role and select the lockbox.payloadViewer role.
   7. Click Save.

   Run this command by specifying the folder and service account IDs:

   yc resource-manager folder add-access-binding <folder_ID> \
     --role lockbox.payloadViewer \
     --subject serviceAccount:<service_account_ID>
   

   1. In the configuration file, describe the resources you want to create:

      resource "yandex_resourcemanager_folder_iam_member" "lockbox" {
        folder_id   = "<folder_ID>"
        role        = "lockbox.payloadViewer"
        member      = "serviceAccount:<service_account_ID>"
      }
      

      Where:

      • folder_id: Folder ID.
      • role: Role being assigned, e.g., lockbox.payloadViewer.
      • member: ID of the service account you are assigning the role to. Use this format: serviceAccount:<service_account_ID>.

   2. Make sure the configuration files are correct.

      1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.

      2. Run this command:

         terraform validate
         

         Terraform will show any errors found in your configuration files.

   3. Confirm creating the resources.

      1. Run this command to view the planned changes:

         terraform plan
         

         If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.

      2. If everything looks correct, apply the changes:

         1. Run this command:

            terraform apply
            

         2. Confirm updating the resources.

         3. Wait for the operation to complete.

   Use the UpdateAccessBindings REST API method for the Folder resource or the FolderService/UpdateAccessBindings gRPC API call.

Set up an Kubernetes service accountSet up an Kubernetes service account

1. Connect to the Managed Service for Kubernetes cluster using kubectl.

2. Create a manifest named service-account.yaml for the Kubernetes service account with the following contents:

   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: wlif
     annotations:
       yandex.cloud/federated-yc-service-account-id: <IAM_service_account_ID>
   

3. Apply the manifest:

   kubectl apply -f service-account.yaml
   

4. To check the ServiceAccount resource you created, run this command:

   kubectl describe serviceaccount wlif
   

   Result:

   Name:                wlif
   Namespace:           default
   ...
   

5. Save the values of the Name and Namespace fields, as you will need them later.

Link the IAM service account to the federationLink the IAM service account to the federation

yc iam workload-identity federated-credential create \
  --service-account-id <IAM_service_account_ID> \
  --federation-id <federation_ID> \
  --external-subject-id "system:serviceaccount:<namespace>:<Kubernetes_service_account_name>"

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

Create a Yandex Lockbox secretCreate a Yandex Lockbox secret

yc lockbox secret create \
  --name <secret_name> \
  --payload "<array_with_secret_contents>" \

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

Test the integrationTest the integration

1. Connect to the Managed Service for Kubernetes cluster using kubectl.

2. Create a test pod manifest named pod.yaml with the following contents:

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

   Where spec:serviceAccountName is the name of the Kubernetes service account you created earlier.

3. Apply the manifest:

   kubectl apply -f pod.yaml
   

4. Make sure the status of the new pod switched to Running:

   kubectl get pod test-wlif
   

   Result:

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

5. Access the container:

   kubectl exec test-wlif -it -- bash
   

6. Install jq:

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

7. Get an IAM token:

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

8. Get the Yandex Lockbox secret:

   curl -sH "Authorization: Bearer ${IAMTOKEN}" \
     "https://payload.lockbox.api.cloud.yandex.net/lockbox/v1/secrets/<secret_ID>/payload"
   

   Result:

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

Manual exchange of a Kubernetes service account token for an IAM tokenManual exchange of a Kubernetes service account token for an IAM token

1. Connect to the Managed Service for Kubernetes cluster using kubectl.

2. Create a test pod manifest named pod.yaml with the following contents:

   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.net/mk8s-oidc/v1/clusters/c49i54tk66ob********
   

   Where:

   • spec:serviceAccountName: Name of the Kubernetes service account you created earlier.
   • spec:volumes:projected:sources:serviceAccountToken:audience: Acceptable Audience values (AUD) value set when creating the federation.

3. Apply the manifest:

   kubectl apply -f pod.yaml
   

4. Make sure the status of the new pod switched to Running:

   kubectl get pod test-wlif
   

   Result:

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

5. Access the container:

   kubectl exec test-wlif -it -- bash
   

6. Set the required variables:

   SA_ID="<IAM_service_account_ID>" && \
   SECRET_ID="<Lockbox_secret_ID>" && \
   SA_TOKEN="$(cat /var/run/secrets/tokens/sa-token)"
   

   Where:

   • SA_ID: IAM service account ID you got earlier.
   • SECRET_ID: Yandex Lockbox secret ID you got earlier.
   • SA_TOKEN: Kubernetes service account token.

7. Install jq:

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

8. Get an IAM token:

   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://auth.yandex.cloud/oauth/token | jq -r '.access_token')
   

9. Get the Yandex Lockbox secret:

   curl -sH "Authorization: Bearer ${IAMTOKEN}" \
     "https://payload.lockbox.api.cloud.yandex.net/lockbox/v1/secrets/${SECRET_ID}/payload"
   

   Result:

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

How to delete the resources you createdHow to delete the resources you created

To stop paying for the resources you created:

• Delete the Yandex Lockbox secret.
• Delete the Managed Service for Kubernetes node group.
• Delete the Managed Service for Kubernetes cluster.

See alsoSee also

• Workload identity federations
• Getting the Yandex Lockbox secret value on the custom Kubernetes installation side