Merge pull request #4077 from liggitt/node-authz

Document node authorization mode

_data/reference.yml

@@ -18,6 +18,7 @@ toc:
     - docs/admin/authorization/index.md
     - docs/admin/authorization/abac.md
     - docs/admin/authorization/rbac.md
+    - docs/admin/authorization/node.md
     - docs/admin/authorization/webhook.md
   - docs/reference/deprecation-policy.md
 

docs/admin/admission-controllers.md

@@ -301,9 +301,9 @@ for more information.
 ### NodeRestriction
 
 This plug-in limits the `Node` and `Pod` objects a kubelet can modify. In order to be limited by this admission plugin,
-kubelets must use credentials in the `system:nodes` group, with a username in the form `system:node:<nodeName>`.  Such
-kubelets will only be allowed to modify their own `Node` API object, only modify `Pod` API objects that are bound to
-their node and only create mirror pods for their own [static pods](/docs/tasks/administer-cluster/static-pod/).
+kubelets must use credentials in the `system:nodes` group, with a username in the form `system:node:<nodeName>`. 
+Such kubelets will only be allowed to modify their own `Node` API object, and only modify `Pod` API objects that are bound to their node.
+Future versions may add additional restrictions to ensure kubelets have the minimal set of permissions required to operate correctly.
 
 ## Is there a recommended set of plug-ins to use?
 

docs/admin/authorization/index.md

