Databricks Apps를 배포할 때 인증은 어떻게 설계해야 할까

이 글은 Databricks 기본 개념을 안다는 전제에서 Databricks Apps의 운영 패턴에 집중한다. 앱을 한 번 띄우는 것보다 중요한 문제는, 누구의 권한으로 어떤 데이터에 접근하게 만들 것인가를 배포 시점에 결정하는 일이다.

개발 단계에서는 개인 PAT로 빠르게 검증할 수 있다. 하지만 운영 환경으로 넘어가면 개인 계정에 묶인 인증은 오래 버티지 못한다. 퇴사, 권한 변경, 토큰 만료, 감사 추적, 비밀정보 회전 같은 운영 문제들이 한꺼번에 따라오기 때문이다.

왜 개인 PAT로 운영하면 안 되는가

PAT는 실험과 로컬 검증에는 편리하다. 문제는 운영 환경에서는 인증 주체가 사람에게 묶인다는 점이다.

개인 PAT로 앱을 운영하면 다음 같은 문제가 생긴다.

• 앱 가용성이 특정 개인 계정 상태에 의존한다
• 누가 어떤 권한으로 데이터에 접근했는지 추적이 흐려진다
• 권한 재검토나 인사 이동이 있을 때 앱도 함께 흔들린다
• 시크릿 회전과 폐기 절차가 사람 중심으로 흘러간다

Databricks Apps에서는 어떤 인증 주체를 써야 하는가

Databricks Apps는 앱이 Databricks 리소스에 접근할 때 사용할 별도 권한 경계를 고려해야 한다. 이때 핵심 개념은 사람이 아니라 애플리케이션을 대표하는 주체를 두는 것이다.

Databricks 공식 문서 기준으로는 앱을 만들면 전용 Service Principal이 할당되고, 런타임에는 앱이 Databricks 리소스에 접근할 수 있도록 관련 OAuth 환경 변수가 주입된다. 그래서 운영 설계의 핵심은 “사람 토큰을 넣을까?”가 아니라 “앱 전용 주체에 어떤 권한을 줄까?”에 가깝다.

이 구조가 중요한 이유는 두 가지다.

1. 앱 권한을 사용자 권한과 분리할 수 있다.
2. 최소 권한 원칙을 앱 단위로 적용할 수 있다.

예를 들어 어떤 앱이 특정 카탈로그의 몇 개 테이블만 읽으면 된다면, 그 범위만 허용한 앱 전용 주체를 두는 편이 훨씬 안전하다. 사용자가 관리자라고 해서 앱도 관리자처럼 움직이면 안 된다.

실무에서 이 주체는 Databricks UI에서 앱의 Authorization 탭이나 Unity Catalog Permissions 화면을 통해 확인하게 된다. 보통은 앱 전용 principal이 자동 생성된 이름으로 보이고, 경우에 따라 app-...로 시작하는 principal 이름이 표시되기도 한다. 결국 운영자가 하는 일은 “앱에 권한을 준다”기보다, 그 앱에 연결된 service principal에 권한을 준다에 더 가깝다.

App authorization과 User authorization은 어떻게 다를까

Databricks Apps에서는 인증 모델도 한 가지가 아니다. 실무적으로는 아래 두 가지를 구분해서 생각해야 한다.

대부분의 운영 글이 놓치기 쉬운 부분이 이 구분이다. 공용 대시보드나 백엔드 처리처럼 앱 자체가 고정된 권한으로 움직여야 하는 경우는 App authorization이 더 자연스럽다. 반면 사용자별 데이터 권한이 그대로 반영되어야 하는 앱이라면 User authorization을 검토해야 한다.

시크릿은 어디에 저장해야 하는가

Databricks 내부 인증에 필요한 값은 앱 런타임에서 자동 주입되는 구조를 활용할 수 있다. 예를 들어 앱 전용 service principal의 client ID와 secret은 DATABRICKS_CLIENT_ID, DATABRICKS_CLIENT_SECRET 같은 환경 변수로 주입된다. 반면 외부 API 키, 데이터베이스 비밀번호, 추가 토큰처럼 Databricks 바깥 자격 증명은 별도 secret manager 전략이 필요하다. 여기서 중요한 것은 저장소 이름보다도 배포 파이프라인과 런타임이 어떤 방식으로 시크릿을 주고받는가다.

