Deploying to Microsoft Azure

Microsoft Azure is a great solution to run JHipster applications in the cloud.

  • The easiest way is to use Azure App Service: there is a JHipster sub-generator to automatically deploy a monolithic application to this service.
  • If you are using Spring Boot microservices, there is a JHipster sub-generator to deploy your applications to Azure Spring Cloud.
  • As with any Docker and Kubernetes cloud provider, you can use the JHipster Docker and Kubernetes support to deploy your Docker images to Microsoft Azure. Follow our Docker Compose documentation and our Kubernetes documentation for more information on these options.

Microsoft Azure

  1. Installing the “az CLI”
  2. Current limitations
  3. Supported databases
  4. Storing secrets
  5. Deploying a Spring Boot executable Jar file to Azure App Service
  6. Deploying Spring Boot microservices to Azure Spring Cloud

Installing the “az CLI”

You can manage your Azure resources using the Web-based Azure portal or using the Azure command-line interface, also known as the “az CLI”.

As with JHipster we always automate everything, installing this “az CLI” is mandatory in order to work with any of the below options.

To install the az CLI on your machine, follow the “Install the Azure CLI” official documentation.

Current limitations

Those limitations can be solved in the future, if you are interested to help do not hesitate to contribute to the project:

  • The sub-generators do not automatically configure external services like databases (see next section for supported databases), Elasticsearch, Kafka or Redis. So you will need to create and configure them manually.
  • Azure only provides Maven plugins, and as a result the JHipster sub-generators can only work with Maven.

Supported databases

SQL databases

Azure provides all types of databases like MySQL/PostgreSQL/Oracle/MS SQL Server. In Azure, they will be secured by default, so if you want to access them from your JHipster application, you will need to open up their firewall.

For example, on MySQL, you will need to 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 rule:

MySQL firewall

Warning for MySQL users: By default, the MySQL connection string generated by JHipster uses the useSSL=false flag in the spring.datasource.url property (typically in your src/main/resources/config/application-prod.yml file). This is because, by default, JHipster uses a local database. On Azure, your database is secured by default, using an SSL certificate, so you will need to put this flag to true.

For example:

spring:
  datasource:
    type: com.zaxxer.hikari.HikariDataSource
    url: jdbc:mysql://jhipster-database.mysql.database.azure.com:3306/test?useUnicode=true&characterEncoding=utf8&useSSL=true&useLegacyDatetimeCode=false&serverTimezone=UTC
    username: [email protected]
    password: XXXXXX

NoSQL databases

You can install a NoSQL database like Cassandra or MongoDB using the Azure Marketplace, or you can use CosmosDB.

CosmosDB is a globally distributed, managed database from Microsoft. It is compatible at the API level with Cassandra and MongoDB, so it can be used with a JHipster application that is generated using those technologies.

Storing secrets

There are several “secrets” that you should store securely in JHipster, at least your database password (see previous section), and your security tokens (have a look at our security documentation for more information).

There are many options in Azure, which you can use to store this data in a better place than your application-prod.yml file. Here are the most common ones:

  • A Spring Cloud Config server, like the JHipster Registry or the configuration server managed by Azure Spring Cloud. This is the best option, as you can tag and rollback configurations, but it needs a dedicated server.
  • Environment variables. This is the easiest option, but it’s bit annoying to setup and it is the less secure one.
  • Azure Key Vault: this is the most secured option, but it is specific to Azure. There is a dedicated Azure Spring Boot Starter for Key Vault which is our recommended way to configure JHipster with Azure Key Vault.

Deploying a Spring Boot executable Jar file to Azure App Service

Deploying to Azure App Service

5-minutes video on deploying a JHipster application to Azure App Service

Generating configuration for Azure App Service

Azure App Service is a managed plaform-as-a-service: on Azure, if you want to deploy a monolith, this is our recommended option.

There are two ways to deploy a Spring Boot application to Azure App Service:

  • Deploy it as a Docker image: this allows you to ship anything inside your Docker image, which can be good for some specific use cases, but for most scenarios this is the most complex and less secured option.
  • Deploy it as an executable Jar file: this is the easiest and more secured option, as the OS and the JVM will be supported and automatically updated by Microsoft.