@@ -58,12 +58,13 @@ of the `bind` verb on `roles` and `clusterroles` resources in the `rbac.authoriz
 * [Authentication](/docs/admin/authentication/) layer checks for authorization of the `impersonate` verb on `users`, `groups`, and `serviceaccounts` in the core API group, and the `userextras` in the `authentication.k8s.io` API group.
 
 ## Authorization Modules
- * **ABAC Mode** - Attribute-based access control (ABAC) defines an access control paradigm whereby access rights are granted to users through the use of policies which combine attributes together. The policies can use any type of attributes (user attributes, resource attributes, object, environment attributes etc). To learn more about using the ABAC mode, see [ABAC Mode](/docs/admin/authorization/abac/)
- * **RBAC Mode** - Role-based access control (RBAC) is a method of regulating access to computer or network resources based on the roles of individual users within an enterprise. In this context, access is the ability of an individual user to perform a specific task, such as view, create, or modify a file. To learn more about using the RBAC mode, see [RBAC Mode](/docs/admin/authorization/rbac/)
+ * **Node** - A special-purpose authorizer that grants permissions to kubelets based on the pods they are scheduled to run. To learn more about using the Node authorization mode, see [Node Authorization](/docs/admin/authorization/node/)
+ * **ABAC** - Attribute-based access control (ABAC) defines an access control paradigm whereby access rights are granted to users through the use of policies which combine attributes together. The policies can use any type of attributes (user attributes, resource attributes, object, environment attributes etc). To learn more about using the ABAC mode, see [ABAC Mode](/docs/admin/authorization/abac/)
+ * **RBAC** - Role-based access control (RBAC) is a method of regulating access to computer or network resources based on the roles of individual users within an enterprise. In this context, access is the ability of an individual user to perform a specific task, such as view, create, or modify a file. To learn more about using the RBAC mode, see [RBAC Mode](/docs/admin/authorization/rbac/)
  ..* When specified "RBAC" (Role-Based Access Control) uses the "rbac.authorization.k8s.io" API group to drive authorization decisions, allowing admins to dynamically configure permission policies through the Kubernetes API.
  ..* As of 1.6 RBAC mode is in beta.
  ..* To enable RBAC, start the apiserver with `--authorization-mode=RBAC`.
- * **Webhook Mode** - A WebHook is an HTTP callback: an HTTP POST that occurs when something happens; a simple event-notification via HTTP POST. A web application implementing WebHooks will POST a message to a URL when certain things happen. To learn more about using the Webhook mode, see [Webhook Mode](/docs/admin/authorization/webhook/)
+ * **Webhook** - A WebHook is an HTTP callback: an HTTP POST that occurs when something happens; a simple event-notification via HTTP POST. A web application implementing WebHooks will POST a message to a URL when certain things happen. To learn more about using the Webhook mode, see [Webhook Mode](/docs/admin/authorization/webhook/)
  * **Custom Modules** - You can create custom modules for using with Kubernetes. To learn more, see **Custom Modules** below.
 
 ### Custom Modules

docs/admin/authorization/node.md

@@ -0,0 +1,93 @@
+---
+assignees:
+- timstclair
+- deads2k
+- liggitt
+- ericchiang
+title: Using Node Authorization
+---
+
+* TOC
+{:toc}
+
+Node authorization is a special-purpose authorization mode that specifically authorizes API requests made by kubelets.
+
+## Overview
+
+The Node authorizer allows a kubelet to perform API operations. This includes:
+
+Read operations:
+
+* services
+* endpoints
+* nodes
+* pods
+* secrets, configmaps, persistent volume claims and persistent volumes related to pods bound to the kubelet's node
+
+Write operations:
+
+* nodes and node status (enable the `NodeRestriction` admission plugin to limit a kubelet to modify its own node)
+* pods and pod status (enable the `NodeRestriction` admission plugin to limit a kubelet to modify pods bound to itself)
+* events
+
+Auth-related operations:
+
+* read/write access to the certificationsigningrequests API for TLS bootstrapping
+* the ability to create tokenreviews and subjectaccessreviews for delegated authentication/authorization checks
+
+In future releases, the node authorizer may add or remove permissions to ensure kubelets
+have the minimal set of permissions required to operate correctly.
+
+In order to be authorized by the Node authorizer, kubelets must use a credential that identifies them as 
+being in the `system:nodes` group, with a username of `system:node:<nodeName>`.
+This group and user name format match the identity created for each kubelet as part of 
+[kubelet TLS bootstrapping](/docs/admin/kubelet-tls-bootstrapping/).
+
+To enable the Node authorizer, start the apiserver with `--authorization-mode=Node`.
+
+To limit the API objects kubelets are able to write, enable the [NodeRestriction](/docs/admin/admission-controllers#NodeRestriction) admission plugin by starting the apiserver with `--admission-control=...,NodeRestriction,...`
+
+## Migration considerations
+
+### Kubelets outside the `system:nodes` group
+
+Kubelets outside the `system:nodes` group would not be authorized by the `Node` authorization mode,
+and would need to continue to be authorized via whatever mechanism currently authorizes them.
+The node admission plugin would not restrict requests from these kubelets.
+
+### Kubelets with undifferentiated usernames
+
+In some deployments, kubelets have credentials that place them in the `system:nodes` group,
+but do not identify the particular node they are associated with,
+because they do not have a username in the `system:node:...` format.
+These kubelets would not be authorized by the `Node` authorization mode,
+and would need to continue to be authorized via whatever mechanism currently authorizes them.
+
+The `NodeRestriction` admission plugin would ignore requests from these kubelets,
+since the default node identifier implementation would not consider that a node identity.
+
+### Upgrades from previous versions using RBAC
+
+Upgraded pre-1.7 clusters using [RBAC](/docs/admin/authorization/rbac/) will continue functioning as-is because the `system:nodes` group binding will already exist.
+
+If a cluster admin wishes to start using the `Node` authorizer and `NodeRestriction` admission plugin
+to limit node access to the API, that can be done non-disruptively:
+
+1. Enable the `Node` authorization mode (`--authorization-mode=Node,RBAC`) and the `NodeRestriction` admission plugin
+2. Ensure all kubelets' credentials conform to the group/username requirements
+3. Audit apiserver logs to ensure the `Node` authorizer is not rejecting requests from kubelets (no persistent `NODE DENY` messages logged)
+4. Delete the `system:node` cluster role binding
+
+### RBAC Node Permissions
+
+In 1.6, the `system:node` cluster role was automatically bound to the `system:nodes` group when using the [RBAC Authorization mode](/docs/admin/authorization/rbac/).
+
+In 1.7, the automatic binding of the `system:nodes` group to the `system:node` role is deprecated
+because the node authorizer accomplishes the same purpose with the benefit of additional restrictions
+on secret and configmap access. If the `Node` and `RBAC` authorization modes are both enabled,
+the automatic binding of the `system:nodes` group to the `system:node` role is not created in 1.7.
+
+In 1.8, the binding will not be created at all.
+
+When using RBAC, the `system:node` cluster role will continue to be created,
+for compatibility with deployment methods that bind other users or groups to that role.

docs/admin/authorization/rbac.md

@@ -461,11 +461,12 @@ The permissions required by individual control loops are contained in the <a hre
 </tr>
 <tr>
 <td><b>system:node</b></td>
-<td><b>system:nodes</b> group</td>
-<td>Allows access to resources required by the kubelet component, <b>including read access to secrets, and write access to pods</b>.
-In the future, read access to secrets and write access to pods will be restricted to objects scheduled to the node.
-To maintain permissions in the future, Kubelets must identify themselves with the group <b>system:nodes</b> and a username in the form <b>system:node:&lt;node-name&gt;</b>.
-See <a href="https://pr.k8s.io/40476">https://pr.k8s.io/40476</a> for details.
+<td><b>system:nodes</b> group (deprecated in 1.7)</td>
+<td>Allows access to resources required by the kubelet component, <b>including read access to all secrets, and write access to all pods</b>.
+As of 1.7, use of the [Node authorizer](/docs/admin/authorization/node/) 
+and [NodeRestriction admission plugin](/docs/admin/admission-controllers#NodeRestriction) 
+is recommended instead of this role, and allow granting API access to kubelets based on the pods scheduled to run on them.
+As of 1.7, when the `Node` authorization mode is enabled, the automatic binding to the `system:nodes` group is not created.
 </td>
 </tr>
 <tr>