Logo

Documentation

Runnable Custom Resources

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).

Runnable

A Runnable object declares the intention of having immutable objects submitted to Kubernetes according to a template ( via ClusterRunTemplate) whenever any of the inputs passed to it changes. i.e., it allows us to provide a mutable spec that drives the creation of immutable objects whenever that spec changes.

---
apiVersion: carto.run/v1alpha1
kind: Runnable
metadata: {}
spec:

  # Inputs are key/values providing inputs to the templated object
  # created for this runnable. Reference inputs in the template
  # using the jsonPath: $(runnable.spec.inputs.<key>)$
  # +optional
  inputs: {}

  # RetentionPolicy specifies how many successful and failed runs
  # should be retained. Runs older than this (ordered by creation
  # time) will be deleted. Setting higher values will increase
  # memory footprint.
  # +optional
  retentionPolicy:

    # MaxFailedRuns is the number of failed runs to retain.
    maxFailedRuns: <integer>

    # MaxSuccessfulRuns is the number of successful runs to
    # retain.
    maxSuccessfulRuns: <integer>

  # RunTemplateRef identifies the run template used to produce
  # resources for this runnable.
  runTemplateRef:
    kind: <string>
    name: <string>

  # Selector refers to an additional object that the template can
  # refer to using: $(selected)$.
  # +optional
  selector:

    # MatchingLabels must match on a single target object, making
    # the object available in the template as $(selected)$
    matchingLabels: {}

    # Resource is the GVK that must match the selected object.
    resource:
      apiVersion: <string>
      kind: <string>

  # ServiceAccountName refers to the Service account with
  # permissions to create resources submitted by the
  # ClusterRunTemplate. 
  # If not set, Cartographer will use the default service account
  # in the runnable's namespace.
  # +optional
  serviceAccountName: <string>

ClusterRunTemplate

A ClusterRunTemplate defines how an immutable object should be stamped out based on data provided by a Runnable.

---
apiVersion: carto.run/v1alpha1
kind: ClusterRunTemplate
metadata: {}
spec:

  # Outputs are a named list of jsonPaths that are used to gather
  # results from the last successful object stamped by the
  # template. E.g: 	my-output:
  # .status.results[?(@.name=="IMAGE-DIGEST")].value Note: outputs
  # are only filled on the runnable when the templated object has
  # a Succeeded condition with a Status of True E.g:    
  # status.conditions[?(@.type=="Succeeded")].status == True a
  # runnable creating an object without a Succeeded condition
  # (like a Job or ConfigMap) will never display an output
  # +optional
  outputs: {}

  # Template defines a resource template for a Kubernetes Resource
  # or Custom Resource which is applied to the server each time
  # the blueprint is applied. Templates support simple value
  # interpolation using the $()$ marker format. For more
  # information, see:
  # https://cartographer.sh/docs/latest/templating/ You should not
  # define the namespace for the resource - it will automatically
  # be created in the owner namespace. If the namespace is
  # specified and is not the owner namespace, the resource will
  # fail to be created.
  template: {}

ClusterRunTemplate differs from supply chain templates in many aspects:

  • ClusterRunTemplate cannot be referenced directly by a ClusterSupplyChain object (it can only be reference by a Runnable)

  • outputs provide a free-form way of exposing any form of results from what has been run (i.e., submitted by the Runnable) to the status of the Runnable object (as opposed to typed “source”, “image”, and “config” from supply chains)

  • Templating context (values provided to the interpolation) is specific to the Runnable: the runnable object itself and the object resulting from the selection query.

  • Templated object metadata.name should not be set. differently from ClusterSupplyChain, a Runnable has the semantics of creating new objects on change, rather than patching. This means that on every input set change, a new name must be derived. To be sure that a name can always be generated, metadata.generateName should be set rather than metadata.name.

Similarly to other templates, ClusterRunTemplate has a template field where data is taken (in this case, from Runnable and selected objects via runnable.spec.selector) and via $()$ allows one to interpolate such data to form a final object.