Version 1.16. This version is no longer supported. For information about how to upgrade to version 1.28, see Upgrade clusters in the latest documentation. For more information about supported and unsupported versions, see the Versioning page in the latest documentation.

Role-based access control (RBAC) for VM Runtime on GDC

VM Runtime on GDC manages a wide range of resources related to your VMs. These resources include Google Kubernetes Engine (GKE) Enterprise edition-defined resources, KubeVirt-defined resources, and Kubernetes resources. VM Runtime on GDC uses role-based access control (RBAC) to set and enforce permissions for managed resources. To help you work with these resources and manage your VMs, we've provided four pre-configured ClusterRoles:

kubevm.admin
kubevm.edit
kubevm.view
kubevm.cluster.view

These built-in roles provide a generalized access model on the custom resources related to VM Runtime on GDC. Each role has pre-established permissions to operate on the resources. This document provides information about resources VM Runtime on GDC manages so that cluster administrators can customize their own access model.

Predefined ClusterRoles

This section describes each of the predefined ClusterRoles. These ClusterRoles are only available when VM Runtime on GDC is enabled:

When VM Runtime on GDC is enabled, the four predefined ClusterRoles are automatically created.
When VM Runtime on GDC is disabled, the four predefined ClusterRoles are deleted.

The following table lists the cluster roles and their related permissions:

Cluster role	Description	Access verbs
`kubevm.admin`	Grants full access to all Google Kubernetes Engine (GKE) Enterprise edition resources.	`get` `list` `watch` `delete` `create` `update` `patch` `deletecollection`
`kubevm.edit`	Grants read/write access to all Google Kubernetes Engine (GKE) Enterprise edition resources.	`get` `list` `watch` `delete` `create` `update` `patch`
`kubevm.view`	Grants read access to all Google Kubernetes Engine (GKE) Enterprise edition resources.	`get` `list` `watch`
`kubevm.cluster.view`	Grants read access to cluster-wise resources. This cluster role is necessary when the edit/view role is bound to a namespace while access to cluster-wise resources is needed.	`get` `list` `watch`

Aggregated ClusterRoles

The kubevm.admin, kubevm.view, and kubevm.edit ClusterRoles aren't used directly. Instead, these three roles are aggregated to Kubernetes default admin, view, and edit ClusterRoles respectively. This aggregation extends the default Kubernetes roles so they can be used to manage Google Kubernetes Engine (GKE) Enterprise edition resources. With aggregated ClusterRoles, you can use Kubernetes default roles to manage access to Google Kubernetes Engine (GKE) Enterprise edition resources or create your own roles based on the predefined ClusterRoles.

Example aggregation label

The kubevm.edit ClusterRole has the label rbac.authorization.k8s.io/aggregate-to-edit: "true", which aggregates it to the Kubernetes edit ClusterRole. The permissions in the kubevm.edit ClusterRole are granted to the Kubernetes default edit role. The kubevm.admin and the kubevm.view ClusterRoles are aggregated similarly with aggregate-to-admin or aggregate-to-view annotations.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
    name: kubevm.edit
    labels:
      kubevm: kubevm.edit
      rbac.authorization.k8s.io/aggregate-to-edit: "true"
...

Typical User Scenarios

The following sections describe how to use RoleBinding and ClusterRoleBinding to grant the permissions specified in the predefined ClusterRoles to a user or set of users.

Cluster admin

To grant admin permissions to a user or set of users, create a ClusterRoleBinding with the Kubernetes default admin ClusterRole.

Example ClusterRoleBinding

The following admin-charlie example ClusterRoleBinding gives user charlie admin permissions. The ClusterRoleBinding uses permissions from the default Kubernetes admin ClusterRole, which includes permissions from the predefined kubevm.admin ClusterRole through aggregation.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: admin-charlie
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: admin
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: User
  name: charlie

Cluster viewer

To grant viewer permissions to a user or set of users, create a ClusterRoleBinding with the Kubernetes default view ClusterRole. See Example ClusterRoleBinding for a similar ClusterRoleBinding example.

Cluster editor

To grant editor permissions to a user or set of users, create a ClusterRoleBinding with the Kubernetes default edit ClusterRole. See Example ClusterRoleBinding for a similar ClusterRoleBinding example.

Namespaced editor

To grant namespaced editor permissions to a user or set of users, you need to create two separate bindings:

Create a RoleBinding on the namespace and reference the default Kubernetes edit ClusterRole.
Create a ClusterRoleBinding that references the predefined kubevm.cluster.view ClusterRole. This ClusterRoleBinding is needed, because some resources, such as virtualmachinetypes and storageclasses, aren't namespaced.

Role binding examples (namespaced editor)

The following RoleBinding and ClusterRoleBinding examples give user charlie editor permissions for resources in the default namespace:

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: edit-charlie
  namespace: default
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: edit
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: User
  name: charlie

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: kubevm-cluster-view-charlie
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: kubevm.cluster.view
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: User
  name: charlie

Namespaced viewer

To grant namespaced viewer permissions to a user or set of users, you need to create two separate bindings:

Create a RoleBinding on the namespace and reference the default Kubernetes view ClusterRole.
Create a ClusterRoleBinding that references the predefined kubevm.cluster.view ClusterRole.

See Role binding examples (namespaced editor) for similar RoleBinding and ClusterRoleBinding examples.

Resources used by VM Runtime on GDC

The following sections contain tables of resources used by VM Runtime on GDC. These sections are for informational purposes only. If you plan to use predefined roles in the typical user scenarios described in the preceding sections, there's no specific use for this information.

If, however, you don't want to use the predefined roles, you can use this resource information to create your own, customized roles.

Google Kubernetes Engine (GKE) Enterprise edition-defined resources

The predefined ClusterRoles focus on access to Google Kubernetes Engine (GKE) Enterprise edition-defined resources. The following table lists the Google Kubernetes Engine (GKE) Enterprise edition resources and the access permissions granted by each of the predefined ClusterRoles.

Resource	Generated	Cluster-wise	`kubevm.admin`	`kubevm.view`	`kubevm.edit`	`kubevm.cluster.view`
`virtualmachineaccessrequests`	–	–	Full	Read	Read/Write	–
`virtualmachinedisks`	–	–	Full	Read	Read/Write	–
`virtualmachines`	–	–	Full	Read	Read/Write	–
`gpuallocations`	–	–	Full	Read	Read/Write	–
`guestenvironmentdata`	Yes	–	Full	Read	Read/Write	–
`vmruntimes`	–	Yes	Full	Read	Read/Write	Read
`virtualmachinetypes`	–	Yes	Full	Read	Read/Write	Read
`vmhighavailabilitypolicies`	–	Yes	Full	Read	Read/Write	Read
`networkinterfaces`	Yes	–	Full	Read	Read/Write	–
`networks`	–	Yes	Full	Read	Read/Write	Read

KubeVirt resources

VM Runtime on GDC is based on the KubeVirt open source project. By default, the permissions for the KubeVirt resources are automatically aggregated to the default Kubernetes roles, similar to the Google Kubernetes Engine (GKE) Enterprise edition-managed resources. Use the resource information in the following table if you want to create your own, customized roles:

Resource	Generated	Cluster-wise
`virtualmachineinstances`/console	–	–
`virtualmachineinstances`/vnc	–	–
`virtualmachineinstances`/portforward	–	–
`virtualmachineinstances`/start	–	–
`virtualmachineinstances`/stop	–	–
`virtualmachineinstances`/restart	–	–
`virtualmachines`	Yes	–
`virtualmachineinstances`	Yes	–
`datavolumes`	–	–
`storageprofiles`	–	Yes
`cdiconfigs`	–	Yes

Kubernetes resources

When you work with VM Runtime on GDC and VMs, you may need to manage access to the following Kubernetes resources. Use the resource information in the following table if you want to create your own, customized roles:

Resource	Generated	Cluster-wise
`pods`	Yes	–
`services`	–	–
`persistentvolumeclaims`	–	–
`secrets`	–	–
`nodes`	–	Yes
`storageclasses`	–	Yes
`configmaps`	–	–

ClusterRole YAML examples

You can retrieve YAML for the ClusterRoles with the following kubectl command:

kubectl get ClusterRole CLUSTERROLE_NAME -o yaml --kubeconfig KUBECONFIG_PATH

Replace the following:

CLUSTERROLE_NAME: the name of the ClusterRole, such as kubevm.cluster.view.
KUBECONFIG_PATH: the path to the kubeconfig file for the cluster.

Here are examples of the command output for each of the four predefined ClusterRoles:

kubevm.admin

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  creationTimestamp: "2022-10-11T21:10:31Z"
  labels:
    kubevm: kubevm.admin
    rbac.authorization.k8s.io/aggregate-to-admin: "true"
  name: kubevm.admin
  resourceVersion: "16654950"
  uid: 3296c279-6e85-4ea6-b250-548bf0c3e935
rules:
- apiGroups:
  - vm.cluster.gke.io
  resources:
  - virtualmachineaccessrequests
  - virtualmachinedisks
  - virtualmachines
  - gpuallocations
  - guestenvironmentdata
  - vmruntimes
  - virtualmachinetypes
  - vmhighavailabilitypolicies
  verbs:
  - get
  - delete
  - create
  - update
  - patch
  - list
  - watch
  - deletecollection
- apiGroups:
  - networking.gke.io
  resources:
  - networkinterfaces
  - networks
  verbs:
  - get
  - delete
  - create
  - update
  - patch
  - list
  - watch
  - deletecollection

kubevm.edit

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  creationTimestamp: "2022-10-11T21:10:31Z"
  labels:
    kubevm: kubevm.edit
    rbac.authorization.k8s.io/aggregate-to-edit: "true"
  name: kubevm.edit
  resourceVersion: "16654951"
  uid: 237bf9ae-b2c8-4303-94dc-e6425a2df331
rules:
- apiGroups:
  - vm.cluster.gke.io
  resources:
  - virtualmachineaccessrequests
  - virtualmachinedisks
  - virtualmachines
  - gpuallocations
  - guestenvironmentdata
  - vmruntimes
  - virtualmachinetypes
  - vmhighavailabilitypolicies
  verbs:
  - get
  - delete
  - create
  - update
  - patch
  - list
  - watch
- apiGroups:
  - networking.gke.io
  resources:
  - networkinterfaces
  - networks
  verbs:
  - get
  - delete
  - create
  - update
  - patch
  - list
  - watch

kubevm.view

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  creationTimestamp: "2022-10-11T21:10:31Z"
  labels:
    kubevm: kubevm.view
    rbac.authorization.k8s.io/aggregate-to-view: "true"
  name: kubevm.view
  resourceVersion: "16654953"
  uid: b5b54e2d-0097-4698-abbd-aeac212d0a34
rules:
- apiGroups:
  - vm.cluster.gke.io
  resources:
  - virtualmachineaccessrequests
  - virtualmachinedisks
  - virtualmachines
  - gpuallocations
  - guestenvironmentdata
  - vmruntimes
  - virtualmachinetypes
  - vmhighavailabilitypolicies
  verbs:
  - get
  - list
  - watch
- apiGroups:
  - networking.gke.io
  resources:
  - networkinterfaces
  - networks
  verbs:
  - get
  - list
  - watch

kubevm.cluster.view

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  creationTimestamp: "2022-10-11T21:10:31Z"
  labels:
    kubevm: kubevm.cluster.view
  name: kubevm.cluster.view
  resourceVersion: "16654956"
  uid: b25dde64-67da-488b-81d2-1a08f9a4a7c1
rules:
- apiGroups:
  - vm.cluster.gke.io
  resources:
  - vmruntimes
  - virtualmachinetypes
  - vmhighavailabilitypolicies
  verbs:
  - get
  - list
  - watch
- apiGroups:
  - networking.gke.io
  resources:
  - networks
  verbs:
  - get
  - list
  - watch