Using dynamic labels

Konflux allows applying some dynamic labels to images derived from properties and params of the build pipeline. The labelling is supported directly by the LABELS param of the build-container tasks. A supporting generate-labels task can optionally be used to produce some dynamic labels.

  1. Supplying labels and annotations to the build-container task with the LABELS and ANNOTATIONS params

  2. Generating dynamic labels or annotations

  3. An incrementing release label or annotation

  4. Combining approaches

Supplying labels and annotations to the build-container task with the LABELS and ANNOTATIONS params

You can specify additional labels and/or annotations to be applied to your image with the LABELS and ANNOTATIONS params, e.g.:

tasks:
...
- name: build-container
  ...
  params:
    - name: IMAGE
      value: "$(params.output-image)"
    - name: DOCKERFILE
      value: "$(params.dockerfile)"
    - name: HERMETIC
      value: "$(params.hermetic)"
    - name: LABELS (1)
      value:
        - from-pull-request=true
        - hermetic-param=$(params.hermetic)
    - name: ANNOTATIONS (2)
      value:
        - my-annotation=true
        - foo=bar
...
1 The LABELS and ANNOTATIONS params accepts an array of labels and annotations to be applied to the image after it is built.

Generating dynamic labels or annotations

You can use the generate-labels task to produce some dynamic labels or annotations. To do so, add the generate-labels task to the list of tasks in your pipeline, e.g.:

tasks:
...
    - name: generate-labels
      params:
        - name: label-templates
          value:
             - "build-date=$SOURCE_DATE" (1)
             - "short-commit=$(tasks.clone-repository.results.short-commit)"
        - name: source-date-epoch
          value: '$(tasks.clone-repository.results.commit-timestamp)'
      runAfter:
        - clone-repository
      taskRef:
        params:
          - name: name
            value: generate-labels
          - name: bundle
            value: quay.io/konflux-ci/tekton-catalog/task-generate-labels:0.1@sha256:0068fe8b3c5d010daee5a922781a74cfb82251e775c260d14d9e50dd1a7aca65
          - name: kind
            value: task
        resolver: bundles
...
1 The generate-labels task defines a small number of environment variables that can usefully be applied to labels and/or annotations, like $SOURCE_DATE and $SOURCE_DATE_EPOCH. See its documentation at task/generate-labels.

The generate-labels task exposes a labels result that can be passed to the build-container task. To be useful, you need to supply the labels result from the generate-labels/generate-annotation tasks to the LABELS/ANNOTATIONS params of the build-container task, e.g.:

tasks:
...
- name: build-container
  ...
  params:
    ...
    - name: LABELS
      value:
      - $(tasks.generate-labels.results.labels[*])
    - name: ANNOTATIONS
      value:
      - $(tasks.generate-annotations.results.labels[*])
...

An incrementing release label or annotation

A common use case for dynamic labels or anootations is to introduce a monotonically incrementing release label.

To achieve this, use either the $SOURCE_DATE or the $ACTUAL_DATE as the value for your release label, depending on your team’s preference.

Use of $SOURCE_DATE will tie your release label to the timestamp of the commit that produces the build, and is more reproducible. Use of $ACTUAL_DATE will tie your release label to the timestamp at the time the build actually takes place, which yields builds that are less reproducible, but which may make more sense for your team’s expectations and working model. 
tasks:
...
    - name: generate-labels
      params:
        - name: label-templates
          value:
             - "release=$SOURCE_DATE_EPOCH"
        - name: source-date-epoch
          value: '$(tasks.clone-repository.results.commit-timestamp)'
      runAfter:
        - clone-repository
      taskRef:
        params:
          - name: name
            value: generate-labels
          - name: bundle
            value: quay.io/konflux-ci/tekton-catalog/task-generate-labels:0.1@sha256:0068fe8b3c5d010daee5a922781a74cfb82251e775c260d14d9e50dd1a7aca65
          - name: kind
            value: task
        resolver: bundles
...
    - name: build-container
      ...
      runAfter:
        ...
        - generate-labels
      params:
        ...
        - name: LABELS
          value:
          - $(tasks.generate-labels.results.labels[*])
...

Combining approaches

You can combine the approaches described above and supply a list of labels and/or annotations to the build-container task constructed from multiple sources.

tasks:
...
    - name: build-container
      ...
      params:
        ...
        - name: LABELS
          value:
          - $(tasks.generate-labels.results.labels[*])
          - "short-commit=$(tasks.clone-repository.results.short-commit)"
        - name: ANNOTATIONS
          value:
          - $(tasks.generate-labels.results.labels[*])
          - "short-commit=$(tasks.clone-repository.results.short-commit)"
...

You can use array indexing to supply some of the results to labels and some others to annotations:

tasks:
...
    - name: build-container
      ...
      params:
        ...
        - name: LABELS
          value:
          - $(tasks.generate-labels.results.labels[1])
        - name: ANNOTATIONS
          value:
          - $(tasks.generate-labels.results.labels[2])
          - $(tasks.generate-labels.results.labels[3])
...