DEV Community: Julien Dubois

Announcing NubesGen, an Open Source tool to automate Azure deployments

Julien Dubois — Wed, 05 May 2021 14:22:07 +0000

Going to production on Azure is only one git push away

What is NubesGen?

NubesGen https://nubesgen.com/ is a Microsoft Open Source project, which provides a Web application that generates an Azure infrastructure graphically: you select easy-to-understand options ("an application server", "a PostgreSQL database"), and it'll generate a state-of-the-art Terraform configuration that you can import and tweak in your project.

Using GitOps practices, NubesGen can also fully automate applying that configuration: it provides one cloud infrastructure per branch in your project, and will build and deploy your code to this infrastructure.

As a result, you can just git push your code to Azure and both the infrastructure and the application deployment are handled for you. No need to go to the Azure portal, or learn how to configure everything!

Video tour of NubesGen, in less than 15 minutes

What is the state of the project?

NubesGen is Open Source, and uses the MIT license.

It's currently under development, but we already have a good number of people who tested it, which makes us confident to do a first technical preview release.

You can already use it:

There is a running instance of the project at https://nubesgen.com/
The source code is available at https://github.com/microsoft/nubesgen/, as well as pre-built packages and Docker images on our release page.

Contributing to the project

Currently NubesGen supports Azure App Service and Azure Functions, as well as some of their most popular options (MySQL, PostgreSQL, Blob Storage, Redis, Cosmos DB, etc.). We're looking for feedback and contributions to improve this existing support first.

Once we have a stable code base for those popular options, we'll then expand the number of supported services, with offers like Azure Kubernetes Services, Azure Spring Cloud, Azure Service Bus. So if you know any of those technologies and are willing to contribute, don't hesitate to ping us and join!

And as any new project, we'll be delighted to count you as one of our stargazers at https://github.com/microsoft/NubesGen/stargazers!

What's next?

The best way to learn about NubesGen is to go to https://nubesgen.com/ and use it!

New Java learning path on Microsoft Learn

Julien Dubois — Thu, 10 Dec 2020 15:27:09 +0000

MS Learn is Microsoft's flagship learning platform, delivering free online tutorials for everyone to study, understand and deliver great technical projects to the cloud.

Today, we deliver a Java learning path on MS Learn, so all Java developers can benefit from the power of Azure.

Java at Microsoft is huge

It's been a long journey for Java at Microsoft. Java is currently used in many products and services by Microsoft: from Minecraft, to LinkedIn and Yammer, and Azure itself, where we have several Java specific offers like Azure Spring Cloud (for Spring developers) and JBoss EAP on App Service (for Jakarta EE developers).

Azure product groups and Microsoft's Java developer advocacy team are building this Java learning path. If you want to learn more about Java on Azure, you can head up to our YouTube channel, where we have interviews of Java Champions, tutorials, online conference sessions...

The MS Learn Java learning path

The Java learning path is for Java developers who want to better understand what they can achieve with Azure. It starts with the basics of Azure, and will make you discover our main services relevant for Java developers.

Here is the Java learning path on MS Learn, in which you will be able to find the following modules:

Introduction to Java on Azure will give you an overview of Java applications and related Azure services.
Choose the right Azure service for deploying your Java application goes into the details of the main Azure services for Java developers, so you can choose the best service depending on your specific needs.
Deploy a Spring Boot app to Azure is for Spring Boot developers who want to deploy their application to Azure.
Deploy a Java web app to Azure is for Jakarta EE developers who want to deploy a JSF application to Azure.
Deploy Spring microservices to Azure is for Spring Boot developers working on microservices architectures.
Build a Java app with cloud-scale NoSQL Cosmos DB is for Java developers who want to use the Cosmos DB NoSQL database on Azure.
Publish a web app to Azure by using the Maven Plugin for Azure App Service focuses on the Maven Azure plugin, and provides a sandbox environment for you to deploy a simple "Hello, world" Java application.
Develop an App using the Maven Plugin for Azure Functions uses the Maven Azure plugin to create and deploy a Java serverless application, running on Azure Functions.

Meet the team

This learning path was created by Java experts at Microsoft, here in alphabetical order:

Sandra Ahlgrimm - @sKriemhild
Ashish Chhabria - @ashishc1
Julien Dubois - @juliendubois
Andy Feldman
Rory Preddy - @rorypreddy
Yoshio Terada - @yoshioterada
Asir Vedamuthu Selvasingh - @asirselvasingh
Nick Walker
Yuchen Wang

What's next?

This learning path is only the beginning! In the next few months, we expect to deliver several more modules for Java developers, covering broad topics like caching (with Azure Cache for Redis), immutable infrastructure (with Terraform), event messaging (with Azure Service Bus), serverless (with Azure Functions), or security (with Azure Active Directory).

If you want to have the latest news on Java on Azure, please follow @JavaAtMicrosoft on Twitter and subscribe to the Java on Azure YouTube channel.

Terraform for Java developers video series

Julien Dubois — Fri, 04 Dec 2020 10:37:32 +0000

Terraform is one of those tools that many people talk about, but which can be a bit frightening for a Java developer.
There are several reasons for this, but mainly it's because Terraform is an infrastructure tool: this is going to create cloud resources for you, which isn't something most Java developers are used to do, and while doing so it's going to cost you some money.
And obviously, you are afraid that doing a wrong configuration is going to cost you a lot!
This series of videos is made exactly with this issue in mind: using a classical Java project, the Spring Petclinic, we'll gently introduce the most important Terraform concepts, so that at the end you'll be able to deploy with confidence a Spring Boot and MySQL infrastructure to the cloud.

Each video is about 10 minutes long, so they are easy to consume, and they all have subtitles: if you have any issue following them, don't forget to turn those subtitles on!

The final project is avaible on https://github.com/jdubois/spring-petclinic/tree/deploy-to-azure/terraform.

Terraform for Java developers, part (1/4)

