Bind an Azure Cosmos DB database to your application in 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: ✔️ Java ❌ C#

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

Instead of manually configuring your Spring Boot applications, you can automatically bind select Azure services to your applications by using Azure Spring Apps. This article demonstrates how to bind your application to an Azure Cosmos DB database.

Prerequisites

  • A deployed Azure Spring Apps instance.
  • An Azure Cache for Redis service instance.
  • The Azure Spring Apps extension for the Azure CLI.

If you don't have a deployed Azure Spring Apps instance, follow the steps in the Quickstart: Deploy your first application to Azure Spring Apps.

Prepare your Java project

  1. Add one of the following dependencies to your application's pom.xml pom.xml file. Choose the dependency that is appropriate for your API type.

    • API type: NoSQL

      <dependency>
          <groupId>com.azure.spring</groupId>
          <artifactId>spring-cloud-azure-starter-data-cosmos</artifactId>
          <version>4.3.0</version>
      </dependency>
      
    • API type: MongoDB

      <dependency>
          <groupId>org.springframework.boot</groupId>
          <artifactId>spring-boot-starter-data-mongodb</artifactId>
      </dependency>
      
    • API type: Cassandra

      <dependency>
          <groupId>org.springframework.boot</groupId>
          <artifactId>spring-boot-starter-data-cassandra</artifactId>
      </dependency>
      
    • API type: Azure Table

      <dependency>
          <groupId>com.azure.spring</groupId>
          <artifactId>spring-cloud-azure-starter-storage-blob</artifactId>
          <version>4.3.0</version>
      </dependency>
      
  2. Update the current app by running az spring app deploy, or create a new deployment for this change by running az spring app deployment create.

Bind your app to the Azure Cosmos DB

  1. Use the Azure CLI to configure your Spring app to connect to a Cosmos SQL Database with a system-assigned managed identity by using the az spring connection create command, as shown in the following example.

    Note

    Updating Azure Cosmos DB database settings can take a few minutes to complete.

    az spring connection create cosmos-sql \
        --resource-group $AZURE_SPRING_APPS_RESOURCE_GROUP \
        --service $AZURE_SPRING_APPS_SERVICE_INSTANCE_NAME \
        --app $APP_NAME \
        --deployment $DEPLOYMENT_NAME \
        --target-resource-group $COSMOSDB_RESOURCE_GROUP \
        --account $COSMOSDB_ACCOUNT_NAME \
        --database $DATABASE_NAME \
        --system-assigned-identity
    

    Note

    If you're using Service Connector for the first time, start by running the command az provider register --namespace Microsoft.ServiceLinker to register the Service Connector resource provider.

    If you're using Cosmos Cassandra, use a --key_space instead of --database.

    Tip

    Run the command az spring connection list-support-types --output table to get a list of supported target services and authentication methods for Azure Spring Apps. If the az spring command isn't recognized by the system, check that you have installed the required extension by running az extension add --name spring.

  2. Alternately, you can use the Azure portal to configure this connection by completing the following steps. The Azure portal provides the same capabilities as the Azure CLI and provides an interactive experience.

    1. Select your Azure Spring Apps instance in the Azure portal and select Apps from the navigation menu. Choose the app you want to connect and select Service Connector on the navigation menu.

    2. Select Create.

    3. On the Basics tab, for service type, select Cosmos DB, then choose a subscription. For API type, select Core (SQL), choose a Cosmos DB account, and a database. For client type, select Java, then select Next: Authentication. If you haven't created your database yet, see Quickstart: Create an Azure Cosmos DB account, database, container, and items from the Azure portal.

    4. On the Authentication tab, choose Connection string. Service Connector automatically retrieves the access key from your Cosmos DB account. Select Next: Networking.

    5. On the Networking tab, select Configure firewall rules to enable access to target service, then select Next: Review + Create.

    6. On the Review + Create tab, wait for the validation to pass and then select Create. The creation can take a few minutes to complete.

    7. Once the connection between your Spring apps and your Cosmos DB database has been generated, you can see it in the Service Connector page and select the unfold button to view the configured connection variables.

Next steps

In this article, you learned how to bind your application in Azure Spring Apps to an Azure Cosmos DB database. To learn more about binding services to your application, see Bind to an Azure Cache for Redis cache.