updates to service injection policy proposal

Signed-off-by: Jess Frazelle <acidburn@google.com>

contributors/design-proposals/service-injection-policy.md

@@ -0,0 +1,175 @@
+# Service Injection Policy
+
+## Abstract
+
+Describes a policy resource that allows loose coupling from services to the pods
+that consume them.
+
+## Motivation
+
+Consuming a service involves more than just connectivity.  In addition to
+coordinates to reach the service, credentials and non-secret configuration
+parameters are typically needed to use the service.  The primitives for this
+already exist, but a gap exists where loose coupling is desired: it should be
+possible to inject pods with the information they need to use a service on a
+service-by-service basis, without the pod authors having to incorporate the
+information into every pod spec where it is needed.
+
+## Constraints and Assumptions
+
+1.  New mechanisms must be made to work with controllers such as deployments and
+    replicasets that create pods
+
+## Use Cases
+
+1.  As a user, I want to be able to describe a way that pods should be injected
+    with the information to consume a particular service in a loosely-coupled
+    way, so that I can concisely model the information about how the service
+    should be consumed without altering every consuming pod spec.
+
+### Loose coupling between services and their consumers
+
+Using a Service Injection Policy allows pod authors to not have to explicitly
+set information for every pod. The information will be injected based off the
+policy's LabelSelector.
+
+## Proposed Changes
+
+### ServiceInjectionPolicy API object
+
+```go
+type ServiceInjectionPolicy struct {
+    unversioned.TypeMeta
+    ObjectMeta
+
+    Spec ServiceInjectionPolicySpec
+}
+
+type ServiceInjectionPolicySpec struct {
+    Service       string # Reference to the service that is being injected
+    LabelSelector *unversioned.LabelSelector
+    Env           []EnvVar
+    EnvFrom       []EnvVarFrom
+    Volumes       []Volume
+    VolumeMounts  []VolumeMount
+}
+```
+
+### AdmissionControl Plugin: ServiceInjectionPolicy
+
+The **ServiceInjectionPolicy** plugin introspects all incoming pod requests and
+injects the pod based off a `LabelSelector` with the desired attributes.
+
+#### Behavior
+
+This will modify the containers in the pod spec. The supported changes to
+`Env`, `EnvFrom`, `Volumes`, and `VolumeMounts` apply to the container spec for
+all containers in the pod with the specified matching `LabelSelector`.
+
+*Why all modify all containers in a pod?*
+
+Currently there is no concept of labels on specific containers in a pod which
+would be necessary for per-container service injections. We could add labels
+for specific containers which would allow this and be the best solution to not
+injecting all. Other solutions include basing the container to inject based off
+matching it's name to another field in the `ServiceInjectionPolicy` spec, but
+this would not scale well and would cause annoyance with configuration
+management.
+
+The resultant modified spec will be annotated to show that it was modified by
+the `ServiceInjectionPolicy`.
+
+#### Optional Behavior with implicit injections
+
+The above described the behavior for explicitly defining what should be
+injected into a pod.
+
+But a helper has been discussed to automatically fill in the
+`ServiceInjectionSpec` values based off annotations on a service defining the
+resources you need. This would be similar to the functionality ConfigMaps and
+Secrets.
+
+## Examples
+
+User submitted pod spec:
+
+```yaml
+apiVersion: v1
+kind: ReplicationController
+metadata:
+  name: website
+spec:
+  replicas: 2
+  selector:
+    app: website
+  template:
+    metadata:
+      name: website
+      labels:
+        role: frontend
+    spec:
+      containers:
+      - name: website
+        image: ecorp/website
+        ports:
+          - containerPort: 80
+```
+
+Example service injection policy:
+
+```yaml
+kind: ServiceInjectionPolicy
+apiVersion: extensions/v1beta1
+metadata:
+  name: allow-database
+  namespace: myns
+spec:
+  service: db
+  labelSelector:
+    matchLabels:
+      role: frontend
+  env:
+    - name: DB_PORT
+      value: 6379
+  volumeMounts:
+    - mountPath: /cache
+      name: cache-volume
+  volumes:
+    - name: cache-volume
+      emptyDir: {}
+```
+
+Pod spec after admission controller:
+
+```yaml
+apiVersion: v1
+kind: ReplicationController
+metadata:
+  name: website
+  annotations:
+    - serviceinjectionpolicy.k8s.io/db: allow-database
+spec:
+  replicas: 2
+  selector:
+    app: website
+  template:
+    metadata:
+      name: website
+      labels:
+        role: frontend
+    spec:
+      containers:
+      - name: website
+        image: ecorp/website
+        volumeMounts:
+          - mountPath: /cache
+            name: cache-volume
+        volumes:
+          - name: cache-volume
+            emptyDir: {}
+        ports:
+          - containerPort: 80
+        env:
+          - name: DB_PORT
+            value: 6379
+```