Merge pull request #21717 from jeffmendoza/sample-guidelines

Auto commit by PR queue bot

examples/README.md

@@ -40,6 +40,24 @@ real applications with Kubernetes.
 Demonstrations of how to use specific Kubernetes features can be found in our [documents](../docs/).
 
 
+### Maintained Examples
+
+Maintained Examples are expected to be updated with every Kubernetes
+release, to use the latest and greatest features, current guidelines
+and best practices, and to refresh command syntax, output, changed
+prerequisites, as needed.
+
+Name | Description | Notable Features Used | Complexity Level
+------------- | ------------- | ------------ | ------------ | ------------
+[Guestbook](guestbook/) | PHP app with Redis | Replication Controller, Service | Beginner
+[WordPress](mysql-wordpress-pd/) | WordPress with MySQL | Deployment, Persistent Volume with Claim | Beginner
+[Cassandra](cassandra/) | Cloud Native Cassandra | Daemon Set | Intermediate
+
+Note: Please add examples to the list above that are maintained.
+
+See [Example Guidelines](guidelines.md) for a description of what goes
+in this directory, and what examples should contain.
+
 <!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
 [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/examples/README.md?pixel)]()
 <!-- END MUNGE: GENERATED_ANALYTICS -->

examples/guidelines.md

@@ -0,0 +1,118 @@
+<!-- BEGIN MUNGE: UNVERSIONED_WARNING -->
+
+<!-- BEGIN STRIP_FOR_RELEASE -->
+
+<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
+     width="25" height="25">
+<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
+     width="25" height="25">
+<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
+     width="25" height="25">
+<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
+     width="25" height="25">
+<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
+     width="25" height="25">
+
+<h2>PLEASE NOTE: This document applies to the HEAD of the source tree</h2>
+
+If you are using a released version of Kubernetes, you should
+refer to the docs that go with that version.
+
+Documentation for other releases can be found at
+[releases.k8s.io](http://releases.k8s.io).
+</strong>
+--
+
+<!-- END STRIP_FOR_RELEASE -->
+
+<!-- END MUNGE: UNVERSIONED_WARNING -->
+
+# Example Guidelines
+
+## An Example Is
+
+An example demonstrates running an application/framework/workload on
+Kubernetes in a meaningful way. It is educational and informative.
+
+Examples are not:
+
+* Full app deployments, ready to use, with no explanation. These
+  belong either
+  [here](https://github.com/kubernetes/application-dm-templates) or in
+  something like [Helm](https://github.com/helm/charts).
+* Simple toys to show how to use a Kubernetes feature. These belong in
+  the [user guide](../docs/user-guide/).
+* Demos that follow a script to show a Kubernetes feature in
+  action. Example: killing a node to demonstrate controller
+  self-healing.
+* A tutorial which guides the user through multiple progressively more
+  complex deployments to arrive at the final solution. An example
+  should just demonstrate how to setup the correct deployment
+
+## An Example Includes
+
+### Up front
+
+* Has a "this is what you'll learn" section.
+* Has a Table of Contents.
+* Has a section that brings up the app in the fewest number of
+  commands (TL;DR / quickstart), without cloning the repo (kubectl
+  apply -f http://...).
+* Points to documentation of prerequisites.
+  * [Create a cluster](../docs/getting-started-guides/) (e.g., single-node docker).
+  * [Setup kubectl](../docs/user-guide/prereqs.md).
+  * etc.
+* Should specify which release of Kubernetes is required and any other
+  prerequisites, such as DNS, a cloudprovider with PV provisioning, a
+  cloudprovider with external load balancers, etc.
+  * Point to general documentation about alternatives for those
+    mechanisms rather than present the alternatives in each example.
+  * Tries to balance between using using new features, and being
+    compatible across environments.
+
+### Throughout
+
+* Should point to documentation on first mention:
+  [kubectl](../docs/user-guide/kubectl-overview.md),
+  [pods](../docs/user-guide/pods.md),
+  [services](../docs/user-guide/services.md),
+  [deployments](../docs/user-guide/deployments.md),
+  [replication controllers](../docs/user-guide/replication-controller.md),
+  [jobs](../docs/user-guide/jobs.md),
+  [labels](../docs/user-guide/labels.md),
+  [persistent volumes](../docs/user-guide/persistent-volumes.md),
+  etc.
+* Most examples should be cloudprovider-independent (e.g., using PVCs, not PDs).
+  * Other examples with cloudprovider-specific bits could be somewhere else.
+* Actually show the app working -- console output, and or screenshots.
+  * Ascii animations and screencasts are recommended.
+* Follows [config best practices](../docs/user-guide/config-best-practices.md).
+* Shouldn't duplicate the [thorough walk-through](../docs/user-guide/#thorough-walkthrough).
+* Docker images are pre-built, and source is contained in a subfolder.
+  * Source is the Dockerfile and any custom files needed beyond the
+    upstream app being packaged.
+  * Images are pushed to `gcr.io/google-samples`. Contact @jeffmendoza
+    to have an image pushed
+  * Images are tagged with a version (not latest) that is referenced
+    in the example config.
+* Only use the code highlighting types
+  [supported by Rouge](https://github.com/jneen/rouge/wiki/list-of-supported-languages-and-lexers),
+  as this is what Github Pages uses.
+* Commands to be copied use the `shell` syntax highlighting type, and
+  do not include any kind of prompt.
+* Example output is in a separate block quote to distinguish it from
+  the command (which doesn't have a prompt).
+* When providing an example command or config for which the user is
+  expected to substitute text with something specific to them, use
+  angle brackets: `<IDENTIFIER>` for the text to be substituted.
+
+
+### At the end
+
+* Should have a section suggesting what to look at next, both in terms
+  of "additional resources" and "what example to look at next".
+
+
+<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
+[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/examples/guidelines.md?pixel)]()
+<!-- END MUNGE: GENERATED_ANALYTICS -->