Contact UsGet started
© 2025 Direct Cursus Technology L.L.C.

Getting the Yandex Lockbox secret value on the custom Kubernetes installation side

Written by
Updated at October 10, 2025

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 on Yandex Cloud resources on behalf of 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.

This tutorial shows you as an example how to get the Yandex Lockbox secret value from the Kubernetes side under a Yandex Cloud service account. Similarly, you can perform any action via the Yandex Cloud CLI, API, or Terraform.

Note

This tutorial demonstrates an example of integrating a custom Kubernetes installation with a workload identity federation. See the Managed Service for Kubernetes integration guide in Accessing the Yandex Cloud API from a Managed Service for Kubernetes cluster using an Identity and Access Management workload identity federation

To get the Yandex Lockbox secret value under a Kubernetes account:

  1. Prepare the Kubernetes cluster.
  2. Get your cloud ready.
  3. Configure a scenario in Kubernetes.

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

Prepare the Kubernetes cluster

  1. Create a new Kubernetes cluster or use an existing one.

    Make sure your cluster meets the following requirements:

    • You are using Kubernetes 1.20 or higher.
      Earlier Kubernetes versions use a different ServiceAccount token format incompatible with the instructions provided here.
    • You have configured kube-apiserver to support projection of ServiceAccount tokens.

    Note

    This tutorial applies to both public and private Kubernetes clusters.

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

    apiVersion: v1
kind: ServiceAccount
metadata:
  name: wlif

  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

    You will need the Name and Namespace field values to further configure integration on the Yandex Cloud side.

  5. Create a 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: ycaud

    In the audience field, specify the token recipient, e.g., ycaud.

  6. Apply the manifest:

    kubectl apply -f pod.yaml

  7. Make sure the pod you created has the RUNNING status:

    kubectl get pod test-wlif

    Result:

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

  8. Get URL Issuer for your Kubernetes cluster:

    kubectl get --raw /.well-known/openid-configuration | jq -r .issuer

  9. Create a file with a public key set (JWKS):

    kubectl get --raw /openid/v1/jwks > cluster-jwks.json

Get 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 navigate to the cloud page to create or select a folder for your infrastructure.

Learn more about clouds and folders here.

The infrastructure support costs include:

  1. Fee for storing the secret and requests to the secret (see Yandex Lockbox pricing).
  2. Fee for data storage in a bucket and data operations (see Object Storage pricing).

Upload a file with a public key set to a public bucket

  1. Create a public bucket:

    1. In the management console, select the folder where you want to create a bucket.
    2. Select Object Storage.
    3. In the top panel, click Create bucket.
    4. On the bucket creation page:

      1. Enter the bucket name consistent with the naming conventions.

      2. In the Read objects field, select For all.

      3. Click Create bucket to complete the operation.

  2. Upload the cluster-jwks.json file you created earlier into the bucket:

    1. Go to the new bucket.
    2. In the left-hand panel, select Objects.
    3. Click Upload objects.
    4. In the top panel, click Upload.
    5. In the window that opens, select the cluster-jwks.json file and click Open.
    6. Click Upload.
    7. Refresh the page.

  3. Get a link to the uploaded file:

    1. Click the file name.
    2. Click Get link in the top-right corner.
    3. Copy the link.

Create a workload identity federation

  1. In the management console, select the folder where you want to create a workload identity federation.
  2. In the list of services, select Identity and Access Management.
  3. In the left-hand panel, select Workload identity federations.
  4. Click Create federation.
  5. In the Issuer value (iss) field, enter URL Issuer for your Kubernetes cluster, which you got earlier, e.g., https://kubernetes.default.svc.cluster.local.
  6. In the Acceptable Audience values (AUD) field, enter the token recipient you specified when creating the pod, e.g., ycaud.
  7. In the JWKS address field, enter a link to the cluster-jwks.json file in the bucket.
  8. In the Name field, enter a name for the federation, e.g., test-iam-federation.
  9. Click Create.

Create a custom secret

  1. In the management console, select the folder where you want to create your secret.
  2. In the list of services, select Lockbox.
  3. Click Create secret.
  4. In the Name field, enter a name for the secret: MY_SECRET.
  5. Select Custom Secret type.
  6. In the Key field, enter a non-secret ID, e.g., secret.
  7. In the Value field, enter the confidential data you want to store.
  8. Click Create.

Create a service account.

  1. Create a service account:

    1. In the management console, select the folder where you want to create a service account.
    2. In the list of services, select Identity and Access Management.
    3. Click Create service account.
    4. Enter a name for the service account, e.g., sa-lockbox.
    5. Click Create.

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

    1. On the management console home page, select a folder.
    2. Navigate to the Access bindings tab.
    3. Find the sa-lockbox account in the list and click .
    4. Click Edit roles.
    5. In the dialog that opens, click Add role and select the lockbox.payloadViewer role.

  1. In the management console, select the folder the service account was created in.

  2. In the list of services, select Identity and Access Management.

  3. In the list of service accounts, select sa-lockbox.

  4. Navigate to the Workload identity federations tab.

  5. Click Link to federation.

  6. In the Workload identity federation field, select the federation you created earlier.

  7. In the Subject value (sub) field, specify the external account ID: system:serviceaccount:<namespace>:<account_name>.

    Where:

    • namespace: The Namespace field value in the output of the kubectl describe serviceaccount <account_name> command, e.g., default.
    • account_name: Name of the account you created, e.g., wlif.

  8. Click Link.

Configure a scenario in Kubernetes

  1. Fill in the variables:

    SA_ID="<service_account_ID>"
SECRET_ID="<secret_ID>"

    Where:

    • SA_ID: Service account ID.
    • SECRET_ID: Custom secret ID.

  2. Get the Kubernetes service account token:

    SA_TOKEN=`kubectl exec -it test-wlif -- cat /var/run/secrets/tokens/sa-token`

  3. Exchange the Kubernetes service account token for the IAM token of the Yandex Cloud service account:

    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')

  4. Request the secret via the API using the Yandex Cloud IAM token:

    SECRET_DATA=$(curl -sH "Authorization: Bearer ${IAMTOKEN}" https://payload.lockbox.api.cloud.yandex.net/lockbox/v1/secrets/$SECRET_ID/payload)
echo ${SECRET_DATA}

    Result:

    { "entries": [ { "key": "secret", "textValue": "67cH2£?pO********" } ], "versionId": "e6q8isknpcp7********" }

Delete the resources you created

Some resources are not free of charge. Delete the resources you no longer need to avoid paying for them:

See also

Previous
GitLab
Next
Managed Service for Kubernetes