Managing access to a Managed Service for Kubernetes cluster

Written by

Yandex Cloud

Improved by

ilya

Updated at October 6, 2026

View in Markdown

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 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 specify a different folder for any command using --folder-name or --folder-id.

If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

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 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, e.g., k8s.cluster-api.editor.

--subject: Subject getting the role.

Here is an example:

serviceAccount:aje6p030************
userAccount:aje8tj79************
system:allAuthenticatedUsers

Subject designations

To indicate a subject, use the --subject parameter in <subject_type>:<ID> format. For some subject types, the Yandex Cloud CLI provides separate parameters instead of --subject, where you only need to specify the subject name or ID without the type. Possible subject designations and matching CLI parameters:

Subject type	Subject designation	Yandex Cloud CLI parameter
`userAccount`	`userAccount:<user_ID>`	`--user-account-id` or `--user-yandex-login`
`serviceAccount`	`serviceAccount:<service_account_ID>`	`--service-account-id` or `--service-account-name`
`federatedUser`	`federatedUser:<user_ID>`	`--user-account-id`
`group`	`group:<group_ID>`	`--group-members`
`system`	`system:allAuthenticatedUsers` (`All authenticated users` group)	`--all-authenticated-users`
	`system:allUsers` (`All users` group)	—
	`system:group:organization:<organization_ID>:users` (`All users in organization X` group)	`--organization-users`
	`system:group:federation:<federation_ID>:users` (`All users in federation N` group)	`--federation-users`
	`system:group:userpool:<pool_ID>:users` (`All users in userpool P` group)	—

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 on how to create such a 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, e.g., k8s.cluster-api.editor.

member: Subject getting the role.

Here is an example:

serviceAccount:${yandex_iam_service_account.k8s_sa.id}
userAccount:ajerq94v************
system:allAuthenticatedUsers

Subject designations

To indicate a subject, use a combination of its type and unique ID, i.e., <subject_type>:<ID>. Here is how you can designate a subject:

Subject type	Subject designation
`userAccount`	`userAccount:<user_ID>`
`serviceAccount`	`serviceAccount:<service_account_ID>`
`federatedUser`	`federatedUser:<user_ID>`
`group`	`group:<group_ID>`
`system`	`system:allAuthenticatedUsers` (`All authenticated users` group)
	`system:allUsers` (`All users` group)
	`system:group:organization:<organization_ID>:users` (`All users in organization X` group)
	`system:group:federation:<federation_ID>:users` (`All users in federation N` group)
	`system:group:userpool:<pool_ID>:users` (`All users in userpool P` group)

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 resource changes.
1. Run this command to view the intended 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 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, e.g., k8s.cluster-api.editor.

subject: Subject getting the role.

Here is an example:

serviceAccount:aje6p030************
userAccount:aje8tj79************
system:allAuthenticatedUsers

Subject designations

Subject type	Subject designation	Yandex Cloud CLI parameter
`userAccount`	`userAccount:<user_ID>`	`--user-account-id` or `--user-yandex-login`
`serviceAccount`	`serviceAccount:<service_account_ID>`	`--service-account-id` or `--service-account-name`
`federatedUser`	`federatedUser:<user_ID>`	`--user-account-id`
`group`	`group:<group_ID>`	`--group-members`
`system`	`system:allAuthenticatedUsers` (`All authenticated users` group)	`--all-authenticated-users`
	`system:allUsers` (`All users` group)	—
	`system:group:organization:<organization_ID>:users` (`All users in organization X` group)	`--organization-users`
	`system:group:federation:<federation_ID>:users` (`All users in federation N` group)	`--federation-users`
	`system:group:userpool:<pool_ID>:users` (`All users in userpool P` group)	—

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 with the infrastructure plan.

To learn 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, e.g., k8s.cluster-api.editor.

member: Subject getting the role.

Here is an example:

serviceAccount:${yandex_iam_service_account.k8s_sa.id}
userAccount:ajerq94v************
system:allAuthenticatedUsers

Subject designations

To indicate a subject, use a combination of its type and unique ID, i.e., <subject_type>:<ID>. Here is how you can designate a subject:

Subject type	Subject designation
`userAccount`	`userAccount:<user_ID>`
`serviceAccount`	`serviceAccount:<service_account_ID>`
`federatedUser`	`federatedUser:<user_ID>`
`group`	`group:<group_ID>`
`system`	`system:allAuthenticatedUsers` (`All authenticated users` group)
	`system:allUsers` (`All users` group)
	`system:group:organization:<organization_ID>:users` (`All users in organization X` group)
	`system:group:federation:<federation_ID>:users` (`All users in federation N` group)
	`system:group:userpool:<pool_ID>:users` (`All users in userpool P` group)

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 resource changes.
1. Run this command to view the intended 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 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: Subject to revoke the role from.

Here is an example:

serviceAccount:aje6p030************
userAccount:aje8tj79************
system:allAuthenticatedUsers

Subject designations

Subject type	Subject designation	Yandex Cloud CLI parameter
`userAccount`	`userAccount:<user_ID>`	`--user-account-id` or `--user-yandex-login`
`serviceAccount`	`serviceAccount:<service_account_ID>`	`--service-account-id` or `--service-account-name`
`federatedUser`	`federatedUser:<user_ID>`	`--user-account-id`
`group`	`group:<group_ID>`	`--group-members`
`system`	`system:allAuthenticatedUsers` (`All authenticated users` group)	`--all-authenticated-users`
	`system:allUsers` (`All users` group)	—
	`system:group:organization:<organization_ID>:users` (`All users in organization X` group)	`--organization-users`
	`system:group:federation:<federation_ID>:users` (`All users in federation N` group)	`--federation-users`
	`system:group:userpool:<pool_ID>:users` (`All users in userpool P` group)	—

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 with the infrastructure plan.

For more on how to create such a 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 resource changes.
1. Run this command to view the intended 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 with the infrastructure plan.
  
  To learn 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 resource changes.
  1. Run this command to view the intended 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 access to a Managed Service for Kubernetes cluster

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