Recuperação de parâmetros e segredos com o Powertools para AWS Lambda (TypeScript)

Ao criar aplicativos Serverless usando o AWS Lambda, você geralmente precisa recuperar parâmetros, como detalhes da conexão do banco de dados, segredos da API ou valores de configuração global em tempo de execução. Você pode disponibilizar esses parâmetros para suas funções do Lambda por meio de armazenamentos de parâmetros seguros, escaláveis e altamente disponíveis, como o AWS Systems Manager Parameter Store ou o AWS Secrets Manager.

O utilitário de parâmetros do Powertools para AWS Lambda (TypeScript) simplifica a integração desses armazenamentos de parâmetros em suas funções do Lambda. O utilitário fornece funções de alto nível para recuperar segredos e parâmetros, integra armazenamento em cache e transformações e reduz a quantidade de código padronizado que você deve escrever.

O utilitário de parâmetros suporta os seguintes armazenamentos de parâmetros:

• Armazenamento de parâmetros do AWS Systems Manager
• Gerenciador de segredos da AWS
• AWS AppConfig
• Amazon DynamoDB
• Provedores de armazenamento de parâmetros personalizados

O utilitário de parâmetros faz parte do Powertools for AWS Lambda (TypeScript), que você pode usar nas bases de código JavaScript e TypeScript. Implementando a orientação do Serverless Applications Lens do AWS Well-Architected Framework, o Powertools fornece utilitários para facilitar a adoção das melhores práticas, como rastreamento distribuído, registro estruturado e métricas assíncronas de negócios e aplicativos.

Para obter mais detalhes, consulte a documentação do Powertools for AWS Lambda (TypeScript) no GitHub e a referência de introdução no blog.

Este blog mostra como usar o novo utilitário de parâmetros para recuperar parâmetros e segredos em suas funções do JavaScript e do TypeScript Lambda com segurança.

Introdução ao utilitário de parâmetros

Configuração inicial

O kit de ferramentas Powertools é modular, o que significa que você pode instalar o utilitário de parâmetros independentemente dos pacotes Logger, Tracing ou Metrics. Instale a biblioteca do utilitário De parâmetros em seu projeto via npm:

npm install @aws-lambda-powertools/parameters

Além disso, você deve adicionar o cliente do AWS SDK para o armazenamento de parâmetros que você planeja usar. O utilitário de parâmetros apenas suporta o AWS SDK v3 para JavaScript, o que permite que o utilitário seja modular. Você instala somente os pacotes SDK necessários para manter o tamanho do pacote pequeno.

Em seguida, atribua as permissões apropriadas do AWS Identity and Access Management (IAM) à função de execução da função Lambda da sua função Lambda, que permitem recuperar parâmetros do armazenamento de parâmetros.

As seções a seguir ilustram como realizar as etapas mencionadas anteriormente para alguns cenários típicos de recuperação de parâmetros.

Recuperando um único parâmetro do SSM Parameter Store

Para recuperar parâmetros do SSM Parameter Store, instale o cliente AWS SDK para SSM, além do utilitário Parameters:

npm install @aws-sdk/client-ssm

Para recuperar um parâmetro individual, o utilitário de parâmetros fornece a função getParameter:

import { getParameter } from '@aws-lambda-powertools/parameters/ssm';

export const handler = async (): Promise<void> => {
  // Retrieve a single parameter
  const parameter = await getParameter('/my/parameter');
  console.log(parameter);
};

Por fim, você precisa atribuir uma política do IAM com a permissão SSM:getParameter à sua função de execução da função Lambda. Aplique o princípio do privilégio mínimo definindo o escopo da permissão para o recurso de parâmetro específico, conforme mostrado no exemplo de política a seguir:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ssm:GetParameter"
      ],
      "Resource": [
        "arn:aws:ssm:AWS_REGION:AWS_ACCOUNT_ID:my/parameter"
      ]
    }
  ]
}

Ajustando o TTL do cache

Por padrão, os parâmetros recuperados são armazenados em cache na memória por 5 segundos. Esse valor em cache é usado para outras invocações da função Lambda até que ela expire. Se seu aplicativo exigir um comportamento diferente, o utilitário De parâmetros permite ajustar o tempo de vida (TTL) por meio do argumento maxAge.

Com base no exemplo anterior, se você quiser armazenar em cache o parâmetro recuperado por 30 em vez de 5 segundos, você pode adaptar o código da função da seguinte forma:

import { getParameter } from '@aws-lambda-powertools/parameters/ssm';

export const handler = async (): Promise<void> => {
  // Retrieve a single parameter with a 30 seconds cache TTL
  const parameter = await getParameter('/my/parameter', { maxAge: 30 });
  console.log(parameter);
};

Em outros casos, talvez você queira sempre recuperar o valor mais recente do armazenamento de parâmetros e ignorar qualquer valor em cache. Para fazer isso, defina o parâmetro forceFetch como true:

import { getParameter } from '@aws-lambda-powertools/parameters/ssm';

export const handler = async (): Promise<void> => {
  // Always retrieve the latest value of a single parameter
  const parameter = await getParameter('/my/parameter', { forceFetch: true });
  console.log(parameter);
};

Para obter detalhes, consulte sempre buscando as últimas novidades na documentação do Powertools for AWS Lambda (TypeScript).

Parâmetros de decodificação armazenados no formato JSON ou base64

Se alguns de seus parâmetros estiverem armazenados em base64 ou JSON, você poderá desserializá-los por meio do argumento transform do utilitário de parâmetros.

Considerando um parâmetro armazenado no SSM como JSON, ele pode ser recuperado e desserializado da seguinte forma:

import { Transform } from '@aws-lambda-powertools/parameters';
import { getParameter } from '@aws-lambda-powertools/parameters/ssm';

export const handler = async (): Promise => {
  // Retrieve and deserialize a single JSON parameter
  const valueFromJson = await getParameter('/my/json/parameter', { transform: Transform.JSON });
  console.log(valueFromJson);
};

O utilitário de parâmetros suporta o argumento transform para todos os provedores de armazenamento de parâmetros e funções de alto nível. Para obter detalhes, consulte desserialização de valores com parâmetros de transformação.

Trabalhando com parâmetros criptografados no SSM Parameter Store

O SSM Parameter Store oferece suporte a parâmetros de string seguros criptografados por meio do AWS Key Management Service (AWS KMS). O utilitário De parâmetros permite que você recupere esses parâmetros criptografados adicionando o argumento decrypt à sua solicitação.

Por exemplo, você pode recuperar um parâmetro criptografado da seguinte forma:

import { getParameter } from '@aws-lambda-powertools/parameters/ssm';

export const handler = async (): Promise<void> => {
  // Decrypt the parameter
  const decryptedParameter = await getParameter('/my/encrypted/parameter', { decrypt: true });
  console.log(decryptedParameter);
};

Recuperando vários parâmetros do SSM Parameter Store

Além de recuperar um único parâmetro usando getParameter, você também pode usar GetParameter para recuperar recursivamente vários parâmetros em um caminho do SSM Parameter Store ou getParametersByName para recuperar vários parâmetros distintos pelo nome completo.

Você também pode aplicar configurações personalizadas de armazenamento em cache, transformação ou descriptografia por parâmetro ao usar getParametersByName. O exemplo a seguir recupera três parâmetros distintos do SSM Parameter Store com diferentes configurações de armazenamento em cache e transformação:

import { getParametersByName } from '@aws-lambda-powertools/parameters/ssm';
import type {
  SSMGetParametersByNameOptionsInterface
} from '@aws-lambda-powertools/parameters/ssm/types';

const props: Record<string, SSMGetParametersByNameOptionsInterface> = {
  '/develop/service/commons/telemetry/config': { maxAge: 300, transform: 'json' },
  '/no_cache_param': { maxAge: 0 },
  '/develop/service/payment/api/capture/url': {}, // When empty or undefined, it uses default values
};

export const handler = async (): Promise<void> => {
  // This returns an object with the parameter name as key
  const parameters = await getParametersByName(props);
  for (const [ key, value ] of Object.entries(parameters)) {
    console.log(`${key}: ${value}`);
  }
};

A recuperação de vários parâmetros exige que as permissões GetParameter e GetParameters estejam presentes na função de execução da função Lambda.

Recuperando segredos do Secrets Manager

Para armazenar com segurança parâmetros confidenciais, como senhas ou chaves de API para serviços externos, o Secrets Manager é uma opção adequada. Para recuperar segredos do Secrets Manager usando o utilitário de parametros, instale o cliente SDK da AWS para o Secrets Manager, além do utilitário Parameters:

npm install @aws-sdk/client-secrets-manager

Agora você pode acessar um segredo usando sua chave da seguinte forma:

import { getSecret } from '@aws-lambda-powertools/parameters/secrets';

export const handler = async (): Promise<void> => {
  // Retrieve a single secret
  const secret = await getSecret('my-secret');
  console.log(secret);
};

Obter um segredo do Secrets Manager exige que você adicione a permissão do IAM secretsmanager:GetSecretValue à sua função de execução da função Lambda.

Recuperando uma configuração de aplicativo do AppConfig

Se você planeja aproveitar sinalizadores de recursos (feature flags) ou configurações dinâmicas de aplicativos em seus aplicativos criados no Lambda, o AppConfig é uma opção adequada. O utilitário de parâmetros facilita a busca de configurações do AppConfig e, ao mesmo tempo, se beneficia dos recursos do utilitário, como armazenamento em cache e transformações.

Por exemplo, considerando um aplicativo AppConfig chamado my-app com um ambiente chamado my-env, você pode recuperar seu perfil de configuração my-configuration da seguinte forma:

import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig';

export const handler = async (): Promise<void> => {
  // Retrieve a configuration, latest version
  const config = await getAppConfig('my-configuration', {
    environment: 'my-env',
    application: 'my-app'
  });
  console.log(config);
};

A recuperação de uma configuração exige que as permissões do IAM appconfig:GetLatestConfiguration e appconfig:StartConfigurationSession sejam anexadas à função de execução da função Lambda.

Recuperando um parâmetro de uma tabela do DynamoDB

A baixa latência e a alta flexibilidade do DynamoDB o tornam uma ótima opção para armazenar parâmetros. Para usar o DynamoDB como armazenamento de parâmetros por meio do utilitário de parametros, instale o cliente e o pacote de utilitários do DynamoDB AWS SDK, além do utilitário Parameters.

npm install @aws-sdk/client-dynamodb @aws-sdk/util-dynamodb

Por padrão, o utilitário de parâmetros espera que a tabela do DynamoDB contendo os parâmetros, tenha uma chave de partição e um atributo chamado value. Por exemplo, supondo que um item com um id de my-parameter e um valor de my-value seja armazenado em uma tabela do DynamoDB chamada my-table, você pode recuperá-lo da seguinte forma:

import { DynamoDBProvider } from '@aws-lambda-powertools/parameters/dynamodb';

const dynamoDBProvider = new DynamoDBProvider({ tableName: 'my-table' });

export const handler = async (): Promise<void> => {
  // Retrieve a value from DynamoDB
  const value = await dynamoDBProvider.get('my-parameter');
  console.log(value);
};

No caso de recuperar um único parâmetro do DynamoDB, a função de execução da função Lambda precisa ter a permissão do IAM dynamodb:GetItem.

O provedor do utilitário de parâmetros do DynamoDB também pode recuperar vários parâmetros de uma tabela com uma única solicitação por meio de uma consulta do DynamoDB. Consulte o provedor DynamoDB na documentação do Powertools for AWS Lambda (TypeScript) para obter detalhes.

Conclusão

Este blog apresenta o utilitário de parâmetros do Powertools para AWS Lambda (TypeScript) e demonstra como ele é usado com diferentes armazenamentos de parâmetros. O utilitário de parâmetros permite que você recupere segredos e parâmetros em sua função Lambda do SSM Parameter Store, Secrets Manager, AppConfig, DynamoDB e armazenamentos de parâmetros personalizados. Ao usar o utilitário, você obtém acesso a funcionalidades como armazenamento em cache e transformação, além de reduzir a quantidade de código padronizado que precisa escrever para suas funções do Lambda.

Para saber mais sobre o utilitário de parâmetros e seu conjunto completo de funcionalidades, consulte a documentação do Powertools for AWS Lambda (TypeScript).

Compartilhe seu feedback sobre o Powertools for AWS Lambda (TypeScript) abrindo um issue do GitHub.

Para obter mais recursos de aprendizado Serverless, visite Serverless Land.