This sample shows you how to deploy an existing Liberty application to AKS using Liberty on AKS solution templates. When you're finished, you can continue to manage the application via the Azure CLI or Azure Portal.
Cargo Tracker is a Domain-Driven Design Jakarta EE application. The application is built with Maven and deployed to Open Liberty running on Azure Kubernetes Service (AKS). The application is exposed by Azure Application Gateway service. For quickstart uses the official Azure offer for running Liberty on AKS, see Deploy a Java application with Open Liberty or WebSphere Liberty on an Azure Kubernetes Service (AKS) cluster.
- Deploy Cargo Tracker to Open Liberty on Azure Kubernetes Service (AKS)
- Introduction
- Prerequisites
- Unit-1 - Deploy and monitor Cargo Tracker
- Clone Cargo Tracker
- Prepare your variables for deployments
- Clone Liberty on AKS Bicep templates
- Build Liberty on AKS Bicep templates
- Sign in to Azure
- Create a resource group
- Prepare deployment parameters
- Invoke Liberty on AKS Bicep template to deploy the Open Liberty Operator
- Create an Azure Database for PostgreSQL instance
- Create Application Insights
- Build and deploy Cargo Tracker
- Monitor Liberty application
- Unit-2 - Automate deployments using GitHub Actions
- Unit-3 - Automate deployments using AZD
- Appendix 1 - Exercise Cargo Tracker Functionality
- Appendix 2 - Learn more about Cargo Tracker
- Appendix 3 - Run cargotracker locally against cloud supporting resources
In this sample, you will:
- Deploy Cargo Tracker:
- Create PostgreSQL Database
- Create the Cargo Tracker - build with Maven
- Provision Azure Infra Services with BICEP templates
- Create an Azure Container Registry
- Create an Azure Kubernetes Service
- Build your application, Open Liberty into a container image
- Push your application image to the container registry
- Deploy your application to AKS
- Expose your application with the Azure Application Gateway
- Verify your application
- Monitor application
- Automate deployments using GitHub Actions
- Automate deployments using AZD
-
JDK 17
-
GIT: git version
2.33.6
. -
Kubernetes CLI version as following:
Client Version: version.Info{Major:"1", Minor:"26", GitVersion:"v1.26.3", GitCommit:"9e644106593f3f4aa98f8a84b23db5fa378900bd", GitTreeState:"clean", BuildDate:"2023-03-15T13:40:17Z", GoVersion:"go1.19.7", Compiler:"gc", Platform:"linux/amd64"} Kustomize Version: v4.5.7
-
Maven: Apache Maven
3.8.7
(NON_CANONICAL). -
Azure Subscription, on which you are able to create resources and assign permissions
- View your subscription using
az account show
- If you don't have an account, you can create one for free.
- Your subscription is accessed using an Azure Service Principal with at least Contributor and User Access Administrator permissions.
- View your subscription using
Note
You can jump to Unit-3 - Automate deployments using AZD if you want to automate deployments using AZD instead of manually deploying Cargo Tracker.
Clone the sample app repository to your development environment.
mkdir cargotracker-liberty-aks
export DIR="$PWD/cargotracker-liberty-aks"
git clone https://github.com/Azure-Samples/cargotracker-liberty-aks.git ${DIR}/cargotracker
cd ${DIR}/cargotracker
git checkout 20241031
If you see a message about detached HEAD state
, it is safe to ignore. It just means you have checked out a tag.
The steps in this section are optional unless you want to enable the AI shortest path computation.
-
Create an Azure OpenAI account and get the required credentials.
-
In a new tab, visit Create and deploy an Azure OpenAI Service resource.
-
If you want to use the following steps, select the Portal tab. Otherwise, just follow the documentation to get the following environment variable values in the way best suited to your needs.
AZURE_OPENAI_KEY
: Your Azure OpenAI API key.AZURE_OPENAI_ENDPOINT
: Your Azure OpenAI Endpoint. This will be something likehttps://ejb011017openai.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT_NAME
: Your Azure OpenAI Deployment name. This example usesgpt-4o
-
Follow the steps up to but not including the section Deploy a model.
-
Expand Resource management in the left navigation bar and select Keys and Endpoint.
-
Select the copy icon next to the value for KEY 1 and save the value as the value of your
AZURE_OPENAI_KEY
environment variable. -
Select the copy icon next to the value for Endpoint and save the value as the value of your
AZURE_OPENAI_ENDPOINT
environment variable. -
Continue in the steps with the section Deploy a model.
-
When you get to the step asking you to Create new deployment, use the following substitutions.
- For Select a model select gpt-4o.
- For Deployment name use gpt-4o.
- To learn more about Azure OpenAI see Azure OpenAI Documentation.
-
Create a bash script with environment variables by making a copy of the supplied template. Customize the variables indicated.
cp ${DIR}/cargotracker/.scripts/setup-env-variables-template.sh ${DIR}/setup-env-variables.sh
Open ${DIR}/setup-env-variables.sh
and customize the values as indicated. If running the AI shortest path feature, uncomment and customize those values as described previously.
Then, set the environment:
source ${DIR}/setup-env-variables.sh
cd ${DIR}
git clone https://github.com/WASdev/azure.liberty.aks ${DIR}/azure.liberty.aks
cd ${DIR}/azure.liberty.aks
git checkout ${LIBERTY_AKS_REPO_REF}
cd ${DIR}
If you see a warning about being in 'detached HEAD' state, it is safe to ignore.
cd ${DIR}/azure.liberty.aks
export VERSION=$(grep -A4 "<parent>" pom.xml | grep "<version>" | awk -F'[<>]' '{print $3}')
cd ${DIR}
curl -L -o ${DIR}/azure-javaee-iaas-parent-${VERSION}.pom \
https://github.com/azure-javaee/azure-javaee-iaas/releases/download/azure-javaee-iaas-parent-${VERSION}/azure-javaee-iaas-parent-${VERSION}.pom
mvn install:install-file -Dfile=${DIR}/azure-javaee-iaas-parent-${VERSION}.pom \
-DgroupId=com.microsoft.azure.iaas \
-DartifactId=azure-javaee-iaas-parent \
-Dversion=${VERSION} \
-Dpackaging=pom
cd ${DIR}/azure.liberty.aks
mvn clean package -DskipTests
If you haven't already, sign into your Azure subscription by using the az login
command and follow the on-screen directions.
az login --use-device-code
If you have multiple Azure tenants associated with your Azure credentials, you must specify which tenant you want to sign in to. You can do this with the --tenant
option. For example, az login --tenant contoso.onmicrosoft.com
.
Create a resource group with az group create
. Resource group names must be globally unique within a subscription.
az group create \
--name ${RESOURCE_GROUP_NAME} \
--location ${LOCATION}
Several parameters are required to invoke the Bicep templates. Parameters and their value are listed in the table. Make sure the variables have correct value.
Parameter Name | Value | Note |
---|---|---|
_artifactsLocation |
https://raw.githubusercontent.com/WASdev/azure.liberty.aks/${LIBERTY_AKS_REPO_REF}/src/main/ |
This quickstart is using templates and scripts from WASdev/azure.liberty.aks/${LIBERTY_AKS_REPO_REF} . |
createCluster |
true |
This value causes provisioning of Azure Kubernetes Service. |
vmSize |
Standard_DS2_v2 |
VM size of AKS node. |
minCount |
1 |
Minimum count of AKS nodes. |
maxCount |
5 |
Maximum count of AKS nodes. |
createACR |
true |
This value causes provisioning of Azure Container Registry. |
deployApplication |
false |
The application will be deployed on the later section. |
enableAppGWIngress |
true |
The value causes to provision Azure Application Gateway Ingress Controller. |
appGatewayCertificateOption |
generateCert |
The option causes generation self-signed certificate for Application Gateway. |
enableCookieBasedAffinity |
true |
The value causes to enable cookie-based affinity for Application Gateway backend setting. |
Create parameter file.
cat <<EOF >parameters.json
{
"$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"_artifactsLocation": {
"value": "https://raw.githubusercontent.com/WASdev/azure.liberty.aks/${LIBERTY_AKS_REPO_REF}/src/main/"
},
"location": {
"value": "eastus"
},
"createCluster": {
"value": true
},
"vmSize": {
"value": "Standard_DS2_v2"
},
"minCount": {
"value": 1
},
"maxCount": {
"value": 5
},
"createACR": {
"value": true
},
"deployApplication": {
"value": false
},
"enableAppGWIngress": {
"value": true
},
"appGatewayCertificateOption": {
"value": "generateCert"
},
"enableCookieBasedAffinity": {
"value": true
}
}
}
EOF
Invoke the Bicep template in ${DIR}/azure.liberty.aks/target/main/bicep/mainTemplate.bicep
to deploy Open Liberty Operator on AKS.
Run the following command to validate the parameter file.
az deployment group validate \
--resource-group ${RESOURCE_GROUP_NAME} \
--name liberty-on-aks \
--parameters @parameters.json \
--template-file ${DIR}/azure.liberty.aks/target/bicep/mainTemplate.bicep
The command should be completed without error. If there is, you must resolve it before moving on. Verify the exit status from the command by examining shell's exit status. In POSIX environments, this is $?
.
echo $?
The value must be 0.
Next, invoke the template.
az deployment group create \
--resource-group ${RESOURCE_GROUP_NAME} \
--name liberty-on-aks \
--parameters @parameters.json \
--template-file ${DIR}/azure.liberty.aks/target/bicep/mainTemplate.bicep
It takes more than 10 minutes to finish the deployment. The Open Liberty Operator is running in namespace default
.
While the previous command runs, use az postgres flexible-server create
to provision a PostgreSQL instance on Azure. The data server allows access from Azure Services.
az postgres flexible-server create \
--resource-group ${RESOURCE_GROUP_NAME} \
--name ${DB_SERVER_NAME} \
--location ${LOCATION} \
--admin-user ${DB_ADMIN_USER} \
--admin-password ${DB_PASSWORD} \
--version 15 --public-access 0.0.0.0
--tier Burstable --sku-name Standard_B1ms --yes
az postgres flexible-server db create \
--resource-group ${RESOURCE_GROUP_NAME} \
--server-name ${DB_SERVER_NAME} \
--database-name ${DB_NAME}
echo "Allow Access to Azure Services"
az postgres flexible-server firewall-rule create \
-g ${RESOURCE_GROUP_NAME} \
-n ${DB_SERVER_NAME} \
-r "AllowAllWindowsAzureIps" \
--start-ip-address "0.0.0.0" \
--end-ip-address "0.0.0.0"
Once the server has been deployed, you must set this parameter and restart the database.
az postgres flexible-server parameter set --name max_prepared_transactions --value 10 -g ${RESOURCE_GROUP_NAME} --server-name ${DB_SERVER_NAME}
az postgres flexible-server restart -g ${RESOURCE_GROUP_NAME} --name ${DB_SERVER_NAME}
To integrate with Application Insights, you need to have an Application Insights instance and expose metrics to it using the Java agent.
First, install or upgrade application-insights
extension.
az extension add --upgrade -n application-insights
Create a Log Analytics Workspace.
az monitor log-analytics workspace create \
--resource-group ${RESOURCE_GROUP_NAME} \
--workspace-name ${WORKSPACE_NAME} \
--location ${LOCATION}
export WORKSPACE_ID=$(az monitor log-analytics workspace list -g ${RESOURCE_GROUP_NAME} --query '[0].id' -o tsv)
This quickstart uses Container Insights to monitor AKS. Enable it with the following commands.
export AKS_CLUSTER_NAME=$(az aks list -g ${RESOURCE_GROUP_NAME} --query \[0\].name -o tsv)
az aks enable-addons \
--addons monitoring \
--name ${AKS_CLUSTER_NAME} \
--resource-group ${RESOURCE_GROUP_NAME} \
--workspace-resource-id ${WORKSPACE_ID}
Next, provision Application Insights.
az monitor app-insights component create \
--resource-group ${RESOURCE_GROUP_NAME} \
--app ${APPINSIGHTS_NAME} \
--location ${LOCATION} \
--workspace ${WORKSPACE_ID}
Obtain the connection string of Application Insights which will be used in later section.
export APPLICATIONINSIGHTS_CONNECTION_STRING=$(az monitor app-insights component show \
--resource-group ${RESOURCE_GROUP_NAME} \
--query '[0].connectionString' -o tsv)
First, prepare the environment variables used in the build time. If you haven't set the deployment variables, run the following command:
source ${DIR}/cargotracker/.scripts/setup-env-variables.sh
Next, obtain the registry information.
export REGISTRY_NAME=$(az acr list -g ${RESOURCE_GROUP_NAME} --query '[0].name' -o tsv)
export LOGIN_SERVER=$(az acr show -n ${REGISTRY_NAME} -g ${RESOURCE_GROUP_NAME} --query 'loginServer' -o tsv)
Now, you're ready to build Cargo Tracker.
mvn clean install -PopenLibertyOnAks --file ${DIR}/cargotracker/pom.xml
The war file is created at ${DIR}/cargotracker/target/cargo-tracker.war
.
The following steps are to build a container image which will be deployed to AKS.
The image tag is constructed with ${project.artifactId}:${project.version}
. Run the following command to obtain their values.
export IMAGE_NAME=$(mvn -q -Dexec.executable=echo -Dexec.args='${project.artifactId}' --non-recursive exec:exec --file ${DIR}/cargotracker/pom.xml)
export IMAGE_VERSION=$(mvn -q -Dexec.executable=echo -Dexec.args='${project.version}' --non-recursive exec:exec --file ${DIR}/cargotracker/pom.xml)
Run ac acr build
command to build the container image.
cd ${DIR}/cargotracker/target
az acr build -t ${IMAGE_NAME}:${IMAGE_VERSION} -r ${REGISTRY_NAME} .
The image is ready to deploy to AKS. Run the following command to connect to AKS cluster.
export AKS_CLUSTER_NAME=$(az aks list -g ${RESOURCE_GROUP_NAME} --query \[0\].name -o tsv)
az aks get-credentials --resource-group ${RESOURCE_GROUP_NAME} --name $AKS_CLUSTER_NAME
Run the following command to create secrets for data source connection and Application Insights connection.
Then deploy the container image to AKS cluster.
kubectl apply -f ${DIR}/cargotracker/target/db-secret.yaml
kubectl apply -f ${DIR}/cargotracker/target/app-insight.yaml
kubectl apply -f ${DIR}/cargotracker/target/openlibertyapplication.yaml
kubectl get pod -w
Press Control + C
to exit the watching mode.
Now, Cargo Tracker is running on Open Liberty, and connecting to Application Insights. You are able to monitor the application.
This section uses Application Insights and Azure Log Analytics to monitor Open Liberty and Cargo Tracker. You can find the resource from your working resource group.
You can open Cargo Tracker in your web browser. Use the following commands to obtain URL of Cargo Tracker. When accessing the application, if you get "502 Bad Gateway" response, just wait a few minutes.
export GATEWAY_PUBLICIP_ID=$(az network application-gateway list \
--resource-group ${RESOURCE_GROUP_NAME} \
--query '[0].frontendIPConfigurations[0].publicIPAddress.id' -o tsv)
export GATEWAY_HOSTNAME=$(az network public-ip show --ids ${GATEWAY_PUBLICIP_ID} --query 'dnsSettings.fqdn' -o tsv)
export CARGO_TRACKER_URL="http://${GATEWAY_HOSTNAME}/cargo-tracker/"
echo "Cargo Tracker URL: ${CARGO_TRACKER_URL}"
Once you have the URL, follow Appendix 1 - Exercise Cargo Tracker Functionality to make some calls.
You can also curl
the REST API exposed by Cargo Tracker. It's strongly recommended you get familiar with Cargo Tracker with the above exercise.
The /graph-traversal/shortest-path
REST API allows you to retrieve shortest path from origin to destination.
The API requires the following parameters:
Parameter Name | Value |
---|---|
origin |
The UN location code value of origin and destination must be five characters long, the first two must be alphabetic and the last three must be alphanumeric (excluding 0 and 1). |
destination |
The UN location code value of origin and destination must be five characters long, the first two must be alphabetic and the last three must be alphanumeric (excluding 0 and 1). |
deadline |
Optional. Deadline value must be eight characters long. |
You can run the following curl command:
curl --verbose -X GET -H "Accept: application/json" "${CARGO_TRACKER_URL}rest/graph-traversal/shortest-path?origin=CNHKG&destination=USNYC"
The /handling/reports
REST API allows you to send an asynchronous message with the information to the handling event registration system for proper registration.
The API requires the following parameters:
Parameter Name | Value |
---|---|
completionTime |
Must be ClockHourOfAmPm. Format: m/d/yyyy HH:MM tt , e.g 3/29/2023 9:30 AM |
trackingId |
Tracking ID must be at least four characters. |
eventType |
Event type value must be one of: RECEIVE, LOAD, UNLOAD, CUSTOMS, CLAIM. |
unLocode |
The UN location code value of origin and destination must be five characters long, the first two must be alphabetic and the last three must be alphanumeric (excluding 0 and 1). |
voyageNumber |
Optional. Voyage number value must be between four and five characters long. |
You can run the following curl
command to load onto voyage 0200T in New York for trackingId of ABC123
:
export DATE=$(date +'%m/%d/%Y %I:%M %p')
cat <<EOF >data.json
{
"completionTime": "${DATE}",
"trackingId": "ABC123",
"eventType": "UNLOAD",
"unLocode": "USNYC",
"voyageNumber": "0200T"
}
EOF
curl --verbose -X POST -d "@data.json" -H "Content-Type: application/json" ${CARGO_TRACKER_URL}rest/handling/reports
You can use Application Insights to detect failures. Run the following curl
command to cause a failed call. The REST API fails at incorrect datetime format.
export DATE=$(date +'%m/%d/%Y %H:%M:%S')
cat <<EOF >data.json
{
"completionTime": "${DATE}",
"trackingId": "ABC123",
"eventType": "UNLOAD",
"unLocode": "USNYC",
"voyageNumber": "0200T"
}
EOF
curl -X POST -d "@data.json" -H "Content-Type: application/json" ${CARGO_TRACKER_URL}rest/handling/reports
The above request causes an error with message like "Error 500: java.time.format.DateTimeParseException: Text '02/01/2024 08:04:49' could not be parsed at index 16".
Open the Application Insights and start monitoring Cargo Tracker. You can find the Application Insights in the same Resource Group where you created deployments using Bicep templates.
Navigate to the Application Map
blade:
Navigate to the Performance
blade:
Select operation GET /cargo-tracker/cargo, select Drill into..., number-N Samples you will find the operations are listed in the right panel.
Select the first operation with response code 200, the End-to-end transaction details page shows.
Select operation POST /cargo-tracker/rest/handling/reports, select Drill into..., number-N Samples you will find the operations are listed in the right panel.
Select the first operation with response code 204. Select the View all button in Traces & events panel, the traces and events are listed.
Navigate to the Failures
blade - you can see a collection of exceptions:
Click on an exception to see the end-to-end transaction and stack trace in context:
Navigate to the Live Metrics blade - you can see live metrics on screen with low latencies < 1 second:
Get the pod name of each server in your terminal.
kubectl -n open-liberty get pod
You will get output like the following content. The first three pods are running Open Liberty servers. The last one is running Open Liberty Operator.
NAME READY STATUS RESTARTS AGE
olo-controller-manager-77cc59655b-2r5qg 1/1 Running 0 2d5h
Get the pod name of each server in your terminal.
kubectl get pod
You will get output like the following content. The first three pods are running Open Liberty servers. The last one is running Open Liberty Operator.
NAME READY STATUS RESTARTS AGE
cargo-tracker-cluster-7c8d78c459-6s4mh 1/1 Running 0 19m
cargo-tracker-cluster-7c8d78c459-j6q8l 1/1 Running 0 19m
cargo-tracker-cluster-7c8d78c459-lczj5 1/1 Running 0 20m
Open the Log Analytics that created in previous steps.
In the Log Analytics landing page, select Logs
blade and run any of the sample queries supplied below for Open Liberty server logs.
Make sure the quary scope is your aks instance.
Type and run the following Kusto query to see operator logs, replace the PodName
with the operator pod name displayed above.
ContainerLogV2
| where PodName == "olo-controller-manager-77cc59655b-2r5qg"
| project ContainerName, LogMessage, TimeGenerated
| sort by TimeGenerated
| limit 500
Type and run the following Kusto query to see Open Liberty server logs, replace the PodName
with one of Open Liberty server name displayed above.
ContainerLogV2
| where PodName == "cargo-tracker-cluster-7c6df94fc7-5rpjd"
| project ContainerName, LogMessage, TimeGenerated
| sort by TimeGenerated
| limit 500
You can change the server pod name to query expected server logs.
Open the Log Analytics that created in previous steps.
In the Log Analytics page, select Logs
blade and run any of the sample queries supplied below for Application logs.
Type and run the following Kusto query to obtain failed dependencies:
AppDependencies
| where Success == false
| project Target, DependencyType, Name, Data, OperationId, AppRoleInstance
Type and run the following Kusto query to obtain java.time.format.DateTimeParseException
exceptions:
AppExceptions
| where ExceptionType == "java.time.format.DateTimeParseException"
| project TimeGenerated, ProblemId, Method, OuterMessage, AppRoleInstance
| sort by TimeGenerated
| limit 100
Type and run the following Kusto query to obtain specified failed request:
AppRequests
| where OperationName contains "POST" and ResultCode == "500"
-
Fork the repository by clicking the 'Fork' button on the top right of the page. This creates a local copy of the repository for you to work in.
-
Configure GITHUB Actions: Follow the instructions in the GITHUB_ACTIONS_CONFIG.md file (Located in the .github folder.)
-
Manually run the workflow
- Under your repository name, click Actions.
- In the left sidebar, click the workflow "Setup OpenLiberty on AKS".
- Above the list of workflow runs, select Run workflow.
- Configure the workflow.
- Use the Branch dropdown to select the workflow's main branch.
- For Azure region select an appropriate region. Take note of this region for potential use later.
- For Choose the wait time before deleting resources select an appropriate value for your usage.
- Leave the remaining values at their default.
- Click Run workflow.
The workflow uses the source code behind the official Azure offer for running Liberty on AKS by checking it out and invoking it from Azure CLI.
This job is to build Liberty on AKS template into a ZIP file containing the ARM template to invoke.
-
Set up environment to build the Liberty on AKS templates
- Set up JDK 17
- Set up bicep 0.29.47
-
Download dependencies
- Checkout azure-javaee-iaas, this is a precondition necessary to build Liberty on AKS templates. For more details, see Azure Marketplace Azure Application (formerly known as Solution Template) Helpers.
-
Checkout and build Liberty on AKS templates
-
Checkout ${{ env.aksRepoUserName }}/azure.liberty.aks. Checkout WASdev/azure.liberty.aks by default. This repository contains all the BICEP templates that provision Azure resources, configure Liberty and deploy app to AKS.
-
Build and test ${{ env.aksRepoUserName }}/azure.liberty.aks. Build and package the Liberty on AKS templates into a ZIP file (e.g. azure.liberty.aks-1.0.32-arm-assembly.zip). The structure of the ZIP file is:
├── mainTemplate.json (ARM template that is built from BICEP files, which will be invoked for the following deployments) └── scripts (shell scripts and metadata)
-
Archive Archive azure.liberty.aks template template. Upload the ZIP file to the pipeline. The later jobs will download the ZIP file for further deployments.
-
This job is to deploy PostgreSQL server and configure firewall settings.
- Set Up Azure Database for PostgreSQL
- azure-login. Login Azure.
- Create Resource Group. Create a resource group to which the database will deploy.
- Set Up Azure Postgresql to Test dbTemplate. Provision Azure Database for PostgreSQL Single Server. The server allows access from Azure services.
This job is to provision Azure resources, run Open Liberty Operator on AKS using the solution template.
-
Download the Liberty on AKS solution template
- Checkout ${{ env.aksRepoUserName }}/azure.liberty.aks. Checkout WASdev/azure.liberty.aks to find the version information.
- Get version information from azure.liberty.aks/pom.xml. Get the version info for solution template ZIP file, which is used to generate the ZIP file name:
azure.liberty.aks-${version}-arm-assembly.zip
- Output artifact name for Download action. Generate and output the ZIP file name:
azure.liberty.aks-${version}-arm-assembly.zip
. - Download artifact for deployment. Download the ZIP file that is built in job:preflight.
-
Deploy Liberty on AKS
- azure-login. Login Azure.
- Create Resource Group. Create a resource group for Liberty on AKS.
- Checkout cargotracker. Checkout the parameter template.
- Prepare parameter file. Set values to the parameters.
- Validate Deploy of Open Liberty Server Cluster Domain offer. Validate the parameters file in the context of the bicep template to be invoked. This will catch some errors before taking the time to start the full deployment.
--template-file
is the mainTemplate.json from solution template ZIP file.--parameters
is the parameter file created in the last step. - Deploy Open Liberty Server Cluster Domain offer. Invoke the mainTemplate.json to deploy resources and configurations. After the deployment completes, you'll get the following result:
- An Azure Container Registry. It'll store app image in the later steps.
- An Azure Kubernetes Service with Open Liberty Operator running in
default
namespace.
- azure-login. Login Azure.
- Deploy Log Analytics Workspace. Provision Log Analytics Workspace to store logs for Container Insights and metrics for Application Insights.
- Enable Container Insights. Enable Azure Monitor in the existing AKS cluster and enable Container Insights.
- Provision Application Insights. Provision Application Insights to monitor the application. Cargo Tracker will connect to the App Insight in later steps. Application Insights shares the same workspace with Container Insights.
This job is to build app, push it to ACR and apply it to Open Liberty server running on AKS.
-
Prepare env
- Set up JDK 1.8。
- Install jq.
- Prepare variables. Obtain AKS and ACR resource properties that will be used in later deployment.
-
Deploy Cargo Tracker
- Checkout cargotracker. Checkout source code of cargo tracker from this repository.
- Build the applications. Set required environment variables and build cargo tracker with Maven.
- Query version string for deployment verification. Obtain the app version string for later verification.
- Build an image and upload to ACR. Build cargo tracker into a docker image with docker file locating in Dockerfile, and push the image to ACR.
- Connect to AKS cluster. Connect to AKS cluster to deploy cargo tracker.
- Apply deployment files. Apply data source configuration in
target/db-secret.yaml
, App Insight configuration intarget/app-insight.yaml
and cargo tracker metadata intarget/openlibertyapplication.yaml
. This will cause cargo tracker deployed to the AKS cluster. - Verify pods are ready. Make sure Cargo Tracker is live.
- Query Application URL. Obtain cargo tracker URL.
-
Make REST API calls
- A HTTP GET request.
- A HTTP POST request.
- An datetime format failure request.
-
Print app URL. Print the cargo tracker URL to pipeline summary page. Now you'are able to access cargo tracker with the URL from your browser.
Use following steps to automate deployments using the Azure Developer CLI (azd).
- Azure Developer CLI (azd) installed.
- Docker installed. You can install Docker by following the instructions here.
- Azure CLI installed. You can install the Azure CLI by following the instructions here.
- Helm installed. For instructions to install Helm see Installing Helm.
-
Clone the Cargo Tracker repository to your development environment.
git clone https://github.com/Azure-Samples/cargotracker-liberty-aks.git cd cargotracker-liberty-aks
-
Run the following command to authenticate with Azure using the Azure CLI.
az login
-
Run the following command to authenticate with Azure using the Azure Developer CLI (azd).
azd auth login
-
Run the following command to create a new environment using the Azure Developer CLI (azd). It's a good idea to use a disambiguation prefix for your environment name, such as your initials and todays date.
azd env new gzh0919-cargotracker-liberty-aks
-
Run the following command to provision the required Azure resources. Input the required parameters when prompted.
- Be sure to select the correct Azure subscription when prompted.
- We observe that
westus
region has a higher likelihood of success thaneastus
.
azd provision
For
administratorLoginPassword
enterSecret123456
.When the provisioning completes, you'll see a message similar to the following:
SUCCESS: Your application was provisioned in Azure in 27 minutes 59 seconds.
-
Ensure Docker is running locally. Run the following command to deploy the Cargo Tracker application to Azure Kubernetes Service (AKS) using the Azure Developer CLI (azd).
azd deploy
-
Wait for the deployment to complete. Once the deployment is complete, you can access the Cargo Tracker application using the URL provided in the output.
You can now exercise the Cargo Tracker functionality as shown in Appendix 1.
The steps in this section show you how to clean up and deallocte the resources deployed in the previous section.
azd down
-
On the main page, inspect the date timestamp, it should reflect today's date. For example, 3.2 2024-08-06 17:48:08.
-
On the main page, select Administration.
-
In the left menu, open Track in a new window.
-
Enter ABC123 and select Track!
-
Observe what the next expected activity is.
-
-
On the main page, select Administration Interface, then, in the left navigation column select Live in a new window. This opens a map view.
- Mouse over the pins and find the one for ABC123. Take note of the information in the hover window.
-
On the main page, select Event Logging Interface. This opens up in a new, small, window.
-
Drop down the menu and select ABC123. Select Next.
-
Select the Location using the information in the next expected activity. Select Next.
-
Select the Event Type using the information in the next expected activity. Select Next.
-
Select the Voyage using the information in the next expected activity. Select Next.
-
Set the Completion Date a few days in the future. Select Next.
-
Review the information and verify it matches the next expected activity. If not, go back and fix it. If so, select Submit.
-
Back on the Public Tracking Interface select Tracking then enter ABC123 and select Track. Observe that different. next expected activity is listed.
-
If desired, go back to Mobile Event Logger and continue performing the next activity.
See Eclipse Cargo Tracker - Applied Domain-Driven Design Blueprints for Jakarta EE
The steps in this section guide you to deploy supporting resources with the GitHub workflow, yet run the cargotracker app locally.
-
Follow the steps in Unit 2 Automate deployments using GitHub Actions, but when you run the workflow, set the value for Set this value to true to cause the workflow to only deploy required supporting resources to true.
-
Follow the steps in Unit-1 - Deploy and monitor Cargo Tracker up to and including Prepare your variables for deployments.
Use the values from the workflow to fill out the values in your
setup-env-variables.sh
.-
DB_RESOURCE_NAME
must be the name of the database resource, such asliberty-dbs-1148487969748
. Find this value by entering the resource group in which the workflow deployed the database and selecting the database resource. -
DB_NAME
must belibertydb
. -
If using the AI shortest path feature, set the
AZURE_OPENAI
variables as described in Unit 1. -
Leave the remainder of the variables unchanged. They are not used in the "Run locally with remote resources without Docker" scenario.
-
-
Remove the Application Insights agent jar.
-
Edit the file
${DIR}/cargotracker/src/main/liberty/config/jvm.options
.Remove the entire line containing the string
applicationinsights-agent.jar
.Application Insights is not used in the "Run locally with remote resources without Docker" scenario.
Note that addtional JVM options can be inserted into this file, such as local debugger options
-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:5005
.
-
-
Wait until the workflow successfully completes the deploy-db job before continuing.
-
Enable network access from your local workstation to the database.
-
Sign in to the Azure portal using the same subscription to which you deployed the database.
-
Find the resource group in which the database has been deployed.
-
Select the database resource. It will be named something like
liberty-dbs-1148487969748
. -
In the left navigation panel, under Settings select Networking.
-
Find the text Add current client IP address. Select the text and select Save. Wait for the save operation to complete.
-
-
Build the cargotracker.war. The POM substitutes the environment variables for the database connection.
mvn -PopenLibertyOnAks clean install
-
Run the cargotracker.war. Make sure to run this command in the same shell where the environment variables are defined.
mvn -PopenLibertyOnAks liberty:run
-
Your cargotracker will now be running at
http://localhost:9080/cargo-tracker/
.- To exercise the UI, follow the steps in Appendix 1 - Exercise Cargo Tracker Functionality. If you get an unexpected error, wait a few minutes and try again.
- To exercise the REST endpoint, including the AI shortest path feature, follow the steps in Use Cargo Tracker and make a few HTTP calls