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/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,75 @@
+---
+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
+
+Kubelets must be able to read the API resources that describe the pods they are supposed to run,
+read secrets, configmaps, persistent volume claims and persistent volumes related to those pods,
+and write API objects that report the status of their pods, and of the node the kubelet is running on.
+
+The Node authorizer tracks which pods are associated with which nodes, and authorizes 
+kubelets to read just the resources related to their pods.
+
+In order to be authorized, 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 (have a username that does not match 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.
+
+The `system:node` cluster role will continue to be created when using RBAC,
+for compatibility with deployment methods that bind other users or groups to that role.

docs/admin/authorization/rbac.md

@@ -460,11 +460,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)</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>