Deploy a Spring Boot Application on a Kubernetes Cluster in the Azure Container Service

Kubernetes and Docker are open-source solutions that help developers automate the deployment, scaling, and management of their applications running in containers.

This tutorial walks you though combining these two popular, open-source technologies to develop and deploy a Spring Boot application to Microsoft Azure. More specifically, you use Spring Boot for application development, Kubernetes for container deployment, and the Azure Container Service (AKS) to host your application.

Prerequisites

Note

Due to the virtualization requirements of this tutorial, you cannot follow the steps in this article on a virtual machine; you must use a physical computer with virtualization features enabled.

Create the Spring Boot on Docker Getting Started web app

The following steps walk you through building a Spring Boot web application and testing it locally.

  1. Open a command-prompt and create a local directory to hold your application, and change to that directory; for example:

    md C:\SpringBoot
    cd C:\SpringBoot
    

    -- or --

    md /users/robert/SpringBoot
    cd /users/robert/SpringBoot
    
  2. Clone the Spring Boot on Docker Getting Started sample project into the directory.

    git clone https://github.com/spring-guides/gs-spring-boot-docker.git
    
  3. Change directory to the completed project.

    cd gs-spring-boot-docker
    cd complete
    
  4. Use Maven to build and run the sample app.

    mvn package spring-boot:run
    
  5. Test the web app by browsing to http://localhost:8080, or with the following curl command:

    curl http://localhost:8080
    
  6. You should see the following message displayed: Hello Docker World

    Browse Sample App Locally

Create an Azure Container Registry using the Azure CLI

  1. Open a command prompt.

  2. Log in to your Azure account:

    az login
    
  3. Create a resource group for the Azure resources used in this tutorial.

    az group create --name=wingtiptoys-kubernetes --location=eastus
    
  4. Create a private Azure container registry in the resource group. The tutorial pushes the sample app as a Docker image to this registry in later steps. Replace wingtiptoysregistry with a unique name for your registry.

    az acr create --admin-enabled --resource-group wingtiptoys-kubernetes--location eastus \
     --name wingtiptoysregistry --sku Basic
    

Push your app to the container registry

  1. Navigate to the configuration directory for your Maven installation (default ~/.m2/ or C:\Users\username.m2) and open the settings.xml file with a text editor.

  2. Retrieve the password for your container registry from the Azure CLI.

    az acr credential show --name wingtiptoysregistry --query passwords[0]
    
    {
    "name": "password",
    "value": "AbCdEfGhIjKlMnOpQrStUvWxYz"
    }
    
  3. Add your Azure Container Registry id and password to a new <server> collection in the settings.xml file. The id and username are the name of the registry. Use the password value from the previous command (without quotes).

    <servers>
       <server>
          <id>wingtiptoysregistry</id>
          <username>wingtiptoysregistry</username>
          <password>AbCdEfGhIjKlMnOpQrStUvWxYz</password>
       </server>
    </servers>
    
  4. Navigate to the completed project directory for your Spring Boot application (for example, "C:\SpringBoot\gs-spring-boot-docker\complete" or "/users/robert/SpringBoot/gs-spring-boot-docker/complete"), and open the pom.xml file with a text editor.

  5. Update the <properties> collection in the pom.xml file with the login server value for your Azure Container Registry.

    <properties>
       <docker.image.prefix>wingtiptoysregistry.azurecr.io</docker.image.prefix>
       <java.version>1.8</java.version>
    </properties>
    
  6. Update the <plugins> collection in the pom.xml file so that the <plugin> contains the login server address and registry name for your Azure Container Registry.

    <plugin>
       <groupId>com.spotify</groupId>
       <artifactId>docker-maven-plugin</artifactId>
       <version>0.4.11</version>
       <configuration>
          <imageName>${docker.image.prefix}/${project.artifactId}</imageName>
          <dockerDirectory>src/main/docker</dockerDirectory>
          <resources>
             <resource>
                <targetPath>/</targetPath>
                <directory>${project.build.directory}</directory>
                <include>${project.build.finalName}.jar</include>
             </resource>
          </resources>
          <serverId>wingtiptoysregistry</serverId>
          <registryUrl>https://wingtiptoysregistry.azurecr.io</registryUrl>
       </configuration>
    </plugin>
    
  7. Navigate to the completed project directory for your Spring Boot application and run the following command to build the Docker container and push the image to the registry:

    mvn package docker:build -DpushImage
    

Note

You may receive an error message that is similar to one of the following when Maven pushes the image to Azure:

  • [ERROR] Failed to execute goal com.spotify:docker-maven-plugin:0.4.11:build (default-cli) on project gs-spring-boot-docker: Exception caught: no basic auth credentials

  • [ERROR] Failed to execute goal com.spotify:docker-maven-plugin:0.4.11:build (default-cli) on project gs-spring-boot-docker: Exception caught: Incomplete Docker registry authorization credentials. Please provide all of username, password, and email or none.

If you get this error, log in to Azure from the Docker command line.

docker login -u wingtiptoysregistry -p "AbCdEfGhIjKlMnOpQrStUvWxYz" wingtiptoysregistry.azurecr.io

Then push your container:

docker push wingtiptoysregistry.azurecr.io/gs-spring-boot-docker

Create a Kubernetes Cluster on AKS using the Azure CLI

  1. Create a Kubernetes cluster in Azure Container Service. The following command creates a kubernetes cluster in the wingtiptoys-kubernetes resource group, with wingtiptoys-containerservice as the cluster name, and wingtiptoys-kubernetes as the DNS prefix:

    az acs create --orchestrator-type=kubernetes --resource-group=wingtiptoys-kubernetes \ 
     --name=wingtiptoys-containerservice --dns-prefix=wingtiptoys-kubernetes
    

    This command may take a while to complete.

  2. Install kubectl using the Azure CLI. Linux users may have to prefix this command with sudo since it deploys the Kubernetes CLI to /usr/local/bin.

    az acs kubernetes install-cli
    
  3. Download the cluster configuration information so you can manage your cluster from the Kubernetes web interface and kubectl.

    az acs kubernetes get-credentials --resource-group=wingtiptoys-kubernetes  \ 
     --name=wingtiptoys-containerservice
    

Deploy the image to your Kubernetes cluster

This tutorial deploys the app using kubectl, then allow you to explore the deployment through the Kubernetes web interface.

Deploy with the Kubernetes web interface

  1. Open a command prompt.

  2. Open the configuration website for your Kubernetes cluster in your default browser:

    az acs kubernetes browse --resource-group=wingtiptoys-kubernetes --name=wingtiptoys-containerservice
    
  3. When the Kubernetes configuration website opens in your browser, click the link to deploy a containerized app:

    Kubernetes Configuration Website

  4. When the Deploy a containerized app page is displayed, specify the following options:

    a. Select Specify app details below.

    b. Enter your Spring Boot application name for the App name; for example: "gs-spring-boot-docker".

    c. Enter your login server and container image from earlier for the Container image; for example: "wingtiptoysregistry.azurecr.io/gs-spring-boot-docker:latest".

    d. Choose External for the Service.

    e. Specify your external and internal ports in the Port and Target port text boxes.

    Kubernetes Configuration Website

  5. Click Deploy to deploy the container.

    Deploy Container

  6. Once your application has been deployed, you will see your Spring Boot application listed under Services.

    Kubernetes Services

  7. If you click the link for External endpoints, you can see your Spring Boot application running on Azure.

    Kubernetes Services

    Browse Sample App on Azure

Deploy with kubectl

  1. Open a command prompt.

  2. Run your container in the Kubernetes cluster by using the kubectl run command. Give a service name for your app in Kubernetes and the full image name. For example:

    kubectl run gs-spring-boot-docker --image=wingtiptoysregistry.azurecr.io/gs-spring-boot-docker:latest
    

    In this command:

    • The container name gs-spring-boot-docker is specified immediately after the run command

    • The --image parameter specifies the combined login server and image name as wingtiptoysregistry.azurecr.io/gs-spring-boot-docker:latest

  3. Expose your Kubernetes cluster externally by using the kubectl expose command. Specify your service name, the public-facing TCP port used to access the app, and the internal target port your app listens on. For example:

    kubectl expose deployment gs-spring-boot-docker --type=LoadBalancer --port=80 --target-port=8080
    

    In this command:

    • The container name gs-spring-boot-docker is specified immediately after the expose deployment command

    • The --type parameter specifies that the cluster uses load balancer

    • The --port parameter specifies the public-facing TCP port of 80. You access the app on this port.

    • The --target-port parameter specifies the internal TCP port of 8080. The load balancer forwards requests to your app on this port.

  4. Once the app is deployed to the cluster, query the external IP address and open it in your web browser:

    kubectl get services -o jsonpath={.items[*].status.loadBalancer.ingress[0].ip} --namespace=${namespace}
    

    Browse Sample App on Azure

Next steps

For more information about using Spring Boot on Azure, see the following articles:

For more information about using Azure with Java, see the Azure for Java Developers and the Java Tools for Visual Studio Team Services.

For more information about the Spring Boot on Docker sample project, see Spring Boot on Docker Getting Started.

The following links provide additional information about creating Spring Boot applications:

  • For more information about creating a simple Spring Boot application, see the Spring Initializr at https://start.spring.io/.

The following links provide additional information about using Kubernetes with Azure:

More information about using Kubernetes command-line interface is available in the kubectl user guide at https://kubernetes.io/docs/user-guide/kubectl/.

The Kubernetes website has several articles that discuss using images in private registries:

For additional examples for how to use custom Docker images with Azure, see Using a custom Docker image for Azure Web App on Linux.