Deploy to Azure Kubernetes Service (AKS) by using Jenkins and the blue/green deployment pattern

Azure Kubernetes Service (AKS) manages your hosted Kubernetes environment, making it quick and easy to deploy and manage containerized applications. You don't need expertise in container orchestration. AKS also eliminates the burden of ongoing operations and maintenance, by provisioning, upgrading, and scaling resources on demand. You don't need to take your applications offline. For more information about AKS, see the AKS documentation.

Blue/green deployment is an Azure DevOps Continuous Delivery pattern that relies on keeping an existing (blue) version live, while a new (green) one is deployed. Typically, this pattern employs load balancing to direct increasing amounts of traffic to the green deployment. If monitoring discovers an incident, traffic can be rerouted to the blue deployment, which is still running. For more information about Continuous Delivery, see What is Continuous Delivery.

In this tutorial, you learn how to perform the following tasks:

  • Learn about the blue/green deployment pattern
  • Create a managed Kubernetes cluster
  • Run a sample script to configure a Kubernetes cluster
  • Manually configure a Kubernetes cluster
  • Create and run a Jenkins job

Prerequisites

  • GitHub account : You need a GitHub account to clone the sample repo.
  • Azure CLI 2.0 : You use the Azure CLI 2.0 to create the Kubernetes cluster.
  • Chocolatey: A package manager you use to install kubectl.
  • kubectl: A command-line interface you use for running commands against Kubernetes clusters.
  • jq: A lightweight, command-line JSON processor.

Clone the sample app from GitHub

On the Microsoft repo in GitHub, you can find a sample app that illustrates how to deploy to AKS by using Jenkins and the blue/green pattern. In this section, you create a fork of that repo in your GitHub, and clone the app to your local system.

  1. Browse to the GitHub repo for the todo-app-java-on-azure sample app.

    Screenshot of sample app on Microsoft GitHub repo

  2. Fork the repo by selecting Fork in the upper right of the page, and follow the instructions to fork the repo in your GitHub account.

    Screenshot of GitHub option to fork

  3. After you fork the repo, you see that the account name changes to your account name, and a note indicates from where the repo was forked (Microsoft).

    Screenshot of GitHub account name and note

  4. Select Clone or download.

    Screenshot of GitHub option to clone or download a repo

  5. In the Clone with HTTPS window, select the copy icon.

    Screenshot of GitHub option to copy the clone URL to the clipboard

  6. Open a terminal or Git Bash window.

  7. Change directories to the desired location where you want to store the local copy (clone) of the repo.

  8. Using the git clone command, clone the URL you copied previously.

    Screenshot of Git Bash git clone command

  9. Press the Enter key to start the clone process.

    Screenshot of Git Bash git clone command results

  10. Change directories to the newly created directory that contains the clone of the app source.

Create and configure a managed Kubernetes cluster

In this section, you perform the following steps:

  • Use the Azure CLI 2.0 to create a managed Kubernetes cluster.
  • Learn how to set up a cluster, either by using the setup script or manually.
  • Create an instance of the Azure Container Registry service.

Use the Azure CLI 2.0 to create a managed Kubernetes cluster

In order to create a managed Kubernetes cluster with the Azure CLI 2.0, ensure that you are using the Azure CLI version 2.0.25 or later.

  1. Sign in to your Azure account. After you enter the following command, you receive instructions that explain how to complete the sign-in.

    az login
    
  2. When you run the az login command in the previous step, a list of all your Azure subscriptions appears (along with their subscription IDs). In this step, you set the default Azure subscription. Replace the <your-subscription-id> placeholder with the desired Azure subscription ID.

    az account set -s <your-subscription-id>
    
  3. Create a resource group. Replace the <your-resource-group-name> placeholder with the name of your new resource group, and replace the <your-location> placeholder with the location. The command az account list-locations displays all Azure locations. During the AKS preview, not all locations are available. If you enter a location that is not valid at this time, the error message lists the available locations.

    az group create -n <your-resource-group-name> -l <your-location>
    
  4. Create the Kubernetes cluster. Replace the <your-resource-group-name> with the name of the resource group created in the previous step, and replace the <your-kubernetes-cluster-name> with the name of your new cluster. (This process can take several minutes to complete.)

    az aks create -g <your-resource-group-name> -n <your-kubernetes-cluster-name> --generate-ssh-keys --node-count 2
    

Set up the Kubernetes cluster

You can set up a blue/green deployment in AKS manually, or with a setup script provided in the sample cloned earlier. In this section, you see how to do both.

Set up the Kubernetes cluster via the sample setup script

  1. Edit the deploy/aks/setup/setup.sh file, replacing the following placeholders with the appropriate values for your environment:

    • <your-resource-group-name>

    • <your-kubernetes-cluster-name>

    • <your-location>

    • <your-dns-name-suffix>

      Screenshot setup.sh script in bash, with several placeholders highlighted

  2. Run the setup script.

    sh setup.sh
    

Set up a Kubernetes cluster manually

  1. Download the Kubernetes configuration to your profile folder.

    az aks get-credentials -g <your-resource-group-name> -n <your-kubernetes-cluster-name> --admin
    
  2. Change the directory to the deploy/aks/setup directory.

  3. Run the following kubectl commands to set up the services for the public endpoint, and the two test endpoints.

    kubectl apply -f  service-green.yml
    kubectl apply -f  test-endpoint-blue.yml
    kubectl apply -f  test-endpoint-green.yml
    
  4. Update the DNS name for the public and test endpoints. When you create a Kubernetes cluster, you also create an additional resource group, with the naming pattern of MC_<your-resource-group-name><your-kubernetes-cluster-name><your-location>.

    Locate the public IPs in the resource group.

    Screenshot of the public IPs in the resource group

    For each of the services, find the external IP address by running the following command:

    kubectl get service todoapp-service
    

    Update the DNS name for the corresponding IP address with the following command:

    az network public-ip update --dns-name aks-todoapp --ids /subscriptions/<your-subscription-id>/resourceGroups/MC_<resourcegroup>_<aks>_<location>/providers/Microsoft.Network/publicIPAddresses/kubernetes-<ip-address>
    

    Repeat the call for todoapp-test-blue and todoapp-test-green:

    az network public-ip update --dns-name todoapp-blue --ids /subscriptions/<your-subscription-id>/resourceGroups/MC_<resourcegroup>_<aks>_<location>/providers/Microsoft.Network/publicIPAddresses/kubernetes-<ip-address>
    
    az network public-ip update --dns-name todoapp-green --ids /subscriptions/<your-subscription-id>/resourceGroups/MC_<resourcegroup>_<aks>_<location>/providers/Microsoft.Network/publicIPAddresses/kubernetes-<ip-address>
    

    The DNS name needs to be unique in your subscription. To ensure the uniqueness, you can use <your-dns-name-suffix>.

Create an instance of Container Registry

  1. Run the az acr create command to create an instance of Container Registry. In the next section, you can then use login server as the Docker registry URL.

    az acr create -n <your-registry-name> -g <your-resource-group-name>
    
  2. Run the az acr credential command to show your Container Registry credentials. Note the Docker registry username and password, as you need them in the next section.

    az acr credential show -n <your-registry-name>
    

Prepare the Jenkins server

In this section, you see how to prepare the Jenkins server to run a build, which is fine for testing. However, you should use an Azure VM agent or Azure Container agent to spin up an agent in Azure to run your builds. For more information, see the Jenkins article on the security implications of building on master.

  1. Deploy a Jenkins Master on Azure.

  2. Connect to the server via SSH, and install the build tools on the server where you run your build.

    sudo apt-get install git maven 
    
  3. Install Docker. Ensure that the user jenkins has permission to run the docker commands.

  4. Install kubectl.

  5. Download jq.

  6. Install jq with the following command:

    sudo apt-get install jq
    
  7. Install the plugins in Jenkins by performing the following steps within the Jenkins dashboard:

    1. Select Manage Jenkins > Manage Plugins > Available.
    2. Search for and install the Azure Container Service plug-in.
  8. Add credentials to manage resources in Azure. If you don’t already have the plug-in, install the Azure Credential plugin.

  9. Add your Azure Service Principal credential as the type Microsoft Azure Service Principal.

  10. Add your Azure Docker registry username and password (as obtained in the section, "Create an instance of Container Registry") as the type Username with password.

Edit the Jenkinsfile

  1. In your own repo, go to /deploy/aks/, and open Jenkinsfile.

  2. Update the file as follows:

    def servicePrincipalId = '<your-service-principal>'
    def resourceGroup = '<your-resource-group-name>'
    def aks = '<your-kubernetes-cluster-name>'
    
    def cosmosResourceGroup = '<your-cosmodb-resource-group>'
    def cosmosDbName = '<your-cosmodb-name>'
    def dbName = '<your-dbname>'
    
    def dockerRegistry = '<your-acr-name>.azurecr.io'
    

    Update the Container Registry credential ID:

    def dockerCredentialId = '<your-acr-credential-id>'
    

Create the job

  1. Add a new job in type Pipeline.

  2. Select Pipeline > Definition > Pipeline script from SCM.

  3. Enter the SCM repo URL with your <your-forked-repo>.

  4. Enter the script path as deploy/aks/Jenkinsfile.

Run the job

  1. Verify that you can run your project successfully in your local environment. Here's how: Run project on local machine.

  2. Run the Jenkins job. The first time you run the job, Jenkins deploys the todo app to the blue environment, which is the default inactive environment.

  3. To verify that the job ran, go to these URLs:

    • Public end point: http://aks-todoapp<your-dns-name-suffix>.<your-location>.cloudapp.azure.com
    • Blue end point - http://aks-todoapp-blue<your-dns-name-suffix>.<your-location>.cloudapp.azure.com
    • Green end point - http://aks-todoapp-green<your-dns-name-suffix>.<your-location>.cloudapp.azure.com

The public and the blue test end points have the same update, while the green end point shows the default tomcat image.

If you run the build more than once, it cycles through blue and green deployments. In other words, if the current environment is blue, the job deploys and tests to the green environment. Then, if tests are good, the job updates the application public endpoint to route traffic to the green environment.

Additional information

For more on zero-downtime deployment, see this quickstart template.

Clean up resources

When you no longer need the resources you created in this tutorial, you can delete them.

az group delete -y --no-wait -n <your-resource-group-name>

Troubleshooting

If you encounter any bugs with the Jenkins plugins, file an issue in the Jenkins JIRA for the specific component.

Next steps

In this tutorial, you learned how to deploy to AKS by using Jenkins and the blue/green deployment pattern. To learn more about the Azure Jenkins provider, see the Jenkins on Azure site.