Chapter 1. Using Dekorate in a Spring Boot application Use Dekorate to automatically generate application manifest files and configure your application for deployment to OpenShift. 1.1. Overview of Dekorate Dekorate is a collection of compile-time annotation processors 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 provides 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 hooks that you can use to deploy Java applications based on Spring Boot to OpenShift Container Platform. 1.1.1. Additional resources Reference for Dekorate configuration properties for OpenShift . Reference for Dekorate configuration properties for Source-to-Image . Reference for all Dekorate Configuration properties in the community documentation. 1.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 Java application project configured to use Spring Boot. Java JDK 8 or JDK 11 is installed. Maven is installed. Procedure Add the Dekorate OpenShift Spring Starter to the pom.xml file of your application to enable Dekorate to porcess your application source code and resource files: <project> ... <dependencies> ... <dependency> <!-- The OpenShift Spring Starter automatically imports the "io.dekorate:openshift-annotations" dependency. --> <groupId>io.dekorate</groupId> <artifactId>openshift-spring-starter</artifactId> <version>USD{dekorate.version}</version> </dependency> ... </dependencies> ... <project> Add the @SpringBootApplication annotation to the main class file of your application project: package org.acme; @SpringBootApplication public class Application { } Package your application to process you application code and resource files with Dekorate mvn clean package Navigate to the target/classes/META-INF/dekorate directory that contains the generated OpenShift manifests. 1.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 Java application project configured to use Spring Boot and Dekorate Java JDK 8 or JDK 11 is installed. Maven is installed. Procedure 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-spring-starter</artifactId> <version>USD{dekorate.version}</version> </dependency> ... </dependencies> ... <project> Configure the default number of replicas that your application starts with when deployed to OpenShift: Add the @OpenshiftApplication annotation to the main source file of your application and set number of replicas to 2. When you build and deploy your application, it automatically starts with 2 replicas of the main application container running: package org.acme; import io.dekorate.openshift.annotation.OpenshiftApplication; // include the parameter for the number of replicas to @OpenshiftApplication(replicas=2) @SpringBootApplication public class Application { } 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 Package your application: mvn clean package Navigate to the target/classes/META-INF/dekorate view the manifests generated by Dekorate. The number of replicas in the deployment configuration YAML template is set to 2: ... spec: replicas: 2 selector: matchLabels: app: acme ... Additional resources Overview of Dekorate configuration properties for OpenShift . 1.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 one class in your application project is annotated with the @SpringBootApplication annotation. Java JDK 8 or JDK 11 is installed. Maven is installed. Procedure 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> <version>USD{dekorate.version}</version> </dependency> ... </dependencies> ... <project> 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. 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 from application.yml . Dekorate parses your project resources in the following order of priority: Annotations application.properties application.yaml application.yml Navigate to the target/classes/META-INF/dekorate directory that contains the generated openshift.json and openshift.yml manifest files. 1.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 @SpringBootApplication annotation is added to the source files in your project. Java JDK 8 or JDK 11 is installed. Maven is installed. oc command-line tool is installed. You are logged in to an OpenShift cluster using oc command-line tool. Procedure Add the Dekorate OpenShift Spring Starter as a dependency to the pom.xml file of your application. Note, that this module is included as a transitive dependency in all Dekorate OpenShift Starters: <project> ... <dependencies> ... <dependency> <groupId>io.dekorate</groupId> <artifactId>openshift-spring-starter</artifactId> <version>USD{dekorate.version}</version> </dependency> ... </dependencies> ... <project> 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 . USD 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: USD oc apply -f target/classes/META-INF/dekorate/openshift.yml # Execute the Source-to-image build and deploy your application to the OpenShift cluster: USD oc start-build example --from-dir=./target --follow 1.6. Using Dekorate with Spring Boot on OpenShift The following example shows you how: You can use the openshift-spring-stater in an application. Dekorate can automaticaly identify the type of the application and configure OpenShift service routes and probes accordingly. You can set up your application to trigger a source-to-image build after Maven compiles your application. Prerequisites A Maven-based application project configured to use Spring Boot and Dekorate . The @SpringBootApplication annotation is added to the source files in your project. Java JDK 8 or JDK 11 is installed. Maven is installed. oc command-line tool installed. You are logged in to an OpenShift cluster using oc command-line tool. Procedure 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> <version>USD{dekorate.version}</version> </dependency> ... </dependencies> ... <project> Add the @SpringBootApplication annotation to your Main.java class. This enables the source-to-image build to start when the application is compiled: /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; @SpringBootApplication public class Main { public static void main(String[] args) { SpringApplication.run(Main.class, args); } } 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 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 1.7. Dekorate configuration properties for OpenShift The properties listed in the table below set the values that Dekorate uses to configure your application for deployment to OpenShift. Dekorate uses the values specified in these properties to populate the Deployment Configuration and application resource files generated for your application project. Each property accepts values of the data type that is listed in the table for the particular property. Some of the properties have a default value that Dekorate uses if you do not specify a value for these attributes. You can set these properties in the application.properties file of your application project. Table 1.1. Dekorate application properties for OpenShift Property Data Type Description Default Value (if applicable) dekorate.openshift.part-of String The name of the collection of components that your application belongs to. The value of this property is used in the name for other Kubernetes resources that your application contains, such as Deployment Configurations and Services. If you do not specify a value for this property, Dekorate uses the name of the groupId that you use in the Maven project of your application as the default value. dekorate.openshift.name String The name of the application. The value of this property is used in the name for other Kubernetes resources that your application contains, such as Deployment Configurations and Services. If you do not specify a value for this property, Dekorate uses the name of the artifactId that you use for the Maven project of your application as the default value. dekorate.openshift.version String The version of the application. The value of this property is used in the name of all Kubernetes resources that your application contains, such as Deployment Configurations and Services. If you do not specify a value for this property, Dekorate uses the version that you specify in the Maven project containing your application as the default value. dekorate.openshift.init-containers Container[] Specifies init containers that you want to use in your application dekorate.openshift.labels Label[] Specifies custom labels to be added to all resources in your application dekorate.openshift.annotations Annotation[] Specifies custom annotations that you want to add to all resources in your application dekorate.openshift.env-vars Env[] Specifies environment variables that you want to define for all containers created for your application dekorate.openshift.working-dir String Specifies the working directory of your application container dekorate.openshift.command String[] Specifies commands that you want to use in your container dekorate.openshift.arguments String[] Specifies custom command-line arguments that you want to use in your container dekorate.openshift.replicas int Specifies how many replicas of application containers you want to create when you deploy your application 1 dekorate.openshift.service-account String Specifies the name of the Service account used by your application dekorate.openshift.host String The name of the host node on which your application is running dekorate.openshift.ports Port[] Network ports that the services provided by your are exposed on dekorate.openshift.service-type ServiceType The type of service that is generated for your application ClusterIP dekorate.openshift.pvc-volumes PersistentVolumeClaimVolume[] Persistent Volume Claims that you want to attach to all containers of your application dekorate.openshift.secret-volumes SecretVolume[] Secret volumes that you want to attach to all containers of your application dekorate.openshift.config-map-volumes ConfigMapVolume[] ConfigMap volumes that you want to attach to all containers of your application dekorate.openshift.git-repo-volumes GitRepoVolume[] Git repository volumes that you want to attach to all containers of your application dekorate.openshift.aws-elastic-block-store-volumes AwsElasticBlockStoreVolume[] AWS Elastic Block Store volumes that you want to attach to all containers of your application dekorate.openshift.azure-disk-volumes AzureDiskVolume[] Microsoft Azure disk volumes that you want to attach to all containers of your application dekorate.openshift.azure-file-volumes AzureFileVolume[] Azure file volumes volumes that you want to attach to all containers of your application dekorate.openshift.mounts Mount[] Mounts that you want to attach to all containers of your application dekorate.openshift.image-pull-policy ImagePullPolicy Specify the image pull policy that you want to when deploying your application IfNotPresent dekorate.openshift.image-pull-secrets String[] Specify the image pull secret policy that you want to use when deploying your application dekorate.openshift.liveness-probe Probe Set up a Liveness probe for your application container dekorate.openshift.readiness-probe Probe Set up a Readiness probe for your application container dekorate.openshift.request-resources ResourceRequirements Specify the amount of resources that your application container requires dekorate.openshift.limit-resources ResourceRequirements Set a resource limit for your application container dekorate.openshift.sidecars Container[] Specify containers that you want to deploy as sidecars dekorate.openshift.expose boolean Set whether you want to expose a Route for your application after you deploy it false dekorate.openshift.headless boolean Set whether you want the service that you generate to execute headless false dekorate.openshift.auto-deploy-enabled boolean Set whether your application is automatically deployed when you generate a deploy hook. Setting this property on your application requires that you hard-code its value in your application.properties file. Do not set this property if you want to avoid hard-coding its value. Instead, use the -Ddekorate.deploy=true option when deploying your application with Maven false dekorate.openshift.deployment-kind String The kind of the deployment resource to use. Supported values are DeploymentConfig , Deployment , StatefulSet , Job , and CronJob defaulting to the first. DeploymentConfig 1.8. Dekorate configuration properties for Source-to-Image The properties listed in the table below set the values that Dekorate uses to configure Source-to-Image (s2i) to build for your applications. You can set these properties in the application.properties file of your application project. Table 1.2. Dekorate configuration properties for S2i Property Data Type Description Default Value (if applicable) dekorate.s2i.enabled boolean Enable s2i build hook generation for your application true dekorate.s2i.registry String Specify the registry name for the image that you want to build dekorate.s2i.group String Specify the group ID of the application. This value will be used as the username in the docker image that you build dekorate.s2i.name String Specify the name of your application. This value is be used as the name of the image that you build. dekorate.s2i.version String The version of the application. This value is be used as the tag of the image that you build. dekorate.s2i.image String Specifies the full reference to the image that you want to build. When set, this property overrides the values of the group , name and version properties. dekorate.s2i.docker-file String Specifies the relative path to the Dockerfile from the root directory of your application project Dockerfile dekorate.s2i.builder-image String Specifies the name of the S2i builder image that you want to use registry.access.redhat.com/ubi8/openjdk-8:1.3 dekorate.s2i.build-env-vars Env[] Set environment variables for the s2i build dekorate.s2i.auto-push-enabled boolean When true , s2i automatically pushes the image to the specified registry when the image is built. false dekorate.s2i.auto-build-enabled boolean When true , s2i automatically registers a build hook when the application is compiled false dekorate.s2i.auto-deploy-enabled boolean When true , your application is automatically deployed when you generate a deploy hook. Setting this property on your application requires that you hard-code its value in your application.properties file. Do not set this property if you want to avoid hard-coding its value. Instead, use the -Ddekorate.deploy=true option when deploying your application with Maven false

