Pular para o conteúdo principal

Usando o Catalog Explorer ou o SQL para se conectar ao AWS S3

Esta página descreve como se conectar a um bucket do AWS S3 criando primeiro um objeto de credencial de armazenamento e, em seguida, criando um objeto de local externo usando o Catalog Explorer ou o SQL. Você deve criar a credencial de armazenamento antes de criar o local externo.

Para um processo de configuração mais automatizado, o site Databricks recomenda o uso do padrãoAWS CloudFormation Quickstart para criar esses dois objetos.

Antes de começar​

Pré-requisitos :

O senhor deve criar o bucket S3 que deseja usar como um local externo no AWS antes de criar o objeto de local externo no Databricks.

  • Não use a notação de ponto (por exemplo, incorrect.bucket.name.notation) nos nomes dos buckets do S3. Embora o AWS permita pontos em nomes de buckets, a Databricks não oferece suporte a buckets S3 com notação de pontos. Os buckets que contêm pontos podem causar problemas de compatibilidade com recursos como Delta Sharing devido a falhas na validação do certificado SSL. Para obter mais informações, consulte as práticas recomendadas de nomenclatura de buckets emAWS.

  • Os caminhos de localização externos devem conter somente caracteres ASCII padrão (letras A–Z, a–z, dígitos 0–9 e símbolos comuns como /, _, -).

  • O bucket não pode ter uma lista de controle de acesso S3 anexada a ele.

  • Evite usar um caminho no S3 que já esteja definido como um local externo em outro metastore do Unity Catalog. O senhor pode ler dados com segurança em um único local externo S3 de mais de um metastore, mas gravações simultâneas no mesmo local S3 de vários metastores podem levar a problemas de consistência.

Requisitos de permissões do Databricks :

  • Você deve ter o privilégio CREATE STORAGE CREDENTIAL na metastore. Os administradores do metastore têm CREATE STORAGE CREDENTIAL no metastore por default.
  • Você deve ter o privilégio CREATE EXTERNAL LOCATION na metastore e na credencial de armazenamento referenciada no local externo. Os administradores do metastore têm CREATE EXTERNAL LOCATION no metastore por default.

Requisitos de permissões do AWS :

  • O senhor deve ter as permissões iam:CreateRole para criar o IAM role.

Criar uma credencial de armazenamento que acesse um bucket do AWS S3​

Antes de criar um local externo, o senhor precisa de uma credencial de armazenamento que permita o acesso ao bucket S3. Se já tiver uma credencial de armazenamento, o senhor pode pular para Criar um local externo para um bucket do AWS S3.

o passo 1: Criar um 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 o senhor já tiver criado um IAM role que forneça esse acesso, poderá pular este passo e ir direto para o passo 2: Fornecer os detalhes do IAM role ao Databricks.

  1. 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.

important

Databricks Bloqueia credenciais de armazenamento novas e existentes com base na função IAM que não são autoproclamadas. Para obter detalhes, consulte Política autopresumida de aplicação de funções.

Para criar a política, você deve usar uma ID externa de placeholder.

  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.

    Esta política estabelece uma relação de confiança entre contas para que o Unity Catalog possa assumir o papel de acessar os dados no bucket em nome dos usuários do Databricks. Isso é especificado pelo ARN na seção Principal. É um valor estático que faz referência a uma função criada pelo Databricks.

    A política define a ID externa como 0000 como espaço reservado. O senhor atualizará isso para a ID externa de sua credencial de armazenamento em um passo posterior. A política é um pouco diferente se o senhor usar Databricks on AWS GovCloud (FedRAMP High).

JSON
{
  "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"
        }
      }
    }
  ]
}

  1. Ignore a configuração da política de permissões. O senhor voltará a acrescentar isso em um passo posterior.

  2. Salve a IAM role.

  3. 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.

nota

