Revamp the example repo for modern use cases
This commit is contained in:
Janet Kuo
parent
56e0318b61
commit
503c00af20
57
README.md
57
README.md
|
|
@ -1,30 +1,49 @@
|
|||
# Kubernetes Examples
|
||||
|
||||
This directory contains a number of examples of how to run real applications
|
||||
with Kubernetes.
|
||||
Welcome to the official Kubernetes Examples repository! This curated collection,
|
||||
stewarded by SIG Apps, provides high-quality, educational examples for running a
|
||||
diverse range of applications and workloads on Kubernetes.
|
||||
|
||||
Refer to the [Kubernetes documentation] for how to execute the tutorials.
|
||||
Our goal is to offer a central hub where you can:
|
||||
* **Discover** practical implementations for various use cases.
|
||||
* **Learn** common patterns and best practices for deploying applications on Kubernetes.
|
||||
* **Explore** configurations for general-purpose applications as well as specialized
|
||||
ones like AI/ML workloads and platforms.
|
||||
|
||||
### Maintained Examples
|
||||
## Browse 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.
|
||||
We encourage you to explore the subdirectories to find examples relevant to your needs.
|
||||
Examples are organized into categories, such as:
|
||||
|
||||
|Name | Description | Notable Features Used | Complexity Level|
|
||||
------------- | ------------- | ------------ | ------------ |
|
||||
|[Guestbook](guestbook/) | PHP app with Redis | Deployment, Service | Beginner |
|
||||
|[Guestbook-Go](guestbook-go/) | Go app with Redis | Deployment, Service | Beginner |
|
||||
|[WordPress](mysql-wordpress-pd/) | WordPress with MySQL | Deployment, Persistent Volume with Claim | Beginner|
|
||||
|[Cassandra](cassandra/) | Cloud Native Cassandra | Daemon Set, Stateful Set, Replication Controller | Intermediate
|
||||
* [ai](ai/): Demonstrations of AI/ML model training, serving, end-to-end platform
|
||||
reference manifests, and MLOps toolchains.
|
||||
* ... (and more as the collection grows!)
|
||||
|
||||
> Note: Please add examples that are maintained to the list above.
|
||||
Each example includes its own detailed `README.md` file covering:
|
||||
* Purpose and learning objectives
|
||||
* Prerequisites (including Kubernetes version and hardware if applicable)
|
||||
* Step-by-step deployment instructions
|
||||
* Verification and cleanup commands
|
||||
* Key Kubernetes concepts used
|
||||
|
||||
See [Example Guidelines](guidelines.md) for a description of what goes
|
||||
in this directory, and what examples should contain.
|
||||
## Contributing to Kubernetes Examples
|
||||
|
||||
[Kubernetes documentation]: https://kubernetes.io/docs/tutorials/
|
||||
We welcome contributions from the community! If you have an example that showcases
|
||||
how to run applications or workloads on Kubernetes effectively and educates users,
|
||||
please consider sharing it.
|
||||
|
||||
### Contributing
|
||||
Before contributing, please thoroughly review our:
|
||||
1. [Example Guidelines](guidelines.md): These outline the standards, structure,
|
||||
and best practices all examples must follow.
|
||||
2. [CONTRIBUTING.md](CONTRIBUTING.md): This provides instructions on the contribution
|
||||
process, including how to propose, submit, and review examples.
|
||||
|
||||
Please see [CONTRIBUTING.md](CONTRIBUTING.md) for instructions on how to contribute.
|
||||
Your contributions help make Kubernetes more accessible and understandable for everyone.
|
||||
|
||||
## Our Philosophy
|
||||
|
||||
We aim for these examples to be:
|
||||
* **Educational:** Clearly explaining how and why things work.
|
||||
* **Practical:** Demonstrating real-world (though possibly simplified) applications and platforms.
|
||||
* **Current:** Reflecting modern Kubernetes features and best practices.
|
||||
* **Maintained:** Kept up-to-date by the community and SIG Apps.
|
||||
|
|
@ -0,0 +1,33 @@
|
|||
# AI/ML Examples on Kubernetes
|
||||
|
||||
Welcome to the AI/ML examples section! Our goal is to provide a collection of
|
||||
community-curated, open-source reference manifests for deploying and managing
|
||||
AI/ML workloads, MLOps toolchains, and end-to-end platforms on Kubernetes.
|
||||
|
||||
This area is under active development as part of a broader initiative to enhance
|
||||
the `kubernetes/examples` repository. We aim to simplify the developer and operator
|
||||
experience for AI applications on Kubernetes, promoting best practices and interoperability.
|
||||
|
||||
## Vision for AI/ML Examples
|
||||
|
||||
We envision this section housing examples such as:
|
||||
* Setups for distributed training frameworks.
|
||||
* Configurations for model serving solutions.
|
||||
* Blueprints for data versioning and experiment tracking integrations.
|
||||
* End-to-end MLOps platform examples.
|
||||
* "AI Kits" designed to help AI/ML experts quickly get started on Kubernetes.
|
||||
|
||||
## Call for Contributions
|
||||
|
||||
The success of this initiative depends on community contributions! If you have expertise
|
||||
in running AI/ML workloads on Kubernetes or ideas for valuable examples, we strongly
|
||||
encourage you to contribute.
|
||||
|
||||
We are particularly interested in examples that are:
|
||||
* Educational and provide an easy start for AI/ML practitioners new to Kubernetes.
|
||||
* Modular and showcase best practices.
|
||||
* Cover a diverse range of tools and MLOps stages.
|
||||
|
||||
## Current Status
|
||||
|
||||
_This section is currently being populated. Check back soon for our first set of AI/ML examples!_
|
||||
198
guidelines.md
198
guidelines.md
|
|
@ -1,84 +1,142 @@
|
|||
# Example Guidelines
|
||||
# Kubernetes Example Guidelines
|
||||
|
||||
## An Example Is
|
||||
Welcome to the `kubernetes/examples` repository! This repository serves as a
|
||||
community-driven collection of high-quality, educational examples demonstrating
|
||||
how to run a diverse range of applications, frameworks, and workloads on Kubernetes.
|
||||
Our goal is to provide a central place for users to discover practical examples,
|
||||
learn common patterns, and understand best practices for deploying applications,
|
||||
including general-purpose workloads and specialized AI/ML workloads and platforms.
|
||||
|
||||
An example demonstrates running an application/framework/workload on
|
||||
Kubernetes in a meaningful way. It is educational and informative.
|
||||
These guidelines are intended for contributors to ensure that all examples are
|
||||
consistent, maintainable, easy to understand, and valuable to the Kubernetes community.
|
||||
By adhering to these guidelines, we can build a rich and up-to-date resource.
|
||||
|
||||
Examples are not:
|
||||
## An Example Is...
|
||||
|
||||
* Full app deployments, ready to use, with no explanation. These
|
||||
belong to [Helm charts](https://github.com/kubernetes/charts).
|
||||
* Simple toys to show how to use a Kubernetes feature. These belong in
|
||||
the [user guide](https://kubernetes.io/docs/home/).
|
||||
* 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 demonstrates running an application, framework, or complex workload
|
||||
(such as AI/ML model serving, training pipelines, associated toolchains) on Kubernetes.
|
||||
It must be:
|
||||
|
||||
## An Example Includes
|
||||
* Meaningful: Solves or illustrates a recognizable, real-world (though potentially simplified) use case.
|
||||
* Educational: Helps users learn how to deploy and manage the specific type of application
|
||||
or pattern on Kubernetes. It should explain the "why" behind the "how."
|
||||
* Illustrative of Best Practices: Showcases current Kubernetes best practices for configuration,
|
||||
security, and application architecture where applicable.
|
||||
* Focused: While it can involve multiple components, it should illustrate a specific concept
|
||||
or setup without becoming overly broad. For very complex systems, consider breaking them into
|
||||
smaller, related examples or leveraging modular design, especially for platform blueprints.
|
||||
|
||||
### Up front
|
||||
## Examples Are NOT...
|
||||
|
||||
* 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](https://github.com/kubernetes/community/blob/master/contributors/devel/running-locally.md) (e.g., single-node docker).
|
||||
* [Setup kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/).
|
||||
* 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 new features, and being
|
||||
compatible across environments.
|
||||
Examples are intended for educational purposes and should not be:
|
||||
|
||||
### Throughout
|
||||
* Minimalistic Feature Snippets: Examples should be more comprehensive than simple snippets
|
||||
designed to illustrate a single Kubernetes API field. Such content is better suited for
|
||||
the official [Kubernetes documentation](https://kubernetes.io/docs/home/).
|
||||
* Pure Kubernetes Feature Demonstrations: Examples should focus on the application running
|
||||
on Kubernetes, not solely on demonstrating a Kubernetes feature in isolation (e.g., showing
|
||||
high availability is a feature demo, not an application example unless it's core to
|
||||
understanding how that specific application achieves HA on Kubernetes).
|
||||
|
||||
* Should point to documentation on first mention:
|
||||
[kubectl](https://kubernetes.io/docs/user-guide/kubectl-overview/),
|
||||
[pods](https://kubernetes.io/docs/concepts/workloads/pods/pod/),
|
||||
[services](https://kubernetes.io/docs/concepts/services-networking/service/),
|
||||
[deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/),
|
||||
[replication controllers](https://kubernetes.io/docs/concepts/workloads/controllers/replicationcontroller/),
|
||||
[jobs](https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/),
|
||||
[labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/),
|
||||
[persistent volumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/),
|
||||
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](https://kubernetes.io/docs/concepts/configuration/overview/).
|
||||
* Shouldn't duplicate the [user guide](https://kubernetes.io/docs/home/).
|
||||
* 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 using 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.
|
||||
## An Example Includes...
|
||||
|
||||
### At the end
|
||||
Each example must be well-structured and documented to ensure clarity and usability.
|
||||
|
||||
* Should have a section suggesting what to look at next, both in terms
|
||||
of "additional resources" and "what example to look at next".
|
||||
### Structure and README
|
||||
|
||||
* Directory: Each example MUST reside in its own clearly named subdirectory within a
|
||||
relevant category (e.g., `/ai/`, `/databases/`).
|
||||
* README.md: Every example MUST have a `README.md` file. This file is crucial for
|
||||
understandability and usability. It SHOULD follow a consistent structure.
|
||||
_(TBD: establish a `EXAMPLE_README_TEMPLATE.md` to guide contributors)._ Key sections include:
|
||||
* Title: Clear and descriptive title of the example.
|
||||
* Purpose / What You'll Learn: Briefly describe what the example demonstrates and what
|
||||
the user will learn by using it.
|
||||
* Table of Contents (ToC): For longer READMEs, a ToC is highly recommended.
|
||||
* Prerequisites, such as:
|
||||
* Required Kubernetes version.
|
||||
* Any necessary tools (e.g., `kubectl`, `kustomize`, `helm`, `git`).
|
||||
* Specific hardware requirements. This is especially important for AI/ML examples.
|
||||
* Quick Start / TL;DR: A concise set of commands to deploy the example with minimal effort,
|
||||
preferably without needing to clone the repository.
|
||||
* Detailed Steps & Explanation:
|
||||
* Walk through the deployment process.
|
||||
* Explain the key Kubernetes manifests and their roles within the example.
|
||||
* Describe important configuration choices.
|
||||
* Verification / Seeing it Work: Commands to verify the application is running correctly,
|
||||
along with expected output (console logs, screenshots, or how to access an endpoint).
|
||||
For AI/ML examples, this might include how to check training progress or send a test inference request.
|
||||
* Configuration Customization (Optional but Recommended): Guidance on how users can
|
||||
customize common parameters.
|
||||
* Cleanup: Commands to remove all resources created by the example.
|
||||
* Troubleshooting (Optional): Common issues and how to resolve them.
|
||||
* Further Reading / Next Steps: Links to relevant official documentation, related
|
||||
examples, or more advanced topics.
|
||||
* Maintainer(s) (Optional): GitHub username(s) of primary maintainers.
|
||||
* Last Validated Kubernetes Version (Recommended): The Kubernetes version against
|
||||
which the example was last successfully tested.
|
||||
|
||||
### Manifests and Configuration
|
||||
|
||||
* Clarity and Best Practices: Manifests should be well-commented where non-obvious.
|
||||
They must follow [Kubernetes configuration best practices](https://kubernetes.io/docs/concepts/configuration/overview/)
|
||||
and general [security best practices](https://kubernetes.io/docs/concepts/security/overview/).
|
||||
* Kubernetes API Usage:
|
||||
* Use stable APIs whenever possible. If beta or alpha features are used, they must
|
||||
be explicitly mentioned along with any necessary feature gates.
|
||||
* Avoid deprecated APIs or features. Reference API documentation for core or custom workload APIs.
|
||||
* Vendor neutral: Do not endorse one particular ecosystem tool or cloud-provider.
|
||||
* Individual manifests will inherently use specific tools to fulfill their purpose.
|
||||
However, examples will be open to manifests for a diverse set of tools, governed
|
||||
by community interest and contribution.
|
||||
* If an example *must* use cloud-provider-specific features (e.g., specific AI accelerators,
|
||||
managed database services critical to an AI workload/platform), this dependency MUST be
|
||||
clearly documented in the `README.md` under prerequisites. If possible, provide guidance
|
||||
for adapting to other environments or a generic setup.
|
||||
* Resource Requests and Limits: Define realistic resource requests and limits for all
|
||||
workloads. For resource-intensive examples, clearly document these and, if feasible,
|
||||
offer scaled-down versions for resource-constrained environments.
|
||||
* External Links in Manifests: All URLs used in manifests must point to reliable, versioned sources.
|
||||
* Container Images:
|
||||
* Publicly Accessible Images: Images used in examples MUST be publicly accessible
|
||||
from well-known, reputable container registries.
|
||||
* Image Tagging: Images MUST be tagged with a specific version instead of using `:latest` tags.
|
||||
* If an example requires a custom-built image not available on public registries, the
|
||||
`Dockerfile` and all necessary source files (build context) MUST be included within
|
||||
the example's subdirectory (e.g., in an `image/` subfolder).
|
||||
|
||||
### Documentation and Commands
|
||||
|
||||
* Linking to Official Docs: On the first mention of a Kubernetes concept, link to its
|
||||
official documentation page.
|
||||
* Code Highlighting: Use appropriate code highlighting for shell commands and YAML
|
||||
manifests, consistent with GitHub's rendering (typically Rouge-supported types).
|
||||
* Commands to be copied by the user should use the `shell` syntax highlighting type,
|
||||
and do not include any kind of prompt characters (e.g., `$`, `#`).
|
||||
* Example output should be in a separate block to distinguish it from the commands.
|
||||
* Placeholders: When providing commands or configuration where users need to substitute
|
||||
their own values, use angle brackets: e.g., `<YOUR_NAMESPACE>`, `<YOUR_BUCKET_NAME>`.
|
||||
* Screenshots/Diagrams (Optional but helpful): For complex examples, screenshots of the
|
||||
running application or simple architecture diagrams can be very beneficial. Store these
|
||||
within the example's subdirectory. Asciinema recordings for terminal interactions are
|
||||
also welcome.
|
||||
|
||||
## Maintenance and Lifecycle
|
||||
|
||||
* Review and Updates: Examples are expected to be kept reasonably up-to-date with current
|
||||
Kubernetes versions and best practices. Contributors are encouraged to revisit their
|
||||
examples periodically. The `README.md` should specify the Kubernetes version(s) against
|
||||
which the example was last tested.
|
||||
* Archiving Policy:
|
||||
* A process will be established by SIG Apps for identifying outdated, unmaintained, or
|
||||
broken examples.
|
||||
* Such examples may be moved to an `archive/` directory or removed after a deprecation
|
||||
period and attempts to find new maintainers. This ensures the repository remains a
|
||||
reliable source of current best practices.
|
||||
* The `README.md` of archived examples should clearly state their archived status and
|
||||
potential incompatibility with current Kubernetes versions.
|
||||
* Community Maintenance: SIG Apps will act as the overall steward, and individual example
|
||||
maintainers (original authors or new volunteers) are crucial for the health of the repository.
|
||||
|
||||
|
||||
<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
|
||||
|
|
|
|||
Loading…
Reference in New Issue