Change:
<ins> <!-- 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 --> </ins>

Discussion:
Forked from , , , , , and other issues. We need to decide how we want examples to be written, document that, and make existing examples conform. Issues: Decide objectives: teaching system concepts, demonstrating system features, getting started quickly with a particular application, providing sample configurations that can be extended by the user for real use cases, ... If teaching concepts or demonstrating features, which ones? How many examples need to illustrate the same concepts/features? What techniques do we want to use to make the examples engaging: interactivity, rewards, etc.? Does it need to be a realistic application configuration (e.g., HA)? Should the example demonstrate the application being used? System best practices Show individual files and then combined files? Show singleton pods and then demonstrate why controllers are needed for self-healing? Secret Cross references to other documentation (e.g., concept and feature documentation) Consistent organization (e.g., should the summary appear at the beginning or the end?) Keeping examples up to date with new features and evolving conventions Repo locations for text vs. config and code Whether/how to show multiple solutions (e.g., kubectl run and yaml) Shell command format (e.g., prompt or no prompt) kubectl output or not Screenshots How to make it possible to run examples without cloning the whole repo System addons that can be assumed (e.g., DNS) Examples that show the cluster being created and destroyed in addition to deploying the application Cloud-provider-specific examples vs. portable examples Unit and end-to-end testing of the examples cc
There is overlap with the quick walkthrough: And with the detailed walkthrough:
+1 This is very meaningful. can make the examples more clear and usable. But can't unify patten, describe and section very well. I can summary your review and my work to give a little suggest to this issue.
Reworking guestbook:
cc
For inspiration:
We've decided to separate tutorials from canned applications -- the latter is covered by .
Interactive demos: More demos:
cc
Quick thoughts: Should point to documentation of prerequisites Create a cluster (e.g., single-node docker) Setup kubectl Should point to documentation on first mention: pods, kubectl, etc.

Should have a "this is what you'll learn" section at beginning Should have a section suggesting what to look at next at the end Should have a section that brings up the app in the fewest number of commands (TL;DR / quickstart), ideally without cloning the repo (kubectl -f http:...) Most examples should be cloudprovider-independent (e.g., using PVCs, not PDs) We could have other examples with cloudprovider-specific bits somewhere else We should distinguish teaching examples, real app setups, tutorials, and demos (e.g., update demo or killing a node to demonstrate controller self-healing) Demonstrations of kubernetes features rather than apps belong in the user guide We shouldn't duplicate the thorough walkthrough
And we should mark which examples are maintained vs not. cc
I would like to see each app example actually show the app working -- output, ascii animations, or screenshots. For example:
The Openshift examples README does a decent job of explaining what each example demonstrates:
We 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. My current preference would be to point to general documentation about alternatives for those mechanisms rather than present the alternatives in each example.
Guidelines are here: