Como trabalhar com camadas em Ruby para funções do Lambda

Uma camada do Lambda é um arquivo .zip que contém código ou dados complementares. As camadas geralmente contêm dependências de biblioteca, um runtime personalizado ou arquivos de configuração. A criação de uma camada envolve três etapas gerais:

Este tópico contém etapas e orientações sobre como empacotar e criar corretamente uma camada em Ruby para o Lambda com dependências de bibliotecas externas.

Pré-requisitos

Para seguir as etapas desta seção, você deve ter o seguinte:

Neste tópico, mencionamos a aplicação de amostra layer-ruby no repositório awsdocs no GitHub. Essa aplicação contém scripts que baixam as dependências e geram as camadas. A aplicação também contém funções correspondentes que usam dependências das camadas. Após criar uma camada, você pode implantar e invocar a função correspondente para verificar se tudo funciona corretamente. Como você usa o runtime Ruby 3.3 para as funções, as camadas também precisam ser compatíveis com o Ruby 3.3.

Na aplicação de amostra layer-ruby, você empacota a biblioteca tzinfo em uma camada do Lambda. O diretório layer/ contém os scripts para gerar a camada. O diretório function/ contém uma amostra de função para ajudar a testar se a camada funciona. A maior parte deste tutorial explica como criar e empacotar essa camada.

Compatibilidade da camada em Ruby com o ambiente de runtime do Lambda

Ao empacotar o código em uma camada em Ruby, você especifica os ambientes de runtime do Lambda com os quais o código é compatível. Para avaliar a compatibilidade do código com um runtime, considere quais versões do Ruby, quais sistemas operacionais e quais arquiteturas de conjunto de instruções foram projetadas para esse código.

Os runtimes em Ruby do Lambda especificam a versão do Ruby e o sistema operacional. Neste documento, você usa o runtime Ruby 3.3, que é baseado no AL2023. Para obter mais informações sobre as versões do runtime, consulte Tempos de execução compatíveis. Ao criar a função do Lambda, você especifica a arquitetura do conjunto de instruções. Neste documento, você usa a arquitetura de x86_64. Para obter mais informações sobre arquiteturas no Lambda, consulte Selecionar e configurar a arquitetura de um conjunto de instruções para a função do Lambda.

Quando você usa o código fornecido em um pacote, cada mantenedor do pacote define sua compatibilidade de forma independente. A maioria das gemas é inteiramente desenvolvida em Ruby, sendo compatível com qualquer runtime que suporte uma versão compatível da linguagem Ruby.

Às vezes, as gemas usam um recurso do Ruby, chamado extensões, para compilar código ou incluir código compilado previamente como parte do processo de instalação. Caso você dependa de uma gema com uma extensão nativa, será preciso avaliar a compatibilidade com o sistema operacional e com a arquitetura do conjunto de instruções. Para avaliar a compatibilidade entre suas gemas e o runtime em Ruby, é necessário inspecionar as gemas e sua documentação. É possível identificar se uma gema usa extensões ao verificar se o campo extensions está definido na especificação da gema. O Ruby identifica a plataforma em que está sendo executado por meio da constante global RUBY_PLATFORM. O runtime em Ruby do Lambda define a plataforma como aarch64-linux ao ser executado na arquitetura arm64, ou x86_64-linux ao ser executado na arquitetura x86_64. Embora não haja uma forma garantida de confirmar a compatibilidade de uma gema com essas plataformas, algumas gemas especificam as plataformas com suporte usando o atributo platform na especificação da gema.

Caminhos de camadas para runtimes em Ruby

Quando você adiciona uma camada a uma função, o Lambda carrega o conteúdo da camada no diretório /opt desse ambiente de execução. Para cada runtime do Lambda, a variável PATH já inclui caminhos de pasta específica no diretório /opt. Para garantir que o Lambda colete o conteúdo da camada, o arquivo .zip da camada deve ter suas dependências nos seguintes caminhos de pasta:

Neste documento, use o caminho ruby/gems/x. O Lambda espera que o conteúdo desse diretório corresponda à estrutura de um diretório de instalação do Bundler. Armazene as dependências das gemas no subdiretório /gems do caminho da camada, juntamente com outros subdiretórios de metadados. Por exemplo, o arquivo .zip de camada resultante que você cria neste tutorial tem a seguinte estrutura de diretórios:

layer_content.zip
└ ruby
    └ gems
        └ 3.3.0
            └ gems
                └ tzinfo-2.0.6
                └ <other_dependencies> (i.e. dependencies of the tzinfo package)
                └ ...
            └ <metadata generated by bundle>

A biblioteca tzinfo está localizada corretamente no diretório ruby/gems/3.3.0/. Isso garante que o Lambda consiga localizar a biblioteca durante as invocações da função.

Empacotar o conteúdo de camada

Neste exemplo, você empacota a biblioteca tzinfo do Ruby em um arquivo .zip de camada. Conclua as etapas a seguir para instalar e empacotar o conteúdo de camada.

Como criar a camada

Nesta seção, você pega o arquivo layer_content.zip gerado na seção anterior e o carrega como uma camada do Lambda. É possível fazer upload de uma camada usando o AWS Management Console ou a API do Lambda por meio da AWS Command Line Interface (AWS CLI). Ao carregar seu arquivo .zip de camada, no seguinte comando PublishLayerVersion da AWS CLI, especifique ruby3.3 como o runtime compatível e arm64 como a arquitetura compatível.

aws lambda publish-layer-version --layer-name ruby-requests-layer \
    --zip-file fileb://layer_content.zip \
    --compatible-runtimes ruby3.3 \
    --compatible-architectures "arm64"

Na resposta, anote o LayerVersionArn, que será algo como arn:aws:lambda:us-east-1:123456789012:layer:ruby-requests-layer:1. Você precisará desse nome do recurso da Amazon (ARN) na próxima etapa deste tutorial, ao adicionar a camada à função.

Como adicionar a camada à sua função

Nesta seção, você implanta uma amostra de função do Lambda que usa a biblioteca tzinfo em seu código de função e, em seguida, você anexa a camada. Para implantar a função, você precisará de um Definir permissões de uma função do Lambda com um perfil de execução. Se ainda não tiver um perfil de execução, siga as etapas na seção recolhível.

O código da função do Lambda importa a biblioteca tzinfo e, em seguida, retorna o código de status e uma string de data localizada.

require 'json'
require 'tzinfo'

def lambda_handler(event:, context:)
    tz = TZInfo::Timezone.get('America/New_York')
    { statusCode: 200, body: tz.to_local(Time.utc(2018, 2, 1, 12, 30, 0)) }
end