Merge pull request #7987 from pweil-/security-context-doc

docs/design/security_context.md

@@ -65,8 +65,8 @@ be addressed with security contexts:
 
 ### Overview
 A *security context* consists of a set of constraints that determine how a container
-is secured before getting created and run. It has a 1:1 correspondence to a
-[service account](https://github.com/GoogleCloudPlatform/kubernetes/pull/2297). A *security context provider* is passed to the Kubelet so it can have a chance
+is secured before getting created and run. A security context resides on the container and represents the runtime parameters that will
+be used to create and run the container via container APIs. A *security context provider* is passed to the Kubelet so it can have a chance
 to mutate Docker API calls in order to apply the security context.
 
 It is recommended that this design be implemented in two phases:
@@ -88,7 +88,7 @@ type SecurityContextProvider interface {
 	// the container is created.
 	// An error is returned if it's not possible to secure the container as 
 	// requested with a security context. 
-	ModifyContainerConfig(pod *api.Pod, container *api.Container, config *docker.Config) error
+	ModifyContainerConfig(pod *api.Pod, container *api.Container, config *docker.Config)
 	
 	// ModifyHostConfig is called before the Docker runContainer call.
 	// The security context provider can make changes to the HostConfig, affecting
@@ -103,88 +103,55 @@ If the value of the SecurityContextProvider field on the Kubelet is nil, the kub
 
 ### Security Context
 
-A security context has a 1:1 correspondence to a service account and it can be included as
-part of the service account resource. Following is an example of an initial implementation:
+A security context resides on the container and represents the runtime parameters that will
+be used to create and run the container via container APIs. Following is an example of an initial implementation:
 
 ```go
+type type Container struct {
+	... other fields omitted ...
+	// Optional: SecurityContext defines the security options the pod should be run with
+    SecurityContext *SecurityContext
+}
 
-// SecurityContext specifies the security constraints associated with a service account
+// SecurityContext holds security configuration that will be applied to a container.  SecurityContext
+// contains duplication of some existing fields from the Container resource.  These duplicate fields
+// will be populated based on the Container configuration if they are not set.  Defining them on
+// both the Container AND the SecurityContext will result in an error.
 type SecurityContext struct {
-    // user is the uid to use when running the container
-	User int
-	
-	// AllowPrivileged indicates whether this context allows privileged mode containers
-	AllowPrivileged bool
-	
-	// AllowedVolumeTypes lists the types of volumes that a container can bind
-	AllowedVolumeTypes []string
-	
-	// AddCapabilities is the list of Linux kernel capabilities to add
-	AddCapabilities []string
-	
-	// RemoveCapabilities is the list of Linux kernel capabilities to remove
-	RemoveCapabilities []string
-	
-	// Isolation specifies the type of isolation required for containers 
-	// in this security context 
-	Isolation ContainerIsolationSpec
-}
+	// Capabilities are the capabilities to add/drop when running the container
+	Capabilities *Capabilities
 
-// ContainerIsolationSpec indicates intent for container isolation
-type ContainerIsolationSpec struct {
-	// Type is the container isolation type (None, Private)
-	Type ContainerIsolationType
-	
-	// FUTURE: IDMapping specifies how users and groups from the host will be mapped
-	IDMapping *IDMapping
-}
+	// Run the container in privileged mode
+	Privileged *bool
 
-// ContainerIsolationType is the type of container isolation for a security context
-type ContainerIsolationType string
+	// SELinuxOptions are the labels to be applied to the container
+	// and volumes
+	SELinuxOptions *SELinuxOptions
 
-const (
-    // ContainerIsolationNone means that no additional consraints are added to
-    // containers to isolate them from their host
-	ContainerIsolationNone ContainerIsolationType = "None"
-	
-	// ContainerIsolationPrivate means that containers are isolated in process
-	// and storage from their host and other containers.
-	ContainerIsolationPrivate ContainerIsolationType = "Private"
-)
-
-// IDMapping specifies the requested user and group mappings for containers 
-// associated with a specific security context
-type IDMapping struct {
-	// SharedUsers is the set of user ranges that must be unique to the entire cluster
-	SharedUsers []IDMappingRange
-	
-	// SharedGroups is the set of group ranges that must be unique to the entire cluster
-	SharedGroups []IDMappingRange
+	// RunAsUser is the UID to run the entrypoint of the container process.
+	RunAsUser *int64
+}
 
-	// PrivateUsers are mapped to users on the host node, but are not necessarily
-	// unique to the entire cluster
-	PrivateUsers []IDMappingRange
+// SELinuxOptions are the labels to be applied to the container.
+type SELinuxOptions struct {
+	// SELinux user label
+	User string
 
-	// PrivateGroups are mapped to groups on the host node, but are not necessarily
-	// unique to the entire cluster
-	PrivateGroups []IDMappingRange
-}
+	// SELinux role label
+	Role string
 
-// IDMappingRange specifies a mapping between container IDs and node IDs
-type IDMappingRange struct {
-	// ContainerID is the starting container UID or GID
-	ContainerID int
+	// SELinux type label
+	Type string
 
-	// HostID is the starting host UID or GID
-	HostID int
-	
-	// Length is the length of the UID/GID range
-	Length int
+	// SELinux level label.
+	Level string
 }
-
 ```
+### Admission
 
+It is up to an admission plugin to determine if the security context is acceptable or not.  At the
+time of writing, the admission control plugin for security contexts will only allow a context that
+has defined capabilities or privileged.  Contexts that attempt to define a UID or SELinux options
+will be denied by default.  In the future the admission plugin will base this decision upon
+configurable policies that reside within the [service account](https://github.com/GoogleCloudPlatform/kubernetes/pull/2297).
 
-#### Security Context Lifecycle
- 
-The lifecycle of a security context will be tied to that of a service account. It is expected that a service account with a default security context will be created for every Kubernetes namespace (without administrator intervention). If resources need to be allocated when creating a security context (for example, assign a range of host uids/gids), a pattern such as [finalizers](https://github.com/GoogleCloudPlatform/kubernetes/issues/3585) can be used before declaring the security context / service account / namespace ready for use.