Bundle Runtime

While Timoni Bundles offer a way to specify the config values in declarative manner, not all the configuration values of an application are known ahead of time. Some values may be available at runtime, in the Kubernetes clusters where the Bundle is applied. For example, the API token for some backend service that your app consumes is stored in a Kubernetes Secret in-cluster. When installing the application with Timoni, you may want to fetch the token from the Kubernetes Secret and use it as a config value. Timoni Runtime API offers a way to define values which are fetched from the Kubernetes API and mapped to fields inside a Bundle.

Example

The following is an example of a Runtime definition that extracts values from the cluster.

runtime: {
	apiVersion: "v1alpha1"
	name:       "production"
	clusters: {
		// using the cluster set in kubeconfig current context
	}
	values: [
		{
			query: "k8s:v1:ConfigMap:infra:aws-info"
			for: {
				"ACCOUNT_ID": "obj.data.account_id"
				"REGION":     "obj.data.region"
			}
		},
		{
			query: "k8s:v1:Secret:infra:redis-auth"
			for: {
				"REDIS_PASS": "obj.data.password"
				"REDIS_CA":   "obj.data.\"ca.crt\""
			}
		},
	]
}

The values from the Runtime, can be mapped to fields in a Bundle using @timoni() attributes.

bundle: {
	_id:   string @timoni(runtime:string:ACCOUNT_ID)
	_reg:  string @timoni(runtime:string:REGION)
	_pass: string @timoni(runtime:string:REDIS_PASS)

	apiVersion: "v1alpha1"
	name:       "podinfo"
	instances: {
		podinfo: {
			module: url: "oci://\(_id).dkr.ecr.\(_reg).amazonaws.com/modules/podinfo"
			namespace: "podinfo"
			values: caching: {
				enabled:  true
				redisURL: "tcp://:\(_pass)@redis.infra:6379"
			}
		}
	}
}

Assuming the ConfigMaps and Secrets are in the cluster, and the Runtime file is runtime.cue and the Bundle file is bundle.cue. Build the runtime to see which values are present on the cluster:

command
output

timoni runtime build -f runtime.cue

ACCOUNT_ID: 1234567890
REGION: us-west-2
REDIS_PASS: password
REDIS_CA:
  -----BEGIN CERTIFICATE-----
  MIIC/jCCAeagAwIBAgIBADANBgkqhkiG9w0BAQsFADAVMRMwEQYDVQQDEwprdWJl
  cm5ldGVzMB4XDTIzMDgxMDE1MTA1MFoXDTMzMDgwNzE1MTA1MFowFTETMBEGA1UE
  AxMKa3ViZXJuZXRlczCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAJgA
  mOniTayGyXG51eYeb1oJGCszRlZv4ci2kzLC0H4YCph6TXDEawrsvyuzGe7fwp4t
  Jq2fQiJgKbibOjHcOwhYqp1lJDu37p6WsLvx/RxbkHoVX8X2n7n1BVS5MbQ81on9
  BdXkff71g8n3HmJo8ZN1abEW434tHFwjjGMDzFoqxTnNM+qMKegxAtTPVbjV4X+5
  4/95L7T0XNd97XnunSUAEJRroMTRuaBAcYz81N0ix3Mc0T+G16aV127R0ZFkPlS8
  bzjA1NGgbiveX7i7n9mNG4Gy7iElP0iidtdrA6loxWYLW1jmEH5/pWQnki7s3OrK
  /94xrQ2MaDpXUzcoc0cCAwEAAaNZMFcwDgYDVR0PAQH/BAQDAgKkMA8GA1UdEwEB
  /wQFMAMBAf8wHQYDVR0OBBYEFJ7f9QzKWA/BQJSRinKne4FZNzScMBUGA1UdEQQO
  MAyCCmt1YmVybmV0ZXMwDQYJKoZIhvcNAQELBQADggEBAAhGgYFB90Rkexgh56q8
  n8uC4XQF6OTJJf/4A9VXNbiZhG+PUYkMUyqeOSOq+IztJVOffuG9ZutYQtJYCX7g
  TUQmZxeKAw1MAMEWAELmNVdbG6Y6YZ14v8SI+TADqeqcIkmDEkACygfeHKdEFOfV
  LoRAc3Zn32byP5M6EVjTXWvb+UbVt7umoBOCbMo3BEF71TEDI5Oww6y3YxDM9/Y7
  MCTu+0XHZNGDgprmci6fzLv8PV0C6eiuUrrBM237WOfk4BYL6pmCDcCWo6aP2cH7
  Y5zcVBxKUs/h5bZfLJFuwXJC5zWudNLOAtNtFhctMwDoNaKYq720g/GmEroq4wgA
  tBI=
  -----END CERTIFICATE-----

