github
/
k3s
mirror of https://github.com/k3s-io/k3s
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #21717 from jeffmendoza/sample-guidelines 

Auto commit by PR queue bot
pull/6/head
k8s-merge-robot 2016-03-03 13:18:29 -08:00
parent b05cf6d53a d303112875
commit 80e201f74b
2 changed files with 136 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
examples/README.md
View File

@ -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 -->

118
examples/guidelines.md Normal file
View File

@ -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 -->