Autenticação para a CLI do Databricks

Observação

Essas informações se aplicam ao site Databricks CLI versões 0.205 e superiores. A CLI da Databricks está em visualização pública.

Databricks CLI O uso está sujeito à LicençaDatabricks e ao Aviso de PrivacidadeDatabricks , incluindo qualquer provisionamento de Dados de Uso.

Este artigo descreve como configurar a autenticação entre a CLI do Databricks e suas accounts e workspaces do Databricks. Consulte O que é a CLI do Databricks?.

Este artigo pressupõe que você já instalou a CLI do Databricks. Consulte Instalar ou atualizar a CLI do Databricks.

Antes de executar os comandos da CLI do Databricks, configure a autenticação entre a CLI do Databricks e suas contas, espaços de trabalho do Databricks ou uma combinação deles, dependendo dos tipos de comandos da CLI que você deseja executar.

Você deve autenticar a CLI do Databricks nos recursos relevantes no momento da execução para executar comandos de automação do Databricks dentro de uma account ou workspace do Databricks. Dependendo se você deseja chamar comandos de nível de workspace ou de nível de account do Databricks, ou ambos, você deve se autenticar no workspace do Databricks, na account ou em ambos. Para uma lista de grupos de comandos da CLI de nível de workspace e de nível de account do Databricks, execute o comando databricks -h. Para uma lista de operações da API REST de nível de workspace e de nível de account que os comandos da CLI do Databricks cobrem, consulte a API REST do Databricks.

As seções a seguir fornecem informações sobre como configurar a autenticação entre a CLI do Databricks e o Databricks:

Autenticação por access token pessoal do Databricks

A autenticação do token de acesso pessoal do Databricks utiliza um token de acesso pessoal do Databricks para autenticar a entidade desejada do Databricks, como por exemplo uma conta de usuário do Databricks ou uma entidade de serviço do Databricks. Consulte também Autenticação de token de acesso pessoal do Databricks.

Observação

Você não pode usar a autenticação com access tokens pessoais do Databricks para autenticar com uma account do Databricks, pois os comandos de nível de account não utilizam access tokens pessoais do Databricks para autenticação. Para autenticar com uma account do Databricks, considere usar um dos seguintes tipos de autenticação:

• Autenticação de máquina para máquina (M2M) do OAuth

• Autenticação de usuário para máquina (U2M) do OAuth

• Autenticação de credenciais do Google Cloud

• Autenticação do Google Cloud ID

Para criar um token de acesso pessoal, faça o seguinte:

1. Em seu workspace do Databricks, clique em seu nome de usuário do Databricks na barra superior e, em seguida, selecione Configurações no menu suspenso.

2. Clique em Desenvolvedor.

3. Ao lado de Access tokens, clique em Gerenciar.

4. Clique em Gerar novo token.

5. (Opcional) Insira um comentário que ajude a identificar esse token no futuro e altere o tempo de vida default do token de 90 dias. Para criar um token sem vida útil (não recomendado), deixe a caixa Duração da vida (dias) vazia (em branco).

6. Clique em Gerar.

7. Copie o token exibido em um local seguro e clique em Concluído.

Observação

É importante que você salve o token copiado em um local seguro. Não compartilhe seu token copiado com outras pessoas. Se você perder o token, não poderá gerar de novo exatamente o mesmo token. Em vez disso, você deverá repetir esse procedimento para criar outro token. Se você perder o token copiado ou acreditar que o token foi comprometido, o Databricks recomenda que você exclua imediatamente esse token do workspace clicando no ícone da lixeira (Revogar) ao lado do token na página Access tokens .

Se o senhor não conseguir criar ou usar o site tokens no seu workspace, isso pode ocorrer porque o administrador do workspace desativou o tokens ou não lhe deu permissão para criar ou usar o tokens. Consulte o administrador do site workspace ou os tópicos a seguir:

• Ativar ou desativar a autenticação de access tokens pessoais para o workspace

• Permissões de access token pessoal

Para configurar e usar a autenticação por access token pessoal do Databricks, faça o seguinte:

Observação

O procedimento a seguir cria um perfil de configuração do Databricks com o nome DEFAULT. Se você já tiver um perfil de configuração DEFAULT que deseja usar, ignore este procedimento. Caso contrário, esse procedimento substituirá o perfil de configuração do DEFAULT existente. Para exibir os nomes e hosts de qualquer perfil de configuração existente, execute o comando databricks auth profiles.