대표적인 선택지는 아래처럼 볼 수 있다.

저장소를 고를 때는 아래 질문이 더 중요하다.

• 누가 시크릿을 생성하고 회전하는가
• 배포 파이프라인이 어떤 권한으로 시크릿을 읽는가
• 앱 런타임이 직접 시크릿을 조회하는가, 아니면 배포 시 주입받는가
• 감사 로그와 접근 통제가 어디에서 남는가

배포 시 런타임에 시크릿을 어떻게 주입할까

운영 설계에서 가장 실전적인 부분은 시크릿 주입 경로다. 보통은 “시크릿 저장소에 넣어 둔다”에서 끝나기 쉬운데, 실제 장애와 보안 문제는 그 다음 단계에서 많이 생긴다. Databricks 내부 인증은 런타임 환경 변수 주입을 활용하고, 외부 시스템용 시크릿만 별도 저장소에서 가져오는 식으로 책임을 나누면 설계가 분명해진다.

대표적인 패턴은 크게 두 가지다.

1. 배포 시 주입 배포 파이프라인이 secret manager에서 값을 읽어 앱 환경 변수나 설정으로 넣는다.

2. 런타임 조회 앱이 시작할 때 또는 필요한 순간에 secret manager에서 직접 값을 가져온다.

각 접근에는 trade-off가 있다.

운영 환경에서는 어느 쪽이든 아래 원칙을 지키는 편이 안전하다.

• 시크릿 값을 코드나 이미지에 넣지 않는다
• 로그에 시크릿이나 토큰 일부가 찍히지 않게 한다
• 접근 실패 시 재시도와 실패 메시지를 분리한다
• 시크릿 회전 주기와 앱 재시작 전략을 같이 정의한다

배포 설정의 감각을 잡기 위한 가장 단순한 app.yaml 예시는 아래처럼 볼 수 있다.

command:
  - python
  - app.py
 
env:
  - name: APP_ENV
    value: production
  - name: EXTERNAL_API_BASE_URL
    value: https://api.example.com

이 예시는 구조를 이해하기 위한 최소 템플릿이다. 실제 운영에서는 여기에 패키지 의존성(requirements.txt), 외부 시크릿 주입 방식, 시작 명령, 앱이 접근할 리소스 권한까지 함께 맞춰야 한다. Databricks 내부 리소스 접근용 값인 DATABRICKS_CLIENT_ID, DATABRICKS_CLIENT_SECRET 같은 항목은 직접 넣는 값이 아니라, 앱 런타임에서 자동 주입되는 값으로 이해하는 편이 맞다.

중요한 점은 환경 변수가 자동으로 주입된다고 해서 앱이 자동으로 Databricks 리소스를 호출하는 것은 아니라는 점이다. 실제로 SQL warehouse를 조회하거나 Apps, Jobs, Unity Catalog 리소스를 읽으려면 애플리케이션 코드가 Databricks SDK나 드라이버를 통해 그 값을 사용해야 한다. 다만 Databricks SDK는 표준 환경 변수 이름(DATABRICKS_HOST, DATABRICKS_CLIENT_ID, DATABRICKS_CLIENT_SECRET)을 읽을 수 있어서, 코드에서는 WorkspaceClient()처럼 비교적 단순한 형태로 시작할 수 있다.

같은 문제를 푸는 방식은 크게 두 가지로 나눌 수 있다.

from databricks.sdk import WorkspaceClient
 
w = WorkspaceClient()
current_user = w.current_user.me()
 
print(current_user.user_name)

SDK를 쓰지 않는다면 바닐라 코드에서 환경 변수를 읽고 OAuth client credentials 흐름으로 토큰을 받아 직접 호출할 수도 있다.

import os
import requests
 
host = os.environ["DATABRICKS_HOST"]
client_id = os.environ["DATABRICKS_CLIENT_ID"]
client_secret = os.environ["DATABRICKS_CLIENT_SECRET"]
 
