Qdrant Managed Cloud의 데이터베이스 인증
Qdrant Managed Cloud의 데이터베이스 인증 (cloud-authentication)
이 페이지에서는 데이터베이스 API 키(Database API key)가 무엇인지 설명하고, Qdrant Cloud 콘솔을 사용해 클러스터용 데이터베이스 API 키를 만드는 방법을 보여줘요. 새 API 키를 사용해 클러스터에 연결하는 방법도 배울 수 있어요.
데이터베이스 API 키는 세밀한 접근 제어(granular access control)로 구성할 수 있어요. 세밀한 접근 제어가 있는 데이터베이스 API 키는 eyJhb로 시작하는 것을 확인할 수 있어요. 어떤 권한을 구성할 수 있는지 이해하려면 접근 표(Table of access)를 참고해 주세요.
세밀한 접근 제어가 있는 데이터베이스 API 키는 v1.11.0 이상 버전을 사용하는 클러스터에서 사용할 수 있어요.
데이터베이스 API 키 만들기
- Cloud 대시보드로 이동해 주세요.
- 클러스터 상세 페이지(Cluster Detail Page) 의 API 키(API Keys) 섹션으로 이동해 주세요.
- 만들기(Create) 를 클릭해 주세요.
- API 키의 이름과 선택적 만료 기간(일 단위, 기본값은 90일)을 선택해 주세요. 만료 기간을 비워두면 만료되지 않아요.
- 기본적으로 토큰에는 클러스터 전체 권한이 주어지며, 관리/쓰기 권한(기본값) 또는 읽기 전용 중에서 선택할 수 있어요.
토큰을 특정 컬렉션 집합으로 제한하려면 컬렉션(Collections) 탭을 선택하고 클러스터에서 사용 가능한 컬렉션을 고르면 돼요. 6. 만들기(Create) 를 클릭하고 API 키를 받아주세요.
보안 모범 사례로 만료 기간을 구성하고 API 키를 정기적으로 교체할 것을 권장해요.
관리자 데이터베이스 API 키 (Admin Database API Keys)
이전 버전의 데이터베이스 API 키인 관리자 데이터베이스 API 키(Admin Database API keys) 는 세밀한 접근 제어가 없어요. 2025년 1월 27일 이전에 생성된 클러스터에는 관리자 데이터베이스 API 키를 만드는 옵션이 여전히 표시돼요. 기존 관리자 데이터베이스 API 키는 계속 작동하지만, 더 나은 보안 제어를 활용할 수 있도록 세밀한 접근 제어가 있는 데이터베이스 API 키로 전환할 것을 권장해요.
세밀한 접근 제어가 있는 데이터베이스 API 키를 활성화하려면 클러스터 상세 페이지의 API 키(API Keys) 섹션에서 활성화(Enable) 를 클릭해 주세요.
클러스터에서 세밀한 접근 제어가 있는 데이터베이스 API 키를 활성화한 후에도 기존 관리자 데이터베이스 API 키는 계속 작동하지만, 새 관리자 데이터베이스 API 키는 만들 수 없게 돼요.
클러스터 접근 테스트하기
생성 후에는 클러스터에 접근할 수 있는 코드 조각을 받게 돼요. 생성된 요청은 다음과 비슷할 거예요:
curl \
-X GET 'https://xyz-example.cloud-region.cloud-provider.cloud.qdrant.io:6333' \
--header 'api-key: <paste-your-api-key-here>'
터미널을 열고 요청을 실행해 주세요. 다음과 같은 응답을 받을 거예요:
{ "title" : "qdrant - vector search engine" , "version" : "1.13.0" , "commit" : "ffda0b90c8c44fc43c99adab518b9787fe57bde6" }
참고: REST 또는 gRPC를 통한 모든 요청의 요청 헤더에 API 키를 포함해야 해요.
SDK로 인증하기
이제 첫 번째 클러스터와 키를 만들었으니, 애플리케이션 내부에서 데이터베이스에 접근하고 싶을 거예요. Python, TypeScript, Go, Rust, .NET, Java용 공식 Qdrant 클라이언트는 모두 API 키 매개변수를 지원해요.
curl \
-X GET https://xyz-example.cloud-region.cloud-provider.cloud.qdrant.io:6333 \
--header 'api-key: <provide-your-own-key>'
# Alternatively, you can use the `Authorization` header with the `Bearer` prefix
curl \
-X GET https://xyz-example.cloud-region.cloud-provider.cloud.qdrant.io:6333 \
--header 'Authorization: Bearer <provide-your-own-key>'
from qdrant_client import QdrantClient
qdrant_client = QdrantClient(
"xyz-example.cloud-region.cloud-provider.cloud.qdrant.io",
api_key="<paste-your-api-key-here>",
)
import { QdrantClient } from "@qdrant/js-client-rest";
const client = new QdrantClient({
host: "xyz-example.cloud-region.cloud-provider.cloud.qdrant.io",
apiKey: "<paste-your-api-key-here>",
});
use qdrant_client::Qdrant;
let client = Qdrant::from_url("https://xyz-example.cloud-region.cloud-provider.cloud.qdrant.io:6334")
.api_key("<paste-your-api-key-here>")
.build()?;
import io.qdrant.client.QdrantClient;
import io.qdrant.client.QdrantGrpcClient;
QdrantClient client = new QdrantClient(
QdrantGrpcClient.newBuilder("xyz-example.cloud-region.cloud-provider.cloud.qdrant.io", 6334, true)
.withApiKey("<paste-your-api-key-here>")
.build());
using Qdrant.Client;
var client = new QdrantClient(
host: "xyz-example.cloud-region.cloud-provider.cloud.qdrant.io",
https: true,
apiKey: "<paste-your-api-key-here>",
);
import "github.com/qdrant/go-client/qdrant"
client, err := qdrant.NewClient(&qdrant.Config{
Host: "xyz-example.cloud-region.cloud-provider.cloud.qdrant.io",
Port: 6334,
APIKey: "<paste-your-api-key-here>",
UseTLS: true,
})