From 497673c66f1420ad0f49d245e6adf159ab7804ac Mon Sep 17 00:00:00 2001 From: Fabrizio Asta Date: Tue, 19 Nov 2024 22:53:17 +0100 Subject: [PATCH] Keep remote pipelines up to date documentation --- docs/modules/ROOT/pages/how-tos/_nav.adoc | 1 + .../ROOT/pages/how-tos/workflows/index.adoc | 2 +- .../keep-remote-pipelines-up-to-date.adoc | 107 ++++++++++++++++++ 3 files changed, 109 insertions(+), 1 deletion(-) create mode 100644 docs/modules/ROOT/pages/how-tos/workflows/keep-remote-pipelines-up-to-date.adoc diff --git a/docs/modules/ROOT/pages/how-tos/_nav.adoc b/docs/modules/ROOT/pages/how-tos/_nav.adoc index 1e0f0fc5..86766b96 100644 --- a/docs/modules/ROOT/pages/how-tos/_nav.adoc +++ b/docs/modules/ROOT/pages/how-tos/_nav.adoc @@ -35,3 +35,4 @@ ** xref:how-tos/deleting.adoc[Deleting applications and components] ** xref:how-tos/workflows/index.adoc[Guidelines for {ProductName} integrated repositories] *** xref:how-tos/workflows/git-submodules.adoc[Building upstream projects with git submodules] +*** xref:how-tos/workflows/keep-remote-pipelines-up-to-date.adoc[Maintaining remote pipelines up to date] \ No newline at end of file diff --git a/docs/modules/ROOT/pages/how-tos/workflows/index.adoc b/docs/modules/ROOT/pages/how-tos/workflows/index.adoc index 57bfb78f..80e60a7b 100644 --- a/docs/modules/ROOT/pages/how-tos/workflows/index.adoc +++ b/docs/modules/ROOT/pages/how-tos/workflows/index.adoc @@ -3,4 +3,4 @@ Depending on your use case, there are several guidelines you can use for repositories that are integrated with {ProductName}: * xref:/how-tos/workflows/git-submodules.adoc[Git Submodule pattern] - +* xref:how-tos/workflows/keep-remote-pipelines-up-to-date.adoc[Maintaining remote pipelines up to date] \ No newline at end of file diff --git a/docs/modules/ROOT/pages/how-tos/workflows/keep-remote-pipelines-up-to-date.adoc b/docs/modules/ROOT/pages/how-tos/workflows/keep-remote-pipelines-up-to-date.adoc new file mode 100644 index 00000000..05f7e631 --- /dev/null +++ b/docs/modules/ROOT/pages/how-tos/workflows/keep-remote-pipelines-up-to-date.adoc @@ -0,0 +1,107 @@ += Maintaining remote Tekton pipelines up to date + +[IMPORTANT] +==== +* This article took for granted the reader knows what a link:https://tekton.dev/docs/pipelines/resolution/[Tekton remote pipeline] is. If this is not the case, please read more about this feature before proceeding. +==== + +== The advantage of using a remote pipeline + +This approach allows a team or an individual contributor to manage plenty of Pipelines from a single repository as source of truth. But there also other good reasons: + +. Pipelines are stored in a Git repository and fetched during execution, eliminating the need to maintain local or static pipeline definitions. +. Teams can leverage Git’s versioning to access specific pipeline branches +. In case of issues, it's very simple to rollback to a previous pipeline version, and apply it globally among the Konflux Components. +. Reduced maintenance overhead + +To start referencing a remote Pipeline from a PipelineRun using a *git resolver*, replace *pipelineSpec* with *pipelineRef*: + +[source,yaml] +---- +apiVersion: tekton.dev/v1 +kind: PipelineRun +metadata: ... # Omitted for brevity +spec: + params: ... # Omitted for brevity + pipelineRef: + resolver: git + params: + - name: org + value: redhat + - name: scmType + value: gitlab + - name: serverURL + value: https://gitlab.cee.redhat.com + - name: url + value: "https://gitlab.cee.redhat.com/your-group-name/your-repo-name.git" + - name: revision + value: main # Specify a branch to target + - name: pathInRepo + value: "pipelines/your-pipeline-name.yaml" # Internal repository path to your pipeline definition YAML file + - name: token + value: pipelines-as-code-secret # Name of the Secret + - name: tokenKey + value: password # Name of the attribute within your Secret, that stores the password/token + workspaces: ... # Omitted for brevity +---- + +== The drawback of having a remote pipeline + +Although Tekton remote pipelines is a huge improvement, it comes with a drawback; the Pipeline CRDs will not be stored in the Konflux Component repository anymore, so MintMaker will not be able to update the TaskRef digests for us. + +== The solution + +To workaround the above issue, the suggested approach is to onboard the repository where the shared pipelines are stored as a Konflux Component, so that Konflux and MintMaker will be able to discover and update digests for us. + +.*Prerequisites* + +* Having a repository where to store shared Pipelines and Tasks. + +[IMPORTANT] +==== +If the repository is private, be sure to have a Secret in place on Konflux to be able to clone it +==== + +.*Procedures* + +. Add Tekton Pipelines and Tasks in the repository. A suggested repository structure would be: + ++ +[source,shell] +---- +. +├── .tekton +│ ├── -pipelines-pull-request.yaml # Used by Konflux to listen to pull requests +│ └── -pipelines-push.yaml # Used by Konflux to listen to pushes +├── pipelines +│ ├── remote-pipeline1.yaml +│ └── remote-pipeline2.yaml +├── tasks +│ ├── remote-task1.yaml +│ └── remote-task2.yaml +└── renovate.json #Renovate/MintMaker configuration +---- + +. Configure and extend MintMaker properly, so that it will be able to discover Tekton Pipelines and take care of them in custom paths: + ++ +[source,json] +.renovate.json +---- +{ + "$schema": "https://docs.renovatebot.com/renovate-schema.json", + "tekton": { + "fileMatch": ["\\.yaml$", "\\.yml$"], // Tekton pipelines to match + "includePaths": ["pipelines/**", "tasks/**"], // Paths where to look for Tekton Pipelines to update + "automerge": true // Define whether MintMaker must take care of PRs and automerge them or not + } +} +---- + ++ +[NOTE] +==== +* MintMaker will read the default configuration from "https://docs.renovatebot.com/renovate-schema.json" and will extend it using the subsequent custom settings. +==== + +. xref:how-tos/creating.adoc[Create a Konflux Application and a Konflux Component] where to reference the repository and branch name.