리소스 & 환경변수

​

리소스 (Resources)

​

리소스란 무엇인가?

참고 비유하자면: 리소스는 회사 출입카드와 같습니다. 직원이 직접 열쇠를 복제하는 것이 아니라, 출입카드에 “어떤 구역에 접근할 수 있는가”를 등록하는 것입니다. 출입카드 자체에는 열쇠 정보가 없고, 카드를 대면 시스템이 권한을 확인하고 문을 열어줍니다.

​

지원 리소스 유형

​

리소스 추가 방법 (UI)

1. 앱 생성/편집 시 Configure 단계로 이동
2. App resources 섹션에서 + Add resource 클릭
3. 리소스 유형 선택 (예: SQL Warehouse)
4. 앱 서비스 프린시펄에 적절한 권한 설정
5. 리소스 키 지정 (app.yaml에서 참조할 이름)

참고 리소스 추가 시 주의: 리소스를 추가하면 두 가지가 동시에 설정됩니다. 첫째, app.yaml에 리소스 선언이 추가됩니다. 둘째, 앱의 서비스 프린시펄에 해당 리소스에 대한 기본 권한이 부여됩니다. 하지만 UC 테이블에 대한 SELECT 권한처럼 세부 권한은 여전히 수동으로 부여해야 합니다.

​

리소스 유형별 상세 가이드

​

SQL Warehouse: 데이터 조회의 핵심

​

SQL Warehouse 연결 예시

command: ['streamlit', 'run', 'app.py']
env:
  - name: DATABRICKS_WAREHOUSE_ID
    valueFrom: sql_warehouse

import os
from databricks import sql
from databricks.sdk.core import Config

cfg = Config()
warehouse_id = os.getenv("DATABRICKS_WAREHOUSE_ID")
http_path = f"/sql/1.0/warehouses/{warehouse_id}"

conn = sql.connect(
    server_hostname=cfg.host.replace("https://", ""),
    http_path=http_path,
    credentials_provider=lambda: cfg.authenticate,
)

​

Serving Endpoint: AI/ML 모델 호출

​

Serving Endpoint 연결 예시

command: ['python', 'app.py']
env:
  - name: SERVING_ENDPOINT
    valueFrom: serving_endpoint

import os
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
endpoint_name = os.getenv("SERVING_ENDPOINT")

response = w.serving_endpoints.query(
    name=endpoint_name,
    dataframe_records=[{"prompt": "Hello, world!"}]
)

​

Secret: 외부 API 키 관리

​

Secret 사용 예시

env:
  - name: EXTERNAL_API_KEY
    valueFrom: my_api_secret

import os

api_key = os.getenv("EXTERNAL_API_KEY")
# api_key를 사용하여 외부 API 호출

주의 Secret Scope 설정: Secret을 앱에서 사용하려면 먼저 Databricks CLI로 Secret Scope를 생성하고 값을 저장해야 합니다. databricks secrets create-scope --scope my-scope 후 databricks secrets put-secret --scope my-scope --key my-key. 앱의 SP에 해당 Scope에 대한 READ 권한을 부여해야 합니다.

​

databricks_host: 워크스페이스 URL 동적 참조

​

권한 모델

팁 최소 권한 원칙: 앱에 필요한 최소한의 권한만 부여하세요. 예를 들어, 쿼리만 실행한다면 SQL Warehouse에 CAN USE만 부여합니다.

주의 흔한 실수: Warehouse에 CAN USE를 부여했지만 UC 테이블에 SELECT를 부여하지 않는 경우가 많습니다. Warehouse 접근 권한과 테이블 접근 권한은 별도로 관리 됩니다. 앱의 SP에 GRANT SELECT ON TABLE catalog.schema.table TO <sp-application-id>도 실행해야 합니다.

​

환경 변수

​

자동 주입 환경 변수

참고 DATABRICKS_APP_PORT의 중요성: 이 환경변수를 무시하면 앱이 시작되지만 외부에서 접속할 수 없습니다. Databricks의 리버스 프록시가 이 포트로 트래픽을 전달하기 때문입니다. FastAPI, Flask 등에서 반드시 이 포트를 사용하세요. Streamlit과 Gradio는 자동으로 처리합니다.

​

환경변수 vs 리소스: 언제 무엇을 쓰는가

참고 판단 기준 요약: “이 값이 환경(dev/staging/prod)에 따라 바뀔 수 있는가?”가 기준입니다. 바뀔 수 있다면 valueFrom으로 리소스 참조를 사용하고, 바뀌지 않는 단순 설정이라면 value로 직접 지정합니다. 민감 정보는 무조건 valueFrom + Secret 리소스입니다.

​

커스텀 환경 변수 정의

env:
  # 정적 값 (하드코딩 허용: 피처 토글, 리전, 타임존 등)
  - name: FEATURE_FLAG_NEW_UI
    value: 'true'
  - name: DEFAULT_TIMEZONE
    value: 'Asia/Seoul'

  # 리소스 참조 (시크릿, 웨어하우스 등)
  - name: WAREHOUSE_ID
    valueFrom: sql_warehouse
  - name: SECRET_KEY
    valueFrom: secret

​

코드에서 접근

import os
warehouse_id = os.getenv("WAREHOUSE_ID")

const warehouseId = process.env.WAREHOUSE_ID;

주의 app.yaml 외부에서 정의한 환경 변수는 앱에서 사용할 수 없습니다. 유일한 예외는 DATABRICKS_APP_PORT입니다.

참고 실무 팁: 환경변수가 올바르게 주입되었는지 확인하려면, 앱 시작 시 모든 필수 환경변수의 존재 여부를 검증하는 코드를 추가하세요. 이렇게 하면 리소스 이름 오타로 인한 런타임 에러를 앱 시작 시점에 즉시 발견할 수 있습니다.