Google Summer of Code 2026 Final Report

[Jaisheesh-2006]

Building a Real-World Kubernetes E-Commerce Application Package with kpt

Organization: CNCF

Project: Build an e-commerce example kpt package

Contributor: @Jaisheesh-2006

Mentors: @liamfallon , @ciaranjohnston , @CsatariGergely

---

Project Overview

Motivation

• Lack of accessible examples: Current kpt examples are rooted in highly specialized domains (like telecom), creating a steep learning curve.
• Incomplete documentation: Existing standard examples are piecemeal and fail to showcase kpt's full end-to-end capabilities.
• Relatable use case: This project bridges the gap by providing a comprehensive, real-world example in a widely understood domain: a microservices e-commerce webstore.

Project Goals

• Package creation: Package the OpenTelemetry Demo (Astronomy Shop) microservices application into a functional, composable kpt package.
• Demonstrate customization: Showcase declarative kpt toolchain features including domain rebranding, regional localization, deployment scaling, and chaos engineering.
• Ensure safe updates: Maintain upstream purity to demonstrate safe, structural 3-way merge update paths.
• Community Enablement: Deliver a robust, comprehensive reference package and comprehensive technical documentation to support adoption within the CNCF ecosystem.

---

What Was Implemented

Package Architecture

• Composable hierarchy: Structured the root package (app/) to orchestrate independent upstream subpackages (shop/ and observability/).
• Sibling customization layers: Implemented customizations via adjacent layers (branding/, regional/, profiles/, chaos/) rather than inline edits.
• Declarative rendering: Utilized the root Kptfile to define a pipeline where mutators and validators act on fully rendered resources.

Features Implemented

Domain Rebranding

• Identity switching: Enabled changing the store's core identity (e.g., from Astronomy to Florist and vice versa) via a single ConfigMap field.
• Dynamic rewrites: Replaced product images, IDs, and database initialization scripts across multiple services seamlessly without touching upstream manifests.

Regional Localization

• Data derivation: Derived locale, currency, and translated catalog data from a single region input.
• Cascading variables: Showcased Starlark's ability to cascade environment variables across frontend, ad, llm, and email services simultaneously.

Regional Sales Tax / VAT Customization

• Automated computation: Created a Starlark mutator that computes the appropriate tax rate and label (e.g., GST, VAT) based on the chosen region.
• Deterministic rendering: Ensured financial configurations are rendered consistently across the application without relying on external API calls.

Deployment Profiles

• Workload scaling: Scaled the entire application workload based on simple profiles ("small", "medium", "large", "default").
• Intelligent adjustments: Used a Starlark script to dynamically adjust replica counts, memory limits, CPU requests, and observability toggles based on the selected tier.

Chaos Engineering

• Declarative Fault Injection: Allowed users to simulate complex failure scenarios (e.g., payment-outage, high-load, memory-leak) by editing a single ConfigMap field.
• Line-by-line String Mutation: Utilized Starlark string manipulation to parse and mutate the embedded flagd JSON payload line-by-line, updating specific keys while preserving overall structure, as the Starlark environment lacked a native JSON parser.
• Upstream Resilience: Relied entirely on existing upstream feature toggles, keeping the microservices completely unmodified for future updates.

Package Update Demonstration

• Upstream isolation: Kept subpackages untouched by local customizations to guarantee safe upstream release pulls.
• Structural merging: Demonstrated kpt pkg update capabilities by preserving local edits while integrating upstream improvements via 3-way merges.

Documentation

• Detailed README: Authored a comprehensive README.md mapping the architectural hierarchy and the kpt rendering flow.
• Tutorials: Provided instructions for deploying customizations and a walkthrough demonstrating the 3-way structural merge of kpt pkg update.

---

Testing & Validation

• KRM Validators: Wrote Starlark validators for every layer to ensure inputs strictly conform to allowed enum values before rendering.
• Pipeline Debugging: Used kpt fn eval to iteratively step through and debug individual KRM functions during development.
• Merge Validation: Tested structural 3-way merges to verify that consumer modifications were preserved alongside simulated upstream changes.

---

Impact

• Production-Scale Example: Introduced a production-scale example package combining two open source projects (OpenTelemetry and kpt).
• Advanced Composition: Demonstrated advanced kpt package composition using independent subpackages and customization layers.
• Customization Workflows: Added documentation for multiple declarative customization workflows.
• Safe Updates: Showcased safe package updates using kpt's structural 3-way merge capabilities.

---

Timeline

• Phase 0 (May 28 - Jun 5): Finalized the architectural design and customization strategy for the project.
• Phase 1 (Jun 6 - Jun 10): Created the root package structure and independent shop/ and observability/ subpackages; verified self-contained RBAC and independent deployments.
• Phase 2 (Jun 11 - Jun 15): Set up the initial kpt fn render pipeline and local cluster demo deployments.
• Phase 3 (Jun 16 - Jun 25): Implemented the domain rebranding pipeline (Astronomy Shop to Florist) and prepared for the midterm evaluation.
• Phase 4 (Jun 27 - Jul 9): Implemented the regional localization pipeline (language and currency derivation), followed by the sales tax and VAT customization pipeline.
• Phase 5 (Jul 10 - Jul 14): Developed the deployment configuration (scaling profiles) pipeline.
• Phase 6 (Jul 15 - Jul 19): Engineered the chaos fault injection layer, finalized comprehensive documentation, and completed final cleanup.
• Phase 7 (Jul 20 - Jul 27): Cleanup, enhance documentation

---

Current Project Status

• Completed work: The package has been merged into kpt-samples and provides a fully functional reference implementation supporting independent rendering, cross-cutting mutations, declarative chaos engineering, and structural package updates.

---

Future Work

• Community Adoption: Encourage developers and organizations to adopt this example as a primary learning resource for advanced kpt usage.
• Maintenance: Fix user-reported bugs and keep the package updated in tandem with upstream OpenTelemetry Demo releases.
• Enhancement: Abstract common, complex Starlark logic into reusable KRM catalog functions for the wider kpt ecosystem.

---

Acknowledgements

• Mentorship: I am deeply grateful to my mentors for their constant guidance, code reviews, and unwavering support.
• CNCF and Google: A huge thank you to the CNCF and Google Summer of Code for providing this incredible opportunity to contribute to the open-source community.
• Kpt Community: My appreciation goes out to the kpt maintainers and community members for their excellent tools, timely responses, and helpful discussions.

---

Resources

• GSOC Project Page: Google Summer of Code
• Merged Pull Request: kptdev/kpt-samples#26
• Repository: kptdev/kpt-samples
• kpt Documentation: kpt.dev