diff --git a/.github/workflows/chart.yaml b/.github/workflows/chart.yaml index 43adec8c..0be0a3bc 100644 --- a/.github/workflows/chart.yaml +++ b/.github/workflows/chart.yaml @@ -3,7 +3,7 @@ name: Release Charts on: push: branches: - - featre/easy-install + - feature/easy-install jobs: release: @@ -21,5 +21,7 @@ jobs: - name: Run chart-releaser uses: helm/chart-releaser-action@v1.5.0 + with: + charts_dir: deploy env: CR_TOKEN: "${{ secrets.GITHUB_TOKEN }}" diff --git a/deploy/install.sh b/deploy/install.sh index e09551bf..0a9744b9 100755 --- a/deploy/install.sh +++ b/deploy/install.sh @@ -257,12 +257,18 @@ else installTLSSecret "ods-private-cert" "${private_cert}" fi +echo "Discovering Helm repository ..." +helm_repo_alias="ods-pipeline" +chart_name="ods-pipeline" +"${helm_bin}" repo add "${helm_repo_alias}" https://opendevstack.github.io/ods-pipeline +"${helm_bin}" repo update "${helm_repo_alias}" + echo "Installing Helm release ${release_name} ..." if [ "${diff}" == "true" ]; then if "${helm_bin}" -n "${namespace}" \ diff upgrade --install --detailed-exitcode --three-way-merge --normalize-manifests \ "${values_args[@]}" \ - ${release_name} ${chart_dir}; then + "${release_name}" "${helm_repo_alias}/${chart_name}"; then echo "Helm release already up-to-date." else if [ "${dry_run}" == "true" ]; then @@ -281,7 +287,7 @@ else "${helm_bin}" -n "${namespace}" \ upgrade --install \ "${values_args[@]}" \ - ${release_name} ${chart_dir} + "${release_name}" "${helm_repo_alias}/${chart_name}" fi fi diff --git a/docs/installation.adoc b/docs/installation.adoc index 4d9ab43a..26d48c95 100644 --- a/docs/installation.adoc +++ b/docs/installation.adoc @@ -5,50 +5,42 @@ This guide will show how to install ODS Pipeline in an existing ODS project. It An ODS Pipeline installation consists of the following resources: -* `Task` resources -* `ConfigMap` and `Secret` resources, e.g. holding credentials of centrally installed tools such as Nexus and SonarQube * A pipeline manager, which is creating pipeline runs in response to Bitbucket webhook requests +* A start and finish task which will get injected into every pipeline run +* `ConfigMap` and `Secret` resources, e.g. holding credentials of centrally installed tools such as Nexus and Bitbucket + == Prerequisites You'll need: -* A namespace in an OpenShift cluster (such as `foo-cd` from an existing ODS project) and a project in Bitbucket (such as `FOO`). +* A namespace in an OpenShift/Kubernetes cluster (such as `foo-cd` from an existing ODS project) and a project in Bitbucket (such as `FOO`). * `git`, link:https://docs.openshift.com/container-platform/latest/cli_reference/openshift_cli/getting-started-cli.html[`oc`] (or link:https://kubernetes.io/docs/reference/kubectl/[`kubectl`]) and link:https://helm.sh[`helm`] installed locally. The plugin link:https://github.com/databus23/helm-diff[`helm-diff`] is optional but recommended. == Installation Instructions -The installation procedure consists of two steps: - -1. Creating a Git repository defining the configuration of the ODS Pipeline installation -2. Using Helm to install from this Git repository +ODS Pipeline is packaged as a Helm chart. The installation procedure consists of three quick steps: -=== Creating a Git repository +1. Configuring the chart values +2. Running the install script (which will deploy the Helm chart) +3. Exposing a route to the pipeline manager -Create a new repository in Bitbucket, e.g. `foo-cd`. The name can be anything, but since the repository will define the K8s resources of namespace `foo-cd` in code, it makes sense to mirror the namespace name. Clone the repository locally and make an initial commit, e.g. by adding a readme file. +=== Step 1: Configuring the chart values -IMPORTANT: The following commands will fail in an empty Git repository, so make sure you have made at least one commit in this repository. - -Now use `git subtree` to get the required source files. The following commands may look a bit complicated, but in a nutshell, they are simply adding one folder (`deploy/`) from the `opendevstack/ods-pipeline` repository at the given revision (e.g. `master`) into your new local repository at the path `deploy`. The benefit of this approach is that it'll make updating ODS Pipeline simple. +Download the template and fill in the values according to the comments in that file. [source] ---- -pipelineGitRef=v0.13.2 # Pick the version you want to install - -git fetch --depth=1 https://github.com/opendevstack/ods-pipeline.git $pipelineGitRef:ods-pipeline-$pipelineGitRef && \ -git checkout ods-pipeline-$pipelineGitRef && \ -git subtree split --prefix=deploy -b subtree-split-branch-$pipelineGitRef && \ -git checkout - && \ -git subtree add --squash --prefix=deploy subtree-split-branch-$pipelineGitRef +curl -L https://raw.githubusercontent.com/opendevstack/ods-pipeline/master/deploy/values.yaml.tmpl -o values.yaml ---- -Once this is done, change to the new folder `deploy` to configure the values of the Helm Chart. Run `cp values.yaml.tmpl values.yaml`, then edit `values.yaml` as described in the comments in that file. Commit and push before proceeding to the next step. +TIP: It is recommended to keep this file around after the installation so that it can be reused when updating ODS Pipeline to future versions. -=== Using Helm to install from the Git repository +=== Step 2: Running the install script ==== Option 1: With external API access -If you have access to the OpenShift API from your local machine, you can simply login to the OpenShift cluster, then install ODS Pipeline by running: +If you have access to the OpenShift API from your local machine, simply login to the OpenShift cluster and install ODS Pipeline by running: [source] ---- @@ -61,8 +53,6 @@ IMPORTANT: If tasks need to trust a private certificate, pass `--private-cert > section. - ==== Option 2: Without external API access If you do not have access to the OpenShift API from your local machine, you can use the https://docs.openshift.com/container-platform/latest/web_console/odc-about-web-terminal.html[OpenShift Web Terminal] to install ODS Pipeline. Open a web terminal in your `*-cd` namespace, then run: @@ -72,48 +62,33 @@ If you do not have access to the OpenShift API from your local machine, you can curl -L https://raw.githubusercontent.com/opendevstack/ods-pipeline/master/scripts/web-terminal-install.sh | bash ---- -This will install all prerequisites automatically. Then you can clone the repository and run `./install.sh -n ` in the terminal. +This will install all prerequisites automatically. Then you can clone the repository and run `./install.sh -n `. `./install.sh` will interactively ask for credentials (such as Bitbucket access token) and will create corresponding K8s secrets. If you prefer to pass these secrets via flags, see `./install.sh --help` for all options. -After you ran the install script, continue with the <> section. - -==== Finishing the installation +=== Step 3: Exposing a route to the pipeline manager Create an HTTPS route to expose the `ods-pipeline` service. You'll need the exposed URL (together with the webhook secret that is stored in the `ods-bitbucket-webhook` K8s secret) when you create webhooks in Bitbucket repositories later. +Done, now you are ready to link:add-to-repository.adoc[enable your repositories to use ODS pipeline]! + IMPORTANT: The `pipeline` serviceaccount needs `admin` permissions in the Kubernetes namespaces it deploys to (e.g. `foo-dev` and `foo-test`). You must create rolebindings for this manually. CAUTION: An important feature of ODS Pipeline is to retain pipeline run artifacts in Nexus and re-use them future pipeline runs (e.g. to promote built container images to another environment). For this purpose, you should create a few `raw` repositories in Nexus. These repositories should not allow re-deployment of artifacts. For example, you might want to have `ods-pipeline-dev`, `ods-pipeline-qa` and `ods-pipeline-prod` repositories, each with a different cleanup policy as fitting your needs. You can then use these repositories from your pipeline to store artifacts and enforce a progression of artifacts from DEV > QA > PROD. -Now you are ready to link:add-to-repository.adoc[enable your repositories to use ODS pipeline]! == Update Instructions -The update procedure consists of two steps: +The update procedure consists of two quick steps: -1. Updating the Git repository defining the configuration of the ODS Pipeline installation -2. Using Helm to install from the Git repository +1. Updating the chart values if required +2. Running the install script (which will deploy the Helm chart) -=== Updating the Git repository +=== Step 1: Updating the chart values -You may fetch updates (e.g. new versions) of `ods-pipeline` like this: +Check if any new values have been introduced in `values.yaml.tmpl` and update your `values.yaml` (which you hopefully retained from the installation) accordingly. -[source] ----- -pipelineGitRef=v0.13.2 # Pick the version you want to update to - -git branch -D ods-pipeline-$pipelineGitRef subtree-split-branch-$pipelineGitRef || true && \ -git fetch --depth=1 https://github.com/opendevstack/ods-pipeline.git $pipelineGitRef:ods-pipeline-$pipelineGitRef && \ -git checkout ods-pipeline-$pipelineGitRef && \ -git subtree split --prefix=deploy -b subtree-split-branch-$pipelineGitRef && \ -git checkout - && \ -git subtree merge --prefix=deploy subtree-split-branch-$pipelineGitRef --squash ----- - -Afterwards, check if any new values have been introduced in `values.yaml.tmpl` and update `values.yaml` accordingly. Commit and push the result. - -=== Using Helm to install from the Git repository +=== Step 2: Running the install script ==== Option 1: With external API access @@ -126,8 +101,6 @@ If you have access to the OpenShift API from your local machine, you can simply TIP: You may also use `--dry-run` to see the changes first. -After you ran the script, continue with the <> section. - TIP: By default, the credentials stored in the K8s secrets will not be updated. If you want to make a change, pass any new values as flags to `install.sh` (see `./install.sh --help` for all options) or update the secrets manually. ==== Option 2: Without external API access @@ -142,7 +115,3 @@ curl -L https://raw.githubusercontent.com/opendevstack/ods-pipeline/master/scrip This will install all prerequisites automatically and update your ODS Pipeline installation to the latest state of your Git repository. TIP: The credentials stored in the K8s secrets will not be updated. If you need to change those, update them manually. - -==== Finishing the update - -Once the resources in your namespace are updated, you likely have to update the `ods.yaml` files in your repository to point to the new tasks, e.g. changing `ods-build-go-v0-12-0` to `ods-build-go-v0-13-2`.