token_response = requests.post(
    f"{host}/oidc/v1/token",
    data={
        "grant_type": "client_credentials",
        "scope": "all-apis",
    },
    auth=(client_id, client_secret),
    timeout=30,
)
token_response.raise_for_status()
access_token = token_response.json()["access_token"]
 
api_response = requests.get(
    f"{host}/api/2.0/preview/scim/v2/Me",
    headers={"Authorization": f"Bearer {access_token}"},
    timeout=30,
)
api_response.raise_for_status()
 
print(api_response.json())

즉, 인증 정보 주입은 Databricks가 해 주지만, 그 인증 정보를 실제 요청에 연결하는 것은 앱 코드나 SDK 호출이 맡는다.

Databricks CLI는 개발 루프를 크게 줄여 준다

로컬에서 Databricks Apps를 개발할 때 가장 편했던 도구 중 하나는 Databricks CLI다. 특히 워크스페이스 폴더와 로컬 파일을 오가며 빠르게 수정하고, 다시 Databricks Apps에 배포하는 흐름이 단순해진다.

기본 준비는 아래 정도면 충분하다.

• Python 실행 환경 준비
• Databricks CLI 설치
• databricks auth login으로 워크스페이스 인증

예를 들어 Python 환경에서는 이렇게 시작할 수 있다.

python -m venv .venv
source .venv/bin/activate
pip install databricks-cli
 
databricks auth login --host https://<workspace-host>

개발 루프의 감각은 아래 예시가 가장 잘 보여 준다.

# 워크스페이스 파일을 로컬로 가져오기
databricks workspace export-dir /Workspace/Users/<user>/my-app .
 
# 이후 수정 사항을 계속 워크스페이스로 동기화
databricks sync --watch . /Workspace/Users/<user>/my-app
 
# 로컬에서 앱 실행
python app.py
# 또는 Streamlit 앱이면
streamlit run app.py
 
# Databricks Apps로 배포
databricks apps deploy my-app --source-code-path /Workspace/Users/<user>/my-app

이 흐름이 유용한 이유는 세 가지다.

• 로컬 편집기에서 빠르게 수정하고 즉시 테스트할 수 있다
• sync --watch로 워크스페이스와 파일 상태를 계속 맞출 수 있다
• 마지막 배포 명령까지 하나의 개발 루프로 이어져 반복 작업이 줄어든다

특히 앱 초기에 requirements.txt, app.yaml, 시작 명령, UI 코드까지 자주 바뀌는 시점에는 CLI 기반 개발 루프가 체감상 꽤 편하다.

Unity Catalog 권한은 어떻게 최소 권한으로 설계해야 할까

Databricks Apps의 인증을 이야기할 때 자주 빠지는 부분이 권한 설계다. 인증 주체를 잘 만들었더라도 Unity Catalog 권한이 넓게 열려 있으면 운영 리스크는 그대로 남는다.

앱이 데이터를 읽기만 한다면 보통 아래 순서로 필요한 권한을 점검해야 한다.

1. USE CATALOG
2. USE SCHEMA
3. 테이블 또는 뷰에 대한 SELECT

데이터를 쓰는 앱이라면 여기에 생성이나 수정 관련 privilege가 추가된다. 중요한 점은 하위 오브젝트 권한만 줘서는 동작하지 않을 수 있다는 것이다. 상위 카탈로그와 스키마 접근 권한이 빠지면 “테이블 권한은 있는데 접근이 안 되는” 상태가 생긴다.

이 권한은 SQL GRANT로 줄 수도 있고, Catalog Explorer에서 catalog / schema / table의 Permissions 탭으로 들어가 principal 기준으로 줄 수도 있다. 운영 현장에서는 후자 방식으로 현재 어떤 principal에 어떤 권한이 붙어 있는지 확인하는 경우가 많다. 여기서 Databricks App에 연결된 app-... principal을 찾아 USE CATALOG, USE SCHEMA, SELECT 같은 권한을 부여하는 식이다.

예를 들어 읽기 전용 앱이라면 이런 식의 사고방식이 필요하다.

GRANT USE CATALOG ON CATALOG analytics TO `app-principal`;
GRANT USE SCHEMA ON SCHEMA analytics.audit TO `app-principal`;
GRANT SELECT ON VIEW analytics.audit.daily_summary TO `app-principal`;

