puzzle/jenkins-techlab

Jenkins Pipeline Techlab

Jenkins Pipeline Techlab

This technical lab is a hands-on workshop. You learn how to use and write Jenkins pipelines in a continuous delivery perspective.

Content Sections

The training content resides within the content directory.

The main part are the labs, which can be found at content/en/docs.

Slides

Slides under reveal-slides will be generated during the build process and be available under slides/intro

To generate the slides during the development use:

./generateslides.sh

The slides will be generated in the public/slides/intro directory

Hugo

This site is built using the static page generator Hugo.

The page uses the docsy theme which is included as a Git Submodule. Docsy is being enhanced using docsy-plus as well as docsy-puzzle for brand specific settings.

After cloning the main repo, you need to initialize the submodule like this:

git submodule update --init --recursive

The default configuration uses the puzzle setup from config/_default. Further, specialized environments can be added in the config directory.

Docsy theme usage

• Official docsy documentation
• Docsy Plus

Update submodules for theme updates

Run the following command to update all submodules with their newest upstream version:

git submodule update --remote

Build using Docker

Build the image:

docker build -t puzzle/jenkins-techlab:latest .

Run it locally:

docker run -i -p 8080:8080 puzzle/jenkins-techlab

Using Buildah and Podman

Build the image:

buildah build-using-dockerfile -t puzzle/jenkins-techlab:latest .

Run it locally with the following command. Beware that --rmi automatically removes the built image when the container stops, so you either have to rebuild it or remove the parameter from the command.

podman run --rm --rmi --interactive --publish 8080:8080 localhost/puzzle/jenkins-techlab

How to develop locally

To develop locally we don't want to rebuild the entire container image every time something changed, and it is also important to use the same hugo versions like in production. We simply mount the working directory into a running container, where hugo is started in the server mode.

export HUGO_VERSION=$(grep "FROM klakegg/hugo" Dockerfile | sed 's/FROM klakegg\/hugo://g' | sed 's/ AS builder//g')
docker run \
  --rm --interactive \
  --publish 8081:8081 \
  -v $(pwd):/src \
  klakegg/hugo:${HUGO_VERSION} \
  server -p 8081 --bind 0.0.0.0

Access the local documentation: localhost:8081

Linting of Markdown content

Markdown files are linted with https://github.com/DavidAnson/markdownlint. Custom rules are in .markdownlint.json. There's a GitHub Action .github/workflows/markdownlint.yaml for CI. For local checks, you can either use Visual Studio Code with the corresponding extension (markdownlint), or the command line like this:

npm install
npm run mdlint

Npm not installed? no problem

export HUGO_VERSION=$(grep "FROM klakegg/hugo" Dockerfile | sed 's/FROM klakegg\/hugo://g' | sed 's/ AS builder//g')
docker run --rm --interactive -v $(pwd):/src klakegg/hugo:${HUGO_VERSION}-ci /bin/bash -c "set -euo pipefail;npm install; npm run mdlint;"

Github Actions

Build

The build action is fired on Pull Requests does the following

• builds all PR Versions (Linting and Docker build)
• deploys the built container images to the container registry
• Deploys a PR environment in a k8s test namespace with helm
• Triggers a redeployment
• Comments in the PR where the PR Environments can be found

PR Cleanup

The pr-cleanup action is fired when Pull Requests are closed and does the following

• Uninstalls PR Helm Release

Push Main

The push main action is fired when a commit is pushed to the main branch (eg. a PR is merged) and does the following, it's very similar to the Build Action

• builds main Versions (Linting and Docker build)
• deploys the built container images to the container registry
• Deploys the main Version on k8s using helm
• Triggers a redeployment

Helm

Manually deploy the training Release using the following command:

helm install --repo https://acend.github.io/helm-charts/  <release> acend-training-chart --values helm-chart/values.yaml -n <namespace>

For debugging purposes use the --dry-run parameter

helm install --dry-run --repo https://acend.github.io/helm-charts/  <release> acend-training-chart --values helm-chart/values.yaml -n <namespace>

Contributions

If you find errors, bugs or missing information please help us improve and have a look at the Contribution Guide.

jenkins-techlab's Issues

Scripted lab numbers

Change lab numbers of scripted labs in additional.
Use lab-10x.x
E.g use lab-109.1 instead of lab-9.3, which corresponds to lab-9.1.

update Jenkins version

10.3 Notification on failure

Es werden nur Rocket Chat Nachrichten gesendet wenn der Build successful war. Bei unstable oder failure werden keine Nachrichten versendet.

Change rocketchat example to something else

The rocketchat example fornotification does not work without the puzzle infrastructure.

Switch to using the maven plugin

Prerequisites

List lab prerequisites in 00_introduction

Lab 9.3 - Plugin Probleme