Se a criptografia estiver ativada, o senhor deverá atualizar sua política KMS key em AWS para conceder acesso ao Unity Catalog IAM role. Caso contrário, o Unity Catalog não poderá acessar os dados no bucket. Adicione o seguinte à política key, substituindo os espaços reservados por seus valores:

JSON
"Principal": {
  "AWS": "arn:aws:iam::<AWS-ACCOUNT-ID>:role/<UNITY-CATALOG-IAM-ROLE>"
}

Consulte Configurar criptografia para S3 usando o Unity Catalog.

  • <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.

Essa política de IAM concede acesso de leitura e gravação. Você também pode criar uma política que conceda somente acesso de leitura. No entanto, isso pode ser desnecessário porque o senhor pode marcar a credencial de armazenamento como somente leitura, e o site Databricks ignora qualquer acesso de gravação concedido por esse IAM role.

JSON
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:ListBucket",
        "s3:GetBucketLocation",
        "s3:ListBucketMultipartUploads",
        "s3:ListMultipartUploadParts",
        "s3:AbortMultipartUpload"
      ],
      "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"
    }
  ]
}
nota

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.

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

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. Para obter mais informações sobre eventos de arquivo, consulte ( Recomendado) Habilitar eventos de arquivo para um local externo.

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 recursos que usam eventos de arquivo. Substitua <BUCKET> pelo nome do bucket S3.

JSON
{
  "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",
        "sqs:PurgeQueue"
      ],
      "Resource": ["arn:aws:s3:::<BUCKET>", "arn:aws:sqs:*:*:csms-*", "arn:aws:sns:*:*:csms-*"]
    },
    {
      "Sid": "ManagedFileEventsListStatement",
      "Effect": "Allow",
      "Action": ["sqs:ListQueues", "sqs:ListQueueTags", "sns:ListTopics"],
      "Resource": ["arn:aws:sqs:*:*:csms-*", "arn:aws:sns:*:*:csms-*"]
    },
    {
      "Sid": "ManagedFileEventsTeardownStatement",
      "Effect": "Allow",
      "Action": ["sns:Unsubscribe", "sns:DeleteTopic", "sqs:DeleteQueue"],
      "Resource": ["arn:aws:sqs:*:*:csms-*", "arn:aws:sns:*:*:csms-*"]
    }
  ]
}

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

    Em Permission tab da função, anexe as políticas IAM que o senhor acabou de criar.

o passo 2: Forneça ao site Databricks os detalhes do IAM role​

  1. Em Databricks, log in para um workspace que está vinculado ao metastore Unity Catalog.

    Você deve ter o privilégio CREATE STORAGE CREDENTIAL. As funções de administrador do metastore e administrador da account incluem essa permissão.

  2. Clique em Ícone de dados. Catálogo para abrir o Catalog Explorer.

  3. Clique em Ícone de adicionar ou ícone de mais e, em seguida, clique em Criar uma credencial .

  4. Selecione um tipo de credencial de IAM role da AWS .

  5. 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 o senhor já tiver definido um instance profile em Databricks, clique em Copy instance profile para copiar o IAM role ARN para esse instance profile. O instance profile's IAM role deve ter uma relação de confiança cruzadaaccount que permita 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 política IAM role e os requisitos de relacionamento de confiança, consulte o passo 1: Criar um IAM role.

  1. (Opcional) Se você quiser que os usuários tenham acesso somente para leitura aos locais externos que usam essa credencial de armazenamento, em Opções avançadas , selecione Limitar ao uso somente para leitura. Você pode alterar essa configuração posteriormente. Para obter mais informações, consulte Marcar uma credencial de armazenamento como somente leitura.

  2. Clique em Criar .

  3. Na caixa de diálogo Credencial de armazenamento criada , copie a ID externa .

  4. Clique em Concluído .

  5. (Opcional) Vincule a credencial de armazenamento a workspaces específicos.

    Em default, qualquer usuário privilegiado pode usar a credencial de armazenamento em qualquer workspace anexado ao metastore. Se o senhor quiser permitir o acesso somente a partir de um espaço de trabalho específico, acesse o espaço de trabalho tab e atribua o espaço de trabalho. Consulte Atribuir uma credencial de armazenamento a um espaço de trabalho específico.

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

No AWS, modifique a política de relacionamento de confiança para adicionar o ID externo da credencial de armazenamento e torná-la autônoma.

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

  2. Edite a política de relacionamento de confiança para ter a seguinte aparência:

    JSON
    {
      "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>"
            }
          }
        }
      ]
    }

    Nessa política, substitua os seguintes valores:

    • <YOUR-AWS-ACCOUNT-ID>: Seu AWS account ID.
    • <THIS-ROLE-NAME>: O nome deste IAM role.
    • <STORAGE-CREDENTIAL-EXTERNAL-ID>: A ID externa da credencial de armazenamento que o senhor copiou no passo anterior.

o passo 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.

nota

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.

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

  2. Clique em Ícone de dados. Catálogo .

  3. Na página de acesso rápido , clique no botão External Data (Dados externos ) > e vá para Credentials (Credenciais ) tab.

    Como alternativa, você pode clicar no ícone de Ícone de engrenagem. engrenagem na parte superior do painel Catálogo e selecionar Credenciais .

  4. Selecione a credencial de armazenamento que você deseja validar.

  5. Clique em Validar configuração .

  6. 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 role para configurá-la corretamente.

Depois que a credencial de armazenamento for validada, você poderá usá-la para criar um local externo.

Política autopretensiosa de aplicação de funções​

Em 30 de junho de 2023, o site AWS atualizou sua política de confiança IAM role para exigir que a função IAM explicitamente se autoconfie nas chamadas STS:AssumeRole. Como resultado, o site Databricks exige que a função AWS IAM para as credenciais de armazenamento seja autônoma. Para obter detalhes, consulte esta postagem no blog da comunidade.

Em 20 de janeiro de 2025 , o site Databricks começou a bloquear o uso de credenciais de armazenamento existentes com a função IAM não autônoma. Essa proibição pode interromper cargas de trabalho e trabalhos que são executados usando credenciais não autônomas.

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 role para 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:

Verificação de credencial de armazenamento autônomo Notebook

Open notebook in new tab

:::::

Criar um local externo para um bucket do AWS S3​

Esta seção descreve como criar um local externo usando o Catalog Explorer ou o SQL. Ele pressupõe que o senhor já tenha uma credencial de armazenamento que permita o acesso ao bucket do S3.

Se o senhor ainda não tiver uma credencial de armazenamento, o site Databricks recomenda usar o padrãoAWS CloudFormation Quickstart para criar a credencial de armazenamento e o local externo. Para criar manualmente uma credencial de armazenamento, consulte Criar uma credencial de armazenamento que acesse um bucket do AWS S3.

Opção 1: criar um local externo usando o Catalog Explorer​

Use o Catalog Explorer para criar manualmente um local externo se você preferir trabalhar na interface do usuário. Para criar locais externos de forma programática, use o SQL.

Para criar o local externo:

  1. Faça login em um site workspace que esteja anexado ao metastore.

  2. Na barra lateral, clique em Ícone de dados. Catálogo .

  3. Na página de acesso rápido , clique no botão External data (Dados externos ) >, vá para External Locations (Locais externos ) tab e clique em Create external location (Criar local externo).

  4. Na caixa de diálogo Criar um novo local externo , clique em Manual e depois em Avançar .

    Para saber mais sobre a opção AWS Quickstart, consulte Usando o padrão AWS CloudFormation Quickstart para se conectar a AWS S3 .

  5. Na caixa de diálogo Criar um novo local externo manualmente , insira um nome de local externo .

  6. Em Tipo de armazenamento , selecione S3 .

  7. Em URL , digite o caminho do bucket S3. Por exemplo, s3://<bucket-path>.

  8. Em Credencial de armazenamento , selecione a credencial de armazenamento que concede acesso ao local externo.

nota

Se o senhor não tiver um objeto de credencial de armazenamento, mas tiver um AWS IAM role que permita o acesso ao bucket S3, poderá selecionar + Criar nova credencial de armazenamento para criar o objeto de credencial de armazenamento nessa caixa de diálogo.

  1. (Opcional) Se você quiser que os usuários tenham acesso somente para leitura ao local externo, clique em Opções avançadas e selecione Limitar ao uso somente para leitura . Você pode alterar essa configuração posteriormente. Para obter mais informações, consulte Marcar um local externo como somente leitura.

  2. (Opcional) Se o local externo for destinado à migração de carga de trabalho herdada, clique em Advanced options (Opções avançadas ) e ative o modo de fallback .

    Consulte Ativar o modo de fallback em locais externos.

  3. (Opcional) Se o bucket S3 exigir criptografia SSE, o senhor poderá configurar um algoritmo de criptografia para permitir que tabelas e volumes externos no Unity Catalog acessem os dados no bucket S3.

    Para obter instruções, consulte Configurar um algoritmo de criptografia em um local externo (somente AWS S3).

  4. (Opcional) Para se inscrever para receber notificações de alteração no local externo, clique em Opções avançadas e selecione Habilitar eventos de arquivo .

    Os eventos de arquivos simplificam a configuração e melhoram o desempenho e a capacidade de recursos, como acionadores de chegada de arquivos e notificações de arquivos do site Auto Loader. Esse passo é opcional, mas altamente recomendado.

    Para obter detalhes, consulte (Recomendado) Habilitar eventos de arquivo para um local externo.

  5. Clique em Criar .

  6. (Opcional) Vincule o local externo a um espaço de trabalho específico.

    Em default, qualquer usuário privilegiado pode usar o local externo em qualquer workspace anexado ao metastore. Se o senhor quiser permitir o acesso somente a partir de um espaço de trabalho específico, acesse o espaço de trabalho tab e atribua o espaço de trabalho. Consulte Atribuir um local externo a um espaço de trabalho específico.

  7. Acesse o site Permissions (Permissões ) tab para conceder permissão para usar o local externo.

    Para que qualquer pessoa use o local externo, você deve conceder permissões:

    • Para usar o local externo para adicionar um local de armazenamento gerenciar ao metastore, catálogo ou esquema, conceda o privilégio CREATE MANAGED LOCATION.

    • Para criar tabelas ou volumes externos, conceda CREATE EXTERNAL TABLE ou CREATE EXTERNAL VOLUME.

    1. Clique em Conceder .
    2. Na caixa de diálogo Grant on <external location> , selecione usuários, grupos ou entidade de serviço no campo Principals e selecione o privilégio que deseja conceder.
    3. Clique em Conceder .

Opção 2: Criar um local externo usando o SQL​

Para criar um local externo usando SQL, execute o seguinte comando em um Notebook ou no editor de consultas SQL. Substitua os valores do espaço reservado.

  • <location-name>: um nome para o local externo. Se location_name incluir caracteres especiais, como hífens (-), ele deverá estar entre acentos invertidos ( ). Veja os nomes.
  • <bucket-path>: o caminho em seu locatário de nuvem ao qual este local externo concede acesso. Por exemplo, s3://mybucket.
  • <storage-credential-name>: o nome da credencial de armazenamento que autoriza a leitura e a gravação no bucket. Se o nome da credencial de armazenamento incluir caracteres especiais, como hífens (-), ele deverá estar entre acentos invertidos ( ).
SQL
CREATE EXTERNAL LOCATION [IF NOT EXISTS] `<location-name>`
URL '<bucket-path>'
WITH ([STORAGE] CREDENTIAL `<storage-credential-name>`)
[COMMENT '<comment-string>'];

Se quiser limitar o acesso de um local externo a um espaço de trabalho específico em seu account, também conhecido como workspace binding ou external location isolation, consulte Assign an external location to specific workspace (Atribuir um local externo a um espaço de trabalho específico).

Next os passos​

Última atualização em