Criar seu primeiro Lambda MicroVM

Este tutorial explica como criar uma imagem do AWS Lambda MicroVM e executar uma microVM a partir dela. Ao final, você terá uma aplicação em execução acessível por HTTPS.

Pré-requisitos

Você precisa de duas coisas antes de começar:

1. Um bucket do Amazon S3 na sua região da AWS preferida para armazenar o artefato da sua aplicação (o arquivo zip que você criará na Etapa 2).

2. Um perfil de compilação do IAM que o Lambda assume durante a criação da imagem. O Lambda usa esse perfil para baixar o artefato de código do Amazon S3 e gravar logs de compilação no CloudWatch.

Crie o perfil do IAM com a política de confiança a seguir. Isso permite que o serviço do Lambda assuma o perfil:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "Service": "lambda.amazonaws.com" },
    "Action": ["sts:AssumeRole", "sts:TagSession"]
  }]
}

Anexe a política de permissões a seguir ao perfil. Substitua <your-bucket-name> pelo nome do bucket do Amazon S3:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:GetObject"],
      "Resource": "arn:aws:s3:::<your-bucket-name>/*"
    },
    {
      "Effect": "Allow",
      "Action": ["logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents"],
      "Resource": "arn:aws:logs:*:*:*"
    }
  ]
}

nota

Se Dockerfile extrair de um repositório privado do AWS ECR, inclua também ecr:GetAuthorizationToken e ecr:BatchGetImage à política de permissões.

Criação da primeira imagem da microVM

A imagem da microVM captura sua aplicação em um estado totalmente inicializado. Quando você executa uma microVM a partir dessa imagem, sua aplicação é iniciada imediatamente, sem atraso na inicialização.

Etapa 1: escreva sua aplicação e o Dockerfile

Crie um servidor HTTP simples que será executado dentro da sua microVM. Esse exemplo usa o Node.js sem dependências externas:

app.js

// Minimal HTTP server — listens on port 8080
const http = require('http');

const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({ status: 'ok', path: req.url }));
});

server.listen(8080, () => {
  console.log('Listening on port 8080');
});

Em seguida, crie um Dockerfile que empacote e inicie sua aplicação:

Dockerfile

# Use a lightweight Node.js runtime for your application layers
FROM node:24-alpine

# Set the working directory inside the container
WORKDIR /app

# Copy your application code
COPY app.js .

# Declare the port your app listens on
EXPOSE 8080

# Start the application — Lambda snapshots the running state
CMD ["node", "app.js"]

nota

A instrução FROM define a imagem do contêiner para as camadas da sua aplicação. Você pode usar qualquer imagem de contêiner compatível. A imagem base gerenciada pelo Lambda, que fornece o sistema operacional e os componentes de serviço da microVM), é especificada separadamente com --base-image-arn na Etapa 3.

Se sua aplicação gerar valores exclusivos (IDs, segredos ou material criptográfico), use a biblioteca CSPRNG (gerador de números pseudoaleatórios protegidos por criptografia) padrão da sua linguagem para garantir exclusividade nas microVMs. Se sua aplicação usar OpenSSL, use a imagem base de contêiner do Lambda, que inclui uma versão compatível com snapshots. Para obter detalhes, consulte a seção de compatibilidade de snapshots em Imagens da microVM.

Etapa 2: empacotar e fazer o upload no Amazon S3

Empacote app.js e Dockerfile em um arquivo zip e, em seguida, faça o upload desse arquivo no bucket do Amazon S3. Execute os seguintes comandos em seu terminal:

zip app.zip app.js Dockerfile
aws s3 cp app.zip s3://your-bucket-name/app.zip

Etapa 3: criar a imagem da microVM

Chame create-microvm-image para iniciar a compilação. O Lambda baixa seu zip do Amazon S3, executa Dockerfile, inicia sua aplicação e captura um snapshot do Firecracker do estado totalmente inicializado:

aws lambda-microvms create-microvm-image \
  --name my-first-microvm-image \
  --code-artifact uri=s3://your-bucket-name/app.zip \
  --base-image-arn arn:aws:lambda:us-east-1:aws:microvm-image:al2023-1 \
  --build-role-arn arn:aws:iam::123456789012:role/MicrovmBuildRole

