Timoni

Timoni is a package manager for Kubernetes powered by CUE. It is designed to improve the user experience of authoring Kubernetes configurations by using CUE's type safety, code generation, and data validation instead of Go templates (like Helm) or YAML layering (like Kustomize).

Note: Timoni is under active development. APIs and the CLI may undergo backwards incompatible changes.

A Timoni module is a package that describes how an application can be customized and deployed on Kubernetes using the CUE configuration language.

Key characteristics include:

• Composition: A module consists of Kubernetes objects and a well-defined configuration schema.
• Lifecycle & Testing: Modules can specify how an application's lifecycle is managed and how it should be tested.
• Distribution: Modules are packaged as Open Container Initiative (OCI) artifacts and distributed via OCI registries.
• Versioning: Modules use semantic versioning and can be referenced by OCI tags or digests. They can also be cryptographically signed for security.

A Timoni Runtime allows you to define configuration values that are not known ahead of time, such as values stored in a Kubernetes cluster (Secrets, ConfigMaps) or environment variables. This enables declarative Bundles to consume dynamic, runtime-available data.

Timoni provides a Runtime API to fetch values from the Kubernetes API and map them to fields inside a Bundle using the @timoni() attribute.

Timoni modules and bundles are distributed as OCI (Open Container Initiative) artifacts. Timoni produces artifacts with specific media types:

• Image: application/vnd.oci.image.manifest.v1+json
• Config: application/vnd.timoni.config.v1+json
• Layer: application/vnd.timoni.content.v1.tar+gzip

To ensure reproducible builds, Timoni includes Git metadata (last modified date, source URL, and source revision) as annotations.

A Timoni module is organized as a CUE module containing specific directories and files. A typical structure looks like this:

├── cue.mod
│   ├── gen # Kubernetes APIs and CRDs schemas
│   ├── pkg # Timoni APIs schemas
│   └── module.cue # Module metadata
├── templates
│   ├── config.cue # Config schema and default values
│   ├── deployment.cue # Kubernetes Deployment template
│   └── service.cue # Kubernetes Service template
├── timoni.cue # Timoni entry point
├── timoni.ignore # Timoni ignore rules
├── values.cue # Timoni values placeholder 
├── LICENSE # Module license
└── README.md # Module documentation

Interpolate expressions into strings, bytes, or field names using the \(expr) syntax. You can also use the + operator to concatenate strings.

Examples:

• "\(kubeLabel)/name" for dynamic field names.
• "http-\(metadata.name)" for dynamic values.
• (metadata.name) + "-http" for concatenation.

nginxSvc: #Service & {
    let kubeLabel = "app.kubernetes.io"
    metadata: {
        name: "nginx"
    }
    spec: {
        selector: {
            "\(kubeLabel)/name": metadata.name
        }
        ports: [{
            name: "http-\(metadata.name)"
        }]
    }
}

Define local values using the let keyword. Aliases are not members of the struct and are omitted from the final output. They are useful for intermediate calculations or reusing values within the same scope.

nginxSvc: #Service & {
    let appName = "nginx"
    metadata: {
        name:      appName
        namespace: appName
    }
    spec: {
        selector: "app.kubernetes.io/name": appName
    }
}

CUE allows embedding a definition into another using the & operator, similar to OOP composition. This is primarily used to create specialized schemas that further constrain the fields of a base schema.

When you embed a schema (e.g., #Service) into a new one (e.g., #HeadlessService), the new schema inherits all fields and constraints from the base. If the specialized schema sets concrete values for certain fields, those fields become fixed and cannot be overridden by the instance using the specialized schema.

#HeadlessService: #Service & {
    spec!: {
        type:      "ClusterIP"
        clusterIP: "None"
    }
}