이 페이지에서는 버전 제어, 환경 관리, 개발자 도구 및 관리되는 배포를 포함하여 데이터 엔지니어링 및 개발 수명 주기에 대한 모범 사례를 제공합니다.
소스 제어
모든 파일 버전 관리
선언적 자동화는 버전 제어에 없는 경우 존재하지 않는다는 개념을 기반으로 합니다. 따라서 Databricks는 다음을 포함하여 거의 모든 파일을 버전 제어하는 것이 좋습니다.
- 모든 노트북과 원본 파일 (
.py,.sql) - 번들 구성 파일(
databricks.yml및 환경별 YAML 재정의)
그러나 다음을 커밋하지 마세요:
- 빌드 아티팩트(예:
.jar또는.whl파일) 대신 CI 중에 컴파일된 이진 파일을 Unity 카탈로그 볼륨에 업로드합니다. JAR 업로드를 참조하세요. - 토큰 또는 자격 증명. 클라우드 비밀 관리자(예: AWS 비밀 관리자 또는 Azure Key Vault)에서 지원되는 작업 영역 수준 비밀 관리를 사용하고 값을 Databricks 비밀 범위로 동기화합니다. 비밀 관리를 참조하세요.
- PII를 사용하는 로컬 데이터 예제 및 파일 제외하려면
.gitignore를 사용하세요.
단일 리포지토리
Databricks는 모든 코드(소스 코드 및 구성 파일)에 단일 리포지토리를 사용하는 것이 좋습니다. 이 리포지토리를 사용하면 공동 작업 및 사용자와 AI 둘 다에 대한 코드 및 모범 사례 공유가 더 쉬워집니다. 각기 다른 배포 주기를 위한 여러 번들이 있는 경우, 하나의 리포지토리에서 관리하세요.
단일 리포지토리 권장 사항의 한 가지 예외는 기밀성을 위해 여러 리포지토리가 필요한 규제된 산업에서입니다.
트렁크 기반 분기 전략
병합 충돌을 최소화하고 주 분기가 항상 배포 가능한 상태인지 확인하려면 트렁크 기반 분기 전략을 사용합니다.
간단한 워크플로는 다음과 같습니다.
- 로컬 또는 작업 영역에서 개발하고 Databricks 개발 작업 영역에 배포하여 변경 내용을 테스트합니다.
- 업데이트를 버전 관리하기 위한 단기 기능 브랜치를 만들고 로컬 환경이나 작업 영역의 변경 사항을 정기적으로 동기화하세요.
- 테스트가 완료되면 기능 분기를 주 분기에 병합합니다.
- CI/CD는 기본 분기를 스테이징 작업 영역에 자동으로 배포하고 자동화된 테스트가 트리거됩니다.
- 스테이징 테스트와 검사에 통과하면 CI/CD가 메인 브랜치를 프로덕션 작업 공간에 배포를 수행합니다.
이러한 단계는 다음 다이어그램에 설명되어 있습니다.
작업 영역 구성
작업 영역 환경 격리
작업 영역 환경을 격리하여 실패한 배포의 영향을 최소화합니다. 다음은 그 예입니다.
- 소규모 팀(최대 5명의 데이터 엔지니어): 단일 클라우드 계정에서 두 개의 작업 영역(개발 및 프로덕션)으로 시작합니다.
- 성장하는 팀(5개 이상의 데이터 엔지니어): 세 개의 작업 영역(개발, 스테이징 및 프로덕션)으로 이동합니다. 스테이징은 축소되더라도 동일한 번들 구성, 스키마 및 중요한 통합과 같은 프로덕션을 기능적으로 대표해야 합니다.
- 규제 산업 (은행, 의료, 방어): 데이터 유출을 방지하기 위해 작업 영역 및 클라우드 계정을 물리적으로 격리합니다. 단일 계정 내에서 IAM 및 Unity 카탈로그 경계를 통해 격리를 관리할 수 있지만 덜 강력한 보안 태세를 제공합니다.
프로덕션 작업 영역의 경우 가능한 경우 네트워크 정책과 함께 서버리스 컴퓨팅을 사용합니다. 그렇지 않으면 엄격하게 제어된 송신 및 네트워크 보안 제어가 있는 프라이빗 서브넷 또는 VNet을 사용하도록 클라우드 계정을 구성합니다.
자세한 내용은 컨텍스트 기반 네트워크 정책을 참조하세요.
데이터 저장소 격리하기
- 단일 Unity 카탈로그 메타스토어를 사용하고 작업 영역 레이아웃을 미러링하는 개발, 스테이징(해당하는 경우) 및 프로덕션에 대해 별도의 카탈로그를 만듭니다.
- 개발 및 스테이징(비프로덕션) 카탈로그에 개별 개발자를 위한 개인 스키마를 사용합니다.
- 프로덕션 카탈로그를
ISOLATED모드에서 프로덕션 작업 영역에만 바인딩합니다. ID가 잘못 구성된 경우에도 개발 또는 스테이징 환경에서 프로덕션 데이터에 연결할 수 없도록 카탈로그의 격리 모드ISOLATED를 설정합니다. - 카탈로그 수준 격리가 충족할 수 없는 규정, 데이터 주권 또는 다중 지역 요구 사항이 있는 조직에 대해서만 별도의 메타스토어, 계정 또는 지역을 예약합니다.
테이블 및 열 메타데이터를 코드로 처리
테이블 및 열 주석을 코드의 일부로 처리합니다.
.sql 선언적 자동화 번들 정의와 함께 파일에 보관하고, 정확한 비즈니스용 정의를 항상 사용할 수 있도록 메타데이터 작업을 통해 배포합니다. 열 이름을 반복하는 대신 행이 나타내는 내용, 단위 및 유효한 값을 일반 언어로 설명하는 주석을 작성합니다.
개인 스키마 구성
개발 중에 사용자당 개인 스키마를 사용하도록 번들을 구성합니다. 예를 들면 다음과 같습니다 dev_${user_name}. 이렇게 하면 개발자가 공유 작업 영역에서 서로의 테이블을 덮어쓰지 않습니다.
서버리스 컴퓨팅 사용
서버리스 컴퓨팅을 사용하여 클러스터 관리를 간소화하고 비용을 최적화합니다. 서버리스 컴퓨팅에 연결하기를 참조하세요.
CI/CD 권장 사항
CI/CD용 선언적 자동화 번들
선언적 자동화 번들(이전의 Databricks 자산 번들)은 Databricks 에코시스템 내에서 코드, 워크플로 및 인프라를 관리하는 강력하고 통합된 접근 방식을 제공하며 CI/CD 파이프라인에 권장됩니다.
CI/CD 워크플로에 번들을 사용하는 방법에 대한 자세한 내용은 Databricks의 CI/CD 워크플로를 참조하세요.
선언적 자동화 번들에 대한 자세한 내용은 선언적 자동화 번들이란?을 참조하세요.
외부 리소스에 대해서만 Terraform 사용
Terraform을 사용하여 다음 리소스를 정의합니다.
- 클라우드 수준 및 외부 리소스
- 권한 없는 사용자가 수행해서는 안 되는 관리자 작업(예: 작업 영역 프로비저닝 또는 클라우드 네트워킹 구성)
다른 모든 Databricks 리소스에는 선언적 자동화 번들을 사용하세요.
번들 관리
작은 번들 만들기
Databricks는 하나의 큰 번들보다 작고 집중된 번들을 개발할 것을 권장합니다.
- 한 팀이 소유한 모든 것을 하나의 번들로 묶으세요.
- 동일한 수명 주기 및 릴리스 주기를 공유하는 동일한 CI/CD 파이프라인을 통해 테스트 및 배포합니다.
- 각 번들은 환경당 별도의 번들을 사용하는 대신 지정된 프로젝트(개발, 스테이징, 프로덕션)에 대한 모든 환경을 포함해야 합니다.
다음 항목에 대해 별도의 번들을 만듭니다:
- 다른 제품 또는 도메인(예: "청구 분석" 및 "사기 감지" 등)
- 다른 소유권 또는 사용 권한 경계
- 명확하게 다른 수명 주기가 있는 워크로드
- 독립적인 승격 또는 롤백이 필요한 경우
sync.paths를 사용하여 공유 폴더 동기화
한 리포지토리에서 여러 번들을 관리하는 경우 번들 루트 외부에서 공유 폴더를 동기화하는 데 사용합니다 sync.paths . 이렇게 하면 다른 프로젝트에서 별도의 배포 ID를 유지하면서 같은 공통 라이브러리 폴더 ../common를 공유할 수 있습니다.
CI/CD에서 번들 간 종속성 모델
번들 B가 번들 A에서 게시한 자산에 종속되는 경우 두 번들을 모두 하나의 번들로 축소하지 않고 CI/CD 또는 오케스트레이션 계층에서 종속성을 모델링합니다.
- 번들 A의 배포 및 게시 워크플로를 번들 B의 명시적인 선행 조건으로 만드세요. 번들 A의 배포가 성공하고 필요한 모든 유효성 검사를 통과한 후에만 번들 B가 시작되도록 파이프라인을 구성하세요.
- 게시된 자산 식별자 또는 위치를 파이프라인 입력으로 전달하고 업스트림 자산이 누락된 경우 빠르게 실패합니다. 이렇게 하면 번들 B가 부분적으로만 게시된 상태를 대상으로 배포되지 않도록 보장합니다.
번들 공유에 대한 자세한 내용은 번들 및 번들 파일 공유를 참조하세요.
사용자 지정 번들 템플릿
사용자 지정 선언적 자동화 번들 템플릿을 새 프로젝트의 기본 시작점으로 사용하여 모든 프로젝트가 각 팀이 처음부터 해결하지 않고 동일한 가드레일(권한, 태그 지정, 클러스터 정책, CI/CD 배선 및 인스턴스 기준)을 상속합니다.
템플릿은 거버넌스, 성능 기본값, 환경 레이아웃 및 할당량 제한과 같은 수명이 긴 공유 규칙을 인코딩해야 합니다. 템플릿에서 앱별 비즈니스 논리, 비밀 또는 일회성 구성을 사용하지 않습니다.
팀, 프로젝트 또는 환경에 따라 달라질 것으로 예상되는 입력만 매개 변수화합니다.
- Project 또는 애플리케이션 이름
- 대상 작업 영역 설정
- 카탈로그 또는 스키마 이름
- 서비스 주체 식별자
- 일정 및 알림 설정
플랫폼 가드레일 및 공유 기본값을 매개 변수화하지 않고 템플릿에서 고정된 상태로 유지합니다.
사용자 지정 번들 템플릿 및 템플릿을 만드는 방법에 대한 자세한 내용은 선언적 Automation 번들 프로젝트 템플릿을 참조하세요.
롤백 및 핫픽스에 대비한 계획
관련 없는 많은 워크로드에서 롤백을 조정하는 대신 단일 번들에서 대상 롤백을 수행할 수 있을 만큼 번들을 작게 유지합니다.
인시던트 발생 중:
- 영향을 받는 번들을 마지막으로 확인된 정상 버전으로 되돌리거나 롤백하세요.
- 정상적인 승격 흐름을 기다릴 수 없는 긴급하고 좁은 범위의 수정에 대해서만 핫픽스를 사용합니다.
- 검증이 끝나는 즉시 모든 핫픽스를 메인 브랜치에 다시 병합하여 트렁크가 단일 기준으로 유지되도록 하세요.
일반 개발
서비스 주체 또는 OIDC 사용
모든 비개발 자동화에 서비스 주체를 사용하여 개별 사용자 계정에서 자동화된 워크플로를 분리하고 내부 사용자가 떠날 때 작업이 계속 실행되도록 합니다. 서비스 주체를 참조하세요.
- 배포 및 런타임에 별도의 서비스 주체를 사용합니다. 번들 배포를 위한 전용 배포 서비스 주체에는 최소한의 데이터 액세스 권한이 있어야 합니다. 각 프로덕션 작업 또는 파이프라인에는 워크로드에 필요한 데이터 및 리소스로만 범위가 지정된 자체 실행 서비스 주체가 있어야 합니다. 이렇게 분리하면 데이터 액세스 권한을 회전하거나 강화할 때 배포가 안전하게 유지되고 인프라 변경 내용이 프로덕션 데이터 액세스에 결합되는 것을 방지할 수 있습니다.
- 규제 산업: CI/CD에 OIDC(워크로드 ID 페더레이션)를 사용합니다. 이렇게 하면 GitHub Actions 또는 Azure DevOps 수명이 긴 비밀이 제거됩니다. CI/CD에서 워크로드 ID 페더레이션 사용을 참조하세요.
Databricks 개발자 도구 사용
Git 폴더 또는 로컬 IDE를 사용하여 Databricks 작업 영역 UI에서 개발합니다. Visual Studio Code 또는 호환되는 포크를 사용하는 경우 다음에 대한 공식 Databricks 확장을 설치합니다.
- Databricks 관련 에이전트 기술
- Unity 카탈로그 및 파일 시스템 액세스
- Databricks 컴퓨팅에서 워크로드를 실행하는 원격 개발 기능
자세한 내용은 Visual Studio Code 대한 Databricks 확장을 참조하세요.
Notebook에서 비즈니스 논리 최소화
Notebook을 비즈니스 논리의 기본 컨테이너로 취급하지 마세요. 탐색 및 시각화에만 사용합니다.
-
Python: 핵심 로직을
src/또는src/py/의 가져와 사용할 수 있는.py모듈에 넣고, 노트북에서 그 함수들을 호출합니다. -
SQL: 쿼리는
src/또는src/sql/의.sql파일에 보관하고, 노트북에 SQL을 직접 인라인하는 대신 작업 및 파이프라인에서 해당 파일을 참조하세요.
Notebook은 기본 코드를 호출하는 씬 오케스트레이션 및 시각화 계층으로만 사용합니다. 이 방법을 사용하면 테스트 및 재사용이 더 쉬워집니다.
노트북 비중이 큰 프로젝트를 마이그레이션할 때는 점진적으로 진행하세요. 다시 사용할 수 있는 모듈 또는 SQL 파일을 한 번에 하나씩 추출하고 선언적 자동화 번들을 사용하여 프로젝트의 나머지 부분과 동일한 배포 및 테스트 워크플로에서 마이그레이션된 자산을 가져옵니다.
동적으로 컨텍스트 전달
작업 종속성에 대한 정적 변수를 사용하지 않습니다. 다단계 작업의 태스크 간에 런타임 컨텍스트를 전달하는 것과 같은 {{tasks.<task_key>.values.<value_key>}} 동적 값 참조를 사용합니다.
테스트 및 관찰 가능성
테스트 계층 구현
번들이 프로덕션으로 나아가는 방식에 맞춘 세 가지 테스트 계층을 사용하세요:
-
단위 테스트: 비즈니스 로직을 가져와 사용할 수 있는
src/모듈에 두고,pytest또는 이에 상응하는 프레임워크로 테스트합니다. 모든 풀 리퀘스트에서 이를 실행하여 실패 시 병합이 차단되도록 하세요. -
번들 유효성 검사:
bundle validate을 로컬에서 실행합니다. CI에서는 프로덕션에 배포하기 전에 YAML 및 리소스 매핑 문제를 사전에 발견할 수 있도록 비프로덕션 작업 영역에bundle deploy를 사용하는 것이 좋습니다. - 스테이징의 통합 테스트: 스테이징에 배포한 후 완료 검사 및 행 개수 또는 스키마 예상과 같은 중요한 데이터 품질 어설션을 사용하여 엔드 투 엔드 작업을 실행합니다.
프로덕션으로 아티팩트를 승격하기 위한 게이트로 "메인 브랜치와 스테이징 환경에서 모든 테스트를 통과하는 것"을 간주합니다.
Lakeflow Spark 선언적 파이프라인의 경우 임시 Notebook 실행 대신 기본 제공 개발 및 유효성 검사 기능을 사용합니다. 오류가 있는 레코드가 포함된 소규모 대표 데이터 세트에 대해 파이프라인 논리를 테스트하고 개발 모드를 사용하여 프로덕션 테이블을 업데이트하기 전에 변경 내용의 유효성을 검사합니다.
로깅을 배포의 일부로 처리
선언적 자동화 번들 배포 워크로드의 경우 각 프로젝트가 독립적으로 정의하는 것이 아니라 메트릭 및 로깅을 배포 계약의 일부로 처리합니다.
- 작업, 파이프라인 및 태스크에서 구조화된 로그를 일관되게 내보낸다. 번들 이름, 대상 환경, 워크로드 이름, 실행 식별자 및 오류를 추적하는 데 필요한 모든 비즈니스 식별자를 포함합니다.
- 모든 프로덕션 워크로드에 대한 표준 운영 메트릭 집합(실행 상태, 기간, 재시도 횟수, 처리량 또는 최신성 지표)을 추적합니다.
- 팀이 각 프로젝트에 대한 관찰 패턴을 다시 만들 필요가 없도록 공유 라이브러리, 재사용 가능한 워크로드 정의 또는 번들 템플릿에서 이러한 규칙을 인코딩합니다.