Invocar uma função do AWS Lambda de um cluster de bancos de dados Aurora PostgreSQL

O AWS Lambda é um serviço computacional orientado a eventos que permite executar código sem o provisionamento ou gerenciamento de servidores. Está disponível para uso com muitos serviços da AWS, incluindo o Aurora PostgreSQL. Por exemplo, você pode usar funções Lambda para processar notificações de eventos de um banco de dados ou para carregar dados de arquivos sempre que um novo arquivo é carregado para o Simple Storage Service (Amazon S3). Para saber mais sobre o Lambda, consulte O que é o AWS Lambda? no Guia do desenvolvedor do AWS Lambda.

nota

A chamada de funções do AWS Lambda é compatível no Aurora PostgreSQL 11.9 e em versões posteriores (incluindo Aurora Serverless v2).

Configurar o Aurora PostgreSQL para trabalhar com funções Lambda é um processo de várias etapas envolvendo o AWS Lambda, o IAM, sua VPC e seu cluster de bancos de dados Aurora PostgreSQL. A seguir, você pode encontrar resumos das etapas necessárias.

Para obter mais informações sobre como criar uma função Lambda, consulte Conceitos básicos do Lambda e Tópicos essenciais do AWS Lambda no Guia do desenvolvedor do AWS Lambda.

Tópicos

• Etapa 1: configurar o cluster de bancos de dados Aurora PostgreSQL para conexões de saída para o AWS Lambda
• Etapa 2: configurar o IAM para o cluster de bancos de dados Aurora PostgreSQL e AWS Lambda
• Etapa 3: instalar a extensão aws_lambda para um cluster de bancos de dados Aurora PostgreSQL
• Etapa 4: usar as funções Lambda auxiliares com o cluster de bancos de dados Aurora PostgreSQL (opcional)
• Etapa 5: invocar uma função Lambda do seu cluster de bancos de dados Aurora PostgreSQL
• Etapa 6: Conceder a outros usuários permissão para invocar funções do Lambda
• Exemplos: Invocar uma função do Lambda do cluster de banco de dados do Aurora PostgreSQL
• Mensagens de erro da função Lambda
• Função do AWS Lambda e referência de parâmetros

Etapa 1: configurar o cluster de bancos de dados Aurora PostgreSQL para conexões de saída para o AWS Lambda

As funções do Lambda sempre são executadas dentro de uma Amazon VPC de propriedade do serviço AWS Lambda. O Lambda aplica regras de segurança e acesso à rede a essa VPC e mantém e monitora a VPC automaticamente. Seu cluster de bancos de dados do Aurora PostgreSQL envia tráfego de rede para a VPC do serviço Lambda. Como você configura isso depende se sua instância de banco de dados primária do cluster de bancos de dados Aurora é pública ou privada.

• Cluster de banco de dados público do Aurora PostgreSQL: a instância de banco de dados primária de um cluster de banco de dados é pública se está localizada em uma sub-rede pública na VPC e se a propriedade “PubliclyAccessible” da instância é true. Para encontrar o valor dessa propriedade, você pode usar o comando da AWS CLI describe-db-instances. Ou, você pode usar o AWS Management Console para abrir a guia Connectivity & security (Conectividade e segurança) e verificar se Publicly accessible (Publicamente acessível) está definido como Yes (Sim). Para verificar se a instância está na sub-rede pública da VPC, use o AWS Management Console ou a AWS CLI.

  Para configurar o acesso ao Lambda, use o AWS Management Console ou a AWS CLI para criar uma regra de saída no grupo de segurança da VPC. A regra de saída especifica que o TCP pode usar a porta 443 para enviar pacotes para qualquer endereço IPv4 (0.0.0.0/0).

• Cluster de banco de dados privado do Aurora PostgreSQL: nesse caso, a propriedade “PubliclyAccessible” da instância é false ou está em uma sub-rede privada. Para permitir que a instância funcione com o Lambda, use um gateway de conversão de endereços de rede (NAT). Para obter mais informações, consulte Gateways de NAT. Ou configure sua VPC com um endpoint da VPC para o Lambda. Para obter mais informações, consulte Endpoints da VPC no Guia do usuário da Amazon VPC. O endpoint responde às chamadas feitas pelo cluster de bancos de dados do Aurora PostgreSQL para suas funções do Lambda.

Agora, sua VPC pode interagir com o VPC do AWS Lambda no nível da rede. Depois, configure as permissões usando o IAM.

Etapa 2: configurar o IAM para o cluster de bancos de dados Aurora PostgreSQL e AWS Lambda

