From 1ec0a277aa502ed97d18484ce65680f2979eaf21 Mon Sep 17 00:00:00 2001 From: Ralph Bean Date: Sat, 12 Oct 2024 13:06:20 -0400 Subject: [PATCH 1/3] Document how to use dynamic labels In particular, how to introduce a monotonically increasing release label. --- docs/modules/ROOT/pages/how-tos/_nav.adoc | 1 + .../how-tos/configuring/dynamic-labels.adoc | 132 ++++++++++++++++++ 2 files changed, 133 insertions(+) create mode 100644 docs/modules/ROOT/pages/how-tos/configuring/dynamic-labels.adoc diff --git a/docs/modules/ROOT/pages/how-tos/_nav.adoc b/docs/modules/ROOT/pages/how-tos/_nav.adoc index 3738c930..fd5550bf 100644 --- a/docs/modules/ROOT/pages/how-tos/_nav.adoc +++ b/docs/modules/ROOT/pages/how-tos/_nav.adoc @@ -11,6 +11,7 @@ *** xref:how-tos/configuring/redundant-rebuilds.adoc[Preventing redundant rebuilds] *** xref:how-tos/configuring/build-with-args.adoc[Passing buildah arguments] *** xref:how-tos/configuring/custom-tags.adoc[Using custom tags] +*** xref:how-tos/configuring/dynamic-labels.adoc[Using dynamic labels] *** xref:how-tos/configuring/overriding-compute-resources.adoc[Overriding compute resources] *** xref:how-tos/configuring/entitlement-subscription.adoc[Using Red Hat entitlement subscription] *** xref:how-tos/configuring/reconfiguring-build-pipeline.adoc[Reconfiguring the build pipeline] diff --git a/docs/modules/ROOT/pages/how-tos/configuring/dynamic-labels.adoc b/docs/modules/ROOT/pages/how-tos/configuring/dynamic-labels.adoc new file mode 100644 index 00000000..d2b9b812 --- /dev/null +++ b/docs/modules/ROOT/pages/how-tos/configuring/dynamic-labels.adoc @@ -0,0 +1,132 @@ += 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. + +. <> +. <> +. <> + +[NOTE] +==== +These can be combined and used together. +==== + +[[supplying-labels-to-the-build-container-task]] +== Supplying labels to the build-container task with the LABELS param + +You can specify additional labels to be applied to your image with the LABELS param, e.g.: + +[source,yaml] +---- +tasks: +... +- name: build-container + ... + params: + - name: IMAGE + value: "$(params.output-image)" + - name: DOCKERFILE + value: "$(params.dockerfile)" + - name: HERMETIC + value: "$(params.hermetic)" + - name: LABELS <.> + value: + - from-pull-request=true + - hermetic-param=$(params.hermetic) +... +---- + +<.> The LABELS param accepts an array of labels to be applied to the image after it is built. + +[[generating-dynamic-labels]] +== Generating dynamic labels + +You can use the *generate-labels* task to produce some dynamic labels. To do so, add the generate-labels task to the list of tasks in your pipeline, e.g.: + +[source,yaml] +---- +tasks: +... + - name: generate-labels + params: + - name: label-templates + value: + - "build-date=$SOURCE_DATE" <.> + - "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 +... +---- + +<.> The generate-labels task defines a small number of environment variables that can usefully be applied to labels, like $SOURCE_DATE and $SOURCE_DATE_EPOCH. See its documentation at link:https://github.com/konflux-ci/tekton-catalog/build-definitions/tree/main/task/generate-labels/0.1[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 task to the labels param of the build-container task, e.g.: + +[source,yaml] +---- +tasks: +... +- name: build-container + ... + params: + ... + - name: LABELS + value: $(tasks.generate-labels.results.labels) +... +---- + + +[[incrementing-release-label]] +== An incrementing release label + +A common use case for dynamic labels 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. + +NOTE: 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. + +[source,yaml] +---- +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) +... +---- From 8121f1bbf4fd826640e67b8b5b112ebeaf9006cb Mon Sep 17 00:00:00 2001 From: Ralph Bean Date: Tue, 15 Oct 2024 07:40:59 -0400 Subject: [PATCH 2/3] Make it more clear that this is array expansion --- .../ROOT/pages/how-tos/configuring/dynamic-labels.adoc | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/modules/ROOT/pages/how-tos/configuring/dynamic-labels.adoc b/docs/modules/ROOT/pages/how-tos/configuring/dynamic-labels.adoc index d2b9b812..6012f59b 100644 --- a/docs/modules/ROOT/pages/how-tos/configuring/dynamic-labels.adoc +++ b/docs/modules/ROOT/pages/how-tos/configuring/dynamic-labels.adoc @@ -82,7 +82,8 @@ tasks: params: ... - name: LABELS - value: $(tasks.generate-labels.results.labels) + value: + - $(tasks.generate-labels.results.labels[*]) ... ---- @@ -127,6 +128,7 @@ tasks: params: ... - name: LABELS - value: $(tasks.generate-labels.results.labels) + value: + - $(tasks.generate-labels.results.labels[*]) ... ---- From e48bdcef19d711ca136bcca16e13b349ce43d5a6 Mon Sep 17 00:00:00 2001 From: Ralph Bean Date: Tue, 15 Oct 2024 07:45:09 -0400 Subject: [PATCH 3/3] Provide an example of combining the two approaches --- .../how-tos/configuring/dynamic-labels.adoc | 26 +++++++++++++++---- 1 file changed, 21 insertions(+), 5 deletions(-) diff --git a/docs/modules/ROOT/pages/how-tos/configuring/dynamic-labels.adoc b/docs/modules/ROOT/pages/how-tos/configuring/dynamic-labels.adoc index 6012f59b..9552ed16 100644 --- a/docs/modules/ROOT/pages/how-tos/configuring/dynamic-labels.adoc +++ b/docs/modules/ROOT/pages/how-tos/configuring/dynamic-labels.adoc @@ -5,11 +5,7 @@ Konflux allows applying some dynamic labels to images derived from properties an . <> . <> . <> - -[NOTE] -==== -These can be combined and used together. -==== +. <> [[supplying-labels-to-the-build-container-task]] == Supplying labels to the build-container task with the LABELS param @@ -132,3 +128,23 @@ tasks: - $(tasks.generate-labels.results.labels[*]) ... ---- + +[[combining-approaches]] +== Combining approaches + +You can combine the approaches described above and supply a list of labels to the build-container task constructed from multiple sources. + +[source,yaml] +---- +tasks: +... + - name: build-container + ... + params: + ... + - name: LABELS + value: + - $(tasks.generate-labels.results.labels[*]) + - "short-commit=$(tasks.clone-repository.results.short-commit)" +... +----