Databricks CLI 마이그레이션

아티클
05/03/2024

이 문서에서는 Databricks CLI 버전 0.18 이하에서 Databricks CLI 버전 0.205 이상으로 마이그레이션하는 방법을 설명합니다. Databricks CLI 버전 0.205 이상은 공개 미리 보기로 제공됩니다.

간단히 하기 위해 이 문서에서는 Databricks CLI 버전 0.18 이하를 "레거시" CLI로, Databricks CLI 버전 0.205 이상을 "새로운" CLI로 참조합니다.

레거시 및 새 CLI에 대한 자세한 내용은 다음을 참조하세요.

레거시 CLI에 대한 Databricks CLI(레거시) 입니다.
Databricks CLI란? 새 CLI에 대한 입니다.

레거시 CLI 제거

레거시 CLI가 설치되어 있고 제거하려는 pip 경우 다음과 같이 (또는 pip3Python 버전에 따라) 명령을 실행 uninstall 합니다.

pip uninstall databricks-cli

새 CLI 설치

새 CLI를 설치하는 방법을 알아보려면 Databricks CLI 설치 또는 업데이트를 참조하세요.

CLI 설치 확인

새 CLI를 사용하고 있는지 확실하지 않은 경우 이 섹션의 지침에 따라 필요에 따라 확인하고 조정합니다. 이러한 지침을 따르기 전에 Python 가상 환경, conda 환경 또는 유사한 환경을 종료해야 합니다.

CLI의 기본 설치 버전을 검사 다음 명령을 실행합니다.

databricks -v

버전 번호가 예상과 다른 경우 다음 중 하나를 수행합니다.

CLI 버전을 하나만 사용하려면 더 이상 사용하지 않으려는 모든 이전 버전의 CLI를 제거합니다. 사용하려는 CLI의 다시 기본 버전에 대한 경로가 나열되도록 운영 체제 PATH 를 업데이트해야 할 수 있습니다.
여러 버전의 CLI를 계속 사용하려면 CLI를 호출할 때마다 사용할 CLI 버전에 대한 전체 경로를 추가합니다.
여러 버전의 CLI를 계속 사용하지만 가장 자주 사용하는 CLI 버전에 대한 전체 경로 앞에 계속 추가하지 않으려면 해당 버전의 전체 경로가 운영 체제에서 PATH먼저 나열되어 있는지 확인합니다. 운영 체제 PATH에서 먼저 나열되지 않은 CLI 버전에 대한 전체 경로를 계속 앞에 추가해야 합니다.

운영 체제를 PATH업데이트하려면 다음을 수행합니다.

Macos 또는 linux

다음 명령 중 하나를 실행하여 설치되는 경로를 databricks 나열합니다.
```
which -a databricks

# Or:
where databricks
```
CLI를 호출할 때마다 전체 경로를 앞에 추가하지 않고 사용하려는 설치 경로를 가져옵니다. 이 경로가 무엇인지 확실하지 않은 경우 각 위치에 대한 전체 경로를 실행하고 다음 -v을 수행합니다. 예를 들면 다음과 같습니다.
```
/usr/local/bin/databricks -v
```
먼저 PATH사용하려는 설치 경로를 배치하려면 다음 명령을 실행하여 사용하려는 경로로 바꿉 /usr/local/bin 다. 이 경로의 끝에 추가 databricks 하지 마세요. 예시:
```
export PATH="/usr/local/bin:$PATH"
```
현재 터미널 세션에 PATH 대해 올바르게 설정되었는지 확인하려면 다음 -v 을 실행하고 databricks 버전 번호를 검사.
```
databricks -v
```
터미널을 PATH 다시 시작할 때마다 이러한 방식으로 설정하려면 3단계의 명령을 셸 초기화 파일에 추가합니다. 예를 들어 Zshell의 경우 이 파일은 일반적으로 .에 ~/.zshrc있습니다. Bash의 경우 이 파일은 일반적으로 .에 있습니다 ~/.bashrc. 다른 셸은 셸 공급자의 설명서를 참조하세요.
셸 초기화 파일을 업데이트한 후 업데이트 PATH 된 값을 적용하려면 터미널을 다시 시작해야 합니다.

Windows

