From 8a7e22dba2888ac8f07659c84f858db186fb16f9 Mon Sep 17 00:00:00 2001 From: Eric Tune Date: Tue, 2 Jun 2015 17:19:17 -0700 Subject: [PATCH] Update Admission Control docs and add others. Address most of the comments from #8936 review. Adds minimal documentation for securityContext and serviceAccounts, which I will expand in a future PR. Adds analytics. Links admission_controllers.md from cluster-admin-guide. --- docs/admission_controllers.md | 109 ++++++++++++++++++++++++++++++++++ docs/cluster-admin-guide.md | 2 + docs/security_context.md | 6 ++ docs/service_accounts.md | 14 +++++ 4 files changed, 131 insertions(+) create mode 100644 docs/admission_controllers.md create mode 100644 docs/security_context.md create mode 100644 docs/service_accounts.md diff --git a/docs/admission_controllers.md b/docs/admission_controllers.md new file mode 100644 index 00000000000..f80372a5744 --- /dev/null +++ b/docs/admission_controllers.md @@ -0,0 +1,109 @@ +# Admission Controllers + +## What are they? + +An admission control plug-in is a piece of code that intercepts requests to the Kubernetes +API server prior to persistence of the object, but after the request is authenticated +and authorized. The plug-in code is in the API server process +and must be compiled into the binary in order to be used at this time. + +Each admission control plug-in is run in sequence before a request is accepted into the cluster. If +any of the plug-ins in the sequence reject the request, the entire request is rejected immediately +and an error is returned to the end-user. + +Admission control plug-ins may mutate the incoming object in some cases to apply system configured +defaults. In addition, admission control plug-ins may mutate related resources as part of request +processing to do things like increment quota usage. + +## Why do I need them? + +Many advanced features in Kubernetes require an admission control plug-in to be enabled in order +to properly support the feature. As a result, a Kubernetes API server that is not properly +configured with the right set of admission control plug-ins is an incomplete server and will not +support all the features you expect. + +## How do I turn on an admission control plug-in? + +The Kubernetes API server supports a flag, ```admission_control``` that takes a comma-delimited, +ordered list of admission control choices to invoke prior to modifying objects in the cluster. + +## What does each plug-in do? + +### AlwaysAdmit + +Use this plugin by itself to pass-through all requests. + +### AlwaysDeny + +Rejects all requests. Used for testing. + +### DenyExecOnPrivileged + +This plug-in will intercept all requests to exec a command in a pod if that pod has a privileged container. + +If your cluster supports privileged containers, and you want to restrict the ability of end-users to exec +commands in those containers, we strongly encourage enabling this plug-in. + +### ServiceAccount + +This plug-in implements automation for [serviceAccounts]( service_accounts.md). +We strongly recommend using this plug-in if you intend to make use of Kubernetes ```ServiceAccount``` objects. + +### SecurityContextDeny + +This plug-in will deny any pod with a [SecurityContext](security_context.md) that defines options that were not available on the ```Container```. + +### ResourceQuota + +This plug-in will observe the incoming request and ensure that it does not violate any of the constraints +enumerated in the ```ResourceQuota``` object in a ```Namespace```. If you are using ```ResourceQuota``` +objects in your Kubernetes deployment, you MUST use this plug-in to enforce quota constraints. + +See the [resourceQuota design doc]( design/admission_control_resource_quota.md). + +It is strongly encouraged that this plug-in is configured last in the sequence of admission control plug-ins. This is +so that quota is not prematurely incremented only for the request to be rejected later in admission control. + +### LimitRanger + +This plug-in will observe the incoming request and ensure that it does not violate any of the constraints +enumerated in the ```LimitRange``` object in a ```Namespace```. If you are using ```LimitRange``` objects in +your Kubernetes deployment, you MUST use this plug-in to enforce those constraints. + +See the [limitRange design doc]( design/admission_control_limit_range.md). + +### NamespaceExists + +This plug-in will observe all incoming requests that attempt to create a resource in a Kubernetes ```Namespace``` +and reject the request if the ```Namespace``` was not previously created. We strongly recommend running +this plug-in to ensure integrity of your data. + +### NamespaceAutoProvision (deprecated) + +This plug-in will observe all incoming requests that attempt to create a resource in a Kubernetes ```Namespace``` +and create a new ```Namespace``` if one did not already exist previously. + +We strongly recommend ```NamespaceExists``` over ```NamespaceAutoProvision```. + +### NamespaceLifecycle + +This plug-in enforces that a ```Namespace``` that is undergoing termination cannot have new content created in it. + +A ```Namespace``` deletion kicks off a sequence of operations that remove all content (pods, services, etc.) in that +namespace. In order to enforce integrity of that process, we strongly recommend running this plug-in. + +Once ```NamespaceAutoProvision``` is deprecated, we anticipate ```NamespaceLifecycle``` and ```NamespaceExists``` will +be merged into a single plug-in that enforces the life-cycle of a ```Namespace``` in Kubernetes. + +## Is there a recommended set of plug-ins to use? + +Yes. + +For Kubernetes 1.0, we strongly recommend running the following set of admission control plug-ins (order matters): + +```shell +--admission_control=NamespaceLifecycle,NamespaceExists,LimitRanger,SecurityContextDeny,ServiceAccount,ResourceQuota +``` + + +[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/admission_controllers.md?pixel)]() diff --git a/docs/cluster-admin-guide.md b/docs/cluster-admin-guide.md index 259f6f81639..0d48b1ff3e4 100644 --- a/docs/cluster-admin-guide.md +++ b/docs/cluster-admin-guide.md @@ -70,6 +70,8 @@ project.](salt.md). * **Authorization** [authorization]( authorization.md) +* **Admission Controllers** [admission_controllers]( admission_controllers.md) + [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/cluster-admin-guide.md?pixel)]() diff --git a/docs/security_context.md b/docs/security_context.md new file mode 100644 index 00000000000..926ecfa154e --- /dev/null +++ b/docs/security_context.md @@ -0,0 +1,6 @@ +# Security Contexts + +A security context defines the operating system security settings (uid, gid, capabilities, SELinux role, etc..) applied to a container. + + +[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/security_context.md?pixel)]() diff --git a/docs/service_accounts.md b/docs/service_accounts.md new file mode 100644 index 00000000000..335a2ea2839 --- /dev/null +++ b/docs/service_accounts.md @@ -0,0 +1,14 @@ +# Service Accounts +A serviceAccount provides an identity for processes that run in a Pod. +The behavior of the the serviceAccount object is implemented via a plugin +called an [Admission Controller]( admission_controllers.md). When this plugin is active +(and it is by default on most distributions), then it does the following when a pod is created or modified: + 1. If the pod does not have a ```ServiceAccount```, it modifies the pod's ```ServiceAccount``` to "default". + 2. It ensures that the ```ServiceAccount``` referenced by a pod exists. + 3. If ```LimitSecretReferences``` is true, it rejects the pod if the pod references ```Secret``` objects which the pods +```ServiceAccount``` does not reference. + 4. If the pod does not contain any ```ImagePullSecrets```, the ```ImagePullSecrets``` of the +```ServiceAccount``` are added to the pod. + 5. If ```MountServiceAccountToken``` is true, it adds a ```VolumeMount``` with the pod's ```ServiceAccount``` API token secret to containers in the pod. + +[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/service_accounts.md?pixel)]()