Admission control proposal

1 files changed, 145 insertions, 0 deletions

diff --git a/admission_control.md b/admission_control.md
new file mode 100644
index 00000000..60e10198
--- /dev/null
+++ b/admission_control.md
@@ -0,0 +1,145 @@
+# Kubernetes Proposal - Admission Control
+
+**Related PR:** 
+
+| Topic | Link |
+| ----- | ---- |
+
+## Background
+
+High level goals:
+
+* Enable an easy-to-use mechanism to provide admission control to cluster
+* Enable a provider to support multiple admission control strategies or author their own
+* Ensure any rejected request can propagate errors back to the caller with why the request failed
+* Enable usage of cluster resources to satisfy admission control criteria
+* Enable admission controller criteria to change without requiring restart of kube-apiserver
+
+Policy is focused on answering if a user is authorized to perform an action.
+
+Admission Control is focused on if the system will accept an authorized action.
+
+The Kubernetes cluster may choose to dismiss an authorized action based on any number of admission control strategies they choose to author and deploy:
+
+1. Quota enforcement of allocated desired usage
+2. Pod black-lister to restrict running specific images on the cluster
+3. Privileged container checker
+4. Host port reservation
+5. Volume validation - e.g. may or may not use hostDir, etc.
+6. Min/max constraint checker for pod requested resources
+7. ...
+
+This proposal therefore attempts to enumerate the basic design, and describe how any number of admission controllers could be injected.
+
+## kube-apiserver
+
+The kube-apiserver takes the following OPTIONAL arguments to enable admission control
+
+| Option | Behavior |
+| ------ | -------- |
+| admission_controllers | List of addresses (ip:port, dns name) to invoke for admission control |
+| admission_controller_service | Service label selector to resolve for admission control (namespace/labelKey/labelValue) |
+
+If the list of addresses to invoke for admission control are provided as a label selector, the kube-apiserver will update the list 
+of admission control services at a regular interval. 
+
+Upon an incoming request, the kube-apiserver performs the following basic flow:
+
+1. Authorize the request, if authorized, continue
+2. Invoke the Admission Control REST API for each defined address, if all return true, continue
+3. RESTStorage processes request
+4. Data is persisted in store
+
+If there is no configured admission control address, then by default, all requests are admitted.
+
+Admission control is enforced on POST/PUT operations, but is ignored on GET/DELETE operations.
+
+## Admission Control REST API
+
+An admission controller satisfies a stable REST API invoked by the kube-apiserver to satisfy requests.
+
+| Action | HTTP Verb | Path | Description |
+| ---- | ---- | ---- | ---- |
+| CREATE | POST | /admissionController | Send a request for admission to evaluate for admittance or denial |
+
+The message body to the admissionController includes the following:
+
+1. requesting user identity
+2. action to perform
+3. proposed resource to create/modify (if any)
+
+If the request for admission is satisfied, return a HTTP 200.
+
+If the request for admission is denied, return a HTTP 403, the response must include a reason for why the response failed.
+
+## System Design
+
+The following demonstrates potential cluster setups using an external list of admission control endpoints.
+
+                                 Request
+                                    +
+                                    |
+                                    |
+                    +---------------|----------+
+                    | API Server    |          |
+                    |---------------|----------|
+                    |               v          |
+                    |        +--------+        |
+                    |        | Policy |        |       +---------------------+---+
+                    |        ++-------+        |       |Endpoints                |
+    +---------+     |         |                |       |-------------------------|
+    |Scheduler|<---+|         v                |       |E1. Quota Enforcer       |
+    +---------+     | +----------------------+ |       |E2. Capacity Planner     |
+                    | | Admission Controller +-------->|E3. White-lister         |
+                    | +----+-----------------+ |       |...                      |
+                    |      |                   |       +-------------------------+
+                    |     +v-------------+     |
+                    |     | REST Storage |     |
+                    |     +--------------+     |
+                    +----------------+---------+
+                                     |
+                                     v
+                          +--------------+
+                          |  Data Store  |
+                          |--------------|
+                          |              |
+                          |              |
+                          |              |
+                          +--------------+
+
+The following demonstrates potential cluster setup that uses services to fulfill admission control.
+
+In this context, the cluster itself is used to provide HA admission control, and pods may choose to
+invoke the API Server to determine if a request is or is not admissible.
+
+
+                                 Request                    +--------+
+                                    +                       |Pods... |
+                                    |                       |--------|
+                                    |                       |        <-------+
+                    +---------------|----------+            |        |       |
+                    | API Server    |          |            |        |       |
+                    |---------------|----------|            +---+----+       |
+                    |               v          |                |            |
+                    |        +--------+        |<---------------+            |
+                    |        | Policy |        |       +-------------------------------------+
+                    |        ++-------+        |       |Service (ns=infra, labelKey=admitter)|
+    +---------+     |         |                |       |-------------------------------------|
+    |Scheduler|<---+|         v                |       |Service1                             |
+    +---------+     | +----------------------+ |       |Service2                             |
+                    | | Admission Controller +-------->|Service3                             |
+                    | +----+-----------------+ |       |...                                  |
+                    |      |                   |       +-------------------------------------+
+                    |     +v-------------+     |
+                    |     | REST Storage |     |
+                    |     +--------------+     |
+                    +----------------+---------+
+                                     |
+                                     v
+                          +--------------+
+                          |  Data Store  |
+                          |--------------|
+                          |              |
+                          |              |
+                          |              |
+                          +--------------+
\ No newline at end of file