Chapter 6. Using Dekorate in a Spring Boot application

6.1. Overview of Dekorate

Dekorate is a collection of compile-time annotation parsers and application resource generators that are provided with Red Hat build of Spring Boot. It works by parsing annotations in your code when you build your application, and extracting configuration properties. Dekorate then uses the extracted values of properties to generate application configuration resources that you can use to deploy your application to a Kubernetes or OpenShift cluster.

As a developer, you can annotate your code and then use Dekorate to automatically generate application manifests when you build your application, which eliminates the need for you to manually write resource files for deploying your application. When your application is based on a rich application runtime framework, such as Spring Boot, Dekorate can integrate directly with the framework and extract the configuration parameters from the API provided by the framework, thus eliminating the need for you to annotate your code. Dekorate can automatically configure your application by:

  • Parsing Dekorate-specific annotations in the application code to obtain value and metadata that are used to populate the manifest files
  • Extracting information from configuration resources, such as application.properties or application.yaml
  • Obtaining the necessary metadata from a rich application framework and extracting the configuration values from the application.properties or application.yml file.

In addition to generating resource definitions for your applications, Dekorate can also generate build hooks allowing you to build and deploy your applications on an OpenShift cluster Dekorate works independently of the language in which you write your applications, and can be used with a wide range of build systems. Dekorate consists of a set of libraries distributed as a Maven BOM. You can add the libraries as dependencies of your application project to use Dekorate with your application.

Red Hat provides support for using Dekorate to generate resource files and build hooks that you can use deploy Java applications based on Spring Boot to OpenShift Container Platform with Apache Maven.

6.2. Configuring your application project to use Dekorate.

Add the Dekorate BOM and the OpenShift Annotations Starter to the pom.xml file of your application project. Include basic annotations in your source files and package your application with Maven to generate the application manifests.

Prerequisites

  • A Maven-based application project configured to use Spring Boot
  • A Java-based application that uses Spring Boot
  • Java JDK 8 or JDK 11 installed
  • Maven installed

Procedure

  1. Add the OpenShift Annotation Starter to the pom.xml file of your application:

    <project>
      ...
      <dependencies>
         ...
        <dependency>
          <groupId>io.dekorate</groupId>
          <artifactId>openshift-annotations</artifactId>
        </dependency>
        <dependency>
          <groupId>io.dekorate</groupId>
          <artifactId>openshift-spring-starter</artifactId>
        </dependency>
        ...
      </dependencies>
    ...
    <project>
  2. Add the @Dekorate annotation to the source files in your application project:

    package org.acme;
    
    import io.dekorate.annotation.Dekorate;
    
    @Dekorate
    public class Application {
    }
  3. Package your application:

    mvn clean package
  4. Navigate to the target/classes/META-INF/dekorate directory that contains the generated application template files.

6.3. Customizing your application configuration with Dekorate

Use Dekorate to customize the configuration of your application for deployment on OpenShift by

  • specifying configuration parameters in annotations in the source your application
  • setting a property in the application.properties file

The following example shows how you can set your application to start with 2 replicas when deployed to OpenShift.

Prerequisites

  • A Maven-based application project configured to use Spring Boot and Dekorate
  • A Java-based application that uses Spring Boot
  • Java JDK 8 or JDK 11 installed
  • Maven installed

Procedure

  1. Add the Dekorate OpenShift Annotations module as a dependency in the pom.xml file of your application:

    <project>
      ...
      <dependencies>
         ...
        <dependency>
          <groupId>io.dekorate</groupId>
          <artifactId>openshift-annotations</artifactId>
        </dependency>
        ...
      </dependencies>
    ...
    <project>
  2. Configure the default number of replicas that your application starts with when deployed to OpenShift:

    1. Add the @OpenshiftApplication annotation to the main source file of your application and specify the number of replicas as 2.

      package org.acme;
      
      import io.dekorate.openshift.annotation.OpenshiftApplication;
      
      // include the parameter for the number of replicas to
      @OpenshiftApplication(replicas=2)
      public class Application {
      }
    2. Alternatively, set the dekorate.openshift.replicas=2 property in the application.properties file of your application.

      /src/main/resources/application.properties

      dekorate.openshift.replicas=2

  3. Package your application:

    mvn clean package
  4. Navigate to the target/classes/META-INF/dekorate view the templates generated by Dekorate. The number of replicas in the deployment configuration YAML template is set to 2:

    ...
    spec:
      replicas: 2
      selector:
        matchLabels:
          app: acme
    ...

6.4. Using annotationless configuration in a Spring Boot application

Use Dekorate to generate OpenShift resource configuration files for your Spring Boot application project by extracting dekorate configuration properties from application.properties and application.yml files. This method does not require that you annotate your application source, because Dekorate can obtain the required metadata from Spring Boot and the configuration parameters from the property files. Annontationless configuration is a feature of rich framework integration between Spring Boot and Dekorate.

Prerequisites

  • A Maven-based application project configured to use Spring Boot and Dekorate
  • At least 1 class in your application project annotated with the @SpringBootApplication annotation.
  • Java JDK 8 or JDK 11 installed
  • Maven installed

Procedure

  1. Add the following dependencies in the pom.xml file of your application:

    <project>
      ...
      <dependencies>
        ...
        <!-- The OpenShift Spring Starter automatically adds "io.dekorate:openshift-annotations" as a transitive dependency -->
        <dependency>
          <groupId>io.dekorate</groupId>
          <artifactId>openshfit-spring-starter</artifactId>
        </dependency>
        ...
      </dependencies>
    ...
    <project>
  2. Add Dekorate configuration properties to the application.properties or application.yml file in your project. You do not have to add any Dekorate property annotations to your source files. Note, that you can still use annotations in your source files, but if you do so, Dekorate overwrites parameters provided in annotations with the parameters provided in the application.properties or application.yml files.
  3. Package your application:

    mvn clean package

    When you build your application Dekorate parses the configuration in the following resources within your application project. The configuration resources are parsed in an increasing order of priority. This means that if 2 different resources of different type present different values for the same configuration parameter, Dekorate uses the value obtained from a resource that is higher on the list of priorities. For example, if an annotation in your source specifies a parameter value, but a different value is specified for the same parameter in your application.yml, Dekorate uses the value it obtains form application.yml. Dekorate parses your project resources in the following order of priority:

    1. Annotations
    2. application.properties
    3. application.yaml
    4. application.yml
  4. Navigate to the target/classes/META-INF/dekorate directory that contains the generated application.json or application.yml manifest file.

6.5. Automatically executing OpenShift Source-to-Image Builds with Dekorate

You can use Dekorate to automatically execute an OpenShift container image build after you compile your application with Maven.

Note, that the functionality of automatically triggering Source-to-image builds using Dekorate is available as a Technology Preview. Red Hat does not provide support for using this functionality in a production environment.

Prerequisites

  • A Maven-based application project configured to use Spring Boot and Dekorate
  • The @OpenShiftApplication annotation added to the source files in your project
  • Java JDK 8 or JDK 11 installed
  • Maven installed
  • oc command-line tool installed
  • You are logged in to an OpenShift cluster using oc command-line tool

Procedure

  1. Add the Dekorate OpenShift Annotations module as a dependency to the pom.xml file of your application. Note, that this module is included as a transitive dependency in all Dekorate Starters:

    <project>
      ...
      <dependencies>
         ...
        <dependency>
          <groupId>io.dekorate</groupId>
          <artifactId>openshift-annotations</artifactId>
        </dependency>
        ...
      </dependencies>
    ...
    <project>
  2. Build and Deploy your application. Include the -Ddekorate.build=true property to execute the container image build after Maven compiles your application. Note that the functionality that automatically executes the Source-to-image build is provided as Technology Preview.

    $ mvn clean install -Ddekorate.build=true

    You can also execute the Source-to-image build manually from the command line after you compile your application with Maven:

    # Process your application YAML template that is generated by Dekorate:
    $ oc apply -f target/classes/META-INF/dekorate/openshift.yml
    # Execute the Source-to-image build and deploy your application to the OpenShift cluster:
    $ oc start-build example --from-dir=./target --follow

6.6. Using Dekorate with Spring Boot on OpenShift

The following example shows you how:

  1. You can use the openshift-spring-stater in an application.
  2. Dekorate can automaticaly identify the type of the application and configure OpenShift service routes and probes accordingly.
  3. You can set up your application to trigger a source-to-image build after Maven compiles your application.
  4. Prerequisites

    • A Maven-based application project configured to use Spring Boot and Dekorate
    • The @SpringBootApplication annotation added to the source files in your project
    • Java JDK 8 or JDK 11 installed
    • Maven installed
    • oc command-line tool installed
    • You are logged in to an OpenShift cluster using oc command-line tool

Procedure

  1. Add the Dekorate Spring Starter as a dependency in the pom.xml file of your application project.

    pom.xml

    <project>
      ...
      <dependencies>
         ...
        <dependency>
          <groupId>io.dekorate</groupId>
          <artifactId>openshift-spring-starter</artifactId>
        </dependency>
        ...
      </dependencies>
    ...
    <project>

  2. Annotate the Main.java class file with the @OpenShiftApplication annotation. This enables the source-to-image build to start when the application compiles.

    /src/main/java/io/dekorate/example/sbonopenshift/Main.java

    package io.dekorate.example.sbonopenshift;
    
    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    
    @OpenShiftApplication
    @SpringBootApplication
    public class Main {
    
      public static void main(String[] args) {
        SpringApplication.run(Main.class, args);
      }
    
    }

  3. Add a Rest controller to your application:

    /src/main/java/io/dekorate/example/sbonopenshift/Controller.java

    package io.dekorate.example.sbonopenshift;
    
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RestController;
    
    @RestController
    public class Controller {
    
      @RequestMapping("/")
      public String hello() {
        return "Hello world";
      }
    }

    The Spring application processor provided by the the Dekorate Spring starter automatically detects the Rest controller and identifies the application type as a web application. For a web application, Dekorate automatically generate the OpenShift application template and configures:

    • the OpenShift Service route for your application
    • exposes a service on the route of your application
    • configures liveness and readiness probe settings
  4. Build and deploy your application. Include the -Ddekorate.deploy=true property to automatically execute the source-to-image build after Maven compiles your application.
mvn clean install -Ddekorate.deploy=true