az --version
Contents
- What you’ll learn
- Additional prerequisites
- Getting started
- Managing an Azure Container Registry
- Uploading images to a container registry
- Creating a Kubernetes cluster on AKS
- Deploying microservices to AKS
- Testing the microservices
- Tearing down the environment
- Great work! You’re done!
- Guide Attribution
Tags
Deploying microservices to Azure Kubernetes Service
1 hour
Prerequisites:
Table of contents
Explore how to deploy microservices to Azure Kubernetes Service (AKS) on Microsoft Azure.
What you’ll learn
You will learn how to deploy two microservices in Open Liberty containers to a Kubernetes cluster on Azure Kubernetes Service (AKS).
Kubernetes is an open source container orchestrator that automates many tasks involved in deploying, managing, and scaling containerized applications. If you would like to learn more about Kubernetes, check out the Deploying microservices to Kubernetes guide.
There are different cloud-based solutions for running your Kubernetes workloads. A cloud-based infrastructure enables you to focus on developing your microservices without worrying about low-level infrastructure details for deployment. Using a cloud helps you to easily scale and manage your microservices in a high-availability setup.
Azure offers a managed Kubernetes service called Azure Kubernetes Service (AKS). Using AKS simplifies the process of running Kubernetes on Azure without needing to install or maintain your own Kubernetes control plane. It provides a hosted Kubernetes cluster that you can deploy your microservices to. You will use AKS with an Azure Container Registry (ACR). ACR is a private registry that is used to store and distribute your container images. Note, because AKS is not free a small cost is associated with running this guide. See the official AKS pricing documentation for more details.
The two microservices you will deploy are called system and inventory.
The system microservice returns the JVM system properties of the running container.
It also returns the name of the pod in the HTTP header, making replicas easy to distinguish from each other.
The inventory microservice adds the properties from the system microservice to the inventory.
This demonstrates how communication can be established between pods inside a cluster.
Additional prerequisites
Before you begin, the following additional tools need to be installed:
-
Docker: You need a containerization software for building containers. Kubernetes supports various container types, but you will use Docker in this guide. For installation instructions, refer to the official Docker documentation. If you already have Docker installed, make sure to have it running.
-
Azure Subscription: To run this guide, you will need an Azure subscription. Navigate to the Microsoft Azure Purchase Options to create an account with your email and start a Pay-As-You-Go subscription.
-
Azure CLI: You will need to use the Azure Command Line Interface (CLI). See the official Install the Azure CLI documentation for information about setting up the Azure CLI for your platform. To verify that the Azure CLI is installed correctly, run the following command:
-
kubectl: You need the Kubernetes command-line tool
kubectlto interact with your Kubernetes cluster. If you do not havekubectlinstalled already, use the Azure CLI to download and installkubectlwith the following command:az aks install-cli
To begin this guide, make sure that you are logged in to Azure to get access to your subscription:
az loginGetting started
The fastest way to work through this guide is to clone the Git repository and use the projects that are provided inside:
git clone https://github.com/openliberty/guide-cloud-azure.git
cd guide-cloud-azureThe start directory contains the starting project that you will build upon.
The finish directory contains the finished project that you will build.
Before you begin, make sure you have all the necessary prerequisites.
Managing an Azure Container Registry
To deploy your microservices, you need to create an Azure Container Registry in the same location where your services are deployed, and link the registry to a resource group. Your registry will manage container instances that will be deployed to a Kubernetes cluster.
Creating a resource group
A resource group is an Azure construct to manage a logical collection of resources for your cloud deployments on Azure. You must create a new resource group to manage the resources you need for your Kubernetes deployment.
To create a resource group, an Azure location must be specified. The metadata for your resources are stored at this specified Azure location. If resources are created later without specifying a location, these new resources run in the same region that you specified for creating a resource group.
See the list of available Azure regions for your Azure subscription:
az account list-locations -o tableYou will see an output similar to the following:
DisplayName Latitude Longitude Name ------------------- ---------- ----------- ------------------ Central US 41.5908 -93.6208 centralus East US 37.3719 -79.8164 eastus East US 2 36.6681 -78.3889 eastus2 West US 37.783 -122.417 westus North Central US 41.8819 -87.6278 northcentralus South Central US 29.4167 -98.5 southcentralus Canada Central 43.653 -79.383 canadacentral Canada East 46.817 -71.217 canadaeast UK South 50.941 -0.799 uksouth UK West 53.427 -3.084 ukwest West Central US 40.890 -110.234 westcentralus West US 2 47.233 -119.852 westus2
The name column specifies the region name that you use to create your resource group.
However, AKS is not available in all regions. Make sure that the region you select is compatible with AKS.
Create a resource group using the az group create command. Remember to replace [location] with a region
that is available for your subscription and compatible with AKS.
az group create -l [location] -n guideGroupYou will see an output similar to the following:
{
"id": "/subscriptions/[subscription-id]/resourceGroups/guideGroup",
"location": "[location]",
"managedBy": null,
"name": "guideGroup",
"properties": {
"provisioningState": "Succeeded"
},
"tags": null,
"type": null
}Creating a container registry
Your private container registry manages Docker images that you build in later steps.
With the Azure az acr command, create an Azure Container Registry.
Replace [registry-name] with a container registry name that is unique within Azure and
contains 5-50 alphanumeric characters. You can check whether a registry name already exists by
using the az acr check-name -n [registry-name] command.
az acr create -g guideGroup -n [registry-name] --sku Basic --admin-enabledIn the az acr create command, the -g option specifies the resource group to designate to the container registry.
You created this resource group before as guideGroup. The -n option specifies the name of the
container registry to be created, which is defined as [registry-name]. The --admin-enabled flag indicates that the admin user is enabled.
The possible Stock Keeping Unit (SKU) values that can be passed into the --sku option are Basic, Standard, and Premium.
These different SKU options provide pricing for various levels of capacity and usage. You use a Basic SKU because it is cheaper
and the services you deploy have low storage and throughput requirements.
You will see an output similar to the following:
{
"adminUserEnabled": true,
"creationDate": "2019-06-05T20:28:09.637994+00:00",
"id": "/subscriptions/[subscription-id]/resourceGroups/guideGroup/providers/Microsoft.ContainerRegistry/registries/[registry-name]",
"location": "[location]",
"loginServer": "[registry-name].azurecr.io",
"name": "[registry-name]",
"networkRuleSet": null,
"provisioningState": "Succeeded",
"resourceGroup": "guideGroup",
"sku": {
"name": "Basic",
"tier": "Basic"
},
"status": null,
"storageAccount": null,
"tags": {},
"type": "Microsoft.ContainerRegistry/registries"
}In the output, the value for loginServer is the server name for your container registry,
which is [registry-name].azurecr.io, with all lowercase letters.
Logging into the container registry
To push Docker images to your registry, you must log in to your Azure Container Registry by using the Azure CLI.
az acr login -n [registry-name]Once you log in, you will see the following message:
Login Succeeded
Uploading images to a container registry
Building your Docker images
The starting Java project, which you can find in the start directory, is a multi-module Maven
project. It is made up of the system and inventory microservices. Each microservice exists in its own directory,
start/system and start/inventory. Both of these directories contain a Dockerfile, which is necessary
for building the Docker images. If you’re unfamiliar with Dockerfiles, check out the
Containerizing microservices guide.
Navigate to the start directory and run the following command:
mvn packageNow that your microservices are packaged, build your
Docker images using the docker build command. To build your image, you need to have Docker installed
and your Docker daemon started.
Run the following commands to build and containerize the application:
docker build -t system:1.0-SNAPSHOT system/.
docker build -t inventory:1.0-SNAPSHOT inventory/.To verify that the images are built, run the docker images command to list all local Docker images:
docker imagesYour two images system and inventory should appear in the list of all Docker images:
REPOSITORY TAG IMAGE ID CREATED SIZE inventory 1.0-SNAPSHOT 08fef024e986 4 minutes ago 471MB system 1.0-SNAPSHOT 1dff6d0b4f31 5 minutes ago 470MB
Pushing the images to a container registry
Pushing the images to a registry allows the cluster to create pods using your container images.
First, tag your container images with your registry.
Replace [registry-server] with the server name of your container registry.
To get the server for your registry, run the az acr show -n [registry-name] --query loginServer command.
The [registry-server] looks like [registry-name].azurecr.io.
docker tag system:1.0-SNAPSHOT [registry-server]/system:1.0-SNAPSHOT
docker tag inventory:1.0-SNAPSHOT [registry-server]/inventory:1.0-SNAPSHOTFinally, push your images to the registry:
docker push [registry-server]/system:1.0-SNAPSHOT
docker push [registry-server]/inventory:1.0-SNAPSHOTCreating a Kubernetes cluster on AKS
Provisioning a cluster
To create your AKS cluster, use the az aks create cluster command.
When the cluster is created, the command outputs information about the cluster.
You might need to wait while your cluster is being created.
az aks create -g guideGroup -n guideClusterRunning this command creates an AKS cluster that is called guideCluster with the resource group
guideGroup.
The option --node-count -c can also be added to this az aks create command to create a cluster
with a certain number of nodes in the Kubernetes node pool. By default, if this option is excluded,
three nodes are assigned to the node pool.
An AKS cluster requires a service principal, which is an identity that is used to represent a resource in Azure that
can be assigned roles and permissions to interact with other resources and the Azure API. The az aks create command automatically generates
a service principal to use with your newly created cluster.
Optionally, you can manually create a service principal yourself and create a cluster with this new service principal.
However, to run this command, your Azure account must have permission access to create service principals.
Merge the credentials of your cluster into your current Kubernetes configuration by using the az aks get-credentials command.
The default Kubernetes configuration file that is updated with your cluster credentials is located within the ~/.kube/config filepath.
az aks get-credentials -g guideGroup -n guideClusterYou will see an output similar to the following:
Merged "guideCluster" as current context in /Users/.kube/config
Run the following command to check the status of the available nodes in your AKS cluster:
kubectl get nodesThe kubectl get nodes command outputs information about three nodes, as the cluster was created with the default number of nodes in a node pool.
The STATUS of each node is in the Ready state.
NAME STATUS ROLES AGE VERSION aks-nodepool1-21407934-0 Ready agent 2m25s v1.12.8 aks-nodepool1-21407934-1 Ready agent 2m48s v1.12.8 aks-nodepool1-21407934-2 Ready agent 2m34s v1.12.8
Storing registry credentials in a secret
To be able to pull the images from your Azure container registry, the credentials of your registry must be added to your service through a secret.
View the password for your Azure container registry:
az acr credential show -n [registry-name] --query "passwords[0].value" -o tsvUse the kubectl create secret docker-registry command to create a secret to hold your registry credentials.
Replace [password] with the registry password that you viewed with the
az acr credential show -n [registry-name] command. The email that is associated with your Docker account replaces [email-address].
kubectl create secret docker-registry guidesecret \
--docker-server=[registry-server] \
--docker-username=[registry-name] \
--docker-password=[password] \
--docker-email=[email-address]The secret is successfully created with the following output:
secret/guidesecret created
Deploying microservices to AKS
Creating a deployment definition
Now that your container images are built and you have created a Kubernetes cluster, you can deploy the images using a Kubernetes resource definition.
A Kubernetes resource definition is a yaml file that contains a description of all your
deployments, services, or any other resources that you want to deploy. All resources can
also be deleted from the cluster by using the same yaml file that you used to deploy them.
The kubernetes.yaml resource definition file is provided for you. If you are interested
in learning more about the Kubernetes resource definition, check out the
Deploying microservices to Kubernetes
guide.
Update thekubernetes.yamlfile in thestartdirectory.kubernetes.yaml
Replace [registry-server] with your container registry server.
You can get the login server for your registry by running the az acr show -n [registry-name] --query loginServer command.
kubernetes.yaml
1apiVersion: apps/v1
2kind: Deployment
3metadata:
4 name: system-deployment
5 labels:
6 app: system
7spec:
8 selector:
9 matchLabels:
10 app: system
11 template:
12 metadata:
13 labels:
14 app: system
15 spec:
16 containers:
17 - name: system-container
18 # tag::sysImage[]
19 image: [registry-server]/system:1.0-SNAPSHOT
20 # end::sysImage[]
21 ports:
22 - containerPort: 9080
23 # tag::sysSecret[]
24 imagePullSecrets:
25 - name: guidesecret
26 # end::sysSecret[]
27---
28apiVersion: apps/v1
29kind: Deployment
30metadata:
31 name: inventory-deployment
32 labels:
33 app: inventory
34spec:
35 selector:
36 matchLabels:
37 app: inventory
38 template:
39 metadata:
40 labels:
41 app: inventory
42 spec:
43 containers:
44 - name: inventory-container
45 # tag::invImage[]
46 image: [registry-server]/inventory:1.0-SNAPSHOT
47 # end::invImage[]
48 ports:
49 - containerPort: 9081
50 # tag::invSecret[]
51 imagePullSecrets:
52 - name: guidesecret
53 # end::invSecret[]
54---
55apiVersion: v1
56kind: Service
57metadata:
58 name: system-service
59spec:
60 # tag::sysLoadBalancer[]
61 type: LoadBalancer
62 # end::sysLoadBalancer[]
63 selector:
64 app: system
65 ports:
66 - protocol: TCP
67 port: 9080
68 targetPort: 9080
69---
70apiVersion: v1
71kind: Service
72metadata:
73 name: inventory-service
74spec:
75 # tag::invLoadBalancer[]
76 type: LoadBalancer
77 # end::invLoadBalancer[]
78 selector:
79 app: inventory
80 ports:
81 - protocol: TCP
82 port: 9081
83 targetPort: 9081The image is the name and tag of the container image that you want
to use for the container. The kubernetes.yaml file references the images that you pushed to your registry
for the system and inventory repositories. These images can be pulled
with the secret that you defined before.
The service that is used to expose your deployments has a type of LoadBalancer.
This means you can access these services from IP addresses that forward incoming traffic to your nodepool via a specific port.
You can expose your services in other ways such as using a NodePort service type.
Deploying your application
To deploy your microservices to Azure Kubernetes Service, you need Kubernetes to create
the contents of the kubernetes.yaml file.
Run the following command to deploy the resources defined in the kubernetes.yaml file:
kubectl create -f kubernetes.yamlYou will see an output similar to the following:
deployment.apps/system-deployment created deployment.apps/inventory-deployment created service/system-service created service/inventory-service created
Run the following command to check the status of your pods:
kubectl get podsIf all the pods are healthy and running, you see an output similar to the following:
NAME READY STATUS RESTARTS AGE system-deployment-6bd97d9bf6-4ccds 1/1 Running 0 15s inventory-deployment-645767664f-nbtd9 1/1 Running 0 15s
Making requests to the microservices
You need the external IP addresses that are associated with the system and inventory services to try out your microservices.
Take note of the EXTERNAL-IP in the output of the following commands. It is the
hostname that you will later substitute into [EXTERNAL-IP] to access the system and inventory services.
View the information of the system service to see its EXTERNAL-IP address:
kubectl get service/system-serviceYou need to wait a while for the EXTERNAL-IP to change from <pending> to an IP address.
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE system-service LoadBalancer 10.0.27.66 <pending> 9080:32436/TCP 26s
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE system-service LoadBalancer 10.0.27.66 23.99.223.10 9080:32436/TCP 74s
View the information of the inventory service to see its EXTERNAL-IP address:
kubectl get service/inventory-serviceYou will need to wait a while for the EXTERNAL-IP to change from <pending> to an IP address.
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE inventory-service LoadBalancer 10.0.103.223 <pending> 9081:32739/TCP 69s
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE inventory-service LoadBalancer 10.0.103.223 168.61.174.136 9081:32739/TCP 2m8s
To access your microservices, point your browser to the following URLs, substituting the appropriate EXTERNAL-IP hostnames
for the system and inventory services:
-
http://[system-EXTERNAL-IP]:9080/system/properties -
http://[inventory-EXTERNAL-IP]:9081/inventory/systems
In the first URL, you see a result in JSON format with the system properties of the container JVM. The second URL returns an empty list, which is expected because no system properties are stored in the inventory yet.
Point your browser to the http://[inventory-EXTERNAL-IP]:9081/inventory/systems/[system-EXTERNAL-IP] URL. When you visit this URL, these system
properties are automatically stored in the inventory. Go back to http://[inventory-EXTERNAL-IP]:9081/inventory/systems and
you see a new entry for [system-EXTERNAL-IP].
Testing the microservices
A few tests are included for you to test the basic functionality of the microservices. If a test failure occurs, then you might have introduced a bug into the code. To run the tests, wait for all pods to be in the ready state before you proceed further.
pom.xml
1<?xml version='1.0' encoding='utf-8'?>
2<project xmlns="http://maven.apache.org/POM/4.0.0"
3 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
5
6 <modelVersion>4.0.0</modelVersion>
7
8 <groupId>io.openliberty.guides</groupId>
9
10 <artifactId>guide-cloud-azure-inventory</artifactId>
11 <version>1.0-SNAPSHOT</version>
12 <packaging>war</packaging>
13
14 <properties>
15 <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
16 <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
17 <maven.compiler.source>11</maven.compiler.source>
18 <maven.compiler.target>11</maven.compiler.target>
19 <!-- Default test properties -->
20 <!-- tag::sysHttpPort[] -->
21 <sys.http.port>9080</sys.http.port>
22 <!-- end::sysHttpPort[] -->
23 <!-- tag::invHttpPort[] -->
24 <inv.http.port>9081</inv.http.port>
25 <!-- end::invHttpPort[] -->
26 <inv.https.port>9444</inv.https.port>
27 <!-- tag::sysKubeService[] -->
28 <system.ip>system-service</system.ip>
29 <!-- end::sysKubeService[] -->
30 <!-- tag::invKubeService[] -->
31 <inventory.ip>inventory-service</inventory.ip>
32 <!-- end::invKubeService[] -->
33 <!-- Liberty configuration -->
34 <liberty.var.system.http.port>${sys.http.port}</liberty.var.system.http.port>
35 <liberty.var.http.port>${inv.http.port}</liberty.var.http.port>
36 <liberty.var.https.port>${inv.https.port}</liberty.var.https.port>
37 </properties>
38
39 <dependencies>
40 <!-- Provided dependencies -->
41 <dependency>
42 <groupId>jakarta.platform</groupId>
43 <artifactId>jakarta.jakartaee-api</artifactId>
44 <version>10.0.0</version>
45 <scope>provided</scope>
46 </dependency>
47 <dependency>
48 <groupId>org.eclipse.microprofile</groupId>
49 <artifactId>microprofile</artifactId>
50 <version>6.1</version>
51 <type>pom</type>
52 <scope>provided</scope>
53 </dependency>
54 <!-- For tests -->
55 <dependency>
56 <groupId>org.junit.jupiter</groupId>
57 <artifactId>junit-jupiter</artifactId>
58 <version>5.11.3</version>
59 <scope>test</scope>
60 </dependency>
61 <dependency>
62 <groupId>org.jboss.resteasy</groupId>
63 <artifactId>resteasy-client</artifactId>
64 <version>6.2.10.Final</version>
65 <scope>test</scope>
66 </dependency>
67 <dependency>
68 <groupId>org.jboss.resteasy</groupId>
69 <artifactId>resteasy-json-binding-provider</artifactId>
70 <version>6.2.10.Final</version>
71 <scope>test</scope>
72 </dependency>
73 <dependency>
74 <groupId>org.glassfish</groupId>
75 <artifactId>jakarta.json</artifactId>
76 <version>2.0.1</version>
77 <scope>test</scope>
78 </dependency>
79 </dependencies>
80
81 <build>
82 <finalName>${project.artifactId}</finalName>
83 <plugins>
84 <plugin>
85 <groupId>org.apache.maven.plugins</groupId>
86 <artifactId>maven-war-plugin</artifactId>
87 <version>3.4.0</version>
88 </plugin>
89 <!-- Enable Liberty Maven plugin -->
90 <plugin>
91 <groupId>io.openliberty.tools</groupId>
92 <artifactId>liberty-maven-plugin</artifactId>
93 <version>3.11.1</version>
94 </plugin>
95 <!-- Plugin to run unit tests -->
96 <plugin>
97 <groupId>org.apache.maven.plugins</groupId>
98 <artifactId>maven-surefire-plugin</artifactId>
99 <version>3.5.1</version>
100 </plugin>
101 <!-- Plugin to run functional tests -->
102 <plugin>
103 <groupId>org.apache.maven.plugins</groupId>
104 <artifactId>maven-failsafe-plugin</artifactId>
105 <version>3.5.1</version>
106 <configuration>
107 <systemPropertyVariables>
108 <system.ip>${system.ip}</system.ip>
109 <inventory.ip>${inventory.ip}</inventory.ip>
110 <system.http.port>${sys.http.port}</system.http.port>
111 <inventory.http.port>${inv.http.port}</inventory.http.port>
112 </systemPropertyVariables>
113 </configuration>
114 </plugin>
115 </plugins>
116 </build>
117</project>The default properties that are defined in the pom.xml file are:
| Property | Description |
|---|---|
|
Name of the Kubernetes Service wrapping the |
|
Name of the Kubernetes Service wrapping the |
|
The HTTP port for the Kubernetes Service |
|
The HTTP port of the Kubernetes Service |
Running the tests
Run the Maven failsafe:integration-test goal to test your microservices by replacing [system-EXTERNAL-IP] and [inventory-EXTERNAL-IP]
with the values that were determined in the previous section.
mvn failsafe:integration-test -Dsystem.ip=[system-EXTERNAL-IP] -Dinventory.ip=[inventory-EXTERNAL-IP]If the tests pass, you will see an output similar to the following for each service:
------------------------------------------------------- T E S T S ------------------------------------------------------- Running it.io.openliberty.guides.system.SystemEndpointIT Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.673 sec - in it.io.openliberty.guides.system.SystemEndpointIT Results: Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
------------------------------------------------------- T E S T S ------------------------------------------------------- Running it.io.openliberty.guides.inventory.InventoryEndpointIT Tests run: 4, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 2.222 sec - in it.io.openliberty.guides.inventory.InventoryEndpointIT Results: Tests run: 4, Failures: 0, Errors: 0, Skipped: 0
Tearing down the environment
It is important to clean up your resources when you are finished with the guide so that you do not incur extra charges for ongoing usage.
When you no longer need your deployed microservices, you can delete all Kubernetes resources
by running the kubectl delete command:
kubectl delete -f kubernetes.yamlBecause you are done testing your cluster, clean up all of its related sources using the az group delete command.
This command removes the resource group, container service, and all related resources:
az group delete -g guideGroup --yes --no-waitGreat work! You’re done!
You have just deployed two microservices running in Open Liberty to Azure Kubernetes Service (AKS). You also
learned how to use kubectl to deploy your microservices on a Kubernetes cluster.
Guide Attribution
Deploying microservices to Azure Kubernetes Service by Open Liberty is licensed under CC BY-ND 4.0
Copied to clipboard
Prerequisites:
Nice work! Where to next?
What did you think of this guide?
Thank you for your feedback!
What could make this guide better?
Raise an issue to share feedback
Create a pull request to contribute to this guide
Need help?
Ask a question on Stack Overflow
