Enabling support for a Yandex Identity and Access Management workload identity federation in a Yandex Managed Service for Kubernetes cluster

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.

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".

See alsoSee also

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