Cloud-Native Architecture / Microservice Template

Non Functional Requirements Template

1. Java 23
2. SpringBoot 3.4.1
3. Jakarta EE 10

Cloud-native (or microservice) architecture is an approach to application design in which software is broken down into small, independent services that communicate through lightweight APIs, enabling more agile development, scalability, and resilience. Rather than running a single monolithic codebase, each microservice can be developed, deployed, and scaled independently.

This decomposition—often containerized and orchestrated using tools such as Kubernetes—allows teams to quickly iterate on features, take advantage of cloud-native capabilities (like auto-scaling and automated deployments), and release updates with minimal disruption to the entire system. According to the Cloud Native Computing Foundation (CNCF), this approach fosters loosely coupled systems that are resilient, manageable, and observable, combined with robust automation (CNCF, 2023).

Key Features of Microservice (Sources: CNCF, 2023; Fowler, 2014):

1. Service Independence: Each microservice is autonomous, allowing for separate development, deployment, and scaling without affecting others.
2. Containerization: Services are commonly packaged in containers (e.g., Docker), providing consistency across different environments and efficient resource utilization.
3. Lightweight Communication: Microservices communicate via lightweight protocols (often HTTP/REST or gRPC), reducing overhead and complexity.
4. Scalability: Independent scaling of services ensures you can allocate resources exactly where needed, improving performance and cost-efficiency.
5. Continuous Delivery and Deployment: Automation enables frequent, reliable releases to production while minimizing disruption.
6. Resilience: Failure of one service doesn’t necessarily bring the entire system down, as microservices are loosely coupled and can handle faults gracefully.

References

• CNCF. (2023). What is Cloud Native? https://www.cncf.io/blog/2023/02/03/what-is-cloud-native/
• Fowler, M. (2014). Microservices. https://martinfowler.com/articles/microservices.html

What the Template Provides out of the box

1. Security Auth/Authorization using AOP and Filters
2. Exception Handling with Exception Framework using AOP ( ..microservice.adapters.aop)
3. Log Management using AOP (json and text formats) using Logback (...adapters.filters)
4. Standardized REST Responses (...domain.models.StandardResponse)
5. Security using JWT Tokens / KeyCloak Auth (...microservice.adapters.security, ...microservice.security)
6. Encrypting Sensitive Data using Encryption Algorithms (...microservice.security)
7. JPA configurations for H2 and PostgreSQL (...server.config)
8. Observability Using Micrometer, Prometheus and Open Telemetry.
9. Database Password Encryption using Jasypt. Checkout the shell programs encrypt and decrypt.
10. Digital Signatures using Standard Java Cryptography.
11. Open API based Swagger API Docs (...microservice.adapters.controllers)

How to Setup and use the template

Encrypting Database Passwords for the Property Files

This microservice template offers a range of built-in functionalities. To simplify the demonstration of various features, an encrypted password is utilized for connecting to H2 and PostgreSQL databases. The template includes utilities for encrypting and decrypting passwords, ensuring that the encryption key is securely stored outside the application’s runtime context.

To know more about how to setup these passwords (for H2 & PostgreSQL) and environment variables checkout Session 1.2

Encrypted H2 (In Memory) Database Password. Uses H2 database in Dev (Profile) mode. Encrypted PostgreSQL Database Password. Uses PostgreSQL DB in Staging & Prod (profile) mode. Password can be decrypted only using an Encryption Key stored in System Enviornment variable

If the Quality Gate check fails, it's because the password is encrypted within the application’s properties file, with the encryption key stored externally, outside the application’s context.

However, quality standards mandate that passwords should be securely stored in a vault, such as HashiCorp Vault, for enhanced security.

Microservice Package Structure

io.fusion.air.microservice

