파이프라인에 대한 환경 버전 구성

Important

Lakeflow 파이프라인의 환경 버전은 공개 미리보기 상태입니다.

환경 버전은 Python 언어 버전과 파이프라인의 Python 코드에 사용할 수 있는 미리 설치된 Python 라이브러리 집합을 고정합니다. 파이프라인에 추가하는 모든 외부 종속성은 이 기준 위에 계층화됩니다.

환경 버전은 파이프라인이 실행되는 Databricks 런타임 버전에서 파이프라인의 Python 런타임을 분리합니다. 환경 버전이 설정되는 동안 Databricks 런타임 업그레이드는 Python 언어 버전 또는 사전 설치된 라이브러리 버전을 변경하지 않습니다. Python 런타임은 동일한 환경 버전을 사용하는 서버리스 작업 및 Notebook과도 일치합니다. Lakeflow 파이프라인에 대한 현재 Databricks 런타임 버전을 찾으려면 Lakeflow 파이프라인 릴리스 정보 및 릴리스 업그레이드 프로세스를 참조하세요.

Databricks는 자동으로 해당 환경 버전으로 적합한 파이프라인을 마이그레이션합니다. 자동 마이그레이션을 참조하세요.

Important

환경 버전의 파이프라인은 Spark Connect를 통해 Python 코드를 실행하는데, 이 과정에서 일부 파이프라인 코드의 동작이 달라질 수 있습니다. 제한 사항과 동작 변경 사항 전체 목록은 환경 버전 호환성을 참조하세요.

요구 사항

환경 버전에는 다음과 같은 요구 사항이 있습니다.

파이프라인은 Unity 카탈로그를 사용해야 합니다. Hive 메타스토어 파이프라인은 지원되지 않습니다.

지원되는 환경 버전

Lakeflow 파이프라인은 서버리스 및 클래식 컴퓨팅 모두에서 환경 버전 3 과 4 를 지원합니다. Python 언어 버전 및 각 버전에서 사용할 수 있는 사전 설치된 Python 라이브러리의 전체 목록은 환경 버전 참조 참조하세요.

자동 마이그레이션

Databricks는 자동으로 해당 환경 버전으로 적합한 파이프라인을 마이그레이션합니다. 마이그레이션은 파이프라인의 다음 업데이트 시점에 이루어지며, 수작업 없이 다음 안전장치를 포함합니다:

이동 전에 행동이 점검됩니다. Databricks는 Spark Connect에서 다르게 동작할 수 있는 코드 패턴을 파이프라인에서 스캔하고, 마이그레이션 전후의 파이프라인 출력 계획을 비교합니다. 환경 버전 호환성을 참조하세요.
실패한 마이그레이션은 자동으로 되돌립니다. 마이그레이션된 업데이트가 어떤 이유로든 실패하면, 데이터가 쓰이기 전에 중단되고, 파이프라인은 다음 업데이트에서 자동으로 이전 실행 상태로 되돌아갑니다. 아무 조치도 필요하지 않습니다.
명시적인 설정은 항상 존중받습니다. environment_version를 직접 설정하면 Databricks에서는 이를 절대 덮어쓰지 않습니다.

파이프라인이 성공적으로 마이그레이션되면, 앞으로는 환경 버전에서 계속 실행됩니다. 파이프라인 설정, GetPipeline API 응답runtime_details, 이벤트 로그에서 선택된 버전을 확인할 수 있습니다.

자동으로 마이그레이션되지 않는 부분

다음 중 하나라도 해당되는 파이프라인은 자동으로 마이그레이션되지 않습니다:

최근 업데이트에서 해결되지 않은 Spark Connect 호환성 경고 가 있습니다.
Unity 카탈로그 파이프라인이 아닙니다.
자동 마이그레이션이 아직 지원하지 않는 다음과 같은 기능을 사용합니다: foreach_batch 싱크, 이벤트 훅, 스냅샷 함수 소스의 AUTO CDC 또는 사용자 지정 이미지.

자동으로 마이그레이션되지 않은 파이프라인은 이전 Python 런타임에서 변경 없이 계속 실행됩니다. 파이프라인이 자격이 되면 직접 환경 버전을 활성화 할 수 있습니다.

직접 환경 버전을 활성화하세요

자동 마이그레이션은 대부분의 파이프라인을 포함합니다. 또한 파이프라인 편집기 UI, 파이프라인 REST API, 또는 선언적 자동화 번들을 통해 환경 버전을 명시적으로 설정할 수 있습니다. 예를 들어 더 빨리 마이그레이션하거나 특정 버전을 핀 지정하는 식입니다.