We recommend using an executable Jar file, but if you’d rather use a Docker image, follow the last section of this page, “Deploying to Docker and Kubernetes”.

To deploy a JHipster application as an executable Jar file to Azure App Service, there is a specific azure-app-service sub-generator:

jhipster azure-app-service

This sub-generator can be used with the following flags:

  • --skip-build Skips building the application
  • --skip-deploy Skips deployment to Azure App Service
  • --skip-insights Skips configuration of Azure Application Insights

The following questions will then need be answered. You will probably need to access the Azure Portal to answer them and check the configured resources.

  • Azure resource group name: This is the name of your Azure resource group, in which your application will be deployed. We recommend setting up a default Azure resource group using the command az configure --defaults group=<resource group name>.
  • Azure App Service plan name: Your Azure App Service will run in an Azure Service Plan. If the service plan already exists, JHipster will use it, and otherwise it will create a new one. By default, JHipster creates a Linux-based service plan, in the “B1” tier (the “Basic” plan, free for 30 days). If you want more information on the service plan tiers, here is the documentation.
  • Azure Application Insights instance name: JHipster can automatically configure an Azure Application Insights instance, so the deployed application will be monitored. This uses the Azure Spring Boot Starter for Application Insights and configures it in the application-azure.yml configuration file.
  • Azure App Service application name: The name of your Azure App Service instance.
  • Which type of deployment do you want ? You can either build and deploy your application locally using Maven, or use GitHub Actions to build and deploy it automatically for you.

The “azure” Spring Boot profile

This sub-generator creates an azure Spring Boot profile and configures it.

  • In your Azure App Service instance, both the prod and azure Spring profiles are automatically enabled, using the SPRING_PROFILES_ACTIVE environment variable.
  • A new Spring Boot configuration is created for that profile, src/main/resources/config/application-azure.yml. For more information on profiles in JHipster, here is the documentation.

Deploying using GitHub Actions

Deploying with GitHub Actions is recommended, as it is easier and probably faster than on your local machine.

  • The configuration is stored in the .github/workflows/azure-app-service.yml.
  • By default, the application is deployed each time there is new push event on the main branch.
  • This deployment mechanism uses the azure-webapp Maven plugin, in order to be consistent with the local deployment. There is an alternative way to deploy to Azure App Service, which doesn’t require Maven. If you are interested in it, look for the azure/webapps-deploy GitHub Action, and follow the example in this blog post.

In order to be authorized to deploy an application to your Azure App Service instance, GitHub needs to have access to a secured token called AZURE_CREDENTIALS. At the end of the sub-generator execution, it has displayed a command-line in the form:

az ad sp create-for-rbac --name http://<your-security-role> --role contributor --scopes /subscriptions/<your-subscription-id>/resourceGroups/<your-resource-group-name> --sdk-auth
  • <your-security-role> is the name of the security role you want to create (by default we use the application name).
  • <your-subscription-id> is the ID of the Azure subscription you are using. It can be found at the top of the subscription screen in the Azure Portal.
  • <your-resource-group-name> is the name of your resource group.

Execute that command to get the secured token. Then, in the GitHub project where your application is located, go to Settings > Secrets, and create a new secret named AZURE_CREDENTIALS in which you need to paste the secured token.

Deploying Spring Boot microservices to Azure Spring Cloud

Azure Spring Cloud is a managed service for Spring Boot applications. It can host any kind of JHipster applications, including monoliths, but it is particularly suited for hosting JHipster microservices and JHipster gateways, which follow the standard JHipster microservice architecture.

Limitations of the Azure Spring Cloud sub-generator

