Merge branch 'master' of git://github.com/kubernetes/website into release-1.12

* 'master' of git://github.com/kubernetes/website: (222 commits) Add temporary owners for 1.13 release (#11453) fix Minikube 404 error. (#11461) Resolve conflicts against dev-1.13 for /ko contents (#11439) replace `run` with `create deployment` (#11392) Updated list all pods with -o wide comment (#11394) fix broken link for KubeletConfiguration (#11423) Update on pod-priority-preemption.md (#11418) Add guidelines for working with localized content (#11415) Update what-is-kubernetes.md (#11399) Remove redundant close tags and little bit formatting (#11389) Add SysEleven MetaKube as hosted solution (#11393) Add rui to sig-docs-zh team (#11391) fix Improper translation (#11384) Add pigletfly(WangBing) as a sig-docs-zh-reviewer (#11370) update link to CloudProvider Interface (#11228) Fix the "my-scheduler-as-kube-scheduler" ClusterRoleBinding. (#11112) fix non-existing "CloudProvider Interface" link (#10953) Updated ingress.md (#11213) Further updates to TLS Bootstrapping (#11258) Updated 'exec' description (#11365) ...
2018-12-03 17:11:43 -05:00
parent 4fa6d715ec b1dde5578c
commit 6e094fa640
399 changed files with 3635 additions and 14434 deletions
@@ -1,8 +1,8 @@
 ---
-title: " Paricipate in a Kubernetes User Experience Study "
+title: " Participate in a Kubernetes User Experience Study "
 date: 2015-03-31