환경 버전을 명시적으로 활성화하기 전에, 파이프라인이 Spark Connect와 호환되는지 확인하세요. Databricks가 버전 활성화가 파이프라인의 동작에 변화를 주도록 감지하면, 데이터가 작성되기 전에 업데이트가 실패하고, 차이를 식별하여 해결해야 할 오류가 발생합니다.

UI를 통해 사용

파이프라인 편집기에서 설정을 클릭합니다.
파이프라인 환경 아래에서 을 선택합니다.환경을 편집합니다.
드롭다운 목록에서 환경 버전을 선택합니다.
파이프라인 설정을 저장합니다.

파이프라인 환경 섹션에 추가된 외부 종속성은 선택한 환경 버전에 포함된 라이브러리 위에 계층화됩니다. 파이프라인에 대한 Python 종속성 관리를 참조하세요.

API를 통해 사용

Pipelines REST API는 파이프라인 만들기 및 업데이트에 대한 블록을 허용합니다 environment . 작업 영역에 대해 개인 액세스 토큰 인증 을 사용하도록 설정해야 합니다.

환경 버전으로 파이프라인을 만들려면 다음을 수행합니다.

curl --request POST \
  --url 'https://<workspace-host>/api/2.0/pipelines' \
  --header 'Authorization: Bearer <personal-access-token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "<pipeline-name>",
    "catalog": "<catalog>",
    "schema": "<schema>",
    "channel": "CURRENT",
    "environment": {
      "environment_version": "4",
      "dependencies": [
        "simplejson==3.19.*"
      ]
    }
  }'

기존 파이프라인에서 환경 버전을 설정하려면 동일한 environment 블록을 로 PUT /api/2.0/pipelines/<pipeline-id>보냅니다.

선언형 자동화 번들을 통해 활성화

선언적 자동화 번들을 사용하여 파이프라인을 만들 때 파이프라인의 YAML 정의에서 환경 버전을 설정할 수 있습니다.

Databricks CLI가 버전 v0.294.0 이상인지 확인합니다. 그렇지 않은 경우 설치 가이드에 따라 업그레이드합니다.
파이프라인 번들 자습서에 따라 번들을 설정합니다.
번들에서 파이프라인 YAML을 찾으세요. 일반적으로 <bundle-folder>/resources/<pipeline_name>_pipeline.yml입니다.
파이프라인 YAML에서 environment_version 및 dependencies 필드를 설정합니다:

resources:
  pipelines:
    my_pipeline:
      name: my_pipeline
      catalog: ${var.catalog}
      schema: ${var.schema}
      root_path: '../src/my_pipeline'
      libraries:
        - glob:
            include: ../src/my_pipeline/transformations/**
      environment:
        environment_version: 4
        dependencies:
          - --editable ${workspace.file_path}

파이프라인에서 환경 버전 확인

파이프라인이 어떤 환경 버전을 실행하는지 확인하려면, 명시적으로 설정했는지 Databricks가 자동 마이그레이션 중에 선택했는지 확인하세요:

UI: 파이프라인 설정을 열고 파이프라인 환경 섹션을 확인하거나 필드에 대한 environment.environment_version JSON 창을 검사합니다.
API: GET /api/2.0/pipelines/<pipeline-id>을(를) 호출하고 응답에서 environment.environment_version을(를) 찾습니다. 이것은 명시적으로 설정한 버전을 보여줍니다; 자동 마이그레이션으로 선택된 버전을 보려면 아래 이벤트 로그를 사용하세요.
이벤트 로그: 업데이트에 사용된 환경 버전을 보고하는 이벤트를 runtime_details 검사합니다. runtime_details 이벤트에 대한 세부 정보를 참조하세요.

환경 버전을 비활성화하거나 롤백하세요

자동 마이그레이션을 수동으로 롤백할 필요는 없습니다. 실패한 마이그레이션은 다음 업데이트에서 자동으로 되돌려집니다. 환경 버전이 제거되면 파이프라인은 이전 Python 런타임 구성으로 돌아갑니다. 예상치 못한 일이 생기면 Azure Databricks 지원팀에 연락하세요.

추가 리소스

환경 버전 호환성 — 제한, 동작 변경, 호환성 스캔, 자동 마이그레이션.
파이프라인에 대한 종속성을 Python 관리 - 환경 버전 위에 외부 Python 종속성을 계층화합니다.

피드백

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

Last updated on 2026-08-19