Apply the Bundle using the values from the Runtime:

command
output

timoni bundle apply -f bundle.cue --runtime runtime.cue

applying instance podinfo
pulling oci://1234567890.dkr.ecr.us-west-2.amazonaws.com/modules/podinfo
using module timoni.sh/podinfo version 6.14.1
installing podinfo in namespace podinfo
ServiceAccount/podinfo/podinfo created
Service/podinfo/podinfo created
Deployment/podinfo/podinfo created
waiting for 3 resource(s) to become ready...
resources are ready

Writing a Runtime spec

A Runtime file must contain a definition that matches the following schema:

#Runtime: {
	apiVersion: string
	name:       string

	clusters?: [string]: {
		group!:       string
		kubeContext!: string
	}

	values?: [...#RuntimeValue]
}

#RuntimeValue: {
	query: string
	for: {[string]: string}
	optional: *false | bool
}

API version

The apiVersion is a required field that specifies the version of the Runtime schema. Currently, the only supported value is v1alpha1.

Name

The name is a required field used to identify the Runtime. The name must be a lowercase identifier (alphanumeric characters, - and _, starting and ending with an alphanumeric character) of at most 63 characters.

Clusters

The clusters field is for defining the target clusters and environments (group of clusters) where a Bundle is applied. A cluster entry must specify the group and kubeContext fields. The cluster name (the clusters map key) must be a lowercase identifier (alphanumeric characters, -, _ and ., starting and ending with an alphanumeric character) of at most 63 characters. The kubeContext value must match a context name from the .kube/config file.

Default clusterWhen no clusters are defined in the Runtime, Timoni will use the current context from the kubeconfig, unless the context is specifed using the --kube-context flag.

Example:

runtime: {
	apiVersion: "v1alpha1"
	name:       "fleet"
	clusters: {
		"preview-us-1": {
			group:       "staging"
			kubeContext: "eks-us-west-2"
		}
		"prod-us-1": {
			group:       "production"
			kubeContext: "eks-us-west-1"
		}
		"prod-eu-1": {
			group:       "production"
			kubeContext: "eks-eu-west-1"
		}
	}
}

The clusters name and group, can be mapped to fields in a Bundle using @timoni() attributes.

bundle: {
	_cluster: string @timoni(runtime:string:TIMONI_CLUSTER_NAME)
	_env:     string @timoni(runtime:string:TIMONI_CLUSTER_GROUP)

	apiVersion: "v1alpha1"
	name:       "apps"
	instances: {
		app: {
			module: url: "oci://ghcr.io/stefanprodan/modules/podinfo"
			namespace: "apps"
			values: {
				ui: message: "Hosted by \(_cluster)"
				if _env == "staging" {
					replicas: 1
				}
				if _env == "production" {
					replicas: 2
				}
			}
		}
	}
}

When applying the above Bundle, Timoni will deploy the app instances to all the clusters, in the order defined in the Runtime. If the apply fails on a staging cluster, Timoni will stop the execution and not continue with production. For more details please see the multi-cluster deployments guide.

Values

The values array is for specifying the list of Kubernetes resources and the fields to be extracted.

Query

The values.query is a required field that specifies the Kubernetes resource. The query field must be in the format k8s:<apiVersion>:<kind>:<namespace>:<name>. Example:

runtime: {
	apiVersion: "v1alpha1"
	name:       "production"
	values: [
		{
			query: "k8s:v1:Secret:infra:redis-auth"
			for: {
				"REDIS_PASS": "obj.data.password"
			}
		},
	]
}

