backup.md

Mendix Azure-Jenkins-Kubernetes CI/CD Reference Implementation

The Mendix Azure-Jenkins-Kubernetes CI/CD Reference Implementation is a reference implementation for running a cluster of Mendix runtime instances by setting up a Kubernetes cluster on Azure. The Kubernetes cluster will use Docker containers built using the Mendix Docker buildpack. The build and deployment of containers on the cluster is orchestrated using Jenkins.

We also have a Reference Implementation available using Microsoft Visual Studio Team Services as CI/CD platform. This implementation is described here

Components

The reference implementation uses the following components:

• Infra: Azure (Container Services)
• Docker Cluster Orchestration: Kubernetes
• CI/CD platform: Jenkins
• Mendix Docker Build Pack

The flow is to run a Jenkins Master containerized in a Kubernetes cluster which spawns temporary Jenkin build slaves in seperate containers for executing Mendix building jobs (using the Mendix build pack). The compiled container image is stored in a registry and can subequently be used to deploy app nodes to the Kubernetes cluster.

Prerequisites

• Azure Account with Owner role in the subscription on which the cluster will be deployed
• Azure CLI 2.0

How to set it up

Part 1 - Setting up the Kubernetes cluster on Azure

1. Clone this repository using:

git clone https://github.com/mendix/azure-kubernetes-cicd-reference-impl

2. Install the Azure CLI 2.0.
3. Login to Azure using:

az login

4. Download and modify the environment variables in the acsmxcluster.sh shell script to match your needs.
5. Execute the acsmxcluster.sh shell script to setup the cluster. This can take up to 20 minutes.

./acsmxcluster.sh

Part 2 - Install and configure Jenkins on the cluster

1. Open the shell you used to setup the cluster. Install Jenkins by running:

kubectl create -f jenkins/jenkins-master-manual.yaml

2. Run the following command to create a tunnel to the Kubernetes Dashboard

kubectl proxy

3. Access the Kubernetes Portal by browsing to http://localhost:8001
4. Open the Jenkins namespace by selecting it on the left of your screen.
5. Select the "Services" page under "Services and discovery". Use the top URL to open Jenkins.
6. Jenkins will ask for the initial Administrator password to unlock itself.
7. Retrieve the initial password from the pod log in the Kubernetes Dashboard. Select Workloads -> Pods -> Jenkins- -> View logs and search for the following section:
8. Copy the initial password into Jenkins to start the initial setup.
9. Install the suggested plugins and create an admin user.
10. Jenkins might occassionally raise the folllowing error due to the port forwarding setup used in the cluster: To fix it: turn Proxy Compatibility on (Manage Jenkins -> Configure Global Security –> Enable Proxy Compatibility) Setting the option might take a few tries of running into the error.

11. Install the Kubernetes plugin for Jenkins: Manage Jenkins -> Manage Plugins -> Available >
12. Add a new configuration for the Kubernetes Cloud: Manage Jenkins -> Configure System -> Add a new cloud -> Kubernetes
13. Add a pod template & container configuration for the Jenkins Build Slaves:
14. Set Jenkins not to build on the master: Manage Jenkins -> Configure System -> Usage = Only build jobs with label expressions matching this node
15. Setup a new pipeline: Create new Job > Pipeline > Enter the pipeline script Pipeline script:

node {
    stage('Get Mendix Build Pack') {
        git 'https://github.com/mendix/docker-mendix-buildpack'
    }
    stage('Retrieve project from team server') {
        checkout([$class: 'SubversionSCM', additionalCredentials: [], excludedCommitMessages: '', excludedRegions: '', excludedRevprop: '', excludedUsers: '', filterChangelog: false, ignoreDirPropChanges: false, includedRegions: '', locations: [[credentialsId: 'mxteamserver', depthOption: 'infinity', ignoreExternalsOption: true, local: 'project', remote: 'https://teamserver.sprintr.com/<project- ID>/trunk']], workspaceUpdater: [$class: 'UpdateUpdater']])
    }
    
    
    stage('Build project & push image') {
      docker.withServer('unix:///var/run/docker.sock') {
        docker.withRegistry('https://index.docker.io/v1', 'dockerregistry')   {
          def image = docker.build("mxproject/companyexpenses:latest", '--build-arg BUILD_PATH=project .')
          withCredentials([[$class: 'UsernamePasswordMultiBinding', credentialsId: 'dockerregistry',
          usernameVariable: 'USERNAME', passwordVariable: 'PASSWORD']]) {
            sh 'docker login -u "$USERNAME" -p "$PASSWORD"';
            image.push();
            }
          }
        }
     }
}

15. Add credentials to access the team server to Jenkins (Credentials->System->Global credentials->Add Credentials, use ID: teamserver)

16. Add credentials to access a docker registry to Jenkins (Credentials->System->Global credentials->Add Credentials, use ID: dockerregistry)

*Do not forget to set the correct URL for your Docker Registry and Subversion repository in the pipeline script *

17. Execute the pipeline by clicking "Build now". Your project should now automatically be checked out from the team server and subsequently build. The resulting Docker Image is then pushed to the registry for storage.

Part 3 - Deploy a database on Azure

Your Mendix app needs a database to store persistent data. In this how-to we will use an Azure SQL Database for this purpose. This database can be created via the Azure Portal:

Do not forget to note the server admin login username and password chosen during database server creation, we will need those later

Part 4 - Creating a deployment pipeline

Now everything is in place to create our deployment pipeline:

1. Install the Configuration File Provider plugin via Manage Jenkins > Manage Plugins and restart Jenkins.

2. Get the cluster credentials by typing the following command on the shell you used to create the cluster above:

az acs kubernetes get-credentials --resource-group=DevOps-Ref-Arch --name=mx-devops-ref-arch

This should update the local configuration file of your Kubernetes client to point to the newly created cluster. This configuration file can be found in ~/.kube/config.

3. Download the file deployment/mendixapp.yaml from this repository and update the database credentials inside it with the connection information of your Azure SQL database.

jdbc:sqlserver://<*DBSRVNAME*>.database.windows.net:1433;database=<*DBNAME*>;user=<*USERNAME*>@<*DBSRVNAME*>;password=<*PASSWORD*>

Replace the following tokens, example values in the table below are taken from the Azure SQL database created earlier in this howto:

Token	Value
<DBSRVNAME>	Database server name, example: mxsqldb
<DBNAME>	Database name, example: companyexp
<USERNAME>	Database server username, for test purposes it is acceptable to use the server admin account details here
<PASSWORD>	Database server password, use corresponding password

4. Go to the Managed File section of the Jenkins Configuration (Manage Jenkins > Managed Files). Upload the configuration files retrieved in the previous two steps using the ID names kubeconfig and mendixapp.yaml, respectively.

5. Create new Jenkins Pipeline (New Item > Pipeline)

6. Use the following script:

node {
    stage('Deploy Company Expenses') {
    configFileProvider([configFile(fileId: 'kubeconfig', targetLocation: '.kube/config'), configFile(fileId: 'mendixapp.yaml', targetLocation: 'mendixapp.yaml')]) {
        sh "kubectl apply -f mendixapp.yaml"
        }
    }
}

7. Executing this pipeline (click "Build now") will deploy your app to the Kubernetes cluster

Part 5 - Accessing your app

1. Execute the following command on the shell you used to deploy the cluster:

kubectl proxy

2. Open a browser and access the Kubernetes Dashboard via http:/localhost:8001/ui
3. You will find a link to your app under services:

ENJOY!