Skip to content

Latest commit

 

History

History
78 lines (46 loc) · 5.38 KB

installation.adoc

File metadata and controls

78 lines (46 loc) · 5.38 KB
Raw

Installation Guide

Table of Contents

This guide will show how to install ODS Pipeline in an existing ODS project. It is possible to use ODS Pipeline and the classic Jenkins CI/CD setup side by side.

An ODS Pipeline installation consists of the following resources:

  • 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/Kubernetes cluster (such as foo-cd from an existing ODS project) and a project in Bitbucket (such as FOO).

  • oc (or kubectl) and helm installed locally. The plugin helm-diff is optional but recommended.

Installation Instructions

ODS Pipeline is packaged as a Helm chart. The installation procedure consists of three quick steps:

  1. Configuring the chart values

  2. Running the install script (which will deploy the Helm chart)

  3. Exposing a route to the pipeline manager

Step 1: Configuring the chart values

Download the template and fill in the values according to the comments in that file.

curl -fsSL https://raw.githubusercontent.com/opendevstack/ods-pipeline/v0.15.0/deploy/values.yaml.tmpl -o values.yaml

Step 2: Running the install script

Login to the OpenShift cluster in your terminal, then run the following from the same directory that the values.yaml file is located in:

curl -fsSL https://raw.githubusercontent.com/opendevstack/ods-pipeline/v0.15.0/deploy/install.sh | bash -s -- -n=<your_cd_namespace>

The script 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, use --help to see all options.

Important
 If tasks need to trust a private certificate, pass --private-cert=<host>. This will create a K8s secret containing the certificate from the specified host, which will then be mounted in pods during task runs.
Tip
 If you want to review the changes first before applying them, supply --dry-run.
Tip
 If you do not have access to the OpenShift API from your local machine, you can use the OpenShift Web Terminal. Open a web terminal in the target namespace and make sure the values.yaml file is present in the working directory there. Then run the installation script as described above. Note that you must either install the helm-diff plugin using helm plugin install https://github.com/databus23/helm-diff --version "v3.3.2" beforehand or supply --no-diff when running the install script.

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 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.

Update Instructions

To update ODS Pipeline, simply run the install script again (using the new version tag that you want to install). Login to the OpenShift cluster in your terminal, then run:

curl -fsSL https://raw.githubusercontent.com/opendevstack/ods-pipeline/v0.15.0/deploy/install.sh | bash -s -- -n=<your_cd_namespace>
Important
 Previous Helm chart values will be reused. If the release notes mention any new or changed Helm chart values, you have to pass those to the install script using --set key1=val1,key2=val2.
Tip
 If you want to review the changes first before applying them, supply --dry-run.
Tip
 If you do not have access to the OpenShift API from your local machine, you can use the OpenShift Web Terminal. Open a web terminal in the target namespace and make sure the values.yaml file is present in the working directory there. Then run the installation script as described above. Note that you must either install the helm-diff plugin using helm plugin install https://github.com/databus23/helm-diff --version "v3.3.2" beforehand or supply --no-diff when running the install script.