Autenticação para a CLI do Databricks

Observação

Esta informação se aplica às versões 0.205 e acima do Databricks CLI, que estão em Public Preview. Para encontrar sua versão da CLI do Databricks, execute databricks -v.

Este artigo descreve como configurar a autenticação entre a CLI do Databricks e sua account e workspace 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 o comando CLI do Databricks, você deve configurar a autenticação entre a CLI do Databricks e sua account do Databricks, workspace ou uma combinação destes, dependendo dos tipos de comando CLI que você deseja executar.

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

Observação

A CLI do Databricks implementa o padrão de autenticação unificada do cliente Databricks , uma abordagem arquitetônica e programática consolidada e consistente para autenticação. Esta abordagem ajuda a tornar a configuração e a automação da autenticação com Databricks mais centralizada e previsível. Ele permite que você configure a autenticação do Databricks uma vez e, em seguida, use essa configuração em várias ferramentas e SDKs do Databricks sem mais alterações na configuração de autenticação. Para obter mais informações sobre este padrão, consulte Autenticação unificada do cliente 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 access token pessoal do Databricks

A autenticação access tokenpessoal do Databricks usa um access token pessoal do Databricks para autenticar a entidade Databricks de destino, como uma account de usuário do Databricks ou uma entidade de serviço do Databricks. Consulte também Autenticação access token pessoal do Databricks.

Observação

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

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

  1. No workspace do Databricks, clique no nome de usuário do Databricks na barra superior e selecione Configurações do usuário na lista suspensa.

  2. Clique em Desenvolvedor.

  3. Ao lado do access token, clique em gerenciar.

  4. Clique em Gerar novos tokens.

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

  6. Clique em Gerar.

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

Observação

Certifique-se de salvar os tokens copiados em um local seguro. Não compartilhe seus tokens copiados com outras pessoas. Se você perder os tokens copiados, não poderá regenerar exatamente os mesmos tokens. Em vez disso, você deve repetir este procedimento para criar novos tokens. Se você perder os tokens copiados ou acreditar que os tokens foram comprometidos, o Databricks recomenda fortemente que você exclua imediatamente esses tokens do seu workspace clicando no ícone da lixeira (Revogar) ao lado dos tokens na página access tokens .

Se não for possível criar ou usar tokens no seu workspace, isso pode ocorrer porque o administrador do workspace desativou os tokens ou não lhe deu permissão para criar ou usar tokens. Consulte o administrador do workspace ou o seguinte:

Para configurar e usar a autenticação 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á possui um perfil de configuração DEFAULT que deseja usar, ignore este procedimento. Caso contrário, este procedimento substituirá seu perfil de configuração DEFAULT existente. Para view os nomes e hosts de quaisquer perfis de configuração existentes, 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 espaço de trabalho do Databricks, por exemplo https://1234567890123456.7.gcp.databricks.com.

  3. Para o prompt access tokenpessoal, 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 default , ele primeiro criará esse arquivo para você e depois adicionará esse perfil de configuração ao novo arquivo. O local default para esse arquivo é ~ (seu usuário pasta home no Unix, Linux ou macOS, ou %USERPROFILE% (seu usuário pasta home no Windows.

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

Autenticação OAuth máquina a máquina (M2M)

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

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 Autenticação OAuth máquina a máquina (M2M)

  2. Crie ou identifique um perfil de configuração do Databricks com os campos a seguir em seu arquivo .databrickscfg . Se você criar o perfil, substitua os espaços reservados pelos valores apropriados.

    Para o comando account-level, defina os seguintes valores no 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 o comando workspace-level, defina os seguintes valores no 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 default do arquivo .databrickscfg é o diretório inicial do usuário. Isto é ~ para Linux e macOS e %USERPROFILE% para Windows.

  3. Use a opção --profile ou -p da CLI do Databricks seguida do nome do perfil de configuração como parte da chamada do 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 depois de --profile ou -p para exibir uma lista de perfis de configuração disponíveis existentes para escolha, em vez de digitar o nome do perfil de configuração manualmente.

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

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

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

  1. Antes de chamar qualquer comando de nível de accountdo Databricks, você deve iniciar o gerenciamento tokens OAuth localmente executando o comando a seguir. Este comando deve ser executado separadamente para cada account na qual você deseja executar comandos. Se você não quiser chamar nenhuma transação no nível account , pule para o passo 5.

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

    databricks auth login --host <account-console-url> --account-id <account-id>
    
  2. A CLI do Databricks solicita que você salve a URL do console account e o ID account localmente como um perfil de configuração do Databricks. Pressione Enter para aceitar o nome de perfil sugerido ou digite o nome de um perfil novo ou existente. Qualquer perfil existente com o mesmo nome será substituído pelo URL e ID account do account da conta.

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

  3. No seu navegador da Web, siga as instruções na tela para log in na sua account do Databricks.

  4. Para view o valor atual tokens OAuth e o carimbo de data/hora de expiração futuro, execute o comando databricks auth token --host <account-console-url> --account-id <account-id>.

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

    No comando a seguir, substitua <workspace-url> pela URL da instância do espaço de trabalho do Databricks, por exemplo https://1234567890123456.7.gcp.databricks.com.

    databricks auth login --host <workspace-url>
    
  6. A CLI do Databricks solicita que você salve a URL workspace localmente como um perfil de configuração do Databricks. Pressione Enter para aceitar o nome de perfil sugerido ou digite o nome de um perfil novo ou existente. Qualquer perfil existente com o mesmo nome será substituído por esta URL workspace .

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

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

  8. Para view o valor atual tokens OAuth e o carimbo de data/hora de expiração futuro, execute o comando databricks auth token --host <workspace-url>.

  9. Use a opção --profile ou -p da CLI do Databricks seguida do 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 uma lista de perfis de configuração existentes disponíveis para escolha, em vez de inserir o nome do perfil de configuração manualmente.

Autenticação de credenciais do Google Clouds

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

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

  1. Crie ou identifique um perfil de configuração do Databricks com os campos a seguir em seu arquivo .databrickscfg . Se você criar o perfil, substitua os espaços reservados pelos valores apropriados.

    Para o comando account-level, defina os seguintes valores no 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 o comando workspace-level, defina os seguintes valores no arquivo .databrickscfg:

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

    Observação

    O local default do arquivo .databrickscfg é o diretório inicial do usuário. Isto é ~ para Linux e macOS e %USERPROFILE% para Windows.

  2. Use a opção --profile ou -p da CLI do Databricks seguida do 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 uma lista de perfis de configuração existentes disponíveis para escolha, em vez de inserir o nome do perfil de configuração manualmente.

Autenticação de ID de nuvens do Google

A autenticação doID de do Google autentica a de clouds clouds serviço de do Google de account destino. Consulte Autenticação de ID clouds do Google.

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

  1. Crie ou identifique um perfil de configuração do Databricks com os campos a seguir em seu arquivo .databrickscfg . Se você criar o perfil, substitua os espaços reservados pelos valores apropriados.

    Para o comando account-level, defina os seguintes valores no 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 o comando workspace-level, defina os seguintes valores no arquivo .databrickscfg:

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

    Observação

    O local default do arquivo .databrickscfg é o diretório inicial do usuário. Isto é ~ para Linux e macOS e %USERPROFILE% para Windows.

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

    Dica

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

Ordem de avaliação da autenticação

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

  1. Para o comando bundle , os valores dos campos nos arquivos de configuração do pacote configurável de um projeto. (Os arquivos de configuração de pacote não suportam a inclusão direta de valores de credenciais de acesso.)

  2. Os valores da variável de ambiente, conforme listado nestes artigos e na variável de ambiente e campos para autenticação unificada do cliente.

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

Sempre que a CLI do Databricks encontra as configurações necessárias, ela para de pesquisar 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 access token pessoal. Neste exemplo, a CLI do Databricks usa o valor da variável de ambiente DATABRICKS_TOKEN e não pesquisa o arquivo .databrickscfg .

  • O comando databricks bundle deploy -e development precisa do valor de um access token pessoal do Databricks. Uma variável de ambiente DATABRICKS_TOKEN não está definida e o arquivo .databrickscfg contém vários access token pessoal . O arquivo de configurações do pacote configurável do projeto contém uma declaração de ambiente development que faz referência por meio de seu 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 chamado DEV e usa o valor do campo token desse perfil.

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