Trabalhar com imagens de contêiner do Lambda

O código da função do AWS Lambda consiste em scripts ou programas compilados e as dependências deles. Você usa umpacote de implantaçãopara implantar seu código de função no Lambda. O Lambda é compatível com dois tipos de pacotes de implantação: imagens de contêiner e arquivos .zip.

Existem três maneiras de criar uma imagem de contêiner para uma função do Lambda:

• Usar uma imagem base da AWS para Lambda

  As imagens base da AWS são pré-carregadas com um  runtime de linguagem, um cliente de interface de runtime para gerenciar a interação entre o Lambda e o código da sua função e um emulador de interface de runtime para testes locais.

• Usar uma imagem base somente para sistema operacional da AWS

  As imagens base somente para sistema operacional da AWS contêm uma distribuição do Amazon Linux e o emulador de interface de runtime. Essas imagens são comumente usadas para criar imagens de contêiner para linguagens compiladas, como Go e Rust e para uma linguagem ou versão de linguagem para a qual o Lambda não fornece uma imagem base, como Node.js 19. Você também pode usar imagens base somente para sistema operacional para implementar um runtime personalizado. Para tornar a imagem compatível com o Lambda, você deve incluir um cliente de interface de runtime para sua linguagem na imagem.

• Usar uma imagem base que não é da AWS

  Você também pode usar uma imagem base alternativa de outro registro de contêiner, como Alpine Linux ou Debian. Você também pode usar uma imagem personalizada criada por sua organização. Para tornar a imagem compatível com o Lambda, você deve incluir um cliente de interface de runtime para sua linguagem na imagem.

dica

Para reduzir o tempo necessário para que as funções do contêiner do Lambda se tornem ativas, consulte Use multi-stage builds na documentação do Docker. Para criar imagens de contêiner eficientes, siga as Melhores práticas para gravar Dockerfiles.

Para criar uma função do Lambda de uma imagem de contêiner, crie sua imagem localmente e carregue-a em um repositório do Amazon Elastic Container Registry (Amazon ECR). Em seguida, especifique o URI do repositório quando criar a função. O repositório do Amazon ECR deve estar na mesma Região da AWS que a função do Lambda. É possível criar uma função usando uma imagem em uma conta da AWS diferente desde que a imagem esteja na mesma região da função do Lambda. Para ter mais informações, consulte Permissões entre contas do Amazon ECR.

Esta página explica os tipos de imagem base e os requisitos para criar imagens de contêiner compatíveis com o Lambda.

nota

Você não pode alterar o tipo de pacote de implantação (.zip ou imagem de contêiner) de uma função existente. Por exemplo, você não pode converter uma função de imagem de contêiner para usar um arquivo compactado. zip. É necessário criar uma nova função.

Requisitos

Instale a AWS Command Line Interface (AWS CLI) versão 2 e a CLI do Docker. Além disso, observe os seguintes requisitos:

• A imagem de contêiner deve implementar o API de tempo de execução do Lambda. Os clientes de interface de runtime de código aberto da AWS implementam a API. Você pode adicionar um cliente de interface de runtime à sua imagem base preferida para torná-lo compatível com o Lambda.

• Deve ser possível executar a imagem do contêiner em um sistema de arquivos somente leitura. Seu código de função pode acessar um diretório /tmp gravável com entre 512 MB e 10.240 MB, em incrementos de 1 MB, de armazenamento.

• O usuário padrão do Lambda deve ser capaz de ler todos os arquivos necessários para executar seu código de função. O Lambda segue as práticas recomendadas de segurança definindo um usuário padrão do Linux com permissões menos privilegiadas. Verifique se o código da aplicação não depende de arquivos que outros usuários do Linux estejam restringidos de executar.

• O Lambda é compatível apenas com imagens de contêiner baseadas em Linux.

• O Lambda fornece imagens base multiarquitetura. No entanto, a imagem que você criar para sua função deverá ser direcionada para apenas uma das arquiteturas. O Lambda não oferece suporte a funções que usam imagens de contêiner multiarquitetura.

Usar uma imagem base da AWS para Lambda

Você pode usar uma das imagens base da AWS para o Lambda criar a imagem de contêiner do código da função. As imagens de base são pré-carregadas com um runtime de linguagem e outros componentes necessários para executar uma imagem de contêiner no Lambda. Você adiciona seu código de função e as dependências à imagem base e, em seguida, empacota-os como uma imagem de contêiner.

A AWS fornece atualizações periodicamente para as imagens base da AWS para o Lambda. Se o Dockerfile incluir o nome da imagem na propriedade FROM, seu cliente Docker extrairá a versão mais recente da imagem do repositório do Amazon ECR. Para usar a imagem base atualizada, você deve reconstruir a imagem do contêiner e atualizar o código da função.

As imagens base do Node.js 20, Python 3.12, Java 21, AL2023 e versões posteriores são baseadas na imagem de contêiner mínimo do Amazon Linux 2023. As imagens básicas anteriores usam o Amazon Linux 2. O AL2023 oferece várias vantagens em relação ao Amazon Linux 2, incluindo uma área de implantação menor e versões atualizadas de bibliotecas, como glibc.

As imagens baseadas em AL2023 usam microdnf (com link simbólico comodnf) como gerenciador de pacotes em vez deyum, que é o gerenciador de pacotes padrão no Amazon Linux 2. microdnfé uma implementação independente do. dnf Para obter uma lista de pacotes incluídos nas imagens baseadas em AL2023, consulte as colunas Minimal Container em Comparating packages installed on Amazon Linux 2023 Container Images. Para obter mais informações sobre as diferenças entre o AL2023 e o Amazon Linux 2, consulte Apresentando o tempo de execução do Amazon Linux 2023 para AWS Lambda no blog de AWS computação.

nota

Para executar imagens baseadas em AL2023 localmente, inclusive com AWS Serverless Application Model (AWS SAM), você deve usar o Docker versão 20.10.10 ou posterior.

Para criar uma imagem de contêiner usando uma imagem base da AWS, escolha as instruções para sua linguagem preferencial:

• Node.js

• TypeScript(usa uma imagem base do Node.js)

• Python

• Java

• Go

• .NET

• Ruby

Usar uma imagem base somente para sistema operacional da AWS

As imagens base somente para sistema operacional da AWS contêm uma distribuição do Amazon Linux e o emulador de interface de runtime. Essas imagens são comumente usadas para criar imagens de contêiner para linguagens compiladas, como Go e Rust e para uma linguagem ou versão de linguagem para a qual o Lambda não fornece uma imagem base, como Node.js 19. Você também pode usar imagens base somente para sistema operacional para implementar um runtime personalizado. Para tornar a imagem compatível com o Lambda, você deve incluir um cliente de interface de runtime para sua linguagem na imagem.

Tags	Runtime	Sistema operacional	Dockerfile	Desaprovação
al2023	Runtime somente para sistema operacional	Amazon Linux 2023	Dockerfile para tempo de execução somente para sistema operacional em GitHub
al2	Runtime somente para sistema operacional	Amazon Linux 2	Dockerfile para tempo de execução somente para sistema operacional em GitHub

Galeria pública do Amazon Elastic Container Registry: gallery.ecr.aws/lambda/provided

Usar uma imagem base que não é da AWS

O Lambda é compatível com qualquer imagem que esteja em conformidade com um dos seguintes formatos de manifesto de imagem:

• Esquema 2 de manifesto V2 de imagem de Docker (usado com o Docker versão 1.10 e posteriores)

• Especificações de Open Container Initiative (OCI – Iniciativa de contêiner aberto) (v1.0.0 e posteriores)

O Lambda oferece suporte a um tamanho máximo de imagem descompactada de 10 GB, incluindo todas as camadas.

nota

Para tornar a imagem compatível com o Lambda, você deve incluir um cliente de interface de runtime para sua linguagem na imagem.

Clientes de interface de runtime

Se você usar uma imagem base somente para sistema operacional ou uma imagem base alternativa, deverá incluir um cliente de interface de runtime na imagem. O cliente de interface de runtime deve estender o API de tempo de execução do Lambda, que gerencia a interação entre o Lambda e o código da sua função. A AWS fornece clientes de interface de runtime de código aberto para as seguintes linguagens:

• Node.js

• Python

• Java

• .NET

• Go

• Ruby

• Rust o cliente de runtime do Rust é um pacote experimental. Ele está sujeito a alterações, e é destinado apenas a fins de avaliação.

Caso esteja usando uma linguagem que não tenha um cliente de interface de runtime fornecido pela AWS, você deverá criar seu próprio cliente de interface de runtime.

Permissões do Amazon ECR

Antes de criar uma função do Lambda com base em uma imagem de contêiner, você deve criar a imagem localmente e carregá-la no repositório do Amazon ECR. Quando criar a função, especifique o URI do repositório do Amazon ECR.

Certifique-se de que as permissões para o usuário ou o perfil que cria a função contenham as políticas gerenciadas pela AWS GetRepositoryPolicy e SetRepositoryPolicy.

Por exemplo, use o console do IAM para criar uma função com a seguinte política:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "VisualEditor0",
      "Effect": "Allow",
      "Action": [
        "ecr:SetRepositoryPolicy",
        "ecr:GetRepositoryPolicy"
      ],
      "Resource": "arn:aws:ecr:us-east-1:111122223333:repository/hello-world"
    }
  ]
}

Políticas do repositório do Amazon ECR

Para uma função na mesma conta que a imagem de contêiner no Amazon ECR, você pode adicionar as permissões ecr:BatchGetImage e ecr:GetDownloadUrlForLayer à política do repositório do Amazon ECR. O exemplo a seguir mostra a política mínima:

{
        "Sid": "LambdaECRImageRetrievalPolicy",
        "Effect": "Allow",
        "Principal": {
          "Service": "lambda.amazonaws.com"
        },
        "Action": [
          "ecr:BatchGetImage",
          "ecr:GetDownloadUrlForLayer"
        ]
    }   

Para obter mais informações sobre as permissões de repositório do Amazon ECR, consulte Políticas de repositório privado no Guia do usuário do Amazon Elastic Container Registry.

Se o repositório do Amazon ECR não incluir essas permissões, o Lambda adicionaráecr:BatchGetImageeecr:GetDownloadUrlForLayerpara as permissões do repositório de imagens do contêiner. O Lambda só poderá adicionar essas permissões se a entidade principal que chamar o Lambda tiver as permissões ecr:getRepositoryPolicy e ecr:setRepositoryPolicy.

Para visualizar ou editar suas permissões de repositório do Amazon ECR, siga as instruções em Configurar uma instrução de política de repositório no Guia do usuário do Amazon Elastic Container Registry.

Permissões entre contas do Amazon ECR

Uma conta diferente na mesma região pode criar uma função que usa uma imagem de contêiner de propriedade da sua conta. No exemplo a seguir, a política de permissões de repositório do Amazon ECR precisa das instruções apresentadas a seguir para conceder acesso à conta número 123456789012.

• CrossAccountPermission— Permite que a conta 123456789012 crie e atualize funções Lambda que usam imagens desse repositório ECR.

• LambdaECR — O ImageCrossAccountRetrievalPolicy Lambda acabará por definir o estado de uma função como inativa se ela não for invocada por um longo período. Essa declaração é necessária para que o Lambda possa recuperar a imagem do contêiner para otimização e armazenamento em cache em nome da função pertencente a 123456789012.

exemplo — Adicionar permissão entre contas ao repositório

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "CrossAccountPermission",
      "Effect": "Allow",
      "Action": [
        "ecr:BatchGetImage",
        "ecr:GetDownloadUrlForLayer"
      ],
      "Principal": {
        "AWS": "arn:aws:iam::123456789012:root"
      }
    },
    {
      "Sid": "LambdaECRImageCrossAccountRetrievalPolicy",
      "Effect": "Allow",
      "Action": [
        "ecr:BatchGetImage",
        "ecr:GetDownloadUrlForLayer"
      ],
      "Principal": {
        "Service": "lambda.amazonaws.com"
      },
      "Condition": {
        "StringLike": {
          "aws:sourceARN": "arn:aws:lambda:us-east-1:123456789012:function:*"
        }
      }
    }
  ]
}

Para dar acesso a várias contas, você adiciona os IDs de conta à lista Principal na política CrossAccountPermission e à lista Avaliação da condição em LambdaECRImageCrossAccountRetrievalPolicy.

Se você estiver trabalhando com várias contas em uma organização da AWS, recomendamos enumerar cada ID de conta na política de permissões do ECR. Essa abordagem se alinha com a prática recomendada de segurança da AWS de definir permissões estreitas nas políticas do IAM.

Configurações de imagem de contêiner

A seguir, são mostradas as configurações comuns de imagem de contêiner. Se você usá-las no Dockerfile, observe como o Lambda interpreta e processa essas configurações:

• ENTRYPOINT: especifica o caminho absoluto para o ponto de entrada da aplicação.

• CMD: especifica parâmetros adicionais que você deseja transmitir com ENTRYPOINT.

• WORKDIR: especifica o caminho absoluto para o diretório de trabalho.

• ENV: especifica uma variável de ambiente para a função do Lambda.

Para obter mais informações sobre como o Docker usa as configurações de imagem de contêiner, consulte ENTRYPOINT na referência do Dockerfile no site Docker Docs. Para obter mais informações sobre como usar ENTRYPOINT e CMD, consulte Demystifying ENTRYPOINT and CMD in Docker no Blog de código aberto da AWS.

Você pode especificar as configurações de imagem de contêiner no Dockerfile ao criar sua imagem. Você também pode substituir essas configurações usando o console do Lambda ou a API do Lambda. Isso permite implantar várias funções que implementam a mesma imagem de contêiner, mas com diferentes configurações de runtime.

Atenção

Quando você especifica ENTRYPOINT ou CMD no Dockerfile ou como uma substituição, certifique-se de inserir o caminho absoluto. Além disso, não use links simbólicos como ponto de entrada para o contêiner.

Para substituir os valores de configuração na imagem do contêiner

1. Abra a página Funções do console do Lambda.

2. Escolha a função a ser atualizada.

3. Sob a Image configuration (Configuração da imagem), escolha Edit (Editar).

4. Insira novos valores para qualquer uma das configurações de substituição e escolha Save (Salvar).

5. (Opcional) Para adicionar ou substituir variáveis de ambiente, em Environment variables (Variáveis de ambiente), escolha Edit (Editar).

Para ter mais informações, consulte Como usar variáveis ​​de ambiente do Lambda.