90 lines
4 KiB
Markdown
90 lines
4 KiB
Markdown
# 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.
|
|
* Use `kubectl` instead of `cluster\kubectl.sh` for example cli
|
|
commands.
|
|
|
|
### 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 -->
|
|
[]()
|
|
<!-- END MUNGE: GENERATED_ANALYTICS -->
|