In this first video, we describe what Terraform is, and we fork the Spring Petclinic project (available at https://github.com/spring-projects/spring-petclinic) to add a Terraform configuration.

Terraform for Java developers, part (2/4)

In this second video, we create a MySQL server and configure it using Terraform, learning how Terraform manages state, and how it can create or update resources.

Terraform for Java developers, part (3/4)

In this third video, we talk about best practices to improve your Terraform code, as well as tooling to facilitate understanding your code.

Terraform for Java developers, part (4/4)

In this fourth video, we complete our Terraform configuration and add a Java application service, configure our Spring Boot project to be deployed on Azure, run everything in the cloud, and finish by destroying our infrastructure.

Don't forget to subscribe to the Java on Azure YouTube channel for more Java tutorials and content!

Java distributed caching in the cloud with the new Azure discovery plugin for Hazelcast

Julien Dubois — Tue, 14 Apr 2020 08:36:25 +0000

Many thanks to Alparslan Avci and Mesut Celik from Hazelcast for their very precious help when writing this blog entry!

The need for distributed caching in the cloud

Scaling stateless applications in the cloud is easy, scaling a database is a lot more trouble.

If you want to run applications efficiently in the cloud, you'll need to use a caching mechanism: if you don't cache your data, any spike in traffic will automatically result in a spike in your database requests. And your database is probably the part of your architecture that scales less, in particular if you're using an SQL database. Also, this is probably the most costly part of your architecture, so even if it does scale up, your bill is going to scale up too, and you probably don't want that.

That's why in JHipster, we have worked very hard, for years, and with several major cache providers, in order to give you the best solution possible.

Typically, we have two types of usage for cache:

Hibernate second-level cache (often called "L2 cache"), that directly caches your entities.
Spring Cache abstraction, that will cache more complex business objects.

Both have their advantages, and that's why we set them both up in JHipster.

Then, we have different caching implementations, that fall in the following 3 main categories:

Local caches (like Caffeine): they are the most efficient, but they don't scale across nodes. So when you add more application nodes, you will have cache synchronization issues, and you will see old (stale) data.
Remote caches (like Redis): they use a remote server, so they will scale up easily, but their performance is often order of magnitudes slower (to get an object you need to fetch it over the network, and then deserialize it - when for a local cache you are just doing a pointer to an object which is already inside your heap).
Distributed caches (like Hazelcast): they would act as a local cache, but are able to scale when you add application nodes thanks to a distributed synchronization mechanism. High-end solutions like Hazelcast can also work as remote caches, but will benefit from having a local cache (often called "near cache") for improved performance. Those look like the best solution, but they come at a price: they are more complex to set up! Years ago, people would use multicast to find nodes automatically, but in the cloud you cannot use such a network feature, and you need a specific mechanism for the nodes to find each other.

In this post, we're going to have a look at a new solution, the Azure discovery plugin for Hazelcast: it uses a specific Azure API in order to scale automatically, solving the complex issue of configuring the distributed cache.

Introduction to the new Azure discovery plugin for Hazelcast

The Azure discovery plugin for Hazelcast is an Open Source project developed by Alparslan Avci from Hazelcast, and available on GitHub at https://github.com/hazelcast/hazelcast-azure.

Such a plugin has been released many years ago, so you might find information about an older version: this new release is a complete rewrite, that is much better has it uses the Azure Instance Metadata service.

The Azure Instance Metadata service is a REST Endpoint accessible to all IaaS virtual machines created via the Azure Resource Manager. The endpoint is available at a well-known non-routable IP address (169.254.169.254) that can be accessed only from within a virtual machine.

The Azure discovery plugin for Hazelcast will need to authenticate to that REST endpoint, and then will query it to know which other virtual machines should be in the cluster.

Installing the Azure discovery plugin for Hazelcast

All the code shown in this article comes from a specific Open Source project that I have created, and which you can check at https://github.com/jdubois/jhipster-hazelcast-azure.

This is a modified JHipster application, as this plug in only works with the newly-released Hazelcast 4, which is not does not fully supports Spring Boot yet (Spring Boot Actuator isn't compatible with Hazelcast 4, but this will fixed with the next Micrometer release).

To install Hazelcast 4 and the new Azure discovery plugin for Hazelcast, you need to add them as dependencies in your pom.xml file:

<dependency>
    <groupId>com.hazelcast</groupId>
    <artifactId>hazelcast</artifactId>
    <version>4.0</version>
</dependency>
<dependency>
    <groupId>com.hazelcast</groupId>
    <artifactId>hazelcast-hibernate53</artifactId>
    <version>2.0.0</version>
</dependency>

As we are not going to use it, if you have the Spring Boot support for Hazelcast in your dependencies (which would be the case for a JHipster application), you can remove this dependency, namely com.hazelcast:hazelcast-spring.

Configuring the Azure discovery plugin for Hazelcast

For this example, we will use JHipster's CacheConfiguration object, but greatly simplify it so you can use it easily in any classical Spring Boot application, and also to make it easier to understand:

package com.mycompany.myapp.config;

import com.hazelcast.config.Config;
import com.hazelcast.core.Hazelcast;
import com.hazelcast.core.HazelcastInstance;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;

@Configuration
public class CacheConfiguration {

    private final Logger log = LoggerFactory.getLogger(CacheConfiguration.class);

    private final Environment env;

    public CacheConfiguration(Environment env) {
        this.env = env;
    }

    @PreDestroy
    public void destroy() {
        log.info("Closing Cache Manager");
        Hazelcast.shutdownAll();
    }

    @Bean
    public HazelcastInstance hazelcastInstance() {
        log.debug("Configuring Hazelcast");
        Config config = new Config();
        config.setInstanceName("hazelcasttest");
        // If running in Azure, use the Hazelcast Azure plugin
        if (env.acceptsProfiles(Profiles.of("azure"))) {
            log.info("Configuring the Hazelcast Azure plug-in");
            config.getNetworkConfig().getJoin().getMulticastConfig().setEnabled(false);
            config.getNetworkConfig().getJoin().getAzureConfig().setEnabled(true);
        }
        return Hazelcast.newHazelcastInstance(config);
    }
}

The important part here is the following line:

config.getNetworkConfig().getJoin().getAzureConfig().setEnabled(true);

There are many more available configuration options detailed at https://github.com/hazelcast/hazelcast-azure, but that default setup is already good enough for most usual needs: the plugin will use the Azure Instance Metadata service to find other virtual machines in the same resource group, and will create a cluster with all of them.

Some important notes on this cluster:

It will use the default private Virtual Network that is created when creating the Virtual Machines. That means that all communications will be hidden to the outside world, and that you don't need to configure a firewall for it (it is already open by default on that private network).
This network uses the 10.0.0.0\24 IP addresses, so you will probably see your Virtual Machines using IPs like 10.0.0.4 and 10.0.0.5 to communicate.

Configuring the virtual machines to access the Azure Instance Metadata service

The plugin will only work if it can query the Azure Instance Metadata service and get the list of the other virtual machines that are configured in the current resource group.

You will need to go to the Azure Portal, and for each virtual machine you will need to do the following operations.

Enable a system assigned managed identity to each virtual machine

For each virtual machine, look at the Identity menu item in the left menu, and enable a "System assigned" identity:

This will allow you to give roles to that virtual machine.

Give the "READ" role on the resource group to each virtual machine

Still in the Azure Portal, go the resource group in which your virtual machines have been created.

In the left menu, select Access control (IAM), and give the Reader role to all the Virtual Machines that you want in your cluster:

Running everything and testing the cluster

Now that everything is configured, you can run your Spring Boot applications in each Virtual Machine.

If everything is correctly set up, each of them should have Hazelcast starting, and the nodes should all join the same cluster, like in this screenshot below:

In that example, we can see that we have 2 nodes, using the private network that we described above (the IPs are 10.0.0.4 and 10.0.0.5). You can see that the current node is 10.0.0.4 (it has a this next to it), and obviously you'll see the opposite on the other node (10.0.0.4 ... this).

If you want to test that the cluster is working fine, an easy solution with the sample application that we created on https://github.com/jdubois/jhipster-hazelcast-azure is to do the following:

Open up port 8080 on the public IP of each virtual machine
Access each application using that public IP
Modify some cached data on one node (as we use the Hibernate L2 cache, all database data is cached), and verify on the other node that the data changed accordingly

Conclusion

A distributed cache is the best solution to scale cloud-native applications, but configuring it in the cloud can be challenging: the new Azure discovery plugin for Hazelcast is a great solution to solve that issue efficiently.

This solution will work great when running virtual machines in Azure, but how will it work with more advanced Azure services?

If you use Azure App Services, the PaaS offering from Azure, you won't be able to use the private interface to connect nodes. However, you will still be able to use the Hazelcast Azure Discovery Plugin with Hazelcast Client to connect to a Hazelcast cluster running in Azure VMs. Documentation is available here.
If you use Azure Kubernetes Service, have a look at the Hazelcast Helm Chart and the Hazelcast Kubernetes Operator.
If you use JHipster with Azure Kubernetes Service or Azure Spring Cloud, you should have a look at how JHipster uses the JHipster Registry to discover nodes, which will work in the same way as the Azure discovery plugin for Hazelcast, using Eureka to discover nodes instead of the Azure Instance Metadata Service.
If you want a pure Java solution, but do not use JHipster, have a look at the Hazelcast Eureka plugin that works the same way as the JHipster Registry, using Eureka to discover nodes.

If you want to check the code used in this article, it is available at https://github.com/jdubois/jhipster-hazelcast-azure.

Spring Boot performance benchmarks with Tomcat, Undertow and Webflux

Julien Dubois — Mon, 06 Apr 2020 13:41:28 +0000

Tomcat vs Undertow vs Webflux

JHipster is used by thousands of people to generate production-ready Spring Boot applications. We've been using Undertow for years, with great success, but as we are planning for JHipster 7 we started discussing migrating away from Undertow.

This is the kind of discussion which happens very frequently in the JHipster community: with so many people contributing, we often test and try alternatives to our current approach.

We ended up discussing about 3 different application servers:

Undertow, from Red Hat/IBM: it is known for being lightweight, and we have years of (good) experiences with it.
Tomcat, from the Apache Software Foundation: by far, the most popular option. It is also the default solution coming with Spring Boot.
Webflux, from VMWare: this isn't really an application server, this is Spring Webflux running on top of Netty. This implies using reactive APIs, which are supposed to provide better performance and scalability. It's a whole different approach, which is also supported by JHipster.

The test applications

I created a performance benchmarks GitHub repository, with applications generated by JHipster.

Those applications are more complex and realistic than simple "hello, world" applications created with Spring Boot. For instance, they use Spring Security and Spring Boot Actuator: those libraries will impact application start-up time and performance, but they are what you would use in the real world.

Then, they are not as complex as they could be: I didn't configure a database or an application cache. Those would make running performance tests a lot more complicated, and wouldn't add any specific value: as we would use the same drivers or caching solution with all three application servers, we would end up testing the same things.

In the GitHub repository, you will find 4 directories: one for each application, and one with the performance tests.

Using Azure Virtual Machines for the test

As we needed to set up a test environment, using the cloud was obviously the best solution! For this test, I have created 2 virtual machines, with their own private network.

I used:

2 Azure Virtual Machines, using their default configuration called "Standard D2s v3" (2 vcpus, 8 GiB memory).
1 private Azure Virtual Network.

One of the machines was hosting the application server, and the other one was used to run the performance test suite.

The VMs were created using the Ubuntu image provided by default by Azure, on which I installed the latest LTS AdoptOpenJDK JVM (openjdk version "11.0.6" 2020-01-14).

To configure your virtual machines easily, I maintain this script which you might find useful: https://github.com/jdubois/jdubois-configuration.

Start-up time

Start-up time is all the rage now, but on JHipster we usually give more importance to runtime performance. For example, that's the reason why we use Afterburner: this slows down our start-up time, but gives about 10% higher runtime performance over a "normal" Spring Boot application.

Here are the results after 10 rounds, for each application server:

	Undertow	Tomcat	Webflux
1	4,879	5,237	4,285
2	4,847	5,125	4,225
3	4,889	5,103	4,221
4	5,013	5,129	4,232
5	4,84	5,134	4,271
6	5,007	5,141	4,191
7	4,868	5,214	4,147
8	4,826	5,032	4,251
9	4,856	5,069	4,274
10	4,908	5,078	4,128
Mean	4,8933	5,1262	4,2225
Difference		4,76%	-13,71%

As expected, Undertow is lighter than the competition, but the difference is quite small.

The runtime performance test

For our runtime performance, we needed to have a specific test suite.

The performance test were written in Scala for the Gatling load-testing tool. They are pretty simple (we are just doing POST and GET requests), and are available here.

This test does the following:

Each user does 100 GET requests and 100 POST requests, every 1.5 seconds.
We will have 10,000 users doing those requests, with a ramp up of 1 minute.

The objective here is to stay under 5,000 requests per second, as when you go above that level you will usually need to do some specific OS tuning.

Undertow performance benchmarks

The Undertow results were quite good: it could handle the whole load without losing one single request, and it was delivering about 2,700 requests per second:

The response time was quite slow, with nearly all users having to wait about 3 seconds to get a response. But it was also quite stable (or "fair" for all users), as the 50th percentile is not that far away from the 99th percentile (or even the "max" time!):

Tomcat performance benchmarks

Tomcat had about 5% of its requests failing:

Those failures explain why the graph below doesn't look very good. Also, it was only delivering about 2,100 requests per second (compared to 2,700 requests per second for Undertow):

Last but not least, the response time was good for about 10% of the requests, but it was much worse than Undertow at the 95th and 99th percentile, which shows that it could not handle all requests correctly. That's also why it had such a bad standard deviation (2,760 seconds!):

Webflux performance benchmarks

Webflux had about 1% of its requests failing:

Those failures were at the beginning of the tests, and then the server could correctly handle the load: it looks like it had to trouble to handle the traffic growth because it was quite sudden, and then stabilized.

Then, we can notice that once stabilized, Webflux had some strange variations - this is why we see all those peaks in the blue graph below: it would go suddenly from handling nearly 5,000 requests/second to less than 1,000 requests/second. In average, it was handling a bit more than 2,700 requests/second, so that's the same as Undertow, but with big variations that Undertow didn't have.

The variations that we noticed in the previous graph also explain why, compared to Undertow, Webflux has a lower 50th percentile, but a higher 95th percentile. And that's also why its standard deviation is much worse:

Conclusion

Undertow definitely had impressive results in those tests! Compared to Tomcat, it proved to start up faster, handle more load, and also had a far more stable throughput. Compared to Webflux, which has a completely different programming model, the difference was less important: Webflux started faster, but had 1% of errors at the beginning of the test - it looks like it had some trouble to handle the load at the beginning, but that wasn't a huge issue.

On JHipster, this is probably one of the many different choices that we have made, which make JHipster applications much faster and more stable than classical Spring Boot applications. So this performance test is definitely very important in our future decision to keep Undertow or move away from it. If you'd like to participate in the discussion, because you ran more tests or have any good insight, please don't hesitate to comment on our "migrating away from Undertow" ticket, or on this blog post.

Using the new Gradle plugin for Azure Functions to deploy Spring Boot serverless applications

Julien Dubois — Tue, 31 Mar 2020 14:36:21 +0000

Introducing the new Gradle plugins for Azure

For building and deploying Java projects, Azure always had great Maven support, but it was lacking Gradle support. As many people love Gradle, in particular when building complex projects, I was thrilled to learn that a new set of Gradle plugins were being developed! They will all be Open Source, and their code will be available on GitHub at https://github.com/microsoft/azure-gradle-plugins.

The first plugin to be released is the one for Azure Functions, at https://github.com/microsoft/azure-gradle-plugins/tree/master/azure-functions-gradle-plugin. Azure Functions is the Azure serverless offer, and you can use it to run your Java workloads in a managed, event-driven, fully scalable and inexpensive environment.

If you want to run this Gradle plugin for a simple Java serverless application, the full documentation is available on the Microsoft Docs website. This is good for a simple Java application, which you would use for a very simple Function, but what about more complex applications, the ones that typically would benefit more from using Gradle?

Running Spring Boot in a serverless environnement

Thanks to Microsoft's work with Pivotal/VMWare, you can run Spring Boot on Azure Functions using the Spring Cloud Function project, which has specific Azure support.

If you want to test Spring Cloud Function and Azure Functions, I maintain the official sample application at https://github.com/Azure-Samples/hello-spring-function-azure. This is using Maven by default, and in this blog post we are going see how to use it with the new Gradle plugin.

Using the new Gradle plugin to deploy Spring Boot to Azure Functions

I have created a specific gradle branch in the official sample project, which you can check at https://github.com/Azure-Samples/hello-spring-function-azure/tree/gradle.

With that code, you will be able to use the new Azure Gradle plugin to deploy a Spring Cloud Function application to Azure Functions.

It uses one specific trick to have Azure Functions run the "Main" Spring Boot class, and this is why we added this block in the build.gradle file:

jar {
    manifest {
        attributes 'Main-Class' : 'com.example.HelloFunction'
    }
}

The block of code above will create a specific Java manifest file, which points to the main Spring Boot class, so that Azure Functions will execute it.

If you look at the Maven version of this application, we are copying a specific local.settings.json file to achieve the same goal (helping Azure Functions find the main class). This solution looks more elegant with Gradle.

Then, the rest of the configuration uses the Gradle plugin normally:

azurefunctions {
    resourceGroup = 'my-spring-function-resource-group'
    appName = 'my-spring-function'
    appSettings {
        WEBSITE_RUN_FROM_PACKAGE = '1'
        FUNCTIONS_EXTENSION_VERSION = '~2'
        FUNCTIONS_WORKER_RUNTIME = 'java'
        MAIN_CLASS = 'com.example.HelloFunction'
    }
    authentication {
        type = 'azure_cli'
    }
    // enable local debug
    // localDebug = "transport=dt_socket,server=y,suspend=n,address=5005"
    deployment {
        type = 'run_from_blob'
    }
}

You will need to configure a specific Azure Resource Group in which your Function will run.
You will need to give a unique appName to your Function: this name should be unique across all of Azure, so usually people prefix it with their username.
We are using the latest FUNCTIONS_EXTENSION_VERSION available at the time of this writing, as it has much better cold start performance when running Java.

Now that the plugin is installed, you can use the following Gradle commands:

gradle azureFunctionsRun

This will run Azure Functions locally, so this is the best way to develop and debug your Function.

gradle azureFunctionsPackage

This will package your application, so it is ready to be deployed to Azure Functions.

gradle azureFunctionsDeploy

This will deploy your Function to Azure Functions, so it is available in the cloud.

The application then works exactly the same as the one built with Maven, of course! So you can test it by doing a cURL request as follows:

curl https://<YOUR_SPRING_FUNCTION_NAME>.azurewebsites.net/api/hello -d "{\"name\":\"Azure\"}"

Screencast: using Spring Boot, JHipster and Azure Spring Cloud together

Julien Dubois — Fri, 13 Mar 2020 09:51:45 +0000

Join me for a live-coding session using Spring Boot, JHipster and Azure Spring Cloud, in order to deliver microservices to cloud efficiently.

Some useful links from the video:

Using Logz.io to make logging Spring Boot Applications easier and faster

Julien Dubois — Mon, 16 Dec 2019 09:59:19 +0000

This blog post is jointly written by Julien Dubois (Microsoft) and Charlie Klein (Logz.io), in order for Spring Boot users to better understand the benefits of using a logs ingestion and analysis tool, like Logz.io.

How logging works in a classical Spring Boot application

Spring Boot applications usually use Logback (official documentation) or Log4J 2 (official documentation) to manage application logs.

This configuration is usually modified depending on each project or company’s usage, and it is common (and good) practice to follow the Twelve-Factor App chapter on logging and output everything to the console.

Advanced users, using for example JHipster, typically use some customized version of Logback, which is usually configured in three different ways:

Using the src/main/resources/logback-spring.xml file. For example, here is JHipster’s default configuration: https://github.com/jhipster/jhipster-sample-app/blob/master/src/main/resources/logback-spring.xml.
Using Spring Boot’s configuration file, under the logging.* properties keys. This is documented at https://docs.spring.io/spring-boot/docs/current/reference/html/appendix-application-properties.html and you can also find an example in JHipster’s default Spring Boot configuration file for development: https://github.com/jhipster/jhipster-sample-app/blob/master/src/main/resources/config/application-dev.yml.
At runtime, as Logback can be programmatically reconfigured. For instance, this is what JHipster users do with their custom LoggingConfiguration.java file or when they use their log management screen.

Configuring logs is great, but once they are sent to the console the real interesting work begins: you need to have a system to aggregate and analyze them! In this article, we’ll use Logz.io to understand what needs to be configured, and most importantly what benefit we can expect from such a solution.

Shipping logs to Logz.io

The first step for shipping your logs to Logz.io is adding the Logz.io dependency to your Maven pom.xml file:

<dependency>
    <groupId>io.logz.logback</groupId>
    <artifactId>logzio-logback-appender</artifactId>
    <version>1.0.22</version>
</dependency>

Then, you need to configure your src/main/resources/logback-spring.xml file to use this library:

<configuration>
    <!-- Use shutdownHook so that we can close gracefully and finish the log drain -->
    <shutdownHook class="ch.qos.logback.core.hook.DelayingShutdownHook"/>
    <appender name="LogzioLogbackAppender" class="io.logz.logback.LogzioLogbackAppender">
        <token><your-logz-io-token></token>
        <logzioUrl>https://<your-logz-io-listener-host>:8071</logzioUrl>
        <logzioType>java-application</logzioType>
        <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
            <level>INFO</level>
        </filter>
    </appender>

    <root level="debug">
        <appender-ref ref="LogzioLogbackAppender"/>
    </root>
</configuration>

A good way to ensure your logs made it to the platform is to open up the “Live Tail” tab in the Logz.io platform. After pressing play, you should see a stream of logs showing up in the application. If you don’t, visit the Logz.io log shipping troubleshooting page.

If you want more information, you should follow this more in-depth tutorial (which was co-written by Julien Dubois) at https://docs.microsoft.com/en-us/azure/java/java-get-started-with-logzio.

Analyzing logs with Logz.io

After shipping your logs to Logz.io, the fun part begins.

Logz.io delivers the ELK Stack and Grafana – the most popular open source monitoring solutions in the world – as a fully-managed service so engineers can use the open source they know without the hassle of building or maintaining scalable logging or metrics pipelines themselves. Users can query and visualize their logs and metrics to monitor for production issues, security incidents, user activity, and and many more user-cases. In this section, we’ll focus on Logz.io’s logging capabilities.

Logz.io users interact with logs on a high-powered version of Kibana (the “K” in the “ELK Stack”) which offers engineers broad flexibility to slice and dice their log data. Logz.io users benefit from Kibana’s complete functionality with additional advanced analytical features that make Kibana faster, more integrated, and easier to use. The following tutorial will take place in the “Kibana” tab on the upper toolbar (Box A).

Upon opening Kibana, you can view all logs generated by your environment. According to our queries below (Box B), there were 1.7 million logs generated by “service-10” within the last 2 days.

Obviously, sorting through this list of logs to identify production issues or monitor user activity is impossible. Clicking on the “Patterns” tab (Box C) will cluster similar groups of logs together so you can quickly understand what kind of log data your service is generating without needing to scroll through the entire list of logs. For each pattern, you can see the time, count, ratio (percentage of logs that fall under the pattern), and the pattern itself.

Scrolling through the log patterns, you can quickly query for the most important log data by clicking the “filter out” or “filter in” buttons to the right of every pattern (Box D). In this case, as we scroll down we find a pattern indicating an “SSL Library error” – something that is clearly worth investigating.

After opening up the SSL error pattern, we can see it was flagged as a “Cognitive Insight”. Cognitive Insights leverages AI to cross reference incoming logs against online discussion forums such as StackOverflow and GitHub to identify critical logged events in your environment.

This feature helps us find the needle in the haystack. Upon opening the Insight, we see contextual information around the event and links to the forums that discuss the SSL Error.

Teams can open these links to see how other engineers addressed the issue.

The last bit of information you may want to know about this SSL error is its origin. In other words, what is the actual code producing this issue? To get this information, you can go to the “Insights” tab in the upper right corner.

This graph helps us correlate issues with specific deployments. The colorful lines represent production issues and the grey dotted lines represent recent deployments. As you can see, the SSL error – represented by the blue dot – did not appear until after the “Updating puppet certificate” deployment at 3:20pm on Dec 4th. Therefore, we can conclude that this deployment led to the SSL error so it can quickly be addressed.

With Cognitive Insights and the ability to plot issues on a deployment timeline, you can close the loop with engineers by showing them the root cause and origin of the problem.

See it for yourself!

In addition to the capabilities explored above, you can monitor metrics on Grafana, build your own Kibana visualizations, set alerts, and do a whole lot more.

Learn more about Logz.io here or try it for yourself here.

Configuring the free TLS/SSL certificates on Azure App Service

Julien Dubois — Mon, 02 Dec 2019 09:19:58 +0000

Free TLS/SSL certificates for Azure App Service

Last month, it was announced at MS Ignite that users of Azure App Service would have free, managed TLS/SSL certificates:

Julien Dubois

@juliendubois

Free SSL certificates on Azure App Services! It's one of my most-awaited announcement at MS Ignite!!
azure.microsoft.com/en-us/updates/…

07:35 AM - 05 Nov 2019

8 24

Azure App Service is a very popular Platform-as-a-Service, which supports Docker images as well as many different languages and frameworks. For example, if you are using Java and Spring Boot, I believe it's the easiest way to go to production on Azure. And using TLS/SSL is of course mandatory when going to production!

Configuring those certificates isn't totally obvious, as you probably don't use Azure to manage your DNS: this short guide is here to help you!

Configure your DNS records

Configuring your DNS records is probably the trickiest part, as it will depend on your DNS provider.

Here we will setup a very generic configuration, which should work on most DNS providers. But as a concrete example, we are going to use Gandi, which is a French DNS provider, and which is the one I use for my julien-dubois.com personal website as well as the different JHipster websites.

What you need to do is add a "CNAME" record that will point from your production DNS name to your Azure App Service instance.

For example, here:

My production website will be https://petclinic.julien-dubois.com.
My App Service instance is called jdubois-petclinic, so it is hosted by default on https://jdubois-petclinic.azurewebsites.net.

WARNING: a hostname entry usually ends with a dot (.) unless you specifically want it to be suffixed by the current domain. This is what most DNS provider will require, and this is why in the screenshot we have jdubois-petclinic.azurewebsites.net. (notice the . at the end).

Your DNS provider probably also allow you to configure directly those DNS records, without using a Web control panel. In that case, your DNS entry would look like this:

petclinic 1800 IN CNAME jdubois-petclinic.azurewebsites.net.

Once this configuration is saved, remember that DNS records can take up to 48 hours to propagate, but it is usually much faster.

In order to check the propagation of your record, you can use a tool like https://dnschecker.org/. In our example, you can see on https://dnschecker.org/#CNAME/petclinic.julien-dubois.com that our CNAME record was correctly propagated.

Configure your Azure App Service instance

You can now go to the Azure portal, and select your Azure App Service instance.

"Custom domains" configuration

In the "Custom domains" menu on the left:

Check the "HTTPS Only" box, as there is no need to keep an unsecured HTTP option.
Click on "Add custom domain", and add the domain name you have configured with your DNS provider

The "Validate" button here will check if your DNS record is correct: if you misconfigured your record, or if your record hasn't been propagated yet, this is where you get an error.

"TLS/SSL settings" configuration

In the "TLS/SSL settings" menu on the left, go to the "Private Key Certificates (.pfx)" tab.

Click on "Create App Service Managed Certificate", this will show a specific screen where you can select the domain name you have previously configured:

Click on "Create" and wait a few seconds for your certificate to be created:

Now, still in the "TLS/SSL settings" page, click on the "Bindings" tab:

Click on "Add TLS/SSL Binding", and select the previously generated certificate. You should use "SNI SSL" as it will work on all modern browsers:

Click on "Add Binding", and you're all set up!

You can now enjoy your website using TLS/SSL:

The easy way to deploy a Spring Boot application to production on Azure

Julien Dubois — Thu, 28 Nov 2019 10:58:16 +0000

In this blog post, we are going to deploy a classical Spring Boot application to production on Azure, with a strong focus on ease-of-use, both from a developer and operations perspective.

Why "the easy way"?

While it is fun to use Kubernetes the hard way, if your goal is to deploy and host a Spring Boot application in production, your customer probably doesn't have the time and money to let you work like this.

We are aiming here at deploying and maintaining a production application with as little work as possible:

As a developer, our goal is just to git push to production and not worry about anything else.
As an ops engineer, our goal is to do the easiest setup possible, and not have any maintenance or scalability work.

The sample application

For this blog post we will use a fork of the famous Spring Petclinic. This is a well-known and well-documented sample Spring Boot application, and we will detail the choices that were made in order to deploy it easily.

There is nothing specific about this application, so if you use a Spring Boot application (or even better, a JHipster application!), you should be able to follow the next steps and be in the cloud very quickly.

Azure App Service overview

There are many ways to deploy a Spring Boot application to Azure. You can obviously use a virtual machine (VM): you'll need to set up everything manually, take care of the OS and JVM maintenance, handle HTTPS and scalability yourself... So while it looks easy at first sight, it's time consuming and the maintenance is going to be a big issue.

We are going to use Azure App Service, which is a Platform-as-a-Service solution. It supports different languages, as well as Docker images, so it can effectively host any kind of application. It is also very cost-efficient.

As a managed service, there is much less maintenance overhead than with a VM, and scalability is already included, which makes it a great way to host monolithic Spring Boot applications. If you have more complex needs, we recommend using Azure Spring Cloud, which shares many similar concepts, but which targets microservices architectures.

Jar or Docker?

Azure App Service supports both Jar deployments and Docker deployments, which are both well-documented and popular ways to deploy Spring Boot applications.

We recommend using Jar deployment here: both the OS and the JVM will be managed (and supported!) by Microsoft, which means you will have far less maintenance work to do. For example, if a security vulnerability is discovered in the JVM, it will be automatically patched without any manual intervention.

Azure App Service setup

First, we'll create an Azure resource group in which we will work:

Go to the Azure portal.
In the search box, look for "Resource groups".
Create a new resource group called spring-petclinic.

Then, create the Azure App Service instance:

In the Azure portal search box, look for "App Services".
Create a new Web App in the spring-petclinic resource group, using Java 11 on Linux, as in the screenshot below:

MySQL setup

Like many Spring Boot applications, the Spring Petclinic uses the MySQL database: if you are using another database, like PostgreSQL, your setup should be similar.

Azure App Service has a feature called "MySQL in-app", that you can use to lower your hosting costs, as MySQL will run inside your Azure App Service instance. While this can be used in development, it comes with several important limitations and is not a production-grade database, so we are not going to use it here.

Go to the Azure portal.
In the search box, look for "Azure Database for MySQL".
Create a MySQL server (and be careful to select the correct pricing tier for your usage!).
Note your database name, your username and password, as we will need them later.

In your MySQL database, go to "Connection security", and select "Allow access to Azure services". You should also click on the "Add client IP" button to automatically add your current IP to the firewall rules, so you can access it from your current machine.

Environment variables

The Spring Petclinic is configured using properties files, which are located in the src/main/resources directory. One of them is called application-mysql.properties, which means it will be used when the mysql Spring Boot profile will be triggered.

In the Azure App Service we created above, select the Settings > Configuration menu on the left.

We need to configure two different settings here:

Set Spring Boot to use the mysql profile, using the SPRING_PROFILES_ACTIVE environment key.
Override the database configuration using environment variables for the SPRING_DATASOURCE_URL, SPRING_DATASOURCE_USERNAME and SPRING_DATASOURCE_PASSWORD keys.

This configuration should look like the screenshot below:

As we are handling secrets here, another solution it to use Azure Key Vault. With Spring Boot, this can be configured using the Azure Key Vault Secrets Spring Boot Starter. This adds some complexity to the project, and isn't more secure than environment variables in our particular use-case (in the end, both become Spring Boot properties, and can be read from the code), so for just storing one secret this is outside of the scope of this "deploy the easy way" article.

Deploying using the Azure Webapp Maven plugin

Now that our App Service is configured, all we need to do is deploy our application. In this first solution, we are going to use the Azure Webapp Maven plugin. This is what most developers would use, as it's easily integrated inside their IDEs.

Inside your pom.xml file, add the following Maven plugin:

      <plugin>
        <groupId>com.microsoft.azure</groupId>
        <artifactId>azure-webapp-maven-plugin</artifactId>
        <version>1.8.0</version>
          <configuration>
            <schemaVersion>V2</schemaVersion>
            <resourceGroup>spring-petclinic</resourceGroup>
            <appName>jdubois-petclinic</appName>
            <region>westeurope</region>
            <pricingTier>B1</pricingTier>
            <runtime>
              <os>linux</os>
              <javaVersion>java11</javaVersion>
              <webContainer>java11</webContainer>
            </runtime>
            <deployment>
              <resources>
                <resource>
                  <directory>${project.basedir}/target</directory>
                  <includes>
                    <include>*.jar</include>
                  </includes>
                </resource>
              </resources>
            </deployment>
          </configuration>
      </plugin>

Of course, you will need to configure the correct parameters for your resourceGroup, appName, region and pricingTier.

This solution is very easy to use for developers, but it has a few drawbacks:

Its configuration is stored inside the project's pom.xml, including configuration that should change depending on environments.
It requires a local build and a manual work for the developer.

Automating deployment with a GitHub Action

A newer alternative to the Azure Webapp Maven plugin is to use a GitHub Action.

You will need to authorize your GitHub Action to publish applications on Azure, here is how to do this:

In the Azure portal, select your App Service and in the overview panel, click on Get publish profile. You will download a .PublishSettings file.
In your GitHub project, go to Settings > Secrets and create a new secret called azureWebAppPublishProfile. Paste the content of the previous .PublishSettings file into that secret.

Then, add the following GitHub Action to your project. Create a file called .github/workflows/build-and-deploy.yml and paste the following content in it:

name: Build and deploy to Azure App Service

on:
  push:
    branches:
      - master

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - name: Set up JDK 11
        uses: actions/setup-java@v1
        with:
          java-version: 11
      - name: Cache Maven archetypes
        uses: actions/cache@v1
        with:
          path: ~/.m2/repository
          key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}
          restore-keys: |
            ${{ runner.os }}-maven-
      - name: Build with Maven
        run: mvn clean package
      - uses: azure/webapps-deploy@v1
        with:
          app-name: spring-petclinic
          publish-profile: ${{ secrets.azureWebAppPublishProfile }} # See https://github.com/Azure/actions-workflow-samples/tree/master/AppService
          package: '${{ github.workspace }}/target/*.jar'

Here is a brief description of this GitHub Action:

It publishes an updated Azure App Service application as soon as code is pushed to the master branch. You can do a similar GitHub Action for other branches: you could have this setup for each project developer, or for each environment.
It checks the latest code and installs Java 11.
It uses the actions/cache GitHub Action to cache Maven archetypes: this considerably improves build times, so it is highly recommended.
It builds and tests the application using Maven.
It deploys the final application using the azure/webapps-deploy GitHub Action. This deployment could also have been made using the Azure Webapp Maven plugin we detailed in the previous section, but this GitHub Action allows to better decouple the code (the pom.xml doesn't have any specific Azure configuration or library), and it's also faster to execute.

Final thoughts

Our two goals are fulled reached:

Developers only need to git push to deploy their Spring Boot application, without even needing to know anything about Azure App Services.
Operations engineers had to do a minimal setup (creating the MySQL and App Service instances, and configuring 4 environment variables), but now the application can run in production without much maintenance. The OS and the JVM will be automatically patched and supported by Microsoft, and scalability is included.

In order to achieve those goals, we didn't have to modify any code in our Spring Boot application. Using GitHub Actions to deploy, all we needed to do is add a hidden file inside the .github repository.

If you want to have a closer look at the final application, my fork of Spring Petclinic is available here.

Using Spring Security with Azure Active Directory

Julien Dubois — Mon, 09 Sep 2019 06:47:14 +0000

Why use Active Directory?

Let's be honnest, Active Directory isn't "cool" today. People see it has very complex, which is true - but security is a complex matter! And it doesn't have the hype of new products like Red Hat's Keycloak, even if both are often used for the same goal, at least with Spring Boot: securing a business application using OpenID Connect.

However, there's one really nice feature of Active Directory: your company has probably it already installed, and probably already pays for it (hint: for a security product, you'd better pay if you want support and the latest patches - that's why I always recommend to pay for Keycloak!). Officially, 85% of Fortune 500 companies are using Active Directory, which is in fact (unofficially!) confirmed by this clever hacker.

So securing a Spring Boot application with Active Directory makes a lot of sense :

It's probably already installed, validated and secured in your company
You'll have access to the official employee list of your company: no need to create new users, handle lost passwords, invalidate old employees...
It's highly secured: you'll have 2 factor authentication, etc, everything is included

But there's a last reason: it's free! Well, not totally free, but if you look at the pricing model, there's a very generous free tier. So you can use it for development or for your start-up idea, without paying anything.

The Azure Spring Boot Starter for Active Directory

Thankfully, the Azure engineering team is providing a Spring Boot Starter for Azure Active Directory, which is available at https://github.com/microsoft/azure-spring-boot/tree/master/azure-spring-boot-starters/azure-active-directory-spring-boot-starter. There are two official tutorials available:

The official tutorial is available here.
There's also a tutorial in the project GitHub repository, which is updated along with the code: this one works with the latest version of the code, and is less detailed than the official one.

Both of them are a bit outdated at the time of this writing, and as it's my work to update them, I'm first doing this blog post to gather feedback:

We'll be using the latest and greatest version of both Spring Boot (2.1.8, released a few hours ago at the time of this writing) and the Azure Spring Boot starters (2.1.7)
We'll be using the new Active Directory user interface: this is a huge case of problem here, as all the screenshots currently available are from the older user interface, so you can't find anything easily

Please, don't hesitate to add comments to this blog post, so I can clean up everything, and create an awesome official tutorial!

The sample project

The sample project we do here is available at https://github.com/jdubois/spring-active-directory, so if you want to see the real code and test it, it's all there.

This is a Spring Boot project generated with Spring Initializr as I wanted to have something extremely simple. It uses the following important components:

Spring Web
OAuth2 Client, which transitively includes Spring Security
Azure Support
Spring Data JPA and MySQL, so we can build a "real" application in the future

Configuring Active Directory

Now is the tricky part of this post! Configuring Active Directory is complicated, so we'll go step-by-step and provide screenshots.

Create your own tenant

Active Directory provides tenants, which are basically instances that you can use. There are two types of instances: work and school (the one I will use here), and social accounts (called "Azure Active Directory B2C").

As discussed earlier, there's a generous free tier, so you can create your own tenant without paying anything:

Go to the the Azure portal
Select "All resources", and look for "Azure Active Directory" and click "create"
Fill in your organization's name, domain and country, and you're done!

Accessing your Active Directory tenant

You can now switch to your Active Directory tenant by clicking on the "Directory + Subscription" icon on the top menu:

Configuring your tenant

Once you have switched to your tenant, select "Active Directory", and you can now configure it with full admin rights. Here's what's important to do.

Click on "App registrations" and create a new registration:

Please note that:

The account type must be "multitenant". The current Spring Boot starter does not work with single tenants, which is an issue being currently addressed.
The redirect URI must be "http://localhost:8080/login/oauth2/code/azure". Of course you can replace "localhost:8080" by your own domain, but the suffix is the default one that will be configured by the Spring Boot starter, and if those URI do not match, you will not be able to log in.

Select the registered application

In the "overview", note the "Application (client) ID", this is what will be used in Spring Security as "client-id", as well as the "Directory (tenant) ID", which will be Spring Security's "tenant-id".
Select "Authentication", and in the Web "Platform configuration", check both options under "Implicit grant" ("Access tokens" and "ID tokens")
Click on "Certificates & secrets", and create a new client secret, which will be Spring Security's "client-secret"

Click on "API permissions", and under "Microsoft Graph", give your application the "Directory.AccessAsUser.All" and "User.Read" permissions
Click on the "Grant admin consent" button at the bottom of the page

Go back to your Active Directory tenant and click on "User settings"

Under "Manage how end users launch and view their applications", validate the "Users can consent to apps accessing company data on their behalf" is set to "Yes" (this should be good by default).

Create users and groups

Still in your Active Directory tenant, select "Groups" and create a new group, for example "group1".

Now select "Users", create a new user, and give that user the "group1" group that we just created.

Configure the Spring Boot application

Now let's use that configured tenant, with this new user, in our Spring Boot application.

In the pom.xml file, add the azure-active-directory-spring-boot-starter:

        <dependency>
            <groupId>com.microsoft.azure</groupId>
            <artifactId>azure-active-directory-spring-boot-starter</artifactId>
        </dependency>

In your application.yml file (or application.properties file if you don't like YAML), configure the following properties. Please note that we got the 3 required values when we registered our application in our Active Directory tenant.

azure:
  activedirectory:
    tenant-id: <tenant-id>
    active-directory-groups: group1, group2

spring:
  security:
    oauth2:
      client:
        registration:
          azure:
            client-id: <client-id>
            client-secret: <client-secret>

We now need to configure our Spring Boot application to use Active Directory. Create a new SecurityConfiguration class:

@EnableWebSecurity
public class SecurityConfiguration extends WebSecurityConfigurerAdapter {

    private final OAuth2UserService<OidcUserRequest, OidcUser> oidcUserService;

    public SecurityConfiguration(OAuth2UserService<OidcUserRequest, OidcUser> oidcUserService) {
        this.oidcUserService = oidcUserService;
    }

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
                .authorizeRequests()
                .anyRequest().authenticated()
                .and()
                .oauth2Login()
                .userInfoEndpoint()
                .oidcUserService(oidcUserService);
    }
}

This configuration will require that each request is secured, and will therefore redirect any user to Active Directory when he tries to connect.

Running everything

When running the Spring Boot application, we recommend you add a src/main/resources/logback-spring.xmllogback-spring.xml file with the following configuration, in order to better understand the issues you might encounter:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE configuration>

<configuration scan="true">
    <include resource="org/springframework/boot/logging/logback/base.xml"/>

    <logger name="org.springframework.security" level="DEBUG"/>
    <logger name="com.microsoft" level="DEBUG"/>
    <logger name="com.example" level="DEBUG"/>

</configuration>

Now if you run the application, accessing it on http://localhost:8080 should point you to Active Directory, where you can sign it using the user we just created earlier:

Testing the security

In order to know if everything is correct, including if our user really receive the "group1" role that we configured earlier, let's add a specific Spring MVC controller called AccountRessource:

package com.example.demo;

import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class AccountResource {

    @GetMapping("/account")
    public Authentication getAccount() {
        return SecurityContextHolder.getContext().getAuthentication();
    }
}

Accessing http://localhost:8080/account should now give you all the user's security information, including his roles! Congratulations, you have secured your Spring Boot application using Active Directory!

Using the new Azure SDK for Java to upload images asynchronously, using Spring Reactor

Julien Dubois — Wed, 04 Sep 2019 16:04:51 +0000

The new Azure SDK for Java

This blog post uses the upcoming Azure SDK for Java: at the time of this writing, this is still a preview release, but many people have already started using it.

To be more precise, we are talking here of the Azure SDK for Java (August 2019 Preview), also seen as "1.0.0-preview.2" on Maven Central.

This new release is important as it uses some new, modern API guidelines, and also because its asynchronous features are powered by Spring Reactor.

Those new reactive APIs are interesting as they deliver better scalability, and work very well with Spring. Unfortunately, they come at the cost of using an API that is more complex to understand, and more complex to debug: this is why we are doing this blog post!

The problem with uploading data

Uploading data takes time, and usually need a good connection: if you're working with mobile devices, this can definitely be an issue! If we use a thread-based model, this means that sending several files is going to block several threads, and is not going to be very scalable. Or you could put all files in a queue that you would manage yourself: this is probably quite complex to code, and this will prevent you from uploading those files in parallel, so performance won't be very good. This is where Spring Reactor comes into play!

The idea here is to upload that data in an asynchronous, non-blocking way, so we can upload many files in parallel without blocking the system.

Spring Reactor and Spring Webflux

Please note that the example here works with Spring Webflux: this is the reactive version of Spring, and as this works in a totally different way than the classical Spring MVC (which is thread-based), this code won't work with Spring MVC. This is one of the issues when doing reactive programming: it's not really possible to mix reactive code and thread-based code, so all your project will need be made and thought with a reactive API. In my opinion, this is best suited in a microservice architecture, where you will code some specific services with a reactive API, and some with a traditional thread-based API. Reactive microservices will probably be a bit more complex to develop and debug, but will provide better scalability, start-up time, memory consumption, so they will be used for some specific, resource-intensive tasks.

Creating a Storage Account

In the the Azure portal, create a new storage account:

Once it is created, go to that storage account and select "Shared access signature", or SAS. A SAS is a signature that allows to access some resources, for a limited period of time: it is perfect for uploading data on a specific location, without compromising security.

After clicking on "Generate SAS and connection string", copy the last generated text field, named "Blob service SAS URL". This is the one we will use with the Azure SDK for Java.

Add the Azure SDK for Java to the pom.xml

As the Azure SDK for Java preview is on Maven Central, this is just a matter of adding the dependency to the project's pom.xml:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-blob</artifactId>
    <version>12.0.0-preview.2</version>
</dependency>

Using the new asynchronous API

Let's first have a look at the final code, which is available on https://github.com/jdubois/jhipster-azure-blob-storage/blob/master/src/main/java/com/example/demo/PictureResource.java:

@RestController
@RequestMapping("/api")
public class PictureResource {

    Logger log = LoggerFactory.getLogger(PictureResource.class);

    @Value("${AZURE_BLOB_ENDPOINT}")
    private String endpoint;

    @PostMapping("/picture")
    public void uploadPicture() throws IOException {
        log.debug("Configuring storage client");
        BlobServiceAsyncClient client =  new BlobServiceClientBuilder()
            .endpoint(endpoint)
            .buildAsyncClient();

        client.createContainer("pictures")
            .doOnError((e) -> {
                log.info("Container already exists");
            })
            .flatMap(
                (clientResponse) -> {
                    log.info("Uploading picture");
                    return clientResponse
                        .value()
                        .getBlockBlobAsyncClient("picture.png")
                        .uploadFromFile("src/main/resources/image.png");
                })
            .subscribe();
    }
}

WARNING This API only works when using Spring Reactive, so please note you need to use this in a Spring Webflux project, and not a Spring MVC project.

Authentication is done using the "Blob service SAS URL" that we copied above, and which is provided using the AZURE_BLOB_ENDPOINT environment variable in this example: please note that the SAS is included in the URL, so there is no need to authenticate elsewhere (there is a credentials() method in the API, that might be misleading, but which is useless in our case). This URL should thus be stored securely, and not commited with your code.

Sending the image uses the Spring Reactor API:

We create a specific pictures container to store some data
We then use Spring Reactor's API to upload a picture
And we finish by using the subscribe() method, which makes our code run asynchronously

As a result, this method will return very quickly, and then the container will be created and the image uploaded, in another thread. This can make debugging harder, but allows our application to accept many more requests, and process them asynchronously.

Improving the reactive code

This tip was provided by Christophe Bornet, many thanks to him!

The previous code is what we usually see in projects, but that can be improved, in order to let Spring Webflux handle the .subscribe() part: this will preserve the backpressure between Spring Webflux and the Azure SDK. Also, that means that errors will be managed by Spring Webflux, instead of being lost: in the case of an error while uploading a file using the Azure SDK, with this new code you will have a clean 500 error.

The change can be seen in this commit, where we replace the .subscribe() by a .then() and we return a Mono<Void> instead of not returning anything. It will be Spring Webflux's responsibility to handle that Mono and call .subscribe().

The resulting code is the following:

    @PostMapping("/picture")
    public Mono<Void> uploadPicture() throws IOException {
        log.debug("Configuring storage client");
        BlobServiceAsyncClient client =  new BlobServiceClientBuilder()
            .endpoint(endpoint)
            .buildAsyncClient();

        return client.createContainer("pictures")
            .doOnError((e) -> {
                log.info("Container already exists");
            })
            .flatMap(
                (clientResponse) -> {
                    log.info("Uploading picture");
                    return clientResponse
                        .value()
                        .getBlockBlobAsyncClient("picture.png")
                        .uploadFromFile("src/main/resources/image.png");
                })
            .then();
    }

It's a bit more advanced usage of the reactive APIs, but the result should be worth the trouble.

Conclusion and feedback

We are currently lacking documentation and samples on this new asynchronous API in Azure SDK for Java. I believe that it is very important in some specific scenarios like the one we have here, as typically you should not upload or download data in the current thread if you want a scalable application.

This SDK is still in preview, so if you have feedback on this API, please comment on this post!

For example, the current API allows you to create a container (and this will fail if a container already exist) or get an existing container (and this will fail if it does not exist yet). Do you think there should be an option to have something like getOrCreateContainer("name"), that will automatically create a container if it is requested?