Architecture and Concepts

Overview

Runnable is a component of Cartographer. The Runnable CRD provides an intermediate layer to update immutable resources. For example, Tekton does not allow updating TaskRuns and PipelineRuns, so Cartographer can update a Runnable object which then creates a new immutable TaskRun/PipelineRun.

Prefer Lifecycle Templates

Note: For most all use cases, users should use lifecycle templates rather than Runnables. The only use case where Runnable would be preferred is if users need to leverage Runnable’s selector (which is unusual).

Concepts

ClusterRunTemplate

With the addition of Runnable, there is a new template, ClusterRunTemplate. A ClusterRunTemplate will always create resources (i.e. kubectl create).

ClusterRunTemplate consists of:

• The Kubernetes resource yaml as spec.template
• Output paths which tell Cartographer where to find the output of the Kubernetes resource
  • The outputs will be added to runnable.status.outputs

Runnable

Runnables consist of:

• RunTemplateRef: a reference to a ClusterRunTemplate which contains the yaml of the immutable resource to be created
• Selector: used to dynamically discover a resource that is needed in the ClusterRunTemplate. The matching resource is available in the template data as selected.
• Inputs: arbitrary key, value pairs that are passed along to the ClusterRunTemplate.

Template Data

See Template Data for templating in Cartographer.

The ClusterRunTemplate is provided a data structure that contains:

• runnable
• selected

Runnable

The entire Runnable resource is available for retrieving values. To use a Runnable value, use the format:

• Simple template: $(runnable.<field-name>.(...))$
• ytt: not currently supported, see issue

Runnable Examples

Simple template	ytt
$(runnable.metadata.name)$	N/A
$(runnable.spec.inputs)$	N/A

Selected

The entire selected resource is available for retrieving values. To use selected value, use the format:

• Simple template: $(selected.<field-name>.(...))$
• ytt: not currently supported, see issue

Selected Examples

Simple template	ytt
$(selected.metadata.name)$	N/A

Theory of Operation

When Cartographer reconciles a Runnable, the resource in the specified ClusterRunTemplate is applied:

1. Resolve Selector: attempt to find a resource that matches the selector
2. Generate and apply resource spec: Apply the result of interpolating spec.template in the ClusterRunTemplate, selected, and the runnable spec.
3. Retrieve Output: The output to use is specified in the template output path
   1. Get the output from the most recently created resource, where status.conditions[?(@.type=="Succeeded")].status == True.
   2. Store the output in runnable.status.outputs.

Runnable In Action

Using Runnable with a Supply Chain

To see an example of the rest of the supply chain, see ClusterSupplyChain.