Keep 1.7 up to date with master. (#4574)

* secrets: add a best practices section and API access recommentations (#4380)

* secrets: add a best practices section and API access recommentations

This section attempts to capture some of the best practices around
client API access to secrets. Specitically that controllers should
avoid list and watch operations in favor of getting specific secrets.

* add "are"

* update scratch.md for issue #4068 (#4069)

* update scratch.md for issue #4068

Issue #4068 details the dangers of recommending single etcd instance.

This will likely need to be expanded into better "highly available" cluster documentation

* Refactor list style

* fix ordered list

* fix unordered list

* ul

* add back shell

* Adding tutorial links to docs (#4570)

* Adding tutorial links to docs

* Update index.md

docs/concepts/configuration/secret.md

@@ -766,6 +766,40 @@ it to read a file.
 
 <!-- TODO: explain how to do this while still using automation. -->
 
+## Best practices
+
+### Clients that use the secrets API
+
+When deploying applications that interact with the secrets API, access should be
+limited using [authorization policies](
+https://kubernetes.io/docs/admin/authorization/) such as [RBAC](
+https://kubernetes.io/docs/admin/authorization/rbac/).
+
+Secrets often hold values that span a spectrum of importance, many of which can
+cause escalations within Kubernetes (e.g. service account tokens) and to
+external systems. Even if an individual app can reason about the power of the
+secrets it expects to interact with, other apps within the same namespace can
+render those assumptions invalid.
+
+For these reasons `watch` and `list` requests for secrets within a namespace are
+extremely powerful capabilities and should be avoided, since listing secrets allows
+the clients to inspect the values if all secrets are in that namespace. The ability to
+`watch` and `list` all secrets in a cluster should be reserved for only the most
+privileged, system-level components.
+
+Applications that need to access the secrets API should perform `get` requests on
+the secrets they need. This lets administrators restrict access to all secrets
+while [white-listing access to individual instances](
+https://kubernetes.io/docs/admin/authorization/rbac/#referring-to-resources) that
+the app needs.
+
+For improved performance over a looping `get`, clients can design resources that
+reference a secret then `watch` the resource, re-requesting the secret when the
+reference changes. Additionally, a ["bulk watch" API](
+https://github.com/kubernetes/community/blob/master/contributors/design-proposals/bulk_watch.md)
+to let clients `watch` individual resources has also been proposed, and will likely
+be available in future releases of Kubernetes. 
+
 ## Security Properties
 
 ### Protections

docs/getting-started-guides/scratch.md

@@ -444,14 +444,29 @@ because of how this is used later.
 - Alternate, manual approach:
 
   1. Set `--configure-cbr0=false` on kubelet and restart.
-  1. Create a bridge
-     - `ip link add name cbr0 type bridge`.
+  1. Create a bridge.
+
+        ```
+        ip link add name cbr0 type bridge
+        ```
+
   1. Set appropriate MTU. NOTE: the actual value of MTU will depend on your network environment
-     - `ip link set dev cbr0 mtu 1460`
+
+        ```
+        ip link set dev cbr0 mtu 1460
+        ```
+
   1. Add the node's network to the bridge (docker will go on other side of bridge).
-     - `ip addr add $NODE_X_BRIDGE_ADDR dev cbr0`
+
+        ```
+        ip addr add $NODE_X_BRIDGE_ADDR dev cbr0
+        ```
+
   1. Turn it on
-     - `ip link set dev cbr0 up`
+
+        ```
+        ip link set dev cbr0 up
+        ```
 
 If you have turned off Docker's IP masquerading to allow pods to talk to each
 other, then you may need to do masquerading just for destination IPs outside
@@ -501,11 +516,13 @@ all configured and managed *by Kubernetes*:
 
 You will need to run one or more instances of etcd.
 
-  - Recommended approach: run one etcd instance, with its log written to a directory backed
+  - Highly available and easy to restore - Run 3 or 5 etcd instances with, their logs written to a directory backed
     by durable storage (RAID, GCE PD)
-  - Alternative: run 3 or 5 etcd instances.
-    - Log can be written to non-durable storage because storage is replicated.
-    - run a single apiserver which connects to one of the etcd nodes.
+  - Not highly available, but easy to restore - Run one etcd instance, with its log written to a directory backed
+    by durable storage (RAID, GCE PD)
+    **Note:** May result in operations outages in case of instance outage
+  - Highly available - Run 3 or 5 etcd instances with non durable storage.
+    **Note:** Log can be written to non-durable storage because storage is replicated.
 
 See [cluster-troubleshooting](/docs/admin/cluster-troubleshooting) for more discussion on factors affecting cluster
 availability.

docs/tutorials/index.md

@@ -37,6 +37,16 @@ each of which has a sequence of steps.
 
 * [Running ZooKeeper, A CP Distributed System](/docs/tutorials/stateful-application/zookeeper/)
 
+#### CI/CD Pipeline
+
+* [Set Up a CI/CD Pipeline with Kubernetes Part 1: Overview](https://www.linux.com/blog/learn/chapter/Intro-to-Kubernetes/2017/5/set-cicd-pipeline-kubernetes-part-1-overview)
+
+* [Set Up a CI/CD Pipeline with a Jenkins Pod in Kubernetes (Part 2)](https://www.linux.com/blog/learn/chapter/Intro-to-Kubernetes/2017/6/set-cicd-pipeline-jenkins-pod-kubernetes-part-2)
+
+* [Run and Scale a Distributed Crossword Puzzle App with CI/CD on Kubernetes (Part 3)](https://www.linux.com/blog/learn/chapter/intro-to-kubernetes/2017/6/run-and-scale-distributed-crossword-puzzle-app-cicd-kubernetes-part-3)
+
+* [Set Up CI/CD for a Distributed Crossword Puzzle App on Kubernetes (Part 4)](https://www.linux.com/blog/learn/chapter/intro-to-kubernetes/2017/6/set-cicd-distributed-crossword-puzzle-app-kubernetes-part-4)
+
 #### Connecting Applications
 
 * [Connecting a Front End to a Back End Using a Service](/docs/tutorials/connecting-apps/connecting-frontend-backend/)