Linux 기반 에뮬레이터 - vNext(미리 보기)

적용 대상: ✅ NoSQL

차세대 Azure Cosmos DB 에뮬레이터는 전적으로 Linux 기반이며 Docker 컨테이너로 사용할 수 있습니다. 다양한 프로세서 및 운영 체제에서 실행을 지원합니다.

Important

이 버전의 에뮬레이터는 게이트웨이 모드에서만 NoSQL API를 지원하며, 기능의 하위 집합을 선택합니다. 자세한 내용은 기능 지원을 참조하세요.

필수 조건

Docker

설치

를 사용하여 docker pullDocker 컨테이너 이미지를 가져옵니다. 컨테이너 이미지는 Microsoft 아티팩트 레지스트리.

docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview

실행 중

컨테이너를 실행하려면 .를 사용합니다 docker run. 그런 다음 컨테이너가 실행 중인지 확인하는 데 사용합니다 docker ps .

docker run --detach --publish 8081:8081 --publish 8080:8080 --publish 1234:1234 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview

docker ps

CONTAINER ID   IMAGE                                                             COMMAND                  CREATED         STATUS         PORTS                                                                                  NAMES
c1bb8cf53f8a   mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview  "/bin/bash -c /home/…"   5 seconds ago   Up 5 seconds   0.0.0.0:1234->1234/tcp, :::1234->1234/tcp, 0.0.0.0:8081->8081/tcp, :::8081->8081/tcp   <container-name>

에뮬레이터에는 다음 두 가지 구성 요소가 포함됩니다.

Data Explorer - 에뮬레이터의 데이터를 대화형으로 탐색합니다. 기본적으로 이 구성 요소는 포트 1234에서 실행됩니다.
Azure Cosmos DB 에뮬레이터 - Azure Cosmos DB 데이터베이스 서비스의 로컬 버전입니다. 기본적으로 이 구성 요소는 포트 8081에서 실행됩니다.

에뮬레이터 게이트웨이 엔드포인트는 주소8081의 포트 http://localhost:8081 를 사용합니다. Data Explorer 이동하려면 웹 브라우저에서 주소 http://localhost:1234 사용합니다. 게이트웨이 엔드포인트는 일반적으로 즉시 사용할 수 있지만 Data Explorer 시작하는 데 몇 초 정도 걸릴 수 있습니다.

건강 상태 검사기

에뮬레이터는 포트 8080에 상태 프로브 엔드포인트를 노출합니다. 이 엔드포인트를 사용하여 에뮬레이터가 완전히 초기화되고 요청을 수락할 준비가 된 시기를 결정합니다.

다음 엔드포인트를 사용할 수 있습니다.

http://localhost:8080/alive — 라이브니스 프로브.
http://localhost:8080/ready — 준비 상태 프로브입니다.
http://localhost:8080/status — 자세한 상태입니다.

비고

레거시 로그 메시지는 System is now fully ready to accept requests 이전 버전과의 호환성을 위해 계속 내보내지만 이후 버전에서 제거될 수 있습니다. 대신 상태 프로브를 사용하여 준비 검사를 수행합니다.

HTTPS 모드

.NET 및 Java SDK는 에뮬레이터에서 HTTP 모드를 지원하지 않습니다. 이 버전의 에뮬레이터는 기본적으로 HTTP로 시작되므로 컨테이너를 시작할 때 HTTPS를 명시적으로 사용하도록 설정해야 합니다(아래 참조). Java SDK의 경우 인증서도 설치해야 합니다.

docker run --detach --publish 8081:8081 --publish 8080:8080 --publish 1234:1234 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview --protocol https

지속형 데이터 볼륨에서 HTTPS를 사용하는 경우 에뮬레이터는 시작할 때 SSL 인증서를 자동으로 다시 생성하므로 인증서 갱신을 관리할 필요가 없습니다.

Docker 명령

다음 표에서는 에뮬레이터를 구성하는 데 사용할 수 있는 Docker 명령을 요약합니다. 이 표에서는 해당 인수, 환경 변수, 허용되는 값, 기본 설정 및 각 명령에 대한 설명을 자세히 설명합니다.

요구 사항	인수	환경 변수	허용되는 값	기본값	Description
컨테이너에서 stdout으로 설정 인쇄	`--help`, `-h`	N/A	N/A	N/A	사용 가능한 구성에 대한 정보 표시
Cosmos 엔드포인트의 포트 설정	`--port [INT]`	포트	INT	8081	컨테이너에 있는 Cosmos 엔드포인트의 포트입니다. 이 포트를 게시해야 합니다(예: `-p 8081:8081`).
Cosmos 엔드포인트에서 사용하는 프로토콜 지정	`--protocol`	프로토콜	`https`, `http`, `https-insecure`	`http`	컨테이너의 Cosmos 엔드포인트 프로토콜입니다.
데이터 탐색기 사용	`--enable-explorer`	탐색기_활성화	`true`, `false`	`true`	동일한 컨테이너에서 Cosmos Data Explorer 실행할 수 있습니다.
데이터 탐색기에서 사용하는 포트 설정	`--explorer-port`	EXPLORER_PORT	INT	1234	Cosmos Data Explorer의 포트가 컨테이너에 있습니다. 이 포트를 게시해야 합니다(예: `-p 1234:1234`).
데이터 탐색기에서 사용하는 프로토콜 지정	`--explorer-protocol`	EXPLORER_PROTOCOL (탐색기_프로토콜)	`https`, `http`, `https-insecure`	`<the value of --protocol>`	컨테이너에 있는 Cosmos 데이터 탐색기의 프로토콜입니다. Cosmos 엔드포인트의 프로토콜 설정을 기본값으로 사용합니다.
게이트웨이 퍼블릭 엔드포인트 사용자 지정	`--gateway-endpoint`	GATEWAY_PUBLIC_ENDPOINT	N/A	`localhost`	공용 게이트웨이 엔드포인트입니다. 기본값은 `localhost`입니다.
파일을 통해 키 지정	`--key-file [PATH]`	KEY_FILE	경로	`<default secret>`	기본 키를 파일에 지정된 키로 재정의합니다. 이 파일을 컨테이너에 탑재해야 합니다(예: KEY_FILE=/mykey인 경우 docker 실행에 `--mount type=bind,source=./myKey,target=/myKey`다음과 같은 옵션을 추가합니다.)
데이터 경로 설정	`--data-path [PATH]`	DATA_PATH	경로	`/data`	데이터의 디렉터리를 지정합니다. 옵션과 함께 `docker run --mount` 자주 사용됩니다(예: DATA_PATH=/usr/cosmos/data인 경우 Docker 실행에 `--mount type=bind,source=./.local/data,target=/usr/cosmos/data`다음과 같은 옵션을 추가합니다.)
https에 사용할 인증서 경로 지정	`--cert-path [PATH]`	CERT_PATH	경로	`<default cert>`	트래픽을 보호하기 위한 인증서 경로를 지정합니다. 이 파일을 컨테이너에 탑재해야 합니다(예: CERT_PATH=/mycert.pfx인 경우 docker 실행에 `--mount type=bind,source=./mycert.pfx,target=/mycert.pfx`다음과 같은 옵션을 추가합니다.)
https에 사용할 인증서 비밀 지정	N/A	CERT_SECRET	string	`<default secret>`	CERT_PATH에 지정된 인증서의 암호입니다.
로그 수준 설정	`--log-level [LEVEL]`	로그_레벨	`quiet`, `error`, `warn`, `info`, `debugtrace`	`info`	에뮬레이터 및 데이터 탐색기에서 생성된 로그의 상세 수준입니다.
OpenTelemetry OTLP 내보내기 활성화	`--enable-otlp`	ENABLE_OTLP_EXPORTER	`true`, `false`	`false`	OpenTelemetry 통합을 사용하도록 설정합니다.
콘솔 내보내기 활성화	`--enable-console`	ENABLE_CONSOLE_EXPORTER	`true`, `false`	`false`	원격 분석 데이터의 콘솔 출력을 사용하도록 설정합니다(디버깅에 유용).
자세한 정보 표시 모드 사용	`--verbose`	장황한	`true`, `false`	`false`	베르보스 모드를 사용하여 PostgreSQL 로그(pglog)를 콘솔에 출력합니다. 디버깅에 유용합니다.
쿼리 버퍼 크기 설정	`--query-buffer-size`	QUERY_BUFFER_SIZE_KB	INT	4096(4MB), 최대 65536(64MB)	쿼리 결과 버퍼의 최대 크기(KB)입니다. 대규모 쿼리에서 HTTP 500 오류가 발생하는 경우 이를 늘입니다.
Microsoft로 보내는 진단 정보 활성화	`--enable-telemetry`	원격 측정 활성화	`true`, `false`	`true`	에뮬레이터를 개선하는 데 도움이 되도록 사용 현황 데이터를 Microsoft에 보낼 수 있습니다.

기능 지원

이 에뮬레이터는 현재 개발 및 미리 보기 상태입니다. 따라서 모든 Azure Cosmos DB 기능이 지원되지는 않습니다. 일부 기능은 나중에 지원되지 않습니다. 이 표에는 다양한 기능의 상태와 지원 수준이 포함되어 있습니다.

기능	Support
Batch API	✅ 지원됨
대량 API	✅ 지원됨
변경 사항 알림	✅ 지원됨
utf 데이터를 사용하여 문서 만들기 및 읽기	✅ 지원됨
컬렉션 만들기	✅ 지원됨
컬렉션을 두 번 생성할 때의 충돌	✅ 지원됨
사용자 지정 인덱스 정책을 사용하여 컬렉션 만들기	⚠️ No-op
ttl 만료를 사용하여 컬렉션 만들기	✅ 지원됨
데이터베이스 만들기	✅ 지원됨
데이터베이스 만들기 두 번 충돌	✅ 지원됨
문서 만들기	✅ 지원됨
분할된 컬렉션 만들기	✅ 지원됨
컬렉션 삭제	✅ 지원됨
데이터베이스 삭제	✅ 지원됨
문서 삭제	✅ 지원됨
컬렉션 성능 가져오기 및 변경	⚠️ 아직 구현되지 않음
큰 문서 삽입	✅ 지원됨
문서 패치	✅ 지원됨
분할된 컬렉션을 병렬로 쿼리	⚠️ 아직 구현되지 않음
집계를 사용하여 쿼리	✅ 지원됨
쿼리 및 필터링	✅ 지원됨
쿼리, 필터링, 프로젝션	✅ 지원됨
동등 조건 쿼리	✅ 지원됨
ID에 대한 동등 연산 쿼리	✅ 지원됨
조인을 사용하여 쿼리	✅ 지원됨
정렬 기준으로 쿼리 수행	✅ 지원됨
분할된 컬렉션에 대한 순서를 사용하여 쿼리	✅ 지원됨
숫자로 순서를 사용하여 쿼리	✅ 지원됨
문자열별 순서를 사용하여 쿼리	✅ 지원됨
페이징을 사용하여 쿼리	✅ 지원됨
범위 연산자와 날짜 시간을 사용한 쿼리	✅ 지원됨
숫자의 범위 연산자를 사용하여 쿼리	✅ 지원됨
문자열에 범위 연산자를 사용하여 쿼리	✅ 지원됨
단일 조인을 사용하여 쿼리	✅ 지원됨
문자열 수학 및 배열 연산자를 사용하여 쿼리	✅ 지원됨
하위 문서를 사용하여 쿼리	✅ 지원됨
두 개의 조인을 사용하여 쿼리	✅ 지원됨
두 개의 조인 및 필터를 사용하여 쿼리	✅ 지원됨
컬렉션 읽기	✅ 지원됨
컬렉션 피드 읽기	⚠️ 아직 구현되지 않음
데이터베이스 읽기	✅ 지원됨
데이터베이스 피드 읽기	⚠️ 아직 구현되지 않음
문서 읽기	✅ 지원됨
문서 피드 읽기	✅ 지원됨
문서 바꾸기	✅ 지원됨
요청 단위	⚠️ 아직 구현되지 않음
저장 프로시저	❌ 계획되지 않음
트리거	❌ 계획되지 않음
UDF	❌ 계획되지 않음
컬렉션 업데이트	⚠️ No-op
문서 업데이트	✅ 지원됨
엔드포인트 제공	⚠️ No-op
사용자 엔드포인트	⚠️ No-op
권한 엔드포인트	⚠️ No-op
클라이언트 암호화 키(CEK)	⚠️ No-op

비고

No-op으로 표시된 기능은 요청을 수락하고 유효한 HTTP 상태 코드를 반환하지만 기본 작업을 실행하지는 않습니다. 코드는 중단되지 않지만 기능 동작에 대해 이러한 기능에 의존하지 않습니다. 사용자 지정 인덱스 정책 및 컬렉션 업데이트는 호환성을 위해 허용되지만 쿼리는 사용자 지정 인덱스에 의해 최적화되지 않습니다.

제한점

아직 지원되지 않거나 계획되지 않은 기능 외에도 다음 목록에는 에뮬레이터의 현재 제한 사항이 포함되어 있습니다.

Azure Cosmos DB용 .NET SDK는 에뮬레이터에서 대량 실행을 지원하지 않습니다.
대규모 쿼리 결과에서 HTTP 500 오류가 발생하는 경우 플래그 또는 --query-buffer-size 환경 변수를 사용하여 QUERY_BUFFER_SIZE_KB 쿼리 버퍼 크기를 늘입니다. 기본값은 4096 KB(4MB)이며 최대값은 KB(65536MB)입니다64.

Java SDK용 인증서 설치

https 모드에서 이 버전의 에뮬레이터와 함께 Azure Cosmos DB Java SDK를 사용하는 경우 로컬 Java 신뢰 저장소에 인증서를 설치해야 합니다.

인증서 가져오기

bash 창에서 다음을 실행합니다.

# If the emulator was started with /AllowNetworkAccess, replace localhost with the actual IP address of it:
EMULATOR_HOST=localhost
EMULATOR_PORT=8081
EMULATOR_CERT_PATH=/tmp/cosmos_emulator.cert
openssl s_client -connect ${EMULATOR_HOST}:${EMULATOR_PORT} </dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > $EMULATOR_CERT_PATH

인증서 설치

파일이 있는 cacerts Java 설치의 디렉터리로 이동합니다(아래를 올바른 디렉터리로 바꿉다).

cd "C:/Program Files/Eclipse Adoptium/jdk-17.0.10.7-hotspot/bin"

인증서를 가져옵니다(암호를 입력하라는 메시지가 표시될 수 있습니다. 기본값은 "changeit").

keytool -cacerts -importcert -alias cosmos_emulator -file $EMULATOR_CERT_PATH

별칭이 이미 있으므로 오류가 발생하면 해당 별칭을 삭제한 다음 위 항목을 다시 실행합니다.

keytool -cacerts -delete -alias cosmos_emulator

OpenTelemetry 지원

OpenTelemetry 는 원격 분석 데이터를 계측, 생성, 수집 및 내보내기 위한 도구, API 및 SDK 컬렉션을 제공하는 오픈 소스 관찰성 프레임워크입니다. OTLP(OpenTelemetry Protocol)는 OpenTelemetry에서 구성 요소 간에 원격 분석 데이터를 전송하는 데 사용하는 프로토콜입니다.

에뮬레이터에서 OpenTelemetry를 사용하여 애플리케이션을 모니터링하고 추적할 수 있습니다. 에뮬레이터는 Docker 컨테이너를 실행할 때 환경 변수 또는 명령줄 플래그를 통해 구성할 수 있는 원격 분석 옵션을 지원합니다.

에뮬레이터는 다음 메트릭을 내보냅니다. OTLP를 지원하고 데이터베이스의 성능 및 상태에 대한 중요한 인사이트를 제공하는 메트릭 백 엔드를 통해 사용할 수 있습니다.

요청 속도: 다양한 작업 유형에 대한 트래픽 패턴을 표시합니다.
쿼리 실행 시간: 다른 쿼리를 실행하는 데 걸린 시간을 측정합니다.
리소스 사용률: CPU, 메모리 사용량 및 연결 풀 메트릭
오류 비율: 유형 및 엔드포인트별 오류 추적

비고

에뮬레이터는 OTLP 내보내기용 조건부 TLS를 지원하므로 보안 연결이 필요한 관찰성 플랫폼과 통합할 수 있습니다.

예제가 포함된 자세한 지침 은 GitHub 리포지토리에서 사용할 수 있습니다.

연속 통합 워크플로에서 사용

특히 데이터베이스와 같은 상태 저장 시스템의 경우 CI/CD 파이프라인에서 Docker 컨테이너를 사용하는 경우 많은 이점이 있습니다. 이는 테스트 도구 모음의 비용 효율성, 성능, 안정성 및 일관성 측면에서 발생할 수 있습니다.

에뮬레이터는 CI/CD 파이프라인의 일부로 통합될 수 있습니다. .NET, Python, Java 및 Go 애플리케이션에서 및 x64 아키텍처를 대상으로 GitHub Actions CI 워크플로의 일부로 에뮬레이터를 사용하는 방법에 대한 예제를 제공하는 이 ARM64를 참조할 수 있습니다 (Linux 러너에 ubuntu를 사용하는 것이 시연됨).

워크플로에서 작업의 일부로 에뮬레이터를 GitHub Actions 서비스 컨테이너 로 구성하는 방법을 보여 주는 GitHub Actions CI 워크플로의 예는 다음과 같습니다. GitHub Docker 컨테이너를 시작하고 작업이 완료되면 수동으로 개입할 필요 없이(예: docker run 명령 사용) 삭제합니다.

name: CI demo app

on:
  push:
    branches: [main]
    paths:
      - 'java-app/**'
  pull_request:
    branches: [main]
    paths:
      - 'java-app/**'

jobs:
  build-and-test:
    runs-on: ubuntu-latest

    services:
      cosmosdb:
        image: mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview
        ports:
          - 8081:8081
        env:
          PROTOCOL: https
        
    env:
      COSMOSDB_CONNECTION_STRING: ${{ secrets.COSMOSDB_CONNECTION_STRING }}
      COSMOSDB_DATABASE_NAME: ${{ vars.COSMOSDB_DATABASE_NAME }}
      COSMOSDB_CONTAINER_NAME: ${{ vars.COSMOSDB_CONTAINER_NAME }}

    steps:

      - name: Set up Java
        uses: actions/setup-java@v3
        with:
          distribution: 'microsoft'
          java-version: '21.0.0'

      - name: Export Cosmos DB Emulator Certificate
        run: |

          sudo apt update && sudo apt install -y openssl

          openssl s_client -connect localhost:8081 </dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > cosmos_emulator.cert

          cat cosmos_emulator.cert

          $JAVA_HOME/bin/keytool -cacerts -importcert -alias cosmos_emulator -file cosmos_emulator.cert -storepass changeit -noprompt
      
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Run tests
        run: cd java-app && mvn test

이 작업은 Ubuntu 실행기에서 실행되며 Docker 이미지를 서비스 컨테이너로 사용합니다 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview . 환경 변수를 사용하여 연결 문자열, 데이터베이스 이름 및 컨테이너 이름을 구성합니다. 이 경우 작업이 GitHub Actions 실행기 컴퓨터에서 직접 실행되므로 작업의 실행 테스트 단계에서는 localhost:8081(8081는 에뮬레이터에 의해 노출되는 포트)를 사용하여 에뮬레이터에 액세스할 수 있습니다.

Export Cosmos DB 에뮬레이터 인증서 단계는 Azure Cosmos DB Java SDK가 현재 에뮬레이터에서 HTTP 모드를 지원하지 않으므로 Java 애플리케이션에만 적용됩니다. PROTOCOL 환경 변수는 https 섹션에서 services로 설정되며 이 단계에서는 에뮬레이터 인증서를 내보낸 후 Java 키스토어로 가져옵니다. .NET에도 동일하게 적용됩니다.

문제 신고

이 버전의 에뮬레이터를 사용하는 데 문제가 발생하는 경우 GitHub 리포지토리(https://github.com/Azure/azure-cosmos-db-emulator-docker)에서 문제를 열고 레이블 cosmosEmulatorVnextPreview로 태그를 지정합니다.

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-04-27