-slug: paricipate-in-kubernetes-user
-url: /blog/2015/03/Paricipate-In-Kubernetes-User
+slug: participate-in-kubernetes-user
+url: /blog/2015/03/Participate-In-Kubernetes-User
 ---
 We need your help in shaping the future of Kubernetes and Google Container Engine, and we'd love to have you participate in a remote UX research study to help us learn about your experiences!&nbsp; If you're interested in participating, we invite you to take [this brief survey](http://goo.gl/AXFFMs) to see if you qualify. If you’re selected to participate, we’ll follow up with you directly.

@@ -8,95 +8,95 @@ Every week the Kubernetes contributing community meet virtually over Google Hang

 Agenda:  

-* kubectl tooling, rolling update, deployments, imperative commands
-* Downward API / env. substitution, and maybe preconditions/dependencies
+* kubectl tooling, rolling update, deployments, imperative commands.
+* Downward API / env. substitution, and maybe preconditions/dependencies.


 **Notes from meeting:**  

 1\. kubectl improvements

-* make it simpler to use, finish rolling update, higher-level deployment concepts
+* make it simpler to use, finish rolling update, higher-level deployment concepts.
 * rolling update

    * today
-        * can replace one rc by another rc specified by a file
+        * can replace one rc by another rc specified by a file.

-        * no explicit support for rollback, can sort of do it by doing rolling update to old version
+        * no explicit support for rollback, can sort of do it by doing rolling update to old version.

-        * we keep annotations on rcs to keep track of desired # instances; won't work for rollback case b/c not symmetric
+        * we keep annotations on rcs to keep track of desired # instances; won't work for rollback case b/c not symmetric.

-    * need immutable image ids; currently no uuid that corresponds to image,version so if someone pushes on top you'll re-pull that; in API server we should translate images into uuids (as close to edge as possible)
+    * need immutable image ids; currently no uuid that corresponds to image,version so if someone pushes on top you'll re-pull that; in API server we should translate images into uuids (as close to edge as possible).

-    * would be nice to auto-gen new rc instead of having user update it (e.g. when change image tag for container, etc.; currently need to change rc name and label value; could automate generating new rc)
+    * would be nice to auto-gen new rc instead of having user update it (e.g. when change image tag for container, etc.; currently need to change rc name and label value; could automate generating new rc).

-    * treating rcs as pets vs. cattle
+    * treating rcs as pets vs. cattle.

    * "roll me from v1 to v2" (or v2 to v1) - good enough for most people. don't care about record of what happened in the past.

    * we're providing the module ansible can call to make something happen.

-    * how do you keep track of multiple templates; today we use multiple RCs
+    * how do you keep track of multiple templates; today we use multiple RCs.

-    * if we had a deployment controller ; deployment config spawns pos that runs rolling update; trigger is level-based update of image repository
+    * if we had a deployment controller; deployment config spawns pos that runs rolling update; trigger is level-based update of image repository.

-    * alternative short-term proposal: create new rc as clone of old one, futz with counts so new one is old one and vv, bring prev-named one (pet) down to zero and bring it back up with new template (this is very similar to how Borg does job updates)
-        * is it worthwhile if we want to have the deployments anyway? yes b/c we have lots of concepts already; need to simplify
+    * alternative short-term proposal: create new rc as clone of old one, futz with counts so new one is old one and vv, bring prev-named one (pet) down to zero and bring it back up with new template (this is very similar to how Borg does job updates).
+        * is it worthwhile if we want to have the deployments anyway? Yes b/c we have lots of concepts already; need to simplify.

-    * deployment controller keeps track of multiple templates which is what you need for rolling updates and canaries
+    * deployment controller keeps track of multiple templates which is what you need for rolling updates and canaries.

    * only reason for new thing is to move the process into the server instead of the client?

-    * may not need to make it an API object; should provide experience where it's not an API object and is just something client side
+    * may not need to make it an API object; should provide experience where it's not an API object and is just something client side.

-    * need an experience now so need to do it in client because object won't land before 1.0
+    * need an experience now so need to do it in client because object won't land before 1.0.

-    * having simplified experience for people who only want to enageg w/ RCs
+    * having simplified experience for people who only want to enageg w/ RCs.

    * how does rollback work: ctrl-c, rollout v2 v1. rollback pattern can be in person's head. 2 kinds of rollback: i'm at steady state and want to go back, and i've got canary deployment and hit ctrl-c how do i get rid of the canary deployment (e.g. new is failing). ctrl-c might not work. delete canary controller and its pods. wish there was a command to also delete pods (there is -- kbectl stop). argument for not reusing name: when you move fwd you can stop the new thing and you're ok, vs. if you replace the old one and you've created a copy if you hit ctrl-c you don't have anything you can stop. but you could wait to flip the name until the end, use naming convention so can figure out what is going on, etc.

-    * two different experiences: (1) i'm using version control, have version history of last week rollout this week, rolling update with two files -> create v2, ??? v1, don't have a pet - moved into world of version control where have cumulative history and; (1) imperative kubectl v1 v2 where sys takes care of details, that's where we use the snapshot pattern
+    * two different experiences: (1) i'm using version control, have version history of last week rollout this week, rolling update with two files -> create v2, ??? v1, don't have a pet - moved into world of version control where have cumulative history and; (1) imperative kubectl v1 v2 where sys takes care of details, that's where we use the snapshot pattern.

 * other imperative commands

    * run-container (or just run): spec command on command line which makes it more similar to docker run; but not multi-container pods.

-    * \--forever vs. not (one shot exec via simple commad)
+    * \--forever vs. not (one shot exec via simple command).

    * would like it go interactive - run -it and runs in cluster but you have interactive terminal to your process.

    * how do command line args work. could say --image multiple times. will cobra support? in openshift we have clever syntax for grouping arguments together. doesn't work for real structured parameters.

-    * alternative: create pod; add container add container ...; run pod -- build and don't run object until 'run pod'
+    * alternative: create pod; add container add container ...; run pod -- build and don't run object until 'run pod'.

-        * \-- to separate container args
+        * \-- to separate container args.

-        * create a pod, mutate it before you run it - like initializer pattern
+        * create a pod, mutate it before you run it - like initializer pattern.
 * kind discovery

-    * if we have run and sometimes it creates an rc and sometimes it doesn't, how does user know what to delete if they want to delete whatever they created with run
+    * if we have run and sometimes it creates an rc and sometimes it doesn't, how does user know what to delete if they want to delete whatever they created with run.

-    * bburns has proposal for don't specify kind if you do command like stop, delete; let kubectl figure it out
+    * bburns has proposal for don't specify kind if you do command like stop, delete; let kubectl figure it out.

-    * alternative: allow you to define alias from name to set of resource types, eg. delete all which would follow that alias (all could mean everything in some namespace, or unscoped, etc.) - someone explicitly added something to a set vs. accidentally showed up like nodes
+    * alternative: allow you to define alias from name to set of resource types, eg. delete all which would follow that alias (all could mean everything in some namespace, or unscoped, etc.) - someone explicitly added something to a set vs. accidentally showed up like nodes.

    * would like to see extended to allow tools to specify their own aliases (not just users); e.g. resize can say i can handle RCs, delete can say I can handle everything, et.c so we can automatically do these things w/o users have to specify stuff. but right mechanism.

-    * resourcebuilder has conept of doing that kind of expansion depending on how we fit in targeted commands. for instance if you want to add a volume to pods and rcs, you need something to go find the pod template and change it. there's the search part of it (delete nginx -> you have to figure out what object they are referring to) and then command can say i got a pod i know what to do with a pod.
+    * resourcebuilder has concept of doing that kind of expansion depending on how we fit in targeted commands. for instance if you want to add a volume to pods and rcs, you need something to go find the pod template and change it. there's the search part of it (delete nginx -> you have to figure out what object they are referring to) and then command can say i got a pod i know what to do with a pod.

    * alternative heuristic: what if default target of all commands was deployments. kubectl run -> deployment. too much work, easier to clean up existing CLI. leave door open for that. macro objects OK but a lot more work to make that work. eventually will want index to make these efficient. could rely more on swagger to tell us types.

 2\. paul/downward api: env substitution

-  * create ad-hoc env var like strings, e.g. k8s_pod_name that would get sub'd by system in objects
-  * allow people to create env vars that refer to fields of k8s objects w/o query api from inside their container; in some caes enables query api from their container (e.g. pass obj names, namespaces); e.g. sidecar containers need this for pulling things from api server
+  * create ad-hoc env var like strings, e.g. k8s_pod_name that would get sub'd by system in objects.
+  * allow people to create env vars that refer to fields of k8s objects w/o query api from inside their container; in some cases enables query api from their container (e.g. pass obj names, namespaces); e.g. sidecar containers need this for pulling things from api server.
  * another proposal similar: instead of env var like names, have JSON-path-like syntax for referring to object field names; e.g. $.[metadata.name][1] to refer to name of current object, maybe have some syntax for referring to related objects like node that a pod is on. advantage of JSON path-like syntax is that it's less ad hoc. disadvantage is that you can only refer to things that are fields of objects.
  * for both, if you populate env vars then you have drawback that fields only set when container is created. but least degree of coupling -- off the shelf containers, containers don't need to know how to talk to k8s API. keeps the k8s concepts in the control plane.
  * we were converging on JSON path like approach. but need prototype or at least deeper proposal to demo.
  * paul: one variant is for env vars in addition to value field have different sources which is where you would plug in e.g. syntax you use to describe a field of an object; another source would be a source that described info about the host. have partial prototype. clean separation between what's in image vs. control plane. could use source idea for volume plugin.
-  * use case: provide info for sidecar container to contact API server
-  * use case: pass down unique identifiers or things like using UID as nique identifier
-  * clayton: for rocket or gce metadata service being available for every pod for more sophisticated things; most containers want to find endpoint of service,
+  * use case: provide info for sidecar container to contact API server.
+  * use case: pass down unique identifiers or things like using UID as unique identifier.
+  * clayton: for rocket or gce metadata service being available for every pod for more sophisticated things; most containers want to find endpoint of service.

 3\. preconditions/dependencies

@@ -104,8 +104,8 @@ Agenda:
 * infer automatically if we ask people to declare which env vars they wanted, or have dep mech at pod or rc or obj level to say this obj doesn't become active until this other thing exists.
 * can use event hook? only app owner knows their dependency or when service is ready to serve.
 * one proposal is to use pre-start hook. another is precondition probe - pre-start hook could do a probe. does anything respond when i hit this svc address or ip, then probe fails. could be implemented in pre-start hook. more useful than post-start. is part of rkt spec. has stages 0, 1, 2. hard to do in docker today, easy in rocket.
-* pre-start hook in container: how will affect readiness probe since the container might have a lock until some arbitrary condition is met if you implement with prestart hook. there has to be some compensation on when kubelet runs readiness/liveness probes if you have a hook. systemd has timeouts around the stages of process lifecycle.
-* if we go to black box model of container pre-start makes sense; if container spec becomes more descriptive of process model like systemd, then does kubelet need to know more about process model to do the right thing
+* pre-start hook in container: how will affect readiness probe since the container might have a lock until some arbitrary condition is met if you implement with prestart hook. there has to be some compensation on when kubelet runs readiness/liveness probes if you have a hook. Systemd has timeouts around the stages of process lifecycle.
+* if we go to black box model of container pre-start makes sense; if container spec becomes more descriptive of process model like systemd, then does kubelet need to know more about process model to do the right thing.
 * ideally msg from inside the container to say i've done all of my pre-start actions. sdnotify for systemd does this. you tell systemd that you're done, it will communicate to other deps that you're alive.
 * but... someone could just implement preconds inside their container. makes it easier to adapt an app w/o having to change their image. alternative is just have a pattern how they do it themselves but we don't do it for them.

@@ -69,7 +69,7 @@ $ docker ps

 CONTAINER ID        IMAGE                                           COMMAND                  CREATED             STATUS              PORTS               NAMES

-a17784253dd2        gcr.io/google\_containers/hyperkube-arm:v1.1.2   "/hyperkube controlle"   2 hours ago         Up 2 hours                              k8s\_controller-manager.7042038a\_k8s-master-127.0.0.1\_default\_43160049df5e3b1c5ec7bcf23d4b97d0\_2174a7c3
+a17784253dd2        gcr.io/google\_containers/hyperkube-arm:v1.1.2   "/hyperkube controller"   2 hours ago         Up 2 hours                              k8s\_controller-manager.7042038a\_k8s-master-127.0.0.1\_default\_43160049df5e3b1c5ec7bcf23d4b97d0\_2174a7c3

 a0fb6a169094        gcr.io/google\_containers/hyperkube-arm:v1.1.2   "/hyperkube scheduler"   2 hours ago         Up 2 hours                              k8s\_scheduler.d905fc61\_k8s-master-127.0.0.1\_default\_43160049df5e3b1c5ec7bcf23d4b97d0\_511945f8

@@ -105,7 +105,9 @@ $ gsutil mb gs://my-spark-models
 ```
 You’ll need to change this URI to something that is unique for you. This will create a bucket that you can use in the example above.  

-**Note** : Computing the model and saving it is much slower than computing the model and throwing it away. This is expected. However, if you plan to reuse a model, it’s faster to compute the model and save it and then restore it each time you want to use it, rather than throw away and recompute the model each time.  
+{{< note >}}
+Computing the model and saving it is much slower than computing the model and throwing it away. This is expected. However, if you plan to reuse a model, it’s faster to compute the model and save it and then restore it each time you want to use it, rather than throw away and recompute the model each time.
+{{< /note >}}

 ### Using Horizontal Pod Autoscaling with Spark (Optional)&nbsp;
 Spark is somewhat elastic to workers coming and going, which means we have an opportunity: we can use use [Kubernetes Horizontal Pod Autoscaling](http://kubernetes.io/docs/user-guide/horizontal-pod-autoscaling/) to scale-out the Spark worker pool automatically, setting a target CPU threshold for the workers and a minimum/maximum pool size. This obviates the need for having to configure the number of worker replicas manually.  
@@ -328,7 +328,7 @@ Standard Kubernetes service cluster-IP's already ensure that non-responsive indi

 We'd love to hear feedback on Kubernetes Cross Cluster Services. To join the community:

- Post issues or feature requests on [GitHub](https://github.com/kubernetes/kubernetes/tree/master/federation)
+- Post issues or feature requests on [GitHub](https://github.com/kubernetes/kubernetes/tree/release-1.8/federation)
 - Join us in the #federation channel on [Slack](https://kubernetes.slack.com/messages/sig-federation)
 - Participate in the [Cluster Federation SIG](https://groups.google.com/forum/#!forum/kubernetes-sig-federation)

@@ -10,7 +10,7 @@ With more than a thousand people coming to [KubeCon](http://events.linuxfoundati
  
 Today, Microsoft [announced](https://azure.microsoft.com/en-us/blog/azure-container-service-the-cloud-s-most-open-option-for-containers/) the next step in Kubernetes on Azure: the introduction of Kubernetes as a supported orchestrator in Azure Container Service (ACS). It’s been really exciting for me to join the ACS team and help build this new addition. The integration of Kubernetes into ACS means that with a few clicks in the Azure portal, or by running a single command in the new python-based Azure command line tool, you will be able to create a fully functional Kubernetes cluster that is integrated with the rest of your Azure resources.  
  
-Kubernetes is availabe in public preview in Azure Container Service today. Community participation has always been an important part of the Kubernetes experience. Over the next few months, I hope you’ll join us and provide your feedback on the experience as we bring it to general availability.  
+Kubernetes is available in public preview in Azure Container Service today. Community participation has always been an important part of the Kubernetes experience. Over the next few months, I hope you’ll join us and provide your feedback on the experience as we bring it to general availability.  
  
 In the spirit of community, we are also excited to announce a new open source project: [ACS Engine](https://github.com/azure/acs-engine). The goal of ACS Engine is to provide an open, community driven location to develop and share best practices for orchestrating containers on Azure. All of our knowledge of running containers in Azure has been captured in that repository, and we look forward to improving and extending it as we move forward with the community. Going forward, the templates in ACS Engine will be the basis for clusters deployed via the ACS API, and thus community driven improvements, features and more will have a natural path into the Azure Container Service. We’re excited to invite you to join us in improving ACS. Prior to the creation of ACS Engine, customers with unique requirements not supported by the ACS API needed to maintain variations on our templates. While these differences start small, they grew larger over time as the mainline template was improved and users also iterated their templates. These differences and drift really impact the ability for users to collaborate, since their templates are all different. Without the ability to share and collaborate, it’s difficult to form a community since every user is siloed in their own variant.  
  
@@ -16,12 +16,10 @@ In Kubernetes, the base unit of scheduling is a Pod: one or more Docker containe

 Traditional HPC applications often exhibit different characteristics:

-
-In financial or engineering simulations, a job may be comprised of tens of thousands of short-running tasks, demanding low-latency and high-throughput scheduling to complete a simulation in an acceptable amount of time.
-
-A computational fluid dynamics (CFD) problem may execute in parallel across many hundred or even thousands of nodes using a message passing library to synchronize state. This requires specialized scheduling and job management features to allocate and launch such jobs and then to checkpoint, suspend/resume or backfill them.
-
-Other HPC workloads may require specialized resources like GPUs or require access to limited software licenses. Organizations may enforce policies around what types of resources can be used by whom to ensure projects are adequately resourced and deadlines are met.
+- In financial or engineering simulations, a job may be comprised of tens of thousands of short-running tasks, demanding low-latency and high-throughput scheduling to complete a simulation in an acceptable amount of time.
+- A computational fluid dynamics (CFD) problem may execute in parallel across many hundred or even thousands of nodes using a message passing library to synchronize state. This requires specialized scheduling and job management features to allocate and launch such jobs and then to checkpoint, suspend/resume or backfill them.
+- Other HPC workloads may require specialized resources like GPUs or require access to limited software licenses. Organizations may enforce policies around what types of resources can be used by whom to ensure projects are adequately resourced and deadlines are met.
+
 HPC workload schedulers have evolved to support exactly these kinds of workloads. Examples include [Univa Grid Engine](http://www.univa.com/products/), [IBM Spectrum LSF](https://www-03.ibm.com/systems/spectrum-computing/products/lsf/) and Altair’s [PBS Professional](http://www.pbsworks.com/PBSProduct.aspx?n=PBS-Professional&c=Overview-and-Capabilities). Sites managing HPC workloads have come to rely on capabilities like array jobs, configurable pre-emption, user, group or project based quotas and a variety of other features.  

 ## Blurring the lines between containers and HPC
@@ -36,18 +34,15 @@ While the notion of packaging a workload into a Docker container, publishing it

 To deal with the challenges of migrating to containers, organizations running container and HPC workloads have several options:

-
-Maintain separate infrastructures
+- Maintain separate infrastructures

 For sites with sunk investments in HPC, this may be a preferred approach. Rather than disrupt existing environments, it may be easier to deploy new containerized applications on a separate cluster and leave the HPC environment alone. The challenge is that this comes at the cost of siloed clusters, increasing infrastructure and management cost.

-
-Run containerized workloads under an existing HPC workload manager
+- Run containerized workloads under an existing HPC workload manager

 For sites running traditional HPC workloads, another approach is to use existing job submission mechanisms to launch jobs that in turn instantiate Docker containers on one or more target hosts. Sites using this approach can introduce containerized workloads with minimal disruption to their environment. Leading HPC workload managers such as [Univa Grid Engine Container Edition](http://blogs.univa.com/2016/05/new-version-of-univa-grid-engine-now-supports-docker-containers/) and [IBM Spectrum LSF](http://blogs.univa.com/2016/05/new-version-of-univa-grid-engine-now-supports-docker-containers/) are adding native support for Docker containers. [Shifter](https://github.com/NERSC/shifter) and [Singularity](http://singularity.lbl.gov/) are important open source tools supporting this type of deployment also. While this is a good solution for sites with simple requirements that want to stick with their HPC scheduler, they will not have access to native Kubernetes features, and this may constrain flexibility in managing long-running services where Kubernetes excels.

-
-Use native job scheduling features in Kubernetes
+- Use native job scheduling features in Kubernetes

 Sites less invested in existing HPC applications can use existing scheduling facilities in Kubernetes for [jobs that run to completion](https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/). While this is an option, it may be impractical for many HPC users. HPC applications are often either optimized towards massive throughput or large scale parallelism. In both cases startup and teardown latencies have a discriminating impact. Latencies that appear to be acceptable for containerized microservices today would render such applications unable to scale to the required levels.

@@ -75,7 +70,4 @@ One client having success with mixed workloads is the Institute for Health Metri

 ![](https://lh5.googleusercontent.com/GJeP6e89r6drl72yzZM_OsZ81MYDp7Zm5xEFpItpmioian3lOp535H4jy1_eELKrzGMYr_wnjGwpK3Uku9dwg2-vqmMC1A1GrMtJc-PZR6GR6Z-fAZNJMEr_Uw3HqvWvi86mF_63XTozysaLpg)

-
-
-
 For sites deploying new clusters that want access to the rich capabilities in Kubernetes but need the flexibility to run non-containerized workloads, this approach is worth a look. It offers the opportunity for sites to share infrastructure between Kubernetes and HPC workloads without disrupting existing applications and businesses processes. It also allows them to migrate their HPC workloads to use Docker containers at their own pace.
@@ -14,7 +14,7 @@ While many improvements have been contributed, we highlight key features in this

 **Day 1:** [5 Days of Kubernetes 1.8](https://kubernetes.io/blog/2017/10/five-days-of-kubernetes-18)  
 **Day 2:** [kubeadm v1.8 Introduces Easy Upgrades for Kubernetes Clusters](https://kubernetes.io/blog/2017/10/kubeadm-v18-released)  
-**Day 3:** [Kuberentes v.1.8 Retrospective: It Takes a Village to Raise a Kubernetes](https://kubernetes.io/blog/2017/10/it-takes-village-to-raise-kubernetes)  
+**Day 3:** [Kubernetes v.1.8 Retrospective: It Takes a Village to Raise a Kubernetes](https://kubernetes.io/blog/2017/10/it-takes-village-to-raise-kubernetes)
 **Day 4:** [Using RBAC, Generally Available in Kubernetes v1.8](https://kubernetes.io/blog/2017/10/using-rbac-generally-available-18)  
 **Day 5:** [Enforcing Network Policies in Kubernetes](https://kubernetes.io/blog/2017/10/enforcing-network-policies-in-kubernetes)  

@@ -111,7 +111,7 @@ For the self-hosted category, a cleverly built webhook admission server and topo
 ### Simple, secure, portable, zero-config topology
 If you build your webhook admission server to also be an extension API server, it becomes possible to aggregate it as a normal API server. This has a number of advantages:  

- Your webhook becomes available like any other API under default kube-apiserver service `kubernetes.default.svc` (e.g. [https://kubernetes.default.svc/apis/admission.example.com/v1/mymutatingadmissionreviews](https://kuberentes.default.svc/apis/admission.example.com/v1/mymutatingadmissionreviews)). Among other benefits, you can test using `kubectl`.
+- Your webhook becomes available like any other API under default kube-apiserver service `kubernetes.default.svc` (e.g. [https://kubernetes.default.svc/apis/admission.example.com/v1/mymutatingadmissionreviews](https://kubernetes.default.svc/apis/admission.example.com/v1/mymutatingadmissionreviews)). Among other benefits, you can test using `kubectl`.
 - Your webhook automatically (without any config) makes use of the in-cluster authentication and authorization provided by kube-apiserver. You can restrict access to your webhook with normal RBAC rules.
 - Your extension API servers and kube-apiserver automatically (without any config) make use of their in-cluster credentials to communicate with the webhook.
 - Extension API servers do not leak their service account token to your webhook because they go through kube-apiserver, which is a secure front proxy.
@@ -137,7 +137,7 @@ However, this design is prone to the classic time-of-check-to-time-of-use ([TOCT

 We went a bit wild with this idea:

-* Create a working directory under the kubelet’s pod directory. Let’s  call it `dir1`.
+* Create a working directory under the kubelet’s pod directory. Let’s call it `dir1`.
 * Bind mount the base volume to under the working directory, `dir1/volume`.
 * Chroot to the working directory `dir1`.
 * Inside the chroot, bind mount `volume/subpath` to `subpath`.  This ensures that any symlinks get resolved to inside the chroot environment.
@@ -30,7 +30,7 @@ You can submit a blog post for consideration one of two ways:
 If you have a post that you want to remain confidential until your publish date, please submit your post via the Google form. Otherwise, you can choose your submission process based on your comfort level and preferred workflow.

 {{< note >}}
-**Note:** Our workflow hasn't changed for confidential advance drafts. Additionally, we'll coordinate publishing for time sensitive posts to ensure that information isn't released prematurely through an open pull request.
+Our workflow hasn't changed for confidential advance drafts. Additionally, we'll coordinate publishing for time sensitive posts to ensure that information isn't released prematurely through an open pull request.
 {{< /note >}}

 ### Call for reviewers
@@ -50,7 +50,7 @@ Autoscaling Kubernetes nodes was historically difficult, as each node requires a

 <img src="/images/blog/2018-06-05-11-ways-not-to-get-hacked/rbac2.png" width="800" />

-Kubernetes' ABAC (Attribute Based Access Control) has been [superseded by RBAC](http://blog.kubernetes.io/2017/04/rbac-support-in-kubernetes.html) since release 1.6, and should not be enabled on the API server. Use RBAC instead:
+Kubernetes' ABAC (Attribute Based Access Control) has been [superseded by RBAC](http://kubernetes.io/blog/2017/04/rbac-support-in-kubernetes.html) since release 1.6, and should not be enabled on the API server. Use RBAC instead:

 ```
 --authorization-mode=RBAC
@@ -0,0 +1,58 @@
+---
+layout: blog
+title: 'Kubernetes Docs Updates, International Edition'
+date: 2018-11-08
+---
+
+**Author**: Zach Corleissen (Linux Foundation)
+
+As a co-chair of SIG Docs, I'm excited to share that Kubernetes docs have a fully mature workflow for localization (l10n). 
+
+## Abbreviations galore
+
+L10n is an abbreviation for _localization_. 
+
+I18n is an abbreviation for _internationalization_. 
+
+I18n is [what you do](https://www.w3.org/International/questions/qa-i18n) to make l10n easier. L10n is a fuller, more comprehensive process than translation (_t9n_). 
+
+## Why localization matters
+
+The goal of SIG Docs is to make Kubernetes easier to use for as many people as possible.
+
+One year ago, we looked at whether it was possible to host the output of a Chinese team working independently to translate the Kubernetes docs. After many conversations (including experts on OpenStack l10n), [much transformation](https://kubernetes.io/blog/2018/05/05/hugo-migration/), and [renewed commitment to easier localization](https://github.com/kubernetes/website/pull/10485), we realized that open source documentation is, like open source software, an ongoing exercise at the edges of what's possible. 
+
+Consolidating workflows, language labels, and team-level ownership may seem like simple improvements, but these features make l10n scalable for increasing numbers of l10n teams. While SIG Docs continues to iterate improvements, we've paid off a significant amount of technical debt and streamlined l10n in a single workflow. That's great for the future as well as the present.
+
+## Consolidated workflow
+
+Localization is now consolidated in the [kubernetes/website](https://github.com/kubernetes/website) repository. We've configured the Kubernetes CI/CD system, [Prow](https://github.com/kubernetes/test-infra/tree/master/prow), to handle automatic language label assignment as well as team-level PR review and approval.
+
+### Language labels 
+
+Prow automatically applies language labels based on file path. Thanks to SIG Docs contributor [June Yi](https://github.com/kubernetes/test-infra/pull/9835), folks can also manually assign language labels in pull request (PR) comments. For example, when left as a comment on an issue or PR, this command assigns the label `language/ko` (Korean).
+
+
+```
+/language ko
+```
+ 
+These repo labels let reviewers filter for PRs and issues by language. For example, you can now filter the k/website dashboard for [PRs with Chinese content](https://github.com/kubernetes/website/pulls?utf8=%E2%9C%93&q=is%3Aopen+is%3Apr+label%3Alanguage%2Fzh).  
+
+### Team review 
+
+L10n teams can now review and approve their own PRs. For example, review and approval permissions for English are [assigned in an OWNERS file](https://github.com/kubernetes/website/blob/master/content/en/OWNERS) in the top subfolder for English content. 
+
+Adding `OWNERS` files to subdirectories lets localization teams review and approve changes without requiring a rubber stamp approval from reviewers who may lack fluency.
+
+## What's next
+
+We're looking forward to the [doc sprint in Shanghai](https://kccncchina2018english.sched.com/event/HVb2/contributor-summit-doc-sprint-additional-registration-required) to serve as a resource for the Chinese l10n team.
+
+We're excited to continue supporting the Japanese and Korean l10n teams, who are making excellent progress.
+
+If you're interested in localizing Kubernetes for your own language or region, check out our [guide to localizing Kubernetes docs](https://kubernetes.io/docs/contribute/localization/) and reach out to a [SIG Docs chair](https://github.com/kubernetes/community/tree/master/sig-docs#leadership) for support.
+
+### Get involved with SIG Docs 
+
+If you're interested in Kubernetes documentation, come to a SIG Docs [weekly meeting](https://github.com/kubernetes/community/tree/master/sig-docs#meetings), or join [#sig-docs in Kubernetes Slack](https://kubernetes.slack.com/messages/C1J0BPD2M/details/).
@@ -0,0 +1,172 @@
+---
+layout: blog
+title: 'gRPC Load Balancing on Kubernetes without Tears'
+date: 2018-11-07
+---
+
+**Author**: William Morgan (Buoyant)
+
+Many new gRPC users are surprised to find that Kubernetes's default load
+balancing often doesn't work out of the box with gRPC. For example, here's what
+happens when you take a [simple gRPC Node.js microservices
+app](https://github.com/sourishkrout/nodevoto) and deploy it on Kubernetes:
+
+![](/images/blog/grpc-load-balancing-with-linkerd/Screenshot2018-11-0116-c4d86100-afc1-4a08-a01c-16da391756dd.34.36.png)
+
+While the `voting` service displayed here has several pods, it's clear from
+Kubernetes's CPU graphs that only one of the pods is actually doing any
+work&mdash;because only one of the pods is receiving any traffic. Why?
+
+In this blog post, we describe why this happens, and how you can easily fix it
+by adding gRPC load balancing to any Kubernetes app with
+[Linkerd](https://linkerd.io), a [CNCF](https://cncf.io) service mesh and service sidecar.
+
+# Why does gRPC need special load balancing?
+
+First, let's understand why we need to do something special for gRPC.
+
+gRPC is an increasingly common choice for application developers. Compared to
+alternative protocols such as JSON-over-HTTP, gRPC can provide some significant
+benefits, including dramatically lower (de)serialization costs, automatic type
+checking, formalized APIs, and less TCP management overhead.
+
+However, gRPC also breaks the standard connection-level load balancing,
+including what's provided by Kubernetes. This is because gRPC is built on
+HTTP/2, and HTTP/2 is designed to have a single long-lived TCP connection,
+across which all requests are *multiplexed*&mdash;meaning multiple requests can be
+active on the same connection at any point in time. Normally, this is great, as
+it reduces the overhead of connection management. However, it also means that
+(as you might imagine) connection-level balancing isn't very useful. Once the
+connection is established, there's no more balancing to be done. All requests
+will get pinned to a single destination pod, as shown below:
+
+![](/images/blog/grpc-load-balancing-with-linkerd/Mono-8d2e53ef-b133-4aa0-9551-7e36a880c553.png)
+
+# Why doesn't this affect HTTP/1.1?
+
+The reason why this problem doesn't occur in HTTP/1.1, which also has the
+concept of long-lived connections, is because HTTP/1.1 has several features
+that naturally result in cycling of TCP connections. Because of this,
+connection-level balancing is "good enough", and for most HTTP/1.1 apps we
+don't need to do anything more.
+
+To understand why, let's take a deeper look at HTTP/1.1. In contrast to HTTP/2,
+HTTP/1.1 cannot multiplex requests. Only one HTTP request can be active at a
+time per TCP connection. The client makes a request, e.g. `GET /foo`, and then
+waits until the server responds. While that request-response cycle is
+happening, no other requests can be issued on that connection.
+
+Usually, we want lots of requests happening in parallel. Therefore, to have
+concurrent HTTP/1.1 requests, we need to make multiple HTTP/1.1 connections,
+and issue our requests across all of them. Additionally, long-lived HTTP/1.1
+connections typically expire after some time, and are torn down by the client
+(or server). These two factors combined mean that HTTP/1.1 requests typically
+cycle across multiple TCP connections, and so connection-level balancing works.
+
+# So how do we load balance gRPC?
+
+Now back to gRPC. Since we can't balance at the connection level, in order to
+do gRPC load balancing, we need to shift from connection balancing to *request*
+balancing. In other words, we need to open an HTTP/2 connection to each
+destination, and balance *requests* across these connections, as shown below:
+
+![](/images/blog/grpc-load-balancing-with-linkerd/Stereo-09aff9d7-1c98-4a0a-9184-9998ed83a531.png)
+
+In network terms, this means we need to make decisions at L5/L7 rather than
+L3/L4, i.e. we need to understand the protocol sent over the TCP connections. 
+
+How do we accomplish this? There are a couple options. First, our application
+code could manually maintain its own load balancing pool of destinations, and
+we could configure our gRPC client to [use this load balancing
+pool](https://godoc.org/google.golang.org/grpc/balancer). This approach gives
+us the most control, but it can be very complex in environments like Kubernetes
+where the pool changes over time as Kubernetes reschedules pods. Our
+application would have to watch the Kubernetes API and keep itself up to date
+with the pods.
+
+Alternatively, in Kubernetes, we could deploy our app as [headless
+services](https://kubernetes.io/docs/concepts/services-networking/service/#headless-services).
+In this case, Kubernetes [will create multiple A
+records](https://kubernetes.io/docs/concepts/services-networking/service/#headless-services)
+in the DNS entry for the service. If our gRPC client is sufficiently advanced,
+it can automatically maintain the load balancing pool from those DNS entries.
+But this approach restricts us to certain gRPC clients, and it's rarely
+possible to only use headless services.
+
+Finally, we can take a third approach: use a lightweight proxy.
+
+# gRPC load balancing on Kubernetes with Linkerd
+
+[Linkerd](https://linkerd.io) is a [CNCF](https://cncf.io)-hosted *service
+mesh* for Kubernetes. Most relevant to our purposes, Linkerd also functions as
+a *service sidecar*, where it can be applied to a single service&mdash;even without
+cluster-wide permissions. What this means is that when we add Linkerd to our
+service, it adds a tiny, ultra-fast proxy to each pod, and these proxies watch
+the Kubernetes API and do gRPC load balancing automatically. Our deployment
+then looks like this:
+
+![](/images/blog/grpc-load-balancing-with-linkerd/Linkerd-8df1031c-cdd1-4164-8e91-00f2d941e93f.io.png)
+
+Using Linkerd has a couple advantages. First, it works with services written in
+any language, with any gRPC client, and any deployment model (headless or not).
+Because Linkerd's proxies are completely transparent, they auto-detect HTTP/2
+and HTTP/1.x and do L7 load balancing, and they pass through all other traffic
+as pure TCP. This means that everything will *just work.*
+
+Second, Linkerd's load balancing is very sophisticated. Not only does Linkerd
+maintain a watch on the Kubernetes API and automatically update the load
+balancing pool as pods get rescheduled, Linkerd uses an *exponentially-weighted
+moving average* of response latencies to automatically send requests to the
+fastest pods. If one pod is slowing down, even momentarily, Linkerd will shift
+traffic away from it. This can reduce end-to-end tail latencies.
+
+Finally, Linkerd's Rust-based proxies are incredibly fast and small. They
+introduce <1ms of p99 latency and require <10mb of RSS per pod, meaning that
+the impact on system performance will be negligible.
+
+# gRPC Load Balancing in 60 seconds
+
+Linkerd is very easy to try. Just follow the steps in the [Linkerd Getting
+Started Instructions](https://linkerd.io/2/getting-started/)&mdash;install the
+CLI on your laptop, install the control plane on your cluster, and "mesh" your
+service (inject the proxies into each pod). You'll have Linkerd running on your
+service in no time, and should see proper gRPC balancing immediately.
+
+Let's take a look at our sample `voting` service again, this time after
+installing Linkerd:
+
+![](/images/blog/grpc-load-balancing-with-linkerd/Screenshot2018-11-0116-24b8ee81-144c-4eac-b73d-871bbf0ea22e.57.42.png)
+
+As we can see, the CPU graphs for all pods are active, indicating that all pods
+are now taking traffic&mdash;without having to change a line of code. Voila,
+gRPC load balancing as if by magic!
+
+Linkerd also gives us built-in traffic-level dashboards, so we don't even need
+to guess what's happening from CPU charts any more. Here's a Linkerd graph
+that's showing the success rate, request volume, and latency percentiles of
+each pod:
+
+![](/images/blog/grpc-load-balancing-with-linkerd/Screenshot2018-11-0212-15ed0448-5424-4e47-9828-20032de868b5.08.38.png)
+
+We can see that each pod is getting around 5 RPS. We can also see that, while
+we've solved our load balancing problem, we still have some work to do on our
+success rate for this service. (The demo app is built with an intentional
+failure&mdash;as an exercise to the reader, see if you can figure it out by
+using the Linkerd dashboard!)
+
+# Wrapping it up
+
+If you're interested in a dead simple way to add gRPC load balancing to your
+Kubernetes services, regardless of what language it's written in, what gRPC
+client you're using, or how it's deployed, you can use Linkerd to add gRPC load
+balancing in a few commands.
+
+There's a lot more to Linkerd, including security, reliability, and debugging
+and diagnostics features, but those are topics for future blog posts.
+
+Want to learn more? We’d love to have you join our rapidly-growing community!
+Linkerd is a [CNCF](https://cncf.io) project, [hosted on
+GitHub](https://github.com/linkerd/linkerd2), and has a thriving community
+on [Slack](https://slack.linkerd.io), [Twitter](https://twitter.com/linkerd),
+and the [mailing lists](https://lists.cncf.io/g/cncf-linkerd-users). Come and
+join the fun!
@@ -10,7 +10,7 @@ cid: community
            <h3>Ensuring Kubernetes works well everywhere and for everyone.</h3>
            <p>Connect with the Kubernetes community on our <a href="http://slack.k8s.io/">Slack channel</a>, <a href="https://discuss.kubernetes.io/">discussion board</a>, or join the
                <a href="https://groups.google.com/forum/#!forum/kubernetes-dev">Kubernetes-dev Google group</a>. A weekly
-                community meeting takes place via video conference to discuss the state of affairs, see 
+                community meeting takes place via video conference to discuss the state of affairs, see
 		<a href="https://github.com/kubernetes/community/blob/master/events/community-meeting.md">these instructions</a> for information
 	        on how to participate.</p>
            <p>You can also join Kubernetes all around the world through our
@@ -26,18 +26,9 @@ cid: community

            <p>As a member of the Kubernetes community, you are welcome to join any of the SIG meetings
                you are interested in. No registration required.</p>
-           <!-- <div id="calendarMeetings">
-                <iframe src="https://calendar.google.com/calendar/embed?src=cgnt364vd8s86hr2phapfjc6uk%40group.calendar.google.com&ctz=America/Los_Angeles"
-                        frameborder="0" scrolling="no"></iframe>
-            </div> -->
+
        </div>
-        <!-- <div class="content">
-            <h3>Events</h3>
-            <div id="calendarEvents">
-                <iframe src="https://calendar.google.com/calendar/embed?src=nt2tcnbtbied3l6gi2h29slvc0%40group.calendar.google.com&ctz=America/Los_Angeles"
-                        frameborder="0" scrolling="no"></iframe>
-            </div>
-        </div> -->
+
        <div class="content">
          <h3>Code of Conduct</h3>
          <p>The Kubernetes community values respect and inclusiveness, and
@@ -46,8 +37,8 @@ cid: community
             an event or meeting, in Slack, or in another communication
             mechanism, reach out to the <a href="https://github.com/kubernetes/community/tree/master/committee-code-of-conduct">Kubernetes Code of Conduct Committee</a>
             <a href="mailto:conduct@kubernetes.io">conduct@kubernetes.io</a>.
-             Your anonymity will be protected.</p>
-           </p>
+             Your anonymity will be protected.
+          </p>
         </div>
    </main>
 </section>
@@ -51,7 +51,7 @@ In version 1.9, the CCM runs the following controllers from the preceding list:
 Additionally, it runs another controller called the PersistentVolumeLabels controller. This controller is responsible for setting the zone and region labels on PersistentVolumes created in GCP and AWS clouds.

 {{< note >}}
-**Note:** Volume controller was deliberately chosen to not be a part of CCM. Due to the complexity involved and due to the existing efforts to abstract away vendor specific volume logic, it was decided that volume controller will not be moved to CCM.
+Volume controller was deliberately chosen to not be a part of CCM. Due to the complexity involved and due to the existing efforts to abstract away vendor specific volume logic, it was decided that volume controller will not be moved to CCM.
 {{< /note >}}

 The original plan to support volumes using CCM was to use Flex volumes to support pluggable volumes. However, a competing effort known as CSI is being planned to replace Flex.
@@ -109,7 +109,7 @@ The PersistentVolumeLabels controller moves the cloud-dependent functionality of

 ## Plugin mechanism

-The cloud controller manager uses Go interfaces to allow implementations from any cloud to be plugged in. Specifically, it uses the CloudProvider Interface defined [here](https://github.com/kubernetes/kubernetes/blob/master/pkg/cloudprovider/cloud.go).
+The cloud controller manager uses Go interfaces to allow implementations from any cloud to be plugged in. Specifically, it uses the CloudProvider Interface defined [here](https://github.com/kubernetes/cloud-provider/blob/9b77dc1c384685cb732b3025ed5689dd597a5971/cloud.go#L42-L62).

 The implementation of the four shared controllers highlighted above, and some scaffolding along with the shared cloudprovider interface, will stay in the Kubernetes core. Implementations specific to cloud providers will be built outside of the core and implement interfaces defined in the core.

@@ -77,7 +77,7 @@ To verify this connection, use the `--kubelet-certificate-authority` flag to
 provide the apiserver with a root certificate bundle to use to verify the
 kubelet's serving certificate.

-If that is not possible, use [SSH tunneling](/docs/concepts/architecture/master-node-communication/#ssh-tunnels)
+If that is not possible, use [SSH tunneling](/docs/tasks/access-application-cluster/port-forward-access-application-cluster/)
 between the apiserver and kubelet if required to avoid connecting over an
 untrusted or public network.

@@ -53,7 +53,6 @@ The `conditions` field describes the status of all `Running` nodes.
 | `PIDPressure`    | `True` if pressure exists on the processes -- that is, if there are too many processes on the node; otherwise `False` |
 | `DiskPressure`    | `True` if pressure exists on the disk size -- that is, if the disk capacity is low; otherwise `False` |
 | `NetworkUnavailable`    | `True` if the network for the node is not correctly configured, otherwise `False` |
-| `ConfigOK`    | `True` if the kubelet is correctly configured, otherwise `False` |

 The node condition is represented as a JSON object. For example, the following response describes a healthy node.

@@ -85,7 +84,7 @@ A Pod that does not have any tolerations gets scheduled according to the old mod
 tolerates the taints of a particular Node can be scheduled on that Node.

 {{< caution >}}
-**Caution:** Enabling this feature creates a small delay between the
+Enabling this feature creates a small delay between the
 time when a condition is observed and when a taint is created. This delay is usually less than one second, but it can increase the number of Pods that are successfully scheduled but rejected by the kubelet.
 {{< /caution >}}

@@ -129,7 +128,7 @@ services are running -- it is eligible to run a pod. Otherwise, it is
 ignored for any cluster activity until it becomes valid.

 {{< note >}}
-**Note:** Kubernetes keeps the object for the invalid node and keeps checking to see whether it becomes valid.
+Kubernetes keeps the object for the invalid node and keeps checking to see whether it becomes valid.
 You must explicitly delete the Node object to stop this process.
 {{< /note >}}

@@ -242,7 +241,7 @@ kubectl cordon $NODENAME
 ```

 {{< note >}}
-**Note:** Pods created by a DaemonSet controller bypass the Kubernetes scheduler
+Pods created by a DaemonSet controller bypass the Kubernetes scheduler
 and do not respect the unschedulable attribute on a node. This assumes that daemons belong on
 the machine even if it is being drained of applications while it prepares for a reboot.
 {{< /note >}}
@@ -1,5 +1,5 @@
 ---
-title: "Compute, Storage, and Networking Extensions"
-weight: 30
+title: "Cluster Administration"
+weight: 100
 ---

@@ -34,7 +34,7 @@ manually through `easyrsa`, `openssl` or `cfssl`.
    that is specified as the `--service-cluster-ip-range` argument for both the API server and
    the controller manager component. The argument `--days` is used to set the number of days
    after which the certificate expires.
-    The sample below also assume that you are using `cluster.local` as the default
+    The sample below also assumes that you are using `cluster.local` as the default
    DNS domain name.

        ./easyrsa --subject-alt-name="IP:${MASTER_IP},"\
@@ -71,7 +71,7 @@ manually through `easyrsa`, `openssl` or `cfssl`.
    with real values before saving this to a file (e.g. `csr.conf`).
    Note that the value for `MASTER_CLUSTER_IP` is the service cluster IP for the
    API server as described in previous subsection.
-    The sample below also assume that you are using `cluster.local` as the default
+    The sample below also assumes that you are using `cluster.local` as the default
    DNS domain name.

        [ req ]
@@ -186,7 +186,7 @@ Finally, add the same parameters into the API server start parameters.
    server as shown below. Be sure to replace the values in angle brackets with
    real values you want to use. The `MASTER_CLUSTER_IP` is the service cluster
    IP for the API server as described in previous subsection.
-    The sample below also assume that you are using `cluster.local` as the default
+    The sample below also assumes that you are using `cluster.local` as the default
    DNS domain name.

        {
@@ -96,7 +96,7 @@ Different settings can be applied to a load balancer service in AWS using _annot
 * `service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled`: Used on the service to enable or disable cross-zone load balancing.
 * `service.beta.kubernetes.io/aws-load-balancer-extra-security-groups`: Used on the service to specify additional security groups to be added to ELB created
 * `service.beta.kubernetes.io/aws-load-balancer-internal`: Used on the service to indicate that we want an internal ELB.
-* `service.beta.kubernetes.io/aws-load-balancer-proxy-protocol`: Used on the service to enable the proxy protocol on an ELB. Right now we only accept the value `*` which means enable the proxy protocol on all ELB backends. In the future we could adjust this to allow setting the proxy protocol only on certain backends.
+* `service.beta.kubernetes.io/aws-load-balancer-proxy-protocol`: Used on the service to enable the proxy protocol on an ELB. Right now we only accept the value `*` which means enabling the proxy protocol on all ELB backends. In the future we could adjust this to allow setting the proxy protocol only on certain backends.
 * `service.beta.kubernetes.io/aws-load-balancer-ssl-ports`: Used on the service to specify a comma-separated list of ports that will use SSL/HTTPS listeners. Defaults to `*` (all)

 The information for the annotations for AWS is taken from the comments on [aws.go](https://github.com/kubernetes/kubernetes/blob/master/pkg/cloudprovider/providers/aws/aws.go)
@@ -358,7 +358,9 @@ Note that the Kubernetes Node name must match the Photon VM name (or if `overrid

 ### Node Name

-The VSphere cloud provider uses the hostname of the node (as determined by the kubelet or overridden with `--hostname-override`) as the name of the Kubernetes Node object.
+The VSphere cloud provider uses the detected hostname of the node (as determined by the kubelet) as the name of the Kubernetes Node object.
+
+The `--hostname-override` parameter is ignored by the VSphere cloud provider.

 ## IBM Cloud Kubernetes Service

@@ -57,7 +57,9 @@ You can use `kubectl logs` to retrieve logs from a previous instantiation of a c

 Everything a containerized application writes to `stdout` and `stderr` is handled and redirected somewhere by a container engine. For example, the Docker container engine redirects those two streams to [a logging driver](https://docs.docker.com/engine/admin/logging/overview), which is configured in Kubernetes to write to a file in json format.

-**Note:** The Docker json logging driver treats each line as a separate message. When using the Docker logging driver, there is no direct support for multi-line messages. You need to handle multi-line messages at the logging agent level or higher.
+{{< note >}}
+The Docker json logging driver treats each line as a separate message. When using the Docker logging driver, there is no direct support for multi-line messages. You need to handle multi-line messages at the logging agent level or higher.
+{{< /note >}}

 By default, if a container restarts, the kubelet keeps one terminated container with its logs. If a pod is evicted from the node, all corresponding containers are also evicted, along with their logs.

@@ -81,13 +83,15 @@ When you run [`kubectl logs`](/docs/reference/generated/kubectl/kubectl-commands
 the basic logging example, the kubelet on the node handles the request and
 reads directly from the log file, returning the contents in the response.

-**Note:** Currently, if some external system has performed the rotation,
+{{< note >}}
+Currently, if some external system has performed the rotation,
 only the contents of the latest log file will be available through
 `kubectl logs`. E.g. if there's a 10MB file, `logrotate` performs
 the rotation and there are two files, one 10MB in size and one empty,
 `kubectl logs` will return an empty response.

 [cosConfigureHelper]: https://github.com/kubernetes/kubernetes/blob/{{< param "githubbranch" >}}/cluster/gce/gci/configure-helper.sh
+{{< /note >}}

 ### System component logs

@@ -215,10 +219,12 @@ If the node-level logging agent is not flexible enough for your situation, you
 can create a sidecar container with a separate logging agent that you have
 configured specifically to run with your application.

-**Note**: Using a logging agent in a sidecar container can lead
+{{< note >}}
+Using a logging agent in a sidecar container can lead
 to significant resource consumption. Moreover, you won't be able to access
 those logs using `kubectl logs` command, because they are not controlled
 by the kubelet.
+{{< /note >}}

 As an example, you could use [Stackdriver](/docs/tasks/debug-application-cluster/logging-stackdriver/),
 which uses fluentd as a logging agent. Here are two configuration files that
@@ -227,9 +233,11 @@ a [ConfigMap](/docs/tasks/configure-pod-container/configure-pod-configmap/) to c

 {{< codenew file="admin/logging/fluentd-sidecar-config.yaml" >}}

-**Note**: The configuration of fluentd is beyond the scope of this article. For
+{{< note >}}
+The configuration of fluentd is beyond the scope of this article. For
 information about configuring fluentd, see the
 [official fluentd documentation](http://docs.fluentd.org/).
+{{< /note >}}

 The second file describes a pod that has a sidecar container running fluentd.
 The pod mounts a volume where fluentd can pick up its configuration data.
@@ -331,7 +331,7 @@ Currently, resources are created without this annotation, so the first invocatio
 All subsequent calls to `kubectl apply`, and other commands that modify the configuration, such as `kubectl replace` and `kubectl edit`, will update the annotation, allowing subsequent calls to `kubectl apply` to detect and perform deletions using a three-way diff.

 {{< note >}}
-**Note:** To use apply, always create resource initially with either `kubectl apply` or `kubectl create --save-config`.
+To use apply, always create resource initially with either `kubectl apply` or `kubectl create --save-config`.
 {{< /note >}}

 ### kubectl edit
@@ -1,5 +1,5 @@
 ---
 title: "Configuration"
-weight: 70
+weight: 80
 ---

@@ -87,7 +87,7 @@ with a standard set of labels. As of Kubernetes v1.4 these labels are
 * `beta.kubernetes.io/arch`

 {{< note >}}
-**Note:** The value of these labels is cloud provider specific and is not guaranteed to be reliable.
+The value of these labels is cloud provider specific and is not guaranteed to be reliable.
 For example, the value of `kubernetes.io/hostname` may be the same as the Node name in some environments
 and a different value in other environments.
 {{< /note >}}
@@ -173,11 +173,15 @@ like node, rack, cloud provider zone, cloud provider region, etc. You express it
 key for the node label that the system uses to denote such a topology domain, e.g. see the label keys listed above
 in the section [Interlude: built-in node labels](#interlude-built-in-node-labels).

-**Note:** Inter-pod affinity and anti-affinity require substantial amount of
+{{< note >}}
+Inter-pod affinity and anti-affinity require substantial amount of
 processing which can slow down scheduling in large clusters significantly. We do
 not recommend using them in clusters larger than several hundred nodes.
+{{< /note >}}

-**Note:** Pod anti-affinity requires nodes to be consistently labelled, i.e. every node in the cluster must have an appropriate label matching `topologyKey`. If some or all nodes are missing the specified `topologyKey` label, it can lead to unintended behavior.
+{{< note >}}
+Pod anti-affinity requires nodes to be consistently labelled, i.e. every node in the cluster must have an appropriate label matching `topologyKey`. If some or all nodes are missing the specified `topologyKey` label, it can lead to unintended behavior.
+{{< /note >}}

 As with node affinity, there are currently two types of pod affinity and anti-affinity, called `requiredDuringSchedulingIgnoredDuringExecution` and
 `preferredDuringSchedulingIgnoredDuringExecution` which denote "hard" vs. "soft" requirements.
@@ -149,7 +149,9 @@ When using Docker:
  multiplied by 100. The resulting value is the total amount of CPU time that a container can use
  every 100ms. A container cannot use more than its share of CPU time during this interval.

-  {{< note >}}**Note**: The default quota period is 100ms. The minimum resolution of CPU quota is 1ms.{{</ note >}}
+  {{< note >}}
+  The default quota period is 100ms. The minimum resolution of CPU quota is 1ms.
+  {{</ note >}}

 - The `spec.containers[].resources.limits.memory` is converted to an integer, and
  used as the value of the
@@ -317,7 +319,7 @@ Kubernetes version 1.8 introduces a new resource, _ephemeral-storage_ for managi
 This partition is “ephemeral” and applications cannot expect any performance SLAs (Disk IOPS for example) from this partition. Local ephemeral storage management only applies for the root partition; the optional partition for image layer and writable layer is out of scope.

 {{< note >}}
-**Note:** If an optional runtime partition is used, root partition will not hold any image layer or writable layers.
+If an optional runtime partition is used, root partition will not hold any image layer or writable layers.
 {{< /note >}}

 ### Requests and limits setting for local ephemeral storage
@@ -420,7 +422,7 @@ http://k8s-master:8080/api/v1/nodes/k8s-node-1/status
 ```

 {{< note >}}
-**Note**: In the preceding request, `~1` is the encoding for the character `/`
+In the preceding request, `~1` is the encoding for the character `/`
 in the patch path. The operation path value in JSON-Patch is interpreted as a
 JSON-Pointer. For more details, see
 [IETF RFC 6901, section 3](https://tools.ietf.org/html/rfc6901#section-3).
@@ -476,7 +478,7 @@ Examples of _valid_ quantities are `3`, `3000m` and `3Ki`. Examples of
 _invalid_ quantities are `0.5` and `1500m`.

 {{< note >}}
-**Note:** Extended resources replace Opaque Integer Resources.
+Extended resources replace Opaque Integer Resources.
 Users can use any domain name prefix other than `kubernetes.io` which is reserved.
 {{< /note >}}

@@ -484,7 +486,7 @@ To consume an extended resource in a Pod, include the resource name as a key
 in the `spec.containers[].resources.limits` map in the container spec.

 {{< note >}}
-**Note:** Extended resources cannot be overcommitted, so request and limit
+Extended resources cannot be overcommitted, so request and limit
 must be equal if both are present in a container spec.
 {{< /note >}}

@@ -12,7 +12,7 @@ find the information it needs to choose a cluster and communicate with the API s
 of a cluster.

 {{< note >}}
-**Note:** A file that is used to configure access to clusters is called
+A file that is used to configure access to clusters is called
 a *kubeconfig file*. This is a generic way of referring to configuration files.
 It does not mean that there is a file named `kubeconfig`.
 {{< /note >}}
@@ -84,15 +84,15 @@ The [imagePullPolicy](/docs/concepts/containers/images/#updating-images) and the
 - `imagePullPolicy: Never`: the image is assumed to exist locally. No attempt is made to pull the image.

 {{< note >}}
-  **Note:** To make sure the container always uses the same version of the image, you can specify its [digest](https://docs.docker.com/engine/reference/commandline/pull/#pull-an-image-by-digest-immutable-identifier), for example `sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2`. The digest uniquely identifies a specific version of the image, so it is never updated by Kubernetes unless you change the digest value.
+To make sure the container always uses the same version of the image, you can specify its [digest](https://docs.docker.com/engine/reference/commandline/pull/#pull-an-image-by-digest-immutable-identifier), for example `sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2`. The digest uniquely identifies a specific version of the image, so it is never updated by Kubernetes unless you change the digest value.
 {{< /note >}}

 {{< note >}}
-  **Note:** You should avoid using the `:latest` tag when deploying containers in production as it is harder to track which version of the image is running and more difficult to roll back properly.
+You should avoid using the `:latest` tag when deploying containers in production as it is harder to track which version of the image is running and more difficult to roll back properly.
 {{< /note >}}

 {{< note >}}
-  **Note:** The caching semantics of the underlying image provider make even `imagePullPolicy: Always` efficient. With Docker, for example, if the image already exists, the pull attempt is fast because all image layers are cached and no image download is needed.
+The caching semantics of the underlying image provider make even `imagePullPolicy: Always` efficient. With Docker, for example, if the image already exists, the pull attempt is fast because all image layers are cached and no image download is needed.
 {{< /note >}}

 ## Using kubectl
@@ -9,7 +9,6 @@ weight: 70

 {{% capture overview %}}

-{{< feature-state for_k8s_version="1.8" state="alpha" >}}
 {{< feature-state for_k8s_version="1.11" state="beta" >}}

 [Pods](/docs/user-guide/pods) can have _priority_. Priority indicates the
@@ -36,7 +35,7 @@ Kubernetes Version | Priority and Preemption State | Enabled by default
 1.10               | alpha                         | no
 1.11               | beta                          | yes

-{{< warning >}} **Warning**: In a cluster where not all users are trusted, a
+{{< warning >}}In a cluster where not all users are trusted, a
 malicious user could create pods at the highest possible priorities, causing
 other pods to be evicted/not get scheduled. To resolve this issue,
 [ResourceQuota](https://kubernetes.io/docs/concepts/policy/resource-quotas/) is
@@ -71,24 +70,13 @@ Pods.

 ## How to disable preemption

-{{< note >}} **Note**: In Kubernetes 1.11, critical pods (except DaemonSet pods,
-which are still scheduled by the DaemonSet controller) rely on scheduler
-preemption to be scheduled when a cluster is under resource pressure. For this
-reason, you will need to run an older version of Rescheduler if you decide to
-disable preemption. More on this is provided below. {{< /note >}}
-
-#### Option 1: Disable both Pod priority and preemption
-
-Disabling Pod priority disables preemption as well. In order to disable Pod
-Priority, set the feature to false for API server, Scheduler, and Kubelet.
-Disabling the feature on Kubelets is not vital. You can leave the feature on for
-Kubelets if rolling out is hard.
-
-```
--feature-gates=PodPriority=false
-```
-
-#### Option 2: Disable Preemption only
+{{< note >}}
+In Kubernetes 1.11, critical pods (except DaemonSet pods, which are
+still scheduled by the DaemonSet controller) rely on scheduler preemption to be
+scheduled when a cluster is under resource pressure. For this reason, you will
+need to run an older version of Rescheduler if you decide to disable preemption.
+More on this is provided below.
+{{< /note >}}

 In Kubernetes 1.11 and later, preemption is controlled by a kube-scheduler flag
 `disablePreemption`, which is set to `false` by default.
@@ -253,7 +241,7 @@ priority Pods to zero or a small number.
 #### PodDisruptionBudget is supported, but not guaranteed!

 A [Pod Disruption Budget (PDB)](/docs/concepts/workloads/pods/disruptions/)
-allows application owners to limit the number Pods of a replicated application
+allows application owners to limit the number of Pods of a replicated application
 that are down simultaneously from voluntary disruptions. Kubernetes 1.9 supports
 PDB when preempting Pods, but respecting PDB is best effort. The Scheduler tries
 to find victims whose PDB are not violated by preemption, but if no such victims
@@ -266,11 +254,13 @@ A Node is considered for preemption only when the answer to this question is
 yes: "If all the Pods with lower priority than the pending Pod are removed from
 the Node, can the pending Pod be scheduled on the Node?"

-{{< note >}} **Note:** Preemption does not necessarily remove all lower-priority
+{{< note >}}
+Preemption does not necessarily remove all lower-priority
 Pods. If the pending Pod can be scheduled by removing fewer than all
 lower-priority Pods, then only a portion of the lower-priority Pods are removed.
 Even so, the answer to the preceding question must be yes. If the answer is no,
-the Node is not considered for preemption. {{< /note >}}
+the Node is not considered for preemption.
+{{< /note >}}

 If a pending Pod has inter-pod affinity to one or more of the lower-priority
 Pods on the Node, the inter-Pod affinity rule cannot be satisfied in the absence
@@ -339,7 +329,7 @@ than the victims. If preemption happens in such scenarios, please file an issue.

 When pods are preempted, they receive their requested graceful termination
 period, which is by default 30 seconds, but it can be any different value as
-specified in the PodSpec. If the victim Pods do not terminate within this period
+specified in the PodSpec. If the victim Pods do not terminate within this period,
 they are force-terminated. Once all the victims go away, the preemptor Pod can
 be scheduled.

@@ -45,9 +45,11 @@ algorithmSource:
 percentageOfNodesToScore: 50
 ```

-{{< note >}} **Note**: In clusters with zero or less than 50 feasible nodes, the
+{{< note >}}
+In clusters with zero or less than 50 feasible nodes, the
 scheduler still checks all the nodes, simply because there are not enough
-feasible nodes to stop the scheduler's search early. {{< /note >}}
+feasible nodes to stop the scheduler's search early.
+{{< /note >}}

 **To disable this feature**, you can set `percentageOfNodesToScore` to 100.

@@ -102,19 +102,24 @@ See [decoding a secret](#decoding-a-secret) for how to see the contents.

 #### Creating a Secret Manually

-You can also create a secret object in a file first,
-in json or yaml format, and then create that object.
+You can also create a Secret in a file first, in json or yaml format,
+and then create that object. The
+[Secret](/docs/reference/generated/kubernetes-api/v1.12/#secret-v1-core) contains two maps:
+data and stringData. The data field is used to store arbitrary data, encoded using
+base64. The stringData field is provided for convenience, and allows you to provide
+secret data as unencoded strings.

-Each item must be base64 encoded:
+For example, to store two strings in a Secret using the data field, convert
+them to base64 as follows:

 ```shell
-$ echo -n 'admin' | base64
+echo -n 'admin' | base64
 YWRtaW4=
-$ echo -n '1f2d1e2e67df' | base64
+echo -n '1f2d1e2e67df' | base64
 MWYyZDFlMmU2N2Rm
 ```

-Now write a secret object that looks like this:
+Write a Secret that looks like this:

 ```yaml
 apiVersion: v1
@@ -127,15 +132,108 @@ data:
  password: MWYyZDFlMmU2N2Rm
 ```

-The data field is a map.  Its keys must consist of alphanumeric characters, '-', '_' or '.'.  The values are arbitrary data, encoded using base64.
-
-Create the secret using [`kubectl create`](/docs/reference/generated/kubectl/kubectl-commands#create):
+Now create the Secret using [`kubectl create`](/docs/reference/generated/kubectl/kubectl-commands#create):

 ```shell
 $ kubectl create -f ./secret.yaml
 secret "mysecret" created
 ```

+For certain scenarios, you may wish to use the stringData field instead. This
+field allows you to put a non-base64 encoded string directly into the Secret,
+and the string will be encoded for you when the Secret is created or updated.
+
+A practical example of this might be where you are deploying an application
+that uses a Secret to store a configuration file, and you want to populate
+parts of that configuration file during your deployment process.
+
+If your application uses the following configuration file:
+
+```yaml
+apiUrl: "https://my.api.com/api/v1"
+username: "user"
+password: "password"
+```
+
+You could store this in a Secret using the following:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: mysecret
+type: Opaque
+stringData:
+  config.yaml: |-
+    apiUrl: "https://my.api.com/api/v1"
+    username: {{username}}
+    password: {{password}}
+```
+
+Your deployment tool could then replace the `{{username}}` and `{{password}}`
+template variables before running `kubectl create`.
+
+stringData is a write-only convenience field. It is never output when
+retrieving Secrets. For example, if you run the following command:
+
+```shell
+kubectl get secret mysecret -o yaml
+```
+
+The output will be similar to:
+
+```yaml
+apiVersion: v1
+data:
+  config.yaml: YXBpVXJsOiAiaHR0cHM6Ly9teS5hcGkuY29tL2FwaS92MSIKdXNlcm5hbWU6IHt7dXNlcm5hbWV9fQpwYXNzd29yZDoge3twYXNzd29yZH19
+kind: Secret
+metadata:
+  creationTimestamp: 2018-11-15T20:40:59Z
+  name: mysecret
+  namespace: default
+  resourceVersion: "7225"
+  selfLink: /api/v1/namespaces/default/secrets/mysecret
+  uid: c280ad2e-e916-11e8-98f2-025000000001
+type: Opaque
+```
+
+If a field is specified in both data and stringData, the value from stringData
+is used. For example, the following Secret definition:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: mysecret
+type: Opaque
+data:
+  username: YWRtaW4=
+stringData:
+  username: administrator
+```
+
+Results in the following secret:
+
+```yaml
+apiVersion: v1
+data:
+  username: YWRtaW5pc3RyYXRvcg==
+kind: Secret
+metadata:
+  creationTimestamp: 2018-11-15T20:46:46Z
+  name: mysecret
+  namespace: default
+  resourceVersion: "7579"
+  selfLink: /api/v1/namespaces/default/secrets/mysecret
+  uid: 91460ecb-e917-11e8-98f2-025000000001
+type: Opaque
+```
+
+Where `YWRtaW5pc3RyYXRvcg==` decodes to `administrator`.
+
+The keys of data and stringData must consist of alphanumeric characters,
+'-', '_' or '.'.
+
 **Encoding Note:** The serialized JSON and YAML values of secret data are
 encoded as base64 strings.  Newlines are not valid within these strings and must
 be omitted.  When using the `base64` utility on Darwin/macOS users should avoid
@@ -344,7 +442,7 @@ When a secret being already consumed in a volume is updated, projected keys are
 Kubelet is checking whether the mounted secret is fresh on every periodic sync.
 However, it is using its local cache for getting the current value of the Secret.
 The type of the cache is configurable using the  (`ConfigMapAndSecretChangeDetectionStrategy` field in
-[KubeletConfiguration struct](https://github.com/kubernetes/kubernetes/blob/{{< param "docsbranch" >}}/pkg/kubelet/apis/kubeletconfig/v1beta1/types.go)).
+[KubeletConfiguration struct](https://github.com/kubernetes/kubernetes/blob/{{< param "docsbranch" >}}/staging/src/k8s.io/kubelet/config/v1beta1/types.go)).
 It can be either propagated via watch (default), ttl-based, or simply redirecting
 all requests to directly kube-apiserver.
 As a result, the total delay from the moment when the Secret is updated to the moment
@@ -353,7 +451,7 @@ propagation delay, where cache propagation delay depends on the chosen cache typ
 (it equals to watch propagation delay, ttl of cache, or zero corespondingly).

 {{< note >}}
-**Note:** A container using a Secret as a
+A container using a Secret as a
 [subPath](/docs/concepts/storage/volumes#using-subpath) volume mount will not receive
 Secret updates.
 {{< /note >}}
@@ -492,7 +590,7 @@ $ kubectl create secret generic ssh-key-secret --from-file=ssh-privatekey=/path/
 ```

 {{< caution >}}
-**Caution:** Think carefully before sending your own ssh keys: other users of the cluster may have access to the secret.  Use a service account which you want to be accessible to all the users with whom you share the Kubernetes cluster, and can revoke if they are compromised.
+Think carefully before sending your own ssh keys: other users of the cluster may have access to the secret.  Use a service account which you want to be accessible to all the users with whom you share the Kubernetes cluster, and can revoke if they are compromised.
 {{< /caution >}}


@@ -544,7 +642,7 @@ $ kubectl create secret generic test-db-secret --from-literal=username=testuser
 secret "test-db-secret" created
 ```
 {{< note >}}
-**Note:** Special characters such as `$`, `\*`, and `!` require escaping.
+Special characters such as `$`, `\*`, and `!` require escaping.
 If the password you are using has special characters, you need to escape them using the `\\` character. For example, if your actual password is `S!B\*d$zDsb`, you should execute the command this way:

    kubectl create secret generic dev-db-secret --from-literal=username=devuser --from-literal=password=S\\!B\\\*d\\$zDsb
@@ -665,7 +763,7 @@ the `dotfile-test-container` will have this file present at the path
 `/etc/secret-volume/.secret-file`.

 {{< note >}}
-**Note**: Files beginning with dot characters are hidden from the output of  `ls -l`;
+Files beginning with dot characters are hidden from the output of  `ls -l`;
 you must use `ls -la` to see them when listing directory contents.
 {{< /note >}}

@@ -774,7 +872,7 @@ Pod level](#use-case-secret-visible-to-one-container-in-a-pod).
   single node.

 {{< note >}}
-**Note:** As of 1.7 [encryption of secret data at rest is supported](/docs/tasks/administer-cluster/encrypt-data/).
+As of 1.7 [encryption of secret data at rest is supported](/docs/tasks/administer-cluster/encrypt-data/).
 {{< /note >}}

 {{% capture whatsnext %}}
@@ -69,7 +69,7 @@ A toleration "matches" a taint if the keys are the same and the effects are the
 `Operator` defaults to `Equal` if not specified.

 {{< note >}}
-**Note:** There are two special cases:
+There are two special cases:

 * An empty `key` with operator `Exists` matches all keys, values and effects which means this
 will tolerate everything.
@@ -230,7 +230,7 @@ added by the NodeController (or kubelet) and the normal logic for evicting pods
 based on the Ready NodeCondition is disabled.

 {{< note >}}
-**Note:** To maintain the existing [rate limiting](/docs/concepts/architecture/nodes/)
+To maintain the existing [rate limiting](/docs/concepts/architecture/nodes/)
 behavior of pod evictions due to node problems, the system actually adds the taints
 in a rate-limited way. This prevents massive pod evictions in scenarios such
 as the master becoming partitioned from the nodes.
@@ -1,5 +1,5 @@
 ---
 title: "Containers"
-weight: 50
+weight: 40
 ---

@@ -44,7 +44,7 @@ https://cs.k8s.io/?q=docker%20manifest%20(create%7Cpush%7Cannotate)&i=nope&files
 These commands rely on and are implemented purely on the Docker CLI. You will need to either edit the `$HOME/.docker/config.json` and set `experimental` key to `enabled` or you can just set `DOCKER_CLI_EXPERIMENTAL` environment variable to `enabled` when you call the CLI commands.

 {{< note >}}
-**Note:** Please use Docker *18.06 or above*, versions below that either have bugs or do not support the experimental command line option. Example https://github.com/docker/cli/issues/1135 causes problems under containerd.
+Please use Docker *18.06 or above*, versions below that either have bugs or do not support the experimental command line option. Example https://github.com/docker/cli/issues/1135 causes problems under containerd.
 {{< /note >}}

 If you run into trouble with uploading stale manifests, just clean up the older manifests in `$HOME/.docker/manifests` to start fresh.
@@ -156,16 +156,16 @@ You can use the IBM Cloud Container Registry to deploy containers from [IBM Clou
 ### Configuring Nodes to Authenticate to a Private Registry

 {{< note >}}
-**Note:** If you are running on Google Kubernetes Engine, there will already be a `.dockercfg` on each node with credentials for Google Container Registry.  You cannot use this approach.
+If you are running on Google Kubernetes Engine, there will already be a `.dockercfg` on each node with credentials for Google Container Registry.  You cannot use this approach.
 {{< /note >}}

 {{< note >}}
-**Note:** If you are running on AWS EC2 and are using the EC2 Container Registry (ECR), the kubelet on each node will
+If you are running on AWS EC2 and are using the EC2 Container Registry (ECR), the kubelet on each node will
 manage and update the ECR login credentials. You cannot use this approach.
 {{< /note >}}

 {{< note >}}
-**Note:** This approach is suitable if you can control node configuration.  It
+This approach is suitable if you can control node configuration.  It
 will not work reliably on GCE, and any other cloud provider that does automatic
 node replacement.
 {{< /note >}}
@@ -183,7 +183,7 @@ in the search paths list below, kubelet uses it as the credential provider when
 *   `/.dockercfg`

 {{< note >}}
-**Note**: You may have to set `HOME=/root` explicitly in your environment file for kubelet.
+You may have to set `HOME=/root` explicitly in your environment file for kubelet.
 {{< /note >}}

 Here are the recommended steps to configuring your nodes to use a private registry.  In this
@@ -240,11 +240,11 @@ registry keys are added to the `.docker/config.json`.
 ### Pre-pulling Images

 {{< note >}}
-**Note:** If you are running on Google Kubernetes Engine, there will already be a `.dockercfg` on each node with credentials for Google Container Registry.  You cannot use this approach.
+If you are running on Google Kubernetes Engine, there will already be a `.dockercfg` on each node with credentials for Google Container Registry.  You cannot use this approach.
 {{< /note >}}

 {{< note >}}
-**Note:** This approach is suitable if you can control node configuration.  It
+This approach is suitable if you can control node configuration.  It
 will not work reliably on GCE, and any other cloud provider that does automatic
 node replacement.
 {{< /note >}}
@@ -263,7 +263,7 @@ All pods will have read access to any pre-pulled images.
 ### Specifying ImagePullSecrets on a Pod

 {{< note >}}
-**Note:** This approach is currently the recommended approach for Google Kubernetes Engine, GCE, and any cloud-providers
+This approach is currently the recommended approach for Google Kubernetes Engine, GCE, and any cloud-providers
 where node creation is automated.
 {{< /note >}}

@@ -57,7 +57,7 @@ corresponding documentation for your CRI implementation for how to configure. As
 feature, not all CRIs support multiple RuntimeClasses yet.

 {{< note >}}
-**Note:** RuntimeClass currently assumes a homogeneous node configuration across the cluster
+RuntimeClass currently assumes a homogeneous node configuration across the cluster
 (which means that all nodes are configured the same way with respect to container runtimes). Any heterogeneity (varying configurations) must be
 managed independently of RuntimeClass through scheduling features
 (see [Assigning Pods to Nodes](/docs/concepts/configuration/assign-pod-node/)).
@@ -87,11 +87,9 @@ spec:


 {{< note >}}
-
-**Note:** It is recommended that RuntimeClass write operations (create/update/patch/delete) be
-restricted to the cluster administrator. This is typically the default.
-See [Authorization Overview](https://kubernetes.io/docs/reference/access-authn-authz/authorization/) for more details.
-
+It is recommended that RuntimeClass write operations (create/update/patch/delete) be
+restricted to the cluster administrator. This is typically the default. See [Authorization
+Overview](https://kubernetes.io/docs/reference/access-authn-authz/authorization/) for more details.
 {{< /note >}}

 ### Usage
@@ -8,7 +8,9 @@ toc_hide: true

 {{% capture overview %}}

-**NOTE:** Be sure to also [create an entry in the table of contents](/docs/home/contribute/write-new-topic/#creating-an-entry-in-the-table-of-contents) for your new document.
+{{< note >}}
+Be sure to also [create an entry in the table of contents](/docs/home/contribute/write-new-topic/#creating-an-entry-in-the-table-of-contents) for your new document.
+{{< /note >}}

 This page explains ...

@@ -1,4 +1,4 @@
 ---
 title: Extending Kubernetes
-weight: 40
+weight: 110
 ---
@@ -91,7 +91,7 @@ Use a ConfigMap if any of the following apply:
 * You want to perform rolling updates via Deployment, etc, when the file is updated.

 {{< note >}}
-**Note:** Use a [secret](/docs/concepts/configuration/secret/) for sensitive data, which is similar to a configMap but more secure.
+Use a [secret](/docs/concepts/configuration/secret/) for sensitive data, which is similar to a configMap but more secure.
 {{< /note >}}

 Use a custom resource (CRD or Aggregated API) if most of the following apply:
@@ -108,11 +108,11 @@ Use a custom resource (CRD or Aggregated API) if most of the following apply:
 Kubernetes provides two ways to add custom resources to your cluster:

 - CRDs are simple and can be created without any programming.
- [API Aggregation](/docs/concepts/api-extension/apiserver-aggregation/) requires programming, but allows more control over API behaviors like how data is stored and conversion between API versions.
+- [API Aggregation](/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/) requires programming, but allows more control over API behaviors like how data is stored and conversion between API versions.

-Kubernetes provides these two options to meet the needs of different users, so that neither ease of use nor flexibility are compromised.
+Kubernetes provides these two options to meet the needs of different users, so that neither ease of use nor flexibility is compromised.

-Aggregated APIs are subordinate APIServers that sit behind the primary API server, which acts as a proxy. This arrangement is called [API Aggregation](/docs/concepts/api-extension/apiserver-aggregation/) (AA). To users, it simply appears that the Kubernetes API is extended.
+Aggregated APIs are subordinate APIServers that sit behind the primary API server, which acts as a proxy. This arrangement is called [API Aggregation](/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/) (AA). To users, it simply appears that the Kubernetes API is extended.

 CRDs allow users to create new types of resources without adding another APIserver. You do not need to understand API Aggregation to use CRDs.

@@ -131,14 +131,14 @@ for a demonstration of how to register a new custom resource, work with instance
 and setup a controller to handle events.

 {{< note >}}
-**Note:** CRD is the successor to the deprecated *ThirdPartyResource* (TPR) API, and is available as of Kubernetes 1.7.
+CRD is the successor to the deprecated *ThirdPartyResource* (TPR) API, and is available as of Kubernetes 1.7.
 {{< /note >}}

 ## API server aggregation

 Usually, each resource in the Kubernetes API requires code that handles REST requests and manages persistent storage of objects. The main Kubernetes API server handles built-in resources like *pods* and *services*, and can also handle custom resources in a generic way through [CRDs](#customresourcedefinitions).

-The [aggregation layer](/docs/concepts/api-extension/apiserver-aggregation/) allows you to provide specialized
+The [aggregation layer](/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/) allows you to provide specialized
 implementations for your custom resources by writing and deploying your own standalone API server.
 The main API server delegates requests to you for the custom resources that you handle,
 making them available to all of its clients.
@@ -171,13 +171,13 @@ Aggregated APIs offer more advanced API features and customization of other feat
 | ------- | ----------- | ---- | -------------- |
 | Validation | Help users prevent errors and allow you to evolve your API independently of your clients. These features are most useful when there are many clients who can't all update at the same time. | Yes.  Most validation can be specified in the CRD using [OpenAPI v3.0 validation](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/#validation).  Any other validations supported by addition of a [Validating Webhook](/docs/reference/access-authn-authz/admission-controllers/#validatingadmissionwebhook-alpha-in-1-8-beta-in-1-9). | Yes, arbitrary validation checks |
 | Defaulting | See above | Yes, via a [Mutating Webhook](/docs/reference/access-authn-authz/admission-controllers/#mutatingadmissionwebhook-beta-in-1-9); Planned, via CRD OpenAPI schema. | Yes |
-| Multi-versioning | Allows serving the same object through two API versions. Can help ease API changes like renaming fields. Less important if you control your client versions. | No, but planned | Yes |
+| Multi-versioning | Allows serving the same object through two API versions. Can help ease API changes like renaming fields. Less important if you control your client versions. | [Yes](/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definition-versioning) | Yes |
 | Custom Storage | If you need storage with a different performance mode (for example, time-series database instead of key-value store) or isolation for security (for example, encryption secrets or different | No | Yes |
 | Custom Business Logic | Perform arbitrary checks or actions when creating, reading, updating or deleting an object | Yes, using [Webhooks](/docs/reference/access-authn-authz/extensible-admission-controllers/#admission-webhooks). | Yes |
 | Scale Subresource | Allows systems like HorizontalPodAutoscaler and PodDisruptionBudget interact with your new resource | [Yes](https://kubernetes.io/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/#scale-subresource)  | Yes |
 | Status Subresource | <ul><li>Finer-grained access control: user writes spec section, controller writes status section.</li><li>Allows incrementing object Generation on custom resource data mutation (requires separate spec and status sections in the resource)</li></ul> | [Yes](https://kubernetes.io/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/#status-subresource) | Yes |
 | Other Subresources | Add operations other than CRUD, such as "logs" or "exec". | No | Yes |
-| strategic-merge-patch | The new endpoints support PATCH with `Content-Type: application/strategic-merge-patch+json`. Useful for updating objects that may be modified both locally, and by the server. For more information, see ["Update API Objects in Place Using kubectl patch"](/docs/tasks/run-application/update-api-object-kubectl-patch/) | No, but similar functionality planned | Yes |
+| strategic-merge-patch | The new endpoints support PATCH with `Content-Type: application/strategic-merge-patch+json`. Useful for updating objects that may be modified both locally, and by the server. For more information, see ["Update API Objects in Place Using kubectl patch"](/docs/tasks/run-application/update-api-object-kubectl-patch/) | No | Yes |
 | Protocol Buffers | The new resource supports clients that want to use Protocol Buffers | No | Yes |
 | OpenAPI Schema | Is there an OpenAPI (swagger) schema for the types that can be dynamically fetched from the server? Is the user protected from misspelling field names by ensuring only allowed fields are set? Are types enforced (in other words, don't put an `int` in a `string` field?) | No, but planned | Yes |

@@ -240,9 +240,9 @@ When you add a custom resource, you can access it using:
 {{% /capture %}}

 {{% capture whatsnext %}}
-* Learn how to [Extend the Kubernetes API with the aggregation layer](/docs/concepts/api-extension/apiserver-aggregation/).
-* Learn how to [Extend the Kubernetes API with CustomResourceDefinition](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/).
-* Learn how to [Migrate a ThirdPartyResource to CustomResourceDefinition](/docs/tasks/access-kubernetes-api/migrate-third-party-resource/).
+
+* Learn how to [Extend the Kubernetes API with the aggregation layer](/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/).
+
+* Learn how to [Extend the Kubernetes API with CustomResourceDefinition](/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/).
+
 {{% /capture %}}
-
-
@@ -32,7 +32,7 @@ The application can simply use it as a service.

 Service Catalog uses the [Open service broker API](https://github.com/openservicebrokerapi/servicebroker) to communicate with service brokers, acting as an intermediary for the Kubernetes API Server to negotiate the initial provisioning and retrieve the credentials necessary for the application to use a managed service.

-It is implemented as an extension API server and a controller, using etcd for storage. It also uses the [aggregation layer](/docs/concepts/api-extension/apiserver-aggregation/) available in Kubernetes 1.7+ to present its API.
+It is implemented as an extension API server and a controller, using etcd for storage. It also uses the [aggregation layer](/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/) available in Kubernetes 1.7+ to present its API.

 <br>

@@ -60,7 +60,7 @@ annotation on each object. The annotation contains the contents of the object
 configuration file that was used to create the object.

 {{< note >}}
-**Note:** Add the `-R` flag to recursively process directories.
+Add the `-R` flag to recursively process directories.
 {{< /note >}}

 Here's an example of an object configuration file:
@@ -134,7 +134,7 @@ kubectl apply -f <directory>/
 ```

 {{< note >}}
-**Note:** Add the `-R` flag to recursively process directories.
+Add the `-R` flag to recursively process directories.
 {{< /note >}}

 Here's an example configuration file:
@@ -148,7 +148,7 @@ kubectl apply -f https://k8s.io/examples/application/simple_deployment.yaml
 ```

 {{< note >}}
-**Note:** For purposes of illustration, the preceding command refers to a single
+For purposes of illustration, the preceding command refers to a single
 configuration file instead of a directory.
 {{< /note >}}

@@ -322,7 +322,7 @@ spec:
 ```

 {{< warning >}}
-**Warning:** Mixing `kubectl apply` with the imperative object configuration commands
+Mixing `kubectl apply` with the imperative object configuration commands
 `create` and `replace` is not supported. This is because `create`
 and `replace` do not retain the `kubectl.kubernetes.io/last-applied-configuration`
 that `kubectl apply` uses to compute updates.
@@ -347,12 +347,12 @@ kubectl delete -f <filename>
 Only use this if you know what you are doing.

 {{< warning >}}
-**Warning:** `kubectl apply --prune` is in alpha, and backwards incompatible
+`kubectl apply --prune` is in alpha, and backwards incompatible
 changes might be introduced in subsequent releases.
 {{< /warning >}}

 {{< warning >}}
-**Warning:** You must be careful when using this command, so that you
+You must be careful when using this command, so that you
 do not delete objects unintentionally.
 {{< /warning >}}

@@ -373,7 +373,7 @@ kubectl apply -f <directory/> --prune -l <labels>
 ```

 {{< warning >}}
-**Warning:** Apply with prune should only be run against the root directory
+Apply with prune should only be run against the root directory
 containing the object configuration files. Running against sub-directories
 can cause objects to be unintentionally deleted if they are returned
 by the label selector query specified with `-l <labels>` and
@@ -391,10 +391,9 @@ kubectl get -f <filename|url> -o yaml
 ## How apply calculates differences and merges changes

 {{< caution >}}
-**Caution:** A *patch* is an update operation that is scoped to specific
-fields of an object instead of the entire object.
-This enables updating only a specific set of fields on an object without
-reading the object first.
+A *patch* is an update operation that is scoped to specific fields of an object
+instead of the entire object. This enables updating only a specific set of fields
+on an object without reading the object first.
 {{< /caution >}}

 When `kubectl apply` updates the live configuration for an object,
@@ -546,7 +545,7 @@ and merged.
 Primitive fields are replaced or cleared.

 {{< note >}}
-**Note:** '-' is used for "not applicable" because the value is not used.
+`-` is used for "not applicable" because the value is not used.
 {{< /note >}}

 | Field in object configuration file  | Field in live object configuration | Field in last-applied-configuration | Action                                    |
@@ -561,7 +560,7 @@ Primitive fields are replaced or cleared.
 Fields that represent maps are merged by comparing each of the subfields or elements of the map:

 {{< note >}}
-**Note:** '-' is used for "not applicable" because the value is not used.
+`-` is used for "not applicable" because the value is not used.
 {{< /note >}}

 | Key in object configuration file    | Key in live object configuration   | Field in last-applied-configuration | Action                           |
@@ -689,7 +688,7 @@ by `name`.
 As of Kubernetes 1.5, merging lists of primitive elements is not supported.

 {{< note >}}
-**Note:** Which of the above strategies is chosen for a given field is controlled by
+Which of the above strategies is chosen for a given field is controlled by
 the `patchStrategy` tag in [types.go](https://git.k8s.io/api/core/v1/types.go#L2565)
 If no `patchStrategy` is specified for a field of type list, then
 the list is replaced.
@@ -900,7 +899,7 @@ Kubernetes objects should be managed using only one method at a time.
 Switching from one method to another is possible, but is a manual process.

 {{< note >}}
-**Note:** It is OK to use imperative deletion with declarative management.
+It is OK to use imperative deletion with declarative management.
 {{< /note >}}

 {{< comment >}}
@@ -924,8 +923,10 @@ configuration involves several manual steps:

 1. Manually remove the `status` field from the configuration file.

-    {{< note >}}**Note:** This step is optional, as `kubectl apply` does not update the status field
-    even if it is present in the configuration file.{{< /note >}}
+    {{< note >}}
+    This step is optional, as `kubectl apply` does not update the status field
+    even if it is present in the configuration file.
+    {{< /note >}}

 1. Set the `kubectl.kubernetes.io/last-applied-configuration` annotation on the object:

@@ -952,7 +953,7 @@ TODO(pwittrock): Why doesn't export remove the status field?  Seems like it shou
 ## Defining controller selectors and PodTemplate labels

 {{< warning >}}
-**Warning:** Updating selectors on controllers is strongly discouraged.
+Updating selectors on controllers is strongly discouraged.
 {{< /warning >}}

 The recommended approach is to define a single, immutable PodTemplate label
@@ -76,8 +76,7 @@ Setting this aspect may set different fields for different object types:
 - `set` <field>: Set an aspect of an object.

 {{< note >}}
-**Note**: In Kubernetes version 1.5, not every verb-driven command has an
-associated aspect-driven command.
+In Kubernetes version 1.5, not every verb-driven command has an associated aspect-driven command.
 {{< /note >}}

 The `kubectl` tool supports these additional ways to update a live object directly,
@@ -95,7 +94,7 @@ You can use the `delete` command to delete an object from a cluster:
 - `delete <type>/<name>`

 {{< note >}}
-**Note**: You can use `kubectl delete` for both imperative commands and imperative object
+You can use `kubectl delete` for both imperative commands and imperative object
 configuration. The difference is in the arguments passed to the command. To use
 `kubectl delete` as an imperative command, pass the object to be deleted as
 an argument. Here's an example that passes a Deployment object named nginx:
@@ -137,7 +136,7 @@ kubectl create service clusterip my-svc --clusterip="None" -o yaml --dry-run | k
 ```

 1. The `kubectl create service -o yaml --dry-run` command creates the configuration for the Service, but prints it to stdout as YAML instead of sending it to the Kubernetes API server.
-1. The `kubectl set --local -f - -o yaml` command reads the configuration from stdin, and writes the updated configuration to stdout as YAML.
+1. The `kubectl set selector --local -f - -o yaml` command reads the configuration from stdin, and writes the updated configuration to stdout as YAML.
 1. The `kubectl create -f -` command creates the object using the configuration provided via stdin.

 ## Using `--edit` to modify objects before creation
@@ -34,7 +34,7 @@ for details.
 ## How to update objects

 {{< warning >}}
-**Warning:** Updating objects with the `replace` command drops all
+Updating objects with the `replace` command drops all
 parts of the spec not specified in the configuration file.  This
 should not be used with objects whose specs are partially managed
 by the cluster, such as Services of type `LoadBalancer`, where
@@ -115,7 +115,7 @@ kubectl replace -f <kind>_<name>.yaml
 ## Defining controller selectors and PodTemplate labels

 {{< warning >}}
-**Warning:** Updating selectors on controllers is strongly discouraged.
+Updating selectors on controllers is strongly discouraged.
 {{< /warning >}}

 The recommended approach is to define a single, immutable PodTemplate label
@@ -15,7 +15,7 @@ approaches.
 ## Management techniques

 {{< warning >}}
-**Warning:** A Kubernetes object should be managed using only one technique. Mixing
+A Kubernetes object should be managed using only one technique. Mixing
 and matching techniques for the same object results in undefined behavior.
 {{< /warning >}}

@@ -74,7 +74,7 @@ See the [API reference](/docs/reference/generated/kubernetes-api/{{< param "vers
 for more details on object definitions.

 {{< warning >}}
-**Warning:** The imperative `replace` command replaces the existing
+The imperative `replace` command replaces the existing
 spec with the newly provided one, dropping all changes to the object missing from
 the configuration file.  This approach should not be used with resource
 types whose specs are updated independently of the configuration file.
@@ -135,7 +135,7 @@ are automatically detected per-object by `kubectl`. This enables working on
 directories, where different operations might be needed for different objects.

 {{< note >}}
-**Note:** Declarative object configuration retains changes made by other
+Declarative object configuration retains changes made by other
 writers, even if the changes are not merged back to the object configuration file.
 This is possible by using the `patch` API operation to write only
 observed differences, instead of using the `replace`
@@ -182,7 +182,7 @@ Summary of container benefits:
    hardware to running an application on an OS using logical resources.
 * **Loosely coupled, distributed, elastic, liberated [micro-services](https://martinfowler.com/articles/microservices.html)**:
    Applications are broken into smaller, independent pieces and can
-    be deployed and managed dynamically -- not a fat monolithic stack
+    be deployed and managed dynamically -- not a monolithic stack
    running on one big single-purpose machine.
 * **Resource isolation**:
    Predictable application performance.
@@ -19,7 +19,7 @@ Instead, applications are informal and described with metadata. The definition o
 what an application contains is loose.

 {{< note >}}
-**Note:** These are recommended labels. They make it easier to manage applications
+These are recommended labels. They make it easier to manage applications
 but aren't required for any core tooling.
 {{< /note >}}

@@ -66,7 +66,7 @@ An empty label selector (that is, one with zero requirements) selects every obje
 A null label selector (which is only possible for optional selector fields) selects no objects.

 {{< note >}}
-**Note**: the label selectors of two controllers must not overlap within a namespace, otherwise they will fight with each other.
+The label selectors of two controllers must not overlap within a namespace, otherwise they will fight with each other.
 {{< /note >}}

 ### _Equality-based_ requirement
@@ -1,5 +1,5 @@
 ---
 title: "Policies"
-weight: 160
+weight: 90
 ---

@@ -37,7 +37,7 @@ administrator to control the following:
 | White list of Flexvolume drivers                    | [`allowedFlexVolumes`](#flexvolume-drivers) |
 | Allocating an FSGroup that owns the pod's volumes   | [`fsGroup`](#volumes-and-file-systems)      |
 | Requiring the use of a read only root file system   | [`readOnlyRootFilesystem`](#volumes-and-file-systems) |
-| The user and group IDs of the container             | [`runAsUser`, `supplementalGroups`](#users-and-groups) |
+| The user and group IDs of the container             | [`runAsUser`, `runAsGroup`, `supplementalGroups`](#users-and-groups) |
 | Restricting escalation to root privileges           | [`allowPrivilegeEscalation`, `defaultAllowPrivilegeEscalation`](#privilege-escalation) |
 | Linux capabilities                                  | [`defaultAddCapabilities`, `requiredDropCapabilities`, `allowedCapabilities`](#capabilities) |
 | The SELinux context of the container                | [`seLinux`](#selinux)                       |
@@ -230,8 +230,8 @@ Create the rolebinding to grant `fake-user` the `use` verb on the example
 policy:

 {{< note >}}
-**Note:** _This is not the recommended way! See the [next section](#run-another-pod)
-for the preferred approach._
+This is not the recommended way! See the [next section](#run-another-pod)
+for the preferred approach.
 {{< /note >}}

 ```shell
@@ -442,7 +442,7 @@ allowedHostPaths:
    readOnly: true # only allow read-only mounts
 ```

-{{< warning >}}**Warning:** There are many ways a container with unrestricted access to the host
+{{< warning >}}There are many ways a container with unrestricted access to the host
 filesystem can escalate privileges, including reading data from other
 containers, and abusing the credentials of system services, such as Kubelet.

@@ -457,7 +457,7 @@ root filesystem (i.e. no writable layer).

 ### Flexvolume drivers

-This specifies a whiltelist of Flexvolume drivers that are allowed to be used
+This specifies a whitelist of Flexvolume drivers that are allowed to be used
 by flexvolume. An empty list or nil means there is no restriction on the drivers.
 Please make sure [`volumes`](#volumes-and-file-systems) field contains the
 `flexVolume` volume type; no Flexvolume driver is allowed otherwise.
@@ -27,7 +27,7 @@ Resource quotas work like this:

 - Different teams work in different namespaces.  Currently this is voluntary, but
  support for making this mandatory via ACLs is planned.
- The administrator creates one or more `ResourceQuotas` for each namespace.
+- The administrator creates one `ResourceQuota` for each namespace.
 - Users create resources (pods, services, etc.) in the namespace, and the quota system
  tracks usage to ensure it does not exceed hard resource limits defined in a `ResourceQuota`.
 - If creating or updating a resource violates a quota constraint, the request will fail with HTTP
@@ -202,7 +202,7 @@ field in the quota spec.
 A quota is matched and consumed only if `scopeSelector` in the quota spec selects the pod.

 {{< note >}}
-**Note:** You need to enable the feature gate `ResourceQuotaScopeSelectors`before using resource quotas
+You need to enable the feature gate `ResourceQuotaScopeSelectors`before using resource quotas
 per PriorityClass.
 {{< /note >}}

@@ -1,5 +1,5 @@
 ---
 title: "Services, Load Balancing, and Networking"
-weight: 80
+weight: 60
 ---

@@ -122,7 +122,7 @@ about the [service proxy](/docs/concepts/services-networking/service/#virtual-ip

 Kubernetes supports 2 primary modes of finding a Service - environment variables
 and DNS. The former works out of the box while the latter requires the
-[kube-dns cluster addon](http://releases.k8s.io/{{< param "githubbranch" >}}/cluster/addons/dns/kube-dns/README.md).
+[CoreDNS cluster addon](http://releases.k8s.io/{{< param "githubbranch" >}}/cluster/addons/dns/coredns).

 ### Environment Variables

@@ -178,7 +178,7 @@ kube-dns   ClusterIP   10.0.0.10    <none>        53/UDP,53/TCP   8m

 If it isn't running, you can [enable it](http://releases.k8s.io/{{< param "githubbranch" >}}/cluster/addons/dns/README.md#how-do-i-configure-it).
 The rest of this section will assume you have a Service with a long lived IP
-(my-nginx), and a DNS server that has assigned a name to that IP (the kube-dns
+(my-nginx), and a DNS server that has assigned a name to that IP (the CoreDNS
 cluster addon), so you can talk to the Service from any pod in your cluster using
 standard methods (e.g. gethostbyname). Let's run another curl application to test this:

@@ -149,7 +149,7 @@ The Endpoints object can specify the `hostname` for any endpoint addresses,
 along with its IP.

 {{< note >}}
-**Note:** Because A records are not created for Pod names, `hostname` is required for the Pod's A record to be created. A Pod with no `hostname` but with `subdomain` only will only create the A record for the headless service (`default-subdomain.my-namespace.svc.cluster.local`), pointing to the Pod's IP address.
+Because A records are not created for Pod names, `hostname` is required for the Pod's A record to be created. A Pod with no `hostname` but with `subdomain` only will only create the A record for the headless service (`default-subdomain.my-namespace.svc.cluster.local`), pointing to the Pod's IP address.
 {{< /note >}}

 ### Pod's DNS Policy
@@ -176,7 +176,7 @@ following pod-specific DNS policies. These policies are specified in the
  See [DNS config](#dns-config) subsection below.

 {{< note >}}
-**NOTE:** "Default" is not the default DNS policy. If `dnsPolicy` is not
+"Default" is not the default DNS policy. If `dnsPolicy` is not
 explicitly specified, then “ClusterFirst” is used.
 {{< /note >}}

@@ -13,48 +13,95 @@ weight: 40
 {{% capture body %}}
 ## Terminology

-Throughout this doc you will see a few terms that are sometimes used interchangeably elsewhere, that might cause confusion. This section attempts to clarify them.
+For the sake of clarity, this guide defines the following terms:

 * Node: A single virtual or physical machine in a Kubernetes cluster.
 * Cluster: A group of nodes firewalled from the internet, that are the primary compute resources managed by Kubernetes.
 * Edge router: A router that enforces the firewall policy for your cluster. This could be a gateway managed by a cloud provider or a physical piece of hardware.
-* Cluster network: A set of links, logical or physical, that facilitate communication within a cluster according to the [Kubernetes networking model](/docs/concepts/cluster-administration/networking/). Examples of a Cluster network include Overlays such as [flannel](https://github.com/coreos/flannel#flannel) or SDNs such as [OVS](https://www.openvswitch.org/).
+* Cluster network: A set of links, logical or physical, that facilitate communication within a cluster according to the [Kubernetes networking model](/docs/concepts/cluster-administration/networking/).
 * Service: A Kubernetes [Service](/docs/concepts/services-networking/service/) that identifies a set of pods using label selectors. Unless mentioned otherwise, Services are assumed to have virtual IPs only routable within the cluster network.

 ## What is Ingress?

-Typically, services and pods have IPs only routable by the cluster network. All traffic that ends up at an edge router is either dropped or forwarded elsewhere. Conceptually, this might look like:
+Ingress, added in Kubernetes v1.1, exposes HTTP and HTTPS routes from outside the cluster to
+{{< link text="services" url="/docs/concepts/services-networking/service/" >}} within the cluster.
+Traffic routing is controlled by rules defined on the ingress resource.

 ```none
    internet
        |
-  ------------
-  [ Services ]
-```
-
-An Ingress is a collection of rules that allow inbound connections to reach the cluster services.
-
-```
-    internet
-        |
   [ Ingress ]
   --|-----|--
   [ Services ]
 ```

-It can be configured to give services externally-reachable URLs, load balance traffic, terminate SSL, offer name based virtual hosting, and more. Users request ingress by POSTing the Ingress resource to the API server. An [Ingress controller](#ingress-controllers) is responsible for fulfilling the Ingress, usually with a loadbalancer, though it may also configure your edge router or additional frontends to help handle the traffic in an HA manner.
+An ingress can be configured to give services externally-reachable URLs, load balance traffic, terminate SSL, and offer name based virtual hosting. An [ingress controller](#ingress-controllers) is responsible for fulfilling the ingress, usually with a loadbalancer, though it may also configure your edge router or additional frontends to help handle the traffic.
+
+An ingress does not expose arbitrary ports or protocols. Exposing services other than HTTP and HTTPS to the internet typically
+uses a service of type [Service.Type=NodePort](/docs/concepts/services-networking/service/#nodeport) or
+[Service.Type=LoadBalancer](/docs/concepts/services-networking/service/#loadbalancer).

 ## Prerequisites

-Before you start using the Ingress resource, there are a few things you should understand. The Ingress is a beta resource, not available in any Kubernetes release prior to 1.1. You need an Ingress controller to satisfy an Ingress, simply creating the resource will have no effect.
+{{< feature-state for_k8s_version="v1.1" state="beta" >}}

-GCE/Google Kubernetes Engine deploys an ingress controller on the master. You can deploy any number of custom ingress controllers in a pod. You must annotate each ingress with the appropriate class, as indicated [here](https://git.k8s.io/ingress-nginx/docs/user-guide/multiple-ingress.md#multiple-ingress-controllers) and [here](https://git.k8s.io/ingress-gce/examples/PREREQUISITES.md#ingress-class).
+Before you start using an ingress, there are a few things you should understand. The ingress is a beta resource. You will need an ingress controller to satisfy an ingress, simply creating the resource will have no effect.

-Make sure you review the [beta limitations](https://github.com/kubernetes/ingress-gce/blob/master/BETA_LIMITATIONS.md#glbc-beta-limitations) of this controller. In environments other than GCE/Google Kubernetes Engine, you need to [deploy a controller](https://git.k8s.io/ingress-nginx/README.md) as a pod.
+GCE/Google Kubernetes Engine deploys an [ingress controller](#ingress-controllers) on the master. Review the
+[beta limitations](https://github.com/kubernetes/ingress-gce/blob/master/BETA_LIMITATIONS.md#glbc-beta-limitations)
+of this controller if you are using GCE/GKE.
+
+In environments other than GCE/Google Kubernetes Engine, you may need to
+[deploy an ingress controller](https://kubernetes.github.io/ingress-nginx/deploy/). There are a number of
+[ingress controller](#ingress-controllers) you may choose from.
+
+## Ingress controllers
+
+In order for the ingress resource to work, the cluster must have an ingress controller running. This is unlike other types of controllers, which run as part of the `kube-controller-manager` binary, and are typically started automatically with a cluster. Choose the ingress controller implementation that best fits your cluster.
+
+* Kubernetes as a project currently supports and maintains [GCE](https://git.k8s.io/ingress-gce/README.md) and
+  [nginx](https://git.k8s.io/ingress-nginx/README.md) controllers.
+
+Additional controllers include:
+
+* [Contour](https://github.com/heptio/contour) is an [Envoy](https://www.envoyproxy.io) based ingress controller
+  provided and supported by Heptio.
+* F5 Networks provides [support and maintenance](https://support.f5.com/csp/article/K86859508)
+  for the [F5 BIG-IP Controller for Kubernetes](http://clouddocs.f5.com/products/connectors/k8s-bigip-ctlr/latest).
+* [HAProxy](http://www.haproxy.org/) based ingress controller
+  [jcmoraisjr/haproxy-ingress](https://github.com/jcmoraisjr/haproxy-ingress) which is mentioned on the blog post
+  [HAProxy Ingress Controller for Kubernetes](https://www.haproxy.com/blog/haproxy_ingress_controller_for_kubernetes/).
+  [HAProxy Technologies](https://www.haproxy.com/) offers support and maintenance for HAProxy Enterprise and
+  the ingress controller [jcmoraisjr/haproxy-ingress](https://github.com/jcmoraisjr/haproxy-ingress).
+* [Istio](https://istio.io/) based ingress controller
+  [Control Ingress Traffic](https://istio.io/docs/tasks/traffic-management/ingress/).
+* [Kong](https://konghq.com/) offers [community](https://discuss.konghq.com/c/kubernetes) or
+  [commercial](https://konghq.com/api-customer-success/) support and maintenance for the
+  [Kong Ingress Controllerfor Kubernetes](https://konghq.com/blog/kubernetes-ingress-controller-for-kong/).
+* [NGINX, Inc.](https://www.nginx.com/) offers support and maintenance for the
+  [NGINX Ingress Controller for Kubernetes](https://www.nginx.com/products/nginx/kubernetes-ingress-controller).
+* [Traefik](https://github.com/containous/traefik) is a fully featured ingress controller
+  ([Let's Encrypt](https://letsencrypt.org), secrets, http2, websocket), and it also comes with commercial
+  support by [Containous](https://containo.us/services).
+
+You may deploy [any number of ingress controllers](https://git.k8s.io/ingress-nginx/docs/user-guide/multiple-ingress.md#multiple-ingress-controllers) within a cluster.
+When you create an ingress, you should annotate each ingress with the appropriate
+[`ingress-class`](https://git.k8s.io/ingress-gce/examples/PREREQUISITES.md#ingress-class) to indicate which ingress
+controller should be used if more than one exists within your cluster.
+If you do not define a class, your cloud provider may use a default ingress provider.
+
+### Before you begin
+
+Ideally, all ingress controllers should fulfill this specification, but the various ingress
+controllers operate slightly differently.
+
+{{< note >}}
+Make sure you review your ingress controller's documentation to understand the caveats of choosing it.
+{{< /note >}}

 ## The Ingress Resource

-A minimal Ingress might look like:
+A minimal ingress resource example:

 ```yaml
 apiVersion: extensions/v1beta1
@@ -73,50 +120,51 @@ spec:
          servicePort: 80
 ```

-*POSTing this to the API server will have no effect if you have not configured an [Ingress controller](#ingress-controllers).*
+ As with all other Kubernetes resources, an ingress needs `apiVersion`, `kind`, and `metadata` fields.  
+ For general information about working with config files, see [deploying applications](/docs/tasks/run-application/run-stateless-application-deployment/), [configuring containers](/docs/tasks/configure-pod-container/configure-pod-configmap/), [managing resources](/docs/concepts/cluster-administration/manage-deployment/).
+ Ingress frequently uses annotations to configure some options depending on the ingress controller, an example of which
+ is the [rewrite-target annotation](https://github.com/kubernetes/ingress-nginx/blob/master/docs/examples/rewrite/README.md).
+ Different [ingress controller](#ingress-controllers) support different annotations. Review the documentation for
+ your choice of ingress controller to learn which annotations are supported.

-__Lines 1-6__: As with all other Kubernetes config, an Ingress needs `apiVersion`, `kind`, and `metadata` fields.  For general information about working with config files, see [deploying applications](/docs/tasks/run-application/run-stateless-application-deployment/), [configuring containers](/docs/tasks/configure-pod-container/configure-pod-configmap/), [managing resources](/docs/concepts/cluster-administration/manage-deployment/) and [ingress configuration rewrite](https://github.com/kubernetes/ingress-nginx/blob/master/docs/examples/rewrite/README.md).
+The ingress [spec](https://git.k8s.io/community/contributors/devel/api-conventions.md#spec-and-status)
+has all the information needed to configure a loadbalancer or proxy server. Most importantly, it
+contains a list of rules matched against all incoming requests. Ingress resource only supports rules
+for directing HTTP traffic.

-__Lines 7-9__: Ingress [spec](https://git.k8s.io/community/contributors/devel/api-conventions.md#spec-and-status) has all the information needed to configure a loadbalancer or proxy server. Most importantly, it contains a list of rules matched against all incoming requests. Currently the Ingress resource only supports http rules.
+### Ingress rules

-__Lines 10-11__: Each http rule contains the following information: A host (e.g.: foo.bar.com, defaults to * in this example), a list of paths (e.g.: /testpath) each of which has an associated backend (test:80). Both the host and path must match the content of an incoming request before the loadbalancer directs traffic to the backend.
+Each http rule contains the following information:

-__Lines 12-14__: A backend is a service:port combination as described in the [services doc](/docs/concepts/services-networking/service/). Ingress traffic is typically sent directly to the endpoints matching a backend.
+* An optional host. In this example, no host is specified, so the rule applies to all inbound
+  HTTP traffic through the IP address is specified. If a host is provided (for example,
+  foo.bar.com), the rules apply to that host.
+* a list of paths (for example, /testpath), each of which has an associated backend defined with a `serviceName`
+  and `servicePort`. Both the host and path must match the content of an incoming request before the
+  loadbalancer will direct traffic to the referenced service.
+* A backend is a combination of service and port names as described in the
+  [services doc](/docs/concepts/services-networking/service/). HTTP (and HTTPS) requests to the
+  ingress matching the host and path of the rule will be sent to the listed backend.

-__Global Parameters__: For the sake of simplicity the example Ingress has no global parameters, see the [API reference](https://releases.k8s.io/{{< param "githubbranch" >}}/staging/src/k8s.io/api/extensions/v1beta1/types.go) for a full definition of the resource. One can specify a global default backend in the absence of which requests that don't match a path in the spec are sent to the default backend of the Ingress controller.
+A default backend is often configured in an ingress controller that will service any requests that do not
+match a path in the spec.

-## Ingress controllers
+### Default Backend

-In order for the Ingress resource to work, the cluster must have an Ingress controller running. This is unlike other types of controllers, which typically run as part of the `kube-controller-manager` binary, and which are typically started automatically as part of cluster creation. Choose the ingress controller implementation that best fits your cluster, or implement a new ingress controller. 
+An ingress with no rules sends all traffic to a single default backend. The default
+backend is typically a configuration option of the [ingress controller](#ingress-controllers)
+and is not specified in your ingress resources.

-* Kubernetes currently supports and maintains [GCE](https://git.k8s.io/ingress-gce/README.md) and [nginx](https://git.k8s.io/ingress-nginx/README.md) controllers. 
-* F5 Networks provides [support and maintenance](https://support.f5.com/csp/article/K86859508) for the [F5 BIG-IP Controller for Kubernetes](http://clouddocs.f5.com/products/connectors/k8s-bigip-ctlr/latest). 
-* [Kong](https://konghq.com/) offers [community](https://discuss.konghq.com/c/kubernetes) or [commercial](https://konghq.com/api-customer-success/) support and maintenance for the [Kong Ingress Controller for Kubernetes](https://konghq.com/blog/kubernetes-ingress-controller-for-kong/)
-* [Traefik](https://github.com/containous/traefik) is a fully featured ingress controller
-([Let's Encrypt](https://letsencrypt.org), secrets, http2, websocket...), and it also comes with commercial support by [Containous](https://containo.us/services)
-* [NGINX, Inc.](https://www.nginx.com/) offers support and maintenance for the [NGINX Ingress Controller for Kubernetes](https://www.nginx.com/products/nginx/kubernetes-ingress-controller)
-* [HAProxy](http://www.haproxy.org/) based ingress controller [jcmoraisjr/haproxy-ingress](https://github.com/jcmoraisjr/haproxy-ingress) which is mentioned on this blog post [HAProxy Ingress Controller for Kubernetes](https://www.haproxy.com/blog/haproxy_ingress_controller_for_kubernetes/)
-* [Istio](https://istio.io/) based ingress controller [Control Ingress Traffic](https://istio.io/docs/tasks/traffic-management/ingress/)
-
-{{< note >}}
-**Note:** Review the documentation for your controller to find its specific support policy.
-{{< /note >}}
-
-## Before you begin
-
-The following document describes a set of cross-platform features exposed through the Ingress resource. Ideally, all Ingress controllers should fulfill this specification, but we're not there yet. We currently support and maintain [GCE](https://git.k8s.io/ingress-gce/README.md) and [nginx](https://git.k8s.io/ingress-nginx/README.md) controllers. If you use the F5 BIG-IP Controller, see [Use the BIG-IP Controller as a Kubernetes Ingress Controller](http://clouddocs.f5.com/containers/latest/kubernetes/kctlr-k8s-ingress-ctlr.html). 
-
-{{< note >}}
-**Note:** Make sure you review your controller's specific docs so you understand the caveats.
-{{< /note >}}
+If none of the hosts or paths match the HTTP request in the ingress objects, the traffic is
+routed to your default backend.

 ## Types of Ingress

 ### Single Service Ingress

 There are existing Kubernetes concepts that allow you to expose a single Service
-(see [alternatives](#alternatives)), however you can do so through an Ingress
-as well, by specifying a *default backend* with no rules.
+(see [alternatives](#alternatives)). You can also do this with an ingress by specifying a
+*default backend* with no rules.

 {{< codenew file="service/networking/ingress.yaml" >}}

@@ -131,29 +179,32 @@ NAME           HOSTS     ADDRESS           PORTS     AGE
 test-ingress   *         107.178.254.228   80        59s
 ```

-Where `107.178.254.228` is the IP allocated by the Ingress controller to satisfy
-this Ingress.
+Where `107.178.254.228` is the IP allocated by the ingress controller to satisfy
+this ingress.
+
+{{< note >}}
+Ingress controllers and load balancers may take a minute or two to allocate an IP address.
+Until that time you will often see the address listed as `<pending>`.
+{{< /note >}}

 ### Simple fanout

-As described previously, Pods within kubernetes have IPs only visible on the
-cluster network, so we need something at the edge accepting ingress traffic and
-proxying it to the right endpoints. This component is usually a highly available
-loadbalancer. An Ingress allows you to keep the number of loadbalancers down
-to a minimum. For example, a setup like:
+A fanout configuration routes traffic from a single IP address to more than one service,
+based on the HTTP URI being requested. An ingress allows you to keep the number of loadbalancers
+down to a minimum. For example, a setup like:

 ```shell
-foo.bar.com -> 178.91.123.132 -> / foo    s1:80
-                                 / bar    s2:80
+foo.bar.com -> 178.91.123.132 -> / foo    service1:4200
+                                 / bar    service2:8080
 ```

-would require an Ingress such as:
+would require an ingress such as:

 ```yaml
 apiVersion: extensions/v1beta1
 kind: Ingress
 metadata:
-  name: test
+  name: simple-fanout-example
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
 spec:
@@ -163,22 +214,22 @@ spec:
      paths:
      - path: /foo
        backend:
-          serviceName: s1
-          servicePort: 80
+          serviceName: service1
+          servicePort: 4200
      - path: /bar
        backend:
-          serviceName: s2
-          servicePort: 80
+          serviceName: service2
+          servicePort: 8080
 ```

-When you create the Ingress with `kubectl create -f`:
+When you create the ingress with `kubectl create -f`:

 ```shell
-kubectl describe ingress test
+kubectl describe ingress simple-fanout-example
 ```

 ```shell
-Name:             test
+Name:             simple-fanout-example
 Namespace:        default
 Address:          178.91.123.132
 Default backend:  default-http-backend:80 (10.8.2.3:8080)
@@ -186,8 +237,8 @@ Rules:
  Host         Path  Backends
  ----         ----  --------
  foo.bar.com
-               /foo   s1:80 (10.8.0.90:80)
-               /bar   s2:80 (10.8.0.91:80)
+               /foo   service1:4200 (10.8.0.90:4200)
+               /bar   service2:8080 (10.8.0.91:8080)
 Annotations:
  nginx.ingress.kubernetes.io/rewrite-target:  /
 Events:
@@ -196,18 +247,19 @@ Events:
  Normal   ADD     22s                loadbalancer-controller  default/test
 ```

-The Ingress controller will provision an implementation specific loadbalancer
-that satisfies the Ingress, as long as the services (`s1`, `s2`) exist.
+The ingress controller will provision an implementation specific loadbalancer
+that satisfies the ingress, as long as the services (`s1`, `s2`) exist.
 When it has done so, you will see the address of the loadbalancer at the
 Address field.

 {{< note >}}
-**Note:** You need to create a default-http-backend [Service](/docs/concepts/services-networking/service/) if necessary.
+Depending on the [ingress controller](#ingress-controllers) you are using, you may need to
+create a default-http-backend [Service](/docs/concepts/services-networking/service/).
 {{< /note >}}

 ### Name based virtual hosting

-Name-based virtual hosts use multiple host names for the same IP address.
+Name-based virtual hosts support routing HTTP traffic to multiple host names at the same IP address.

 ```none
 foo.bar.com --|                 |-> foo.bar.com s1:80
@@ -215,45 +267,71 @@ foo.bar.com --|                 |-> foo.bar.com s1:80
 bar.foo.com --|                 |-> bar.foo.com s2:80
 ```

-The following Ingress tells the backing loadbalancer to route requests based on
+The following ingress tells the backing loadbalancer to route requests based on
 the [Host header](https://tools.ietf.org/html/rfc7230#section-5.4).

 ```yaml
 apiVersion: extensions/v1beta1
 kind: Ingress
 metadata:
-  name: test
+  name: name-virtual-host-ingress
 spec:
  rules:
  - host: foo.bar.com
    http:
      paths:
      - backend:
-          serviceName: s1
+          serviceName: service1
          servicePort: 80
  - host: bar.foo.com
    http:
      paths:
      - backend:
-          serviceName: s2
+          serviceName: service2
          servicePort: 80
 ```

-__Default Backends__: An Ingress with no rules, like the one shown in the previous
-section, sends all traffic to a single default backend. You can use the same
-technique to tell a loadbalancer where to find your website's 404 page, by
-specifying a set of rules *and* a default backend. Traffic is routed to your
-default backend if none of the Hosts in your Ingress match the Host in the
-request header, and/or none of the paths match the URL of the request.
+If you create an ingress resource without any hosts defined in the rules, then any
+web traffic to the IP address of your ingress controller can be matched without a name based
+virtual host being required. For example, the following ingress resource will route traffic 
+requested for `first.bar.com` to `service1`, `second.bar.com` to `service2`, and any traffic
+to the IP address without a hostname defined in request (that is, without a request header being
+presented) to `service3`.
+
+```yaml
+apiVersion: extensions/v1beta1
+kind: Ingress
+metadata:
+  name: name-virtual-host-ingress
+spec:
+  rules:
+  - host: first.bar.com
+    http:
+      paths:
+      - backend:
+          serviceName: service1
+          servicePort: 80
+  - host: second.foo.com
+    http:
+      paths:
+      - backend:
+          serviceName: service2
+          servicePort: 80
+  - http:
+      paths:
+      - backend:
+          serviceName: service3
+          servicePort: 80
+```

 ### TLS

-You can secure an Ingress by specifying a [secret](/docs/concepts/configuration/secret)
-that contains a TLS private key and certificate. Currently the Ingress only
+You can secure an ingress by specifying a [secret](/docs/concepts/configuration/secret)
+that contains a TLS private key and certificate. Currently the ingress only
 supports a single TLS port, 443, and assumes TLS termination. If the TLS
-configuration section in an Ingress specifies different hosts, they will be
+configuration section in an ingress specifies different hosts, they will be
 multiplexed on the same port according to the hostname specified through the
-SNI TLS extension (provided the Ingress controller supports SNI). The TLS secret
+SNI TLS extension (provided the ingress controller supports SNI). The TLS secret
 must contain keys named `tls.crt` and `tls.key` that contain the certificate
 and private key to use for TLS, e.g.:

@@ -264,46 +342,55 @@ data:
  tls.key: base64 encoded key
 kind: Secret
 metadata:
-  name: testsecret
+  name: testsecret-tls
  namespace: default
 type: Opaque
 ```

-Referencing this secret in an Ingress will tell the Ingress controller to
-secure the channel from the client to the loadbalancer using TLS:
+Referencing this secret in an ingress will tell the ingress controller to
+secure the channel from the client to the loadbalancer using TLS. You need to make
+sure the TLS secret you created came from a certificate that contains a CN 
+for `sslexample.foo.com`.

 ```yaml
 apiVersion: extensions/v1beta1
 kind: Ingress
 metadata:
-  name: no-rules-map
+  name: tls-example-ingress
 spec:
  tls:
-  - secretName: testsecret
-  backend:
-    serviceName: s1
-    servicePort: 80
+  - hosts:
+    - sslexample.foo.com
+    secretName: testsecret-tls
+  rules:
+    - host: sslexample.foo.com
+      http:
+        paths:
+        - path: /
+          backend:
+            serviceName: service1
+            servicePort: 80
 ```

-Note that there is a gap between TLS features supported by various Ingress
+{{< note >}}
+There is a gap between TLS features supported by various ingress
 controllers. Please refer to documentation on
 [nginx](https://git.k8s.io/ingress-nginx/README.md#https),
 [GCE](https://git.k8s.io/ingress-gce/README.md#frontend-https), or any other
-platform specific Ingress controller to understand how TLS works in your environment.
+platform specific ingress controller to understand how TLS works in your environment.
+{{< /note >}}

 ### Loadbalancing

-An Ingress controller is bootstrapped with some load balancing policy settings
-that it applies to all Ingress, such as the load balancing algorithm, backend
+An ingress controller is bootstrapped with some load balancing policy settings
+that it applies to all ingress, such as the load balancing algorithm, backend
 weight scheme, and others. More advanced load balancing concepts
 (e.g. persistent sessions, dynamic weights) are not yet exposed through the
-Ingress. You can still get these features through the
+ingress. You can still get these features through the
 [service loadbalancer](https://github.com/kubernetes/ingress-nginx).
- With time, we plan to distill load balancing patterns that are applicable
-cross platform into the Ingress resource.

 It's also worth noting that even though health checks are not exposed directly
-through the Ingress, there exist parallel concepts in Kubernetes such as
+through the ingress, there exist parallel concepts in Kubernetes such as
 [readiness probes](/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/)
 which allow you to achieve the same end result. Please review the controller
 specific docs to see how they handle health checks (
@@ -312,7 +399,7 @@ specific docs to see how they handle health checks (

 ## Updating an Ingress

-Say you'd like to add a new Host to an existing Ingress, you can update it by editing the resource:
+To update an existing ingress to add a new Host, you can update it by editing the resource:

 ```shell
 kubectl describe ingress test
@@ -362,7 +449,8 @@ spec:
 ..
 ```

-Saving the yaml will update the resource in the API server, which should tell the Ingress controller to reconfigure the loadbalancer.
+Saving the yaml will update the resource in the API server, which should tell the
+ingress controller to reconfigure the loadbalancer.

 ```shell
 kubectl describe ingress test
@@ -388,28 +476,30 @@ Events:
  Normal   ADD     45s                loadbalancer-controller  default/test
 ```

-You can achieve the same by invoking `kubectl replace -f` on a modified Ingress yaml file.
+You can achieve the same by invoking `kubectl replace -f` on a modified ingress yaml file.

 ## Failing across availability zones

-Techniques for spreading traffic across failure domains differs between cloud providers. Please check the documentation of the relevant Ingress controller for details. Please refer to the federation [doc](/docs/concepts/cluster-administration/federation/) for details on deploying Ingress in a federated cluster.
+Techniques for spreading traffic across failure domains differs between cloud providers.
+Please check the documentation of the relevant [ingress controller](#ingress-controllers) for
+details. You can also refer to the [federation documentation](/docs/concepts/cluster-administration/federation/)
+for details on deploying ingress in a federated cluster.

 ## Future Work

-* Various modes of HTTPS/TLS support (e.g.: SNI, re-encryption)
-* Requesting an IP or Hostname via claims
-* Combining L4 and L7 Ingress
-* More Ingress controllers
-
-Please track the [L7 and Ingress proposal](https://github.com/kubernetes/kubernetes/pull/12827) for more details on the evolution of the resource, and the [Ingress repository](https://github.com/kubernetes/ingress/tree/master) for more details on the evolution of various Ingress controllers.
+Track [SIG Network](https://github.com/kubernetes/community/tree/master/sig-network)
+for more details on the evolution of the ingress and related resources. You may also track the
+[ingress repository](https://github.com/kubernetes/ingress/tree/master) for more details on the
+evolution of various ingress controllers.

 ## Alternatives

-You can expose a Service in multiple ways that don't directly involve the Ingress resource:
+You can expose a Service in multiple ways that don't directly involve the ingress resource:

 * Use [Service.Type=LoadBalancer](/docs/concepts/services-networking/service/#loadbalancer)
 * Use [Service.Type=NodePort](/docs/concepts/services-networking/service/#nodeport)
 * Use a [Port Proxy](https://git.k8s.io/contrib/for-demos/proxy-to-service)
+
 {{% /capture %}}

 {{% capture whatsnext %}}
@@ -16,7 +16,7 @@ weight: 10

 Kubernetes [`Pods`](/docs/concepts/workloads/pods/pod/) are mortal. They are born and when they die, they
 are not resurrected.  [`ReplicaSets`](/docs/concepts/workloads/controllers/replicaset/) in
-particular create and destroy `Pods` dynamically (e.g. when scaling up or down).  While each `Pod` gets its own IP address, even
+particular create and destroy `Pods` dynamically (e.g. when scaling out or in).  While each `Pod` gets its own IP address, even
 those IP addresses cannot be relied upon to be stable over time. This leads to
 a problem: if some set of `Pods` (let's call them backends) provides
 functionality to other `Pods` (let's call them frontends) inside the Kubernetes
@@ -87,7 +87,7 @@ Kubernetes `Services` support `TCP`, `UDP` and `SCTP` for protocols.  The defaul
 is `TCP`.

 {{< note >}}
-**Note:** SCTP support is an alpha feature since Kubernetes 1.12
+SCTP support is an alpha feature since Kubernetes 1.12
 {{< /note >}}

 ### Services without selectors
@@ -132,7 +132,7 @@ subsets:
 ```

 {{< note >}}
-**Note:** The endpoint IPs may not be loopback (127.0.0.0/8), link-local
+The endpoint IPs may not be loopback (127.0.0.0/8), link-local
 (169.254.0.0/16), or link-local multicast (224.0.0.0/24). They cannot be the
 cluster IPs of other Kubernetes services either because the `kube-proxy`
 component doesn't support virtual IPs as destination yet.
@@ -212,10 +212,12 @@ options for load balancing algorithm, such as:
 - `sed`: shortest expected delay
 - `nq`: never queue

-**Note:** ipvs mode assumes IPVS kernel modules are installed on the node
+{{< note >}}
+ipvs mode assumes IPVS kernel modules are installed on the node
 before running kube-proxy. When kube-proxy starts with ipvs proxy mode,
 kube-proxy would validate if IPVS modules are installed on the node, if
 it's not installed kube-proxy will fall back to iptables proxy mode.
+{{< /note >}}

 ![Services overview diagram for ipvs proxy](/images/docs/services-ipvs-overview.svg)

@@ -322,8 +324,8 @@ DNS server watches the Kubernetes API for new `Services` and creates a set of
 DNS records for each.  If DNS has been enabled throughout the cluster then all
 `Pods` should be able to do name resolution of `Services` automatically.

-For example, if you have a `Service` called `"my-service"` in Kubernetes
-`Namespace` `"my-ns"` a DNS record for `"my-service.my-ns"` is created.  `Pods`
+For example, if you have a `Service` called `"my-service"` in a Kubernetes
+`Namespace` called `"my-ns"`, a DNS record for `"my-service.my-ns"` is created.  `Pods`
 which exist in the `"my-ns"` `Namespace` should be able to find it by simply doing
 a name lookup for `"my-service"`.  `Pods` which exist in other `Namespaces` must
 qualify the name as `"my-service.my-ns"`.  The result of these name lookups is the
@@ -459,7 +461,7 @@ public IP address resource needs to be created first, and it should be in the sa
 group of the other automatically created resources of the cluster. For example, `MC_myResourceGroup_myAKSCluster_eastus`. Specify the assigned IP address as loadBalancerIP. Ensure that you have updated the securityGroupName in the cloud provider configuration file. For information about troubleshooting `CreatingLoadBalancerFailed` permission issues see, [Use a static IP address with the Azure Kubernetes Service (AKS) load balancer](https://docs.microsoft.com/en-us/azure/aks/static-ip) or [CreatingLoadBalancerFailed on AKS cluster with advanced networking](https://github.com/Azure/AKS/issues/357).

 {{< note >}}
-**Note:** The support of SCTP in the cloud provider's load balancer is up to the cloud provider's
+The support of SCTP in the cloud provider's load balancer is up to the cloud provider's
 load balancer implementation. If SCTP is not supported by the cloud provider's load balancer the
 Service creation request is accepted but the creation of the load balancer fails.
 {{< /note >}}
@@ -693,7 +695,9 @@ There are other annotations to manage Classic Elastic Load Balancers that are de

 #### Network Load Balancer support on AWS [alpha]

-**Warning:** This is an alpha feature and not recommended for production clusters yet.
+{{< warning >}}
+This is an alpha feature and not recommended for production clusters yet.
+{{< /warning >}}

 Starting in version 1.9.0, Kubernetes supports Network Load Balancer (NLB). To
 use a Network Load Balancer on AWS, use the annotation `service.beta.kubernetes.io/aws-load-balancer-type`
@@ -747,13 +751,15 @@ spec:
  - "143.231.0.0/16"
 ```

-**Note:** NLB only works with certain instance classes, see the [AWS documentation](http://docs.aws.amazon.com/elasticloadbalancing/latest/network/target-group-register-targets.html#register-deregister-targets)
+{{< note >}}
+NLB only works with certain instance classes, see the [AWS documentation](http://docs.aws.amazon.com/elasticloadbalancing/latest/network/target-group-register-targets.html#register-deregister-targets)
 for supported instance types.
+{{< /note >}}

 ### Type ExternalName {#externalname}

 {{< note >}}
-**NOTE:** ExternalName Services are available only with `kube-dns` version 1.7 and later.
+ExternalName Services are available only with `kube-dns` version 1.7 and later.
 {{< /note >}}

 Services of type ExternalName map a service to a DNS name (specified using
@@ -772,7 +778,7 @@ spec:
  externalName: my.database.example.com
 ```

-When looking up the host `my-service.prod.svc.CLUSTER`, the cluster DNS service
+When looking up the host `my-service.prod.svc.cluster.local`, the cluster DNS service
 will return a `CNAME` record with the value `my.database.example.com`. Accessing
 `my-service` works in the same way as other Services but with the crucial
 difference that redirection happens at the DNS level rather than via proxying or
@@ -1,5 +1,5 @@
 ---
 title: "Storage"
-weight: 90
+weight: 70
 ---

@@ -85,7 +85,7 @@ Once a user has a claim and that claim is bound, the bound PV belongs to the use
 The purpose of the Storage Object in Use Protection feature is to ensure that Persistent Volume Claims (PVCs) in active use by a pod and Persistent Volume (PVs) that are bound to PVCs are not removed from the system as this may result in data loss.

 {{< note >}}
-**Note:** PVC is in active use by a pod when the pod status is `Pending` and the pod is assigned to a node or the pod status is `Running`.
+PVC is in active use by a pod when the pod status is `Pending` and the pod is assigned to a node or the pod status is `Running`.
 {{< /note >}}

 When the [Storage Object in Use Protection feature](/docs/tasks/administer-cluster/storage-object-in-use-protection/) is enabled, if a user deletes a PVC in active use by a pod, the PVC is not removed immediately. PVC removal is postponed until the PVC is no longer actively used by any pods, and also if admin deletes a PV that is bound to a PVC, the PV is not removed immediately. PV removal is postponed until the PV is not bound to a PVC any more.
@@ -147,7 +147,7 @@ For volume plugins that support the `Delete` reclaim policy, deletion removes bo
 #### Recycle

 {{< warning >}}
-**Warning:** The `Recycle` reclaim policy is deprecated. Instead, the recommended approach is to use dynamic provisioning.
+The `Recycle` reclaim policy is deprecated. Instead, the recommended approach is to use dynamic provisioning.
 {{< /warning >}}

 If supported by the underlying volume plugin, the `Recycle` reclaim policy performs a basic scrub (`rm -rf /thevolume/*`) on the volume and makes it available again for a new claim.
@@ -238,7 +238,7 @@ This feature has no effect on PVCs that are not in use by a Pod or deployment. Y
 uses the PVC before the expansion can complete.

 {{< note >}}
-**Note:** Expanding EBS volumes is a time consuming operation. Also, there is a per-volume quota of one modification every 6 hours.
+Expanding EBS volumes is a time consuming operation. Also, there is a per-volume quota of one modification every 6 hours.
 {{< /note >}}


@@ -335,7 +335,7 @@ In the CLI, the access modes are abbreviated to:
 | CephFS               | &#x2713;     | &#x2713;    | &#x2713;     |
 | Cinder               | &#x2713;     | -           | -            |
 | FC                   | &#x2713;     | &#x2713;    | -            |
-| Flexvolume           | &#x2713;     | &#x2713;    | -            |
+| Flexvolume           | &#x2713;     | &#x2713;    | depends on the driver |
 | Flocker              | &#x2713;     | -           | -            |
 | GCEPersistentDisk    | &#x2713;     | &#x2713;    | -            |
 | Glusterfs            | &#x2713;     | &#x2713;    | &#x2713;     |
@@ -377,7 +377,7 @@ Currently, only NFS and HostPath support recycling. AWS EBS, GCE PD, Azure Disk,
 A Kubernetes administrator can specify additional mount options for when a Persistent Volume is mounted on a node.

 {{< note >}}
-**Note:** Not all Persistent volume types support mount options.
+Not all Persistent volume types support mount options.
 {{< /note >}}

 The following volume types support mount options:
@@ -402,6 +402,14 @@ In the past, the annotation `volume.beta.kubernetes.io/mount-options` was used i
 of the `mountOptions` attribute. This annotation is still working, however
 it will become fully deprecated in a future Kubernetes release.

+### Node Affinity
+
+{{< note >}}
+For most volume types, you do not need to set this field. It is automatically populated for [AWS EBS](/docs/concepts/storage/volumes/#awselasticblockstore), [GCE PD](/docs/concepts/storage/volumes/#gcepersistentdisk) and [Azure Disk](/docs/concepts/storage/volumes/#azuredisk) volume block types. You need to explicitly set this for [local](/docs/concepts/storage/volumes/#local) volumes.
+{{< /note >}}
+
+A PV can specify [node affinity](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#volumenodeaffinity-v1-core) to define constraints that limit what nodes this volume can be accessed from. Pods that use a PV will only be scheduled to nodes that are selected by the node affinity.
+
 ### Phase

 A volume will be in one of the following phases:
@@ -495,7 +503,7 @@ the requirements are ANDed together: only a PV of the requested class and with
 the requested labels may be bound to the PVC.

 {{< note >}}
-**Note:** Currently, a PVC with a non-empty `selector` can't have a PV dynamically provisioned for it.
+Currently, a PVC with a non-empty `selector` can't have a PV dynamically provisioned for it.
 {{< /note >}}

 In the past, the annotation `volume.beta.kubernetes.io/storage-class` was used instead
@@ -547,7 +555,7 @@ applicable.
 * RBD (Ceph Block Device)

 {{< note >}}
-**Note**: Only FC and iSCSI volumes supported raw block volumes in Kubernetes 1.9.
+Only FC and iSCSI volumes supported raw block volumes in Kubernetes 1.9.
 Support for the additional plugins was added in 1.10.
 {{< /note >}}

@@ -605,7 +613,7 @@ spec:
 ```

 {{< note >}}
-**Note:** When adding a raw block device for a Pod, we specify the device path in the container instead of a mount path.
+When adding a raw block device for a Pod, we specify the device path in the container instead of a mount path.
 {{< /note >}}

 ### Binding Block Volumes
@@ -627,7 +635,7 @@ Volume binding matrix for statically provisioned volumes:
 |   Filesystem  | unspecified     | BIND             |

 {{< note >}}
-**Note:** Only statically provisioned volumes are supported for alpha release. Administrators should take care to consider these values when working with raw block devices.
+Only statically provisioned volumes are supported for alpha release. Administrators should take care to consider these values when working with raw block devices.
 {{< /note >}}

 ## Volume Snapshot and Restore Volume from Snapshot Support
@@ -123,8 +123,10 @@ the class or PV, so mount of the PV will simply fail if one is invalid.

 {{< feature-state for_k8s_version="v1.12" state="beta" >}}

-**Note:** This feature requires the `VolumeScheduling` feature gate to be
+{{< note >}}
+This feature requires the `VolumeScheduling` feature gate to be
 enabled.
+{{< /note >}}

 The `volumeBindingMode` field controls when [volume binding and dynamic
 provisioning](/docs/concepts/storage/persistent-volumes/#provisioning) should occur.
@@ -159,8 +161,10 @@ The following plugins support `WaitForFirstConsumer` with pre-created Persistent
 ### Allowed Topologies
 {{< feature-state for_k8s_version="v1.12" state="beta" >}}

-**Note:** This feature requires the `VolumeScheduling` feature gate to be
+{{< note >}}
+This feature requires the `VolumeScheduling` feature gate to be
 enabled.
+{{< /note >}}

 When a cluster operactor specifies the `WaitForFirstConsumer` volume binding mode, it is no longer necessary
 to restrict provisioning to specific topologies in most situations. However,
@@ -232,8 +236,10 @@ parameters:
  encrypting the volume. If none is supplied but `encrypted` is true, a key is
  generated by AWS. See AWS docs for valid ARN value.

-**Note:** `zone` and `zones` parameters are deprecated and replaced with
+{{< note >}}
+`zone` and `zones` parameters are deprecated and replaced with
 [allowedTopologies](#allowed-topologies)
+{{< /note >}}

 ### GCE PD

@@ -269,8 +275,10 @@ specified, Kubernetes will arbitrarily choose among the specified zones. If the
 `zones` parameter is omitted, Kubernetes will arbitrarily choose among zones
 managed by the cluster.

-**Note:** `zone` and `zones` parameters are deprecated and replaced with
+{{< note >}}
+`zone` and `zones` parameters are deprecated and replaced with
 [allowedTopologies](#allowed-topologies)
+{{< /note >}}

 ### Glusterfs

@@ -105,7 +105,7 @@ EBS volume can be pre-populated with data, and that data can be "handed off"
 between Pods.

 {{< caution >}}
-**Important:** You must create an EBS volume using `aws ec2 create-volume` or the AWS API before you can use it.
+You must create an EBS volume using `aws ec2 create-volume` or the AWS API before you can use it.
 {{< /caution >}}

 There are some restrictions when using an `awsElasticBlockStore` volume:
@@ -170,7 +170,7 @@ that data can be "handed off" between Pods.  CephFS can be mounted by multiple
 writers simultaneously.

 {{< caution >}}
-**Important:** You must have your own Ceph server running with the share exported before you can use it.
+You must have your own Ceph server running with the share exported before you can use it.
 {{< /caution >}}

 See the [CephFS example](https://github.com/kubernetes/examples/tree/{{< param "githubbranch" >}}/staging/volumes/cephfs/) for more details.
@@ -215,11 +215,11 @@ Note that this path is derived from the volume's `mountPath` and the `path`
 keyed with `log_level`.

 {{< caution >}}
-**Important:** You must create a [ConfigMap](/docs/tasks/configure-pod-container/configure-pod-configmap/) before you can use it.
+You must create a [ConfigMap](/docs/tasks/configure-pod-container/configure-pod-configmap/) before you can use it.
 {{< /caution >}}

 {{< note >}}
-**Note:** A Container using a ConfigMap as a [subPath](#using-subpath) volume mount will not
+A Container using a ConfigMap as a [subPath](#using-subpath) volume mount will not
 receive ConfigMap updates.
 {{< /note >}}

@@ -229,7 +229,7 @@ A `downwardAPI` volume is used to make downward API data available to applicatio
 It mounts a directory and writes the requested data in plain text files.

 {{< note >}}
-**Note:** A Container using Downward API as a [subPath](#using-subpath) volume mount will not
+A Container using Downward API as a [subPath](#using-subpath) volume mount will not
 receive Downward API updates.
 {{< /note >}}

@@ -245,7 +245,7 @@ or different paths in each Container.  When a Pod is removed from a node for
 any reason, the data in the `emptyDir` is deleted forever.

 {{< note >}}
-**Note:** A Container crashing does *NOT* remove a Pod from a node, so the data in an `emptyDir` volume is safe across Container crashes.
+A Container crashing does *NOT* remove a Pod from a node, so the data in an `emptyDir` volume is safe across Container crashes.
 {{< /note >}}

 Some uses for an `emptyDir` are:
@@ -290,7 +290,7 @@ You can specify single or multiple target World Wide Names using the parameter
 targetWWNs expect that those WWNs are from multi-path connections.

 {{< caution >}}
-**Important:** You must configure FC SAN Zoning to allocate and mask those LUNs (volumes) to the target WWNs beforehand so that Kubernetes hosts can access them.
+You must configure FC SAN Zoning to allocate and mask those LUNs (volumes) to the target WWNs beforehand so that Kubernetes hosts can access them.
 {{< /caution >}}

 See the [FC example](https://github.com/kubernetes/examples/tree/{{< param "githubbranch" >}}/staging/volumes/fibre_channel) for more details.
@@ -307,7 +307,7 @@ reattached by Flocker to the node that the Pod is scheduled. This means data
 can be "handed off" between Pods as required.

 {{< caution >}}
-**Important:** You must have your own Flocker installation running before you can use it.
+You must have your own Flocker installation running before you can use it.
 {{< /caution >}}

 See the [Flocker example](https://github.com/kubernetes/examples/tree/{{< param "githubbranch" >}}/staging/volumes/flocker) for more details.
@@ -321,7 +321,7 @@ preserved and the volume is merely unmounted.  This means that a PD can be
 pre-populated with data, and that data can be "handed off" between Pods.

 {{< caution >}}
-**Important:** You must create a PD using `gcloud` or the GCE API or UI before you can use it.
+You must create a PD using `gcloud` or the GCE API or UI before you can use it.
 {{< /caution >}}

 There are some restrictions when using a `gcePersistentDisk`:
@@ -403,7 +403,7 @@ spec:
 ### gitRepo (deprecated) {#gitrepo}

 {{< warning >}}
-**Warning:** The gitRepo volume type is deprecated. To provision a container with a git repo, mount an [EmptyDir](#emptydir) into an InitContainer that clones the repo using git, then mount the [EmptyDir](#emptydir) into the Pod's container.
+The gitRepo volume type is deprecated. To provision a container with a git repo, mount an [EmptyDir](#emptydir) into an InitContainer that clones the repo using git, then mount the [EmptyDir](#emptydir) into the Pod's container.
 {{< /warning >}}

 A `gitRepo` volume is an example of what can be done as a volume plugin.  It
@@ -443,7 +443,7 @@ be "handed off" between Pods.  GlusterFS can be mounted by multiple writers
 simultaneously.

 {{< caution >}}
-**Important:** You must have your own GlusterFS installation running before you can use it.
+You must have your own GlusterFS installation running before you can use it.
 {{< /caution >}}

 See the [GlusterFS example](https://github.com/kubernetes/examples/tree/{{< param "githubbranch" >}}/staging/volumes/glusterfs) for more details.
@@ -521,7 +521,7 @@ unmounted.  This means that an iscsi volume can be pre-populated with data, and
 that data can be "handed off" between Pods.

 {{< caution >}}
-**Important:** You must have your own iSCSI server running with the volume created before you can use it.
+You must have your own iSCSI server running with the volume created before you can use it.
 {{< /caution >}}

 A feature of iSCSI is that it can be mounted as read-only by multiple consumers
@@ -537,7 +537,7 @@ See the [iSCSI example](https://github.com/kubernetes/examples/tree/{{< param "g
 {{< feature-state for_k8s_version="v1.10" state="beta" >}}

 {{< note >}}
-**Note:** The alpha PersistentVolume NodeAffinity annotation has been deprecated
+The alpha PersistentVolume NodeAffinity annotation has been deprecated
 and will be removed in a future release. Existing PersistentVolumes using this
 annotation must be updated by the user to use the new PersistentVolume
 `NodeAffinity` field.
@@ -610,7 +610,7 @@ provisioning yet. For an example on how to run an external local provisioner,
 see the [local volume provisioner user guide](https://github.com/kubernetes-incubator/external-storage/tree/master/local-volume).

 {{< note >}}
-**Note:** The local PersistentVolume requires manual cleanup and deletion by the
+The local PersistentVolume requires manual cleanup and deletion by the
 user if the external static provisioner is not used to manage the volume
 lifecycle.
 {{< /note >}}
@@ -625,7 +625,7 @@ that data can be "handed off" between Pods.  NFS can be mounted by multiple
 writers simultaneously.

 {{< caution >}}
-**Important:** You must have your own NFS server running with the share exported before you can use it.
+You must have your own NFS server running with the share exported before you can use it.
 {{< /caution >}}

 See the [NFS example](https://github.com/kubernetes/examples/tree/{{< param "githubbranch" >}}/staging/volumes/nfs) for more details.
@@ -782,7 +782,7 @@ option for the API server. The `path` field specifies a relative path to the mou
 of the projected volume.

 {{< note >}}
-**Note:** A Container using a projected volume source as a [subPath](#using-subpath) volume mount will not
+A Container using a projected volume source as a [subPath](#using-subpath) volume mount will not
 receive updates for those volume sources.
 {{< /note >}}

@@ -818,7 +818,7 @@ spec:
 ```

 {{< caution >}}
-**Important:** Make sure you have an existing PortworxVolume with name `pxvol`
+Make sure you have an existing PortworxVolume with name `pxvol`
 before using it in the Pod.
 {{< /caution >}}

@@ -830,7 +830,7 @@ A `quobyte` volume allows an existing [Quobyte](http://www.quobyte.com) volume t
 be mounted into your Pod.

 {{< caution >}}
-**Important:** You must have your own Quobyte setup running with the volumes
+You must have your own Quobyte setup running with the volumes
 created before you can use it.
 {{< /caution >}}

@@ -846,7 +846,7 @@ means that a RBD volume can be pre-populated with data, and that data can
 be "handed off" between Pods.

 {{< caution >}}
-**Important:** You must have your own Ceph installation running before you can use RBD.
+You must have your own Ceph installation running before you can use RBD.
 {{< /caution >}}

 A feature of RBD is that it can be mounted as read-only by multiple consumers
@@ -866,7 +866,7 @@ volumes (or it can dynamically provision new volumes for persistent volume claim
 [ScaleIO Persistent Volumes](/docs/concepts/storage/persistent-volumes/#scaleio)).

 {{< caution >}}
-**Important:** You must have an existing ScaleIO cluster already setup and
+You must have an existing ScaleIO cluster already setup and
 running with the volumes created before you can use them.
 {{< /caution >}}

@@ -908,11 +908,11 @@ backed by tmpfs (a RAM-backed filesystem) so they are never written to
 non-volatile storage.

 {{< caution >}}
-**Important:** You must create a secret in the Kubernetes API before you can use it.
+You must create a secret in the Kubernetes API before you can use it.
 {{< /caution >}}

 {{< note >}}
-**Note:** A Container using a Secret as a [subPath](#using-subpath) volume mount will not
+A Container using a Secret as a [subPath](#using-subpath) volume mount will not
 receive Secret updates.
 {{< /note >}}

@@ -934,7 +934,7 @@ The StorageOS Container requires 64-bit Linux and has no additional dependencies
 A free developer license is available.

 {{< caution >}}
-**Important:** You must run the StorageOS Container on each node that wants to
+You must run the StorageOS Container on each node that wants to
 access StorageOS volumes or that will contribute storage capacity to the pool.
 For installation instructions, consult the
 [StorageOS documentation](https://docs.storageos.com).
@@ -974,7 +974,7 @@ For more information including Dynamic Provisioning and Persistent Volume Claims
 ### vsphereVolume {#vspherevolume}

 {{< note >}}
-**Prerequisite:** Kubernetes with vSphere Cloud Provider configured. For cloudprovider
+Prerequisite: Kubernetes with vSphere Cloud Provider configured. For cloudprovider
 configuration please refer [vSphere getting started guide](https://vmware.github.io/vsphere-storage-for-kubernetes/documentation/).
 {{< /note >}}

@@ -982,7 +982,7 @@ A `vsphereVolume` is used to mount a vSphere VMDK Volume into your Pod.  The con
 of a volume are preserved when it is unmounted. It supports both VMFS and VSAN datastore.

 {{< caution >}}
-**Important:** You must create VMDK using one of the following method before using with Pod.
+You must create VMDK using one of the following method before using with Pod.
 {{< /caution >}}

 #### Creating a VMDK volume
@@ -1191,16 +1191,16 @@ persistent volume:
 - `controllerPublishSecretRef`: A reference to the secret object containing
  sensitive information to pass to the CSI driver to complete the CSI
  `ControllerPublishVolume` and `ControllerUnpublishVolume` calls. This field is
-  optional, and  may be empty if no secret is required. If the secret object
+  optional, and may be empty if no secret is required. If the secret object
  contains more than one secret, all secrets are passed.
 - `nodeStageSecretRef`: A reference to the secret object containing
  sensitive information to pass to the CSI driver to complete the CSI
-  `NodeStageVolume` call. This field is optional, and  may be empty if no secret
+  `NodeStageVolume` call. This field is optional, and may be empty if no secret
  is required. If the secret object contains more than one secret, all secrets
  are passed.
 - `nodePublishSecretRef`: A reference to the secret object containing
  sensitive information to pass to the CSI driver to complete the CSI
-  `NodePublishVolume` call. This field is optional, and  may be empty if no
+  `NodePublishVolume` call. This field is optional, and may be empty if no
  secret is required. If the secret object contains more than one secret, all
  secrets are passed.

@@ -1274,7 +1274,7 @@ Its values are:
   [Linux kernel documentation](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt)

 {{< caution >}}
-**Caution:** `Bidirectional` mount propagation can be dangerous. It can damage
+`Bidirectional` mount propagation can be dangerous. It can damage
 the host operating system and therefore it is allowed only in privileged
 Containers. Familiarity with Linux kernel behavior is strongly recommended.
 In addition, any volume mounts created by Containers in Pods must be destroyed
@@ -1,5 +1,5 @@
 ---
 title: "Workloads"
-weight: 60
+weight: 50
 ---

@@ -14,8 +14,9 @@ A _Cron Job_ creates [Jobs](/docs/concepts/workloads/controllers/jobs-run-to-com

 One CronJob object is like one line of a _crontab_ (cron table) file. It runs a job periodically
 on a given schedule, written in [Cron](https://en.wikipedia.org/wiki/Cron) format.
+
 {{< note >}}
-**Note:** All **CronJob** `schedule:` times are denoted in UTC.
+All **CronJob** `schedule:` times are denoted in UTC.
 {{< /note >}}

 For instructions on creating and working with cron jobs, and for an example of a spec file for a cron job, see [Running automated tasks with cron jobs](/docs/tasks/job/automated-tasks-with-cron-jobs).
@@ -20,7 +20,7 @@ A _Deployment_ controller provides declarative updates for [Pods](/docs/concepts
 You describe a _desired state_ in a Deployment object, and the Deployment controller changes the actual state to the desired state at a controlled rate. You can define Deployments to create new ReplicaSets, or to remove existing Deployments and adopt all their resources with new Deployments.

 {{< note >}}
-**Note:** You should not manage ReplicaSets owned by a Deployment. All the use cases should be covered by manipulating the Deployment object. Consider opening an issue in the main Kubernetes repository if your use case is not covered below.
+You should not manage ReplicaSets owned by a Deployment. All the use cases should be covered by manipulating the Deployment object. Consider opening an issue in the main Kubernetes repository if your use case is not covered below.
 {{< /note >}}

 {{% /capture %}}
@@ -57,7 +57,7 @@ In this example:
  as long as the Pod template itself satisfies the rule.
  
  {{< note >}}
-  **Note:** `matchLabels` is a map of {key,value} pairs. A single {key,value} in the `matchLabels` map 
+  `matchLabels` is a map of {key,value} pairs. A single {key,value} in the `matchLabels` map 
  is equivalent to an element of `matchExpressions`, whose key field is "key", the operator is "In",
  and the values array contains only "value". The requirements are ANDed.
  {{< /note >}}
@@ -74,11 +74,11 @@ In this example:
 To create this Deployment, run the following command:

 ```shell
-kubectl create -f  https://k8s.io/examples/controllers/nginx-deployment.yaml
+kubectl create -f https://k8s.io/examples/controllers/nginx-deployment.yaml
 ```

 {{< note >}}
-**Note:** You may specify the `--record` flag to write the command executed in the resource annotation `kubernetes.io/change-cause`. It is useful for future instrospection, for example to see the commands executed in each Deployment revision.
+You may specify the `--record` flag to write the command executed in the resource annotation `kubernetes.io/change-cause`. It is useful for future introspection, for example to see the commands executed in each Deployment revision.
 {{< /note >}}

 Next, run `kubectl get deployments`. The output is similar to the following:
@@ -145,14 +145,14 @@ nginx-deployment-2035384211-qqcnn   1/1       Running   0          18s       app
 The created ReplicaSet ensures that there are three `nginx` Pods running at all times.

 {{< note >}}
-**Note:** You must specify an appropriate selector and Pod template labels in a Deployment (in this case,
+You must specify an appropriate selector and Pod template labels in a Deployment (in this case,
 `app: nginx`). Do not overlap labels or selectors with other controllers (including other Deployments and StatefulSets). Kubernetes doesn't stop you from overlapping, and if multiple controllers have overlapping selectors those controllers might conflict and behave unexpectedly.
 {{< /note >}}

 ### Pod-template-hash label

 {{< note >}}
-**Note:** Do not change this label.
+Do not change this label.
 {{< /note >}}

 The `pod-template-hash` label is added by the Deployment controller to every ReplicaSet that a Deployment creates or adopts.
@@ -163,7 +163,7 @@ and in any existing Pods that the ReplicaSet might have.
 ## Updating a Deployment

 {{< note >}}
-**Note:** A Deployment's rollout is triggered if and only if the Deployment's pod template (that is, `.spec.template`)
+A Deployment's rollout is triggered if and only if the Deployment's pod template (that is, `.spec.template`)
 is changed, for example if the labels or container images of the template are updated. Other updates, such as scaling the Deployment, do not trigger a rollout.
 {{< /note >}}

@@ -307,7 +307,7 @@ In any case, if you need to perform a label selector update, exercise great caut
 all of the implications.

 {{< note >}}
-**Note:** In API version `apps/v1`, a Deployment's label selector is immutable after it gets created.
+In API version `apps/v1`, a Deployment's label selector is immutable after it gets created.
 {{< /note >}}

 * Selector additions require the pod template labels in the Deployment spec to be updated with the new label too,
@@ -326,7 +326,7 @@ By default, all of the Deployment's rollout history is kept in the system so tha
 (you can change that by modifying revision history limit).

 {{< note >}}
-**Note:** A Deployment's revision is created when a Deployment's rollout is triggered. This means that the
+A Deployment's revision is created when a Deployment's rollout is triggered. This means that the
 new revision is created if and only if the Deployment's pod template (`.spec.template`) is changed,
 for example if you update the labels or container images of the template. Other updates, such as scaling the Deployment,
 do not create a Deployment revision, so that you can facilitate simultaneous manual- or auto-scaling.
@@ -373,7 +373,7 @@ nginx-deployment-3066724191-08mng   0/1       ImagePullBackOff   0          6s
 ```

 {{< note >}}
-**Note:** The Deployment controller will stop the bad rollout automatically, and will stop scaling up the new
+The Deployment controller will stop the bad rollout automatically, and will stop scaling up the new
 ReplicaSet. This depends on the rollingUpdate parameters (`maxUnavailable` specifically) that you have specified.
 Kubernetes by default sets the value to 25%.
 {{< /note >}}
@@ -681,7 +681,7 @@ nginx-3926361531   3         3         3         28s
 ```

 {{< note >}}
-**Note:** You cannot rollback a paused Deployment until you resume it.
+You cannot rollback a paused Deployment until you resume it.
 {{< /note >}}

 ## Deployment status
@@ -754,13 +754,13 @@ attributes to the Deployment's `.status.conditions`:
 See the [Kubernetes API conventions](https://git.k8s.io/community/contributors/devel/api-conventions.md#typical-status-properties) for more information on status conditions.

 {{< note >}}
-**Note:** Kubernetes will take no action on a stalled Deployment other than to report a status condition with
+Kubernetes will take no action on a stalled Deployment other than to report a status condition with
 `Reason=ProgressDeadlineExceeded`. Higher level orchestrators can take advantage of it and act accordingly, for
 example, rollback the Deployment to its previous version.
 {{< /note >}}

 {{< note >}}
-**Note:** If you pause a Deployment, Kubernetes does not check progress against your specified deadline. You can
+If you pause a Deployment, Kubernetes does not check progress against your specified deadline. You can
 safely pause a Deployment in the middle of a rollout and resume without triggering the condition for exceeding the
 deadline.
 {{< /note >}}
@@ -865,7 +865,7 @@ this Deployment you want to retain. The rest will be garbage-collected in the ba
 it is 10.

 {{< note >}}
-**Note:** Explicitly setting this field to 0, will result in cleaning up all the history of your Deployment
+Explicitly setting this field to 0, will result in cleaning up all the history of your Deployment
 thus that Deployment will not be able to roll back.
 {{< /note >}}

@@ -916,7 +916,7 @@ from `.spec.template` or if the total number of such Pods exceeds `.spec.replica
 Pods with `.spec.template` if the number of Pods is less than the desired number.

 {{< note >}}
-**Note:** You should not create other pods whose labels match this selector, either directly, by creating
+You should not create other pods whose labels match this selector, either directly, by creating
 another Deployment, or by creating another controller such as a ReplicaSet or a ReplicationController. If you
 do so, the first Deployment thinks that it created these other pods. Kubernetes does not stop you from doing this.
 {{< /note >}}
@@ -206,7 +206,7 @@ back-off count is reset if no new failed Pods appear before the Job's next
 status check.

 {{< note >}}
-**Note:** Issue [#54870](https://github.com/kubernetes/kubernetes/issues/54870) still exists for versions of Kubernetes prior to version 1.12
+Issue [#54870](https://github.com/kubernetes/kubernetes/issues/54870) still exists for versions of Kubernetes prior to version 1.12
 {{< /note >}}

 ## Job Termination and Cleanup
@@ -16,7 +16,7 @@ weight: 20
 {{% capture overview %}}

 {{< note >}}
-**NOTE:** A [`Deployment`](/docs/concepts/workloads/controllers/deployment/) that configures a [`ReplicaSet`](/docs/concepts/workloads/controllers/replicaset/) is now the recommended way to set up replication.
+A [`Deployment`](/docs/concepts/workloads/controllers/deployment/) that configures a [`ReplicaSet`](/docs/concepts/workloads/controllers/replicaset/) is now the recommended way to set up replication.
 {{< /note >}}

 A _ReplicationController_ ensures that a specified number of pod replicas are running at any one
@@ -16,7 +16,7 @@ weight: 40
 StatefulSet is the workload API object used to manage stateful applications.

 {{< note >}}
-**Note:** StatefulSets are stable (GA) in 1.9.
+StatefulSets are stable (GA) in 1.9.
 {{< /note >}}

 {{< glossary_definition term_id="statefulset" length="all" >}}
@@ -144,7 +144,7 @@ Cluster Domain | Service (ns/name) | StatefulSet (ns/name)  | StatefulSet Domain
 kube.local    | foo/nginx         | foo/web           | nginx.foo.svc.kube.local        | web-{0..N-1}.nginx.foo.svc.kube.local        | web-{0..N-1} |

 {{< note >}}
-**Note:** Cluster Domain will be set to `cluster.local` unless
+Cluster Domain will be set to `cluster.local` unless
 [otherwise configured](/docs/concepts/services-networking/dns-pod-service/#how-it-works).
 {{< /note >}}

@@ -93,7 +93,7 @@ time as frequent voluntary disruptions.  We call this set of features
 ## How Disruption Budgets Work

 An Application Owner can create a `PodDisruptionBudget` object (PDB) for each application.
-A PDB limits the number pods of a replicated application that are down simultaneously from
+A PDB limits the number of pods of a replicated application that are down simultaneously from
 voluntary disruptions.  For example, a quorum-based application would
 like to ensure that the number of replicas running is never brought below the
 number needed for a quorum. A web front end might want to
@@ -25,7 +25,7 @@ Pods in a Kubernetes cluster can be used in two main ways:
 * **Pods that run a single container**. The "one-container-per-Pod" model is the most common Kubernetes use case; in this case, you can think of a Pod as a wrapper around a single container, and Kubernetes manages the Pods rather than the containers directly.
 * **Pods that run multiple containers that need to work together**. A Pod might encapsulate an application composed of multiple co-located containers that are tightly coupled and need to share resources. These co-located containers might form a single cohesive unit of service--one container serving files from a shared volume to the public, while a separate "sidecar" container refreshes or updates those files. The Pod wraps these containers and storage resources together as a single manageable entity.

-The [Kubernetes Blog](http://blog.kubernetes.io) has some additional information on Pod use cases. For more information, see:
+The [Kubernetes Blog](http://kubernetes.io/blog) has some additional information on Pod use cases. For more information, see:

 * [The Distributed System Toolkit: Patterns for Composite Containers](https://kubernetes.io/blog/2015/06/the-distributed-system-toolkit-patterns)
 * [Container Design Patterns](https://kubernetes.io/blog/2016/06/container-design-patterns)
@@ -55,7 +55,7 @@ A Pod can specify a set of shared storage *volumes*. All containers in the Pod c
 You'll rarely create individual Pods directly in Kubernetes--even singleton Pods. This is because Pods are designed as relatively ephemeral, disposable entities. When a Pod gets created (directly by you, or indirectly by a Controller), it is scheduled to run on a Node in your cluster. The Pod remains on that Node until the process is terminated, the pod object is deleted, the pod is *evicted* for lack of resources, or the Node fails.

 {{< note >}}
-**Note:** Restarting a container in a Pod should not be confused with restarting the Pod. The Pod itself does not run, but is an environment the containers run in and persists until it is deleted.
+Restarting a container in a Pod should not be confused with restarting the Pod. The Pod itself does not run, but is an environment the containers run in and persists until it is deleted.
 {{< /note >}}

 Pods do not, by themselves, self-heal. If a Pod is scheduled to a Node that fails, or if the scheduling operation itself fails, the Pod is deleted; likewise, a Pod won't survive an eviction due to a lack of resources or Node maintenance. Kubernetes uses a higher-level abstraction, called a *Controller*, that handles the work of managing the relatively disposable Pod instances. Thus, while it is possible to use Pod directly, it's far more common in Kubernetes to manage your pods using a Controller. See [Pods and Controllers](#pods-and-controllers) for more information on how Kubernetes uses Controllers to implement Pod scaling and healing.
@@ -51,7 +51,7 @@ Pods, Kubernetes modifies the Pod Spec. For changes to `Env`, `EnvFrom`, and
 the Pod; for changes to `Volume`, Kubernetes modifies the Pod Spec.

 {{< note >}}
-**Note:** A Pod Preset is capable of modifying the `.spec.containers` field in a
+A Pod Preset is capable of modifying the `.spec.containers` field in a
 Pod spec when appropriate. *No* resource definition from the Pod Preset will be
 applied to the `initContainers` field.
 {{< /note >}}
@@ -13,18 +13,14 @@ we're happy to have your help! Anyone can contribute, whether you're new to the
 project or you've been around a long time, and whether you self-identify as a
 developer, an end user, or someone who just can't stand seeing typos.

-For more ways to get involved in the Kubernetes community or to learn about us,
-also visit the [Kubernetes community site](/community/).
-
-Looking for the [style guide](/docs/contribute/style/style-guide/) or the
-[Kubernetes Community site](/community/)?
-{{% /capture %}}
+For more ways to get involved in the Kubernetes community or to learn about us, visit the [Kubernetes community site](/community/). 
+For information on the Kubernetes documentation style guide, see the [style guide](/docs/contribute/style/style-guide/).

 {{% capture body %}}

-## Types of contributor
+## Types of contributors

- A _member_ of the Kubernetes organization has [signed the CLA](/docs/contribute/start#sign-the-cla)
+- A _member_ of the Kubernetes organization who has [signed the CLA](/docs/contribute/start#sign-the-cla)
  and contributed some time and effort to the project. See
  [Community membership](https://github.com/kubernetes/community/blob/master/community-membership.md)
  for specific criteria for membership.
@@ -33,8 +29,8 @@ Looking for the [style guide](/docs/contribute/style/style-guide/) or the
  added to the appropriate Github group and `OWNERS` files in the Github
  repository, by a SIG Docs Approver.
 - A SIG Docs _approver_ is a member in good standing who has shown a continued
-  commitment to the project and is granted the ability to merge pull requests
-  and thus to publish content on behalf of the Kubernetes organization.
+  commitment to the project. An approver can merge pull requests
+  and publish content on behalf of the Kubernetes organization.
  Approvers can also represent SIG Docs in the larger Kubernetes community.
  Some of the duties of a SIG Docs approver, such as coordinating a release,
  require a significant time commitment.
@@ -54,7 +50,7 @@ documentation, but it should help you get started.
  - File actionable bugs
 - [Member](/docs/contribute/start/)
  - Improve existing docs
-  - Bring up ideas for improvement on Slack or SIG docs mailing list
+  - Bring up ideas for improvement on [Slack](http://slack.k8s.io/) or the [SIG docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs)
  - Improve docs accessibility
  - Provide non-binding feedback on PRs
  - Write a blog post or case study
@@ -98,7 +98,7 @@ SIG Docs [reviewers](/docs/contribute/participating/#reviewers) can sponsor
 new contributors.

 After a new contributor has successfully submitted 5 substantive pull requests
-to one or more Kubernetes repositiries, they are eligible to apply for
+to one or more Kubernetes repositories, they are eligible to apply for
 [membership](/docs/contribute/participating#members) in the Kubernetes
 organization. The contributor's membership needs to be backed by two sponsors
 who are already reviewers.
@@ -9,7 +9,6 @@ This page shows how to automatically generate reference pages for the
 commands provided by the `kubectl` tool.

 {{< note >}}
-**Note:**
 This topic shows how to generate reference documentation for
 [kubectl commands](/docs/reference/generated/kubectl/kubectl-commands)
 like
@@ -132,7 +131,6 @@ on how to do this, see
 Monitor your cherry-pick pull request until it is merged into the release branch.

 {{< note >}}
-**Note:**
 Proposing a cherry pick requires that you have permission to set a label and a
 milestone in your pull request. If you don’t have those permissions, you will
 need to work with someone who can set the label and milestone for you.
@@ -98,7 +98,7 @@ or more comments in the Kubernetes source code.
 ### Making changes to comments in the source code

 {{< note >}}
-**Note**: The following steps are an example, not a general procedure. Details 
+The following steps are an example, not a general procedure. Details 
 will be different in your situation.
 {{< /note >}}

@@ -184,7 +184,7 @@ to monitor your pull request until it has been merged.
 is an example of a pull request that fixes a typo in the Kubernetes source code.

 {{< note >}}
-**Note**: It can be tricky to determine the correct source file to be changed. In the
+It can be tricky to determine the correct source file to be changed. In the
 preceding example, the authoritative source file is under the `staging` directory
 in the `kubernetes/kubernetes` repository. But in your situation,the `staging` directory
 might not be the place to find the authoritative source. For guidance, check the
@@ -208,9 +208,11 @@ commit into the release-1.9 branch. The idea is to cherry pick the commit that e
 the commit that has the results of running the scripts. For instructions, see
 [Propose a Cherry Pick](https://github.com/kubernetes/community/blob/master/contributors/devel/cherry-picks.md). 

-**Note:** Proposing a cherry pick requires that you have permission to set a label and a milestone in your
+{{< note >}}
+Proposing a cherry pick requires that you have permission to set a label and a milestone in your
 pull request. If you don't have those permissions, you will need to work with someone who can set the label
 and milestone for you.
+{{< /note >}}

 When you have a pull request in place for cherry picking your one commit into the release-1.9 branch,
 the next step is to run these scripts in the release-1.9 branch of your local environment.
@@ -12,7 +12,6 @@ reference documentation for tools and components in the

 {{% /capture %}}

-
 {{% capture prerequisites %}}

 * You need a machine that is running Linux or macOS.
@@ -36,7 +35,6 @@ information, see

 {{% /capture %}}

-
 {{% capture steps %}}

 ## Getting two repositories
@@ -71,7 +69,6 @@ your base directory is `$GOPATH/src/github.com/kubernetes/kubernetes.`
 The remaining steps refer to your base directory as `<k8s-base>`.

 {{< note >}}
-**Note:**
 If you only need to generate, but not change, the reference docs, you don't need to
 manually get the `kubernetes/kubernetes` repository. When you run the `update-imported-docs`
 tool, it automatically clones the `kubernetes/kubernetes` repository.
@@ -109,16 +106,15 @@ to do this, see
 Monitor your cherry-pick pull request until it is merged into the release branch.

 {{< note >}}
-**Note:** Proposing a cherry pick requires that you have permission to set a label
+Proposing a cherry pick requires that you have permission to set a label
 and a milestone in your pull request. If you don’t have those permissions, you will
 need to work with someone who can set the label and milestone for you.
 {{< /note >}}

 ## Overview of update-imported-docs

-The website repository contains a `update-imported-docs` tool under the
-`kubernetes/website/update-imported-docs/` directory that performs the
-following steps:
+The `update-imported-docs` tool is located in the `kubernetes/website/update-imported-docs/`
+directory. The tool performs the following steps:

 1. Clones the related repositories specified in a configuration file. For the
   purpose of generating reference docs, the repositories that are cloned by
@@ -135,8 +131,8 @@ to `kubernetes/website`.

 ## Customizing the config file

-Open `<web-base>/update-imported-docs/reference.yaml` for editing.
-Do not change the content for the `generate-command` entry unless you undertand
+Open `<web-base>/update-imported-docs/reference.yml` for editing.
+Do not change the content for the `generate-command` entry unless you understand
 what it is doing and need to change the specified release branch.

 ```shell
@@ -160,8 +156,9 @@ repos:
    make comp
 ```

-The `update-imported-docs` tool uses `src` and `dst` fields in a configuration
-to decide the source and target location for doc files to be copied.
+In reference.yml, the `files` field is a list of `src` and `dst` fields. The `src` field
+specifies the location of a generated Markdown file, and the `dst` field specifies
+where to copy this file in the cloned `kubernetes/website` repository.
 For example:

 ```yaml
@@ -241,6 +238,4 @@ topics will be visible in the
 * [Generating Reference Documentation for the Kubernetes API](/docs/home/contribute/generated-reference/kubernetes-api/)
 * [Generating Reference Documentation for the Kubernetes Federation API](/docs/home/contribute/generated-reference/federation-api/)

-{{% /capture %}}
-
-
+{{% /capture %}}
@@ -12,8 +12,7 @@ This page assumes that you've read and mastered the tasks in the
 learn about more ways to contribute.

 {{< note >}}
-**Note:** Some tasks require you to use the Git command line client and other
-tools.
+Some tasks require you to use the Git command line client and other tools.
 {{< /note >}}

 {{% /capture %}}
@@ -38,7 +37,7 @@ that one person does all of them all of the time.
 In any given week, a specific docs approver volunteers to do initial triage
 and review of [pull requests and issues](#triage-and-categorize-issues). This
 person is the "PR Wrangler" for the week. The schedule is maintained using the
-[PR Wrangler scheduler(https://github.com/kubernetes/website/wiki/PR-Wranglers).
+[PR Wrangler scheduler](https://github.com/kubernetes/website/wiki/PR-Wranglers).
 To be added to this list, attend the weekly SIG Docs meeting and volunteer. Even
 if you are not on the schedule for the current week, you can still review pull
 requests (PRs) that are not already under active review.
@@ -387,11 +386,11 @@ most up-to-date version of that branch.
      ```

      {{< note >}}
-**Note:** Do not reference a Github issue or pull request by ID or URL in the
-commit message. If you do, it will cause that issue or pull request to get
-a notification every time the commit shows up in a new Git branch. You can
-link issues and pull requests together later, in the Github UI.
-{{< /note >}}
+      Do not reference a Github issue or pull request by ID or URL in the
+      commit message. If you do, it will cause that issue or pull request to get
+      a notification every time the commit shows up in a new Git branch. You can
+      link issues and pull requests together later, in the Github UI.
+      {{< /note >}}

 5.  Optionally, you can test your change by staging the site locally using the
    `hugo` command. See [View your changes locally](#view-your-changes-locally).
@@ -528,7 +527,7 @@ In any given week, a specific docs approver volunteers to do initial
 on this list, attend the weekly SIG Docs meeting and volunteer. Even if you are
 not on the schedule for the current week, you can still review PRs.

-People in SIG Docs are only responsible for triaging and categorizing
+People in SIG Docs are responsible only for triaging and categorizing
 documentation issues. General website issues are also filed in the
 `kubernetes/website` repository.

@@ -626,6 +625,13 @@ resolve the issue. Dead links in the API and Kubectl docs are automation issues
 and should be assigned a P1 until the problem can be fully understood. All other
 dead links are issues that need to be manually fixed and can be assigned a P3.

+#### Blog issues
+
+[Kubernetes Blog](https://kubernetes.io/blog/) entries are expected to become
+outdated over time, so we maintain only blog entries that are less than one year old. 
+If an issue is related to a blog entry that is more than one year old, it should be closed
+without fixing. 
+
 #### Support requests or code bug reports

 Some issues opened for docs are instead issues with the underlying code, or
@@ -800,6 +806,18 @@ content. See [Localization](/docs/contribute/localization/) and ask on the
 [kubernetes-sig-docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs)
 or in `#sig-docs` on Slack if you are interested in helping out.

+### Working with localized content
+
+Follow these guidelines for working with localized content:
+
+- Limit PRs to a single language. 
+
+   Each language has its own reviewers and approvers.
+
+- Reviewers, verify that PRs contain changes to only one language.
+
+   If a PR contains changes to source in more than one language, ask the PR contributor to open separate PRs for each language.
+
 {{% /capture %}}

 {{% capture whatsnext %}}
@@ -29,6 +29,10 @@ Localizations must meet some requirements for workflow (*how* to localize) and o

 To add a new localization of the Kubernetes documentation, you'll need to update the website by modifying the  [site configuration](#modify-the-site-configuration) and [directory structure](#add-a-new-localization-directory). Then you can start [translating documents](#translating-documents)!

+{{< note >}}
+For an example localization-related [pull request](../create-pull-request), see [this pull request](https://github.com/kubernetes/website/pull/8636) to the [Kubernetes website repo](https://github.com/kubernetes/website) adding Korean localization to the Kubernetes docs.
+{{< /note >}}
+
 Let Kubernetes SIG Docs know you're interested in creating a localization! Join the [SIG Docs Slack channel](https://kubernetes.slack.com/messages/C1J0BPD2M/). We're happy to help you get started and answer any questions you have.

 All localization teams must be self-sustaining with their own resources. We're happy to host your work, but we can't translate it for you.
@@ -199,7 +203,7 @@ For more information about working from forks or directly from the repository, s

 ### Upstream contributions

-SIG Docs welcomes upstream contributions and corrections to the English source! Open a [pull request](https://kubernetes.io/docs/contribute/start/#improve-existing-content) (from a fork) with any updates.
+SIG Docs welcomes [upstream contributions and corrections](/docs/contribute/intermediate#localize-content) to the English source. 

 {{% /capture %}}

@@ -84,7 +84,7 @@ in the Kubernetes organization. Follow these steps:
 1.  Find two reviewers or approvers to [sponsor](/docs/contribute/advanced#sponsor-a-new-contributor)
    your membership.
    
-      Ask for sponsorship in the #sig-docs channel on the 
+      Ask for sponsorship in the [#sig-docs channel on the 
      Kubernetes Slack instance](https://kubernetes.slack.com) or on the
      [SIG Docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs).
      
@@ -24,12 +24,7 @@ code repositories, refer to

 ## The basics about our docs

-The Kubernetes documentation is written in Markdown and processed and deployed
-using Hugo. The source is in Github at
-[https://github.com/kubernetes/website](https://github.com/kubernetes/website).
-Most of the documentation source is stored in `/content/en/docs/`. Some of the
-reference documentation is automatically generated from scripts in the
-`update-imported-docs/` directory.
+The Kubernetes documentation is written in Markdown and processed and deployed using Hugo. The source is in Github at [https://github.com/kubernetes/website](https://github.com/kubernetes/website). Most of the documentation source is stored in `/content/en/docs/`. Some of the reference documentation is automatically generated from scripts in the `update-imported-docs/` directory.

 You can file issues, edit content, and review changes from others, all from the
 Github website. You can also use Github's embedded history and search tools.
@@ -70,6 +65,14 @@ We make use of the standard Hugo shortcodes, as well as a few that are custom to
 the Kubernetes documentation. See [Custom Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/) for
 information about how to use them.

+### Multiple languages 
+
+Documentation source is available in multiple languages in `/content/`. Each language has its own folder with a two-letter code determined by the [ISO 639-1 standard](https://www.loc.gov/standards/iso639-2/php/code_list.php). For example, English documentation source is stored in `/content/en/docs/`. 
+
+For more information about contributing to documentation in multiple languages, see ["Localize content"](/docs/contribute/intermediate#localize-content) in the intermediate contributing guide.
+
+If you're interested in starting a new localization, see ["Localization"](/docs/contribute/localization/).
+
 ## File actionable issues

 Anyone with a Github account can file an issue (bug report) against the
@@ -213,7 +216,7 @@ documentation.
    include more detail if appropriate.

    {{< note >}}
-**Note**: Do not include references to other Github issues or pull
+Do not include references to other Github issues or pull
 requests in your commit message. You can add those to the pull request
 description later.
 {{< /note >}}
@@ -231,7 +234,7 @@ description later.
    **Create pull request**.
    
    {{< note >}}
-**Note**: If you don't want to create the pull request now, you can do it
+If you don't want to create the pull request now, you can do it
 later, by browsing to the main URL of the Kubernetes website repository or
 your fork's repository. The Github website will prompt you to create the
 pull request if it detects that you pushed a new branch to your fork.
@@ -32,7 +32,7 @@ weight: 10


 {{% note %}}
-**Note:** For page weights, it can be smart not to use 1, 2, 3 ..., but some other interval, say 10, 20, 30... This allows you to insert pages where you want later.
+For page weights, it can be smart not to use 1, 2, 3 ..., but some other interval, say 10, 20, 30... This allows you to insert pages where you want later.
 {{% /note %}}


@@ -56,7 +56,7 @@ linkTitle: Title used in links


 {{% note %}}
-**Note:** The above needs to be done per language. If you don't see your section in the menu, it is probably because it is not identified as a section by Hugo. Create a `_index.md` content file in the section folder.
+The above needs to be done per language. If you don't see your section in the menu, it is probably because it is not identified as a section by Hugo. Create a `_index.md` content file in the section folder.
 {{% /note %}}

 ### Documentation Side Menu
@@ -5,5 +5,5 @@ title: Example #1
 This is an **example** content file inside the **includes** leaf bundle.

 {{< note >}}
-**Note:** Included content files can also contain shortcodes.
+Included content files can also contain shortcodes.
 {{< /note >}}
@@ -14,7 +14,7 @@ Read more about shortcodes in the [Hugo documentation](https://gohugo.io/content
 {{% capture body %}}
 ## Feature state

-In a markdown page (.md file) on this site, you can add a shortcode to display version and state of the documented feature.
+In a markdown page (`.md` file) on this site, you can add a shortcode to display version and state of the documented feature.

 ### Feature state demo

@@ -24,7 +24,7 @@ Below is a demo of the feature state snippet, which displays the feature as stab
 {{</* feature-state for_k8s_version="v1.10" state="stable" */>}}
 ```

-Will render to: 
+Renders to: 

 {{< feature-state for_k8s_version="v1.10" state="stable" >}}

@@ -37,8 +37,6 @@ The valid values for `state` are:

 ### Feature state code

-Below is the template code for each available feature state.
-
 The displayed Kubernetes version defaults to that of the page or the site. This can be changed by passing the <code>for_k8s_version</code> shortcode parameter.

 ````
@@ -92,14 +90,14 @@ Renders to:

 ## Glossary

-You can reference glossary terms with an inclusion that will automatically update and replace content with the relevant links from [our glossary](/docs/reference/glossary/). When the term is moused-over by someone
-using the online documentation, the glossary entry will display a tooltip.
+You can reference glossary terms with an inclusion that automatically updates and replaces content with the relevant links from [our glossary](/docs/reference/glossary/). When the term is moused-over by someone
+using the online documentation, the glossary entry displays a tooltip.

 The raw data for glossary terms is stored at [https://github.com/kubernetes/website/tree/master/content/en/docs/reference/glossary](https://github.com/kubernetes/website/tree/master/content/en/docs/reference/glossary), with a content file for each glossary term.

 ### Glossary Demo

-For example, the following include within the markdown will render to {{< glossary_tooltip text="cluster" term_id="cluster" >}} with a tooltip:
+For example, the following include within the markdown renders to {{< glossary_tooltip text="cluster" term_id="cluster" >}} with a tooltip:

 ````liquid
 {{</* glossary_tooltip text="cluster" term_id="cluster" */>}}
@@ -113,9 +111,8 @@ The `tabs` shortcode takes these parameters:

 * `name`: The name as shown on the tab.
 * `codelang`: If you provide inner content to the `tab` shortcode, you can tell Hugo what code language to use for highlighting.
-* `include`: The file to include in the tab. If the tab lives in a Hugo [leaf bundle](https://gohugo.io/content-management/page-bundles/#leaf-bundles), the file -- which can be any MIME type supported by Hugo -- will be looked up in the bundle itself. If not, the content page to include will be looked up relative to the current. Note that with the `include` you will not have any shortcode inner content and must use the self-closing syntax, e.g. {{</* tab name="Content File #1" include="example1" /*/>}}. Non-content files will be code-highlighted. The language to use will be taken from the filename if not provided in `codelang`.
-
-* If your inner content is markdown, you must use `%`-delimiter to surorund the tab, e.g. `{{%/* tab name="Tab 1" %}}This is **markdown**{{% /tab */%}}`
+* `include`: The file to include in the tab. If the tab lives in a Hugo [leaf bundle](https://gohugo.io/content-management/page-bundles/#leaf-bundles), the file -- which can be any MIME type supported by Hugo -- is looked up in the bundle itself. If not, the content page that needs to be included is looked up relative to the current page. Note that with the `include`, you do not have any shortcode inner content and must use the self-closing syntax. For example, <code>{{</* tab name="Content File #1" include="example1" /*/>}}</code>. The language needs to be specified under `codelang` or the language is taken based on the file name. Non-content files are code-highlighted by default. 
+* If your inner content is markdown, you must use the `%`-delimiter to surround the tab. For example, `{{%/* tab name="Tab 1" %}}This is **markdown**{{% /tab */%}}`
 * You can combine the variations mentioned above inside a tab set.

 Below is a demo of the tabs shortcode.
@@ -137,7 +134,7 @@ println "This is tab 2."
 {{< /tabs */>}}
 ```

-Will be rendered as:
+Renders to: 

 {{< tabs name="tab_with_code" >}}
 {{< tab name="Tab 1" codelang="bash" >}}
@@ -154,7 +151,9 @@ println "This is tab 2."
 {{</* tabs name="tab_with_md" >}}
 {{% tab name="Markdown" %}}
 This is **some markdown.**
-{{< note >}}**Note:** It can even contain shortcodes.{{< /note >}}
+{{< note >}}
+It can even contain shortcodes.
+{{< /note >}}
 {{% /tab %}}
 {{< tab name="HTML" >}}
 <div>
@@ -165,12 +164,16 @@ This is **some markdown.**
 {{< /tabs */>}}
 ```

-Will be rendered as:
+Renders to:

 {{< tabs name="tab_with_md" >}}
 {{% tab name="Markdown" %}}
 This is **some markdown.**
-{{< note >}}**Note:** It can even contain shortcodes.{{< /note >}}
+
+{{< note >}}
+It can even contain shortcodes.
+{{< /note >}}
+
 {{% /tab %}}
 {{< tab name="HTML" >}}
 <div>
@@ -190,7 +193,7 @@ This is **some markdown.**
 {{< /tabs */>}}
 ```

-Will be rendered as:
+Renders to:

 {{< tabs name="tab_with_file_include" >}}
 {{< tab name="Content File #1" include="example1" />}}
@@ -15,7 +15,7 @@ directory of the [`kubernetes/website`](https://github.com/kubernetes/website)
 repository.

 {{< note >}}
-**Note**: Every new topic needs to use a template. If you are unsure which
+Every new topic needs to use a template. If you are unsure which
 template to use for a new topic, start with the
 [concept template](#concept-template).
 {{< /note >}}
@@ -75,7 +75,7 @@ To write a new concept page, create a Markdown file in a subdirectory of the

 An example of a published topic that uses the concept template is
 [Annotations](/docs/concepts/overview/working-with-objects/annotations/). The
-page you are currently reading also uses the content template.
+page you are currently reading also uses the concept template.

 ## Task template

--- a/Show More
+++ b/Show More