Criar uma função do Lambda usando uma imagem de contêiner - AWS Lambda
RequisitosUsar uma imagem base da AWSUsar uma imagem base somente para sistema operacional da AWSUsar uma imagem base que não é da AWSClientes de interface de runtimePermissões do Amazon ECRCiclo de vida da função

Criar uma função do Lambda usando uma imagem de contêiner

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:

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. Imagens base 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 no AL2023 usam o microdnf (com link simbólico dnf) como o gerenciador de pacotes, em vez do yum, que é o gerenciador de pacotes padrão no Amazon Linux 2. O microdnf é uma implementação autônoma do dnf. Para obter uma lista dos pacotes incluídos nas imagens baseadas no AL2023, consulte as colunas Contêiner mínimo em Comparar pacotes instalados em imagens de contêiner do Amazon Linux 2023. Para obter mais informações sobre as diferenças entre o AL2023 e o Amazon Linux 2, consulte Introdução ao runtime do Amazon Linux 2023 para AWS Lambda no blog AWS Compute.

nota

Para executar imagens baseadas no AL2023 localmente, inclusive com o 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:

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 runtime somente para sistema operacional no GitHub

al2

 Runtime somente para sistema operacional Amazon Linux 2 Dockerfile para runtime somente para sistema operacional no 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:

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 incluam 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 do Lambda que usam imagens desse repositório ECR.

  • LambdaecrimagecrossAccountRetrievalPolicy: o Lambda eventualmente definirá o estado de uma função como inativo se ela não for invocada por um período prolongado. 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.

Além das permissões do Lambda, o usuário ou o perfil que cria a função também deve ter as permissões BatchGetImage e GetDownloadUrlForLayer.

Ciclo de vida da função

Depois de carregar uma imagem de contêiner nova ou atualizada, o Lambda otimiza a imagem antes que a função possa processar chamadas. O processo de otimização pode levar alguns segundos. A função permanece no estado Pending até que o processo seja concluído. A função então faz a transição para o estado Active. Enquanto o estado for Pending, você poderá invocar a função, mas ocorrerá uma falha em outras operações na função. As invocações que ocorrem enquanto uma atualização de imagem está em andamento executam o código da imagem anterior.

Se uma função não é invocada por várias semanas, o Lambda recupera a versão otimizada e a função muda para o estado Inactive. Para reativar a função, você deve chamá-la. O Lambda rejeita a primeira invocação e a função entra noPendingaté que o Lambda reotimize a imagem. A função então retorna ao estado Active.

O Lambda busca periodicamente a imagem de contêiner associada a partir do repositório do Amazon ECR. Se a imagem correspondente do contêiner não existir mais no Amazon ECR ou as permissões forem revogadas, a função irá inserir o estado Failed e o Lambda retornará uma falha para qualquer chamada de função.

É possível usar a API do Lambda para obter informações sobre o estado de uma função. Para ter mais informações, consulte Estados da função do Lambda.