Change:
Demonstrations of how to use specific Kubernetes features can be found in our [documents](../docs/). <ins> ### 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. </ins> <!-- BEGIN MUNGE: GENERATED_ANALYTICS --> [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/examples/README.md?pixel)]() <!-- END MUNGE: GENERATED_ANALYTICS -->

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: