Crie uma credencial de armazenamento para se conectar ao AWS S3

Este artigo descreve como criar uma credencial de armazenamento no Unity Catalog para conectar ao AWS S3.

Para gerenciar o acesso ao armazenamento da nuvem subjacente que contém tabelas e volumes, o Unity Catalog utiliza os seguintes tipos de objeto:

As credenciais de armazenamento encapsulam uma credencial de nuvem de longo prazo que oferece acesso ao armazenamento na nuvem.
Os locais externos contêm uma referência a uma credencial de armazenamento e um caminho de armazenamento na nuvem.

Para mais informações, consulte Conectar ao armazenamento de objetos na nuvem com o Unity Catalog.

O Unity Catalog oferece suporte a duas opções de armazenamento em nuvem para o Databricks na AWS: buckets do AWS S3 e buckets do Cloudflare R2. O Cloudflare R2 destina-se principalmente a casos de uso de Delta Sharing nos quais você deseja evitar taxas de saída de dados. O S3 é apropriado para a maioria dos outros casos de uso. Este artigo se concentra na criação de credenciais de armazenamento para o S3. Para o Cloudflare R2, consulte Criar uma credencial de armazenamento para se conectar ao Cloudflare R2.

Para criar uma credencial de armazenamento para acesso a um bucket S3, você cria uma IAM role que autoriza o acesso (leitura, ou leitura e gravação) ao caminho do bucket S3 e faz referência a essa IAM role na definição da credencial de armazenamento.

Requisitos

No Databricks:

Um workspace do Databricks ativado para o Unity Catalog.
CREATE STORAGE CREDENTIAL privilégio no metastore do Unity Catalog anexado ao workspace. Os administradores de contas e administradores do metastore têm esse privilégio por padrão.

Na sua conta da AWS:

Um bucket S3 na mesma região que os workspaces dos quais você deseja acessar os dados.

O nome do bucket não pode incluir notação de ponto (por exemplo, incorrect.bucket.name.notation). Para mais orientações sobre nomenclatura de buckets, consulte as regras de nomenclatura de buckets da AWS.
A capacidade de criar IAM roles.

Passo 1: criar uma IAM role

Na AWS, crie uma IAM role que conceda acesso ao bucket S3 que você deseja que seus usuários acessem. Essa IAM role deve ser definida na mesma account que o bucket do S3.

Dica

Se você já criou uma IAM role que oferece esse acesso, pode pular esta passo e ir direto para a passo 2: dar ao Databricks os detalhes da IAM role.

Crie uma IAM role que permitirá acesso ao bucket S3.

O processo de criação de função divide-se em dois passos. Neste passo, você cria a função, adicionando uma policy de relacionamento de confiança temporária e um ID externo de placeholder que você modifica após criar a credencial de armazenamento no Databricks.

Você deve modificar a policy de confiança após criar a função, pois ela deve ser autoassumida (ou seja, deve ser configurada para confiar em si mesma). A função deve, portanto, existir antes de você adicionar a instrução de autossuposição. Para obter informações sobre funções autoassumidas, consulte este artigo do blog da Amazon.

Importante

A partir de 20 de setembro de 2024, o Databricks começará a impor a exigência de autoassumir para novas credenciais de armazenamento. Em 20 de janeiro de 2025, o Databricks começará a bloquear credenciais de armazenamento existentes que não são autoassumidas. Para mais detalhes, consulte a Política de imposição de função autoassumida.

Para criar a política, você deve usar uma ID externa de placeholder. Um ID externo é necessário na AWS para conceder acesso aos seus recursos da AWS a terceiros.
1. Crie a IAM role com uma policy de confiança personalizada.
2. No campo Policy de confiança personalizada, cole o JSON da policy a seguir.
  
  Essa política estabelece uma relação de confiança entreaccount para que Unity Catalog possa assumir a função de acessar os dados no bucket em nome dos usuários de Databricks. Isso é especificado pelo ARN na seção Principal. É um valor estático que faz referência a uma função criada pela Databricks. Observe que a política é ligeiramente diferente se o senhor usar Databricks on AWS GovCloud.
  
  A policy define o ID externo como 0000 como um placeholder. Você atualizará isso para o ID externo da sua credencial de armazenamento em uma etapa posterior.
  { "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::414351767826:role/unity-catalog-prod-UCMasterRole-14S5ZJVKOTYTL" ] }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "sts:ExternalId": "0000" } } }] }
  { "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Principal": { "AWS": [ "arn:aws-us-gov:iam::044793339203:role/unity-catalog-prod-UCMasterRole-1QRFA8SGY15OJ" ] }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "sts:ExternalId": "0000" } } }] }
3. Ignore a configuração da policy de permissões. Você voltará para adicioná-la em uma passo posterior.
4. Salve a IAM role.

Crie a seguinte política de IAM na mesma account que o bucket S3, substituindo os seguintes valores:

<BUCKET>: nome do depósito S3.
<KMS-KEY>: Opcional. Se a criptografia estiver habilitada, informe o nome da key KMS que criptografa o conteúdo do bucket do S3. Se a criptografia estiver desabilitada, remova toda a seção KMS da policy de IAM.
<AWS-ACCOUNT-ID>: ID de account da sua account da AWS (não da sua account do Databricks).
<AWS-IAM-ROLE-NAME>: nome da IAM role AWS que você criou na passo anterior.

Esta policy de IAM concede acesso de leitura e gravação. Você também pode criar uma policy que conceda acesso somente de leitura. No entanto, isso pode ser desnecessário, pois você pode marcar a credencial de armazenamento como somente leitura, e qualquer acesso de gravação concedido por essa IAM role será ignorado.

{
  "Version": "2012-10-17",
  "Statement": [
      {
          "Action": [
              "s3:GetObject",
              "s3:PutObject",
              "s3:DeleteObject",
              "s3:ListBucket",
              "s3:GetBucketLocation"
          ],
          "Resource": [
              "arn:aws:s3:::<BUCKET>/*",
              "arn:aws:s3:::<BUCKET>"
          ],
          "Effect": "Allow"
      },
      {
          "Action": [
              "kms:Decrypt",
              "kms:Encrypt",
              "kms:GenerateDataKey*"
          ],
          "Resource": [
              "arn:aws:kms:<KMS-KEY>"
          ],
          "Effect": "Allow"
      },
      {
          "Action": [
              "sts:AssumeRole"
          ],
          "Resource": [
              "arn:aws:iam::<AWS-ACCOUNT-ID>:role/<AWS-IAM-ROLE-NAME>"
          ],
          "Effect": "Allow"
      }
    ]
}

Observação

Se você precisar de uma policy de IAM mais restritiva para o Unity Catalog, entre em contato com a equipe da sua account do Databricks para obter ajuda.

Crie uma política IAM para eventos de arquivo no mesmo account que o bucket S3.

Observação

Esse passo é opcional, mas altamente recomendado. Se o senhor não conceder acesso ao Databricks para configurar eventos de arquivo em seu nome, deverá configurar os eventos de arquivo manualmente para cada local. Caso contrário, o senhor terá acesso limitado a recursos críticos que o site Databricks poderá liberar no futuro.

A política de IAM concede à Databricks permissão para atualizar a configuração de notificação de eventos do seu bucket, criar um tópico de SNS, criar uma fila de SQS e assinar a fila de SQS no tópico de SNS. Esses são recursos necessários para os recursos que usam eventos de arquivo. Substitua <BUCKET> pelo nome do bucket S3.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ManagedFileEventsSetupStatement",
      "Effect": "Allow",
      "Action": [
        "s3:GetBucketNotification",
        "s3:PutBucketNotification",
        "sns:ListSubscriptionsByTopic",
        "sns:GetTopicAttributes",
        "sns:SetTopicAttributes",
        "sns:CreateTopic",
        "sns:TagResource",
        "sns:Publish",
        "sns:Subscribe",
        "sqs:CreateQueue",
        "sqs:DeleteMessage",
        "sqs:ReceiveMessage",
        "sqs:SendMessage",
        "sqs:GetQueueUrl",
        "sqs:GetQueueAttributes",
        "sqs:SetQueueAttributes",
        "sqs:TagQueue",
        "sqs:ChangeMessageVisibility"
      ],
      "Resource": [
        "arn:aws:s3:::<BUCKET>",
        "arn:aws:sqs:*:*:*",
        "arn:aws:sns:*:*:*"
      ]
    },
    {
      "Sid": "ManagedFileEventsListStatement",
      "Effect": "Allow",
      "Action": [
        "sqs:ListQueues",
        "sqs:ListQueueTags",
        "sns:ListTopics"
      ],
      "Resource": "*"
    },
    {
      "Sid": "ManagedFileEventsTeardownStatement",
      "Effect": "Allow",
      "Action": [
        "sns:Unsubscribe",
        "sns:DeleteTopic",
        "sqs:DeleteQueue"
      ],
      "Resource": [
        "arn:aws:sqs:*:*:*",
        "arn:aws:sns:*:*:*"
      ]
    }
  ]
}

Anexe as políticas do site IAM ao site IAM role.

Na seção Permissão da função tab, anexe as políticas IAM que o senhor acabou de criar.

passo 2: informar ao Databricks os detalhes da IAM role

No Databricks, faça login em um workspace vinculado ao metastore.

Você deve ter o privilégio CREATE STORAGE CREDENTIAL. As funções de administrador do metastore e de administrador de conta incluem esse privilégio.
Clique em Catalog.
No topo do painel Catálogo, clique no ícone Adicionar e selecione Adicionar uma credencial de armazenamento no menu.

Esta opção não aparece se você não tiver o privilégio CREATE STORAGE CREDENTIAL.

Como alternativa, na página de Acesso rápido, clique no botão Dados externos >, vá para a aba Credenciais de armazenamento e selecione Criar credencial.
Selecione um tipo de credencial de IAM role da AWS.
Insira um nome para a credencial, o ARN da IAM role que autoriza o Unity Catalog a acessar o local de armazenamento em seu locatário de nuvem e um comentário opcional.

Dica

Se você já definiu um instance profile no Databricks, pode clicar em Copiar instance profile para copiar o ARN da IAM role para esse instance profile. A IAM role do instance profile deve ter uma relação de confiança entre accounts que permite que o Databricks assuma a função para acessar o bucket em nome dos usuários do Databricks. Para obter mais informações sobre a policy de IAM role e os requisitos de relação de confiança, consulte Etapa 1: criar uma IAM role.
(Opcional) Se você quiser que os usuários tenham acesso somente para leitura às external locations que usam essa credencial de armazenamento, em Opções avançadas, selecione Somente leitura. Para obter mais informações, consulte Marcar uma credencial de armazenamento como somente leitura.
Clique em Criar.
Na caixa de diálogo Credencial de armazenamento criada, copie a ID externa.
Clique em Concluído.
(Opcional) Vincule a credencial de armazenamento a workspaces específicos.

Por padrão, qualquer usuário com privilégios pode usar a credencial de armazenamento em qualquer workspace conectado ao metastore. Se você quiser permitir o acesso apenas de workspaces específicos, vá para a aba Workspaces e atribua os workspaces. Consulte (Opcional) Atribuir uma credencial de armazenamento a workspaces específicos.

Você também pode criar uma credencial de armazenamento usando o provedor Databricks Terraform e databricks_storage_credential.

o passo 3: Atualizar a política de relacionamento de confiança do site IAM role

No AWS, modifique a policy de relacionamento de confiança para adicionar a ID externa da sua credencial de armazenamento e torná-la autoassumida.

Retorne à sua IAM role salva e vá para a tab Relações de confiança .

Edite a policy de relacionamento de confiança da seguinte forma:

Adicione o seguinte ARN à declaração "Permitir". Substitua <YOUR-AWS-ACCOUNT-ID> e <THIS-ROLE-NAME> pelos valores reais do seu account ID e IAM role.

"arn:aws:iam::<YOUR-AWS-ACCOUNT-ID>:role/<THIS-ROLE-NAME>"

Na instrução "sts:AssumeRole", atualize o ID externo do espaço reservado para o ID externo da sua credencial de armazenamento que você copiou no passo anterior.

"sts:ExternalId": "<STORAGE-CREDENTIAL-EXTERNAL-ID>"

Sua policy agora deve ter esta aparência, com o texto de substituição atualizado para usar o ID externo, o ID da account e os valores de IAM role da sua credencial de armazenamento:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": [
          "arn:aws:iam::414351767826:role/unity-catalog-prod-UCMasterRole-14S5ZJVKOTYTL",
          "arn:aws:iam::<YOUR-AWS-ACCOUNT-ID>:role/<THIS-ROLE-NAME>"
        ]
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "<STORAGE-CREDENTIAL-EXTERNAL-ID>"
        }
      }
    }
  ]
}

Etapa 4: validar a credencial de armazenamento

Depois de fazer as alterações na política de confiança IAM role no passo 3: Atualizar a política de relacionamento de confiança IAM role , verifique se o IAM role está configurado corretamente para ser usado como credencial de armazenamento.

Observação

Para validar a configuração, você deve ser o proprietário da credencial de armazenamento, um administrador do metastore ou ter CREATE EXTERNAL LOCATION permissões na credencial de armazenamento.

No Databricks, faça login em um workspace vinculado ao metastore.
Clique em Catalog.
Na página de Acesso rápido, clique no botão Dados externos > e vá para a aba Credenciais de armazenamento.

Como alternativa, você pode clicar no ícone de engrenagem no topo do painel Catálogo e selecionar Credenciais de armazenamento.
Selecione a credencial de armazenamento que você deseja validar.
Clique em .
Se alguma das verificações falhar, retorne ao passo 3: Atualize a política de relacionamento de confiança do site IAM role e revise a política de confiança do site IAM rolepara configurá-la corretamente.

Quando a credencial de armazenamento é validada, você pode usá-la para criar um local externo.

Política de imposição de função autoassumida

Em 30 de junho de 2023, a AWS atualizou sua política de confiança de IAM roles para exigir que as IAM roles confiassem explicitamente em si mesmas para chamadas STS:AssumeRole. Como resultado, a Databricks exige que as IAM roles da AWS para credenciais de armazenamento sejam autônomas e, em breve, proibirá credenciais de armazenamento não autônomas. Para mais informações, consulte esta postagem no blog da comunidade.

O Databricks começará a proibir a criação de credenciais de armazenamento com IAM roles da AWS que não são autoassumidas em 20 de setembro de 2024. As credenciais de armazenamento existentes com IAM roles não autoassumidas continuarão funcionando, mas você não poderá criar novas credenciais de armazenamento usando essas funções.

Em 20 de janeiro de 2025, o Databricks começará a bloquear o uso de credenciais de armazenamento existentes com IAM roles não autoassumidas. Isso pode potencialmente interromper cargas de trabalho e jobs que são executados usando credenciais que não são autoassumidas.

Para verificar se um AWS IAM role para uma credencial de armazenamento é autônomo, siga as instruções no passo 4: Validar a credencial de armazenamento. Se a verificação Self Assume Role falhar, repita o passo 3: Atualize a política de relacionamento de confiança do IAM role e reconfigure a política de confiança do IAM rolepara confiar em si mesmo.

Se você tiver várias credenciais de armazenamento em um metastore que deseja verificar, use o seguinte notebook para verificar as capacidades de autoassumir de todas as credenciais de armazenamento em seu metastore:

Notebook de verificação de credenciais de armazenamento autoassumidas

Abrir notebook em nova aba

(Opcional) Atribuir uma credencial de armazenamento a workspaces específicos

Visualização

Esse recurso está em visualização pública.

Por padrão, uma credencial de armazenamento pode ser acessada de todos os workspaces na metastore. Isso significa que, se um usuário tiver recebido um privilégio (como CREATE EXTERNAL LOCATION) nessa credencial de armazenamento, ele poderá exercer esse privilégio em qualquer workspace vinculado ao metastore. Se você usar workspaces para isolar o acesso aos dados do usuário, talvez queira permitir o acesso a uma credencial de armazenamento somente de workspaces específicos. Esse recurso é conhecido como vinculação de workspace ou isolamento de credenciais de armazenamento.

Um caso de uso típico para vincular uma credencial de armazenamento a workspaces específicos é o cenário em que um administrador de cloud configura uma credencial de armazenamento usando uma credencial de conta de cloud de produção, e você deve garantir que os usuários do Databricks usem essa credencial para criar locais externos somente no workspace de produção.

Para obter mais informações sobre a vinculação de workspace, consulte (Opcional) Atribuir um local externo a workspaces específicos e Limitar o acesso ao catálogo a workspaces específicos.

Observação

As vinculações de workspace são referenciadas quando os privilégios sobre as credenciais de armazenamento são exercidos. Por exemplo, se um usuário criar uma localização externa usando uma credencial de armazenamento, a vinculação de workspace na credencial de armazenamento é verificada apenas quando a localização externa é criada. Depois que a localização externa é criada, ela funcionará independentemente das vinculações de workspace configuradas na credencial de armazenamento.

Vincule uma credencial de armazenamento a um ou mais workspaces

Para atribuir uma credencial de armazenamento a espaços de trabalho específicos, você pode usar o Catalog Explorer ou a CLI da Databricks.

Permissões necessárias: administrador do Metastore ou proprietário das credenciais de armazenamento.

Observação

Os administradores do metastore podem ver todas as credenciais de armazenamento em um metastore usando o Catalog Explorer, e os proprietários de credenciais de armazenamento podem ver todas as credenciais que possuem em um metastore, independentemente de a credencial estar atribuída ao workspace atual. As credenciais de armazenamento que não estão atribuídas ao workspace aparecem esmaecidas.

Efetue login em um workspace vinculado ao metastore.
Na barra lateral, clique em Catálogo.
No topo do painel Catálogo, clique no ícone de engrenagem e selecione Credenciais de armazenamento.

Como alternativa, na página de Acesso rápido, clique no botão Dados externos > e vá para a aba Credenciais de armazenamento.
Selecione a credencial de armazenamento e vá para a guia Workspaces.
Na guia Workspaces, desmarque a caixa de seleção Todos os workspaces têm acesso.

Se sua credencial de armazenamento já estiver vinculada a um ou mais workspaces, essa caixa de seleção já estará desmarcada.
Clique em Atribuir a workspaces e digite ou localize os workspaces que deseja atribuir.

Para revogar o acesso, vá para a tab Workspaces, selecione o workspace e clique em Revogar. Para permitir o acesso de todos os workspaces, marque a caixa de seleção Todos os workspaces têm acesso.

Existem dois grupos de comando da CLI do Databricks e duas etapas necessárias para atribuir uma credencial de armazenamento a um workspace.

Nos exemplos a seguir, substitua <profile-name> pelo nome do seu perfil de configuração de autenticação do Databricks. Ele deve incluir o valor de um access token pessoal, além do nome da instância do workspace e da ID do workspace em que você gerou o access token pessoal. Consulte Autenticação de access token pessoal do Databricks.

Use o comando update do grupo de comando storage-credentials para definir as credenciais de armazenamento isolation mode para ISOLATED:
```
databricks storage-credentials update <my-storage-credential> \
--isolation-mode ISOLATED \
--profile <profile-name>
```
O padrão isolation-mode é OPEN para todos os workspaces anexados ao metastore.
Use o comando update-bindings do grupo de comandos workspace-bindings para atribuir os espaços de trabalho à credencial de armazenamento:
```
databricks workspace-bindings update-bindings storage-credential <my-storage-credential> \
--json '{
  "add": [{"workspace_id": <workspace-id>}...],
  "remove": [{"workspace_id": <workspace-id>}...]
}' --profile <profile-name>
```
Use as propriedades "add" e "remove" para adicionar ou remover vinculações de workspace.

Observação

A vinculação somente para leitura (BINDING_TYPE_READ_ONLY) não está disponível para credenciais de armazenamento. Portanto, não há razão para definir binding_type para a vinculação de credenciais de armazenamento.

Para listar todas as atribuições de workspace para uma credencial de armazenamento, use o comando get-bindings do grupo de comando workspace-bindings:

databricks workspace-bindings get-bindings storage-credential <my-storage-credential> \
--profile <profile-name>

Desassociar uma credencial de armazenamento de um workspace

As instruções para revogar o acesso ao workspace a uma credencial de armazenamento usando o Catalog Explorer ou o grupo de comandos workspace-bindings de CLI estão incluídas em Vincular uma credencial de armazenamento a um ou mais workspaces.

Próximos passos

Você pode visualizar, atualizar, excluir e conceder permissão a outros usuários para usar credenciais de armazenamento. Consulte Gerenciar credenciais de armazenamento.

Você pode usar a credencial de armazenamento para definir locais externos. Consulte Criar um local externo para conectar o armazenamento cloud a Databricks.