CLI를 호출할 때마다 전체 경로를 앞에 추가하지 않고 사용하려는 설치 databricks 를 마우스 오른쪽 단추로 클릭합니다.
파일 위치 열기를 클릭합니다.
예를 들어 C:\Windows경로에 databricks유의하세요.
시작 메뉴에서 환경 변수를 검색합니다.
계정에 대한 환경 변수 편집을 클릭합니다.
섹션의 사용자 변수에서 경로 변수를 <username> 선택합니다.
편집을 클릭합니다.
새로 만들기를 클릭합니다.
추가하려는 경로(예: C:\Windows)를 입력하지 않고 databricks.exe 입력합니다.
위로 이동 단추를 사용하여 방금 추가한 경로를 목록의 시작 부분으로 이동합니다.
확인을 클릭합니다.
올바르게 설정되었는지 확인 PATH 하려면 새 명령 프롬프트를 열고 다음을 -v실행하고 databricks 버전 번호를 검사.
```
databricks -v
```

추가 인증 유형 사용

레거시 CLI와 새 CLI는 모두 Azure Databricks 개인용 액세스 토큰 인증을 지원합니다. 그러나 Databricks는 가능한 경우 새 CLI만 지원하는 다른 Azure Databricks 인증 유형을 사용하는 것이 좋습니다.

Azure Databricks 개인용 액세스 토큰 인증을 사용해야 하는 경우 Databricks는 Azure Databricks 계정 또는 작업 영역 사용자 대신 서비스 주체와 연결된 토큰을 사용하는 것이 좋습니다. 서비스 주체 관리를 참조하세요.

새 CLI는 Azure Databricks 개인용 액세스 토큰 외에도 Microsoft Entra ID 토큰을 지원합니다. 이러한 추가 토큰은 일반적으로 1시간 안에 만료되므로 더 안전하지만 Azure Databricks 개인용 액세스 토큰은 하루에서 무기한으로 유효할 수 있습니다. 이는 토큰이 실수로 다른 사용자가 액세스할 수 있는 버전 제어 시스템에 검사 경우 특히 중요합니다. 또한 새 CLI는 만료될 때 이러한 추가 토큰을 자동으로 새로 고칠 수 있지만 Azure Databricks 개인용 액세스 토큰을 새로 고치는 것은 수동 프로세스이거나 자동화하기 어려울 수 있습니다.

자세한 내용은 Databricks CLI에 대한 인증을 참조하세요.

명령 그룹 및 명령 비교

다음 표에는 레거시 CLI 명령 그룹과 해당 새 CLI 명령 그룹이 나와 있습니다. CLI 간에 중요한 차이점이 있는 경우 추가 테이블에는 레거시 CLI 명령 또는 옵션과 새 CLI 명령 또는 옵션 등가 항목이 나열됩니다.

명령 그룹

레거시 명령 그룹	새 명령 그룹
`cluster-policies`	`cluster-policies`. 모든 명령 이름은 동일합니다.
`clusters`	`clusters`. 모든 명령 이름은 동일합니다.
`configure`	`configure`. 구성 옵션을 참조하세요.
`fs`	`fs`. fs 명령을 참조 하세요.
`groups`	`groups`. 그룹 명령을 참조 하세요.
`instance-pools`	`instance-pools`. 모든 명령 이름은 동일합니다.
`jobs`	`jobs`. 모든 명령 이름은 동일합니다.
`libraries`	`libraries`. 를 제외한 `list`모든 명령 이름은 동일합니다. 이 `list` 명령은 더 이상 사용할 수 없습니다. 대신 또는 `cluster-status` 명령을 사용합니다`all-cluster-statuses`.
`pipelines`	`pipelines`. 파이프라인 명령을 참조 하세요.
`repos`	`repos`. 모든 명령 이름은 동일합니다.
`runs`	`jobs`. 실행 명령을 참조 하세요.
`secrets`	`secrets`. 비밀 명령을 참조 하세요.
`stack`	새 CLI에서는 사용할 수 없습니다. Databricks는 Databricks Terraform 공급자를 대신 사용하는 것이 좋습니다.
`tokens`	`tokens`. 토큰 명령을 참조 하세요.
`unity-catalog`	다양 한. unity 카탈로그 명령 그룹을 참조하세요.
`workspace`	`workspace`. 작업 영역 명령을 참조 하세요.

`configure` 옵션

레거시 옵션	새 옵션
`-o`	레거시 CLI는 OAuth 인증에 사용합니다 `-o` . 새 CLI는 CLI 출력이 `-o` 텍스트 형식인지 JSON 형식인지를 지정하기 위해 용도를 변경합니다. Azure Databricks에는 적용되지 않습니다.
`--oauth`	Azure Databricks에는 적용되지 않습니다.
`-s` 또는 `--scope`	Azure Databricks에는 적용되지 않습니다.
`-t` 또는 `--token`	`-t` 또는 `--token` (동일)
`-f` 또는 `--token-file`	새 CLI에서는 사용할 수 없습니다.
`--host`	`--host` (동일)
`--aad-token`	Azure Databricks 개인용 액세스 토큰 대신 메시지가 표시되면 Microsoft Entra ID(이전의 Azure Active Directory) 토큰을 사용하고 `--host` 지정합니다.
`--insecure`	새 CLI에서는 사용할 수 없습니다.
`--jobs-api-version`	새 CLI에서는 사용할 수 없습니다. 새 CLI는 작업 API 2.1만 사용합니다. 레거시 작업 API 2.0을 호출하려면 레거시 CLI를 사용하고 작업 CLI(레거시)를 참조하세요.
`--debug`	새 CLI에서 디버깅 및 로깅은 디버그 모드를 참조하세요.
`--profile`	`--profile` (동일) 또는 `-p`
`-h` 또는 `--help`	`-h` 또는 `--help` (동일)

`fs` 명령

레거시 CLI의 모든 fs 명령은 새 CLI에서 사용할 수 없다는 점을 제외하고 fs mv 새 CLI에서 동일합니다.

레거시 명령	새 명령
`fs cat`	`fs cat` (동일)
`fs cp`	`fs cp` (동일)
`fs ls`	`fs ls` (동일)
`fs mkdirs`	`fs mkdir`
`fs mv`	새 CLI에서는 사용할 수 없습니다.
`fs rm`	`fs rm` (동일)

`groups` 명령

레거시 명령	새 명령
`groups add-member`	`groups patch`
`groups create`	`groups create` (동일)
`groups delete`	`groups delete` (동일)
`groups list`	`groups list` (동일)
`groups list-members`	`groups list`
`groups list-parents`	`groups list`
`groups remove-member`	`groups patch`

`pipelines` 명령

레거시 명령	새 명령
`pipelines create`	`pipelines create` (동일)
`pipelines delete`	`pipelines delete` (동일)
`pipelines deploy`	`pipelines create`
`pipelines edit`	`pipelines update`
`pipelines get`	`pipelines get` (동일)
`pipelines list`	`pipelines list-pipeline-events` 또는 `pipelines list-pipelines` 또는 `pipelines list-updates`
`pipelines reset`	`pipelines reset` (동일)
`pipelines start`	`pipelines start update`
`pipelines stop`	`pipelines stop` (동일)
`pipelines update`	`pipelines update` (동일)

`runs` 명령

레거시 명령	새 명령
`runs cancel`	`jobs cancel-run`
`runs get`	`jobs get-run`
`runs get-output`	`jobs get-run-output`
`runs list`	`jobs list-runs`
`runs submit`	`jobs submit`

`secrets` 명령

레거시 명령	새 명령
`secrets create-scope`	`secrets create-scope` (동일)
`secrets delete`	`secrets delete-secret`
`secrets delete-acl`	`secrets delete-acl` (동일)
`secrets delete-scope`	`secrets delete-scope` (동일)
`secrets get-acl`	`secrets get-acl` (동일)
`secrets list`	`secrets list-secrets`
`secrets list-acls`	`secrets list-acls` (동일)
`secrets list-scopes`	`secrets list-scopes` (동일)
`secrets put`	`secrets put-secret`
`secrets put-acl`	`secrets put-acl` (동일)
`secrets write`	`secrets put-secret`
`secrets write-acl`	`secrets put-acl`

`tokens` 명령

레거시 명령	새 명령
`tokens create`	`tokens create` (동일)
`tokens list`	`tokens list` (동일)
`tokens revoke`	`tokens delete`

`unity-catalog` 명령 그룹

unity-catalog <command> 에서 레거시 CLI는 새 CLI에만 <command> 적용됩니다.

레거시 명령 그룹	새 명령 그룹
`unity-catalog catalogs`	`catalogs` (동일하지만 삭제 `unity-catalog`)
`unity-catalog external-locations`	`external-locations` (동일하지만 삭제 `unity-catalog`)
`unity-catalog lineage`	새 CLI에서는 사용할 수 없습니다. 데이터 계보 API를 참조하세요.
`unity-catalog metastores`	`metastores` (동일하지만 삭제 `unity-catalog`)
`unity-catalog permissions`	`grants`
`unity-catalog providers`	`providers` (동일하지만 삭제 `unity-catalog`)
`unity-catalog recipients`	`recipients` (동일하지만 삭제 `unity-catalog`)
`unity-catalog schemas`	`schemas` (동일하지만 삭제 `unity-catalog`)
`unity-catalog shares`	`shares` (동일하지만 삭제 `unity-catalog`)
`unity-catalog storage-credentials`	`storage-credentials` (동일하지만 삭제 `unity-catalog`)
`unity-catalog tables`	`tables` (동일하지만 삭제 `unity-catalog`)

`workspace` 명령

레거시 명령	새 명령
`workspace delete`	`workspace delete` (동일)
`workspace export`	`workspace export` (동일)
`workspace export-dir`	`workspace export`
`workspace import`	`workspace import` (동일)
`workspace import-dir`	`workspace import`
`workspace list`	`workspace list` (동일)
`workspace ls`	`workspace list`
`workspace mkdirs`	`workspace mkdirs` (동일)
`workspace rm`	`workspace delete`

기본 및 위치 인수

대부분의 새 CLI 명령에는 함께 제공되는 옵션이 없는 기본 인수가 하나 이상 있습니다. 일부 새 CLI 명령에는 특정 순서로 지정해야 하며 함께 제공되는 옵션이 없는 두 개 이상의 위치 인수가 있습니다. 이는 대부분의 명령에 모든 인수에 대해 옵션을 지정해야 하는 레거시 CLI와 다릅니다. 예를 들어 새 CLI의 clusters get 명령은 클러스터 ID를 기본 인수로 사용합니다. 그러나 레거시 CLI의 clusers get 명령을 사용하려면 클러스터 ID와 함께 옵션을 지정 --cluster-id 해야 합니다. 예시:

레거시 CLI의 경우:

# This works with the legacy CLI.
databricks clusters get --cluster-id 1234-567890-a1b23c4d

# This does **not** work with the legacy CLI - "Error:
#   Missing None. One of ['cluster-id', 'cluster-name'] must be provided."
databricks clusters get 1234-567890-a1b23c4d

새 CLI의 경우:

# This works with the new CLI.
databricks clusters get 1234-567890-a1b23c4d

# This does **not** work with the new CLI - "Error: unknown flag: --cluster-id"
databricks clusters get --cluster-id 1234-567890-a1b23c4d

또 다른 예로, 새 CLI의 grants get 명령은 두 가지 기본 인수인 보안 형식과 보안 개체의 전체 이름을 사용합니다. 그러나 레거시 CLI의 unity-catalog permissions get 명령을 사용하려면 보안 개체의 전체 이름과 함께 옵션을 지정 --<securable-type> 해야 합니다. 예시:

레거시 CLI의 경우:

databricks unity-catalog permissions get --schema main.default

새 CLI의 경우:

# This works with the new CLI.
databricks grants get schema main.default

# This does **not** work with the new CLI - "Error: unknown flag: --schema"
databricks grants get --schema main.default

디버그 모드

레거시 CLI는 오류 시 전체 스택 추적을 표시하는 옵션을 제공합니다 --debug . 새 CLI의 --debug 경우 옵션이 인식되지 않습니다. 대신 다음 옵션을 사용합니다.

에 지정된 <path>파일에 로그 정보를 쓰는 데 사용합니다--log-file <path>. 이 옵션을 제공하지 않으면 로그 정보가 stderr에 출력됩니다. --log-file 또한 결과를 지정하지 않고 지정하면 --log-level 로그 정보가 파일에 기록되지 않습니다.
기록된 정보의 형식을 지정하는 데 사용합니다 --log-format <type> . <type> 은 text (지정되지 않은 경우 기본값) 또는 json.일 수 있습니다.
기록된 정보 수준을 지정하는 데 사용합니다 --log-level <format> . 허용되는 값은 disabled (지정되지 않은 경우 기본값), trace, debug, info, warn및 error.

레거시 CLI의 경우 다음 예제에서는 오류 발생에 대한 전체 스택 추적을 보여줍니다.

databricks fs ls / --debug

# Output:
#
# HTTP debugging enabled
# NoneType: None
# Error: The path / must start with "dbfs:/"

새 CLI의 경우 다음 예제에서는 전체 스택 추적을 현재 작업 디렉터리에 명명된 new-cli-errors.log 파일에 기록합니다. 스택 추적은 JSON 형식으로 파일에 기록됩니다.

