Implementar funciones Node.js Lambda con imágenes de contenedor
Hay tres formas de crear una imagen de contenedor para una función de Lambda en Node.js:
-
Uso de una imagen base de AWS de Node.js
Las imágenes base de AWS vienen precargadas con un tiempo de ejecución de lenguaje, un cliente de interfaz de tiempo de ejecución para administrar la interacción entre Lambda y el código de la función y un emulador de interfaz de tiempo de ejecución para realizar pruebas a nivel local.
-
Uso de una imagen base exclusiva del sistema operativo de AWS
Las imágenes base exclusivas del sistema operativo de AWS
contienen una distribución de Amazon Linux y el emulador de interfaz de tiempo de ejecución . Por lo general, estas imágenes se utilizan para crear imágenes contenedoras para lenguajes compilados, como Go y Rust, y para un lenguaje o versión de un lenguaje para los que Lambda no proporciona una imagen base, como Node.js 19. También se pueden usar imágenes base exclusivas del sistema operativo para implementar un tiempo de ejecución personalizado. Para que la imagen sea compatible con Lambda, debe incluir el cliente de interfaz de tiempo de ejecución para Node.js en la imagen. -
Uso de una imagen base que no sea de AWS
Puede utilizar una imagen base alternativa de otro registro de contenedores, como Alpine Linux o Debian. También puede utilizar una imagen personalizada creada por su organización. Para que la imagen sea compatible con Lambda, debe incluir el cliente de interfaz de tiempo de ejecución para Node.js en la imagen.
sugerencia
Para reducir el tiempo que tardan las funciones de contenedor de Lambda en activarse, consulte Uso de compilaciones de varias fases
En esta página, se explica cómo compilar, probar e implementar imágenes de contenedor para Lambda.
Temas
AWS imágenes base para Node.js
AWS proporciona las siguientes imágenes base para Node.js:
Etiquetas | Tiempo de ejecución | Sistema operativo | Dockerfile | Obsolescencia |
---|---|---|---|---|
20 |
Node.js 20 | Amazon Linux 2023 | Dockerfile para Node.js 20 en GitHub |
No programado |
18 |
Node.js 18 | Amazon Linux 2 | Dockerfile para Node.js 18 en GitHub |
31 de julio de 2025 |
Repositorio de Amazon ECR: gallery.ecr.aws/lambda/nodejs
Las imágenes base de Node.js 20 y versiones posteriores se basan en la imagen de contenedor mínima de Amazon Linux 2023. Las imágenes base anteriores utilizan Amazon Linux 2. AL2023 ofrece varias ventajas con respecto a Amazon Linux 2, incluida una huella de implementación más reducida y versiones actualizadas de bibliotecas como glibc
.
Las imágenes basadas en AL2023 utilizan microdnf
(enlazadas simbólicamente como dnf
) como administrador de paquetes en lugar de yum
, que es el administrador de paquetes predeterminado en Amazon Linux 2. microdnf
es una implementación independiente de dnf
. Para obtener una lista de los paquetes que se incluyen en las imágenes basadas en AL2023, consulte las columnas de Minimal Container de Comparing packages installed on Amazon Linux 2023 Container Images. Para obtener más información sobre las diferencias entre AL2023 y Amazon Linux 2, consulte Introducing the Amazon Linux 2023 runtime for AWS Lambda
nota
Para ejecutar imágenes basadas en AL2023 de forma local, incluso con AWS Serverless Application Model (AWS SAM), debe usar Docker en la versión 20.10.10 o posterior.
Uso de una imagen base de AWS de Node.js
Para completar los pasos de esta sección, debe disponer de lo siguiente:
-
Docker
(versión mínima 20.10.10 para las imágenes base de Node.js 20 y versiones posteriores) -
Node.js
Para crear una imagen de contenedor a partir de una imagen base AWS para Node.js
-
Cree un directorio para el proyecto y, a continuación, cambie a ese directorio.
mkdir example cd example
-
Cree un nuevo proyecto de Node.js con
npm
. Para aceptar las opciones predeterminadas proporcionadas en la experiencia interactiva, oprimaEnter
.npm init
-
Cree un nuevo archivo denominado
index.js
. Puede agregar el siguiente código de función de muestra al archivo para realizar pruebas o utilizar su propio código.ejemplo Controlador de CommonJS
exports.handler = async (event) => { const response = { statusCode: 200, body: JSON.stringify('Hello from Lambda!'), }; return response; };
-
Si su función depende de bibliotecas distintas de AWS SDK for JavaScript, utilice npm
para agregarlas al paquete. -
Cree un nuevo archivo Dockerfile con la siguiente configuración:
-
Establezca la propiedad
FROM
en el URI de la imagen base. -
Utilice el comando COPY para copiar el código de la función y las dependencias del tiempo de ejecución a
{LAMBDA_TASK_ROOT}
, una variable de entorno definido de Lambda. -
Establezca el argumento
CMD
para el controlador de la función de Lambda.
Tenga en cuenta que el Dockerfile de ejemplo no incluye una instrucción USER
. Al implementar una imagen de contenedor en Lambda, Lambda define automáticamente un usuario predeterminado de Linux con permisos de privilegio mínimo. Esto es diferente del comportamiento estándar de Docker, que utiliza de forma predeterminada el usuario root
cuando no se proporciona ninguna instrucciónUSER
.ejemplo Dockerfile
FROM
public.ecr.aws/lambda/nodejs:20
# Copy function code COPYindex.js
${LAMBDA_TASK_ROOT} # Set the CMD to your handler (could also be done as a parameter override outside of the Dockerfile) CMD [ "index.handler
" ] -
-
Cree la imagen de Docker con el comando docker build
. En el siguiente ejemplo se asigna un nombre a la imagen docker-image
y se le asigna la etiquetatest
.docker build --platform linux/amd64 -t
docker-image
:test
.nota
El comando especifica la opción
--platform linux/amd64
para garantizar que el contenedor sea compatible con el entorno de ejecución de Lambda, independientemente de la arquitectura de la máquina de compilación. Si tiene intención de crear una función de Lambda con la arquitectura del conjunto de instrucciones ARM64, asegúrese de cambiar el comando para utilizar la opción--platform linux/arm64
en su lugar.
-
Inicie la imagen de Docker con el comando docker run. En este ejemplo,
docker-image
es el nombre de la imagen ytest
es la etiqueta.docker run --platform linux/amd64 -p 9000:8080
docker-image
:test
Este comando ejecuta la imagen como un contenedor y crea un punto de conexión local en
localhost:9000/2015-03-31/functions/function/invocations
.nota
Si creó la imagen de Docker para la arquitectura del conjunto de instrucciones ARM64, asegúrese de utilizar la opción
--platform linux/
en lugar dearm64
--platform linux/
.amd64
-
Desde una nueva ventana de terminal, publique un evento en el punto de conexión local.
-
Obtenga el ID del contenedor.
docker ps
-
Use el comando docker kill
para detener el contenedor. En este comando, reemplace 3766c4ab331c
por el ID del contenedor del paso anterior.docker kill
3766c4ab331c
Para cargar la imagen en Amazon ECR y crear la función de Lambda
-
Para autenticar la CLI de Docker en su registro de Amazon ECR, ejecute el comando get-login-password
. -
Establezca el valor de
--region
en la Región de AWS en la que desee crear el repositorio de Amazon ECR. -
Reemplace
111122223333
por el ID de su Cuenta de AWS.
aws ecr get-login-password --region
us-east-1
| docker login --username AWS --password-stdin111122223333
.dkr.ecr.us-east-1
.amazonaws.com -
-
Cree un repositorio en Amazon ECR con el comando create-repository
. aws ecr create-repository --repository-name
hello-world
--regionus-east-1
--image-scanning-configuration scanOnPush=true --image-tag-mutability MUTABLEnota
El repositorio de Amazon ECR debe estar en la misma Región de AWS que la función de Lambda.
Si se realiza de la forma correcta, verá una respuesta como la siguiente:
{ "repository": { "repositoryArn": "arn:aws:ecr:us-east-1:111122223333:repository/hello-world", "registryId": "111122223333", "repositoryName": "hello-world", "repositoryUri": "111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world", "createdAt": "2023-03-09T10:39:01+00:00", "imageTagMutability": "MUTABLE", "imageScanningConfiguration": { "scanOnPush": true }, "encryptionConfiguration": { "encryptionType": "AES256" } } }
-
Copie el valor de
repositoryUri
de la salida del paso anterior. -
Ejecute el comando docker tag
para etiquetar la imagen local en su repositorio de Amazon ECR como la versión más reciente. En este comando: -
docker-image:test
es el nombre y la etiquetade su imagen de Docker. Son el nombre y la etiqueta de la imagen que especificó en el comando docker build
. -
Reemplace
<ECRrepositoryUri>
por elrepositoryUri
que ha copiado. Asegúrese de incluir:latest
al final del URI.
docker tag docker-image:test
<ECRrepositoryUri>
:latestEjemplo:
docker tag
docker-image
:test
111122223333
.dkr.ecr.us-east-1
.amazonaws.com/hello-world
:latest -
-
Ejecute el comando docker push
para implementar la imagen local en el repositorio de Amazon ECR. Asegúrese de incluir :latest
al final del URI del repositorio.docker push
111122223333
.dkr.ecr.us-east-1
.amazonaws.com/hello-world
:latest -
Cree un rol de ejecución para la función si aún no tiene uno. Necesitará el nombre de recurso de Amazon (ARN) del rol en el paso siguiente.
-
Cree la función de Lambda. En
ImageUri
, especifique el URI del repositorio anterior. Asegúrese de incluir:latest
al final del URI.aws lambda create-function \ --function-name
hello-world
\ --package-type Image \ --code ImageUri=111122223333
.dkr.ecr.us-east-1
.amazonaws.com/hello-world
:latest \ --rolearn:aws:iam::111122223333:role/lambda-ex
nota
Puede crear una función con una imagen de una cuenta AWS diferente, siempre que la imagen esté en la misma región que la función de Lambda. Para obtener más información, consulte Permisos entre cuentas de Amazon ECR.
-
Invoque la función.
aws lambda invoke --function-name
hello-world
response.jsonDebería ver una respuesta como la siguiente:
{ "ExecutedVersion": "$LATEST", "StatusCode": 200 }
-
Para ver la salida de la función, compruebe el archivo
response.json
.
Para actualizar el código de la función, debe volver a compilar la imagen, cargar la nueva imagen en el repositorio de Amazon ECR y, a continuación, utilizar el comando update-function-code
Lambda resuelve la etiqueta de la imagen en un resumen de imagen específico. Esto significa que si apunta la etiqueta de imagen que se utilizó para implementar la función a una nueva imagen en Amazon ECR, Lambda no actualiza automáticamente la función para usar la nueva imagen.
Para implementar la nueva imagen en la misma función de Lambda, debe usar el comando update-function-code--publish
crea una nueva versión de la función con la imagen del contenedor actualizada.
aws lambda update-function-code \ --function-name
hello-world
\ --image-uri111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest
\ --publish
Uso de una imagen base alternativa con el cliente de interfaz de tiempo de ejecución
Si usa una imagen base exclusiva del sistema operativo o una imagen base alternativa, debe incluir el cliente de interfaz de tiempo de ejecución en su imagen. El cliente de interfaz de tiempo de ejecución extiende el Uso de la API de tiempo de ejecución de Lambda para tiempos de ejecución personalizados, que administra la interacción entre Lambda y el código de la función.
Instale el cliente de interfaz de tiempo de ejecución para Node.js
npm install aws-lambda-ric
También puede descargar el cliente de interfaz de tiempo de ejecución Node.js
14.x
16.x
18.x
20.x
El siguiente ejemplo muestra cómo crear una imagen de contenedor para Node.js utilizando una imagen base que no es de AWS. El siguiente Dockerfile de ejemplo usa una imagen base de buster
. El Dockerfile incluye el cliente de interfaz de tiempo de ejecución.
Para completar los pasos de esta sección, debe disponer de lo siguiente:
-
Node.js
Para crear una imagen de contenedor a partir de una imagen base que no es de AWS
-
Cree un directorio para el proyecto y, a continuación, cambie a ese directorio.
mkdir example cd example
-
Cree un nuevo proyecto de Node.js con
npm
. Para aceptar las opciones predeterminadas proporcionadas en la experiencia interactiva, oprimaEnter
.npm init
-
Cree un nuevo archivo denominado
index.js
. Puede agregar el siguiente código de función de muestra al archivo para realizar pruebas o utilizar su propio código.ejemplo Controlador de CommonJS
exports.handler = async (event) => { const response = { statusCode: 200, body: JSON.stringify('Hello from Lambda!'), }; return response; };
-
Cree un nuevo Dockerfile. El siguiente Dockerfile usa una imagen base de
buster
en lugar de una imagen base de AWS. El Dockerfile incluye el cliente de interfaz de tiempo de ejecución, que hace que la imagen sea compatible con Lambda. El Dockerfile utiliza una compilación de varias etapas . La primera etapa crea una imagen de compilación, que es un entorno estándar de Node.js donde se instalan las dependencias de la función. La segunda etapa crea una imagen más compacta que incluye el código de la función y sus dependencias. Esto reduce el tamaño final de la imagen. -
Establezca la propiedad
FROM
como el identificador de la imagen base. -
Utilice el comando
COPY
para copiar el código de la función y las dependencias del tiempo de ejecución. -
Configure
ENTRYPOINT
como el módulo que desea que el contenedor de Docker ejecute cuando se inicie. En este caso, el módulo es el cliente de interfaz de tiempo de ejecución. -
Establezca el argumento
CMD
para el controlador de la función de Lambda.
Tenga en cuenta que el Dockerfile de ejemplo no incluye una instrucción USER
. Al implementar una imagen de contenedor en Lambda, Lambda define automáticamente un usuario predeterminado de Linux con permisos de privilegio mínimo. Esto es diferente del comportamiento estándar de Docker, que utiliza de forma predeterminada el usuario root
cuando no se proporciona ninguna instrucciónUSER
.ejemplo Dockerfile
# Define custom function directory ARG FUNCTION_DIR="/function" FROM
node:20-buster
as build-image # Include global arg in this stage of the build ARG FUNCTION_DIR # Install build dependencies RUN apt-get update && \ apt-get install -y \ g++ \ make \ cmake \ unzip \ libcurl4-openssl-dev # Copy function code RUN mkdir -p ${FUNCTION_DIR} COPY . ${FUNCTION_DIR} WORKDIR ${FUNCTION_DIR} # Install Node.js dependencies RUN npm install # Install the runtime interface client RUN npm install aws-lambda-ric # Grab a fresh slim copy of the image to reduce the final size FROMnode:20-buster-slim
# Required for Node runtimes which use npm@8.6.0+ because # by default npm writes logs under /home/.npm and Lambda fs is read-only ENV NPM_CONFIG_CACHE=/tmp/.npm # Include global arg in this stage of the build ARG FUNCTION_DIR # Set working directory to function root directory WORKDIR ${FUNCTION_DIR} # Copy in the built dependencies COPY --from=build-image ${FUNCTION_DIR} ${FUNCTION_DIR} # Set runtime interface client as default command for the container runtime ENTRYPOINT ["/usr/local/bin/npx", "aws-lambda-ric"
] # Pass the name of the function handler as an argument to the runtime CMD ["index.handler
"] -
-
Cree la imagen de Docker con el comando docker build
. En el siguiente ejemplo se asigna un nombre a la imagen docker-image
y se le asigna la etiquetatest
.docker build --platform linux/amd64 -t
docker-image
:test
.nota
El comando especifica la opción
--platform linux/amd64
para garantizar que el contenedor sea compatible con el entorno de ejecución de Lambda, independientemente de la arquitectura de la máquina de compilación. Si tiene intención de crear una función de Lambda con la arquitectura del conjunto de instrucciones ARM64, asegúrese de cambiar el comando para utilizar la opción--platform linux/arm64
en su lugar.
Utilice el emulador de interfaz de tiempo de ejecución
Para instalar y ejecutar el emulador de interfaz de tiempo de ejecución en su equipo local
-
Desde el directorio del proyecto, ejecute el siguiente comando para descargar el emulador de interfaz de tiempo de ejecución (arquitectura x86-64) de GitHub e instalarlo en su equipo local.
-
Inicie la imagen de Docker con el comando docker run. Tenga en cuenta lo siguiente:
-
docker-image
es el nombre de la imagen ytest
es la etiqueta. -
/usr/local/bin/npx aws-lambda-ric index.handler
es elENTRYPOINT
seguido delCMD
de su Dockerfile.
Este comando ejecuta la imagen como un contenedor y crea un punto de conexión local en
localhost:9000/2015-03-31/functions/function/invocations
.nota
Si creó la imagen de Docker para la arquitectura del conjunto de instrucciones ARM64, asegúrese de utilizar la opción
--platform linux/
en lugar dearm64
--platform linux/
.amd64
-
-
Publique un evento en el punto de conexión local.
-
Obtenga el ID del contenedor.
docker ps
-
Use el comando docker kill
para detener el contenedor. En este comando, reemplace 3766c4ab331c
por el ID del contenedor del paso anterior.docker kill
3766c4ab331c
Para cargar la imagen en Amazon ECR y crear la función de Lambda
-
Para autenticar la CLI de Docker en su registro de Amazon ECR, ejecute el comando get-login-password
. -
Establezca el valor de
--region
en la Región de AWS en la que desee crear el repositorio de Amazon ECR. -
Reemplace
111122223333
por el ID de su Cuenta de AWS.
aws ecr get-login-password --region
us-east-1
| docker login --username AWS --password-stdin111122223333
.dkr.ecr.us-east-1
.amazonaws.com -
-
Cree un repositorio en Amazon ECR con el comando create-repository
. aws ecr create-repository --repository-name
hello-world
--regionus-east-1
--image-scanning-configuration scanOnPush=true --image-tag-mutability MUTABLEnota
El repositorio de Amazon ECR debe estar en la misma Región de AWS que la función de Lambda.
Si se realiza de la forma correcta, verá una respuesta como la siguiente:
{ "repository": { "repositoryArn": "arn:aws:ecr:us-east-1:111122223333:repository/hello-world", "registryId": "111122223333", "repositoryName": "hello-world", "repositoryUri": "111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world", "createdAt": "2023-03-09T10:39:01+00:00", "imageTagMutability": "MUTABLE", "imageScanningConfiguration": { "scanOnPush": true }, "encryptionConfiguration": { "encryptionType": "AES256" } } }
-
Copie el valor de
repositoryUri
de la salida del paso anterior. -
Ejecute el comando docker tag
para etiquetar la imagen local en su repositorio de Amazon ECR como la versión más reciente. En este comando: -
docker-image:test
es el nombre y la etiquetade su imagen de Docker. Son el nombre y la etiqueta de la imagen que especificó en el comando docker build
. -
Reemplace
<ECRrepositoryUri>
por elrepositoryUri
que ha copiado. Asegúrese de incluir:latest
al final del URI.
docker tag docker-image:test
<ECRrepositoryUri>
:latestEjemplo:
docker tag
docker-image
:test
111122223333
.dkr.ecr.us-east-1
.amazonaws.com/hello-world
:latest -
-
Ejecute el comando docker push
para implementar la imagen local en el repositorio de Amazon ECR. Asegúrese de incluir :latest
al final del URI del repositorio.docker push
111122223333
.dkr.ecr.us-east-1
.amazonaws.com/hello-world
:latest -
Cree un rol de ejecución para la función si aún no tiene uno. Necesitará el nombre de recurso de Amazon (ARN) del rol en el paso siguiente.
-
Cree la función de Lambda. En
ImageUri
, especifique el URI del repositorio anterior. Asegúrese de incluir:latest
al final del URI.aws lambda create-function \ --function-name
hello-world
\ --package-type Image \ --code ImageUri=111122223333
.dkr.ecr.us-east-1
.amazonaws.com/hello-world
:latest \ --rolearn:aws:iam::111122223333:role/lambda-ex
nota
Puede crear una función con una imagen de una cuenta AWS diferente, siempre que la imagen esté en la misma región que la función de Lambda. Para obtener más información, consulte Permisos entre cuentas de Amazon ECR.
-
Invoque la función.
aws lambda invoke --function-name
hello-world
response.jsonDebería ver una respuesta como la siguiente:
{ "ExecutedVersion": "$LATEST", "StatusCode": 200 }
-
Para ver la salida de la función, compruebe el archivo
response.json
.
Para actualizar el código de la función, debe volver a compilar la imagen, cargar la nueva imagen en el repositorio de Amazon ECR y, a continuación, utilizar el comando update-function-code
Lambda resuelve la etiqueta de la imagen en un resumen de imagen específico. Esto significa que si apunta la etiqueta de imagen que se utilizó para implementar la función a una nueva imagen en Amazon ECR, Lambda no actualiza automáticamente la función para usar la nueva imagen.
Para implementar la nueva imagen en la misma función de Lambda, debe usar el comando update-function-code--publish
crea una nueva versión de la función con la imagen del contenedor actualizada.
aws lambda update-function-code \ --function-name
hello-world
\ --image-uri111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest
\ --publish