Skip to main content
A Timoni module describes how an application can be customised and deployed on Kubernetes, using the CUE configuration language. A module is composed of a set of Kubernetes objects and a well-defined configuration schema. Besides the Kubernetes templates and config schema, a module can specify how the lifecycle of the application should be managed, how the application should be tested. The Timoni modules are packaged as Open Container Initiative (OCI) artifacts and distributed through OCI registries. Modules are semantically versioned and can be referenced by their OCI tag or digest. A module version can be cryptographically signed when pushed to an OCI registry. To facilitate the development, testing, and publishing of modules, the Timoni CLI provides familiar commands tailored for these purposes.

​
Module Structure

The Timoni module file structure consists of a set of directories and CUE files organised into a CUE module. Example of a module’s root directory:
Timoni streamlines the creation of new modules through a blueprint-based approach. In addition to utilizing official blueprints, users can develop and employ custom blueprints for generating modules. Timoni further assists in vendoring and keeping Kubernetes APIs and CRDs schemas up-to-date.

​
Module Artifacts

A module is packaged as an OCI artifact that contains the contents of the module directory compressed as a gzipped tarball. To optimize the registry storage and to minimize the bandwidth usage, the vendored CUE definitions are stored in a separate artifact layer and cached locally. The module version is reflected in the artifact tag, and its metadata is stored in the artifact annotations. Example of a module’s OCI manifest:

​
Artifact Annotations

The module metadata is stored in the artifact manifest as annotations. Timoni sets the following annotations when pushing a module: The sh.timoni.images annotation records each image in the <repository>:<tag>@<digest> format. When images.cue contains more than one image, the references are comma-separated and sorted alphabetically, for example:
Custom annotations, such as the module’s license, description, and documentation URL, can be added with the --annotation flag of timoni mod push:

​
Module Instance

A Timoni instance represents a module instantiation on a Kubernetes cluster. The instance holds the inventory of the Kubernetes objects deployed on the cluster, the OCI reference of the module, and the user-supplied configuration values. In the cluster, the instance is stored as a Kubernetes Secret of type timoni.sh/instance. The secret’s name contains the instance name in the format timoni.<instance name>, and the secret’s namespace is the instance namespace. The role of the instance Kubernetes Secret is to keep track of the managed objects and to help Timoni’s garbage collector to delete the objects when the instance is uninstalled. Timoni offers a set of commands for inspecting the instance state:
  • timoni inspect module - displays the module URL, digest, and version
  • timoni inspect values - displays the instance config values
  • timoni inspect resources - displays the Kubernetes objects managed by the instance

​
Module Development

For an overview of CUE and the reasons why we chose it as the configuration language for Timoni, please see the CUE introduction. To get familiar with the CUE syntax, please see the CUE guide. This guide will walk you through the core features of CUE and how to use them to generate Kubernetes objects. To get started with Timoni module development, please see the following guides:

​
Module Distribution

Timoni modules are distributed as OCI artifacts, for more information please see: