Quickstart: Deploy your first application to Azure Spring Apps

Note

Azure Spring Apps is the new name for the Azure Spring Cloud service. Although the service has a new name, you'll see the old name in some places for a while as we work to update assets such as screenshots, videos, and diagrams.

This article applies to: ✔️ Basic/Standard tier ✔️ Enterprise tier

This quickstart explains how to deploy a small application to run on Azure Spring Apps.

Note

Steeltoe support for Azure Spring Apps is currently offered as a public preview. Public preview offerings allow customers to experiment with new features prior to their official release. Public preview features and services aren't meant for production use. For more information about support during previews, see the FAQ or file a Support request.

By following this quickstart, you'll learn how to:

• Generate a basic Steeltoe .NET Core project
• Provision an Azure Spring Apps service instance
• Build and deploy the app with a public endpoint
• Stream logs in real time

The application code used in this quickstart is a simple app built with a .NET Core Web API project template. When you've completed this example, the application will be accessible online and can be managed via the Azure portal and the Azure CLI.

Prerequisites

• An Azure account with an active subscription. Create an account for free.
• .NET Core 3.1 SDK. The Azure Spring Apps service supports .NET Core 3.1 and later versions.
• Azure CLI version 2.0.67 or later.
• Git.

Install Azure CLI extension

Verify that your Azure CLI version is 2.0.67 or later:

az --version

Install the Azure Spring Apps extension for the Azure CLI using the following command:

az extension add --name spring

Sign in to Azure

1. Sign in to the Azure CLI:

   az login
   

2. If you have more than one subscription, choose the one you want to use for this quickstart.

   az account list -o table
   

   az account set --subscription <Name or ID of a subscription from the last step>
   

Generate a Steeltoe .NET Core project

In Visual Studio, create an ASP.NET Core Web application named as "hello-world" with API project template. Please notice there will be an auto-generated WeatherForecastController that will be our test endpoint later on.

1. Create a folder for the project source code and generate the project.

   mkdir source-code
   

   cd source-code
   

   dotnet new webapi -n hello-world --framework netcoreapp3.1
   

2. Navigate into the project directory.

   cd hello-world
   

3. Edit the appSettings.json file to add the following settings:

   "spring": {
     "application": {
       "name": "hello-world"
     }
   },
   "eureka": {
     "client": {
       "shouldFetchRegistry": true,
       "shouldRegisterWithEureka": true
     }
   }
   

4. Also in appsettings.json, change the log level for the Microsoft category from Warning to Information. This change ensures that logs will be produced when you view streaming logs in a later step.

   The appsettings.json file now looks similar to the following example:

   {
     "Logging": {
       "LogLevel": {
         "Default": "Information",
         "Microsoft": "Information",
         "Microsoft.Hosting.Lifetime": "Information"
       }
     },
     "AllowedHosts": "*",
     "spring": {
       "application": {
         "name": "hello-world"
       }
     },
     "eureka": {
       "client": {
         "shouldFetchRegistry": true,
         "shouldRegisterWithEureka": true
       }
     }
   }
   

5. Add dependencies and a Zip task to the .csproj file:

   <ItemGroup>
     <PackageReference Include="Steeltoe.Discovery.ClientCore" Version="3.1.0" />
     <PackageReference Include="Microsoft.Azure.SpringCloud.Client" Version="2.0.0-preview.1" />
   </ItemGroup>
   <Target Name="Publish-Zip" AfterTargets="Publish">
     <ZipDirectory SourceDirectory="$(PublishDir)" DestinationFile="$(MSBuildProjectDirectory)/deploy.zip" Overwrite="true" />
   </Target>
   

   The packages are for Steeltoe Service Discovery and the Azure Spring Apps client library. The Zip task is for deployment to Azure. When you run the dotnet publish command, it generates the binaries in the publish folder, and this task zips the publish folder into a .zip file that you upload to Azure.

6. In the Program.cs file, add a using directive and code that uses the Azure Spring Apps client library:

   using Microsoft.Azure.SpringCloud.Client;
   

   public static IHostBuilder CreateHostBuilder(string[] args) =>
               Host.CreateDefaultBuilder(args)
                   .UseAzureSpringCloudService()
                   .ConfigureWebHostDefaults(webBuilder =>
                   {
                       webBuilder.UseStartup<Startup>();
                   });
   

7. In the Startup.cs file, add a using directive and code that uses the Steeltoe Service Discovery at the end of the ConfigureServices method:

   using Steeltoe.Discovery.Client;
   

   public void ConfigureServices(IServiceCollection services)
   {
       // Template code not shown.
   
       services.AddDiscoveryClient(Configuration);
   }
   

8. Build the project to make sure there are no compile errors.

   dotnet build
   

Provision a service instance

The following procedure creates an instance of Azure Spring Apps using the Azure portal.

1. Open the Azure portal.

2. From the top search box, search for Azure Spring Apps.

3. Select Azure Spring Apps from the results.

   

4. On the Azure Spring Apps page, select Create.

   

5. Fill out the form on the Azure Spring Apps Create page. Consider the following guidelines:

   • Subscription: Select the subscription you want to be billed for this resource.
   • Resource group: Create a new resource group. The name you enter here will be used in later steps as <resource group name>.
   • Service Details/Name: Specify the <service instance name>. The name must be between 4 and 32 characters long and can contain only lowercase letters, numbers, and hyphens. The first character of the service name must be a letter and the last character must be either a letter or a number.
   • Region: Select the region for your service instance.

   

6. Select Review and create.

7. Select Create.

Build and deploy the app

The following procedure builds and deploys the project that you created earlier.

1. Make sure the command prompt is still in the project folder.

2. Run the following command to build the project, publish the binaries, and store the binaries in a .zip file in the project folder.

   dotnet publish -c release -o ./publish
   

3. Create an app in your Azure Spring Apps instance with a public endpoint assigned. Use the same application name "hello-world" that you specified in appsettings.json.

   az spring app create -n hello-world -s <service instance name> -g <resource group name> --assign-endpoint --runtime-version NetCore_31
   

4. Deploy the .zip file to the app.

   az spring app deploy -n hello-world -s <service instance name> -g <resource group name> --runtime-version NetCore_31 --main-entry hello-world.dll --artifact-path ./deploy.zip
   

   The --main-entry option identifies the .dll file that contains the application's entry point. After the service uploads the .zip file, it extracts all the files and folders and tries to execute the entry point in the .dll file specified by --main-entry.

   It takes a few minutes to finish deploying the application. To confirm that it has deployed, go to the Apps section in the Azure portal.

Test the app

Once deployment has completed, access the app at the following URL:

https://<service instance name>-hello-world.azuremicroservices.io/weatherforecast

The app returns JSON data similar to the following example:

[{"date":"2020-09-08T21:01:50.0198835+00:00","temperatureC":14,"temperatureF":57,"summary":"Bracing"},{"date":"2020-09-09T21:01:50.0200697+00:00","temperatureC":-14,"temperatureF":7,"summary":"Bracing"},{"date":"2020-09-10T21:01:50.0200715+00:00","temperatureC":27,"temperatureF":80,"summary":"Freezing"},{"date":"2020-09-11T21:01:50.0200717+00:00","temperatureC":18,"temperatureF":64,"summary":"Chilly"},{"date":"2020-09-12T21:01:50.0200719+00:00","temperatureC":16,"temperatureF":60,"summary":"Chilly"}]

Stream logs in real time

Use the following command to get real-time logs from the App.

az spring app logs -n hello-world -s <service instance name> -g <resource group name> --lines 100 -f

Logs appear in the output:

[Azure Spring Apps] The following environment variables are loaded:
2020-09-08 20:58:42,432 INFO supervisord started with pid 1
2020-09-08 20:58:43,435 INFO spawned: 'event-gather_00' with pid 9
2020-09-08 20:58:43,436 INFO spawned: 'dotnet-app_00' with pid 10
2020-09-08 20:58:43 [Warning] No managed processes are running. Wait for 30 seconds...
2020-09-08 20:58:44,843 INFO success: event-gather_00 entered RUNNING state, process has stayed up for > than 1 seconds (startsecs)
2020-09-08 20:58:44,843 INFO success: dotnet-app_00 entered RUNNING state, process has stayed up for > than 1 seconds (startsecs)
←[40m←[32minfo←[39m←[22m←[49m: Steeltoe.Discovery.Eureka.DiscoveryClient[0]
      Starting HeartBeat
info: Microsoft.Hosting.Lifetime[0]
      Now listening on: http://[::]:1025
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Production
info: Microsoft.Hosting.Lifetime[0]
      Content root path: /netcorepublish/6e4db42a-b160-4b83-a771-c91adec18c60
2020-09-08 21:00:13 [Information] [10] Start listening...
info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
      Request starting HTTP/1.1 GET http://asa-svc-hello-world.azuremicroservices.io/weatherforecast
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
      Executing endpoint 'hello_world.Controllers.WeatherForecastController.Get (hello-world)'
info: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[3]
      Route matched with {action = "Get", controller = "WeatherForecast"}. Executing controller action with signature System.Collections.Generic.IEnumerable`1[hello_world.WeatherForecast] Get() on controller hello_world.Controllers.WeatherForecastController (hello-world).
info: Microsoft.AspNetCore.Mvc.Infrastructure.ObjectResultExecutor[1]
      Executing ObjectResult, writing value of type 'hello_world.WeatherForecast[]'.
info: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[2]
      Executed action hello_world.Controllers.WeatherForecastController.Get (hello-world) in 1.8902ms
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
      Executed endpoint 'hello_world.Controllers.WeatherForecastController.Get (hello-world)'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
      Request finished in 4.2591ms 200 application/json; charset=utf-8

Tip

Use az spring app logs -h to explore more parameters and log stream functionalities.

For advanced log analytics features, visit Logs tab in the menu on the Azure portal. Logs here have a latency of a few minutes.

This quickstart explains how to deploy a small application to Azure Spring Apps.

The application code used in this tutorial is a simple app built with Spring Initializr. When you've completed this example, the application will be accessible online and can be managed via the Azure portal.

This quickstart explains how to:

• Generate a basic Spring project
• Provision a service instance
• Build and deploy the app with a public endpoint
• Stream logs in real time

Prerequisites

To complete this quickstart:

• Install JDK 8 or JDK 11
• Sign up for an Azure subscription
• (Optional) Install the Azure CLI version 2.0.67 or higher and the Azure Spring Apps extension with the command: az extension add --name spring
• (Optional) Install IntelliJ IDEA
• (Optional) Install the Azure Toolkit for IntelliJ and sign-in
• (Optional) Install Maven. If you use the Azure Cloud Shell, this installation isn't needed.

Generate a Spring project

Start with Spring Initializr to generate a sample project with recommended dependencies for Azure Spring Apps. This link uses the following URL to provide default settings for you.

https://start.spring.io/#!type=maven-project&language=java&platformVersion=2.5.7&packaging=jar&jvmVersion=1.8&groupId=com.example&artifactId=hellospring&name=hellospring&description=Demo%20project%20for%20Spring%20Boot&packageName=com.example.hellospring&dependencies=web,cloud-eureka,actuator,cloud-config-client

The following image shows the recommended Initializr set up for this sample project.

This example uses Java version 8. If you want to use Java version 11, change the option under Project Metadata.

1. Select Generate when all the dependencies are set.

2. Download and unpack the package, then create a web controller for a simple web application by adding the file src/main/java/com/example/hellospring/HelloController.java with the following contents:

   package com.example.hellospring;
   
   import org.springframework.web.bind.annotation.RestController;
   import org.springframework.web.bind.annotation.RequestMapping;
   
   @RestController
   public class HelloController {
   
       @RequestMapping("/")
       public String index() {
           return "Greetings from Azure Spring Apps!";
       }
   
   }
   

Provision an instance of Azure Spring Apps

The following procedure creates an instance of Azure Spring Apps using the Azure portal.

1. In a new tab, open the Azure portal.

2. From the top search box, search for Azure Spring Apps.

3. Select Azure Spring Apps from the results.

   

4. On the Azure Spring Apps page, select Create.

   

5. Fill out the form on the Azure Spring Apps Create page. Consider the following guidelines:

   • Subscription: Select the subscription you want to be billed for this resource.
   • Resource group: Creating new resource groups for new resources is a best practice. You will use this resource group in later steps as <resource group name>.
   • Service Details/Name: Specify the <service instance name>. The name must be between 4 and 32 characters long and can contain only lowercase letters, numbers, and hyphens. The first character of the service name must be a letter and the last character must be either a letter or a number.
   • Location: Select the region for your service instance.

   

6. Select Review and create.

Build and deploy the app

CLI

The following procedure builds and deploys the application using the Azure CLI. Execute the following command at the root of the project.

1. Sign in to Azure and choose your subscription.

   az login
   

   If you have more than one subscription, use the following command to list the subscriptions you have access to, then choose the one you want to use for this quickstart.

   az account list -o table
   

   Use the following command to set the default subscription to use with the Azure CLI commands in this quickstart.

   az account set --subscription <Name or ID of a subscription from the last step>
   

2. Build the project using Maven:

   mvn clean package -DskipTests
   

3. Create the app with a public endpoint assigned. If you selected Java version 11 when generating the Spring project, include the --runtime-version=Java_11 switch.

   az spring app create -n hellospring -s <service instance name> -g <resource group name> --assign-endpoint true
   

4. Deploy the Jar file for the app (target\hellospring-0.0.1-SNAPSHOT.jar on Windows):

   az spring app deploy -n hellospring -s <service instance name> -g <resource group name> --artifact-path <jar file path>/hellospring-0.0.1-SNAPSHOT.jar
   

5. It takes a few minutes to finish deploying the application. To confirm that it has deployed, go to the Apps section in the Azure portal. You should see the status of the application.

IntelliJ

The following procedure uses the IntelliJ plug-in for Azure Spring Apps to deploy the sample app in IntelliJ IDEA.

Import project

1. Open the IntelliJ Welcome dialog, then select Open to open the import wizard.

2. Select the hellospring folder.

   

Deploy the app

In order to deploy to Azure, you must sign in with your Azure account, then choose your subscription. For sign-in details, see Installation and sign-in.

1. Right-click your project in IntelliJ project explorer, then select Azure -> Deploy to Azure Spring Apps.

   

2. Accept the name for the app in the Name field. Name refers to the configuration, not the app name. Users don't usually need to change it.

3. In the Artifact textbox, select Maven:com.example:hellospring-0.0.1-SNAPSHOT.

4. In the Subscription textbox, verify your subscription is correct.

5. In the Service textbox, select the instance of Azure Spring Apps that you created in Provision an instance of Azure Spring Apps.

6. In the App textbox, select + to create a new app.

   

7. In the App name: textbox, enter hellospring, then check the More settings check box.

8. Select the Enable button next to Public endpoint. The button will change to Disable <to be enabled>.

9. If you used Java 11, select Java 11 in Runtime.

10. Select OK.

    

11. Under Before launch, select the Run Maven Goal 'hellospring:package' line, then select the pencil to edit the command line.

    

12. In the Command line textbox, enter -DskipTests after package, then select OK.

    

13. Start the deployment by selecting the Run button at the bottom of the Deploy Azure Spring Apps app dialog. The plug-in will run the command mvn package -DskipTests on the hellospring app and deploy the jar generated by the package command.

Visual Studio Code

To deploy a simple Spring Boot web app to Azure Spring Apps, follow the steps in Build and Deploy Java Spring Boot Apps to Azure Spring Apps with Visual Studio Code.

Once deployment has completed, you can access the app at https://<service instance name>-hellospring.azuremicroservices.io/.

Streaming logs in real time

CLI

Use the following command to get real-time logs from the App.

az spring app logs -n hellospring -s <service instance name> -g <resource group name> --lines 100 -f

Logs appear in the results:

Tip

Use az spring app logs -h to explore more parameters and log stream functionalities.

IntelliJ

1. Select Azure Explorer, then Spring Cloud.

2. Right-click the running app.

3. Select Streaming Logs from the drop-down list.

4. Select instance.

   

5. The streaming log will be visible in the output window.

   

Visual Studio Code

To get real-time application logs with Visual Studio Code, follow the steps in Stream your application logs.

For advanced logs analytics features, visit the Logs tab in the menu on the Azure portal. Logs here have a latency of a few minutes.

Clean up resources

If you plan to continue working with subsequent quickstarts and tutorials, you might want to leave these resources in place. When no longer needed, delete the resource group, which deletes the resources in the resource group. To delete the resource group by using Azure CLI, use the following commands:

echo "Enter the Resource Group name:" &&
read resourceGroupName &&
az group delete --name $resourceGroupName &&
echo "Press [ENTER] to continue ..."

Next steps

In this quickstart, you learned how to:

• Generate a basic Spring project
• Provision a service instance
• Build and deploy the app with a public endpoint
• Stream logs in real time

To learn how to use more Azure Spring capabilities, advance to the quickstart series that deploys a sample application to Azure Spring Apps:

Introduction to the sample app

More samples are available on GitHub: Azure Spring Apps Samples.