Initial migration from kangasta/jenkins-examples

Author: kangasta

.gitattributes

@@ -0,0 +1,2 @@
+* text=auto
+*.sh text eol=lf

.github/workflows/deploy.yml

@@ -0,0 +1,31 @@
+name: Deploy
+on:
+  push:
+    branches:
+    - main
+
+jobs:
+  deploy-pages:
+    name: Deploy to pages
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+    - uses: actions/setup-python@v2
+      with:
+        python-version: "3.12"
+    - name: Install dependencies
+      run: |
+        pip install -r requirements.txt
+    - name: Build site
+      run: |
+        mkdocs build
+        touch site/.nojekyll
+    - name: Deploy to pages
+      uses: JamesIves/github-pages-deploy-action@3.7.1
+      with:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        BRANCH: gh-pages
+        FOLDER: site
+        CLEAN: true

.gitignore

@@ -0,0 +1 @@
+site/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Toni Kangas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,4 @@
+# CI/CD Examples
+
+Examples on how to develop CI/CD pipelines and how to configure development environment for working with CI/CD pipelines.
+

examples/docker/docker-on-wsl.md

@@ -0,0 +1,148 @@
+# Docker on WSL
+
+If you do not already have Windows Subsystem for Linux (WSL) installed, see [Install Linux on Windows with WSL](https://docs.microsoft.com/en-us/windows/wsl/install) for instructions.
+
+This document describes how to configure WSL 2, install recent version of Ubuntu (24.04 LTS), and install Docker as well as Docker compose.
+
+## Configure WSL settings
+
+Open PowerShell and check current WSL status by running `wsl --status`.
+
+```pwsh
+wsl --status
+```
+
+If default version is not 2, run `wsl --set-default-version 2`. This enables more recent, virtual machine based WSL, that is required for us to be able to run Docker daemon in the WSL.
+
+```pwsh
+wsl --set-default-version 2
+```
+
+If output indicates any problems with WSL 2 Kernel, such as `The WSL 2 kernel file is not found.`, run `wsl --update` and `wsl --shutdown`, as suggested. These command might require admin priviledges. To obtain these, find PowerShell, right click it, and select _Run as System Administrator_.
+
+```pwsh
+wsl --update
+wsl --shutdown
+```
+
+Run `wsl --status` again. The output should display 2 as default version, recent last update date, and kernel version.
+
+If you already have recent version of Ubuntu installed, ensure that it uses WSL 2 by running `wsl --list --verbose`. If necessary, use `wsl --set-version` to update your instance to use WSL 2. Skip next section.
+
+```pwsh
+wsl --list --verbose
+wsl --set-version "YOUR_DISTRO_HERE" 2
+```
+
+## Install recent version of Ubuntu
+
+Install recent version of Ubuntu from either Microsoft Store or PowerShell. These instructions use Ubuntu 22.04. Other distributions might also work, if you know what you are doing.
+
+If you want to install distro through the PowerShell, run `wsl --list --online` and follow the instructions.
+
+```pwsh
+wsl --list --online
+wsl --install -d Ubuntu-24.04
+```
+
+If you want to install distro through Microsoft Store: Open Microsoft Store, search for `Ubuntu 22`, select _Ubuntu 22.04 LTS_, and click _Install_.
+
+If not opened automatically, open the installed Ubuntu distro and follow instruction in installation wizard.
+
+## Install Docker
+
+Open Ubuntu you just installed and follow [Install Docker Engine on Ubuntu](https://docs.docker.com/engine/install/ubuntu/) instructions.
+
+__tl;dr:__ Run the convenience script available in `get.docker.com`:
+
+```bash
+curl -fsSL https://get.docker.com -o get-docker.sh
+sudo sh get-docker.sh
+```
+
+Ignore the `WSL DETECTED: We recommend using Docker Desktop for Windows.` warning.
+
+To be able to run docker commands without `sudo`, add current user to `docker` group with `usermod`. Note that you might have to logout and login for the changes to take effect.
+
+```bash
+sudo usermod -aG docker $USER
+```
+
+## Configure networking
+
+By default, WSL 2 uses local DNS server to reflect network settings, such as VPN, from the host Windows to WSL instances. The IP address of this DNS server might fall into IP range used by the Dockers default bridge network. In that case, containers will not be able to resolve domains.
+
+To configure working DNS inside containers you can either use public DNS or modify IP range used by Dockers default network. If you are working behind a corporate firewall, public DNS might not work.
+
+=== "Use public DNS in WSL 2"
+
+    To use public DNS, you must first disable WSL from automatically generating DNS settings to `/etc/resolv.conf`. To do this, add following rows to `/etc/wsl.conf` file in your WSL instance, for example, by editing (or creating) it with `sudo nano /etc/wsl.conf`:
+
+    ```conf
+    [network]
+    generateResolvConf = false
+    ```
+
+    For the changes to take effect, restart WSL by running `wsl --shutdown` in powershell and launching WSL instance again.
+
+    ```pwsh
+    wsl --shutdown
+    ```
+
+    Finally, configure DNS server manually by creating `/etc/resolv.conf` with following content, for example by opening it with `sudo nano /etc/resolv.conf`:
+
+    ```conf
+    nameserver 8.8.8.8
+    ```
+
+=== "Configure IP range for Docker"
+
+    To configure Docker to use IP ranges that wont overlap with DNS server configured by WSL, add following content to `/etc/docker/daemon.json`, for example, by opening it with `sudo nano /etc/docker/daemon.json`:
+
+    ```json
+    {
+      "bip": "172.21.0.1/16",
+      "default-address-pools": [
+        {
+          "base":"172.22.0.0/16",
+          "size":24
+        }
+      ]
+    }
+    ```
+
+    If you already have dockerd running, you have to restart it for the changes to take effect.
+
+    ```bash
+    sudo service docker restart
+    ```
+
+    If containers cannot resolve domains with above configuration, ensure that the above networks do not overlap with the DNS server configured by WSL by running `ipconfig` in powershell and checking the networks it outputs.
+
+## Start Docker daemon
+
+Start `dockerd` as a background process by using `service` or, alternatively, start `dockerd` directly.
+
+```bash
+sudo service docker start
+```
+
+Note that this must be done every time WSL is restarted. If `docker` commands print `Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?` error, run `sudo service docker status` command to check if `dockerd` is running and, if necessary, run `sudo service docker start` command again.
+
+If you are working on Windows 11, you can use [boot settings](https://docs.microsoft.com/en-us/windows/wsl/wsl-config#boot-settings) to start Docker daemon automatically on WSL instance startup. To do this, add following rows to `/etc/wsl.conf` file in your WSL instance, for example, by editing (or creating) it with `sudo nano /etc/wsl.conf`.
+
+```conf
+[boot]
+command = service docker start
+```
+
+## Install Docker compose
+
+Follow [Install Docker Compose](https://docs.docker.com/compose/install/) instructions for Linux.
+
+__tl;dr:__ Install Docker Compose with the distros package manager:
+
+```bash
+sudo apt-get update
+sudo apt-get install docker-compose-plugin
+```

examples/index.md

@@ -0,0 +1,11 @@
+# CI/CD Examples
+
+This website contains examples on how to develop CI/CD pipelines and how to configure development environment for working with CI/CD pipelines.
+
+## Installing Docker
+
+See [Get Docker](https://docs.docker.com/get-docker/) for installation instructions.
+
+If you use Docker a lot on Mac or Windows system, the recommended Docker Desktop is likely a good option for you. Note that, since January 2022, it has required paid subscription if used for commercial development.
+
+Alternatively, Windows users can [install Docker on top of WSL2](./docker/docker-on-wsl/). For Mac users there are alternatives, such as [Colima](https://github.com/abiosoft/colima), available.

examples/jenkins/ansible-kubernetes/Dockerfile

@@ -0,0 +1,7 @@
+FROM python:3.12
+
+RUN pip install ansible kubernetes && \
+    apt update && \
+    apt install jq -y && \
+    curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl" && \
+    install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

examples/jenkins/ansible-kubernetes/Jenkinsfile

@@ -0,0 +1,29 @@
+pipeline {
+    agent any
+    parameters {
+        choice(name: 'ANIMAL', choices: ['cat', 'cow', 'dog', 'lion', 'pig'], description: 'Tag to use for deployment image')
+    }
+    stages {
+        stage("deploy") {
+            agent {
+                dockerfile {
+                    dir "ansible-kubernetes"
+                    reuseNode true
+                }
+            }
+            environment {
+                K8S_AUTH_KUBECONFIG = credentials('kubeconfig')
+            }
+            steps {
+                sh """
+                    ansible-playbook ansible-kubernetes/deploy-to-kubernetes.yml --extra-vars "animal=${params.ANIMAL}"
+                """
+                // Do not use Groovy string interpolation for credential
+                sh '''
+                    export KUBECONFIG=$K8S_AUTH_KUBECONFIG
+                    ./ansible-kubernetes/wait-until-service-up.sh
+                '''
+            }
+        }
+    }
+}

examples/jenkins/ansible-kubernetes/README.md

@@ -0,0 +1,32 @@
+# Deploy application to Kubernetes with Ansible
+
+This example contains a pipeline that deploys an simple hello-world application to a Kubernetes cluster.
+
+## Prerequisites
+
+You will need a running Kubernetes cluster, that supports services with `LoadBalancer` type, and a kubeconfig file that can be used to deploy application (a deployment and a service) into the cluster.
+
+## Preparing the Jenkins instance
+
+The pipeline provided by this example can be added to any Jenkins instance you have administrator access and can run pipeline stages with docker agent. For example, Jenkins configuration from [Docker-in-Docker](../dind-jenkins/) example can be used.
+
+We will use secret file to configure credentials for managing the target Kubernetes cluster. To create the secret file credential, open _Global credentials_ from _Jenkins_ credentials store from [Manage Jenkins > Manage Credentials](http://localhost:8080/credentials/) and click _Add Credentials_ from the left side menu.
+
+In the _New credentials_ form:
+
+1. Select _Secret file_ as the credential _kind_
+2. Upload your kubeconfig to the _file_ input
+3. Configure _ID_ for the credential. [Jenkinsfile](./Jenkinsfile) uses `kubeconfig` as the ID.
+4. (Optionally) add a description.
+
+## Configure the pipeline
+
+First, create a new pipeline via [New Item](http://localhost:8080/view/all/newJob) button in the rigth side menu of the Jenkins dashboard. The name of the pipeline could be for example `Animals` and it should be an pipeline.
+
+In the configure pipeline view, scroll to the bottom and under Pipeline sub-header select `Pipeline script from SCM`. SCM type should be `Git` and Repository URL the url of this repository: `https://github.com/kangasta/jenkins-examples.git`. Ensure that branch specifier includes `main` branch of the repository and modify the Script Path to be `ansible-kubernetes\Jenkinsfile`.
+
+After you have created the pipeline, try to execute it by clicking _Build Now_. The pipeline should have deployed the example application into the Kubernetes cluster with the default image tag (`cow`) defined in the [deploy-to-kubernetes.yml](./deploy-to-kubernetes.yml) Ansible playbook.
+
+You can find the URL of the created load-balancer from the console output of the build. Open the application with your browser or user curl to see the application response.
+
+In addition, after the first execution Jenkins should have updated the project configuration to contain parameters defined in the pipeline and we can configure the image tag in _Build with Parameters_ menu.