If the Kubernetes resource is global, the query format is k8s:<apiVersion>:<kind>:<name>. Example:

runtime: {
	apiVersion: "v1alpha1"
	name:       "production"
	values: [
		{
			query: "k8s:cert-manager.io/v1:ClusterIssuer:letsencrypt"
			for: {
				"ISSUER_EMAIL": "obj.spec.acme.email"
			}
		},
	]
}

For

The values.for is a required map that specifies which fields to be extracted from the Kubernetes resource. The for map must contain pairs of name and CUE expression. Example:

runtime: {
	apiVersion: "v1alpha1"
	name:       "production"
	values: [
		{
			query: "k8s:source.toolkit.fluxcd.io/v1:GitRepository:flux-system:cluster"
			for: {
				"GIT_REVISION": "obj.status.artifact.revision"
				"GIT_STATUS":   "[for c in obj.status.conditions if c.type == \"Ready\" {c.status}][0]"
			}
		},
	]
}

The CUE expression must result in a concrete value of type string, number or bool.

Optional

The optional field can be set to true and Timoni will skip not found Kubernetes resources instead of throwing an error.

Using values from Kubernetes API

The values defined in a Runtime can be referred in Bundles using CUE attributes. The @timoni(runtime:[string|number|bool]:[VAR_NAME]) CUE attribute can be placed next to a field to set its value from the runtime.

bundle: {
	apiVersion: "v1alpha1"
	name:       "app"
	instances: {
		app: {
			module: url: "oci://localhost:5000/modules/app"
			namespace: "apps"
			values: {
				host:    string @timoni(runtime:string:HOST)
				enabled: bool   @timoni(runtime:bool:ENABLED)
				score:   int    @timoni(runtime:number:SCORE)
			}
		}
	}
}

If a runtime value is optional, you can provide defaults which will be used only if the runtime doesn’t contain the referenced value:

values: {
	host:    "example.com" @timoni(runtime:string:HOST)
	enabled: true          @timoni(runtime:bool:ENABLED)
	score:   1             @timoni(runtime:number:SCORE)
}

To load the runtime values at apply time, use the --runtime flag:

timoni bundle apply -f bundle.cue --runtime runtime.cue

At apply time, Timoni injects the fields values from the runtime, if a specified runtime var is not found and if a default is not provided, the apply with fail with an incomplete value error. Runtime values are validated against the type declared in the attribute before they are injected. A number value must be a CUE number literal, and a bool value must be true or false; anything else fails the apply with a failed to parse attribute error. A string value is quoted, so it may hold arbitrary text including newlines.

Using values from environment variables

To use values from environment variables, the environment must contain variables which match the CUE attributes. Example:

bundle: {
	apiVersion: "v1alpha1"
	name:       "app"
	instances: {
		app: {
			module: url: "oci://localhost:5000/modules/app"
			namespace: "apps"
			values: {
				sshKey:  string @timoni(runtime:string:SSH_KEY)
				isAdmin: false  @timoni(runtime:bool:IS_ADMIN)
			}
		}
	}
}

Export the env vars and run the timoni bundle apply --runtime-from-env command.

EXPORT SSH_KEY=$(cat .ssh/id_ecdsa.pub)
EXPORT IS_ADMIN="true"

timoni bundle apply -f bundle.cue --runtime-from-env

Mixing values from the Runtime and EnvironmentWhen using timoni bundle apply --runtime runtime.cue --runtime-from-env, the values coming from the Runtime take precedence over the Environment.

Get Started

App Delivery

App Packaging

Integrations

Bundle Runtime

Example

Writing a Runtime spec

API version

Name

Clusters

Values

Query

For

Optional

Using values from Kubernetes API

Using values from environment variables

​Example

​Writing a Runtime spec

​API version

​Name

​Clusters

​Values

​Query

​For

​Optional

​Using values from Kubernetes API

​Using values from environment variables

Example

Writing a Runtime spec

API version

Name

Clusters

Values

Query

For

Optional

Using values from Kubernetes API

Using values from environment variables