Invocar funções Lambda do seu cluster de bancos de dados Aurora PostgreSQL requer certos privilégios. Para configurar os privilégios necessários, recomendamos que você crie uma política do IAM que permita chamar funções Lambda, atribuir essa política a uma função e, em seguida, aplicar a função ao cluster de banco de dados. Essa abordagem dá ao cluster de banco de dados privilégios para invocar a função Lambda especificada em seu nome. As etapas a seguir mostram como fazer isso usando a AWS CLI.

Para configurar permissões do IAM para usar seu cluster com o Lambda

1. Use o comando da AWS CLI create-policy para criar uma política do IAM que permita que o seu cluster de bancos de dados Aurora PostgreSQL invoque a função Lambda especificada. (O ID da instrução (Sid) é uma descrição opcional para sua instrução de política e não tem efeito sobre o uso.) Esta política fornece ao seu cluster de bancos de dados Aurora as permissões mínimas necessárias para invocar a função Lambda especificada.

   aws iam create-policy  --policy-name rds-lambda-policy --policy-document '{
       "Version": "2012-10-17",
       "Statement": [
           {
           "Sid": "AllowAccessToExampleFunction",
           "Effect": "Allow",
           "Action": "lambda:InvokeFunction",
           "Resource": "arn:aws:lambda:aws-region:444455556666:function:my-function"
           }
       ]
   }'

   Você também pode usar a política AWSLambdaRole predefinida que permite invocar qualquer uma das suas funções Lambda. Para obter mais informações, consulte Políticas do IAM baseadas em identidade para o Lambda.

2. Use o comando da AWS CLI create-role para criar uma função do IAM que a política possa assumir em tempo de execução.

   aws iam create-role  --role-name rds-lambda-role --assume-role-policy-document '{
       "Version": "2012-10-17",
       "Statement": [
           {
           "Effect": "Allow",
           "Principal": {
               "Service": "rds.amazonaws.com"
           },
           "Action": "sts:AssumeRole"
           }
       ]
   }'

3. Anexe a política à função usando o comando da AWS CLI attach-role-policy.

   aws iam attach-role-policy \
       --policy-arn arn:aws:iam::444455556666:policy/rds-lambda-policy \
       --role-name rds-lambda-role --region aws-region
   

4. Aplique a função ao seu cluster de bancos de dados Aurora PostgreSQL usando o comando da AWS CLI add-role-to-db-cluster Esta última etapa permite que seus usuários de banco de dados de clusters de banco de dados invoquem funções Lambda.

   aws rds add-role-to-db-cluster \
          --db-cluster-identifier my-cluster-name \
          --feature-name Lambda \
          --role-arn  arn:aws:iam::444455556666:role/rds-lambda-role   \
          --region aws-region

Com a VPC e as configurações do IAM concluídas, agora você pode instalar a extensão aws_lambda. (Observe que você pode instalar a extensão a qualquer momento, mas até configurar o suporte à VPC e os privilégios do IAM corretos, a extensão aws_lambda não adiciona nada às capacidades do cluster de bancos de dados Aurora PostgreSQL.)

Etapa 3: instalar a extensão aws_lambda para um cluster de bancos de dados Aurora PostgreSQL

Para usar o AWS Lambda com o cluster de banco de dados do Aurora PostgreSQL, adicione a extensão aws_lambda do PostgreSQL ao cluster de banco de dados do Aurora PostgreSQL. Esta extensão fornece o cluster de bancos de dados Aurora PostgreSQL com a capacidade de chamar funções Lambda do PostgreSQL.

Para instalar a extensão aws_lambda em seu cluster de bancos de dados Aurora PostgreSQL

Use a linha de comando psql do PostgreSQL ou a ferramenta pgAdmin para se conectar ao seu cluster de bancos de dados Aurora PostgreSQL.

1. Conecte-se ao seu cluster de bancos de dados Aurora PostgreSQL como usuário com privilégios rds_superuser. O usuário padrão postgres é mostrado no exemplo.

   psql -h cluster-instance.444455556666.aws-region.rds.amazonaws.com -U postgres -p 5432

2. Instale a extensão aws_lambda. A extensão aws_commons também é necessária. Ela fornece funções auxiliares para aws_lambda e muitas outras extensões do Aurora para PostgreSQL. Se ainda não estiver no seu cluster do Aurora PostgreSQL, ela é instalada com aws_lambda como mostrado a seguir.

   CREATE EXTENSION IF NOT EXISTS aws_lambda CASCADE;
   NOTICE:  installing required extension "aws_commons"
   CREATE EXTENSION

A extensão aws_lambda está instalada em sua instância de banco de dados primária do cluster de bancos de dados Aurora PostgreSQL. Agora você pode criar estruturas de conveniência para chamar suas funções Lambda.

Etapa 4: usar as funções Lambda auxiliares com o cluster de bancos de dados Aurora PostgreSQL (opcional)

Você pode usar as funções auxiliares na extensão aws_commons para preparar entidades que você pode invocar mais facilmente a partir do PostgreSQL. Para isso, você precisa ter as seguintes informações sobre suas funções Lambda:

• Nome da função – O nome, nome do recurso da Amazon (ARN), versão ou apelido da função Lambda. A política do IAM criada em Etapa 2: configurar o IAM para a instância e o Lambda requer o ARN, portanto, recomendamos que você use o ARN da sua função.

• Região da AWS – (Opcional) A região da AWS onde a função Lambda está localizada se não estiver na mesma região que seu cluster de bancos de dados Aurora PostgreSQL.

Para manter as informações do nome da função Lambda, você pode usar a função aws_commons.create_lambda_function_arn. Esta função auxiliar cria uma estrutura composta aws_commons._lambda_function_arn_1 com os detalhes necessários para a função de invocação. A seguir, você pode encontrar três abordagens alternativas para configurar essa estrutura composta.

SELECT aws_commons.create_lambda_function_arn(
   'my-function',
   'aws-region'
) AS aws_lambda_arn_1 \gset

SELECT aws_commons.create_lambda_function_arn(
   '111122223333:function:my-function',
   'aws-region'
) AS lambda_partial_arn_1 \gset

SELECT aws_commons.create_lambda_function_arn(
   'arn:aws:lambda:aws-region:111122223333:function:my-function'
) AS lambda_arn_1 \gset

Qualquer um desses valores pode ser usado em chamadas para a função aws_lambda.invoke. Para ver exemplos, consulte Etapa 5: invocar uma função Lambda do seu cluster de bancos de dados Aurora PostgreSQL.

Etapa 5: invocar uma função Lambda do seu cluster de bancos de dados Aurora PostgreSQL

A função aws_lambda.invoke se comporta de forma síncrona ou assíncrona, dependendo do invocation_type. As duas alternativas para esse parâmetro são RequestResponse (o padrão) e Event, da seguinte forma:

• RequestResponse – Este tipo de invocação é síncrono. É o comportamento padrão quando a chamada é feita sem especificar um tipo de invocação. A carga útil da resposta inclui os resultados da função aws_lambda.invoke. Use esse tipo de invocação de quando seu fluxo de trabalho exigir o recebimento de resultados da função Lambda antes de continuar.

• Event – Este tipo de invocação é assíncrono. A resposta não inclui uma carga útil contendo resultados. Use esse tipo de invocação quando o fluxo de trabalho não precisar de um resultado da função Lambda para continuar o processamento.

Como um teste simples de sua configuração, você pode se conectar à sua instância de banco de dados usando psql e chamar uma função de exemplo a partir da linha de comando. Suponha que você tenha uma das funções básicas configuradas em seu serviço Lambda, como a função Python simples mostrada na captura de tela a seguir.

Para invocar uma função de exemplo

1. Conecte-se à sua instância de banco de dados primária usando psql ou pgAdmin.

   psql -h cluster.444455556666.aws-region.rds.amazonaws.com -U postgres -p 5432

2. Invoque a função usando seu ARN.

   SELECT * from aws_lambda.invoke(aws_commons.create_lambda_function_arn('arn:aws:lambda:aws-region:444455556666:function:simple', 'us-west-1'), '{"body": "Hello from Postgres!"}'::json );

   A resposta se parece com esta a seguir.

   status_code |                        payload                        | executed_version | log_result
   -------------+-------------------------------------------------------+------------------+------------
            200 | {"statusCode": 200, "body": "\"Hello from Lambda!\""} | $LATEST          |
   (1 row)

Se sua tentativa de invocação não for bem-sucedida, consulte Mensagens de erro da função Lambda .

Etapa 6: Conceder a outros usuários permissão para invocar funções do Lambda

Neste ponto dos procedimentos, apenas você como rds_superuser pode invocar suas funções do Lambda. Para permitir que outros usuários invoquem quaisquer funções criadas por você, é necessário conceder permissão a eles.

Como conceder a outros permissão para invocar funções do Lambda

1. Conecte-se à sua instância de banco de dados primário usando psql ou pgAdmin.

   psql -h cluster.444455556666.aws-region.rds.amazonaws.com -U postgres -p 5432

2. Execute os seguintes comandos SQL:

   postgres=>  GRANT USAGE ON SCHEMA aws_lambda TO db_username;
   GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA aws_lambda TO db_username;