Habilitar chaves gerenciadas pelo cliente para serviços gerenciados

Artigo
09/12/2024

Observação

Esse recurso requer o plano Premium.

Para ter controle adicional de seus dados, adicione sua própria chave para proteger e controlar o acesso a alguns tipos de dados. O Azure Databricks tem vários recursos de chave gerenciados pelo cliente. Para comparar os recursos relacionados, confira Chaves gerenciadas pelo cliente para criptografia.

Dica

Este artigo descreve como configurar sua própria chave a partir dos cofres do Azure Key Vault para serviços gerenciados. Para obter instruções sobre como usar uma chave do HSM Gerenciado do Azure Key Vault, consulte Habilitar chaves HSM gerenciadas pelo cliente para serviços gerenciados.

Os dados de serviços gerenciados no plano de controle do Azure Databricks são criptografados em repouso. É possível adicionar uma chave gerenciada pelo cliente para serviços gerenciados a fim de ajudar a proteger e controlar o acesso aos seguintes tipos de dados criptografados:

Fonte do notebook no plano de controle do Azure Databricks.
Os resultados de notebooks executados interativamente (não como trabalhos) armazenados no plano de controle. Por padrão, resultados maiores também são armazenados no bucket raiz do workspace. É possível configurar o Azure Databricks para armazenar todos os resultados de notebook interativos na sua conta de nuvem.
Segredos armazenados pelas APIs do gerenciador de segredos.
Consultas e histórico de consultas do SQL do Databricks.
Tokens de acesso pessoal (PAT) ou outras credenciais usadas para configurar a integração do Git com as pastas Git do Databricks.

Depois que você adiciona uma criptografia de chave gerenciada pelo cliente para um workspace, o Azure Databricks usa sua chave a fim de controlar o acesso à chave que criptografa operações de gravação futuras nos dados de serviços gerenciados do workspace. Os dados existentes não são criptografados novamente. A chave de criptografia de dados é armazenada em cache na memória para várias operações de leitura e gravação e é removida da memória em um intervalo regular. Novas solicitações para esses dados exigem outra solicitação para o sistema de gerenciamento de chaves do serviço de nuvem. Ao excluir ou revogar sua chave, ocorrerá uma falha na leitura ou gravação nos dados protegidos ao final do intervalo de tempo do cache.

É possível girar (atualizar) a chave gerenciada pelo cliente posteriormente. Consulte Girar a chave posteriormente.

Esse recurso não criptografa os dados armazenados fora do painel de controle. Para outros recursos de chave gerenciada pelo cliente, confira Chaves gerenciadas pelo cliente para criptografia

Requisitos

Para usar a CLI do Azure para essas tarefas, instale a ferramenta da CLI do Azure e instale a extensão do Databricks:
```
az extension add --name databricks
```
Para usar o PowerShell para essas tarefas, instale Azure PowerShell e instale o módulo do Databricks Powershell. Você também deve fazer logon:
```
Connect-AzAccount
```
Para iniciar sessão na sua conta do Azure como utilizador, consulte Iniciar sessão do PowerShell com uma conta de utilizador do Azure Databricks. Para iniciar sessão na sua conta do Azure como entidade de serviço, consulte Iniciar sessão do PowerShell com uma entidade de serviço do Microsoft Entra ID.

Etapa 1: configurar um Key Vault

Você deve criar uma instância do Azure Key Vault e definir suas permissões. Você pode fazer isso por meio do portal do Azure, da CLI ou de APIs.

Importante

O Key Vault deve estar no mesmo locatário do Azure que o workspace do Azure Databricks.

Essas instruções oferecem detalhes sobre várias opções de implantação:

Usar o Portal do Azure
Usar a CLI do Azure
Usar o Azure Powershell

Use o portal do Azure

Criar ou selecionar um Key Vault:
- Para criar um Key Vault, acesse a página do portal do Azure para criar um Cofre de Chaves. Clique em + Criar. Insira o nome do grupo de recursos, o nome do Key Vault, a região e o tipo de preços. Clique em Revisar + criar e em Criar.
- Para usar um Key Vault existente, copie o nome do Key Vault para a próxima etapa.
Obter a ID do objeto do aplicativo AzureDatabricks:
1. No portal do Azure, acesse Microsoft Entra ID.
2. Selecione Aplicativos Empresariais no menu da barra lateral.
3. Pesquise AzureDatabricks e clique no Aplicativo Empresarial nos resultados.
4. Em Propriedades, copie a ID do objeto.
Adicionar uma política de acesso ao Key Vault usando o portal do Azure:
1. Navegue até o Azure Key Vault que você usará para configurar as chaves gerenciadas pelo cliente para os serviços gerenciados para seu espaço de trabalho.
2. Clique na guia Políticas de acesso no painel do lado esquerdo.
3. Selecione o botão Criar encontrado na parte superior da página.
4. Na seção Permissões de chave, na guia Permissões, habilite Get, Desencapsular chave e Encapsular chave.
5. Clique em Próximo.
6. Na guia Principal, digite AzureDatabricks e role para o primeiro resultado do Aplicativo Empresarial com uma ID de Aplicativo de 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d e selecione-o.
7. Continue para a guia Revisar + criar e clique em b.

Use a CLI do Azure

Usar a CLI do Azure para concluir as instruções a seguir.

Criar um Key Vault ou selecionar um Key Vault existente:
- Para criar um Key Vault, use o seguinte comando da CLI do Azure e substitua os itens entre colchetes pela sua região, nome do Key Vault, nome do grupo de recursos e localização:
```
az keyvault create --location <region> \
                   --name <key-vault-name> \
                   --resource-group <resource-group-name> \
                   --location <location> \
                   --enable-purge-protection
```
- Para usar um Key Vault existente, copie o nome do Key Vault para a próxima etapa.

Obtenha a ID do objeto do aplicativo AzureDatabricks com a CLI do Azure.

az ad sp show --id "2ff814a6-3304-4ab8-85cb-cd0e6f879c1d" \
              --query "id" \
              --output tsv

Confirme que você está usando a assinatura correta do Azure:
```
az account set --subscription {subscription_id}
```

Use o Azure Powershell

Você pode criar um Key Vault ou usar um existente.

Criar um cofre de chaves:

$keyVault = New-AzKeyVault -Name <key-vault-name> \
-ResourceGroupName <resource-group-name> \
-Location <location> \
-sku <sku> \
-EnablePurgeProtection

Usar um Key Vault existente:

$keyVault = Get-AzKeyVault -VaultName <key-vault-name>

Etapa 2: preparar uma chave

Você cria uma chave ou usa uma chave existente. Use as ferramentas que preferir usar: portal do Azure, CLI do Azure ou outras ferramentas.

Usar a CLI do Azure

Criar uma chave no Key Vault. O KeyType deve ser RSA.

Para criar a chave na CLI, execute este comando:

az keyvault key create --name <key-name> \
                       --vault-name <key-vault-name> \
                       --protection software

Anote os valores a seguir, que você pode obter na ID da chave na propriedade kid na resposta. Você o usará em etapas subsequentes:

URL do Key Vault: a parte inicial da ID da chave que inclui o nome do Key Vault. Ele tem o formato https://<key-vault-name>.vault.azure.net.
Nome da chave: nome da sua chave.
Versão da chave: a versão da chave.

A ID da chave completa geralmente tem o formulário https://<key-vault-name>.vault.azure.net/keys/<key-name>/<key-version>. As chaves de Key Vault do Azure que estão em uma nuvem não pública têm um formulário diferente.

Para usar uma chave existente, ao invés de criar uma, obtenha e copie esses valores para sua chave para que você possa usá-los nas próximas etapas. Verifique se a chave existente está habilitada antes de continuar.

Usar o Azure Powershell