Para criar um perfil de configuração com um nome diferente de DEFAULT, adicione --profile <configuration-profile-name> ou -p <configuration-profile-name> ao final do comando databricks configure a seguir, substituindo <configuration-profile-name> pelo nome do novo perfil de configuração.

1. Use a CLI do Databricks para executar o seguinte comando:

   databricks configure
   

2. Para o prompt Databricks Host, insira o URL da instância do seu workspace do Databricks, por exemplo https://1234567890123456.7.gcp.databricks.com.

3. Para o prompt Access token pessoal, insira o access token pessoal do Databricks para seu workspace

   Depois de inserir seu access token pessoal do Databricks, um perfil de configuração correspondente é adicionado ao seu arquivo .databrickscfg . Se a CLI do Databricks não conseguir encontrar esse arquivo em seu local padrão, ele criará esse arquivo para você primeiro e depois adicionará esse perfil de configuração ao novo arquivo. O local padrão desse arquivo é na sua pasta ~ (sua página inicial de usuário) no Unix, Linux ou macOS, ou sua pasta %USERPROFILE% (sua página inicial de usuário) no Windows.

4. Agora você pode usar a opção --profile ou -p da CLI do Databricks seguida pelo nome do seu perfil de configuração, como parte do comando da CLI do Databricks, por exemplo, databricks clusters list -p <configuration-profile-name>.

Autenticação OAuth machine-to-machine (M2M)

Em vez de se autenticar com Databricks usando a autenticaçãoDatabricks pessoal access token , o senhor pode usar a autenticação OAuth. OAuth fornece ao tokens tempos de expiração mais rápidos do que o Databricks pessoal access tokens, e oferece melhor invalidação e escopo de sessão no lado do servidor. Como o OAuth access tokens expira em menos de uma hora, isso reduz o risco associado à verificação acidental do tokens no controle de origem. Consulte também Autenticar o acesso ao Databricks com uma entidade de serviço usando o OAuth (OAuth M2M).

Para configurar e usar a autenticação OAuth M2M, faça o seguinte:

1. Conclua as instruções de configuração da autenticação OAuth M2M. Consulte Autenticar o acesso ao Databricks com uma entidade de serviço usando OAuth (OAuth M2M)

2. Crie ou identifique um perfil de configuração do Databricks com os seguintes campos no arquivo .databrickscfg. Se você criar o perfil, substitua os placeholders pelos valores apropriados.

   Para comandos de nível de account, defina os seguintes valores no seu arquivo .databrickscfg:

   [<some-unique-configuration-profile-name>]
   host          = <account-console-url>
   account_id    = <account-id>
   client_id     = <service-principal-client-id>
   client_secret = <service-principal-oauth-secret>
   

   Para comandos de nível de workspace, defina os seguintes valores no seu arquivo .databrickscfg:

   [<some-unique-configuration-profile-name>]
   host          = <workspace-url>
   client_id     = <service-principal-client-id>
   client_secret = <service-principal-oauth-secret>
   

   Observação

   O local padrão do arquivo .databrickscfg é no diretório inicial do usuário. É ~ para Linux e macOS, e %USERPROFILE% para Windows.

3. Use a opção --profile ou -p da CLI do Databricks seguida pelo nome do seu perfil de configuração como parte da chamada de comando da CLI do Databricks, por exemplo, databricks account groups list -p <configuration-profile-name> ou databricks clusters list -p <configuration-profile-name>.

   Dica

   Pressione Tab após --profile ou -p para exibir uma lista de perfis de configuração disponíveis, em vez de digitar o nome do perfil de configuração manualmente.

Autenticação OAuth user-to-machine (U2M)

Em vez de autenticar com Databricks usando a autenticação de tokens, o senhor pode usar a autenticação OAuth. OAuth fornece ao tokens tempos de expiração mais rápidos do que o Databricks pessoal access tokens, e oferece melhor invalidação e escopo de sessão no lado do servidor. Como o OAuth access tokens expira em menos de uma hora, isso reduz o risco associado à verificação acidental do tokens no controle de origem. Consulte também Autenticar o acesso a Databricks com um usuário account usando OAuth (OAuth U2M).

Para configurar e usar a autenticação OAuth U2M, faça o seguinte:

1. Antes de chamar quaisquer comandos de nível de account do Databricks, você deve iniciar o gerenciamento de tokens OAuth localmente, executando o seguinte comando. Esse comando deve ser executado separadamente para cada account em que você deseja executar comandos. Se você não quiser chamar nenhuma operação de nível de account, pule para o passo 5.

   No comando a seguir, substitua os seguintes espaços reservados:

   • Substitua <account-console-url> pelo seu Databricks https://accounts.gcp.databricks.com.

   • Substitua <account-id> pelo ID da sua account do Databricks. Consulte Localizar o ID da sua account.

   databricks auth login --host <account-console-url> --account-id <account-id>
   

2. O Databricks CLI solicita que o usuário salve o account URL do console e o account ID localmente como um Databricks perfil de configuração. Pressione Enter para aceitar o nome de perfil sugerido ou insira o nome de um perfil novo ou existente. Qualquer perfil existente com o mesmo nome é substituído por esse URL do console account e pelo ID account.

   Para obter uma lista de todos os perfis existentes, em um terminal ou prompt de comando separado, execute o comando databricks auth profiles. Para visualizar as configurações existentes de um perfil específico, execute o comando databricks auth env --profile <profile-name>.

3. No seu navegador, siga as instruções na tela para fazer login na sua account do Databricks.

4. Para ver o valor atual do token OAuth e a data e hora de expiração futura, execute o comando databricks auth token --host <account-console-url> --account-id <account-id>.

5. Antes de chamar qualquer comando no nível do workspace do Databricks, você deve iniciar o gerenciamento de tokens OAuth localmente executando o seguinte comando. Este comando deve ser executado separadamente para cada workspace no qual você deseja executar comandos.

   No comando a seguir, substitua <workspace-url> pelo URL da instância do seu workspace do Databricks, por exemplo https://1234567890123456.7.gcp.databricks.com.

   databricks auth login --host <workspace-url>
   

6. A CLI do Databricks pede que você salve o URL do espaço de trabalho no local como perfil de configuração do Databricks. Pressione Enter para aceitar o nome de perfil sugerido ou insira o nome de um perfil novo ou existente. Se já existir um perfil com o mesmo nome ele será substituído pelo URL do console desta conta e pela ID da conta.

   Para obter uma lista de todos os perfis existentes, em um terminal ou prompt de comando separado, execute o comando databricks auth profiles. Para visualizar as configurações existentes de um perfil específico, execute o comando databricks auth env --profile <profile-name>.

7. No navegador da web, conclua as instruções na tela para fazer log in no workspace do Databricks.

8. Para ver o valor atual do token OAuth e a data e hora de expiração futura, execute o comando databricks auth token --host <workspace-url>.

9. Use a opção --profile ou -p da CLI do Databricks, seguida pelo nome do seu perfil de configuração, como parte da chamada de comando da CLI do Databricks, por exemplo databricks account groups list -p <configuration-profile-name> ou databricks clusters list -p <configuration-profile-name>.

   Dica

   Você pode pressionar Tab após --profile ou -p para exibir a lista de perfis de configuração disponíveis existentes para escolher, em vez de inserir o nome do perfil de configuração manualmente.

Autenticação de credenciais do Google Cloud

A autenticação de credenciais do Google Cloud usa credenciais de account de serviço do Google Cloud para autenticar a account de serviço do Google Cloud de destino. Veja também Autenticação de credenciais do Google Cloud.

Para configurar a autenticação de credenciais de nuvem do Google, o senhor deve ter a autenticação de ID de nuvem do Google instalada localmente. Você também deve fazer o seguinte:

1. Crie ou identifique um perfil de configuração do Databricks com os seguintes campos no arquivo .databrickscfg. Se você criar o perfil, substitua os placeholders pelos valores apropriados.

   Para comandos de nível de account, defina os seguintes valores no seu arquivo .databrickscfg:

   [<some-unique-configuration-profile-name>]
   host               = <account-console-url>
   account_id         = <account-id>
   google_credentials = <path-to-google-service-account-credentials-file>
   

   Para comandos de nível de workspace, defina os seguintes valores no seu arquivo .databrickscfg:

   [<some-unique-configuration-profile-name>]
   host               = <workspace-url>
   google_credentials = <path-to-google-service-account-credentials-file>
   

   Observação

   O local padrão do arquivo .databrickscfg é no diretório inicial do usuário. É ~ para Linux e macOS, e %USERPROFILE% para Windows.