databricks fs ls / --log-file new-cli-errors.log --log-format json --log-level trace

# Output:
#
# Error: expected dbfs path (with the dbfs:/ prefix): /
#
# (The full stack trace is also written to the new-cli-errors.log file.)

일반적인 질문

이 섹션에서는 레거시에서 새 CLI로 마이그레이션하는 방법에 대한 일반적인 질문을 나열합니다.

레거시 CLI는 어떻게 됩니까?

레거시 CLI는 여전히 사용할 수 있지만 중요하지 않은 업데이트를 받지 못하고 있습니다. 레거시 CLI 설명서는 이를 반영합니다. Databricks는 사용자가 가능한 한 빨리 새 CLI로 마이그레이션하는 것이 좋습니다.

레거시 CLI는 항상 Databricks가 레거시 CLI에 대한 새로운 기능 작업을 계획하지 않으며 레거시 CLI는 Databricks 지원 채널을 통해 지원되지 않는다는 고지 사항을 포함하는 실험적 상태였습니다.

레거시 CLI는 언제 더 이상 사용되지 않는가요?

Databricks는 레거시 CLI를 더 이상 사용하지 않는 날짜 또는 타임라인 설정하지 않았습니다. 그러나 Databricks는 사용자가 가능한 한 빨리 새 CLI로 마이그레이션하는 것이 좋습니다.

새 CLI는 언제 GA(일반 공급)로 릴리스되나요?

GA로 새 CLI를 릴리스하기 위한 릴리스 날짜 또는 타임라인 설정되지 않았습니다. 이는 공개 미리 보기 중에 Databricks가 사용자로부터 받은 피드백에 따라 달라집니다.

레거시와 새 CLI의 주요 차이점은 무엇인가요?

레거시 CLI는 Python 패키지로 릴리스되었습니다. 새 CLI는 독립 실행형 실행 파일로 릴리스되며 런타임 종속성을 설치할 필요가 없습니다.
새 CLI에는 Databricks REST API의 전체 적용 범위가 있습니다. 레거시 CLI는 그렇지 않습니다.
새 CLI는 공개 미리 보기로 사용할 수 있습니다. 레거시 CLI는 실험적 상태로 다시 기본.

새 CLI에 레거시 CLI와 전체 기능 패리티가 있나요?

새 CLI에는 레거시 CLI의 거의 모든 명령에 대한 적용 범위가 있습니다. 그러나 특히 새 CLI가 없는 것은 레거시 CLI의 stacks 명령 그룹입니다. 또한 새 CLI의 새 명령 그룹으로 리팩터링된 것과 같은 unity-catalogruns 몇 가지 레거시 CLI 명령 그룹도 있습니다. 마이그레이션 지침은 이 문서의 앞부분에 제공된 정보를 참조하세요.

레거시에서 새 CLI로 마이그레이션할 어떻게 할까요? 있나요?

마이그레이션 지침은 이 문서의 앞부분에 제공된 정보를 참조하세요. 새 CLI는 레거시 CLI를 대체하는 드롭인이 아니며 레거시에서 새 CLI로 이동하기 위해 일부 설정이 필요합니다.

레거시 및 새 CLI의 설치가 동일한 컴퓨터에 존재할 수 있나요?

예. 레거시 및 새 CLI의 설치는 동일한 컴퓨터에 있을 수 있지만 서로 다른 디렉터리에 있어야 합니다. 실행 파일은 모두 이름이 지정 databricks되므로 머신 PATH을 구성하여 기본적으로 실행되는 실행 파일을 제어해야 합니다. 새 CLI를 실행하지만 실수로 레거시 CLI를 대신 실행하려는 경우 기본적으로 레거시 CLI는 동일한 인수를 사용하여 새 CLI를 실행하고 다음 경고 메시지를 표시합니다.

Databricks CLI <new-version-number> found at <new-path>
Your current PATH prefers running CLI <old-version-number> at <old-path>

Because both are installed and available in PATH,
I assume you are trying to run the newer version.

If you want to disable this behavior you can set DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION=1.

Executing CLI <new-version-number>...
-------------------------------------
Databricks CLI <new-version-number>

앞의 경고 메시지에 표시된 것처럼 환경 변수를 설정하여 1 이 동작을 사용하지 않도록 설정하고 DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION 레거시 CLI를 대신 실행할 수 있습니다.

도움말 보기

레거시 CLI에서 새 CLI로 마이그레이션하는 데 도움이 되도록 다음 리소스를 참조하세요.