Lifecycle

Cartographer creates objects from templates and their inputs (values from user inputs or object earlier created by Cartographer). Over the lifespan of the object, we expect the definition of the object to change due to new inputs. The lifecycle field of a template allows specification of how the created object will be treated when a change is called for. Objects are either updated or new objects are created which will be read when successful.

Specifying No Lifecycle

If no lifecycle is specified in the template, Cartographer will default to the mutable lifecycle, described below.

Mutable Lifecycle

For most kubernetes objects, mutable lifecycle is the proper choice. These are resources that can be updated.

apiVersion: carto.run/v1alpha1
kind: Cluster[Config|Deployment|Image|Source]Template
spec:
  lifecycle: mutable

This will ensure that when a supply chain resource (step) refers to the template, the specified object will be stamped and created in the workload’s namespace. If the values passed to the template change, the object will be updated. If the template changes the name or GVK (group, version, kind) of object being created, the new object will be created and the previous object deleted.

The outputs from an object stamped from a mutable template are continuously read and passed on as inputs to later resources in the supply chain.

Immutable Lifecycle

Some Kubernetes objects are not meant to be updated. See Jobs for an example: https://kubernetes.io/docs/concepts/workloads/controllers/job/

You cannot update the Job because these fields are not updatable.

Objects that are immutable should be created with the immutable lifecycle:

apiVersion: carto.run/v1alpha1
kind: Cluster[Config|Deployment|Image|Source]Template
spec:
  lifecycle: immutable

When inputs to the template change and the definition of the object that would be stamped is altered, a new object will be created on the cluster. The previous object will continue to exist.

Immutable objects are only read when their health rule is fulfilled. Implications: When no immutable objects have previously existed and a new object is created, no values from it will be propagated down the supply chain until that object fulfills its health rules. When multiple immutable objects exist, the most recently created healthy object will have its values propagated down the supply chain.

To learn about specifying health rules, see here. A tutorial on health rules exists here.

Users may specify a retentionPolicy to determine how many previously created objects should remain on the cluster. The default immutable behavior is the equivalent of:

apiVersion: carto.run/v1alpha1
kind: Cluster[Config|Deployment|Image|Source]Template
spec:
  retentionPolicy:
    maxFailedRuns: 10
    maxSuccessfulRuns: 10

Given an 11th healthy object, the first created object will be garbage collected, and similar behavior given an 11th unhealthy object.

Tekton Lifecycle

Tekton tasks and pipelines can be useful in Cartographer supply chains. The Tekton lifecycle is a convenience method that does not need health rules specified. Given:

apiVersion: carto.run/v1alpha1
kind: Cluster[Config|Deployment|Image|Source]Template
spec:
  lifecycle: tekton

immutable objects will be created on the cluster. As Tekton uses the condition success to indicate a healthy pipelinerun/taskrun, Cartographer uses the equivalent of the following healthRule for tekton lifecycle objects:

apiVersion: carto.run/v1alpha1
kind: Cluster[Config|Deployment|Image|Source]Template
spec:
  healthRule:
    singleConditionType: Success

Users can override the healthRule by specifying it explicitly.

Tutorial Walkthrough

Our tutorials include a walkthrough of a use case for Tekton Lifecycle. Follow along, create k8s objects, observe the state of your cluster, and become a lifecycle expert.