Managing Managed Service for Kubernetes cluster access

Written by

Updated at November 11, 2025

Getting a list of roles assigned for a cluster
Assigning a role
Assigning multiple roles
Revoking a role
Examples
- Granting cluster management access to a service account

You can assign a user or service account a role that grants access to the Kubernetes API of a specific cluster.

This allows you to issue granular roles to various users and service accounts for access to individual clusters.

Warning

Note that besides the role that grants access to the cluster's Kubernetes API, the user also needs a minimum role for viewing folder resources, e.g., k8s.viewer (to view information about all clusters in the folder) or primitive viewer (to view all resources in the folder).

For example, you can assign the k8s.viewer role for a folder and the k8s.cluster-api.editor role to manage Kubernetes resources of a specific cluster. This way, the user can view information about all clusters in the folder but only access the API of a specific cluster.

To manage user view permissions for cluster lists, we recommend using different folders in your cloud.

Getting a list of roles assigned for a cluster

CLI

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

By default, the CLI uses the folder specified when creating the 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 parameter.

To get a list of clusters in the default folder, run this command:
```
yc managed-kubernetes cluster list
```

To get a list of roles assigned for the cluster, run this command:

yc managed-kubernetes cluster list-access-bindings <cluster_name_or_ID>

Assigning a role

CLI

Terraform

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

View the description of the CLI command for assigning a role for a cluster:
```
yc managed-kubernetes cluster add-access-binding --help
```
Use this command to assign a role:
```
yc managed-kubernetes cluster add-access-binding <cluster_name_or_ID> \
  --role <role> \
  --subject <subject_type>:<subject_ID>
```
Where:
- --role: Role being assigned, e.g., k8s.cluster-api.editor.
- --subject: Type and ID of the subject you are assigning the role to, in <subject_type>:<subject_ID> format.
  
  Here is an example:
  - serviceAccount:aje6p030************
  - userAccount:aje8tj79************
  - system:allAuthenticatedUsers
  Possible subject types:
  - userAccount: Yandex account added to Yandex Cloud or an account from a user pool.
  - serviceAccount: Service account created in Yandex Cloud.
  - federatedUser: Account of an identity federation user.
  - group: Yandex Identity Hub user group.
  - system: Public group of users.
    
    The possible values of a subject ID are as follows:
    - allAuthenticatedUsers: All authenticated users.
    - allUsers: Any user. No authentication is required.
  To learn more about subject types, see the Subject a role is assigned to section.

To view a list of roles assigned for the cluster, run this command:

yc managed-kubernetes cluster list-access-bindings <cluster_name_or_ID>

Warning

Do not use the yandex_kubernetes_cluster_iam_member resource to assign roles managed by yandex_kubernetes_cluster_iam_binding.

Open the current configuration file with the Managed Service for Kubernetes cluster description.

For more information about creating this file, see Creating a Managed Service for Kubernetes cluster.
Add a resource description:
```
resource "yandex_kubernetes_cluster_iam_member" "<local_resource_name>" {
  cluster_id = "<cluster_ID>"
  role       = "<role>"
  member     = "<subject_type>:<subject_ID>"
}
```
Where:
- cluster_id: Cluster ID.
- role: Role being assigned, e.g., k8s.cluster-api.editor.
- member: Type and ID of the subject you are assigning the role to, in <subject_type>:<subject_ID> format.
  
  Here is an example:
  - serviceAccount:${yandex_iam_service_account.k8s_sa.id}
  - userAccount:ajerq94v************
  - system:allAuthenticatedUsers
  Possible subject types:
  - userAccount: Yandex account added to Yandex Cloud or an account from a user pool.
  - serviceAccount: Service account created in Yandex Cloud.
  - federatedUser: Account of an identity federation user.
  - group: Yandex Identity Hub user group.
  - system: Public group of users.
    
    The possible values of a subject ID are as follows:
    - allAuthenticatedUsers: All authenticated users.
    - allUsers: Any user. No authentication is required.
  To learn more about subject types, see the Subject a role is assigned to section.
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.
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.
For more information, see this Terraform provider guide.