2. Use a opção --profile ou -p da CLI do Databricks, seguida pelo nome do seu perfil de configuração, como parte da chamada de comando da CLI do Databricks, por exemplo databricks account groups list -p <configuration-profile-name> ou databricks clusters list -p <configuration-profile-name>.

   Dica

   Você pode pressionar Tab após --profile ou -p para exibir a lista de perfis de configuração disponíveis existentes para escolher, em vez de inserir o nome do perfil de configuração manualmente.

Autenticação do Google Cloud ID

A autenticação do Google Cloud ID autentica a account de serviço do Google Cloud de destino. Veja Autenticação do Google Cloud ID.

Para configurar a autenticação do Google Cloud ID, o senhor deve ter a autenticação do Google Cloud ID instalada localmente. Você também deve fazer o seguinte:

1. Crie ou identifique um perfil de configuração do Databricks com os seguintes campos no arquivo .databrickscfg. Se você criar o perfil, substitua os placeholders pelos valores apropriados.

   Para comandos de nível de account, defina os seguintes valores no seu arquivo .databrickscfg:

   [<some-unique-configuration-profile-name>]
   host                   = <account-console-url>
   account_id             = <account-id>
   google_service_account = <google-cloud-service-account-email-address>
   

   Para comandos de nível de workspace, defina os seguintes valores no seu arquivo .databrickscfg:

   [<some-unique-configuration-profile-name>]
   host                   = <workspace-url>
   google_service_account = <google-cloud-service-account-email-address>
   

   Observação

   O local padrão do arquivo .databrickscfg é no diretório inicial do usuário. É ~ para Linux e macOS, e %USERPROFILE% para Windows.

2. Use a opção --profile ou -p do Databricks CLI seguida pelo nome do seu perfil de configuração, como parte da chamada de comando do Databricks CLI, por exemplo databricks clusters list -p <configuration-profile-name>.

   Dica

   Você pode pressionar Tab após --profile ou -p para exibir a lista de perfis de configuração disponíveis existentes para escolher, em vez de inserir o nome do perfil de configuração manualmente.

Ordem de autenticação da avaliação

Sempre que a CLI do Databricks precisa reunir as configurações necessárias para tentar se autenticar com um workspace ou account do Databricks, ela procura essas configurações nos seguintes locais, na seguinte ordem.

1. Para qualquer comando executado a partir do diretório de trabalho do bundle (a raiz do bundle e qualquer caminho aninhado), os valores dos campos dentro dos arquivos de configuração do bundle de um projeto. (Os arquivos de configuração do bundle não suportam a inclusão direta de valores de credenciais de acesso.)

2. Os valores das variáveis de ambiente, conforme listado neste artigo e em Campos e variáveis de ambiente para autenticação unificada do cliente.

3. Valores do campo de perfil de configuração no arquivo .databrickscfg , conforme indicado anteriormente neste artigo.

Sempre que a CLI do Databricks encontra as configurações necessárias, ele interrompe a pesquisa em outros locais. Por exemplo:

• A CLI do Databricks precisa do valor de um access token pessoal do Databricks. Uma variável de ambiente DATABRICKS_TOKEN é definida e o arquivo .databrickscfg também contém vários tokens de acesso pessoal. Neste exemplo, a CLI do Databricks utiliza o valor da variável de ambiente DATABRICKS_TOKEN e não pesquisa o arquivo .databrickscfg .

• O comando databricks bundle deploy -t dev precisa do valor de um access token pessoal do Databricks. Uma variável de ambiente DATABRICKS_TOKEN não é definida e o arquivo .databrickscfg contém vários access tokens pessoais. O arquivo de configurações do pacote do projeto contém uma declaração de ambiente dev que faz referência, por meio do campo profile, a um perfil de configuração denominado DEV. Neste exemplo, a CLI do Databricks pesquisa o arquivo .databrickscfg em busca de um perfil denominado DEV e utiliza o valor do campo token desse perfil.

• O comando databricks bundle run -t dev hello-job precisa do valor de um access token pessoal do Databricks. Uma variável de ambiente DATABRICKS_TOKEN não é definida e o arquivo .databrickscfg contém vários access tokens pessoais. O arquivo de configurações do pacote do projeto contém uma declaração de ambiente dev que faz referência, por meio do campo host, a uma URL específica do workspace do Databricks. Neste exemplo, a CLI do Databricks pesquisa os perfis de configuração no arquivo .databrickscfg em busca de um perfil que contenha um campo host com uma URL de workspace correspondente. A CLI do Databricks localiza um campo host correspondente e usa o valor do campo token desse perfil.