stefanprodan/timoni

timoni

Timoni is a package manager for Kubernetes, powered by CUE and inspired by Helm.

The Timoni project strives to improve the UX of authoring Kubernetes configs. Instead of mingling Go templates with YAML like Helm, or layering YAML on top of each-other like Kustomize, Timoni relies on cuelang's type safety, code generation and data validation features to offer a better experience of creating, packaging and delivering apps to Kubernetes.

[!IMPORTANT] Note that Timoni in under active development and is still in its infancy. The APIs and command-line interface may change in a backwards incompatible manner.

Get Started

To get started with Timoni please visit the documentation website at timoni.sh.

Concepts

• Module - App definition containing Kubernetes CUE templates and configuration schema, distributed as OCI artifacts.
• Instance - App instantiation referencing the module and workloads deployed on a Kubernetes cluster.
• Bundle - App composition bundling multiple modules and configurations into a deployable unit.
• OCI Artifact - Packaging format used for distributing modules and bundles through registries or local OCI archives and layouts.

[!TIP] If you are familiar with Helm, a Timoni module is the equivalent of a chart, a Timoni bundle is the equivalent of an umbrella chart, and a Timoni instance is the equivalent of a Helm release.

Features

App Packaging and Distribution

Timoni enables software vendors to define complex application deployments, packaged as Modules, using type-safe Kubernetes templates and rich customisation options for end-users.

The app configuration packaged in a Module is distributed as an Open Container Initiative (OCI) artifact, next to the app images, in a container registry. Timoni Modules are semantically versioned and can be cryptographically signed when pushed. Local build outputs are unsigned OCI archives or layouts for offline handoff.

Module distribution:

timoni mod push ./my-app -v 1.0.0 oci://registry.example.com/my-app
timoni mod build ./my-app -v 1.0.0 -o ./my-app-1.0.0.oci.tar

Generic artifacts transport bundle files, runtime files, and other content without module, instance, or deployment semantics:

timoni artifact push -f ./delivery -t 1.0.0 oci://registry.example.com/my-app
timoni artifact build -f ./delivery -t 1.0.0 -o ./my-app-delivery-1.0.0.oci.tar

The timoni CLI consumes module artifacts; Kubernetes nodes consume separate workload images. Local OCI outputs are for transport, not apply inputs; use a module directory for registry-free apply.

With Timoni, platform engineers can manage the lifecycle of Kubernetes controllers, including the upgrade of CRDs. Module authors can import CRD schemas from YAML files and incorporate Kubernetes custom resources in their app deployments.

App Lifecycle Management

With Timoni, users can manage the whole lifecycle of applications deployed on Kubernetes. From highly customised installation to seamless upgrades, end-to-end testing, safe rollback and uninstallation.

With Timoni, users can bundle microservices and distributed monoliths into a deployable unit. The Timoni Bundle offers a declarative way of managing the app delivery across clusters, where secrets and other environment-specific config values are dynamically loaded during installation or upgrades.

Bundle lifecycle:

timoni bundle build  -f ./bundle.cue # Render without applying (optional)
timoni bundle apply  -f ./bundle.cue # Install or upgrade
timoni bundle delete -f ./bundle.cue # Uninstall

License

Timoni is Apache 2.0 licensed and accepts contributions via GitHub pull requests. Please see the contributing guide for more information.