To view a list of roles assigned for the cluster, run this CLI command:

yc managed-kubernetes cluster list-access-bindings <cluster_name_or_ID>

Assigning multiple roles

CLI

Terraform

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

Alert

The set-access-bindings command deletes all roles assigned for the cluster and assigns new ones.

To view a list of roles assigned for the cluster, run this command:

yc managed-kubernetes cluster list-access-bindings <cluster_name_or_ID>

View the description of the CLI command for assigning roles for a cluster:
```
yc managed-kubernetes cluster set-access-bindings --help
```
To assign roles, run this command:
```
yc managed-kubernetes cluster set-access-bindings <cluster_name_or_ID> \
  --access-binding role=<role_1>,subject=<subject_type>:<subject_1_ID> \
  --access-binding role=<role_2>,subject=<subject_type>:<subject_2_ID>
```
Where --access-binding assigns a role to a subject. You can assign multiple roles at once by describing each of them in a separate --access-binding parameter.
- role: Role being assigned, e.g., k8s.cluster-api.editor.
- subject: Type and ID of the subject you are assigning the role to, in <subject_type>:<subject_ID> format.
  
  Here is an example:
  - serviceAccount:aje6p030************
  - userAccount:aje8tj79************
  - system:allAuthenticatedUsers
  Possible subject types:
  - userAccount: Yandex account added to Yandex Cloud or an account from a user pool.
  - serviceAccount: Service account created in Yandex Cloud.
  - federatedUser: Account of an identity federation user.
  - group: Yandex Identity Hub user group.
  - system: Public group of users.
    
    The possible values of a subject ID are as follows:
    - allAuthenticatedUsers: All authenticated users.
    - allUsers: Any user. No authentication is required.
  To learn more about subject types, see the Subject a role is assigned to section.

Warning

Do not use the yandex_kubernetes_cluster_iam_member resource to assign roles managed by yandex_kubernetes_cluster_iam_binding.

Open the current Terraform configuration file that defines your infrastructure.

For information on how to create this file, see Creating a cluster.
Add resource descriptions:
```
resource "yandex_kubernetes_cluster_iam_member" "<resource_1_local_name>" {
  cluster_id = "<cluster_ID>"
  role       = "<role_1>"
  member     = "<subject_type>:<subject_ID>"
}

resource "yandex_kubernetes_cluster_iam_member" "<resource_2_local_name>" {
  cluster_id = "<cluster_ID>"
  role       = "<role_2>"
  member     = "<subject_type>:<subject_ID>"
}
```
Where:
- cluster_id: Cluster ID.
- role: Role being assigned, e.g., k8s.cluster-api.editor.
- member: Type and ID of the subject you are assigning the role to, in <subject_type>:<subject_ID> format.
  
  Here is an example:
  - serviceAccount:${yandex_iam_service_account.k8s_sa.id}
  - userAccount:ajerq94v************
  - system:allAuthenticatedUsers
  Possible subject types:
  - userAccount: Yandex account added to Yandex Cloud or an account from a user pool.
  - serviceAccount: Service account created in Yandex Cloud.
  - federatedUser: Account of an identity federation user.
  - group: Yandex Identity Hub user group.
  - system: Public group of users.
    
    The possible values of a subject ID are as follows:
    - allAuthenticatedUsers: All authenticated users.
    - allUsers: Any user. No authentication is required.
  To learn more about subject types, see the Subject a role is assigned to section.
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.
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.
For more information, see this Terraform provider guide.

To view a list of roles assigned for the cluster, run this CLI command:

yc managed-kubernetes cluster list-access-bindings <cluster_name_or_ID>

Revoking a role

CLI

Terraform

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

To view a list of roles assigned for the cluster, run this command:

yc managed-kubernetes cluster list-access-bindings <cluster_name_or_ID>

