Merge in missing changes from master

Author: chenopis

docs/concepts/api-extension/custom-resources.md

@@ -48,24 +48,24 @@ When creating a new API, consider whether to [aggregate your API with the Kubern
 #### Declarative APIs
 
 In a Declarative API, typically:
- - your API consists of a relatively small number of relatively small objects (resources).
- - the objects define configuration of applications or infrastructure
- - the objects are updated relatively infrequently
- - humans often need to read and write the objects
- - the main operations on the objects are CRUD-y (creating, reading, updating and deleting)
- - transactions across objects are not required: the API represents a desired state, not an exact state.
+ - Your API consists of a relatively small number of relatively small objects (resources).
+ - The objects define configuration of applications or infrastructure.
+ - The objects are updated relatively infrequently.
+ - Humans often need to read and write the objects.
+ - The main operations on the objects are CRUD-y (creating, reading, updating and deleting).
+ - Transactions across objects are not required: the API represents a desired state, not an exact state.
 
 Imperative APIs are not declarative.
 Signs that your API might not be declarative include:
- - the client says "do this", and then gets a synchornous response back when it is done.
- - the client says "do this", and then gets an operation ID back, and has to check a separate Operation objects to determine completion of the request.
- - you talk about Remote Procedure Calls (RPCs)
- - directly stoing large amounts of data (e.g. > a few kB per object, or >1000s of objects)
- - high bandwidth access (10s of requests per second sustained) needed
- - store end-user data (such as images, PII, etc) or other large-scale data processed by applications
- - the natural operations on the objects are not CRUD-y.
- - the API is not easily modeled as objects.
- - you chose to represent pending operations with an operation ID or operation object.
+ - The client says "do this", and then gets a synchornous response back when it is done.
+ - The client says "do this", and then gets an operation ID back, and has to check a separate Operation objects to determine completion of the request.
+ - You talk about Remote Procedure Calls (RPCs).
+ - Directly storing large amounts of data (e.g. > a few kB per object, or >1000s of objects).
+ - High bandwidth access (10s of requests per second sustained) needed.
+ - Store end-user data (such as images, PII, etc) or other large-scale data processed by applications.
+ - The natural operations on the objects are not CRUD-y.
+ - The API is not easily modeled as objects.
+ - You chose to represent pending operations with an operation ID or operation object.
 
 ### Should I use a configMap or a custom resource?
 
@@ -102,7 +102,7 @@ Aggregated APIs are subordinate APIServers that sit behind the primary API serve
 
 Custom Resource Definitions (CRDS) allow users to create new types of resources without adding another APIserver. You do not need to understand API Aggregation to use CRDs.
 
-Regardless of whether they are installed via CRDs or AA, the new resources are called Custom Resources to distinguish them from built-in Kubernetes resources (like pods)
+Regardless of whether they are installed via CRDs or AA, the new resources are called Custom Resources to distinguish them from built-in Kubernetes resources (like pods).
 
 ## CustomResourceDefinitions
 
@@ -215,9 +215,9 @@ Kubernetes [client libraries](/docs/reference/client-libraries/) can be used to
 
 When you add a custom resource, you can access it using:
   - kubectl
-  - the kubernetes dynamic client
-  - a REST client that you write
-  - a client generated using Kubernetes client generation tools (generating one is an advanced undertaking, but some projects may provide a client along with the CRD or AA).
+  - The kubernetes dynamic client.
+  - A REST client that you write.
+  - A client generated using Kubernetes client generation tools (generating one is an advanced undertaking, but some projects may provide a client along with the CRD or AA).
 
 {% endcapture %}
 

docs/concepts/policy/psp.yaml renamed to docs/concepts/policy/example-psp.yaml

@@ -1,8 +1,10 @@
 apiVersion: extensions/v1beta1
 kind: PodSecurityPolicy
 metadata:
-  name: permissive
+  name: example
 spec:
+  privileged: false  # Don't allow privileged pods!
+  # The rest fills in some required fields.
   seLinux:
     rule: RunAsAny
   supplementalGroups:
@@ -11,10 +13,5 @@ spec:
     rule: RunAsAny
   fsGroup:
     rule: RunAsAny
-  hostPorts:
-  - min: 8000
-    max: 8080
   volumes:
   - '*'
-  allowedCapabilities:
-  - '*'

docs/concepts/policy/privileged-psp.yaml

@@ -0,0 +1,27 @@
+apiVersion: extensions/v1beta1
+kind: PodSecurityPolicy
+metadata:
+  name: privileged
+  annotations:
+    seccomp.security.alpha.kubernetes.io/allowedProfileNames: '*'
+spec:
+  privileged: true
+  allowPrivilegeEscalation: true
+  allowedCapabilities:
+  - '*'
+  volumes:
+  - '*'
+  hostNetwork: true
+  hostPorts:
+  - min: 0
+    max: 65535
+  hostIPC: true
+  hostPID: true
+  runAsUser:
+    rule: 'RunAsAny'
+  seLinux:
+    rule: 'RunAsAny'
+  supplementalGroups:
+    rule: 'RunAsAny'
+  fsGroup:
+    rule: 'RunAsAny'

docs/concepts/policy/restricted-psp.yaml

@@ -0,0 +1,48 @@
+apiVersion: extensions/v1beta1
+kind: PodSecurityPolicy
+metadata:
+  name: restricted
+  annotations:
+    seccomp.security.alpha.kubernetes.io/allowedProfileNames: 'docker/default'
+    apparmor.security.beta.kubernetes.io/allowedProfileNames: 'runtime/default'
+    seccomp.security.alpha.kubernetes.io/defaultProfileName:  'docker/default'
+    apparmor.security.beta.kubernetes.io/defaultProfileName:  'runtime/default'
+spec:
+  privileged: false
+  # Required to prevent escalations to root.
+  allowPrivilegeEscalation: false
+  # This is redundant with non-root + disallow privilege escalation,
+  # but we can provide it for defense in depth.
+  requiredDropCapabilities:
+    - ALL
+  # Allow core volume types.
+  volumes:
+    - 'configMap'
+    - 'emptyDir'
+    - 'projected'
+    - 'secret'
+    - 'downwardAPI'
+    # Assume that persistentVolumes set up by the cluster admin are safe to use.
+    - 'persistentVolumeClaim'
+  hostNetwork: false
+  hostIPC: false
+  hostPID: false
+  runAsUser:
+    # Require the container to run without root privileges.
+    rule: 'MustRunAsNonRoot'
+  seLinux:
+    # This policy assumes the nodes are using AppArmor rather than SELinux.
+    rule: 'RunAsAny'
+  supplementalGroups:
+    rule: 'MustRunAs'
+    ranges:
+      # Forbid adding the root group.
+      - min: 1
+        max: 65535
+  fsGroup:
+    rule: 'MustRunAs'
+    ranges:
+      # Forbid adding the root group.
+      - min: 1
+        max: 65535
+  readOnlyRootFilesystem: false

docs/concepts/storage/persistent-volumes.md

@@ -245,10 +245,12 @@ Generally, a PV will have a specific storage capacity.  This is set using the PV
 Currently, storage size is the only resource that can be set or requested.  Future attributes may include IOPS, throughput, etc.
 
 ### Volume Mode
-{% assign for_k8s_version="v1.9" %}{% include feature-state-alpha.md %}
 
 Prior to v1.9, the default behavior for all volume plugins was to create a filesystem on the persistent volume. With v1.9, the user can specify a volumeMode which will now support raw block devices in addition to file systems. Valid values for volumeMode are "Filesystem" or "Block". If left unspecified, volumeMode defaults to "Filesystem" internally. This is an optional API parameter. 
 
+**Note:** This feature is alpha in v1.9 and may change in the future. 
+{: .note}
+
 ### Access Modes
 
 A `PersistentVolume` can be mounted on a host in any way supported by the resource provider.  As shown in the table below, providers will have different capabilities and each PV's access modes are set to the specific modes supported by that particular volume.  For example, NFS can support multiple read/write clients, but a specific NFS PV might be exported on the server as read-only.  Each PV gets its own set of access modes describing that specific PV's capabilities.
@@ -384,7 +386,7 @@ Claims use the same conventions as volumes when requesting storage with specific
 
 ### Volume Modes
 
-Claims use the same convention as volumes to indicate the consumption of the volume as either a filesystem or block device.
+Claims use the same convention as volumes to indicates the consumption of the volume as either a filesystem or block device.
 
 ### Resources
 
@@ -470,7 +472,7 @@ spec:
 
 ## Raw Block Volume Support
 
-Static provisioning support for Raw Block Volumes is included as an alpha feature for v1.9. Raw block volumes can be specified through new API fields. Currently, Fibre Channel is the only supported plugin for this feature.
+Static provisioning support for Raw Block Volumes is included as an alpha feature for v1.9. With this change are some new API fields that need to be used to facilitate this functionality. Currently, Fibre Channel is the only supported plugin for this feature.
 
 ### Persistent Volumes using a Raw Block Volume
 ```
@@ -530,7 +532,7 @@ spec:
 
 ### Binding Block Volumes
 
-If a user requests a raw block volume through the persistentVolumeClaim.volumeMode field, it can only bind to PersistentVolume with the matching volumeMode field.
+If a user requests a raw block volume by indicating this using the volumeMode field in the PersistentVolumeClaim spec, the binding rules differ slighty from previous releases that didn't consider this mode as part of the spec.
 Listed is a table of possible combinations the user and admin might specify for requesting a raw block device. The table indicates if the volume will be bound or not given the combinations:
 Volume binding matrix for statically provisioned volumes:
 

docs/getting-started-guides/scratch.md

@@ -705,7 +705,7 @@ Complete this template for the scheduler pod:
     "containers": [
       {
         "name": "kube-scheduler",
-        "image": "$HYBERKUBE_IMAGE",
+        "image": "$HYPERKUBE_IMAGE",
         "command": [
           "/hyperkube",
           "scheduler",

docs/tasks/access-application-cluster/access-cluster.md

@@ -55,7 +55,8 @@ $ kubectl proxy --port=8080 &
 
 See [kubectl proxy](/docs/user-guide/kubectl/{{page.version}}/#proxy) for more details.
 
-Then you can explore the API with curl, wget, or a browser, like so:
+Then you can explore the API with curl, wget, or a browser, replacing localhost
+with [::1] for IPv6, like so:
 
 ```shell
 $ curl http://localhost:8080/api/

docs/tasks/access-application-cluster/frontend.yaml

@@ -1,5 +1,5 @@
-kind: Service
 apiVersion: v1
+kind: Service
 metadata:
   name: frontend
 spec:

docs/tutorials/stateful-application/web.yaml

@@ -1,4 +1,3 @@
----
 apiVersion: v1
 kind: Service
 metadata:

docs/tutorials/stateful-application/webp.yaml

@@ -1,4 +1,3 @@
----
 apiVersion: v1
 kind: Service
 metadata:
@@ -45,4 +44,4 @@ spec:
       accessModes: [ "ReadWriteOnce" ]
       resources:
         requests:
-          storage: 1Gi
+          storage: 1Gi

docs/tutorials/stateful-application/zookeeper.yaml

@@ -1,4 +1,3 @@
----
 apiVersion: v1
 kind: Service
 metadata:

docs/user-guide/environment-guide/backend-rc.yaml

@@ -1,4 +1,3 @@
----
 apiVersion: v1
 kind: ReplicationController
 metadata:

docs/user-guide/environment-guide/backend-srv.yaml

@@ -1,4 +1,3 @@
----
 apiVersion: v1
 kind: Service
 metadata:

docs/user-guide/environment-guide/show-rc.yaml

@@ -1,4 +1,3 @@
----
 apiVersion: v1
 kind: ReplicationController
 metadata:

docs/user-guide/environment-guide/show-srv.yaml

@@ -1,4 +1,3 @@
----
 apiVersion: v1
 kind: Service
 metadata:

docs/user-guide/multi-pod.yaml

@@ -1,4 +1,3 @@
----
 apiVersion: v1
 kind: Pod
 metadata: