Kubernetes: Deploy a Spring Boot Application

In this tutorial, you use an Oracle Cloud Infrastructure account to set up a Kubernetes cluster. Then, you deploy a Spring Boot application to your cluster. Key tasks include how to:

  • Set up OpenSSL API encryption keys to access your cluster.
  • Set up an authentication token.
  • Set up a Kubernetes cluster on OCI.
  • Set up OCI CLI to access your cluster.
  • Build a Spring Boot application and Docker Image.
  • Push your image to OCIR.
  • Deploy your Docker application to your cluster.
  • Connect to your application from the internet.
A diagram of the components needed to run a Spring Boot app on Oracle Cloud Infrastructure Container Engine

For additional information, see:

Before You Begin

To successfully perform this tutorial, you must have the following:

If you have Windows, you can Download Git for Windows and access a Linux environment. Here are some options:

Install or have the following applications:

  • JDK 11 and set JAVA_HOME in .bashrc
  • Python 3
  • Kubernetes 1.11.9+
  • Apache Maven 3.6+
  • Docker 18.0.6+

1. Gather Required Information

Prepare the information you need from the Oracle Cloud Infrastructure Console.

  1. Check your service limits:
    • Regions: minimum 2

      In the top navigation bar, expand <region>. Example: US East (Ashburn) and US West (Phoenix).

    • Compute instances: minimum 3

      Click your profile avatar. Select Tenancy. Go to Service Limits and expand Compute.

    • Block Volume: minimum 50 GBs

      In the Service Limits section, expand Block Volume.

    • Load Balancer: available

      In the Service Limits section, expand Networking.

  2. Have a compartment for your cluster.
  3. Create an authorization token:
    • In the top navigation bar, click your user avatar.
    • Select your username.
    • Click Auth Tokens.
    • Click Generate Token.
    • Give it a description.
    • Click Generate Token.
    • Copy the token and save it.
    Note

    Make sure you save your token right after you create it. You will not have access to it later.
  4. Find your region identifier and region key from Regions and Availability Domains. Example: us-ashburn-1 and iad for Ashburn.
  5. Collect the following information and copy them into your notepad.
    • Auth Token: <auth-token> from step 3.
    • Region: <region-identifier> from step 4. Example: us-ahburn-1.
    • Region Key: <region-key> from step 4. Example: iad.
    • Tenancy name: <tenancy-name> from your user avatar.
    • Tenancy OCID: <tenancy-ocid> from your user avatar, go to Tenancy:<your-tenancy> and copy OCID.
    • Username: <user-name> from your user avatar.
    • User OCID: <user-ocid> from your user avatar, go to User Settings and copy OCID.

2. Set up OCI Command Line Interface

You can use the OCI Command Line Interface (CLI) to push your application to Oracle Registry and then pull and deploy it with Oracle Container Engine (OKE) which is Kubernetes. In this step, you install and set up the CLI to run on a MacOS or a Linux environment.

  1. Install virtualenv:

    With a virtual environment, you can manage dependencies for your project. Every project can be in its own virtual environment to host independent groups of Python libraries.

    • Ubuntu:
      sudo apt update
      sudo apt install python3-pip
      sudo apt install python3-venv
    • Red Hat Linux: When you install Python 3 from Red Hat Software Collections, venv, virtualenv, and pip will be installed, so you are ready to install whatever modules you choose.
      sudo yum install rh-python36
      sudo pip3 install virtualenv
    • MacOS: When you install Python 3 for MacOS, pip3 will be installed, so you are ready to install modules with pip3.
      brew install python3
      pip3 install pipenv
    Note

    You may need to type "y" a few times to accept the packages that are installed to the VM.
  2. Install a virtual environment wrapper.

    The virtualenvwrapper is an extension to virtualenv. It provides a set of commands, which makes working with virtual environments much more pleasant. It also places all your virtual environments in one place. The virtualenvwrapper provides tab-completion on environment names.

    sudo pip3 install virtualenvwrapper
  3. Set up your virtual environment wrapper in .bashrc.

    Update the file:

    sudo vi .bashrc

    In the file, append the following text and save the file:

    # set up Python env
    export WORKON_HOME=~/envs
    export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python3
    export VIRTUALENVWRAPPER_VIRTUALENV_ARGS=' -p /usr/bin/python3 '
    source /usr/local/bin/virtualenvwrapper.sh

    Activate the above commands in the current window.

    source ~/.bashrc
  4. Start a virtual environment.
    mkvirtualenv cli-app
    You should see something like: (cli-app) ubuntu@<ubuntu-instance-name>:~$
  5. Install OCI CLI .
    pip3 install oci-cli
  6. Test the installation:
    oci os ns get

    You should get your namespace if everything is set up correctly.

  7. Set up the OCI CLI config file.
    oci setup config

    Enter basic information: (Get the answers from "Gather Required Information" step.)

    • Location for your config [$HOME/.oci/config]: <take-default>
    • User OCID: <user-ocid>
    • Tenancy OCID: <tenancy-ocid>
    • Region (e.g. us-ashburn-1): <region-identifier>

    Set up your OpenSSL API encryption keys:

    • Generate a new API Signing RSA key pair? [Y/n]: Y
    • Directory for your keys [$HOME/.oci]: <take-default>
    • Name for your key [oci_api_key] <take-default>
    Note

    Your private key is oci_api_key.pem and your public key is oci_api_key_public.pem.
  8. Deactivate the virtual environment:
    deactivate

    The (cli-app) prefix in your environment should not be displayed anymore.

    Note

    • Whenever you want to use the OCI CLI, activate it with: workon cli-app
    • workon deactivates the environment you are currently in, if you change project names. This way, you can quickly switch between environments.
  9. Activate the cli-app environment:
    workon cli-app
  10. Copy the public key.
    In the terminal enter:
    cat $HOME/.oci/oci_api_key_public.pem
  11. Add the public key to your user account.
    • From your user avatar, go to User Settings.
    • Click Add Public Key.
    • Select Paste Public Keys.
    • Paste value from previous step, including the lines with BEGIN PUBLIC KEY and END PUBLIC KEY
    • Click Add.
    You have now set up the Oracle Cloud Infrastructure CLI to connect to your tenancy with your user account. Next, you create a Kubernetes cluster in your tenancy.

3. Create your Kubernetes Cluster

Set up the Kubernetes cluster you will deploy your Spring Boot application to. You will use a wizard to set up your first cluster.

  1. From the OCI main menu select Developer Services then Container Clusters.
  2. Click Create Cluster.
  3. Select Quick Create.
  4. Click Launch Workflow.

    The Cluster Creation dialog is displayed.

  5. Fill in the following information
    • Name: <your-cluster-name>
    • Compartment: <your-compartment-name>
    • Kubernetes Version: <take-default>
    • Visibility Type: <Private>
    • Shape: VM.Standard.E2.1
    • Number of Nodes: 3
    • Add Ons: <none-selected>
  6. Click Next.

    All your choices are displayed. Review them to make sure everything is configurated correctly.

  7. Click Create Cluster.

    The services set up for your cluster are displayed.

  8. Click Close.
  9. Get a cup of coffee. It may take a few minutes for the cluster to be created.
You have successfully created a Kubernetes cluster. Next you will need to configure management options for your cluster.

4. Manage your Kubernetes Cluster (Local)

With your Kubernetes cluster setup, you need to configure your local system. To do that, complete the following steps:

  1. From the OCI main menu select Developer Services then Container Clusters.
  2. Click the link to <your-cluster>.

    The information about your cluster is displayed.

  3. Click Access Cluster.
  4. Select Local Access.
  5. Follow the steps provided in the dialog. They are reprinted here for your reference.
    Note

    If you are not in your virtual environment, enter: workon cli-app before you run kubectl commands.

    Check your oci CLI version.

    oci -v

    Make your .kube directory if it doesn't exist.

    mkdir -p $HOME/.kube

    Create kubeconfig file for your setup. Use the information from Access Your Cluster dialog.

    oci ce cluster create-kubeconfig <use data from dialog>

    Export the KUBECONFIG environment variable.

    export KUBECONFIG=$HOME/.kube/config
  6. Test your cluster configuration with the following commands.

    List clusters:

    kubectl get service

    Get deployment details:

    kubectl describe deployment

    Get pods:

    kubectl get pods

    Note: Specify a different config file on the command line to look at a different cluster for example:

    kubectl --kubeconfig=</path/to/config/file>

With your cluster configured, you are now ready to prepare you application for deployment.

5. Create your Local Spring Boot Application

Next, build your application Docker image so you can deploy the image to Oracle Registry (OCIR).

To create a Spring Boot Docker image, perform the following steps:

  1. Check out the Spring Boot Docker guide with Git:
    git clone http://github.com/spring-guides/gs-spring-boot-docker.git
  2. Change into the gs-spring-boot-docker/initial directory.
  3. Change into the Java source directory: src/main/java/hello.
  4. Update the code with the following:
    package hello;
                            
    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RestController;
    
    @SpringBootApplication
    @RestController
    public class Application {
    
        @RequestMapping("/")
        public String home() {
            return "<h1>Spring Boot Hello World!</h1>";
        }
    
        public static void main(String[] args) {
            SpringApplication.run(Application.class, args);
        }
    
    }                      
                        
  5. Save the file.
  6. Create a file named Dockerfile in the initial folder.
    
    FROM openjdk:8-jdk-alpine
    RUN addgroup -S spring && adduser -S spring -G spring
    USER spring:spring
    ARG JAR_FILE=target/*.jar
    COPY ${JAR_FILE} app.jar
    ENTRYPOINT ["java","-jar","/app.jar"]
                        
  7. Build and package the app: mvn package
  8. Run and test the app: java -jar target/gs-spring-boot-docker-0.1.0.jar
  9. Test the app either by entering curl -X GET http://localhost:8080 in a new terminal, or loading localhost:8080 in a browser (if your environment is local).

    You may need to precede the docker commands with sudo in the following steps.

  10. Build the Docker images: docker build -t spring-boot-hello .
  11. Run your Docker image: docker run -p 8080:8080 -t spring-boot-hello

    Your Docker environment is now setup for OCIR.

    For more information, see the Spring Boot Docker tutorial.

Congratulations! You have successfully created a Spring Boot Docker image.

6. Deploy your Docker Image to OCIR and your Cluster

Next, push your Spring Boot Docker image to OCIR. Then use that Docker image to deploy your application.:

Create an OCIR Repository
  1. From the main menu select Developer Services then Registry.
  2. Click on Create Repository.
  3. Create a private repository with your choice of name.
    You are now ready to push your local image to OCIR.
Push your Local Image

Now change to your local machine so you can push your image to OCIR.

  1. Open a terminal window.
  2. Login to OCIR:
    docker login <region-key>.ocir.io

    You are prompted for your login name and password.

    • Username: <tenancy-name>/<user-name>
    • Password: <auth-token>
  3. List your local Docker images:
    docker images

    The Docker images on your system are displayed. Identify the image you created in the last section: spring-boot-hello

  4. Tag your local image so it can be pushed to OCIR:
    docker tag <your-local-image> <target-tag>

    The target tag consists of: <region-key>.ocir.io/<tenancy-name>/<repo-name>/<image-name>

  5. Check your Docker images to see if the tag has been created.
    docker images

    The target tag that you created should have the same image ID as your local image.

  6. Push the image to OCIR.
    docker push <target-tag>:latest

    You should see your image in OCIR after the push command is complete.

Deploy your Image to your Cluster

With your image in OCIR, you can now deploy your image and app.

  1. First, create a registry secret for your application. This will be used to authenticate your image when it is deployed to your cluster.

    Fill in the information in this template to create your secret.

    
    kubectl create secret docker-registry ocirsecret --docker-server=<region-key>.ocir.io  --docker-username='<tenancy-name>/<user-name>' --docker-password='<auth-token>'  --docker-email='<email-address>'                                
                        

    After executing the command, you should get a message similar to: secret/ocirsecret created.

  2. Verify the secret was created. Issue the following command.
    kubectl get secret ocirsecret --output=yaml

    The output includes information about your secret is shown in the yaml format.

  3. Determine the host URL to your registry image using the following template.
    
    <region-code>.ocir.io/<tenancy-name>/<repo-name>/<image-name>:<tag>
                    
  4. Create an sb-app.yaml file on your system. Put the following text in the file. Replace the URL for your image and replace the secret name.
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: sbapp
    spec:
      selector:
        matchLabels:
          app: sbapp
      replicas: 3
      template:
        metadata:
          labels:
            app: sbapp
        spec:
          containers:
          - name: sbapp
            image: <your-image-url>
            imagePullPolicy: Always
            ports:
            - name: sbapp
              containerPort: 8080
              protocol: TCP
          imagePullSecrets:
            - name: <your-secret-name>
    ---
    apiVersion: v1
    kind: Service
    metadata:
      name: sbapp-lb
      labels:
        app: sbapp
    spec:
      type: LoadBalancer
      ports:
      - port: 8080
      selector:
        app: sbapp

    Note: The code after the dashes adds a load balancer.

  5. Deploy your application with the following command.
    kubectl create -f sb-app.yaml
Test your App

Your load balancer may take a few seconds to load after issuing the command.

  1. Check for your load balancer to deploy.
    kubectl get service

    Repeat the command until load balancer is assigned an IP address.

  2. Using the IP address for the load balancer connect to your app in a browser, http://x.x.x.x:8080
Congratulations! You have successfully installed and deployed a Spring Boot app to a Kubernetes cluster on Oracle Cloud Infrastructure.

What's Next

You have successfully created a Hello World application, deployed it to a Kubernetes cluster and made it accessible on the internet, using the Spring Boot framework.

To explore more information about development with Oracle products check out these sites: