Skip to content

Extend Spring Boot app + Service Bus sample #55

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
paolosalvatori merged 2 commits into from
Mar 5, 2026
Merged

Extend Spring Boot app + Service Bus sample #55

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
35c08be
Extend Spring Boot app + Service Bus sample
paolosalvatori Mar 5, 2026
daf6eff
Merge branch 'main' into updates
paolosalvatori Mar 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 71 additions & 22 deletions samples/servicebus/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,31 +1,80 @@
# Azure ServiceBus (Java SDK)
# Azure Service Bus with Spring Boot

This sample creates a minimal Spring Boot application that sends and receive messages via Azure ServiceBus.
This sample demonstrates a Java Spring Boot application that sends and receives messages via [Azure Service Bus](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-messaging-overview). The application uses the [Spring Cloud Azure Service Bus Stream Binder](https://learn.microsoft.com/en-us/azure/developer/java/spring-framework/configure-spring-cloud-stream-binder-java-app-with-service-bus) to connect to a Service Bus queue, send a `Hello, World!` message, and receive it back, and then exits.

## Overview
> [!NOTE]
> At this time, the Azure Web Apps and Azure Function Apps emulators in LocalStack for Azure do not support Java applications. The Spring Boot sample application must be executed directly on the host machine and cannot be deployed to the emulator.

- **`app`**: A folder that contains the Java application
- **`scripts/deploy.sh`**: One script that provisions the required resources for this sample and runs the application

## Quick Start
## Architecture

The solution is composed of the following Azure resources:

1. [Azure Resource Group](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-cli): A logical container scoping all resources in this sample.
2. [Azure Service Bus Namespace](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-messaging-overview): The messaging namespace that hosts the queue used by the application.
3. [Azure Service Bus Queue](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-queues-topics-subscriptions#queues): The `myqueue` queue used to send and receive messages.

> **Note**
> The Java application currently runs on the host machine. In a future iteration, it will be deployed to an emulator-hosted web app.

## Prerequisites

- [Azure Subscription](https://azure.microsoft.com/free/)
- [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli)
- [Azlocal CLI](https://azure.localstack.cloud/user-guides/sdks/az/): LocalStack Azure CLI wrapper
- [Java 21+](https://learn.microsoft.com/en-us/java/openjdk/download)
- [Maven 3.8+](https://maven.apache.org/download.cgi)
- [Terraform](https://developer.hashicorp.com/terraform/downloads), if you plan to deploy the sample via Terraform.
- [Bicep extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-bicep), if you plan to deploy the sample via Bicep.

## Deployment

Set up the Azure emulator using the LocalStack for Azure Docker image. Before starting, ensure you have a valid `LOCALSTACK_AUTH_TOKEN` to access the Azure emulator. Refer to the [Auth Token guide](https://docs.localstack.cloud/getting-started/auth-token/) to obtain your Auth Token and set it in the `LOCALSTACK_AUTH_TOKEN` environment variable. The Azure Docker image is available on the [LocalStack Docker Hub](https://hub.docker.com/r/localstack/localstack-azure-alpha). To pull the image, execute:

To deploy the scenario against a LocalStack Emulator:
```bash
bash ./scripts/deploy.sh
docker pull localstack/localstack-azure-alpha
```

The script will:
1. Creates a ResourceGroup
2. Creates a Servicebus Namespace
3. Creates a Servicebus Queue
4. Starts the Java app

The app then:
1. Connects to the configured ServiceBus
2. Sends a message to a queue
3. Receives the message, and shuts down the application

After the application has shutdown, the script will then:
5. Deletes the resource group with all of it's resources
Start the LocalStack Azure emulator by running:

```bash
export LOCALSTACK_AUTH_TOKEN=<your_auth_token>
IMAGE_NAME=localstack/localstack-azure-alpha localstack start
```

Deploy the application to LocalStack for Azure using one of these methods:

- [Azure CLI Deployment](./java/scripts/deploy.sh)
- [Bicep Deployment](./java/bicep/deploy.sh)
- [Terraform Deployment](./java/terraform/deploy.sh)

All deployment methods have been fully tested against Azure and the LocalStack for Azure local emulator.

> **Note**
> When you deploy the application to LocalStack for Azure for the first time, the initialization process involves downloading and building Docker images. This is a one-time operation—subsequent deployments will be significantly faster. Depending on your internet connection and system resources, this initial setup may take several minutes.

## How It Works

The deploy script performs the following steps:

1. Creates a resource group.
2. Creates a Service Bus namespace.
3. Creates a Service Bus queue (`myqueue`).
4. Retrieves the namespace connection string and exports it as `AZURE_SERVICEBUS_CONNECTION_STRING`.
5. Starts the Spring Boot application via `mvn clean spring-boot:run`.

The application then:

1. Connects to the configured Service Bus namespace using the connection string.
2. Sends a `Hello, World!` message to the `myqueue` queue.
3. Receives the message via a `@ServiceBusListener` consumer.
4. Shuts down after receiving the message.

## References

- [Azure Service Bus Documentation](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-messaging-overview)
- [Spring Cloud Azure Service Bus](https://learn.microsoft.com/en-us/azure/developer/java/spring-framework/configure-spring-cloud-stream-binder-java-app-with-service-bus)
- [Azure Service Bus Queues](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-queues-topics-subscriptions)
- [Spring Boot Starter for Azure Service Bus](https://learn.microsoft.com/en-us/azure/developer/java/spring-framework/spring-cloud-azure)
- [LocalStack for Azure](https://azure.localstack.cloud/)


176 changes: 176 additions & 0 deletions samples/servicebus/java/bicep/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,176 @@
# Bicep Deployment

This directory contains a Bicep template and a deployment script for provisioning Azure services in LocalStack for Azure. For further details about the sample application, refer to the [Azure Service Bus with Spring Boot](../../README.md).

## Prerequisites

Before deploying this solution, ensure you have the following tools installed:

- [LocalStack for Azure](https://azure.localstack.cloud/): Local Azure cloud emulator for development and testing
- [Visual Studio Code](https://code.visualstudio.com/): Code editor installed on one of the [supported platforms](https://code.visualstudio.com/docs/supporting/requirements#_platforms)
- [Bicep extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-bicep): VS Code extension for Bicep language support and IntelliSense
- [Docker](https://docs.docker.com/get-docker/): Container runtime required for LocalStack
- [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli): Azure command-line interface
- [Azlocal CLI](https://azure.localstack.cloud/user-guides/sdks/az/): LocalStack Azure CLI wrapper
- [Java 21+](https://learn.microsoft.com/en-us/java/openjdk/download): Java runtime for compiling and running the sample application
- [Maven 3.8+](https://maven.apache.org/download.cgi): Build tool for managing Java project dependencies and compilation
- [jq](https://jqlang.org/): JSON processor for scripting and parsing command outputs

### Installing azlocal CLI

The [deploy.sh](deploy.sh) Bash script uses the `azlocal` CLI instead of the standard Azure CLI to work with LocalStack. Install it using:

```bash
pip install azlocal
```

For more information, see [Get started with the az tool on LocalStack](https://azure.localstack.cloud/user-guides/sdks/az/).

## Architecture Overview

The [deploy.sh](deploy.sh) script creates the [Azure Resource Group](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-cli), while the Bicep template creates the following Azure resources:

1. [Azure Resource Group](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-cli): A logical container scoping all resources in this sample.
2. [Azure Service Bus Namespace](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-messaging-overview): The messaging namespace that hosts the queue used by the application.
3. [Azure Service Bus Queue](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-queues-topics-subscriptions#queues): The `myqueue` queue used to send and receive messages.

The Spring Boot sample application connects to the Service Bus namespace, sends a test message to the sample queue, receives it back, and exits. For more information on the sample application, see [Azure Service Bus with Spring Boot](../../README.md).

## Configuration

Before deploying the `main.bicep` template, update the [main.bicepparam](main.bicepparam) file with your specific values:

```bicep
using 'main.bicep'

param queueName = 'myqueue'
param zoneRedundant = false
param tags = {
environment: 'test'
iac: 'bicep'
}
```

## Provisioning Scripts

You can use the [deploy.sh](deploy.sh) script to automate the deployment of all Azure resources and the sample application in a single step, streamlining setup and reducing manual configuration. The script executes the following steps:

- Detects environment (LocalStack vs Azure Cloud) and uses the appropriate CLI.
- Creates the resource group if it doesn't exist.
- Optionally validates the Bicep template.
- Optionally runs a what-if deployment for preview.
- Deploys the `main.bicep` template with parameters from [main.bicepparam](main.bicepparam).
- Extracts the Service Bus namespace name from deployment outputs.
- Retrieves the namespace connection string and exports it as `AZURE_SERVICEBUS_CONNECTION_STRING`.
- Compiles the Spring Boot project and runs the app on the host machine.

## Deployment

You can set up the Azure emulator by utilizing LocalStack for Azure Docker image. Before starting, ensure you have a valid `LOCALSTACK_AUTH_TOKEN` to access the Azure emulator. Refer to the [Auth Token guide](https://docs.localstack.cloud/getting-started/auth-token/) to obtain your Auth Token and specify it in the `LOCALSTACK_AUTH_TOKEN` environment variable. The Azure Docker image is available on the [LocalStack Docker Hub](https://hub.docker.com/r/localstack/localstack-azure-alpha). To pull the Azure Docker image, execute the following command:

```bash
docker pull localstack/localstack-azure-alpha
```

Start the LocalStack Azure emulator using the localstack CLI, execute the following command:

```bash
export LOCALSTACK_AUTH_TOKEN=<your_auth_token>
IMAGE_NAME=localstack/localstack-azure-alpha localstack start
```

Navigate to the `bicep` folder:

```bash
cd samples/servicebus/java/bicep
```

Make the script executable:

```bash
chmod +x deploy.sh
```

Run the deployment script:

```bash
./deploy.sh
```

## Validation

Once the deployment completes, run the [validate.sh](../scripts/validate.sh) script to confirm that all resources were provisioned and configured as expected:

```bash
#!/bin/bash

# Variables
PREFIX='local'
SUFFIX='test'
RESOURCE_GROUP_NAME="${PREFIX}-rg"
SERVICEBUS_NAMESPACE_NAME="${PREFIX}-sb-ns-${SUFFIX}"
SERVICEBUS_QUEUE_NAME="myqueue"
ENVIRONMENT=$(az account show --query environmentName --output tsv)

# Choose the appropriate CLI based on the environment
if [[ $ENVIRONMENT == "LocalStack" ]]; then
echo "Using azlocal for LocalStack emulator environment."
AZ="azlocal"
else
echo "Using standard az for AzureCloud environment."
AZ="az"
fi

# Check resource group
echo -e "[$RESOURCE_GROUP_NAME] resource group:\n"
$AZ group show \
--name "$RESOURCE_GROUP_NAME" \
--output table \
--only-show-errors

# Check Service Bus namespace
echo -e "\n[$SERVICEBUS_NAMESPACE_NAME] Service Bus namespace:\n"
$AZ servicebus namespace show \
--resource-group "$RESOURCE_GROUP_NAME" \
--name "$SERVICEBUS_NAMESPACE_NAME" \
--query "{name:name, location:location, serviceBusEndpoint:serviceBusEndpoint, status:provisioningState}" \
--output table \
--only-show-errors

# Check Service Bus queue
echo -e "\n[$SERVICEBUS_QUEUE_NAME] Service Bus queue:\n"
$AZ servicebus queue show \
--resource-group "$RESOURCE_GROUP_NAME" \
--namespace-name "$SERVICEBUS_NAMESPACE_NAME" \
--name "$SERVICEBUS_QUEUE_NAME" \
--query "{name:name, messageCount:messageCount, sizeInBytes:sizeInBytes}" \
--output table \
--only-show-errors
```

## Cleanup

To destroy all created resources:

```bash
#!/bin/bash

# Variables
PREFIX='local'
SUFFIX='test'
RESOURCE_GROUP_NAME="${PREFIX}-rg"

# Delete resource group and all contained resources
az group delete --name $RESOURCE_GROUP_NAME --yes --no-wait

# Verify deletion
az group list --output table
```

This will remove all Azure resources created by the Bicep deployment script.

## Related Documentation

- [Azure Bicep Documentation](https://docs.microsoft.com/en-us/azure/azure-resource-manager/bicep/)
- [Bicep Language Reference](https://docs.microsoft.com/en-us/azure/azure-resource-manager/bicep/bicep-functions)
- [LocalStack for Azure Documentation](https://azure.localstack.cloud/)
Loading