From 1913a8d023b25fab5b7a8aad287baee09a7042f1 Mon Sep 17 00:00:00 2001 From: Aline Abler Date: Mon, 5 Aug 2024 17:27:43 +0200 Subject: [PATCH 1/2] Add documentation for CI/CD setup and Commodore Compile Pipeline --- docs/Makefile | 4 +- .../ROOT/pages/explanations/cicd-support.adoc | 40 ++++++++ .../pages/how-tos/compile-pipeline-setup.adoc | 92 +++++++++++++++++++ .../ROOT/partials/nav-explanation.adoc | 1 + docs/modules/ROOT/partials/nav-howtos.adoc | 1 + 5 files changed, 136 insertions(+), 2 deletions(-) create mode 100644 docs/modules/ROOT/pages/explanations/cicd-support.adoc create mode 100644 docs/modules/ROOT/pages/how-tos/compile-pipeline-setup.adoc diff --git a/docs/Makefile b/docs/Makefile index d2349038..c11c659f 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -13,10 +13,10 @@ asciidoctor_epub3_cmd ?= $(docker_cmd) run $(docker_opts) --volume "$${PWD}":/d asciidoctor_opts ?= --destination-dir=$(out_dir) asciidoctor_kindle_opts ?= --attribute ebook-format=kf8 -vale_cmd ?= $(docker_cmd) run $(docker_opts) --volume "$${PWD}"/src/modules/ROOT/pages:/pages vshn/vale:2.6.1 --minAlertLevel=error /pages +vale_cmd ?= $(docker_cmd) run $(docker_opts) --volume "$${PWD}"/src/modules/ROOT/pages:/pages ghcr.io/vshn/vale:2.27.0 --minAlertLevel=error /pages hunspell_cmd ?= $(docker_cmd) run $(docker_opts) --volume "$${PWD}":/spell vshn/hunspell:1.7.0 -d en,vshn -l -H _public/**/**/*.html htmltest_cmd ?= $(docker_cmd) run $(docker_opts) --volume "$${PWD}"/_public:/test wjdp/htmltest:v0.12.0 -preview_img ?= vshn/antora-preview:3.0.1.1 +preview_img ?= ghcr.io/vshn/antora-preview:3.1.2.3 preview_cmd ?= $(docker_cmd) run --rm --publish 35729:35729 --publish 2020:2020 --volume "${PWD}":/preview/antora $(preview_img) --antora=docs --style=syn .PHONY: docs-all diff --git a/docs/modules/ROOT/pages/explanations/cicd-support.adoc b/docs/modules/ROOT/pages/explanations/cicd-support.adoc new file mode 100644 index 00000000..55adacf4 --- /dev/null +++ b/docs/modules/ROOT/pages/explanations/cicd-support.adoc @@ -0,0 +1,40 @@ += CI/CD Support + +Lieutenant can configure Git repositories to enable CI/CD for tenant repositories. +This feature is designed to support the https://github.com/projectsyn/commodore-compile-pipelines[Commodore Compile Pipeline], but can be used independently. + + +[NOTE] +-- +Automatic configuration of CI/CD tooling is so far only supported on GitLab. + +To allow the Lieutenant Operator to connect to GitLab, refer to xref:how-tos/gitlab-connection.adoc[Connection to GitLab]. +-- + +== CI/CD pipeline configuration +Lieutenant configures the CI/CD pipeline by managing files in the tenant repository, such as the `.gitlab-ci.yml` file. +These files are configured in the tenant's `spec.compilePipeline.pipelineFiles`, where arbitrary files can be defined that are added to the tenant repository if the compile pipeline is enabled. + +The system assumes that the CI/CD system (for example GitLab CI) can be fully configured using files in the repository. + +== CI/CD parameters +Lieutenant ensures that the CI/CD pipeline can access the Lieutenant API as well as the necessary cluster catalog repositories. +This is achieved by passing a number of parameters to the CI/CD pipeline. + +The mechanism by which these parameters are provided is specific to a Git host. +Currently, only GitLab is supported, where this information is provided through CI/CD variables on the tenant repository. + + +In particular, the following parameters are provided on a tenant where `spec.compilePipeline.enabled` is set to `true`: + +* `ACCESS_TOKEN_CLUSTERNAME`, where `CLUSTERNAME` is the name of a specific cluster, with `-` replaced by `_`. + This contains an access token, which has read-write access the corresponding cluster's catalog repository. + The access token is created automatically for each cluster where `spec.enableCompilePipeline` is set to `true` and `spec.gitRepoTemplate.accessToken` contains a valid secret reference. +* `COMMODORE_API_URL`. This contains the URL at which the Lieutenant API can be accessed. +* `COMMODORE_API_TOKEN`. This contains an access token for the Lieutenant API. +* `CLUSTERS`. This contains a space-separated list of cluster IDs for which the CI/CD pipeline should run; that is, the list of clusters where `spec.enableCompilePipeline` is `true`. + +The CI/CD pipeline can use these parameters to compile cluster catalogs with Commodore, and push them to the corresponding catalog repositories. +The https://github.com/projectsyn/commodore-compile-pipelines[Commodore Compile Pipeline] is a GitLab CI pipeline definition which accomplishes that. +However, it is possible to use other CI/CD systems. + diff --git a/docs/modules/ROOT/pages/how-tos/compile-pipeline-setup.adoc b/docs/modules/ROOT/pages/how-tos/compile-pipeline-setup.adoc new file mode 100644 index 00000000..3de49c34 --- /dev/null +++ b/docs/modules/ROOT/pages/how-tos/compile-pipeline-setup.adoc @@ -0,0 +1,92 @@ += Compile Pipeline Setup + +Lieutenant can automatically configure CI/CD tooling on your Git repositories. +This page explains how to set up the https://github.com/projectsyn/commodore-compile-pipelines[Commodore Compile Pipeline]. + +[NOTE] +-- +Automatic configuration of CI/CD tooling is so far only supported on GitLab. + +To allow the Lieutenant Operator to connect to GitLab, refer to xref:how-tos/gitlab-connection.adoc[Connection to GitLab]. +-- + +== Enabling the Compile Pipeline for individual tenants and clusters + +The `compilePipelineSpec` field on a Tenant object governs how CI/CD tooling is managed. +To enable the Commodore Compile Pipeline on a tenant, configure it as follows: + +[source,bash] +.... +kubectl patch tenant my-tenant --type merge -p ' +spec: + compilePipeline: + enabled: true <1> + pipelineFiles: + .gitlab-ci.yml: | <2> + include: + - https://raw.githubusercontent.com/projectsyn/commodore-compile-pipelines/main/gitlab/commodore-pipeline.yml +' +.... +<1> This field enables the compile pipeline for this tenant. +If it is `false` or unset, no CI/CD tooling will be managed, regardless of other configuration options on the tenant or its clusters. +<2> This example causes Lieutenant to create a file `.gitlab-ci.yml` in the tenant repository, which references the open-source https://github.com/projectsyn/commodore-compile-pipelines[Commodore Compile Pipeline]. +It is possible to customize this file, or create different files. + +In addition, the Compile Pipeline must be enabled for each cluster where CI/CD is desired: +[source,bash] +.... +kubectl patch cluster my-cluster --type merge -p ' +spec: + enableCompilePipeline: true <1> + gitRepoTemplate: + accessToken: + secretRef: my-cluster-api-token <2> +' +.... +<1> This field enables the compile pipeline for this cluster. +If it is `false` or unset, the tenant's CI/CD configuration will disregard this cluster. +<2> For the compile pipeline to work, an access token for the Git repository is required. +Lieutenant creates this access token and will store it in the secret specified here. + + +== Enabling the Compile Pipeline for all clusters of a tenant + +We can leverage templating to configure and enable the Compile Pipeline for all clusters on a tenant. +For more information on templating, refer to xref:explanations/templating.adoc[Templating]. + +The following example configures a tenant such that its clusters automatically include the correct configuration for the Compile Pipeline: +[source,bash] +.... +kubectl patch tenant my-tenant --type merge -p ' +spec: + clusterTemplate: + enableCompilePipeline: true + gitRepoTemplate: + accessToken: + secretRef: '{{ .Name }}-api-token' +' +.... + + +== Enabling the Compile Pipeline for all tenants + +We can leverage tenant templating to configure and enable the Compile Pipeline for all clusters on a tenant. +For more information on templating, refer to xref:how-tos/create-tenant.adoc#_tenant_templating[Tenant Templating]. + +[source,bash] +.... +kubectl patch tenanttemplate my-template --type merge -p ' +spec: + clusterTemplate: + enableCompilePipeline: true + gitRepoTemplate: + accessToken: + secretRef: '{{ .Name }}-api-token' + compilePipeline: + enabled: true + pipelineFiles: + .gitlab-ci.yml: | + include: + - https://raw.githubusercontent.com/projectsyn/commodore-compile-pipelines/main/gitlab/commodore-pipeline.yml +' +.... diff --git a/docs/modules/ROOT/partials/nav-explanation.adoc b/docs/modules/ROOT/partials/nav-explanation.adoc index 2f52b5a7..a24a8088 100644 --- a/docs/modules/ROOT/partials/nav-explanation.adoc +++ b/docs/modules/ROOT/partials/nav-explanation.adoc @@ -2,3 +2,4 @@ * xref:lieutenant-operator:ROOT:explanations/deletion.adoc[Object Deletion] * xref:lieutenant-operator:ROOT:explanations/templating.adoc[Templating] * xref:lieutenant-operator:ROOT:explanations/rbac-access.adoc[Multi tenant access] +* xref:lieutenant-operator:ROOT:explanations/cicd-support.adoc[CI/CD support] diff --git a/docs/modules/ROOT/partials/nav-howtos.adoc b/docs/modules/ROOT/partials/nav-howtos.adoc index 0e386327..f809dd9c 100644 --- a/docs/modules/ROOT/partials/nav-howtos.adoc +++ b/docs/modules/ROOT/partials/nav-howtos.adoc @@ -2,6 +2,7 @@ * xref:lieutenant-operator:ROOT:how-tos/vault.adoc[Vault Configuration] * xref:lieutenant-operator:ROOT:how-tos/local-env.adoc[Running Operator locally] * xref:lieutenant-operator:ROOT:how-tos/gitlab-connection.adoc[GitLab Connection] +* xref:lieutenant-operator:ROOT:how-tos/compile-pipeline-setup.adoc[Set up the Commodore Compile Pipeline] * xref:lieutenant-operator:ROOT:how-tos/create-tenant.adoc[Create a Tenant] * xref:lieutenant-operator:ROOT:how-tos/create-cluster.adoc[Create a Cluster] * xref:lieutenant-operator:ROOT:how-tos/create-gitrepo.adoc[Create a Git Repository] From 1236c7a817f3946eaa7ccc4f4a06d58c2afdf72d Mon Sep 17 00:00:00 2001 From: Aline Abler Date: Tue, 6 Aug 2024 17:12:33 +0200 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Simon Gerber --- docs/modules/ROOT/pages/explanations/cicd-support.adoc | 5 +++-- docs/modules/ROOT/pages/how-tos/compile-pipeline-setup.adoc | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/modules/ROOT/pages/explanations/cicd-support.adoc b/docs/modules/ROOT/pages/explanations/cicd-support.adoc index 55adacf4..b3b83650 100644 --- a/docs/modules/ROOT/pages/explanations/cicd-support.adoc +++ b/docs/modules/ROOT/pages/explanations/cicd-support.adoc @@ -6,7 +6,7 @@ This feature is designed to support the https://github.com/projectsyn/commodore- [NOTE] -- -Automatic configuration of CI/CD tooling is so far only supported on GitLab. +Currently, automatic configuration of CI/CD tooling is only supported on GitLab. To allow the Lieutenant Operator to connect to GitLab, refer to xref:how-tos/gitlab-connection.adoc[Connection to GitLab]. -- @@ -36,5 +36,6 @@ In particular, the following parameters are provided on a tenant where `spec.com The CI/CD pipeline can use these parameters to compile cluster catalogs with Commodore, and push them to the corresponding catalog repositories. The https://github.com/projectsyn/commodore-compile-pipelines[Commodore Compile Pipeline] is a GitLab CI pipeline definition which accomplishes that. -However, it is possible to use other CI/CD systems. +If the available CI pipeline definition isn't suitable for your use case, you can deploy an arbitrary valid `.gitlab-ci.yml` through the `pipelineFiles` mechanism. +Please note that Lieutenant doesn't check the validity of the files provided in `pipelineFiles`. diff --git a/docs/modules/ROOT/pages/how-tos/compile-pipeline-setup.adoc b/docs/modules/ROOT/pages/how-tos/compile-pipeline-setup.adoc index 3de49c34..78ee85b0 100644 --- a/docs/modules/ROOT/pages/how-tos/compile-pipeline-setup.adoc +++ b/docs/modules/ROOT/pages/how-tos/compile-pipeline-setup.adoc @@ -5,7 +5,7 @@ This page explains how to set up the https://github.com/projectsyn/commodore-com [NOTE] -- -Automatic configuration of CI/CD tooling is so far only supported on GitLab. +Currently, automatic configuration of CI/CD tooling is only supported on GitLab. To allow the Lieutenant Operator to connect to GitLab, refer to xref:how-tos/gitlab-connection.adoc[Connection to GitLab]. --