Se você planeja criar uma chave, talvez seja necessário definir a política de acesso, dependendo de como e quando a criou. Por exemplo, se você criou recentemente o Key Vault usando o PowerShell, seu novo Key Vault poderá não ter a política de acesso necessária para criar uma chave. O exemplo a seguir usa o parâmetro EmailAddress para definir a política. Para obter detalhes relacionados, consulte o artigo da Microsoft sobre Set-AzKeyVaultAccessPolicy.

Defina a política de acesso em um novo Key Vault:
```
Set-AzKeyVaultAccessPolicy \
-VaultName $keyVault.VaultName \
-PermissionsToKeys all \
-EmailAddress <email-address>
```

Você pode criar uma chave ou recuperar uma chave existente:

Criar uma chave:

$key = Add-AzKeyVaultKey \
-VaultName $keyVault.VaultName \
-Name <key-name> \
-Destination 'Software'

Recupere uma chave existente:

$key = Get-AzKeyVaultKey \
-VaultName $keyVault.VaultName \
-Name <key-name>

Adicione uma política de acesso com permissões ao Key Vault:

$managedService = Get-AzureADServicePrincipal \
-Filter "appId eq '2ff814a6-3304-4ab8-85cb-cd0e6f879c1d'"

Set-AzKeyVaultAccessPolicy -VaultName $keyVault.VaultName \
-ObjectId $managedService.ObjectId \
-PermissionsToKeys wrapkey,unwrapkey,get

Etapa 3: adicionar uma chave a um espaço de trabalho

Você pode implantar um novo espaço de trabalho com uma chave gerenciada pelo cliente para serviços gerenciados ou adicionar uma chave a um espaço de trabalho existente. Você pode fazer as duas coisas com os modelos do ARM, Powershell, CLI do Azure, portal do Azure ou outras ferramentas. Esta seção inclui os detalhes de várias opções de implantação:

Usar o portal do Azure sem modelo
Usar a CLI do Azure sem modelo
Usar o Powershell sem modelo
Aplicar alterações com um modelo do ARM

Usar o portal do Azure sem modelo

Acesse a página inicial do Portal do Azure.
Clique em Criar um recurso no canto superior esquerdo da página.
Na barra de pesquisa, digite Azure Databricks e clique na opção Azure Databricks.
Clique em Criar no widget Azure Databricks.
Insira valores dos campos de entrada nas guias Básico e Rede.
Depois de alcançar a guia Criptografia:
- Para criar um espaço de trabalho, habilite Usar sua própria chave na seção Serviços Gerenciados.
- Para atualizar um espaço de trabalho, habilite os Serviços Gerenciados.
Defina os campos de criptografia.
- No campo Identificador de Chave, cole o Identificador de Chave da sua chave do Azure Key Vault.
- No menu suspenso Assinatura, insira o nome da assinatura da sua chave do Azure Key Vault.
Complete as guias restantes e clique em Revisar + Criar (para o novo espaço de trabalho) ou Salvar (para atualizar um espaço de trabalho).

Importante

Se você girar a chave, deverá manter a chave antiga disponível por 24 horas.

Usar a CLI do Azure sem modelo

Adicione uma política de acesso ao Key Vault com o seguinte comando. Substitua <key-vault-name> pelo nome do cofre que você usou na etapa anterior e substitua <object-id> pela ID do objeto do aplicativo AzureDatabricks.
```
az keyvault set-policy -n <key-vault-name> \
                       --key-permissions get wrapKey unwrapKey  \
                       --object-id <object-id>
```

Criar ou atualizar um espaço de trabalho:

Para criação e atualização, adicione estes campos ao comando:

managed-services-key-name: Nome da chave
managed-services-key-vault: Key Vault URI
managed-services-key-version: Versão da chave

Exemplo de criação de um espaço de trabalho usando estes campos:

az databricks workspace create --name <workspace-name> \
--resource-group <resource-group-name> \
--location <location> \
--sku premium \
--managed-services-key-name <key-name> \
--managed-services-key-vault <key-vault-uri> \
--managed-services-key-version <key-version>

Exemplo de atualização de um espaço de trabalho usando estes campos:

az databricks workspace update --name <workspace-name> \
--resource-group <resource-group-name> \
--managed-services-key-name <key-name> \
--managed-services-key-vault <key-vault-uri> \
--managed-services-key-version <key-version>

Importante

Se você girar a chave, deverá manter a chave antiga disponível por 24 horas.

Usar o Powershell sem modelo

Para criar ou atualizar um espaço de trabalho, adicione os seguintes parâmetros ao comando para sua nova chave:

ManagedServicesKeyVaultPropertiesKeyName: Nome da chave
ManagedServicesKeyVaultPropertiesKeyVaultUri: URI da Chave
ManagedServicesKeyVaultPropertiesKeyVersion: Versão da chave

Exemplo de criação de espaço de trabalho com estes campos:

New-AzDatabricksWorkspace -Name <workspace-name> \
-ResourceGroupName <resource-group-name> \
-location $keyVault.Location \
-sku premium \
-ManagedServicesKeyVaultPropertiesKeyName $key.Name \
-ManagedServicesKeyVaultPropertiesKeyVaultUri $keyVault.VaultUri \
-ManagedServicesKeyVaultPropertiesKeyVersion $key.Version

Exemplo de atualização de espaço de trabalho com estes campos:

Update-AzDatabricksWorkspace -Name <workspace-name> \
-ResourceGroupName <resource-group-name> \
-sku premium \
-ManagedServicesKeyVaultPropertiesKeyName $key.Name \
-ManagedServicesKeyVaultPropertiesKeyVaultUri $keyVault.VaultUri \
-ManagedServicesKeyVaultPropertiesKeyVersion $key.Version

Importante

Se você girar a chave, deverá manter a chave antiga disponível por 24 horas.

Aplicar alterações com um modelo do ARM

O modelo de ARM a seguir cria um novo espaço de trabalho com uma chave gerenciada pelo cliente, usando a versão da API 2023-02-01 para o recurso Microsoft.Databricks/workspaces. Salve esse texto localmente em um arquivo chamado databricks-cmk-template.json.

Esse modelo de exemplo não inclui todos os recursos possíveis do Azure Databricks, como fornecer sua própria VNet para implantar o espaço de trabalho.

Importante

Se você já usa um modelo, mescle os parâmetros, recursos e saídas extras desse modelo no seu modelo existente.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "workspaceName": {
      "type": "string",
      "metadata": {
        "description": "The name of the Azure Databricks workspace to create."
      }
    },
    "pricingTier": {
      "type": "string",
      "defaultValue": "premium",
      "allowedValues": [
        "standard",
        "premium"
      ],
      "metadata": {
        "description": "The pricing tier of workspace."
      }
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]",
      "metadata": {
        "description": "Location for all resources."
      }
    },
    "apiVersion": {
      "type": "string",
      "defaultValue": "2023-02-01",
      "allowedValues":[
        "2023-02-01",
        "2021-04-01-preview"
      ],
      "metadata": {
        "description": "The api version to create the workspace resources"
      }
    },
    "keyvaultUri": {
      "type": "string",
      "metadata": {
        "description": "The Key Vault URI for customer-managed key for managed services"
      }
    },
    "keyName": {
      "type": "string",
      "metadata": {
        "description": "The key name used for customer-managed key for managed services"
      }
    },
    "keyVersion": {
      "type": "string",
      "metadata": {
        "description": "The key version used for customer-managed key for managed services"
      }
    }
  },
  "variables": {
    "managedResourceGroupName": "[concat('databricks-rg-', parameters('workspaceName'), '-', uniqueString(parameters('workspaceName'), resourceGroup().id))]"
  },
  "resources": [
    {
      "type": "Microsoft.Databricks/workspaces",
      "name": "[parameters('workspaceName')]",
      "location": "[parameters('location')]",
      "apiVersion": "[parameters('apiVersion')]",
      "sku": {
        "name": "[parameters('pricingTier')]"
      },
      "properties": {
        "ManagedResourceGroupId": "[concat(subscription().id, '/resourceGroups/', variables('managedResourceGroupName'))]",
        "encryption": {
          "entities": {
             "managedServices": {
                "keySource": "Microsoft.Keyvault",
                "keyVaultProperties": {
                   "keyVaultUri": "[parameters('keyvaultUri')]",
                   "keyName": "[parameters('keyName')]",
                   "keyVersion": "[parameters('keyVersion')]"
                }
             }
          }
        }
      }
    }
  ],
  "outputs": {
    "workspace": {
      "type": "object",
      "value": "[reference(resourceId('Microsoft.Databricks/workspaces', parameters('workspaceName')))]"
    }
  }
}

Se você já usa um outro modelo, você pode mesclar os parâmetros, os recursos e as saídas desse modelo em seu modelo existente.

Para usar este modelo para criar ou atualizar um espaço de trabalho, escolha uma dessas opções de implantação:

Aplicar um modelo com a CLI do Azure
Aplicar um modelo com o portal do Azure

Aplicar um modelo com a CLI do Azure

Para criar um novo workspace com a CLI do Azure, execute o seguinte comando:

az deployment group create --resource-group <resource-group-name>  \
                           --template-file <file-name>.json \
                           --parameters workspaceName=<new-workspace-name> \
                           keyvaultUri=<keyvaultUrl> \
                           keyName=<keyName> keyVersion=<keyVersion>

Para atualizar um workspace existente para usar um workspace de chave gerenciada pelo cliente (ou girar a chave existente) usando a CLI do Azure:

Se o modelo do ARM que implantou o workspace nunca adicionou chaves gerenciadas pelo cliente, adicione resources.properties.encryption a seção e seus parâmetros relacionados. Veja o modelo no início deste artigo.
1. Adicione a seção resources.properties.encryption do modelo.
2. Na seção parameters, adicione três novos parâmetros keyvaultUri, keyNamee keyVersion do modelo.
3. Na seção parameters, remova "type": "string", do modelo.
Execute o mesmo comando para criar um novo workspace. Desde que o nome do grupo de recursos e o nome do workspace sejam idênticos ao workspace existente, esse comando atualiza o workspace existente em vez de criar um novo workspace.
```
az deployment group create --resource-group <existing-resource-group-name>  \
                           --template-file <file-name>.json \
                           --parameters workspaceName=<existing-workspace-name> \
                           keyvaultUri=<keyvaultUrl> \
                           keyName=<keyName> keyVersion=<keyVersion>
```
Além das alterações nos parâmetros relacionados à chave, use os mesmos parâmetros que foram usados para criar o workspace.

Importante

Se você girar a chave, deverá manter a chave antiga disponível por 24 horas.

Aplicar um modelo com o portal do Azure

Para usar o modelo no portal do Azure para criar ou atualizar um workspace:

Vá até a página Implantação personalizada.
Clique em Criar seu próprio modelo no editor.
Cole no JSON.
Clique em Save (Salvar).
Preencha os parâmetros.

Para atualizar um workspace existente, use os mesmos parâmetros que você usou para criar o workspace. Para adicionar uma chave pela primeira vez, adicione os três parâmetros relacionados à chave. Para girar a chave, altere alguns ou todos os parâmetros relacionados à chave. Verifique se o nome do grupo de recursos e o nome do workspace são idênticos ao workspace existente. Se eles são iguais, esse comando atualiza o workspace existente em vez de criar um novo workspace.

Além das alterações nos parâmetros relacionados à chave, use os mesmos parâmetros que foram usados para criar o workspace.
Clique em Examinar + Criar.
Se não houver problemas de validação, clique em Criar.

Importante

Se você girar a chave, deverá manter a chave antiga disponível por 24 horas.

Para obter mais detalhes, confira o artigo do Azure Início Rápido: Criar e implantar modelos do ARM usando o portal do Azure.

Etapa 4 (opcional): importar notebooks novamente

Depois de adicionar uma chave de serviços gerenciados para um workspace existente, somente operações de gravação futuras usarão sua chave. Os dados existentes não são criptografados novamente.

É possível exportar todos os notebooks e importá-los novamente para que a chave que criptografa os dados seja protegida e controlada por sua chave. Você pode usar as APIs Exportar e Importar workspace.

Girar a chave posteriormente

Se você já estiver usando uma chave gerenciada pelo cliente para serviços gerenciados, poderá atualizar o workspace com uma nova versão de chave ou uma chave totalmente nova. Isso é chamado de rotação de chave.

Crie uma nova chave ou gire sua chave existente no Key Vault. Consulte Etapa 1: configurar um Key Vault.

Verifique se a nova chave tem a permissões apropriadas.
Confirme se o seu modelo tem a versão correta da API. Ele deve ser igual ou maior que 2021-04-01-preview.
Atualize o espaço de trabalho com sua nova chave usando o portal, a CLI ou o PowerShell. Consulte Etapa 3: Adicionar uma chave a um espaço de trabalho e siga as instruções para atualização do espaço de trabalho. Certifique-se de usar os mesmos valores para o nome do grupo de recursos e o nome do espaço de trabalho para que ele atualize o espaço de trabalho existente, em vez de criar um novo espaço de trabalho. Além das alterações nos parâmetros relacionados à chave, use os mesmos parâmetros que foram usados para criar o workspace.

Importante

Se você girar a chave, deverá manter a chave antiga disponível por 24 horas.
Opcionalmente, exporte e reimporte notebooks existentes para garantir que todos os notebooks existentes usem sua nova chave.

Solução de problemas

Exclusão acidental de uma chave

Se você excluir sua chave no Azure Key Vault, o logon do workspace começará a falhar e nenhum notebook poderá ser lido pelo Azure Databricks. Para evitar isso, recomendamos que você habilite as exclusões temporárias. Essa opção garante que, se uma chave for excluída, ela poderá ser recuperada em um período de 30 dias. Se a exclusão temporária estiver habilitada, você poderá simplesmente reabilitar a chave para resolver o problema.

Falha de atualização da chave devido às permissões do Key Vault

Se você tiver problemas para criar seu espaço de trabalho, verifique se o Key Vault tem as permissões corretas. O erro retornado do Azure pode não indicar corretamente isso como a causa raiz. Além disso, as permissões necessárias são get, wrapKeye unwrapKey. Consulte Etapa 1: configurar um Key Vault.

Chaves perdidas são irrecuperáveis

Se você perder sua chave e não puder recuperar, todos os dados do notebook criptografados pela chave serão irrecuperáveis.

Compartilhar via

Habilitar chaves gerenciadas pelo cliente para serviços gerenciados

Requisitos

Etapa 1: configurar um Key Vault

Use o portal do Azure

Use a CLI do Azure

Use o Azure Powershell

Etapa 2: preparar uma chave

Usar a CLI do Azure

Usar o Azure Powershell

Etapa 3: adicionar uma chave a um espaço de trabalho

Usar o portal do Azure sem modelo

Usar a CLI do Azure sem modelo

Usar o Powershell sem modelo

Aplicar alterações com um modelo do ARM

Aplicar um modelo com a CLI do Azure

Aplicar um modelo com o portal do Azure

Etapa 4 (opcional): importar notebooks novamente

Girar a chave posteriormente

Solução de problemas

Exclusão acidental de uma chave

Falha de atualização da chave devido às permissões do Key Vault

Chaves perdidas são irrecuperáveis

Comentários

Recursos adicionais