diff --git a/examples/README.md b/examples/README.md index 476c70bb9a1..ba955d4da8f 100644 --- a/examples/README.md +++ b/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. + [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/examples/README.md?pixel)]() diff --git a/examples/guidelines.md b/examples/guidelines.md new file mode 100644 index 00000000000..8d31eddc294 --- /dev/null +++ b/examples/guidelines.md @@ -0,0 +1,118 @@ + + + + +WARNING +WARNING +WARNING +WARNING +WARNING + +

PLEASE NOTE: This document applies to the HEAD of the source tree

+ +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). + +-- + + + + + +# 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: `` 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". + + + +[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/examples/guidelines.md?pixel)]() +