View the description of the CLI command for revoking a role for a cluster:
```
yc managed-kubernetes cluster remove-access-binding --help
```
To revoke a role, run this command:
```
yc managed-kubernetes cluster remove-access-binding <cluster_name_or_ID> \
  --role <role> \
  --subject <subject_type>:<subject_ID>
```
Where:
- --role: Role being revoked, e.g., k8s.cluster-api.editor.
- --subject: Type and ID of the subject the role is assigned to, in <subject_type>:<subject_ID> format.
  
  Here is an example:
  - serviceAccount:aje6p030************
  - userAccount:aje8tj79************
  - system:allAuthenticatedUsers
  Possible subject types:
  - userAccount: Yandex account added to Yandex Cloud or an account from a user pool.
  - serviceAccount: Service account created in Yandex Cloud.
  - federatedUser: Account of an identity federation user.
  - group: Yandex Identity Hub user group.
  - system: Public group of users.
    
    The possible values of a subject ID are as follows:
    - allAuthenticatedUsers: All authenticated users.
    - allUsers: Any user. No authentication is required.
  To learn more about subject types, see the Subject a role is assigned to section.

Warning

Do not use the yandex_kubernetes_cluster_iam_member resource to assign roles managed by yandex_kubernetes_cluster_iam_binding.

Open the current Terraform configuration file that defines your infrastructure.

For information on how to create this file, see Creating a cluster.

Find the description of the resource with the role you want to revoke and delete this description:

resource "yandex_kubernetes_cluster_iam_member" "<local_resource_name>" {
  cluster_id = "<cluster_ID>"
  role       = "<role>"
  member     = "<subject_type>:<subject_ID>"
}

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.
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.
For more information, see this Terraform provider guide.

To view a list of roles assigned for the cluster, run this CLI command:

yc managed-kubernetes cluster list-access-bindings <cluster_name_or_ID>

Examples

Granting cluster management access to a service account

To enable a service account to view information about all Managed Service for Kubernetes clusters in the folder but only modify Kubernetes resources in one specific cluster, assign it the k8s.viewer role for the folder and the k8s.cluster-api.editor role for that cluster:
CLI

Terraform
1. Assign the role for the folder:
  yc resource-manager folder add-access-binding \ --id <folder_ID> \ --role k8s.viewer \ --subject=serviceAccount:<service_account_ID>
2. Assign the roles for the cluster:
  yc managed-kubernetes cluster set-access-bindings <cluster_name_or_ID> \ --access-binding role=k8s.cluster-api.editor,subject=serviceAccount:<service_account_ID>
1. Open the current Terraform configuration file describing your infrastructure.
  
  For information on how to create this file, see Creating a cluster.
2. Add resource descriptions:
  resource "yandex_resourcemanager_folder_iam_member" "k8s-viewer-account-iam" { folder_id = "<folder_ID>" role = "k8s.viewer" member = "serviceAccount:<service_account_ID>" } resource "yandex_kubernetes_cluster_iam_member" "k8s-cluster-api-editor" { cluster_id = "<cluster_ID>" role = "k8s.cluster-api.editor" member = "serviceAccount:<service_account_ID>" }
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:
    
    Run this command:
    
    terraform apply
    
    Confirm updating the resources.
    
    Wait for the operation to complete.

To view a list of roles assigned for the cluster, run this CLI command:

yc managed-kubernetes cluster list-access-bindings <cluster_name_or_ID>

Managing Managed Service for Kubernetes cluster access

Getting a list of roles assigned for a clusterGetting a list of roles assigned for a cluster

Assigning a roleAssigning a role

Assigning multiple rolesAssigning multiple roles

Revoking a roleRevoking a role

ExamplesExamples

Granting cluster management access to a service accountGranting cluster management access to a service account

Was the article helpful?

Getting a list of roles assigned for a cluster

Assigning a role

Assigning multiple roles

Revoking a role

Examples

Granting cluster management access to a service account