Configurar segredos externos no Catálogo Unity

Important

Esse recurso está em Beta.

Esta página mostra como conectar um esquema do Unity Catalog a um gerenciador de segredos externo para que seus valores secretos permaneçam no Azure Key Vault.

Para saber como funcionam segredos externos e suas limitações, veja Segredos externos no Catálogo Unity.

Requirements

• Atenda aos requisitos dos segredos do Unity Catalog.
• A Beta de segredos externos deve estar ativada no seu espaço de trabalho.
• O esquema que você quer fazer backup externamente não deve conter nenhum segredo gerenciado pelo Azure Databricks. Exclua segredos existentes antes de mudar o backend.
• Você deve ter uma conexão Unity Catalog com seu gerenciador de segredos externo e uma credencial de serviço Unity Catalog que a conexão use para autenticar. Para criar essas conexões, você deve ter USE CONNECTION em uma conexão existente ou CREATE CONNECTION na metastore para criar uma, e acesso a uma credencial de serviço, ou CREATE CREDENTIAL na metastore para criar uma.

• O suporte do Azure Key Vault está disponível apenas no Azure Databricks no Azure, usando uma conexão AZURE_KEY_VAULT.

Configurar segredos externos

Crie uma credencial de serviço

A conexão se autentica no seu gerenciador de segredos externo usando uma credencial de serviço do Unity Catalog.

Crie uma credencial de serviço com base em uma identidade gerenciada ou em um service principal e conceda a ela permissão para listar e ler os segredos do Key Vault de destino. Por exemplo, atribua a função Key Vault Secrets User ou uma política de acesso equivalente com permissões de segredo get e list. Para instruções, veja Criar credenciais de serviço.

Crie uma conexão

Crie uma conexão com o Unity Catalog que faça referência à credencial de serviço da etapa anterior e aponte para seu gerenciador de segredos externo.

Gerenciador de Catálogos

1. No Azure Databricks, abra o Explorador de Catálogo, clique no + menu e selecione Criar uma conexão.
2. Insira um nome de Conexão e selecione o tipo de conexão Azure Key Vault.
3. Selecione a credencial de serviço a ser usada para autenticação e defina o nome do cofre do Key Vault.
4. Clique em Criar.

CLI do Databricks

Passe o corpo da conexão com --json, usando o tipo de conexão AZURE_KEY_VAULT. Defina vault_name para o nome do seu Key Vault e credential para o nome da credencial de serviço:

databricks connections create --json '{
  "name": "my_key_vault_connection",
  "connection_type": "AZURE_KEY_VAULT",
  "options": {
    "vault_name": "my-vault",
    "credential": "my_key_vault_credential"
  }
}'

API REST

Use o endpoint /api/2.1/unity-catalog/connections com o tipo de conexão AZURE_KEY_VAULT. Azure Databricks resolve vault_name para https://<vault_name>.vault.azure.net:

curl -X POST \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "my_key_vault_connection",
    "connection_type": "AZURE_KEY_VAULT",
    "options": {
      "vault_name": "my-vault",
      "credential": "my_key_vault_credential"
    }
  }' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/connections"

Fazer backup de um schema usando a conexão

Configure o backend secreto do esquema no Explorador de Catálogos.

1. No Azure Databricks, abra o Explorador de Catálogos e vá até o esquema.

2. Nos detalhes do esquema, localize a configuração externa do gerenciador de segredos e clique em Ativar.

   O esquema não deve conter nenhum segredo gerenciado pelo Azure Databricks. Se aparecer, remova-os primeiro. Habilitar permanece desativado até que o esquema não tenha segredos.

3. Selecione a conexão que você criou na etapa anterior e confirme.

O esquema agora é respaldado pelo seu gerenciador de segredos externo, e seus segredos aparecem no Unity Catalog.

Para apontar o esquema para uma conexão diferente, use Edit. Para retornar o esquema ao armazenamento gerenciado pelo Azure Databricks, edite o esquema e desative segredos externos.

Definir ou alterar o back-end de segredos de um esquema requer USE CATALOG no catálogo pai, a propriedade do esquema ou MANAGE no esquema, e USE CONNECTION na conexão.

Leia segredos externos

Depois que o esquema é respaldado externamente, seus segredos aparecem no Catálogo Unity e você os lê como qualquer outro segredo do Catálogo Unity. Listar um esquema aciona uma importação, então um segredo recém-adicionado aparece apenas após a próxima lista. Os comandos de leitura são os mesmos em ambas as nuvens.

Dbutils

dbutils Aplica redação secreta e é a forma recomendada de ler um valor. Requer o Databricks Runtime 17.3 LTS ou superior, ou ambiente serverless na versão 4 ou superior.

# List the secrets in the schema
all_secrets = dbutils.secrets.list(catalog="main", schema="default")

# Read a specific secret value from the external secret manager
my_secret = dbutils.secrets.get(catalog="main", schema="default", key="example_secret")

API REST

Defina include_value=true e leia o effective_value campo para devolver o valor. A API REST não redige valores retornados, embora ainda audite o acesso; o Azure Databricks recomenda dbutils em vez disso.

curl -G \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  --data-urlencode "include_value=true" \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.default.example_secret"

Você também pode navegar e listar segredos externos no Explorador de Catálogos, da mesma forma que os segredos gerenciados pelo Azure Databricks. Veja Leia um segredo.

Se um segredo ainda não aparecer no Catálogo da Unity, você ainda pode lê-lo pelo nome. Forneça o nome como aparece no gerenciador de segredos externo, com as substituições de caracteres das restrições de nomenclatura aplicadas.

Recursos adicionais

Característica	Descrição
Segredos externos no Catálogo Unity	Aprenda como o Unity Catalog importa, governa e lê segredos respaldados externamente, e revise as limitações.
Segredos no Unity Catalog	Crie, governe e gerencie segredos que o Azure Databricks armazena no Unity Catalog.
Criar credenciais de serviço	Crie a credencial de serviço do Unity Catalog que a conexão usa para autenticar.