Control the Apply Behavior

Timoni allows changing the default apply behaviour of Kubernetes resources with the action.timoni.sh annotations.

Annotations

CUE	Generated YAML
`timoniv1.Action.Force`	`action.timoni.sh/force: enabled`
`timoniv1.Action.OneOff`	`action.timoni.sh/one-off: enabled`
`timoniv1.Action.Keep`	`action.timoni.sh/prune: disabled`
`timoniv1.Action.DisableWaiting`	`action.timoni.sh/wait: disabled`

Force Apply

To recreate immutable resources such as Kubernetes Jobs, these resources can be annotated with action.timoni.sh/force: "enabled". Example:

package templates

import (
	batchv1 "k8s.io/api/batch/v1"
	timoniv1 "timoni.sh/core/v1alpha1"
)

#TestJob: batchv1.#Job & {
	#config:    #Config
	apiVersion: "batch/v1"
	kind:       "Job"
	metadata: timoniv1.#MetaComponent & {
		#Meta:      #config.metadata
		#Component: "test"
	}
	metadata: annotations: timoniv1.Action.Force
	spec: {...}
}

One-Off Apply

To apply resources only if they don’t exist on the cluster, these resources can be annotated with action.timoni.sh/one-off: "enabled". Example:

package templates

import (
	batchv1 "k8s.io/api/batch/v1"
	timoniv1 "timoni.sh/core/v1alpha1"
)

#InstallJob: batchv1.#Job & {
	#config:    #Config
	apiVersion: "batch/v1"
	kind:       "Job"
	metadata: timoniv1.#MetaComponent & {
		#Meta:      #config.metadata
		#Component: "install"
	}
	metadata: annotations: timoniv1.Action.OneOff
	spec: {...}
}

Disable Pruning

To prevent Timoni’s garbage collector from deleting certain resources such as Kubernetes Persistent Volume Claims, these resources can be annotated with action.timoni.sh/prune: "disabled". Example:

package templates

import (
	corev1 "k8s.io/api/core/v1"
	timoniv1 "timoni.sh/core/v1alpha1"
)

#DatabasePVC: corev1.#PersistentVolumeClaim & {
	#config:    #Config
	apiVersion: "v1"
	kind:       "PersistentVolumeClaim"
	metadata: timoniv1.#MetaComponent & {
		#Meta:      #config.metadata
		#Component: "database"
	}
	metadata: annotations: timoniv1.Action.Keep
	spec: {...}
}

Disable Waiting

To prevent Timoni’s readiness check from waiting for certain resources such as Kubernetes Persistent Volumes, these resources can be annotated with action.timoni.sh/wait: "disabled". Example:

package templates

import (
	corev1 "k8s.io/api/core/v1"
	timoniv1 "timoni.sh/core/v1alpha1"
)

#DatabasePV: corev1.#PersistentVolume & {
	#config:    #Config
	apiVersion: "v1"
	kind:       "PersistentVolume"
	metadata: timoniv1.#MetaComponent & {
		#Meta:      #config.metadata
		#Component: "database"
	}
	metadata: annotations: timoniv1.Action.DisableWaiting
	spec: {...}
}

Waiting for Custom Resources

For custom resources, a readiness evaluation can be defined with custom health checks inside timoni.cue in module root. Example:

package main

import timoniv1 "timoni.sh/core/v1alpha1"

timoni: healthChecks: {
	"cert-manager.io": timoniv1.#HealthCheckForCondition & {
		group: "cert-manager.io"
	}
	"trust.cert-manager.io": timoniv1.#HealthCheckForCondition & {
		group:         "trust.cert-manager.io"
		conditionType: "Synced"
	}
}

The above definition tells Timoni to look for the Ready=True condition in all kinds under the cert-manager.io group (ClusterIssuer, Issuer, Certificate) and to look for Synced=True for the trust-manager kinds (ClusterBundle, Bundle).

Taking Ownership of Existing Resources

When a module’s resources already exist on the cluster, Timoni takes ownership of them during the server-side apply. Objects created with kubectl apply or helm install (both Helm v3 and Helm v4 releases) become managed by Timoni: the field ownership is transferred from the kubectl and helm field managers to timoni before the objects are applied, and the fields set with these tools are replaced with the module’s desired state. When taking ownership, Timoni removes the following metadata from the objects:

the kubectl.kubernetes.io/last-applied-configuration annotation
the meta.helm.sh/release-name annotation
the meta.helm.sh/release-namespace annotation

This allows migrating an app from Helm to Timoni by installing the module instance over the existing Helm release, then deleting the Helm release secrets without uninstalling the app.

CUE Language

Module Development

Module Distribution

Control the Apply Behavior

Annotations

Force Apply

One-Off Apply

Disable Pruning

Disable Waiting

Waiting for Custom Resources

Taking Ownership of Existing Resources

​Annotations

​Force Apply

​One-Off Apply

​Disable Pruning

​Disable Waiting

​Waiting for Custom Resources

​Taking Ownership of Existing Resources

Annotations

Force Apply

One-Off Apply

Disable Pruning

Disable Waiting

Waiting for Custom Resources

Taking Ownership of Existing Resources