A imagem se inicia no estado CREATING. Verifique o status da compilação com:

aws lambda-microvms get-microvm-image \
  --image-identifier my-first-microvm-image

Quando a compilação é concluída, o campo state é alterado para CREATED:

{
  "imageName": "my-first-microvm-image",
  "imageArn": "arn:aws:lambda:us-east-1:123456789012:microvm-image:my-first-microvm-image",
  "state": "CREATED",
  "imageVersion": "1.0",
  ...
}

Se o estado for CREATE_FAILED, verifique os logs de compilação no CloudWatch em /aws/lambda/microvms/my-first-microvm-image.

Execução de sua primeira microVM

Quando a imagem da microVM atingir o estado CREATED, você poderá executar as microVMs a partir dela. Cada imagem pode iniciar várias microVMs: por locatário, sessão do usuário ou trabalho.

Execute uma microVM com o seguinte comando:

aws lambda-microvms run-microvm \
  --image-identifier my-first-microvm-image \
  --ingress-network-connectors "arn:aws:lambda:us-east-1:aws:network-connector:aws-network-connector:ALL_INGRESS" \
  --egress-network-connectors "arn:aws:lambda:us-east-1:aws:network-connector:aws-network-connector:INTERNET_EGRESS" \
  --idle-policy '{"autoResumeEnabled":true,"maxIdleDurationSeconds":900,"suspendedDurationSeconds":300}'

Explicação dos parâmetros:

• --ingress-network-connectors: permite tráfego HTTPS de entrada para sua microVM em todas as portas. É um conector gerenciado pelo Lambda.

• --egress-network-connectors: permite o acesso à internet de saída a partir da microVM. É um conector gerenciado pelo Lambda.

• --idle-policy: configura o comportamento automático de suspensão-retomada. Essa política suspende a microVM após 15 minutos de inatividade, a mantém suspensa por até 5 minutos e é retomada automaticamente quando o tráfego chega.

A resposta inclui a ID da microVM e o URL do endpoint:

{
  "microvmId": "mvm-01234567-abcd-ef01-2345-6789abcdef01",
  "state": "PENDING",
  "endpoint": "mvm-01234567-abcd-ef01-2345-6789abcdef01.lambda-microvm.us-east-1.on.aws",
  ...
}

Aguarde até que o estado atinja RUNNING:

aws lambda-microvms get-microvm \
  --microvm-identifier mvm-01234567-abcd-ef01-2345-6789abcdef01

Conexão à microVM

Todas as solicitações ao endpoint de uma microVM exigem um token de autenticação. Gere um com:

aws lambda-microvms create-microvm-auth-token \
  --microvm-identifier mvm-01234567-abcd-ef01-2345-6789abcdef01 \
  --expiration-in-minutes 30 \
  --allowed-ports '[{"allPorts":{}}]'

A resposta inclui um token no campo authToken. Use-o para enviar uma solicitação à sua aplicação em execução:

curl https://mvm-01234567-abcd-ef01-2345-6789abcdef01.lambda-microvm.us-east-1.on.aws/ \
  -H "X-aws-proxy-auth: <token-value>"

Você deve ver a resposta da sua aplicação:

{"status":"ok","path":"/"}

Sua microVM está executando e fornecendo tráfego. A aplicação que você escreveu na Etapa 1 está ativa no URL do endpoint.

Fazer a limpeza.

Para evitar cobranças contínuas, encerre a microVM quando terminar:

aws lambda-microvms terminate-microvm \
  --microvm-identifier mvm-01234567-abcd-ef01-2345-6789abcdef01

Próximas etapas

• Saiba mais sobre Principais conceitos para entender o processo de snapshot, os estados do ciclo de vida e as imagens básicas.

• Explore Imagens da microVM para saber mais sobre hooks de compilação de imagens, versionamento e compatibilidade de snapshots.

• Consulte Execução de microVMs para obter exemplos de SDK, ganchos do ciclo de vida e estratégias de escalabilidade.