schemas

Timoni CUE Schemas

The Timoni's CUE schemas are included in the modules generated with timoni mod init.

Schemas

Kubernetes Metadata

• #Annotations - Schema for validating Kubernetes annotations.
• Action - Values of action.timoni.sh annotations for controlling Timoni's apply behaviour.
• #Labels - Schema for validating Kubernetes labels.
• #StdLabel - Values of Kubernetes app.kubernetes.io labels.
• #Metadata - Schema for generating Kubernetes metadata (name, namespace, annotations and labels), with automatic generation of app.kubernetes.io/managed-by, app.kubernetes.io/name and app.kubernetes.io/version labels.
• #MetaComponent - Superset of #Metadata schema for Kubernetes namespaced objects, that appends the component name to metadata.name, and with automatic generation of app.kubernetes.io/component label.
• #MetaClusterComponent - Superset of #Metadata schema for Kubernetes global objects, that appends the component name to metadata.name, and with automatic generation of app.kubernetes.io/component label.
• #Selector - Schema for generating Kubernetes label selectors with automatic generation of app.kubernetes.io/name label.
• #ObjectReference - Schema for generating Kubernetes object references based on apiVersion, kind, name and namespace.

Immutable ConfigMaps and Secrets

• #ImmutableConfig - Schema for generating immutable Kubernetes ConfigMaps and Secrets. The metadata.name of the generated object is suffixed with the hash of the input data. The #Meta input accepts both #Metadata and #MetaComponent values.

Container Image

• #Image - Schema for generating a container image and pull policy from repository, tag and digest inputs.
• #ImagePullSecret - Schema for generating a Kubernetes Secret of type kubernetes.io/dockerconfigjson from repository, username and password inputs.

Container Resource Requirements

• #CPUQuantity - Schema for validating Kubernetes CPU resource requirements.
• #MemoryQuantity - Schema for validating Kubernetes memory resource requirements.
• #ResourceRequirements - Schema for generating container requests and limits from cpu and memory inputs.

Security Contexts

• #SecurityContextPreset - Values of the securityContextPreset module knob: hardened (default) pins the numeric UID/GID defaults, platform omits them so that an admission controller (e.g. OpenShift) can assign them.
• #ContainerSecurityContext - Schema for the restricted container security context: denies privilege escalation, makes the root filesystem read-only and drops all capabilities.
• #PodSecurityContext - Schema for generating the pod-level security context from #Preset and #User (optionally #Group and #FSGroup) inputs. Defaults to runAsNonRoot with the RuntimeDefault seccomp profile, and pins the numeric identity fields only under the hardened preset.

Pod Scheduling

• #AffinityPreset - Values of the affinity.podAntiAffinity module knob: soft (default) prefers spreading the workload replicas across topology domains, hard requires it, none disables it.
• #AffinityValues - Schema for the module values of a workload's affinity setting: an #AffinityPreset or raw rules for podAntiAffinity, raw rules for nodeAffinity and podAffinity.
• #Affinity - Schema for generating the pod affinity rules from the #Values, #MatchLabels, #TopologyKey and #Weight inputs; the #Enabled field tells whether any rules are set, letting modules omit the affinity field from the pod spec.

Prometheus Monitoring

• #PromDuration - Schema for validating durations in Prometheus format, e.g. 30s or 1m30s.
• #Monitor - Schema for the module values shared by the Prometheus Operator ServiceMonitor and PodMonitor resources: the enable knob, monitor metadata, per-scrape limits and target labels.
• #MonitorEndpoint - Schema for the module values of one monitor scrape endpoint; duration fields left empty defer to the Prometheus defaults.
• #MonitorValues - The canonical values block for a module's serviceMonitor or podMonitor setting scraping a single endpoint, unifying #Monitor and #MonitorEndpoint.
• #MonitorSpec - Schema for generating the ServiceMonitor/PodMonitor spec fields common to both kinds from the #Values input, omitting the unset limits and target labels.
• #MonitorEndpointSpec - Schema for generating a ServiceMonitor endpoint or a PodMonitor podMetricsEndpoint from the #Values input, omitting the unset scrape settings.

Semantic Versioning

• #SemVer - Schema for validating semantic versions and enforcing a minimum major and/or minor version.

Custom Health Checks

• #HealthCheck - Schema for defining a custom readiness evaluation in CUE for Kubernetes custom resources that are not kstatus-compliant.
• #HealthCheckForCondition - Schema for generating a health check for custom resources that signal readiness through status conditions.
• #HealthCheckLibrary - Ready-made health checks for popular custom resources, grouped by API family under families, with all unifying every family. Currently, covers the Kubernetes Gateway API kinds from both the standard and the experimental channels under families.gatewayAPI, and the Cluster API core kinds under families.clusterAPI.

Timoni API

These schemas describe Timoni's own APIs and are the single source of truth used by the timoni CLI to validate bundles, runtimes and instances. They are exposed here so that they can be imported and reused in CUE projects.

• #Bundle - Schema for validating a Timoni Bundle, i.e. the set of instances applied to a cluster.
• #Runtime - Schema for validating a Timoni Runtime, i.e. the target clusters and the values fetched from their resources.
• #RuntimeValue - Schema for a single Runtime value query.
• #Timoni - Schema for a module's instance, holding the instance configuration and the Kubernetes resources to apply.

Vendoring

To update a module's schemas to the latest version, run the following command from within the module root:

timoni artifact pull oci://ghcr.io/stefanprodan/timoni/schemas:latest \
  --output cue.mod/pkg

To update the schemas and verify the signature with Cosign v2:

timoni artifact pull oci://ghcr.io/stefanprodan/timoni/schemas:latest \
  --verify=cosign \
  --certificate-identity-regexp="^https://github.com/stefanprodan/timoni.*$" \
  --certificate-oidc-issuer=https://token.actions.githubusercontent.com \
  --output cue.mod/pkg