Deploy a Micronaut Microservices Application to the Azure Kubernetes Service
This guide shows how to deploy a Micronaut® application, consisting of three microservices, to the Azure Kubernetes Service (AKS) using the Micronaut Kubernetes project.
The Micronaut Kubernetes project provides integration between Micronaut and Kubernetes. It adds support for the following features:
- Service Discovery
- Configuration client for config maps and secrets
- Kubernetes blocking and non-blocking clients built on top of the official Kubernetes Java SDK
AKS is a managed Kubernetes service for deploying containerized applications to the cloud. The guide demonstrates how to use Kubernetes Service Discovery and Distributed Configuration to connect three microservices, and discover how Micronaut integration with Kubernetes simplifies deployment to AKS. The application consists of three microservices:
- users - contains customer data that can place orders on items, also a new customer can be created. It requires HTTP basic authentication to access it.
- orders - contains all orders that customers have created as well as available items that customers can order. This microservice also enables the creation of new orders. It requires HTTP basic authentication to access it.
- api - acts as a gateway to the orders and users microservices. It combines results from both microservices and checks data when a customer creates a new order.
Prerequisites #
- JDK 17 or higher. See Setting up Your Desktop.
- An Azure account. See Setting up Your Cloud Accounts.
- The Azure CLI. Follow the Azure documentation for installing or updating the latest version of the Azure CLI.
- An Azure user with sufficient permissions to create and manage AKS and Azure Container Registry (ACR).
- A Docker-API compatible container runtime such as Rancher Desktop or Docker installed and running.
kubectl
to deploy the application to AKS.
A note regarding your development environment
Consider using Visual Studio Code, which provides native support for developing applications with the Graal Development Kit extension.
Note: If you use IntelliJ IDEA, enable annotation processing.
Windows platform: The GDK guides are compatible with Gradle only. Maven support is coming soon.
1. Create or Download a Microservices Application #
You can create a microservices application from scratch by following this guide, or you can download the completed example:
The application ZIP file will be downloaded to your default downloads directory. Unzip it, open it in your code editor, and proceed to the next steps.
Note: By default, a Micronaut application detects its runtime environment. A detected environment (in this case, k8s) overrides the default specified environment (in this case, azure). This means that you should locate your configuration in the application-k8s.properties and bootstrap-k8s.properties files. Alternatively, you can specify the
azure
environment passing it as a command-line option (-Dmicronaut.environments=azure
) or via an environment variable (MICRONAUT_ENVIRONMENTS=azure
).
2. Prepare to Deploy Microservices #
2.1. Create a Resource Group #
We recommend that you create a new resource group for this guide, but you can use an existing resource group instead.
Run the az group create command to create a resource group named gdkguides in the eastus region:
az group create --location eastus --name gdkguides
If you prefer using the region geographically closer to you, run az account list-locations
to list all available regions.
2.2. Register Microsoft.ContainerRegistry as a Resource Provider #
Run the az provider register
command to register Microsoft.ContainerRegistry as a Resource Provider:
az provider register --namespace 'Microsoft.ContainerRegistry'
This will take a while to execute. Check the status:
az provider show --namespace Microsoft.ContainerRegistry
Once the "registrationState": "Registering"
changes to "registrationState": "Registered"
, the registration is complete.
2.3. Register Microsoft.ContainerService as a Resource Provider #
Run the az provider register
command to register Microsoft.ContainerService as a Resource Provider:
az provider register --namespace 'Microsoft.ContainerService'
This will take a while to execute. Check the status:
az provider show --namespace Microsoft.ContainerService
Once the "registrationState": "Registering"
changes to "registrationState": "Registered"
, the registration is complete.
2.4. Create an Azure Container Registry #
Run the az acr create
command to create an Azure Container Registry:
az acr create \
--name gdkrepo \
--resource-group gdkguides \
--sku Basic
2.5. Create an Azure Kubernetes Cluster #
Run the az aks create
command to create an Azure Kubernetes Cluster:
az aks create \
--name gdkCluster \
--resource-group gdkguides \
--node-count 1 \
--dns-name-prefix=gdk \
--attach-acr gdkrepo \
--generate-ssh-keys
Run kubectl get nodes
to list the cluster nodes to verify the connection to your cluster:
kubectl get nodes
The response should look like this:
NAME STATUS ROLES AGE VERSION
aks-nodepool1-70833750-vmss000000 Ready <none> 3m v1.29.7
2.6. Authenticate to Your Azure Container Registry #
Run the az aks get-credentials
command to generate a kubectl
configuration for authentication to ACR:
az aks get-credentials \
--resource-group gdkguides \
--name gdkCluster
Run the az acr login
command to authenticate to your Azure Container Registry:
az acr login --name gdkrepo
Alternately, login using docker login
.
Run az acr login
with the --expose-token
flag to generate an access token, and save it in the TOKEN
environment variable:
export TOKEN=$(az acr login --name gdkrepo --expose-token --output tsv --query accessToken)
Then run:
docker login gdkrepo.azurecr.io \
--username 00000000-0000-0000-0000-000000000000 \
--password-stdin <<< $TOKEN
You should see Login Succeeded
after logging in.
2.7. Create and Publish Container Images #
2.7.1. Create and Publish a Container Image of the Native Users Microservice
- To create a container image of the native users microservice named “users”, run the following command from the users directory:
./gradlew :azure:dockerBuildNative
Note: If you encounter problems creating a container image, run the following command from the users/build/docker/native-main/ directory:
docker build . -t users-azure -f DockerfileNative
./mvnw package -Dpackaging=docker-native -Pgraalvm
Note: If you encounter problems creating a container image, run the following command from the users/target/ directory:
docker build . -t users-azure -f Dockerfile
- Tag the image with the login server of your container registry:
docker tag users-azure gdkrepo.azurecr.io/users-azure:latest
- Push the image to the container registry:
docker push gdkrepo.azurecr.io/users-azure:latest
2.7.2. Create and Publish a Container Image of the Native Orders Microservice
- To create a container image of the native orders microservice named “orders”, run the following command from the orders directory:
./gradlew :azure:dockerBuildNative
Note: If you encounter problems creating a container image, run the following command from the orders/build/docker/native-main/ directory:
docker build . -t orders-azure -f DockerfileNative
./mvnw package -Dpackaging=docker-native -Pgraalvm
Note: If you encounter problems creating a container image, run the following command from the orders/target/ directory:
docker build . -t orders-azure -f Dockerfile
- Tag the image with the login server of your container registry:
docker tag orders-azure gdkrepo.azurecr.io/orders-azure:latest
- Push the image to the container registry:
docker push gdkrepo.azurecr.io/orders-azure:latest
2.7.3. Create and Publish a Container Image of the Native API (Gateway) Microservice
- To create a container image of the native api microservice named “api”, run the following command from the api directory:
./gradlew :azure:dockerBuildNative
Note: If you encounter problems creating a container image, run the following command from the api/build/docker/native-main/ directory:
docker build . -t api-azure -f DockerfileNative
./mvnw package -Dpackaging=docker-native -Pgraalvm
Note: If you encounter problems creating a container image, run the following command from the api/target/ directory:
docker build . -t api-azure -f Dockerfile
- Tag the image with the login server of your container registry:
docker tag api-azure gdkrepo.azurecr.io/api-azure:latest
- Push the image to the container registry:
docker push gdkrepo.azurecr.io/api-azure:latest
2.8. Update the Kubernetes Manifest Files #
2.8.1. Update the Users Manifest File
Edit the file named users/k8s-azure.yml as follows:
apiVersion: apps/v1
kind: Deployment
metadata:
namespace: gdk-k8s
name: users
spec:
selector:
matchLabels:
app: users
template:
metadata:
labels:
app: users
spec:
serviceAccountName: gdk-service
containers:
- name: users
image: 'gdkrepo.azurecr.io/users:latest' # <1>
imagePullPolicy: Always # <2>
ports:
- name: http
containerPort: 8080
readinessProbe:
httpGet:
path: /health/readiness
port: 8080
initialDelaySeconds: 5
timeoutSeconds: 3
livenessProbe:
httpGet:
path: /health/liveness
port: 8080
initialDelaySeconds: 5
timeoutSeconds: 3
failureThreshold: 10
env:
- name: MICRONAUT_ENVIRONMENTS
value: azure
---
apiVersion: v1
kind: Service
metadata:
namespace: gdk-k8s
name: users
spec:
selector:
app: users
type: NodePort
ports:
- protocol: TCP
port: 8080
1 The location of the image that you created in ACR
2 Change imagePullPolicy
to Always
.
2.8.2. Update the Orders Manifest File
Edit the file named orders/k8s-azure.yml as follows:
apiVersion: apps/v1
kind: Deployment
metadata:
namespace: gdk-k8s
name: orders
spec:
selector:
matchLabels:
app: orders
template:
metadata:
labels:
app: orders
spec:
serviceAccountName: gdk-service
containers:
- name: orders
image: 'gdkrepo.azurecr.io/orders:latest' # <1>
imagePullPolicy: Always # <2>
ports:
- name: http
containerPort: 8080
readinessProbe:
httpGet:
path: /health/readiness
port: 8080
initialDelaySeconds: 5
timeoutSeconds: 3
livenessProbe:
httpGet:
path: /health/liveness
port: 8080
initialDelaySeconds: 5
timeoutSeconds: 3
failureThreshold: 10
env:
- name: MICRONAUT_ENVIRONMENTS
value: azure
---
apiVersion: v1
kind: Service
metadata:
namespace: gdk-k8s
name: orders
spec:
selector:
app: orders
type: NodePort
ports:
- protocol: TCP
port: 8080
1 The location of the image that you created in ACR
2 Change imagePullPolicy
to Always
.
2.8.3. Update the API Manifest File
Edit the file named api/k8s-azure.yml as follows:
apiVersion: apps/v1
kind: Deployment
metadata:
namespace: gdk-k8s
name: api
spec:
selector:
matchLabels:
app: api
template:
metadata:
labels:
app: api
spec:
serviceAccountName: gdk-service
containers:
- name: api
image: 'gdkrepo.azurecr.io/api:latest' # <1>
imagePullPolicy: Always # <2>
ports:
- name: http
containerPort: 8080
readinessProbe:
httpGet:
path: /health/readiness
port: 8080
initialDelaySeconds: 5
timeoutSeconds: 3
livenessProbe:
httpGet:
path: /health/liveness
port: 8080
initialDelaySeconds: 5
timeoutSeconds: 3
failureThreshold: 10
env:
- name: MICRONAUT_ENVIRONMENTS
value: azure
---
apiVersion: v1
kind: Service
metadata:
namespace: gdk-k8s
name: api
spec:
selector:
app: api
type: LoadBalancer
ports:
- protocol: TCP
port: 8080
1 The location of the image that you created in ACR
2 Change imagePullPolicy
to Always
.
3. Deploy Microservices to AKS #
-
Deploy the auth.yml file that specifies service roles and secrets:
kubectl apply -f auth.yml
-
Deploy the users microservice:
kubectl apply -f users/k8s-azure.yml
-
Deploy the orders microservice:
kubectl apply -f orders/k8s-azure.yml
-
Deploy the api microservice:
kubectl apply -f api/k8s-azure.yml
4. Test Integration Between the Microservices Deployed to AKS #
- Run the following command to check the status of the pods and make sure that all of them have the status “Running”:
kubectl get pods -n=gdk-k8s
NAME READY STATUS RESTARTS AGE api-6fb4cd949f-kxxx8 1/1 Running 0 12s orders-595887ddd6-6lzp4 1/1 Running 0 17s users-df6f78cd7-lgnzx 1/1 Running 0 23s
-
Run this command to check the status of the microservices:
kubectl get services -n=gdk-k8s
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE api LoadBalancer 10.100.208.154 <redacted> 8080:31171/TCP 31s orders NodePort 10.100.157.155 <none> 8080:30742/TCP 36s users NodePort 10.100.126.97 <none> 8080:31580/TCP 42s
If
EXTERNAL-IP
is in a<pending>
state, wait a couple of seconds and then run the command again. -
Retrieve the URL of the api microservice and set it as the value of the
$API_URL
environment variable:export API_URL=http://$(kubectl get svc api -n=gdk-k8s -o json | jq -r '.status.loadBalancer.ingress[0].ip'):8080
-
Run a
curl
command to create a new user via the api microservice:curl -X "POST" "$API_URL/api/users" \ -H 'Content-Type: application/json; charset=utf-8' \ -d '{ "first_name": "Nemanja", "last_name": "Mikic", "username": "nmikic" }'
Your output should look like:
{ "id":1, "username":"nmikic", "first_name":"Nemanja", "last_name":"Mikic" }
-
Run a
curl
command to create a new order via the api microservice:curl -X "POST" "$API_URL/api/orders" \ -H 'Content-Type: application/json; charset=utf-8' \ -d '{ "user_id": 1, "item_ids": [1,2] }'
Your output should include details of the order, as follows:
{ "id": 1, "user": { "first_name": "Nemanja", "last_name": "Mikic", "id": 1, "username": "nmikic" }, "items": [ { "id": 1, "name": "Banana", "price": 1.5 }, { "id": 2, "name": "Kiwi", "price": 2.5 } ], "total": 4.0 }
-
Run a
curl
command to list the orders:curl "$API_URL/api/orders" \ -H 'Content-Type: application/json; charset=utf-8'
You should see output that is similar to the following:
[ { "id": 1, "user": { "first_name": "Nemanja", "last_name": "Mikic", "id": 1, "username": "nmikic" }, "items": [ { "id": 1, "name": "Banana", "price": 1.5 }, { "id": 2, "name": "Kiwi", "price": 2.5 } ], "total": 4.0 } ]
-
Try to place an order for a user who does not exist (with
id
100). Run acurl
command:curl -X "POST" "$API_URL/api/orders" \ -H 'Content-Type: application/json; charset=utf-8' \ -d '{ "user_id": 100, "item_ids": [1,2] }'
You should see the following error message:
{ "message": "Bad Request", "_links": { "self": [ { "href": "/api/orders", "templated": false } ] }, "_embedded": { "errors": [ { "message": "User with id 100 doesn't exist" } ] } }
7. Clean up Cloud Resources #
Once you are done with this guide, you can delete the Azure resources created to avoid incurring unnecessary charges.
Delete the resource group and all of its resources with:
az group delete --name gdkguides
Alternatively, run these commands to delete resources individually:
kubectl delete namespaces gdk-k8s
az aks delete --name gdkCluster --resource-group gdkguides
az acr delete --name gdkrepo
az group delete --name gdkguides
Summary #
This guide demonstrated how to use Kubernetes Service Discovery and Distributed Configuration, provided with the Micronaut Kubernetes integration, to connect three microservices, and to deploy these microservices to a Kubernetes cluster in the Azure Kubernetes Service.