Private preview guidance for new Java features in azd

This guide describes new Java features in azd, and a corresponding Visual Studio Code extension built on these features, designed to empower Java developers to more easily onboard to Azure. These new features simplify the complex and varied tasks developers must use to go onboard to Azure. Such tasks include: using the Azure portal, Azure CLI or PowerShell, and even infrastructure as code technologies such as Bicep or Terraform. Each of these tasks has its own learning curve and skillset. We use the term “onboarding Java apps onto Azure” to mean provisioning all the app and the necessary backing services like Database, Message service. We intend to further optimize the onboarding experience for you.

Given the current release is in private preview, we start with the most common deployment scenarios. We focus on demonstrating the general concept to you and would like to gather feedback from you for the next release – public preview.

Below is the supported scope for this private preview:

• Spring + Maven project only
• Supported Spring Boot versions: 2.x and 3.x
• Supported backing services:

A more detailed list of supported target scenarios is available by viewing Target scenarios.

• Supported compute service

  • Azure Container Apps

• An Azure subscription. The private preview provides an Azure pass. To create a subscription using the Azure pass, see Creating a Microsoft Azure pass subscription.

  Note

  You must enable "local auth" in the subscription to allow the proper functioning of the private preview. To learn how, see Fix access problem caused by policy.

• Prepare a local machine with either Windows or Unix-like operating system installed - for example, Ubuntu, macOS, or Windows Subsystem for Linux.
• Ensure a Java SE implementation version 17 - for example, Microsoft build of OpenJDK is installed.
• Ensure that Git is installed.
• If you intend to use the Visual Studio Code extension, ensure Visual Studio Code is installed.
• If you have the Azure CLI installed, run az logout and remove the .azure directory in your home directory.
• If you have Azure PowerShell installed, run Disconnect-AzAccount and remove the %USERPROFILE%\.Azure directory.
• If you already have the Azure Developer CLI (azd) installed:
  • Run azd auth logout.
  • Completely uninstall any existing versions of azd, if any, following the steps in How do I uninstall Azure Developer CLI?
• If you already have Visual Studio Code installed, ensure the Azure Developer CLI extension is uninstalled.
  • In Visual Studio Code, select Extensions in the sidebar or press Ctrl+Shift+X (on Windows or GNU/Linux) or Cmd+Shift+X (on macOS).
  • Enter Azure Developer CLI. If you see it, select the cog wheel icon.
  • Select Uninstall.
  • Shut down Visual Studio Code.
  • Start Visual Studio Code.
  • Shut down Visual Studio Code again.
• Install Docker desktop. If operating in a headles environment on GNU/Linux, you can install Docker Engine. See Install Docker Engine.
• If you are using Windows to execute these steps:
  • Install WSL for building Linux docker image on windows. See How to install Linux on Windows with WSL.
  • PowerShell 7. See Installing PowerShell on Windows.
• If using the provided sample app, Install Node.js. See Download Node.js.

The purpose of this private preview is for Microsoft to gather feedback on the design and implementation of new features in azd aimed at easing the journey Java developers take to Azure. The steps in this section show you how to install the private preview versions of the software with these features.

The steps in this section contain links for installing the private preview binary of azd on the supported developer systems. You can choose to run installation scripts, or simply download statically linked binaries.

The steps in this section are use installation scripts to install the software.

• GNU/Linux or macOS

  • Bash
  • PowerShell

  Bash

  curl -fsSL https://azuresdkreleasepreview.blob.core.windows.net/azd/standalone/pr/4586/uninstall-azd.sh | bash;
  curl -fsSL https://azuresdkreleasepreview.blob.core.windows.net/azd/standalone/pr/4586/install-azd.sh | bash -s -- --base-url https://azuresdkreleasepreview.blob.core.windows.net/azd/standalone/pr/4586 --version '' --verbose --skip-verify
  

• Windows with PowerShell

  • Bash
  • PowerShell

  Not applicable.

• Windows with MSI

  • Bash
  • PowerShell

  Not applicable

For this installation method, unzip the zip file and place the binary in a directory on your executable path. Rename the binary to azd.

• GNU/Linux
  • x86_64 - https://azuresdkreleasepreview.blob.core.windows.net/azd/standalone/pr/4586/azd-linux-amd64.tar.gz
  • ARM64 - https://azuresdkreleasepreview.blob.core.windows.net/azd/standalone/pr/4586/azd-linux-arm64.tar.gz
• MacOS
  • x86_64 - https://azuresdkreleasepreview.blob.core.windows.net/azd/standalone/pr/4586/azd-darwin-amd64.zip
  • ARM64 - https://azuresdkreleasepreview.blob.core.windows.net/azd/standalone/pr/4586/azd-darwin-arm64.zip
• Windows
  • x86_64 - https://azuresdkreleasepreview.blob.core.windows.net/azd/standalone/pr/4586/azd-windows-amd64.zip
  • ARM64 - https://azuresdkreleasepreview.blob.core.windows.net/azd/standalone/pr/4586/azd-windows-arm64-alpha.zip
  • MSI
    • x86_64 - https://azuresdkreleasepreview.blob.core.windows.net/azd/standalone/pr/4586/azd-windows-amd64.msi

1. Ensure the azd you have installed is the correct version by running the following command and looking for the text azd version 1.12.0-beta.1-pr.4428931 (commit 19fa8e14d814399d66c86d393eb497081dbab9f9).

   • Bash
   • PowerShell

   Bash

   azd version
   

   If the azd you have installed is a different version, review the installation steps you performed and resolve the problem before proceeding.

2. This private preview depends on an "alpha" feature in azd called "composability". For details on this feature, please see Azure Developer CLI (azd) – November 2024. Because this feature is in alpha state, you must explicitly enable it with the following command.

   • Bash
   • PowerShell

   Bash

   azd config set alpha.compose on
   

   Validate that the preceding action successfully completed by running the following command and looking for the text Status: On in the section for compose:.

   • Bash
   • PowerShell

   Bash

   azd config list-alpha
   

Install the private preview version of the azd Visual Studio Code extension. If you intend to use AZD commands directly you may skip the steps in this section.

1. Download the extension at https://azuresdkreleasepreview.blob.core.windows.net/azd/vscode/pr/4586/azure-dev-0.9.0-alpha.1.vsix

   • Bash
   • PowerShell

   Bash

   curl -o azure-dev-0.9.0-alpha.1.vsix https://azuresdkreleasepreview.blob.core.windows.net/azd/vscode/pr/4586/azure-dev-0.9.0-alpha.1.vsix
   

2. Open Visual Studio Code.

3. Press Ctrl+Shift+P (Windows or GNU/Linux) or Cmd+Shift+P (macOS) to open the Command Palette.

4. Type Install from VSIX in the search bar.

5. Select the Extensions: Install from VSIX... option from the dropdown.

   A file picker dialog will open. Navigate to the location of your downloaded .vsix file, select it, and select Open. The extension will be installed, and you may be prompted to reload VS Code.

   If prompted to sign in to Azure, do so using the provided Azure pass subscription.

6. Select Extensions from the left navigation bar, or press Ctrl+Shift+X (Windows or GNU/Linux) or Cmd+Shift+X (macOS).

7. Type Azure Developer CLI. Hover the mouse over the Azure Developer CLI. You must see v0.9.0-alpha1.

8. Shut down Visual Studio Code.

9. Start Visual Studio Code.

10. Shut down Visual Studio Code again.

11. If not already installed, install the Yaml editor VS code extension from Red Hat. See YAML - Visual Studio Marketplace.

You can try out using either our provided sample project or your own Spring project. Please be aware that:

• If using the provided sample project, please git clone it locally from GitHub. For instructions on cloning with SSH, see Connecting to GitHub with SSH.

• If using your own Spring project, please make sure conforms to the supported scope defined previously. It’s recommended you have the necessary Dockerfile instances in your project. It’s ok if you don’t, but the presence of a Dockerfile indicates you have already done the work to containerize your application. We will containerize your app if there is no Dockerfile, but it’s possible your app may have features that our containerization feature does not support.

The sample Spring project is a to-do list management app, composed of three microservices: web, api service and email service. When a user adds or updates a to-do item on the web page, the to-do item will be stored into MongoDB by Api service. For those due to-do items, the Api service will issue messages into Azure Service Bus. These messages will be consumed by the email service to send an email to you. This diagram describes the overall architecture and interaction relationship among the three services and their backing services: MongoDB and Azure Service Bus.

