Skip to content

Latest commit

 

History

History
411 lines (277 loc) · 15.3 KB

README.adoc

File metadata and controls

411 lines (277 loc) · 15.3 KB
Raw

OpenShift Pipelines

1. Introduction

Red Hat OpenShift Pipelines is a cloud-native, continuous integration and continuous delivery (CI/CD) solution based on Kubernetes resources. It uses Tekton building blocks to automate deployments across multiple platforms by abstracting away the underlying implementation details.

What do we understand as Cloud Native CI/CD?

  • Containers: Built for container apps and runs on Kubernetes.

  • Serverless: Runs serverless with no CI/CD engine to manage and maintain.

  • DevOps: Designed with microservices and distributed teams in mind.

To get more details, you can check the official documentation.

2. TL;DR Full Installation

ℹ️
 This repository has been fully migrated to the GitOps pattern. This means that it is strongly recommended to deploy ArgoCD in order to deploy these components in an standard way. You can install GitOps using this repository.

As this is a public repo, it is not possible to upload all the credentials freely to the git repository. For that reason, the following script will install the Pipelines operator and configure it. After that, it will configure Grafana dashboards if Grafana is installed and create the appropriate secrets to access all the resources. Please, execute the following script:

./auto-install.sh
❗

This task still lacks the configuration of the secrets. For that, you will need to create the secrets directory and add your secrets in there. Check:

  • the following section and create the files, but don’t apply the resources to the cluster.

  • the annex C to create the entitlements for builds. Don’t apply the resources to the cluster.

This is the folder structure you should have after configuring the secrets:

secrets/
├── entitlement-key.pem
├── entitlement.pem
├── git-secret-ssh.yaml
├── kustomization.yaml
├── quay-alopezme-pull-secret.yaml
└── rh-registry-sa.yaml

The content of the kustomization.yaml should be:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namespace: ocp-pipelines

resources:

  # Red Hat Registry
  - rh-registry-sa.yaml

  # Quay Robot Account
  - quay-alopezme-pull-secret.yaml

  # Git repositories
  - git-secret-ssh.yaml


secretGenerator:
  - name: etc-pki-entitlement
    files:
      - entitlement-key.pem
      - entitlement.pem
    options:
      disableNameSuffixHash: true

3. Secrets for authentication

In many practical use cases, you might need to pull from private Git repositories or might need to push to an external container registry such as Quay.io. In this section, we will summarize how to create the Secrets to configure all the credentials.

3.1. Red Hat Registry

To use the registry.redhat.io registry, you have to have a Red Hat login. To consume container images from registry.redhat.io in shared environments such as OpenShift, it is recommended for an administrator to use a Registry Service Account, also referred to as authentication tokens, in place of an individual’s Customer Portal credentials.

The management of Service Accounts is available via the Registry Service Account management application.

apiVersion: v1
kind: Secret
metadata:
  name: $SECRET_NAME
data:
  .dockerconfigjson: $DOCKER_CONFIG_FILE_CONTENT
type: kubernetes.io/dockerconfigjson

Once you create the file with its contents, you can apply it to the cluster like this:

oc apply -f secrets/rh-registry-sa.yaml -n ocp-pipelines
oc secrets link -n ocp-pipelines pipeline rh-registry-sa

For more information, check the full KCS article.

3.2. Git repository

To clone a private repository in the pipeline, the pipeline Service Account will need to be able to authenticate against the repository. There are two main options to get this authentication: Using a username+token (Or a PAT if using GitHub) or using an SSH private key.

Option 1: Create Secret with SSH Private Key
oc create secret generic git-secret-ssh --type=kubernetes.io/ssh-auth --from-file=ssh-privatekey=$LOCATION_PRIVATE_KEY -n pipelines
oc annotate secret git-secret-ssh tekton.dev/git-0="$GIT_PRIVATE_URL"
oc secrets link -n ocp-pipeline pipeline git-secret-ssh
Option 2: Create Secret with GitHub PAT token
oc create secret generic gh-pat-secret -n ocp-pipelines  \
    --type=kubernetes.io/basic-auth \
    --from-literal=username=$GITHUB_USERNAME \
    --from-literal=password=$GITHUB_PAT
oc annotate secret gh-pat-secret tekton.dev/git-0="$GIT_PRIVATE_URL"
oc secrets link -n ocp-pipelines pipeline gh-pat-secret

For more information about the PAT creation and configuration, you can follow the instructions that we have in the following workshop guidelines.

3.3. Quay Robot Account

Robot accounts are a way to access repositories without requiring a human user account. A robot account has its own credentials, generated by Quay and linked to an Organization. To create a Robot Account and get its credentials, you have to access the Quay web console. For this repository, we are going to use my personal Quay organization, which is located at: https://quay.io/user/alopezme.

Quay robot accounts dashboard
Figure 1. Quay robot accounts dashboard

Using an admin account, you can access the organization, go to the Robot Accounts section and click on Create Robot Account. After creating the Account, click on it to directly download the Kubernetes secret definition that you have to apply in your namespace.

Once you create the file with its contents, you can apply it to the cluster like this:

oc apply -f secrets/quay-alopezme-pull-secret.yaml -n ocp-pipelines
oc secrets link -n ocp-pipelines pipeline quay-alopezme-pull-secret

For more information, you can access the documentation of the on-premise installation of Quay.

4. Monitoring

If you have Grafana installed in the cluster, you can create the following Dashboards to monitor the status of the pipeline’s execution. There are two dashboards obtained from different sources:

In general, Tekton has several relevant metrics. All of them are detailed in the upstream documentation.

5. Useful Tasks and Pipelines

5.1. Tasks

This section contains several tasks that can be useful for the pipelines.

Task New Description

List Files

✔️

List files from a mounted workspace.

Download release

✔️

Download the latest release of a GitHub release from a given organization/repository.

chmod

✔️

Change permissions of a file

Skopeo Copy

❌

Patched version of the Skopeo copy task. The feature to bulk-copy several images in the same Pipeline execution is currently affected by this bug.

Buildah Entitlements

❌

Patched version of the Buildah task where the Task also mounts the etc-pki-entitlements secret with the full entitlements of SCA.

5.2. Pipelines

Pipeline Description

Copy image

Copy one container image from one container repository to another.

Bulk copy images

Copy several images listed in a ConfigMap from one container repository to another.

Build image

This pipeline builds an image by cloning a git repo and building the image using its Dockerfile and the default buildah task.

Build image with entitlements

This pipeline modifies the default buildah task to mount the etc-pki-entitlements and be able to install every package present in a repository that your organization has access to.

Build image Download

This pipeline also builds a container image and includes a binary downloaded from the GH releases section of any repository (By default, it installs kustomize).

Copy entitlements

Pipeline that copies the etc-pki-entitlements secret from the openshift-config-managed to the selected namespace.

6. Running pipelines

Copy images from one repo to another
oc create -f pipelineruns/11-copy-image.yaml
Bulk Copy images from one repo to another
oc create -f pipelineruns/12-copy-bulk-images.yaml
Clone repo and build image
oc create -f pipelineruns/21-build-image.yaml
Clone repo and build image with RHEL entitlements
oc create -f pipelineruns/22-build-image-entitlements.yaml
Clone repo, download binary and build an image with RHEL entitlements
oc create -f pipelineruns/31-copy-entitlements.yaml

6.1. Copy entitlements

Copy Entitlements Secret to current project
oc create -f pipelineruns/23-build-image-download.yaml

If you don’t want to use the previous pipeline, you can do it manually with the following command:

Copy Entitlements Secret to current project
oc get secret etc-pki-entitlement -n openshift-config-managed -o yaml | yq 'del(.metadata.creationTimestamp, .metadata.uid, .metadata.resourceVersion, .metadata.namespace, .metadata.managedFields)' | oc create -n pipelines -f -

7. Triggers

Triggers capture external events, such as a Git pull request, and process them to extract key pieces of information. Triggers consist of four different CRDs that work together:

  • The TriggerBinding resource extracts the fields from an event payload and stores them as parameters.

  • The TriggerTemplate resource acts as a standard for the way resources must be created.

  • The Trigger resource combines the TriggerBinding and TriggerTemplate resources, and optionally, the interceptors event processor.

  • The EventListener resource provides an endpoint or an event sink, that listens for incoming HTTP-based events with a JSON payload.

We have an example using a CronJob to automatically trigger the Pipeline every morning.

Annex A: Installing Tekton CLI

To get the most out of Openshift Pipelines, you will need to download and install the tkn command line tool. You can download it from the Tekton documentation or directly from your Openshift cluster:

Download tkn cli
Figure 2. Download tkn cli

Annex B: Tutorial

If you want a tutorial to learn Openshift Pipelines, I recommend you this tutorial from Red Hat Scholars.

Annex C: Default ClusterTasks

The Openshift Pipelines Operator configures several ClusterTasks by default. Here you can find a summary of them for documentation purposes:

$ tkn clustertasks list
NAME                        DESCRIPTION              AGE
argocd-task-sync-and-wait   This task syncs (de...   2 days ago
buildah                     Buildah task builds...   2 days ago
git-cli                     This task can be us...   2 days ago
git-clone                   These Tasks are Git...   2 days ago
helm-upgrade-from-repo      These tasks will in...   2 days ago
helm-upgrade-from-source    These tasks will in...   2 days ago
jib-maven                   This Task builds Ja...   2 days ago
kn                          This Task performs ...   2 days ago
kn-apply                    This task deploys a...   2 days ago
kubeconfig-creator          This Task do a simi...   2 days ago
maven                       This Task can be us...   2 days ago
openshift-client            This task runs comm...   2 days ago
pull-request                This Task allows a ...   2 days ago
s2i-dotnet                  s2i-dotnet task fet...   2 days ago
s2i-go                      s2i-go task clones ...   2 days ago
s2i-java                    s2i-java task clone...   2 days ago
s2i-nodejs                  s2i-nodejs task clo...   2 days ago
s2i-perl                    s2i-perl task clone...   2 days ago
s2i-php                     s2i-php task clones...   2 days ago
s2i-python                  s2i-python task clo...   2 days ago
s2i-ruby                    s2i-ruby task clone...   2 days ago
skopeo-copy                 Skopeo is a command...   2 days ago
tkn                         This task performs ...   2 days ago
trigger-jenkins-job         The following task ...   2 days ago

Annex D: Retrieve the etc-pki-entitlement secret

In some cases, the Insights Operator cannot retrieve the etc-pki-entitlement secret correctly. In such cases, it is possible to download the certificate from the Red Hat management console. If this is your case…​

>> Click Here <<

Annex E: Run Tekton Pipelines on Quay Image Mirroring Notifications

In this section, we are going to explore the proposal by siamaksade in Red Hat’s Blog: Keep Your Applications Secure With Automatic Rebuilds and in his GitHub repository quay-mirror-pipeline. For more information:

>> Click Here <<