Commands:
<project> <dependencies> <dependency> <!-- The OpenShift Spring Starter automatically imports the "io.dekorate:openshift-annotations" dependency. --> <groupId>io.dekorate</groupId> <artifactId>openshift-spring-starter</artifactId> <version>USD{dekorate.version}</version> </dependency> </dependencies> <project>
package org.acme; @SpringBootApplication public class Application { }
mvn clean package
<project> <dependencies> <dependency> <groupId>io.dekorate</groupId> <artifactId>openshift-spring-starter</artifactId> <version>USD{dekorate.version}</version> </dependency> </dependencies> <project>
package org.acme; import io.dekorate.openshift.annotation.OpenshiftApplication; // include the parameter for the number of replicas to @OpenshiftApplication(replicas=2) @SpringBootApplication public class Application { }
dekorate.openshift.replicas=2
mvn clean package
spec: replicas: 2 selector: matchLabels: app: acme
<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> <version>USD{dekorate.version}</version> </dependency> </dependencies> <project>
mvn clean package
<project> <dependencies> <dependency> <groupId>io.dekorate</groupId> <artifactId>openshift-spring-starter</artifactId> <version>USD{dekorate.version}</version> </dependency> </dependencies> <project>
mvn clean install -Ddekorate.build=true
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
<project> <dependencies> <dependency> <groupId>io.dekorate</groupId> <artifactId>openshift-spring-starter</artifactId> <version>USD{dekorate.version}</version> </dependency> </dependencies> <project>
package io.dekorate.example.sbonopenshift; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; @SpringBootApplication public class Main { public static void main(String[] args) { SpringApplication.run(Main.class, args); } }
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"; } }
mvn clean install -Ddekorate.deploy=true