1. adapters (All the Implementations from App/Service perspective)
2. domain (All Entities, Models, Interfaces for the implementations)
3. security (All Security related modules)
4. server (Managing the Service - from a server perspective, Setups (Cache, DB, Kafka etc, Configs)
5. utils (Standard Utilities)

Security Framework with Spring Security, JWT, KeyCloak, & Cryptography

1. Adapters Package (left side) – Integrations with Spring MVC, AOP, Filters, and Web Security.
2. Security Package (right side) – Core libraries and utilities for JWT creation, validation, cryptography, etc.

1. Adapters Package (io.fusion.air.microservice.adapters)

A. Filters Package

1. JWT Auth Filter

• A javax.servlet.Filter (or jakarta.servlet.Filter) that intercepts requests early in the servlet chain.
• It extracts JWTs from headers, validates or parses them, and stores user claims in a ClaimsManager for downstream use.

2. Log Filter

• Another servlet filter for logging requests. Possibly logs details like request URIs, IP addresses, timings, etc.

3. Security Filter

• A filter that enforces security rules at the servlet layer (e.g., blocking requests with invalid data or applying firewall rules).
• Complements or replaces Spring Security’s default filter chain in some scenarios. These filters run before the DispatcherServlet. They can reject or manipulate requests if authentication or security checks fail.

B. Spring Framework (DispatcherServlet)

• DispatcherServlet is the central Spring MVC component that routes incoming HTTP requests to the appropriate controller endpoints. Checkout the API flow in Part 4 of my Java 23 series.

C. AOP Package

• Authorization Request Aspect
• A Spring AOP aspect that intercepts controller or service methods to enforce authorization rules.
• Typically checks whether the user has the necessary roles/permissions based on JWT claims or custom annotations (@AuthorizationRequired).

Checkout the Java 23, SpringBoot 3.3.4, & Jakarta EE 10 for more details on this topic.

Template Tutorials - Java 23, SpringBoot 3.3.4 & Jakarta 10 Series

1. Java 23, SpringBoot 3.3.4 & Jakarta 10 — Part 1
2. Java 23, SpringBoot 3.3.4: AOP Exception Handling — Part 2
3. Java 23, SpringBoot 3.3.4: Logback Setup — Part 3
4. Java 23, SpringBoot 3.3.4: Log/Events: API Flow & Logging — Part 4
5. Java 23, SpringBoot 3.3.4: Metrics: Micrometer, Prometheus, Actuator — Part 5
6. Java 23, SpringBoot 3.3.4: Metrics: Micrometer & AOP — Part 6
7. Java 23, SpringBoot 3.3.4: Tracing: OpenTelemetry — Part 7
8. Java 23, SpringBoot 3.4.1: Tracing: OpenTelemetry In Action — Part 8 Coming Soon
9. Java 23, SpringBoot 3.4.1: Filters: Security, Log — Part 9 Coming Soon
10. Java 23, SpringBoot 3.4.1: AOP: Spring Security — Part 10 Coming Soon
11. Java 23, SpringBoot 3.4.1: CRUD — Part 11 Coming Soon
12. Java 23, SpringBoot 3.4.1: CRUD Queries & Page Sort — Part 12 Coming Soon

Pre-Requisites

1. SpringBoot 3.3.4
2. Java 23
3. Jakarta EE 10 (jakarta.servlet., jakarta.persistence., javax.validation.*)
4. Maven 3.8.6
5. Git 2.31

1. Setting up the Template

Step 1.1 - Getting Started

1. git clone https://github.com/arafkarsh/ms-springboot-334-vanilla
2. cd ms-springboot-334-vanilla

Step 1.2 - Setup Encrypted DB Password in Property files

1.2.1 Encrypt the Database passwords for H2 and PostgreSQL

If you dont encrypt the password with your Encryption Key it will throw an exception saying unable to decrypt the password. Here are the steps to encrypt the password.

Run the follwing command line option

$ source encrypt your-db-password your-encrypton-key

Your encryption key will be set in the following Environment variable. SpringBoot Will automatically pickup the encryption key from this environment variable.

JASYPT_ENCRYPTOR_PASSWORD=your-encrypton-key

1.2.2 Update the Database passwords for H2 and PostgreSQL in the Property files

Update the property file in the local file

spring.datasource.password=ENC(kkthRIyJ7ogLJP8PThfXjqko33snTUa9lY1GkyFpzr7KFRVhRVXLOMwNSIzr4EjFGAOWLhWTH5cAWzRzAfs33g==)

AND

• the property template in src/main/resources/app.props.tmpl
• dev src/main/resources/application-dev.properties

spring.datasource.password=ENC(kkthRIyJ7ogLJP8PThfXjqko33snTUa9lY1GkyFpzr7KFRVhRVXLOMwNSIzr4EjFGAOWLhWTH5cAWzRzAfs33g==)

AND the property files for

• staging src/main/resources/application-staging.properties
• prod src/main/resources/application-prod.properties

spring.datasource.password=ENC(/J0gRHIdlhBHFwpNo3a+1q3+8Uig5+uSNQHO/lCGOrfg/e8Wt2o3v1eC4TaquaDVGREOEFphpw1B84lOtxgeIA==)

1.2.3 - Generating the Encrypted Text from REST Endpoint

You can use the following REST Endpoint to encrypt the sensitive data. This will work only after setting the environment variable JASYPT_ENCRYPTOR_PASSWORD and creating the first DB password using the command line options.

Step 1.3 - Compile (Once your code is ready)

1.3.1 Compile the Code

Execute the "compile" from ms-springboot-334-vanilla

1. compile OR ./compile (Runs in Linux and Mac OS)
2. mvn clean; mvn -e package; (All Platforms)
3. Use the IDE Compile options

1.3.2 What the "Compile" Script will do

1. Clean up the target folder
2. Generate the build no. and build date (takes application.properties backup)
3. build final output SpringBoot fat jar and maven thin jar
4. copy the jar files (and dependencies) to src/docker folder
5. copy the application.properties file to current folder and src/docker folder

In Step 1.3.2 application.properties file will be auto generated by the "compile" script. This is a critical step. Without generated application.properties file the service will NOT be running. There is pre-built application properties file. Following three property files are critical (to be used with Spring Profiles)

1. application.properties
2. application-dev.properties
3. application-staging.properties
4. application-prod.properties

Step 1.4 - Run the Application

1.4.1 - Spring Profiles

1. dev (Development Mode)
2. staging (Staging Mode)
3. prod (Production Mode)

1.4.2 - Start the Service

1. Linux or Mac OS - Profiles (dev, staging, or prod)

run 

run dev 

run staging 

run prod 

2. All Platforms - Profiles (dev, staging, or prod)

 mvn spring-boot:run -Dspring-boot.run.profiles=dev

 mvn spring-boot:run -Dspring-boot.run.profiles=staging

 mvn spring-boot:run -Dspring-boot.run.profiles=prod

3. Microsoft Windows - Profiles (dev, staging, or prod)

java -jar target/ms-vanilla-service-*-spring-boot.jar --spring.profiles.active=dev  -Djava.security.manager=java.lang.SecurityManager -Djava.security.policy=./vanilla.policy

java -jar target/ms-vanilla-service-*-spring-boot.jar --spring.profiles.active=staging  -Djava.security.manager=java.lang.SecurityManager -Djava.security.policy=./vanilla.policy

java -jar target/ms-vanilla-service-*-spring-boot.jar --spring.profiles.active=prod  -Djava.security.manager=java.lang.SecurityManager -Djava.security.policy=./vanilla.policy

1.4.3 - Test the Service

1. test OR ./test (Runs in Linux or Mac OS)
2. Execute the curl commands directly (from the test script)

1.4.4 - Running through IDE

Check the application.properties (in the project root directory) to change the profile Ex. spring.profiles.default=dev

1.4.5 - $ run prod (Result)

1.4.6 - MS Cache Swagger UI Docs for Testing

Step 1.5 - Testing the APIs Using Swagger API Docs or Postman

To test the APIs (in secure mode - you will see a lock icon in the Swagger Docs). These test tokens are generated based on the flag server.token.test=true in the application.properties file. (Change the app.props.tmpl if you want to change in the build process.) In the Production environment, this flag should be false. These tokens can be generated only in an Auth Service. All the services need not generate these tokens unless for the developers to test it out. In a real world scenario, disable (Comment out the function generateTestToken() from the code java file ServiceEventListener.java in the package documentation io.fusion.air.microservice.server.service) this feature for production environment.

Step 1.5.1: Copy the Auth Token

Step 1.5.2: Click on the Authorize Button (Top Left the Swagger UI)

Step 1.5.3: Enter the Token and Click Authorize

Step 1.5.4: Enter the Refresh Token & Tx Token with every request that needs authorization

Step 1.6 - Import Swagger API Docs Into Postman

What is Postman?

• Postman is an API platform for building and using APIs. Postman simplifies each step of the API lifecycle and streamlines collaboration so you can create better APIs—faster.
• Download Postman for Windows, Mac & Linux. https://www.postman.com/

Step 1.6.1: Swagger Open API 3.0 Docs JSON Format

Step 1.6.2: Import Into Postman - Set the Link

Step 1.6.3: Import Into Postman - Confirm

Step 1.6.4: Test the API

Step 1.7 - JWT Token Validation example

1.7.1 Public API (Without Token Validation) - ...adapters.controllers.open.*

1.7.2 Secure API with a Single Token (Primarily to be used by ADMIN)

1.7.3 Secure API with an Additional Tx Token which contains App Specific Claims.

1.7.4 All the APIs under the Secure Package (under ...adapters.controllers.secured.*)

2. CRUD Operations Demo & Error Handling

2.1 CRUD Operations

2.1.1 GET Query Execution and Fallback Data

2.1.2 POST Create Data - Product 1

2.1.3 POST Create Data - Product 1 : Result

2.1.4 POST Create Data - Product 2

2.1.5 POST Create Data - Product 3

2.1.6 GET All the Data (Created in Steps 2.2 - 2.5)

2.1.7 GET Single Record

2.1.8 PUT Update the Product Price

2.1.9 PUT Update the Product - DeActivate the Product > Set isActive Flag = False

2.1.10 State of the Records after Inserts and Updates

2.2 Error Handling for SpringBoot App / Service

2.2.1 Error Handling - Invalid Input

2.2.2 Error Handling - Invalid Input - Result

2.2.3 Error Handling - Invalid Input - Field Validations

2.2.4 Error Handling - Invalid Input - Field Validations - Result

2.2.5 Error Handling - Version Mismatch based o JPA @Version Annotation

2.3 Log Management

2.3.1 Log Success Messages

2.3.2 Log Failure Messages

3. Configure the Template: Setup Org, Service, & Container Name, Versions, API Path in app.props.tmpl

1. git clone https://github.com/arafkarsh/ms-springboot-334-vanilla.git
2. cd ms-springboot-334-vanilla

Update the Properties Template

1. Update the Org Name in src/main/resources/app.props.tmpl file (service.org)
2. Update the Microservice name in src/main/resources/app.props.tmpl file (service.name)
3. Update the API Version in src/main/resources/app.props.tmpl file (service.api.version)
4. Update the API Name in src/main/resources/app.props.tmpl file (service.api.name)
5. Update the Container Name in src/main/resources/app.props.tmpl file (service.container)
6. Update the Server Version src/main/resources/app.props.tmpl file (server.version) Pom File 0.4.0 app.props.tmpl Microservice Server Properties server.version=0.4.0

Sample Property File Template

When you change the version in POM.xml, update that info in src/main/resources/app.props.tmpl - server.version property also.

4. Docker Container Setup

Step 4.1 - Verify Container Name and Org Name

1. Verify the Org Name in src/main/resources/app.props.tmpl file (service.org)
2. Verify the container name in src/main/resources/app.props.tmpl file (service.container)
3. Verify the microservice name in src/main/resources/app.props.tmpl file (service.api.name)

Step 4.2 - Build the image

1. build (Build the Container)
2. scan (Scan the container vulnerabilities)

Step 4.3 - Test the image

1. start (Start the Container)
2. logs (to view the container logs) - Wait for the Container to Startup
3. Check the URL in a Browser

Step 4.4 - Push the image to Container Cloud Repository

Update the Org Name in src/main/resources/app.props.tmpl file (service.org) Setup the Docker Hub or any other Container Registry

1. push (Push the Container to Docker Hub)

Step 4.5 Other Commands

1. stop (Stop the Container)
2. stats (show container stats)

(C) Copyright 2021-25 : Apache 2 License : Author: Araf Karsh Hamid

 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.