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

content/en/docs/reference/kubectl/overview.md

@@ -349,6 +349,87 @@ $ kubectl logs <pod-name>
 $ kubectl logs -f <pod-name>
 ```
 
+## Examples: Creating and using plugins
+
+Use the following set of examples to help you familiarize yourself with writing and using `kubectl` plugins:
+
+```shell
+// create a simple plugin in any language and name the resulting executable file
+// so that it begins with the prefix "kubectl-"
+$ cat ./kubectl-hello
+#!/bin/bash
+
+# this plugin prints the words "hello world"
+echo "hello world"
+
+// with our plugin written, let's make it executable
+$ sudo chmod +x ./kubectl-hello
+
+// and move it to a location in our PATH
+$ sudo mv ./kubectl-hello /usr/local/bin
+
+// we have now created and "installed" a kubectl plugin.
+// we can begin using our plugin by invoking it from kubectl as if it were a regular command
+$ kubectl hello
+hello world
+
+// we can "uninstall" a plugin, by simply removing it from our PATH
+$ sudo rm /usr/local/bin/kubectl-hello
+```
+
+In order to view all of the plugins that are available to `kubectl`, we can use
+the `kubectl plugin list` subcommand:
+
+```shell
+$ kubectl plugin list
+The following kubectl-compatible plugins are available:
+
+/usr/local/bin/kubectl-hello
+/usr/local/bin/kubectl-foo
+/usr/local/bin/kubectl-bar
+
+// this command can also warn us about plugins that are
+// not executable, or that are overshadowed by other
+// plugins, for example
+$ sudo chmod -x /usr/local/bin/kubectl-foo
+$ kubectl plugin list
+The following kubectl-compatible plugins are available:
+
+/usr/local/bin/kubectl-hello
+/usr/local/bin/kubectl-foo
+  - warning: /usr/local/bin/kubectl-foo identified as a plugin, but it is not executable
+/usr/local/bin/kubectl-bar
+
+error: one plugin warning was found
+```
+
+We can think of plugins as a means to build more complex functionality on top
+of the existing kubectl commands:
+
+```shell
+$ cat ./kubectl-whoami
+#!/bin/bash
+
+# this plugin makes use of the `kubectl config` command in order to output
+# information about the current user, based on the currently selected context
+kubectl config view --template='{{ range .contexts }}{{ if eq .name "'$(kubectl config current-context)'" }}Current user: {{ .context.user }}{{ end }}{{ end }}'
+```
+
+Running the above plugin gives us an output containing the user for the currently selected
+context in our KUBECONFIG file:
+
+```shell
+// make the file executable
+$ sudo chmod +x ./kubectl-whoami
+
+// and move it into our PATH
+$ sudo mv ./kubectl-whoami /usr/local/bin
+
+$ kubectl whoami
+Current user: plugins-user
+```
+
+To find out more about plugins, take a look at the [example cli plugin](https://github.com/kubernetes/sample-cli-plugin).
 
 ## Next steps
 

content/en/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions.md

@@ -447,8 +447,9 @@ The column's `format` controls the style used when `kubectl` prints the value.
 
 ### Subresources
 
+{{< feature-state state="beta" for_kubernetes_version="1.11" >}}
+
 Custom resources support `/status` and `/scale` subresources.
-This feature is __beta__ in v1.11 and enabled by default.
 
 You can disable this feature using the `CustomResourceSubresources` feature gate on
 the [kube-apiserver](/docs/admin/kube-apiserver):
@@ -469,7 +470,28 @@ When the status subresource is enabled, the `/status` subresource for the custom
 - `PUT` requests to the `/status` subresource only validate the status stanza of the custom resource.
 - `PUT`/`POST`/`PATCH` requests to the custom resource ignore changes to the status stanza.
 - Any changes to the spec stanza increments the value at `.metadata.generation`.
-- `properties`, `required` and `description` are the only constructs allowed in the root of the CRD OpenAPI validation schema.
+- Only the following constructs are allowed at the root of the CRD OpenAPI validation schema:
+
+  - Description
+  - Example
+  - ExclusiveMaximum
+  - ExclusiveMinimum
+  - ExternalDocs
+  - Format
+  - Items
+  - Maximum
+  - MaxItems
+  - MaxLength
+  - Minimum
+  - MinItems
+  - MinLength
+  - MultipleOf
+  - Pattern
+  - Properties
+  - Required
+  - Title
+  - Type
+  - UniqueItems
 
 #### Scale subresource