Lab 9.3 die installatione des pipeline maven plugin lässt sich nicht installieren da zuerst die beiden credentials und credentials-binding plugins aktualisiert werden müssen. Die Aktualisierung der Plugins schlägt aus unbekannten gründen fehl.

automatisches Testing für Jenkins

Nach Rücksprache mit @chrira soll für Jenkins ein Testing aufgebaut werden.
Dann könnten renovate PRs bezüglich jenkins Image updates automatisch gemerged werden.

Action Required: Fix Renovate Configuration

There is an error with this repository's Renovate configuration that needs to be fixed. As a precaution, Renovate will stop PRs until it is resolved.

Error type: Cannot find preset's package (github>whitesource/merge-confidence:beta)

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Repository problems

These problems occurred while renovating this repository. View logs.

• WARN: Fallback to renovate.json file as a preset is deprecated, please use a default.json file instead.

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• Update module github.com/google/docsy to v0.10.0

Ignored or Blocked

These are blocked by an existing closed PR and will not be recreated unless you click a checkbox below.

• Update module github.com/acend/docsy-plus to v1.1.0
• Update module github.com/google/docsy/dependencies to v0.7.2

Detected dependencies

docker-compose

local_env/docker-compose.yml

dockerfile

Dockerfile

• klakegg/hugo 0.111.3-ext-ubuntu
• ubuntu noble
• nginxinc/nginx-unprivileged 1.27-alpine

local_env/agent/Dockerfile

local_env/master/Dockerfile

ssh-honeypot/Dockerfile

github-actions

.github/workflows/build.yaml

• actions/checkout v4@692973e3d937129bcbf40652eb9f2f61becf3332
• actions/setup-node v4
• docker/setup-qemu-action v3
• docker/setup-buildx-action v3
• docker/login-action v3
• docker/build-push-action v6
• actions/upload-artifact v4
• azure/setup-helm v4
• azure/setup-kubectl v4
• marocchino/sticky-pull-request-comment v2

.github/workflows/pr-cleanup.yaml

• actions/checkout v4@692973e3d937129bcbf40652eb9f2f61becf3332
• azure/setup-helm v4
• azure/setup-kubectl v4

.github/workflows/push-main.yaml

• actions/checkout v4@692973e3d937129bcbf40652eb9f2f61becf3332
• actions/setup-node v4
• docker/setup-qemu-action v3
• docker/setup-buildx-action v3
• docker/login-action v3
• docker/build-push-action v6
• actions/upload-artifact v4
• azure/setup-helm v4
• azure/setup-kubectl v4

gomod

go.mod

• go 1.19
• github.com/acend/docsy-acend v1.0.0
• github.com/acend/docsy-plus v1.0.0
• github.com/google/docsy v0.4.0
• github.com/google/docsy/dependencies v0.4.0
• github.com/puzzle/docsy-puzzle v0.0.0-20230123144731-757054047a02@757054047a02

helm-values

helm-chart/values.yaml

npm

package.json

• husky 9.1.4
• markdownlint-cli 0.41.0

reveal-slides/package.json

• reveal-md ^6.0.0

---

• Check this box to trigger a request for Renovate to run again on this repository

enable renovate-bot

add renovate.json

update presentation

new structure:

1. Agenda (cra)

• update

3. CI/CD (cra)

• image promotion
• config by env

4. why pipelines (cra)

• generally
• Jenkins-pipelines

5. Jenkins overview (cbl)

• Jenkins history (swe/projects/PITC_Puzzle_ITC/APPU_APPUiO/03_Praesentationen/18_AMM_Techlab/04_CICD_on_OpenShift_3.0.odp)
• Architektur
  • scaling information up to date?
• Groovy. Declarative vs. Scripted, what runs where
  • language is Groovy with Jenkins DSL
  • what gets executed where and when (master, slave)?
  • scripted is deprecated (use script block if variables are needed)
• Tools:
  • Tools @ Puzzle weg (ausblenden)
  • Tools: standard, by plugin, CustomTool
  • Custom Tools ( custom-tools-plugin) This plugin is up for adoption!
  • Docker Agents (docker plugin)
• Best Practices
  • add Workspace cleanup
  • re-use workflow for similar projects
  • example for every Best Practice
  • where to find help

6. remove Puzzle Setup
7. explain Docker Setup
8. update Objectives

• kind of implementations?

remove old slides

Remove reveal-js slides and gh-pages.

• do not build gh-pages (remove configuration and branch)
• remove slides folder: reveal-slides/
• remove link: content/en/slides/_index.en.md

The techlab can not be completed without access to puzzle infrastructure

The techlab can not be completed without access to puzzle infrastructure.
I used a local installation. It would make sense to rewrite the techlab so it can be done by anyone.

Things which can not be done in a local install are:

• rocketchat integration
• openshift integration

Lab 15.1 Replace Ruby Image

Replace Ruby Image with puzzle internal images (registry.puzzle.ch/docker.io/ruby:)

Lab-9 no automatic git checkout in scripted pipeline

I think this difference between scripted and declarative pipelines should be mentioned in the beginning (maybe lab 2)

Improve Node.js Lab

Add additional Node.js lab with tests and artifact archiving.

Fail Jenkins job with OCP problems

Fail Build:

        stage('build application') {
            steps {
                script {
                    openshift.withCluster(env.OPENSHIFT_CLUSTER) {
                        openshift.withCredentials(env.OPENSHIFT_CREDENTIALS) {
                            openshift.withProject(env.OPENSHIFT_PROJECT) {
                                echo "Hello from project ${openshift.project()} in cluster ${openshift.cluster()}"
                                def bcSelector = openshift.selector("BuildConfig", [ app : env.APP_LABEL ]) // select build
                                def build = bcSelector.startBuild()
                                def result = build.logs('-f')
                                ctx.echo("oc startBuild action: ${result.actions[0].cmd}")
                                ctx.echo("oc startBuild status: ${result.status}")
                                if (build.object().status.phase == 'Failed') {
                                    ctx.fail("openshift build ${build.object().metadata.name} failed")
                                }
                            }
                        }
                    }
                }
            }
        }

Add Build timeout to OpenShift Build and add same timeout to Build Stage in Jenkins.

Add same behavior to apply and rollout

Adding java to path does not work

Setting and referencing a environment variable in the same withEnv() statement does not seem to work. This is used in lab-08 and all following labs.

Example:

node() {
    withEnv(["JABBA_HOME=/nal_hutta", "PATH+JABBA=${env.JABBA_HOME}"]) {
        stage('Build') {
            sh 'echo $PATH && echo $JABBA_HOME'
        }
    }
}

Add Features

• show script approval
• show stage conditions: https://www.jenkins.io/doc/book/pipeline/syntax/#when
• call parameterized jobs from other jobs
• show Puzzle Share Library and make an advanced lab to use some features of it:
  https://github.com/puzzle/jenkins-pipeline-shared-libraries
• Setting Build Resources
• Git clone secret

lab test on windows

Check setup for using the lab on windows.

create new OpenShift Jenkins workflow lab

Show integration and promotion according to: https://github.com/chrira/techlab/blob/lab-4-jenkins/additional-labs/jenkins.md

• no Jenkins Deployment on OCP
• no Jenkins BC
• add SA for accessing project from external Jenkins

Lab 12.2 Check artifact on SSH server

docker command does not work, tried alternatives:
sudo docker exec -u puzzler openssh-server bash and sudo docker exec -it -u puzzler openssh-server bash
either did not work.
Errors:
sudo docker exec -u puzzler openssh-server bash
[sudo] password for ela:
OCI runtime exec failed: open /tmp/runc-process569058889: read-only file system: unknown

sudo docker exec -it -u puzzler openssh-server bash
failed to create runc console socket: mkdir /tmp/pty498703440: read-only file system: unknown

Error when using OG docker command
sudo docker-compose -f local_env/ssh-server-compose.yaml exec -u puzzler openssh-server bash
failed to create runc console socket: mkdir /tmp/pty2571181478: read-only file system: unknown

change presentation to hugo

render lab with hugo

The lab OpenShift Integration is outdated

It references the jenkns build strategy in openshift, which as far as I know is deprecated.

explain multibranch pipelin

In presentation or in lab.
Explain what it is for and what it creates (jobs for branches)
Job config is only read-only (comes from Jenkinsfile)

Document access to private git repo

Add hint to create Access Token in Git repo and how to configure a credential for the pull when creating the multibranch pipeline.

Improve Lab-08 Tools

There are a few thing that could be improved about this lab:

• explain what the default tool are and how to use them first
• then explain the reason why we use custom tools
• add a link to jenkins tutorials with docker agents as alternative for custom tool

local-env Setup

Start whole test environment with the docker-compose file.

Windows folder permissions hint

Add hint for Docker folder access permissions.
Local volume

Is the strong focus on the scripted pipelines necessary?

Almost every lab has a declarative and srciped section. In many of the labs there are no differences (the scripted one feels like just another syntax). This feels a bit repetitive. Furthermore the real differences between scripted and declarative are never explained (only mentioned here and there).

I would suggest:

• Make a section early describing the differences between declarative and scrippted:
  • What does the script block do?
  • No automatic checkout of source control.
  • ...
• In the following chapters only mention the scripted pipeline if there are important differences.
• Move the examples of the scripted pipelines into a folder (similar to the exercise solutions)

Improve Ruby Lab

Add additional Ruby lab with tests and artifact archiving.