From c9867786bdea6239d53c9c8ab829e839358528a7 Mon Sep 17 00:00:00 2001 From: "eric.chiang.m@gmail.com" Date: Tue, 28 Nov 2017 16:52:53 -0800 Subject: [PATCH] rbac: docs for aggregated cluster roles --- docs/admin/authorization/rbac.md | 82 ++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) diff --git a/docs/admin/authorization/rbac.md b/docs/admin/authorization/rbac.md index f387f44456cd3..a50d74240a236 100644 --- a/docs/admin/authorization/rbac.md +++ b/docs/admin/authorization/rbac.md @@ -191,6 +191,76 @@ Because resource names are not present in the URL for create, list, watch, and d those verbs would not be allowed by a rule with resourceNames set, since the resourceNames portion of the rule would not match the request. +### Aggregated ClusterRoles + +As of 1.9, ClusterRoles can be created by combining other ClusterRoles using an `aggregationRule`. The +permissions of aggregated ClusterRoles are controller-managed, and filled in by unioning the rules of any +ClusterRole that matches the provided label selector. An example aggregated ClusterRole: + +```yaml +kind: ClusterRole +apiVersion: rbac.authorization.k8s.io/v1 +metadata: + name: monitoring +aggregationRule: + clusterRoleSelectors: + - matchLabels: + rbac.example.com/aggregate-to-monitoring: "true" +rules: [] # Rules are automatically filled in by the controller manager. +``` + +Creating a ClusterRole that matches the label selector will add rules to the aggregated ClusterRole. In this case +rules can be added to the "monitoring" ClusterRole by creating another ClusterRole that has the label +`rbac.example.com/aggregate-to-monitoring: true`. + +```yaml +kind: ClusterRole +apiVersion: rbac.authorization.k8s.io/v1 +metadata: + name: monitoring-endpoints + labels: + rbac.example.com/aggregate-to-monitoring: "true" +# These rules will be added to the "monitoring" role. +rules: +- apiGroups: [""] + Resources: ["services", "endpoints", "pods"] + verbs: ["get", "list", "watch"] +``` + +The default user-facing roles (described below) use ClusterRole aggregation. This lets admins attach rules +for custom resources, such as those served by CustomResourceDefinitions or Aggregated API servers, to the +default roles. + +For example, the following ClusterRoles let the "admin" and "edit" default roles manage the custom resource +"CronTabs" and the "view" role perform read-only actions on the resource. + +```yaml +kind: ClusterRole +apiVersion: rbac.authorization.k8s.io/v1 +metadata: + name: aggregate-cron-tabs-edit + labels: + # Add these permissions to the "admin" and "edit" default roles. + rbac.authorization.k8s.io/aggregate-to-admin: "true" + rbac.authorization.k8s.io/aggregate-to-edit: "true" +rules: +- apiGroups: ["stable.example.com"] + resources: ["crontabs"] + verbs: ["*"] +--- +kind: ClusterRole +apiVersion: rbac.authorization.k8s.io/v1 +metadata: + name: aggregate-cron-tabs-view + labels: + # Add these permissions to the "view" default role. + rbac.authorization.k8s.io/aggregate-to-view: "true" +rules: +- apiGroups: ["stable.example.com"] + resources: ["crontabs"] + verbs: ["get", "list", "watch"] +``` + #### Role Examples Only the `rules` section is shown in the following examples. @@ -402,6 +472,18 @@ They include super-user roles (`cluster-admin`), roles intended to be granted cluster-wide using ClusterRoleBindings (`cluster-status`), and roles intended to be granted within particular namespaces using RoleBindings (`admin`, `edit`, `view`). +As of 1.9, user-facing roles use [ClusterRole Aggregation](#aggregated-clusterroles) to allow admins to include +rules for custom resources on these roles. To add rules to the "admin", "edit", or "view" role, create a +ClusterRole with one or more of the following labels: + +```yaml +metadata: + labels: + rbac.authorization.k8s.io/aggregate-to-admin: "true" + rbac.authorization.k8s.io/aggregate-to-edit: "true" + rbac.authorization.k8s.io/aggregate-to-view: "true" +``` +