Now that we have explained the sample app, let’s deploy it to Azure. In the following steps, "the repository" refers to the sample Spring project you have cloned from GitHub.

1. Sign in to Azure using the provided Azure pass. Follow the steps in azd auth login. If you are running in a headless environment, consider using azd auth login --use-device-code.

2. Change to the top level directory of the repository and invoke VS code with code . The dot is important. If you have the Visual Studio Code Java Extension pack installed, wait for it to show Java: Ready before proceeding.

   

   The Visual Studio Code Java Extension pack is not required but its presence does not interfere with these instructions.

3. Configure your email address in ./email-service/src/main/resources/application.properties.

   Bash

   email.receiver.address=<your-email-address>
   

4. Right click on the root pom.xml and choose Azure Developer CLI (azd) -> Generate Azure deployment script (init). If you prefer to just use the azd CLI, you can run this command in the top level directory of the cloned repository.

   • Bash
   • PowerShell

   Bash

   azd init --from-code
   

5. When prompted, fill in necessary inputs in command window of VS code. As the command runs, the prompts may include the following.

   

   1. Use code in the current directory.

      

   2. Confirm and continue initializing my app.

      

   3. Select User assigned managed identity.

      

      If the README.md file is opened in the editor, it is safe to close it.

6. Now you will find a generated YAML file azure.yaml under the root path. Please open and examine its content and check if it includes the required backing services, apps in the project, the app hosting service by default being Azure Container Apps and service bindings declaring correctly for your app and corresponding backing services so that your apps can connect to the backing service correctly.

   

7. In the file navigator, right-click on the azure.yaml and select Azure Developer CLI (azd) -> Package, provision and deploy (up) to trigger the overall provisioning and deployment. If you prefer to just use the azd CLI, you can run this command in the top level directory of the cloned repository.

   • Bash
   • PowerShell

   Bash

   azd up
   

   1. You must provide an env name. This name must be unique within your subscription. We suggest the following pattern to ensure uniqueness: your initials, a sequence number and today’s date in mmyy format. For example, ejb011205. This value is included in an Azure resource group name for the deployed resources.

      1. Select the subscription to use: please use the newly created subscription from the Azure PASS.

      2. Select the Azure location (also known as Azure region).

         Note

         CosmosDB is known to have sufficient quota in East US 2. If you select a region with insufficient CosmosDB quota, the deployment will fail.

   You can take a look at the output logs to monitor the progress.

   

   

   A successful deployment will conclude with text similar to the following: SUCCESS: Your up workflow to provision and deploy to Azure completed in 6 minutes 35 seconds.

   If you don’t see this text, troubleshoot and resolve the problem before continuing.

The steps in this section show you how to exercise the deployed app.

1. Once done, visit the Azure Portal https://aka.ms/publicportal. Sign in with the Azure Pass credentials, if necessary.

   1. Open the hamburger menu and select Resource groups. Find your resource group with the env name you configured.

   2. Because this is a fresh Azure pass, you’ll only have one resource group. Please examine if you get the expected result with corresponding backing services running and apps deployed and running.

      1. Select the Type column header to sort the table of resources in ascending order by resource type.
      2. Toggle the grouping box to show Group by type.
      3. For the sample app, you should see something similar to the following illustration:

      

2. In the Container App section, select web. Locate the Application Url value and open it in a new browser tab. Add some to-do items.

   

3. Set a due date for this item.

   

   Set the date exactly one day in the future. This prompts the message microservice to send an email to the provided address.

The steps in this section show you how to validate the performance of the app.

1. Return to the Portal and visit the Overview of your Resource group.

2. Select the resource of type Azure Cosmos DB for MongoDB account (RU).

   

The steps in this section show you how to manually edit azure.yaml to use another authentication type for the app binding to Azure Service Bus.

1. Open azure.yaml again. Locate the section within resources called servicebus.

2. Change the auth type for Azure Service Bus to be connectionString.

   

   Save the file.

3. Right-click on the azure.yaml and choose Package, provision and deploy (up) again. If you prefer to just use the azd CLI, you can run this command in the top level directory of the cloned repository.

   • Bash
   • PowerShell

   Bash

   azd up
   

   Observe the logs to see the progress.

   

4. Check on Azure Portal:

   1. For Azure Cosmos DB and Azure Service Bus, nothing changed.
   2. Now your apps binding to Azure Service Bus via the connection string.

5. Add some more todo entries and verify it works as expected.

The steps in this section show how to clean up your workarea so you can do the entire exercise again.

1. There are several ways to clean up the Azure resources.

   1. Within the IDE: Right click on azure.yaml and select Delete Deployment and Resources (down). This approach will clear out the resources very thoroughly and take a long time.

   2. Within the Portal: locate the resource group and select Delete.

2. Remove the .azure directory within the cloned repository.

3. git reset -–hard

4. rm azure.yaml

The steps in this section show how to use your own cloud-ready Spring project with the new azd features. It is important that your own cloud-ready Spring project conforms to the scope listed in the User Experience section.

1. Sign in to Azure using the provided Azure pass. Follow the steps in azd auth login. If you are running in a headless environment, consider using azd auth login --use-device-code.

2. Change to the top level directory of the repository and invoke VS code with code . The dot is important. If you have the Visual Studio Code Java Extension pack installed, wait for it to show Java: Ready before proceeding.

   

   The Visual Studio Code Java Extension pack is not required but its presence does not interfere with these instructions.

3. Right-click on the root pom.xml and choose Azure Developer CLI (azd) -> Generate Azure deployment script (init). If you prefer to just use the azd CLI, you can run this command in the top level directory of the cloned repository.

   • Bash
   • PowerShell

   Bash

   azd init --from-code
   

4. When prompted, fill in necessary inputs in command window of VS code. As the command runs, the prompts may include the following.

   

   1. Use code in the current directory.

      

   2. Confirm and continue initializing my app.

      

5. Now you will find a generated YAML file azure.yaml under the root path. Please open and examine its content and check if it includes the required backing services, apps in the project, the app hosting service by default being Azure Container Apps and service bindings declaring correctly for your app and corresponding backing services so that your apps can connect to the backing service correctly.

   

6. If anything is missing manually edit the azure.yaml by following the steps in azure.yaml resource configuration.

7. In the file navigator, right click on the azure.yaml and select Azure Developer CLI (azd) -> Package, provision and deploy (up) to trigger the overall provisioning and deployment. If you prefer to just use the azd CLI, you can run this command in the top level directory of the cloned repository.

   • Bash
   • PowerShell

   Bash

   azd up
   

   1. You must provide an env name. This name must be unique within your subscription. We suggest the following pattern to ensure uniqueness: your initials, a sequence number and today’s date in mmyy format. For example, ejb011205. This value is included in an Azure resource group name for the deployed resources.

      1. Select the subscription to use: please use the newly created subscription from the Azure PASS.

      2. Select the Azure location (also known as Azure region).

         Note

         CosmosDB is known to have sufficient quota in East US 2. If you select a region with insufficient CosmosDB quota, the deployment will fail.

   You can take a look at the output logs to monitor the progress.

   

   

   A successful deployment will conclude with text similar to the following: SUCCESS: Your up workflow to provision and deploy to Azure completed in 6 minutes 35 seconds.

   If you don’t see this text, troubleshoot and resolve the problem before continuing.

The steps in this section show you how to exercise the deployed app.

1. Once done, visit the Azure Portal https://aka.ms/publicportal. Sign in with the Azure Pass credentials, if necessary.

   1. Open the hamburger menu and select Resource groups. Find your resource group with the env name you configured.
   2. Because this is a fresh Azure pass, you’ll only have one resource group. Please examine if you get the expected result with corresponding backing services running and apps deployed and running.

The steps in this section show how to clean up your workarea so you can do the entire exercise again.

1. There are several ways to clean up the Azure resources.

   1. Within the IDE: Right click on azure.yaml and select Delete Deployment and Resources (down). This approach will clear out the resources very thoroughly and take a long time.

   2. Within the Portal: locate the resource group and select Delete.

2. Remove the .azure directory within the cloned repository.

3. git reset -–hard

4. rm azure.yaml

• Several other Spring Boot projects have been validated for use with the preview features in this repository.

  https://github.com/azure-javaee/azure-spring-boot-samples

  Please feel free to try out the features with these projects using steps similar to the preceding steps.