|
1 | | -# Example Guidelines |
2 | | - |
3 | | -## An Example Is |
4 | | - |
5 | | -An example demonstrates running an application/framework/workload on |
6 | | -Kubernetes in a meaningful way. It is educational and informative. |
7 | | - |
8 | | -Examples are not: |
9 | | - |
10 | | -* Full app deployments, ready to use, with no explanation. These |
11 | | - belong to [Helm charts](https://github.com/kubernetes/charts). |
12 | | -* Simple toys to show how to use a Kubernetes feature. These belong in |
13 | | - the [user guide](https://kubernetes.io/docs/home/). |
14 | | -* Demos that follow a script to show a Kubernetes feature in |
15 | | - action. Example: killing a node to demonstrate controller |
16 | | - self-healing. |
17 | | -* A tutorial which guides the user through multiple progressively more |
18 | | - complex deployments to arrive at the final solution. An example |
19 | | - should just demonstrate how to setup the correct deployment |
20 | | - |
21 | | -## An Example Includes |
22 | | - |
23 | | -### Up front |
24 | | - |
25 | | -* Has a "this is what you'll learn" section. |
26 | | -* Has a Table of Contents. |
27 | | -* Has a section that brings up the app in the fewest number of |
28 | | - commands (TL;DR / quickstart), without cloning the repo (kubectl |
29 | | - apply -f http://...). |
30 | | -* Points to documentation of prerequisites. |
31 | | - * [Create a cluster](https://github.com/kubernetes/community/blob/master/contributors/devel/running-locally.md) (e.g., single-node docker). |
32 | | - * [Setup kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). |
33 | | - * etc. |
34 | | -* Should specify which release of Kubernetes is required and any other |
35 | | - prerequisites, such as DNS, a cloudprovider with PV provisioning, a |
36 | | - cloudprovider with external load balancers, etc. |
37 | | - * Point to general documentation about alternatives for those |
38 | | - mechanisms rather than present the alternatives in each example. |
39 | | - * Tries to balance between using new features, and being |
40 | | - compatible across environments. |
41 | | - |
42 | | -### Throughout |
43 | | - |
44 | | -* Should point to documentation on first mention: |
45 | | - [kubectl](https://kubernetes.io/docs/user-guide/kubectl-overview/), |
46 | | - [pods](https://kubernetes.io/docs/concepts/workloads/pods/pod/), |
47 | | - [services](https://kubernetes.io/docs/concepts/services-networking/service/), |
48 | | - [deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/), |
49 | | - [replication controllers](https://kubernetes.io/docs/concepts/workloads/controllers/replicationcontroller/), |
50 | | - [jobs](https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/), |
51 | | - [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/), |
52 | | - [persistent volumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/), |
53 | | - etc. |
54 | | -* Most examples should be cloudprovider-independent (e.g., using PVCs, not PDs). |
55 | | - * Other examples with cloudprovider-specific bits could be somewhere else. |
56 | | -* Actually show the app working -- console output, and or screenshots. |
57 | | - * Ascii animations and screencasts are recommended. |
58 | | -* Follows [config best practices](https://kubernetes.io/docs/concepts/configuration/overview/). |
59 | | -* Shouldn't duplicate the [user guide](https://kubernetes.io/docs/home/). |
60 | | -* Docker images are pre-built, and source is contained in a subfolder. |
61 | | - * Source is the Dockerfile and any custom files needed beyond the |
62 | | - upstream app being packaged. |
63 | | - * Images are pushed to `gcr.io/google-samples`. Contact @jeffmendoza |
64 | | - to have an image pushed |
65 | | - * Images are tagged with a version (not latest) that is referenced |
66 | | - in the example config. |
67 | | -* Only use the code highlighting types |
68 | | - [supported by Rouge](https://github.com/jneen/rouge/wiki/list-of-supported-languages-and-lexers), |
69 | | - as this is what GitHub Pages uses. |
70 | | -* Commands to be copied using the `shell` syntax highlighting type, and |
71 | | - do not include any kind of prompt. |
72 | | -* Example output is in a separate block quote to distinguish it from |
73 | | - the command (which doesn't have a prompt). |
74 | | -* When providing an example command or config for which the user is |
75 | | - expected to substitute text with something specific to them, use |
76 | | - angle brackets: `<IDENTIFIER>` for the text to be substituted. |
77 | | - |
78 | | -### At the end |
79 | | - |
80 | | -* Should have a section suggesting what to look at next, both in terms |
81 | | - of "additional resources" and "what example to look at next". |
| 1 | +# Kubernetes Example Guidelines |
| 2 | + |
| 3 | +Welcome to the `kubernetes/examples` repository! This repository serves as a |
| 4 | +community-driven collection of high-quality, educational examples demonstrating |
| 5 | +how to run a diverse range of applications, frameworks, and workloads on Kubernetes. |
| 6 | +Our goal is to provide a central place for users to discover practical examples, |
| 7 | +learn common patterns, and understand best practices for deploying applications, |
| 8 | +including general-purpose workloads and specialized AI/ML workloads and platforms. |
| 9 | + |
| 10 | +These guidelines are intended for contributors to ensure that all examples are |
| 11 | +consistent, maintainable, easy to understand, and valuable to the Kubernetes community. |
| 12 | +By adhering to these guidelines, we can build a rich and up-to-date resource. |
| 13 | + |
| 14 | +## An Example Is... |
| 15 | + |
| 16 | +An example demonstrates running an application, framework, or complex workload |
| 17 | +(such as AI/ML model serving, training pipelines, associated toolchains) on Kubernetes. |
| 18 | +It must be: |
| 19 | + |
| 20 | +* Meaningful: Solves or illustrates a recognizable, real-world (though potentially simplified) use case. |
| 21 | +* Educational: Helps users learn how to deploy and manage the specific type of application |
| 22 | + or pattern on Kubernetes. It should explain the "why" behind the "how." |
| 23 | +* Illustrative of Best Practices: Showcases current Kubernetes best practices for configuration, |
| 24 | + security, and application architecture where applicable. |
| 25 | +* Focused: While it can involve multiple components, it should illustrate a specific concept |
| 26 | + or setup without becoming overly broad. For very complex systems, consider breaking them into |
| 27 | + smaller, related examples or leveraging modular design, especially for platform blueprints. |
| 28 | + |
| 29 | +## Examples Are NOT... |
| 30 | + |
| 31 | +Examples are intended for educational purposes and should not be: |
| 32 | + |
| 33 | +* Minimalistic Feature Snippets: Examples should be more comprehensive than simple snippets |
| 34 | + designed to illustrate a single Kubernetes API field. Such content is better suited for |
| 35 | + the official [Kubernetes documentation](https://kubernetes.io/docs/home/). |
| 36 | +* Pure Kubernetes Feature Demonstrations: Examples should focus on the application running |
| 37 | + on Kubernetes, not solely on demonstrating a Kubernetes feature in isolation (e.g., showing |
| 38 | + high availability is a feature demo, not an application example unless it's core to |
| 39 | + understanding how that specific application achieves HA on Kubernetes). |
| 40 | + |
| 41 | +## An Example Includes... |
| 42 | + |
| 43 | +Each example must be well-structured and documented to ensure clarity and usability. |
| 44 | + |
| 45 | +### Structure and README |
| 46 | + |
| 47 | +* Directory: Each example MUST reside in its own clearly named subdirectory within a |
| 48 | + relevant category (e.g., `/ai/`, `/databases/`). |
| 49 | +* README.md: Every example MUST have a `README.md` file. This file is crucial for |
| 50 | + understandability and usability. It SHOULD follow a consistent structure. |
| 51 | + _(TBD: establish a `EXAMPLE_README_TEMPLATE.md` to guide contributors)._ Key sections include: |
| 52 | + * Title: Clear and descriptive title of the example. |
| 53 | + * Purpose / What You'll Learn: Briefly describe what the example demonstrates and what |
| 54 | + the user will learn by using it. |
| 55 | + * Table of Contents (ToC): For longer READMEs, a ToC is highly recommended. |
| 56 | + * Prerequisites, such as: |
| 57 | + * Required Kubernetes version. |
| 58 | + * Any necessary tools (e.g., `kubectl`, `kustomize`, `helm`, `git`). |
| 59 | + * Specific hardware requirements. This is especially important for AI/ML examples. |
| 60 | + * Quick Start / TL;DR: A concise set of commands to deploy the example with minimal effort, |
| 61 | + preferably without needing to clone the repository. |
| 62 | + * Detailed Steps & Explanation: |
| 63 | + * Walk through the deployment process. |
| 64 | + * Explain the key Kubernetes manifests and their roles within the example. |
| 65 | + * Describe important configuration choices. |
| 66 | + * Verification / Seeing it Work: Commands to verify the application is running correctly, |
| 67 | + along with expected output (console logs, screenshots, or how to access an endpoint). |
| 68 | + For AI/ML examples, this might include how to check training progress or send a test inference request. |
| 69 | + * Configuration Customization (Optional but Recommended): Guidance on how users can |
| 70 | + customize common parameters. |
| 71 | + * Cleanup: Commands to remove all resources created by the example. |
| 72 | + * Troubleshooting (Optional): Common issues and how to resolve them. |
| 73 | + * Further Reading / Next Steps: Links to relevant official documentation, related |
| 74 | + examples, or more advanced topics. |
| 75 | + * Maintainer(s) (Optional): GitHub username(s) of primary maintainers. |
| 76 | + * Last Validated Kubernetes Version (Recommended): The Kubernetes version against |
| 77 | + which the example was last successfully tested. |
| 78 | + |
| 79 | +### Manifests and Configuration |
| 80 | + |
| 81 | +* Clarity and Best Practices: Manifests should be well-commented where non-obvious. |
| 82 | + They must follow [Kubernetes configuration best practices](https://kubernetes.io/docs/concepts/configuration/overview/) |
| 83 | + and general [security best practices](https://kubernetes.io/docs/concepts/security/overview/). |
| 84 | +* Kubernetes API Usage: |
| 85 | + * Use stable APIs whenever possible. If beta or alpha features are used, they must |
| 86 | + be explicitly mentioned along with any necessary feature gates. |
| 87 | + * Avoid deprecated APIs or features. Reference API documentation for core or custom workload APIs. |
| 88 | +* Vendor neutral: Do not endorse one particular ecosystem tool or cloud-provider. |
| 89 | + * Individual manifests will inherently use specific tools to fulfill their purpose. |
| 90 | + However, examples will be open to manifests for a diverse set of tools, governed |
| 91 | + by community interest and contribution. |
| 92 | + * If an example *must* use cloud-provider-specific features (e.g., specific AI accelerators, |
| 93 | + managed database services critical to an AI workload/platform), this dependency MUST be |
| 94 | + clearly documented in the `README.md` under prerequisites. If possible, provide guidance |
| 95 | + for adapting to other environments or a generic setup. |
| 96 | +* Resource Requests and Limits: Define realistic resource requests and limits for all |
| 97 | + workloads. For resource-intensive examples, clearly document these and, if feasible, |
| 98 | + offer scaled-down versions for resource-constrained environments. |
| 99 | +* External Links in Manifests: All URLs used in manifests must point to reliable, versioned sources. |
| 100 | +* Container Images: |
| 101 | + * Publicly Accessible Images: Images used in examples MUST be publicly accessible |
| 102 | + from well-known, reputable container registries. |
| 103 | + * Image Tagging: Images MUST be tagged with a specific version instead of using `:latest` tags. |
| 104 | + * If an example requires a custom-built image not available on public registries, the |
| 105 | + `Dockerfile` and all necessary source files (build context) MUST be included within |
| 106 | + the example's subdirectory (e.g., in an `image/` subfolder). |
| 107 | + |
| 108 | +### Documentation and Commands |
| 109 | + |
| 110 | +* Linking to Official Docs: On the first mention of a Kubernetes concept, link to its |
| 111 | + official documentation page. |
| 112 | +* Code Highlighting: Use appropriate code highlighting for shell commands and YAML |
| 113 | + manifests, consistent with GitHub's rendering (typically Rouge-supported types). |
| 114 | + * Commands to be copied by the user should use the `shell` syntax highlighting type, |
| 115 | + and do not include any kind of prompt characters (e.g., `$`, `#`). |
| 116 | + * Example output should be in a separate block to distinguish it from the commands. |
| 117 | +* Placeholders: When providing commands or configuration where users need to substitute |
| 118 | + their own values, use angle brackets: e.g., `<YOUR_NAMESPACE>`, `<YOUR_BUCKET_NAME>`. |
| 119 | +* Screenshots/Diagrams (Optional but helpful): For complex examples, screenshots of the |
| 120 | + running application or simple architecture diagrams can be very beneficial. Store these |
| 121 | + within the example's subdirectory. Asciinema recordings for terminal interactions are |
| 122 | + also welcome. |
| 123 | + |
| 124 | +## Maintenance and Lifecycle |
| 125 | + |
| 126 | +* Review and Updates: Examples are expected to be kept reasonably up-to-date with current |
| 127 | + Kubernetes versions and best practices. Contributors are encouraged to revisit their |
| 128 | + examples periodically. The `README.md` should specify the Kubernetes version(s) against |
| 129 | + which the example was last tested. |
| 130 | +* Archiving Policy: |
| 131 | + * A process will be established by SIG Apps for identifying outdated, unmaintained, or |
| 132 | + broken examples. |
| 133 | + * Such examples may be moved to an `archive/` directory or removed after a deprecation |
| 134 | + period and attempts to find new maintainers. This ensures the repository remains a |
| 135 | + reliable source of current best practices. |
| 136 | + * The `README.md` of archived examples should clearly state their archived status and |
| 137 | + potential incompatibility with current Kubernetes versions. |
| 138 | +* Community Maintenance: SIG Apps will act as the overall steward, and individual example |
| 139 | + maintainers (original authors or new volunteers) are crucial for the health of the repository. |
82 | 140 |
|
83 | 141 |
|
84 | 142 | <!-- BEGIN MUNGE: GENERATED_ANALYTICS --> |
|
0 commit comments