핵심은 앱이 필요한 데이터 경계만 통과하게 만드는 것이다. 앱 하나에 광범위한 카탈로그 접근을 열어 두면, 초기 개발은 편할 수 있어도 운영 감사와 권한 리뷰에서 빠르게 부담이 커진다.

UI 관점으로 바꾸면 아래처럼 이해하면 된다.

• catalog Permissions에서 앱 principal에 USE CATALOG를 준다
• schema Permissions에서 같은 principal에 USE SCHEMA를 준다
• table 또는 view Permissions에서 SELECT 또는 MODIFY를 준다

즉, 앱이 실제로는 자동 생성된 principal 이름으로 보이더라도, 권한 모델은 일반 사용자나 다른 service principal과 동일한 Unity Catalog 규칙을 따른다.

Databricks UI 기준으로는 이 흐름이 더 직관적이다.

이 과정을 한 번 경험하면 “앱에 권한을 준다”는 표현이 실제로는 “앱의 service principal에 Unity Catalog grant를 준다”는 뜻이라는 점이 분명해진다.

배포할 때 자주 나는 실수

운영 환경으로 옮길 때 반복해서 나타나는 실수는 대체로 비슷하다.

Databricks Apps를 실제로 배포할 때는 패키지와 설정 문제도 자주 만난다. 실무에서 자주 보게 되는 패턴은 아래처럼 정리할 수 있다.

이 표가 중요한 이유는, Databricks Apps의 배포 오류가 항상 인증 문제만은 아니기 때문이다. 어떤 에러는 패키지 설치 단계에서 발생하고, 어떤 에러는 런타임 환경 변수 누락 때문이며, 또 어떤 에러는 앱 principal에 리소스 권한이 빠져서 발생한다. 그래서 문제를 볼 때 “권한 문제인지, 패키지 문제인지, 실행 설정 문제인지”를 먼저 나누는 편이 빠르다.

권한 문제를 만났을 때는 아래 순서로 보면 빠르다.

1. 앱 Authorization 탭에서 어떤 principal이 생성되었는지 확인한다
2. 그 principal이 Unity Catalog Permissions 화면에 실제로 검색되는지 본다
3. catalog에 USE CATALOG, schema에 USE SCHEMA, table/view에 SELECT 또는 MODIFY가 있는지 확인한다
4. 그래도 안 되면 App authorization과 User authorization 중 어떤 모델로 실행 중인지 다시 점검한다

운영 체크리스트

• 앱 인증 주체가 개인 계정이 아니라 앱 전용 주체인지 확인한다
• secret manager와 배포 파이프라인의 책임 경계를 문서화한다
• 시크릿 조회 실패 시 앱 동작 방식을 정한다
• Unity Catalog에서 카탈로그, 스키마, 오브젝트 권한이 모두 최소 범위인지 점검한다
• 토큰과 시크릿 회전 주기를 운영 캘린더에 반영한다
• 감사 로그와 접근 이력 확인 경로를 준비한다

운영 가능한 인증 구조는 따로 설계해야 한다

Databricks Apps를 운영 환경에 올릴 때 중요한 것은 앱을 띄우는 방법보다, 앱이 어떤 신뢰 경계 안에서 움직이는지 결정하는 일이다. Service Principal, secret manager, Unity Catalog 권한은 따로따로 고르는 옵션이 아니라 하나의 운영 모델로 함께 설계해야 한다.

개발 단계에서는 “일단 붙여 보자”가 가능하지만, 운영 단계에서는 그 접근이 오래가지 못한다. 인증 주체를 사람에게서 분리하고, 시크릿 저장과 주입 경로를 명확히 하고, 카탈로그 권한을 최소 범위로 설계해야 앱이 안정적으로 살아남는다.

앞선 글에서 Databricks의 저장, 거버넌스, 처리 계층을 큰 그림으로 봤다면, 이 글의 포인트는 그 위에 올라가는 앱이 어떤 방식으로 플랫폼 자원에 접근해야 하는지를 운영 관점에서 보는 데 있다.

참고 자료

• Databricks Apps 
• Configure authorization in a Databricks app 
• Best practices for Databricks Apps 
• What is Unity Catalog?