Executar queries federadas no Amazon Redshift (autenticação IAM)

Configure Databricks Lakehouse Federation to run federated queries on Amazon Redshift using AWS Identity and Access Management (IAM) authentication instead of a username and password. Authentication uses a Unity Catalog service credential that references an AWS IAM role. For general Redshift federation setup with username and password, see Run federated queries on Amazon Redshift.

nota

A autenticação IAM para Amazon Redshift está disponível apenas no Databricks on AWS, pois ela depende de um IAM role da AWS referenciado por uma credencial de serviço.

Before you begin

Before you run federated queries on Amazon Redshift using IAM authentication, you must meet the following requirements.

Requisitos do Databricks

• Um workspace habilitado para o Unity Catalog.
• Databricks compute that uses Databricks Runtime 19 or above and Standard or Dedicated access mode.
• O privilégio CREATE CONNECTION no metastore do Unity Catalog anexado ao workspace.
• O privilégio CREATE SERVICE CREDENTIAL no metastore.

Requisitos da AWS

• Um cluster provisionado ou um workgroup Serverless do Amazon Redshift.
• Network connectivity from your Databricks workspace to the cluster or workgroup. See Networking recommendations for Lakehouse Federation.
• The ability to create IAM roles and policies.

Choose an authentication mode

Redshift IAM authentication supports three modes. Choose the one that matches your Redshift deployment, because it determines the IAM action you grant and whether you create a database user:

• DB User (redshift:GetClusterCredentials): Para clusters provisionados. Requer um usuário de banco de dados explícito criado no Redshift.
• Group Federation (redshift:GetClusterCredentialsWithIAM): para clusters provisionados. O Databricks deriva a identidade do banco de dados da IAM role, portanto, você não cria um usuário.
• Serverless (redshift-serverless:GetCredentials): para o Redshift Serverless. A identidade do banco de dados é derivada automaticamente, como na Group Federation.

Configurar a autenticação do AWS IAM

Conclua os seguintes os passos na AWS para criar o usuário do banco de dados, a política de IAM e a IAM role que o Unity Catalog usa para se conectar.

Passo 1: Configurar a identidade do banco de dados do Redshift

Para o modo de usuário de banco de dados (DB User), conecte-se ao seu cluster do Redshift e crie um usuário de banco de dados com a autenticação por senha desativada. Em seguida, conceda a ele os privilégios necessários. Você pode executar estes comandos na página Query data > Query in query editor do cluster.

SQL

CREATE USER iam_user PASSWORD DISABLE;
GRANT ALL ON DATABASE dev TO iam_user;
GRANT USAGE ON SCHEMA public TO iam_user;
GRANT ALL ON ALL TABLES IN SCHEMA public TO iam_user;

Para os modos Group Federation e Serverless, ignore a instrução CREATE USER. O Databricks deriva a identidade do banco de dados automaticamente. A identidade derivada ainda precisa de privilégios no banco de dados; portanto, conceda os privilégios exigidos pelas suas consultas a essa identidade ou a um grupo ou função do Redshift à qual ela pertença. Sem eles, a conexão é autenticada, mas as consultas federadas falham com um erro de permissão.

Step 2: Set up the AWS IAM policy

Create an IAM policy that authorizes the credential-fetching action for your authentication mode.

DB User

Para clusters provisionados, autorize redshift:GetClusterCredentials no cluster, no usuário do banco de dados e no banco de dados:

JSON

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "RedshiftDbUser",
      "Effect": "Allow",
      "Action": ["redshift:GetClusterCredentials"],
      "Resource": [
        "arn:aws:redshift:<region>:<account-id>:cluster:<cluster-name>",
        "arn:aws:redshift:<region>:<account-id>:dbuser:<cluster-name>/<db-user>",
        "arn:aws:redshift:<region>:<account-id>:dbname:<cluster-name>/<database>"
      ]
    }
  ]
}

Group Federation

Para clusters provisionados, autorize redshift:GetClusterCredentialsWithIAM no cluster e no banco de dados. A identidade do banco de dados vem da IAM role, portanto, nenhum ARN de dbuser é necessário:

JSON

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "RedshiftGroupFederation",
      "Effect": "Allow",
      "Action": ["redshift:GetClusterCredentialsWithIAM"],
      "Resource": [
        "arn:aws:redshift:<region>:<account-id>:cluster:<cluster-name>",
        "arn:aws:redshift:<region>:<account-id>:dbname:<cluster-name>/<database>"
      ]
    }
  ]
}

Serverless

Para o Redshift Serverless, autorize redshift-serverless:GetCredentials no workgroup. Esta ação está no namespace redshift-serverless e atua em um ARN de workgroup, não nos recursos de clusters provisionados usados pelos outros modos:

JSON

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "RedshiftServerless",
      "Effect": "Allow",
      "Action": ["redshift-serverless:GetCredentials"],
      "Resource": ["arn:aws:redshift-serverless:<region>:<account-id>:workgroup/<workgroup-id>"]
    }
  ]
}

Para obter mais informações, consulte Using IAM authentication to generate database user credentials e Security and connections in Amazon Redshift Serverless na documentação da AWS.

O passo 3: Criar a AWS IAM role

Crie uma IAM role que o Unity Catalog possa assumir para autenticar no Redshift:

1. In the AWS IAM console, go to Roles and click Create role .

2. Em Trusted entity type , selecione Custom trust policy .

3. In the Custom trust policy editor, paste the following policy. This is a placeholder. Depois de criar a credencial de serviço no Databricks, substitua-a pela política de confiança que o Databricks gera. O Principal e o Action são obrigatórios. O bloco Condition é opcional neste estágio.

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

4. Click Next . On the Add permissions page, select the IAM policy you created in Set up the AWS IAM policy.

5. Clique em Next , insira um Role name e clique em Create role .

6. Anote o ARN da função. Você a fornece ao criar a credencial de serviço.

Para obter mais informações sobre IAM roles com políticas de confiança personalizada, consulte Creating a role using custom trust policies na documentação da AWS.

Step 4: Create the Databricks service credential

Crie uma credencial de serviço do Unity Catalog que faça referência ao ARN da função do IAM da etapa anterior. Para obter os passos detalhados, consulte Criar credenciais de serviço.

Depois de criar a credencial de serviço, conclua a configuração da política de confiança da IAM role:

1. Na caixa de diálogo Service credential created , copie toda a política de confiança exibida e clique em Done .
2. Retorne à sua IAM role no console da AWS, abra a tab Trust relationships e substitua a política de confiança de placeholder pela que você copiou. Isso adiciona a ID externa da sua credencial de serviço e torna a função autoassumida.

Anote o nome da credencial de serviço. Você faz referência a ela ao criar a conexão.

Criar uma conexão

A conexão especifica um caminho e as credenciais para acessar um sistema de banco de dados externo. Para criar uma conexão, você pode usar o Catalog Explorer ou o comando CREATE CONNECTION do SQL em um Notebook do Databricks ou no editor de consultas SQL do Databricks.

nota

You can also use the Databricks REST API or the Databricks CLI to create a connection. See POST /api/2.1/unity-catalog/connections and Unity Catalog comandos.

Permissões necessárias: Administrador do Metastore ou usuário com o privilégio CREATE CONNECTION.

Catalog Explorer

1. In your Databricks workspace, click Catalog .

2. At the top of the Catalog pane, click the Add icon and select Create a connection from the menu.

3. Na página Connection basics do assistente Set up connection , insira um Connection name fácil de usar.

4. Selecione um Connection type de Redshift .

5. Para Auth type , selecione Service Credential .

6. (Opcional) Adicione um comentário.

7. Clique em Avançar .

8. Na página Authentication , insira as seguintes propriedades de conexão para o seu cluster ou workgroup do Redshift:

   • Host : Por exemplo, redshift-demo.us-west-2.redshift.amazonaws.com
   • Port : For example, 5439
   • User : para o modo de usuário de banco de dados (DB User), o usuário de banco de dados que você criou. Por exemplo, iam_user. Deixe em branco para os modos Group Federation e Serverless.

9. Clique em Avançar .

10. Na página Connection details , selecione o Authentication mode ( DB User , Group Federation ou Serverless ) e, em Service credential , selecione a credencial de serviço que você criou em Create the service credential.

11. Clique em Criar conexão .

12. Na página Catalog basics , insira um nome para o catálogo externo. Um catálogo externo espelha um banco de dados em um sistema de dados externo para que você possa query e gerenciar o acesso aos dados nesse banco de dados usando o Databricks e o Unity Catalog.

13. (Opcional) Clique em Testar conexão para confirmar se está funcionando.

14. Clique em Create catalog .

15. On the Access page, select the workspaces in which users can access the catalog you created. You can select All workspaces have access , or click Assign to workspaces , select the workspaces, and then click Assign .

16. Altere o Owner que pode gerenciar o acesso a todos os objetos no catálogo. Comece a digitar um principal na caixa de texto e clique no principal nos resultados retornados.

17. Conceda Privilégios no catálogo. Clique em Grant :

    1. Especifique os Principals que terão acesso aos objetos no catálogo. Comece a digitar um principal na caixa de texto e clique no principal nos resultados retornados.

    2. Selecione as Privilege presets para conceder a cada principal. Todos os usuários da conta recebem BROWSE como default.

       • Selecione Data Reader no menu suspenso para conceder privilégios de read em objetos no catálogo.
       • Selecione Data Editor no menu suspenso para conceder os privilégios read e modify em objetos no catálogo.
       • Manually select the privileges to grant.

    3. Clique em Conceder .

18. Clique em Avançar .

19. Na página Metadata , especifique os pares key-value de tags. Para obter mais informações, consulte Aplicar tags a objetos protegíveis do Unity Catalog.

20. (Opcional) Adicione um comentário.

21. Clique em Salvar .

SQL

Run the following comando in a notebook or the Databricks SQL query editor. Providing the credential option instead of a password creates an IAM-authenticated connection. Set auth_mode to match your Redshift deployment, and set user only for db_user mode.

SQL

-- db_user mode (provisioned cluster)
CREATE CONNECTION <connection-name> TYPE redshift
OPTIONS (
  host '<hostname>',
  port '<port>',
  user '<iam-user>',
  auth_mode 'db_user',
  credential '<service-credential-name>'
);

-- group_federation mode (provisioned cluster)
CREATE CONNECTION <connection-name> TYPE redshift
OPTIONS (
  host '<hostname>',
  port '<port>',
  auth_mode 'group_federation',
  credential '<service-credential-name>'
);

-- serverless mode (Redshift Serverless)
CREATE CONNECTION <connection-name> TYPE redshift
OPTIONS (
  host '<hostname>',
  port '<port>',
  auth_mode 'serverless',
  credential '<service-credential-name>'
);

Criar um catálogo externo

nota

If you use the UI to create a connection to the fonte de dados, foreign catalog creation is included and you can skip esta etapa.

nota

If you use the UI to create a connection to the fonte de dados, foreign catalog creation is included and you can skip esta etapa.

Um catálogo externo espelha um banco de dados em um sistema de dados externo para você consultar e gerenciar o acesso aos dados nesse banco de dados com Databricks e Unity Catalog. Para criar um catálogo externo, utiliza-se uma conexão com a fonte de dados que já foi definida.

Para criar um catálogo externo, você pode usar o Catalog Explorer ou o comando SQL CREATE FOREIGN CATALOG em um notebook do Databricks ou no editor de consultas SQL. Você também pode usar a API REST do Databricks ou a CLI do Databricks para criar um catálogo. Consulte POST /api/2.1/unity-catalog/catalogs e comandos do Unity Catalog.

Permissões necessárias: permissão CREATE CATALOG na metastore e propriedade da conexão ou o privilégio CREATE FOREIGN CATALOG na conexão.

Catalog Explorer

1. No seu workspace do Databricks, clique em Catalog para abrir o Catalog Explorer.

2. Na parte superior do painel Catálogo , clique no ícone Adicionar e selecione Adicionar um catálogo no menu.

   Como alternativa, na página de acesso rápido , clique no botão Catálogos e no botão Criar catálogo .

3. Siga as instruções para criar catálogos externos em Create catalogs.

SQL

Run the following SQL comando in a notebook or SQL query editor. Items in brackets are optional. Replace the placeholder values:

• <catalog-name>: Nome para o catálogo no Databricks.
• <connection-name>: The connection object that specifies the data source, path, and access credentials.
• <database-name>: Nome do banco de dados que você deseja espelhar como um catálogo no Databricks.

SQL

CREATE FOREIGN CATALOG [IF NOT EXISTS] <catalog-name> USING CONNECTION <connection-name>
OPTIONS (database '<database-name>');

Recursos adicionais

• Pushdowns suportados
• Gerenciar credenciais de serviço
• Recomendações de rede para a Lakehouse Federation
• query bancos de dados externos usando a função remote_query