Unity 카탈로그의 비밀

Important

이 페이지에서는 Unity Catalog에서 보안 비밀을 생성하고, 읽고, 제어하고, 관리하는 방법을 설명합니다. Unity 카탈로그 비밀은 암호, 토큰 또는 API 키와 같은 중요한 자료를 저장하는 보안 개체입니다. 노트북과 작업은 코드에 값을 노출하지 않고도 비밀 정보를 참조할 수 있습니다.

Unity 카탈로그 비밀은 3단계 네임스페이스(catalog.schema.secret)를 사용하며 메타스토어에 연결된 작업 영역에서 사용할 수 있습니다. Unity 카탈로그 권한은 이를 제어합니다. 이렇게 하면 다른 데이터 자산에 사용하는 것과 동일한 액세스 모델 및 감사를 비밀에 적용할 수 있습니다.

메모

Unity 카탈로그 비밀은 비밀 범위로 구성된 작업 영역 수준 Azure Databricks 비밀과 다릅니다. Unity 카탈로그 권한으로 비밀을 제어하고 3단계 네임스페이스를 사용하여 참조하려는 경우 Unity 카탈로그 비밀을 사용합니다.

Unity 카탈로그 비밀 작동 방식

Unity 카탈로그 암호는 스키마 아래의 보안 개체이며 정규화된 이름을 catalog.schema.secret사용합니다. 다른 Unity 카탈로그 보안 개체와 마찬가지로 비밀은 카탈로그 및 스키마의 권한 상속을 지원합니다. 보안 개체 및 상속에 대한 자세한 내용은 Unity 카탈로그 보안 개체 참조를 참조하세요.

다음과 같은 방법으로 Unity 카탈로그 비밀을 사용할 수 있습니다.

코드에서 값을 검색합니다. READ SECRET 액세스 권한이 있으면 사용자는 dbutils 또는 Unity Catalog REST API를 사용해 노트북 및 작업에서 비밀 값을 검색할 수 있습니다. 그런 다음 이를 사용하여 외부 시스템으로 인증하거나 데이터를 암호화 및 암호 해독할 수 있습니다.
Unity 카탈로그 개체의 값을 참조합니다. Unity 카탈로그 연결과 같은 Unity 카탈로그 개체는 이름으로 비밀을 참조할 수 있으므로 통합에서 사용자에게 값에 대한 액세스 권한을 부여하지 않고 비밀을 사용할 수 있습니다. 개체에 따라 비밀을 참조하려면 REFERENCE SECRET 또는 READ SECRET 중 하나가 필요합니다.

Azure Databricks 암호화된 Unity 카탈로그 비밀 값을 저장하고 비밀 수정을 적용하여 출력 및 로그의 실수로 인한 노출을 줄입니다. 비밀을 회전하려면 UI 또는 Unity 카탈로그 REST API를 사용하여 주기적으로 해당 값을 업데이트합니다.

Unity 카탈로그 비밀에 대한 권한

다음 권한은 비밀을 제어합니다. 카탈로그, 스키마 또는 개별 비밀 수준에서 부여할 수 있으며 Unity 카탈로그 권한 상속을 따릅니다.

특권	설명
`CREATE SECRET`	사용자가 스키마에서 비밀을 만들 수 있습니다. 카탈로그 또는 스키마 수준에서 부여됩니다.
`READ SECRET`	사용자가 비밀 값을 검색할 수 있습니다.
`WRITE SECRET`	사용자가 비밀 값을 업데이트할 수 있습니다.
`REFERENCE SECRET`	사용자가 값에 액세스하지 않고 Unity 카탈로그 연결에서 비밀을 참조할 수 있습니다.

스키마에 비밀 정보를 생성하려면 사용자에게 USE CATALOG 권한이 있어야 하며, 해당 스키마를 소유하고 있거나 해당 스키마에 대해 CREATE SECRET 및 USE SCHEMA 권한이 있어야 합니다. 권한을 부여하는 방법을 알아보려면 Unity 카탈로그에서 권한 관리를 참조하세요.

시작하기 전 주의 사항:

Unity 카탈로그 비밀을 사용하려면 다음 요구 사항을 충족해야 합니다.

작업 영역이 Unity 카탈로그에 대해 사용 가능하도록 설정되어야 합니다. 소개는 Unity 카탈로그란?을 참조하세요.
Unity Catalog가 활성화된 컴퓨팅에서 시크릿에 액세스해야 합니다. Azure Databricks 다음 중 하나를 권장합니다.
- 환경 버전 4 이상을 사용하는 서버리스 작업 및 노트북
- Databricks Runtime 17.3 LTS 이상을 실행하는 표준 액세스 모드 의 클래식 컴퓨팅입니다.
dbutils로 보안 비밀을 가져오려면 컴퓨팅 리소스는 Databricks Runtime 17.3 LTS 이상 또는 서버리스 환경 버전 4 이상에서 실행되어야 합니다.

비밀 만들기

비밀을 생성하려면 USE CATALOG 권한이 있고 스키마를 소유하고 있거나, 스키마에 대한 CREATE SECRET 및 USE SCHEMA 권한이 있어야 합니다. Unity 카탈로그 비밀에 대한 권한을 참조하세요.

카탈로그 탐색기

Azure Databricks 작업 영역에서 카탈로그를 클릭하여 카탈로그 탐색기를 엽니다.
비밀을 만들 스키마로 이동합니다.
비밀 만들기>를 클릭합니다.
이름과값을 입력합니다. 필요에 따라 메모 와 만료 날짜를 추가합니다. 비밀이 만료되면 카탈로그 탐색기에 경고가 표시됩니다.
만들기를 클릭합니다.

REST API

엔드포인트를 사용하여 다음 cURL 명령을 실행합니다 /api/2.1/unity-catalog/secrets .

curl -X POST \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "catalog_name": "main",
    "schema_name": "default",
    "name": "example_secret",
    "value": "your_secret_value",
    "comment": "your secret description"
  }' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets"

비밀 읽기

비밀 값을 읽으려면 해당 비밀이나 상위 카탈로그 또는 스키마에 대해 READ SECRET 권한이 있어야 합니다.

비밀 관리 유틸리티(dbutils.secrets)

Azure Databricks는 비밀 값 마스킹이 적용되므로 비밀을 읽을 때 dbutils를 사용하는 것을 권장합니다. 이 옵션을 사용하려면 Databricks Runtime 17.3 LTS 이상 또는 서버리스 환경 버전 4 이상이 필요합니다.

# Read a specific secret
my_secret = dbutils.secrets.get(catalog="main", schema="default", key="example_secret")

자세한 내용은 비밀 유틸리티(dbutils.secrets)를 참조하세요.

REST API

Warning

Unity 카탈로그 REST API를 사용하여 검색된 비밀 값은 비밀 수정의 대상이 아니지만 감사 로그에 액세스가 기록됩니다. Azure Databricks 대신 권장합니다dbutils.

값을 반환하려면 응답에서 include_value=true 필드를 설정하고 effective_value 읽습니다.

curl -G \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  --data-urlencode "include_value=true" \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.default.example_secret"

비밀에 대한 권한 관리

카탈로그 또는 스키마 수준에서 권한을 부여 CREATE SECRET 하여 비밀을 만들 수 있는 사용자를 제어합니다. 카탈로그, 스키마 또는 개별 시크릿 수준에서 액세스를 제어하기 위해 READ SECRET, WRITE SECRET 또는 REFERENCE SECRET를 부여합니다. 권한 상속이 적용됩니다. 권한 부여 및 취소에 대한 자세한 내용은 Unity 카탈로그에서 권한 관리를 참조하세요.

비밀을 만들 수 있는 권한 부여

카탈로그 탐색기

카탈로그 탐색기에서 스키마로 이동합니다.
권한 탭을 클릭합니다.
Grant를 클릭합니다.
액세스 권한을 부여할 보안 주체를 선택한 다음, CREATE SECRET을 선택합니다.

보안 주체에 USE SCHEMA이(가) 없으면 이를 부여하라는 경고 메시지가 표시됩니다. USE SCHEMA 는 스키마에서 비밀을 만드는 데도 필요합니다.
확인을 클릭합니다.

SQL

GRANT CREATE SECRET, USE SCHEMA ON SCHEMA main.default TO `user@example.com`;

REST API

엔드포인트를 사용하여 다음 cURL 명령을 실행합니다 /api/2.1/unity-catalog/permissions/schema/{schema_name} .

curl -X PATCH \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "changes": [{
      "principal": "user@example.com",
      "add": ["CREATE_SECRET", "READ_SECRET", "REFERENCE_SECRET", "WRITE_SECRET"]
    }]
  }' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/permissions/schema/{schema_name}"

비밀에 대한 액세스 권한 부여

카탈로그 탐색기

카탈로그 탐색기에서 보안 암호로 이동한 후 해당 항목을 클릭합니다.
권한 탭을 클릭합니다.
Grant를 클릭합니다.
보안 주체 및 부여할 권한을 선택한 다음 확인을 클릭합니다.

SQL

GRANT READ SECRET ON SECRET main.default.example_secret TO `user@example.com`;

REST API

엔드포인트를 사용하여 다음 cURL 명령을 실행합니다 /api/2.1/unity-catalog/permissions/secret/{catalog.schema.secret} .

curl -X PATCH \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "changes": [{
      "principal": "user@example.com",
      "add": ["READ_SECRET", "REFERENCE_SECRET", "WRITE_SECRET"]
    }]
  }' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/permissions/secret/{catalog.schema.secret}"

비밀 나열, 업데이트 및 삭제

비밀 목록 작성

카탈로그 탐색기

카탈로그 탐색기에서 스키마로 이동합니다.
개요 창에서 비밀을 클릭하여 스키마의 모든 비밀을 확인합니다.

비밀 관리 유틸리티(dbutils.secrets)

# List all secrets in a schema
all_secrets = dbutils.secrets.list(catalog="main", schema="default")

REST API

목록 요청은 결과 수를 제어하는 데 사용합니다 page_size .

curl -G \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  --data-urlencode "catalog_name=main" \
  --data-urlencode "schema_name=default" \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets"

비밀 업데이트

비밀 값을 업데이트하려면 해당 비밀에 대해 WRITE SECRET 권한이 있어야 합니다.

카탈로그 탐색기

카탈로그 탐색기에서 스키마로 이동하고 개요 창에서 비밀을 클릭합니다.
업데이트하려면 시크릿을 클릭하세요.
오른쪽 위 모서리에서 케밥 메뉴(세로 점)를 클릭하고 편집을 선택합니다.
새 값 또는 만료 날짜를 입력한 다음 확인을 클릭합니다.

REST API

업데이트 요청에는 매개 변수가 update_mask 필요합니다. 둘 다 update_mask 에 포함된 필드와 요청 본문만 업데이트됩니다.

curl -X PATCH \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"value": "new_secret_value"}' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.default.example_secret?update_mask=*"

비밀 삭제

카탈로그 탐색기

카탈로그 탐색기에서 스키마로 이동하고 개요 창에서 비밀을 클릭합니다.
삭제할 비밀을 클릭합니다.
오른쪽 위 모서리에서 케밥 메뉴(세로 점)를 클릭하고 삭제를 선택합니다.
비밀의 전체 이름을 입력한 다음 삭제를 클릭합니다.

REST API

curl -X DELETE \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.default.example_secret"

Unity 카탈로그 시크릿에 대한 감사 이벤트

시스템 테이블은 system.access.audit Unity 카탈로그 비밀과 관련된 이벤트를 기록합니다. 예를 들어 특정 날짜에 사용자에 대한 모든 비밀 이벤트를 보려면 다음 쿼리를 실행합니다.

SELECT * FROM system.access.audit
WHERE
  user_identity.email = "user@example.com"
  AND event_date = "2026-02-20"
  AND service_name = "unityCatalog"
  AND action_name LIKE "%Secret%";

감사 로그에 대한 자세한 내용은 감사 로그 시스템 테이블 참조를 참조하세요.

고객 관리형 키를 사용하여 비밀 값 암호화

기본적으로 Azure Databricks Databricks 관리형 키를 사용하여 비밀 값을 암호화합니다. 대신 CMK(고객 관리형 키)를 사용할 수 있습니다. CMK 암호화 관리 카탈로그 기능을 사용하도록 설정하고 계정에 CMK 구성을 연결하는 경우 Azure Databricks CMK를 사용하여 비밀 값을 암호화합니다. 자세한 내용은 Unity 카탈로그에 대한 고객 관리형 키를 참조하세요.

Limitations

Unity 카탈로그 비밀에는 다음과 같은 제한 사항이 있습니다.

SQL 웨어하우스가 없습니다. Unity 카탈로그 비밀은 SQL 웨어하우스에서 지원되지 않습니다. Unity Catalog가 활성화된 컴퓨팅 또는 서버리스에서는 Databricks Runtime 17.3 LTS 이상이 필요합니다.
전역 검색 기능이 없습니다. Unity 카탈로그 비밀은 전역 검색에 표시되지 않습니다.
BROWSE 권한 지원이 없습니다.카탈로그에 대한 BROWSE는 Unity Catalog 시크릿에는 적용되지 않습니다. 비밀을 검색 가능하게 하려면 개별 비밀 또는 해당 스키마에 대해 READ SECRET 또는 REFERENCE SECRET 권한을 부여하세요.
init 스크립트가 없습니다. 전역 또는 클러스터 초기화 스크립트에서는 Unity 카탈로그 비밀을 사용할 수 없습니다. Azure Databricks에서는 가능하면 초기화 스크립트 대신 전용 기능을 사용할 것을 권장합니다.
정보 스키마가 없습니다. 비밀에 대한 정보 스키마 테이블은 아직 사용할 수 없습니다. 검색을 위해 카탈로그 탐색기 또는 REST API를 사용합니다.
dbutils 런타임 범위. dbutils 검색 기능은 Databricks Runtime 기반 노트북 및 작업에서 지원됩니다. 원격 개발 또는 컴파일된 JAR 실행 모드와 같은 비 Databricks 런타임 컨텍스트는 지원되지 않습니다.
OAuth API 범위입니다. Unity 카탈로그 비밀 API는 OAuth API 범위에서 unity-catalog 만 액세스할 수 있습니다. 작업 영역 수준의 Azure Databricks 비밀에만 secrets API 스코프를 사용하세요.
할당량 한도입니다. 각 스키마당 최대 100개의 시크릿, 메타스토어당 최대 1,000개의 시크릿.

피드백

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

Last updated on 2026-07-17

Unity 카탈로그의 비밀

Unity 카탈로그 비밀 작동 방식

Unity 카탈로그 비밀에 대한 권한

시작하기 전 주의 사항:

비밀 만들기

카탈로그 탐색기

REST API

비밀 읽기

비밀 관리 유틸리티(dbutils.secrets)

REST API

비밀에 대한 권한 관리

비밀을 만들 수 있는 권한 부여

카탈로그 탐색기

SQL

REST API

비밀에 대한 액세스 권한 부여

카탈로그 탐색기

SQL

REST API

비밀 나열, 업데이트 및 삭제

비밀 목록 작성

카탈로그 탐색기

비밀 관리 유틸리티(dbutils.secrets)

REST API

비밀 업데이트

카탈로그 탐색기

REST API

비밀 삭제

카탈로그 탐색기

REST API

Unity 카탈로그 시크릿에 대한 감사 이벤트

고객 관리형 키를 사용하여 비밀 값 암호화

Limitations

피드백

추가 리소스