diff --git a/README.md b/README.md index ac5a1eeb..19c20b07 100644 --- a/README.md +++ b/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. \ No newline at end of file diff --git a/ai/README.md b/ai/README.md new file mode 100644 index 00000000..b4a1f6e2 --- /dev/null +++ b/ai/README.md @@ -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!_ diff --git a/guidelines.md b/guidelines.md index 7ba3cb3e..ff66e89d 100644 --- a/guidelines.md +++ b/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: `` 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., ``, ``. +* 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.