다음을 통해 공유

관리 ID를 사용하여 Azure 가상 머신에서 Azure Cosmos DB에 연결하는 방법

  • 아티클

이 문서에서는 관리 ID를 사용하여 Azure Cosmos DB에 연결하도록 가상 머신을 설정합니다. Azure Cosmos DB는 최신 앱을 개발하기 위한 완전 관리형 NoSQL 데이터베이스입니다. Azure 리소스에 대한 관리 ID를 사용하면 Azure에서 관리하는 ID를 사용하여 Microsoft Entra인증을 지원하는 서비스에 액세스할 때 애플리케이션을 인증할 수 있습니다.

필수 조건

리소스 그룹 만들기

mi-test라는 리소스 그룹을 만듭니다. 이 리소스 그룹은 이 자습서에서 사용되는 모든 리소스에 사용합니다.

관리 ID를 사용하여 Azure VM 만들기

이 자습서에는 Azure VM(가상 머신)이 필요합니다. mi-vm-01이라는 시스템이 할당한 관리 ID가 사용하도록 설정된 가상 머신을 만듭니다. 또한 이전에 만든 리소스 그룹(mi-test)에서 mi-ua-01이라는 사용자가 할당한 관리 ID를 만들 수도 있습니다. 사용자가 할당한 관리 ID를 사용하는 경우 만드는 동안 VM에 할당할 수 있습니다.

시스템이 할당한 관리 ID를 사용하는 VM 만들기

시스템 할당 관리 ID를 사용하도록 설정된 Azure VM을 만들려면 계정에 Virtual Machine 기여자 역할 할당이 필요합니다. 다른 Microsoft Entra 역할 할당은 필요하지 않습니다.

  • Azure Portal에서 가상 머신을 검색합니다.
  • 만들기를 선택합니다.
  • [기본 사항] 탭에서 필요한 정보를 제공합니다.
  • 다음: 디스크 >를 선택합니다.
  • 필요에 따라 정보를 계속 입력하고, 관리 탭에서 ID 섹션을 찾아서 시스템이 할당한 관리 ID 옆의 확인란을 선택합니다.

VM을 만드는 동안 시스템에 할당된 관리 ID를 사용하도록 설정하는 방법을 보여 주는 이미지

자세한 내용은 다음 Azure 가상 머신 설명서를 검토하세요.

사용자가 할당한 관리 ID를 사용하는 VM 만들기

아래 단계에서는 사용자가 할당한 관리 ID가 구성된 가상 머신을 만드는 방법을 보여 줍니다.

현재 Azure Portal은 VM을 만드는 동안 사용자가 할당한 관리 ID를 할당하도록 지원하지 않습니다. 가상 머신을 만든 다음, 사용자가 할당한 관리 ID를 할당해야 합니다.

Azure Portal을 사용하여 VM에서 Azure 리소스에 대한 관리 ID 구성

Azure Cosmos DB 계정 만들기

이제 사용자가 할당한 관리 ID 또는 시스템이 할당한 관리 ID를 사용하는 VM이 ​​있으므로 관리 권한이 있는 Azure Cosmos DB 계정이 필요합니다. 이 자습서에서 사용할 Azure Cosmos DB 계정을 만들어야 하는 경우 Azure Cosmos DB 빠른 시작에서 이 작업을 수행하는 방법에 대한 자세한 단계를 제공합니다.

참고 항목

관리 ID는 Microsoft Entra 인증을 지원하는 모든 Azure 리소스에 액세스하는 데 사용할 수 있습니다. 이 자습서에서는 Azure Cosmos DB 계정이 아래와 같이 구성되어 있다고 가정합니다.

설정 값 Description
구독 구독 이름 이 Azure Cosmos DB 계정에 사용할 Azure 구독을 선택합니다.
리소스 그룹 리소스 그룹 이름 mi-test를 선택하거나 새로 만들기를 선택한 다음, 새 리소스 그룹에 대한 고유한 이름을 입력합니다.
어카운트 이름 고유 이름 Azure Cosmos DB 계정을 식별하는 이름을 입력합니다. URI를 만들기 위해 제공하는 이름에 documents.azure.com이 추가되므로 고유한 이름을 사용합니다.

이름은 소문자, 숫자 및 하이픈(-) 문자만 포함할 수 있으며, 길이는 3~44자여야 합니다.
API 만들 계정 형식 Azure Cosmos DB for NoSQL을 선택하여 문서 데이터베이스를 만들고 SQL 구문을 사용하여 쿼리합니다.

SQL API에 대한 자세한 정보
위치 사용자와 가장 가까운 지역 Azure Cosmos DB 계정을 호스트할 지리적 위치를 선택합니다. 데이터에 가장 빨리 액세스할 수 있도록 사용자와 가장 가까운 위치를 사용합니다.

참고 항목

테스트하는 경우 Azure Cosmos DB 무료 계층 할인을 적용할 수 있습니다. Azure Cosmos DB 무료 계층을 사용하는 경우 처음에는 1000RU/초 및 25GB의 스토리지가 계정에 무료로 제공됩니다. 체험 계층에 대해 자세히 알아보세요. 이 자습서의 목적을 위해 이 선택은 아무런 차이가 없습니다.

액세스 허가

이 시점에서 관리 ID와 Azure Cosmos DB 계정으로 구성된 두 개의 가상 머신이 모두 있어야 합니다. 계속하기 전에 몇 가지 다른 역할을 관리 ID에 부여해야 합니다.

  • 먼저 Azure RBAC를 사용하여 Azure Cosmos DB 관리 평면에 대한 액세스 권한을 부여합니다. 데이터베이스 및 컨테이너를 만들려면 DocumentDB 계정 기여자 역할을 관리 ID에 할당해야 합니다.

  • Azure Cosmos DB RBAC도 사용하여 기여자 역할을 관리 ID에 부여해야 합니다. 구체적인 단계는 아래에서 확인할 수 있습니다.

참고 항목

여기서는 Cosmos DB 기본 제공 데이터 기여자 역할을 사용합니다. 액세스 권한을 부여하려면 역할 정의를 ID와 연결해야 합니다. 이 경우 가상 머신과 연결된 관리 ID입니다.

Azure Portal에는 현재 사용할 수 있는 역할 할당 옵션이 없습니다.

데이터 액세스

관리 ID를 사용하여 Azure Cosmos DB에 액세스하려면 Azure.identity 라이브러리를 사용하여 애플리케이션에서 인증을 사용하도록 설정할 수 있습니다. ManagedIdentityCredential을 직접 호출하거나 DefaultAzureCredential을 사용할 수 있습니다.

ManagedIdentityCredential 클래스는 배포 환경에 할당된 관리 ID를 사용하여 인증을 시도합니다. DefaultAzureCredential 클래스는 다양한 인증 옵션을 순서대로 시도합니다. DefaultAzureCredential에서 시도하는 두 번째 인증 옵션은 관리 ID입니다.

아래 예제에서는 데이터베이스, 컨테이너, 컨테이너의 항목을 만들고, 가상 머신의 시스템이 할당한 관리 ID를 사용하여 새로 만든 항목을 다시 읽습니다. 사용자가 할당한 관리 ID를 사용하려면 관리 ID의 클라이언트 ID를 지정하여 사용자가 할당한 관리 ID를 지정해야 합니다.

string userAssignedClientId = "<your managed identity client Id>";
var tokenCredential = new DefaultAzureCredential(new DefaultAzureCredentialOptions { ManagedIdentityClientId = userAssignedClientId });

아래 샘플을 사용하려면 다음 NuGet 패키지가 필요합니다.

  • Azure.Identity
  • Microsoft.Azure.Cosmos
  • Microsoft.Azure.Management.CosmosDB

위의 NuGet 패키지 외에도 시험판 포함을 사용하도록 설정한 다음, Azure.ResourceManager.CosmosDB를 추가해야 합니다.

using Azure.Identity;
using Azure.ResourceManager.CosmosDB;
using Azure.ResourceManager.CosmosDB.Models;
using Microsoft.Azure.Cosmos;
using System;
using System.Threading.Tasks;

namespace MITest
{
    class Program
    {
        static async Task Main(string[] args)
        {
            // Replace the placeholders with your own values
            var subscriptionId = "Your subscription ID";
            var resourceGroupName = "You resource group";
            var accountName = "Cosmos DB Account name";
            var databaseName = "mi-test";
            var containerName = "container01";

            // Authenticate to Azure using Managed Identity (system-assigned or user-assigned)
            var tokenCredential = new DefaultAzureCredential();

            // Create the Cosmos DB management client using the subscription ID and token credential
            var managementClient = new CosmosDBManagementClient(tokenCredential)
            {
                SubscriptionId = subscriptionId
            };

            // Create the Cosmos DB data client using the account URL and token credential
            var dataClient = new CosmosClient($"https://{accountName}.documents.azure.com:443/", tokenCredential);

            // Create a new database using the management client
            var createDatabaseOperation = await managementClient.SqlResources.StartCreateUpdateSqlDatabaseAsync(
                resourceGroupName,
                accountName,
                databaseName,
                new SqlDatabaseCreateUpdateParameters(new SqlDatabaseResource(databaseName), new CreateUpdateOptions()));
            await createDatabaseOperation.WaitForCompletionAsync();

            // Create a new container using the management client
            var createContainerOperation = await managementClient.SqlResources.StartCreateUpdateSqlContainerAsync(
                resourceGroupName,
                accountName,
                databaseName,
                containerName,
                new SqlContainerCreateUpdateParameters(new SqlContainerResource(containerName), new CreateUpdateOptions()));
            await createContainerOperation.WaitForCompletionAsync();

            // Create a new item in the container using the data client
            var partitionKey = "pkey";
            var id = Guid.NewGuid().ToString();
            await dataClient.GetContainer(databaseName, containerName)
                .CreateItemAsync(new { id = id, _partitionKey = partitionKey }, new PartitionKey(partitionKey));

            // Read back the item from the container using the data client
            var pointReadResult = await dataClient.GetContainer(databaseName, containerName)
                .ReadItemAsync<dynamic>(id, new PartitionKey(partitionKey));

            // Run a query to get all items from the container using the data client
            await dataClient.GetContainer(databaseName, containerName)
                .GetItemQueryIterator<dynamic>("SELECT * FROM c")
                .ReadNextAsync();
        }
    }
}

ManagedIdentityCredential을 사용하는 언어별 예제는 다음과 같습니다.

.NET

Azure Cosmos DB 클라이언트를 초기화합니다.

CosmosClient client = new CosmosClient("<account-endpoint>", new ManagedIdentityCredential());

그런 다음, 데이터를 읽고 씁니다.

Java

Azure Cosmos DB 클라이언트를 초기화합니다.

CosmosAsyncClient Client = new CosmosClientBuilder().endpoint("<account-endpoint>") .credential(new ManagedIdentityCredential()) .build();

그런 다음, 이러한 샘플에서 설명한 대로 데이터를 읽고 씁니다.

JavaScript

Azure Cosmos DB 클라이언트를 초기화합니다.

const client = new CosmosClient({ "<account-endpoint>", aadCredentials: new ManagedIdentityCredential() });

그런 다음, 이러한 샘플에서 설명한 대로 데이터를 읽고 씁니다.

정리 단계

팁

이 문서의 단계는 시작하는 포털에 따라 약간 다를 수 있습니다.

  1. Azure Portal에 로그인합니다.

  2. 삭제하려는 리소스를 선택합니다.

  3. 삭제를 선택합니다.

  4. 메시지가 표시되면 삭제를 확인합니다.

다음 단계

Azure 리소스의 관리 ID에 대해 자세히 알아보기

Azure Cosmos DB에 대해 자세히 알아보세요.