Azure Spring Cloud provides a managed discovery server based on Netflix Eureka, so this can only works with JHipster applications using the “no” or “JHipster Registry” service discovery:

  • If no service discovery is configured in the application, the sub-generator described below will add Netflix Eureka automatically. This is the easiest way to get your microservice running on Azure Spring Cloud.
  • JHipster Registry is in fact a Netflix Eureka server, so this is fully compatible with Azure Spring Cloud. JHipster provides many custom configuration for Eureka: it is required that you remove the eureka.instance.instanceId Spring Boot property in your application.yml file, as this should be managed by Azure Spring Cloud. Other eureka properties work fine with Azure Spring Cloud, but they can be removed to use instead Azure’s default values. When using this configuration, you will benefit from some advanced features from JHipster, like distributed caching configuration, that normally rely on the JHipster Registry.

As a result, only applications using Hashicorp Consul as a service discovery mechanism will not work, as this is not supported by Azure Spring Cloud.

Generating configuration for Azure Spring Cloud

A specific Azure Spring Cloud extension must be added to the “az CLI”:

az extension add --name spring-cloud

Once this extension is installed, you will be able to run az spring-cloud commands, and automate the Azure Spring Cloud configuration with JHipster.

To deploy a JHipster application on Azure Spring Cloud, there is a specific azure-spring-cloud sub-generator:

jhipster azure-spring-cloud

This sub-generator can be used with the following flags:

  • --skip-build Skips building the application
  • --skip-deploy Skips deployment to Azure Spring Cloud

The following questions will then need be answered. You will probably need to access the Azure Portal to answer them and check the configured resources.

  • Azure resource group name: This is the name of your Azure resource group, in which your application will be deployed. We recommend setting up a default Azure resource group using the command az configure --defaults group=<resource group name>.
  • Azure Spring Cloud service name (the name of your cluster): This is the name of your Azure Spring Cloud cluster instance. We recommend setting up a default Azure Spring Cloud service name using the command az configure --defaults spring-cloud=<resource group name>.
  • Azure Spring Cloud application name: The name of the Spring Boot application you are deploying on Azure Spring Cloud.
  • Which type of deployment do you want ? You can either build and deploy your application locally using Maven, or use GitHub Actions to build and deploy it automatically for you.

The “azure” Maven and Spring Boot profile

If you have followed documentation above on the azure-app-service sub-generator, the azure-spring-cloud sub-generator works a bit differently, as it configures:

  • A new Spring Boot profile called azure, configured at src/main/resources/config/application-azure.yml.
  • A new Maven profile, also called azure. This Maven profile will automatically force the usage of the prod and azure Spring Boot profiles at runtime, so there is no need to configure them at the Azure Spring Cloud level (this is the main difference with Azure App Service, where those are configured as environment variables).

For more information on profiles in JHipster, here is the documentation.

Azure Spring Cloud specific features

As documented in the section above, the azure-spring-cloud sub-generator adds a specific azure Maven profile. This profile adds some libraries at build time, so that the running application can benefit from Azure Spring Cloud’s specific features:

  • It connects the application to the managed Spring Cloud Service Discovery server (as detailed in the section above, “Limitations of the Azure Spring Cloud sub-generator”).
  • It configures the application using the managed Spring Cloud Config Server.
  • It sends distributed tracing data to Azure Monitor.

Deploying using GitHub Actions

Deploying with GitHub Actions is recommended, as it is easier and probably faster than on your local machine.

  • The configuration is stored in the .github/workflows/azure-spring-cloud.yml.
  • By default, the application is deployed each time there is new push event on the main branch.
  • This deployment mechanism uses directly the “az CLI” to deploy to the Azure Spring Cloud cluster.

In order to be authorized to deploy an application to your Azure Spring Cloud cluster, GitHub needs to have access to a secured token called AZURE_CREDENTIALS. This token can generated by using the following command line:

az ad sp create-for-rbac --name http://<your-security-role> --role contributor --scopes /subscriptions/<your-subscription-id>/resourceGroups/<your-resource-group-name> --sdk-auth
  • <your-security-role> is the name of the security role you want to create (by default we use the application name).
  • <your-subscription-id> is the ID of the Azure subscription you are using. It can be found at the top of the subscription screen in the Azure Portal.
  • <your-resource-group-name> is the name of your resource group.

Execute that command to get the secured token. Then, in the GitHub project where your application is located, go to Settings > Secrets, and create a new secret named AZURE_CREDENTIALS in which you need to paste the secured token.