Tabla de contenido

• ¿Cuáles son los requisitos previos?
• ¿Por qué debe usar Docker en lugar del despliegue Zip?
• ¿Cómo se configuran las dependencias de Maven?
• ¿Cómo se escribe el controlador Lambda?
• ¿Cómo se configura la plantilla SAM?
• ¿Cómo se construye el Dockerfile?
• ¿Cómo se construye y despliega la función Lambda?
• ¿Cuáles son los próximos pasos?

¿Cuáles son los requisitos previos? {#prerequisites}

Antes de comenzar, confirme que las siguientes herramientas están instaladas en la máquina de desarrollo. Cada herramienta desempeña un papel específico en el pipeline de construcción y despliegue.

• IntelliJ IDEA — el IDE utilizado en esta guía. Descargue desde jetbrains.com/idea.
• AWS Toolkit para JetBrains — proporciona el asistente de proyectos SAM y configuraciones de ejecución de Lambda dentro de IntelliJ. Las instrucciones de configuración están en la página de documentación de AWS Toolkit para JetBrains.
• AWS SAM CLI — la herramienta de línea de comandos que construye imágenes Docker y despliega funciones Lambda. Instálelo siguiendo la guía de instalación del SAM CLI.
• Docker Desktop — necesario porque la función Lambda se empaqueta como una imagen de contenedor, no un archivo Zip. Descargue Docker Community Edition.

Para pruebas de invocación local antes de desplegar en AWS, también instale:

• Java 8 JDK — disponible en la página de descargas de Oracle JDK 8.
• Apache Maven — siga la guía de instalación de Maven.

Una vez que todas las herramientas estén en su lugar, abra IntelliJ IDEA y cree un nuevo proyecto a través de Archivo → Nuevo → Proyecto. En el asistente de proyectos, seleccione la plantilla de AWS Lambda y elija las siguientes opciones:

• Tipo de Paquete: Image
• Tiempo de Ejecución: java8 o java11
• Plantilla SAM: Maven

¿Por qué debe usar Docker en lugar del despliegue Zip? {#why-docker}

AWS Lambda admite dos tipos de paquetes de despliegue: archivos Zip e imágenes de contenedor. El despliegue Zip funciona bien para funciones Java livianas porque el entorno de ejecución es completamente gestionado por AWS. Sin embargo, IronPDF proporciona un binario nativo — un motor de renderizado de PDF basado en Chrome — que debe extraerse y ejecutarse en tiempo de ejecución. El entorno de ejecución de Lambda para implementaciones Zip restringe las escrituras del sistema de archivos a /tmp, y las limitaciones de capas del paquete Zip impiden la extracción de grandes binarios nativos.

El despliegue de imagen de contenedor elimina estas restricciones. Cuando define su propia imagen Docker, controla el sistema operativo base, los paquetes de sistema instalados y el diseño del directorio. El motor de renderizado de IronPDF se puede extraer a /tmp al inicio, las bibliotecas del sistema necesarias se pueden preinstalar en la imagen, y el límite de tamaño del contenedor (10 GB) es lo suficientemente grande para alojar el motor completo.

La consecuencia práctica es simple: configure PackageType: Image en template.yaml y construya usando una imagen base compatible con Docker. El SAM CLI se encarga del resto.

¿Cómo se configuran las dependencias de Maven? {#maven-dependencies}

El archivo pom.xml necesita tres categorías de dependencias adicionales más allá del SDK estándar de Lambda: la biblioteca Java de IronPDF, el motor de renderizado IronPDF Linux x64, y el transporte gRPC utilizado internamente por el motor de IronPDF.

Abra pom.xml y agregue las siguientes dependencias dentro de <dependencies>:

//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf</artifactId>
    <version>2024.9.1</version>
</dependency>
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf-engine-linux-x64</artifactId>
    <version>2024.9.1</version>
</dependency>
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-simple</artifactId>
    <version>2.0.3</version>
</dependency>
<dependency>
    <groupId>io.perfmark</groupId>
    <artifactId>perfmark-api</artifactId>
    <version>0.26.0</version>
</dependency>
<dependency>
    <groupId>io.grpc</groupId>
    <artifactId>grpc-okhttp</artifactId>
    <version>1.50.2</version>
</dependency>
<dependency>
    <groupId>io.grpc</groupId>
    <artifactId>grpc-netty-shaded</artifactId>
    <version>1.50.2</version>
</dependency>

//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf</artifactId>
    <version>2024.9.1</version>
</dependency>
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf-engine-linux-x64</artifactId>
    <version>2024.9.1</version>
</dependency>
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-simple</artifactId>
    <version>2.0.3</version>
</dependency>
<dependency>
    <groupId>io.perfmark</groupId>
    <artifactId>perfmark-api</artifactId>
    <version>0.26.0</version>
</dependency>
<dependency>
    <groupId>io.grpc</groupId>
    <artifactId>grpc-okhttp</artifactId>
    <version>1.50.2</version>
</dependency>
<dependency>
    <groupId>io.grpc</groupId>
    <artifactId>grpc-netty-shaded</artifactId>
    <version>1.50.2</version>
</dependency>

El artefacto ironpdf-engine-linux-x64 agrupa el motor de renderizado precompilado basado en Chromium para Linux de 64 bits. Esto es lo que permite a IronPDF renderizar HTML a PDF dentro del contenedor de Lambda. Sin él, las llamadas de renderizado fallarán con un error de binario faltante. Las dependencias de gRPC (grpc-okhttp, grpc-netty-shaded, perfmark-api) son necesarias porque IronPDF se comunica con su motor de renderizado a través de un canal gRPC local. La dependencia slf4j-simple proporciona una implementación mínima de registro para que los registros internos de IronPDF sean visibles en CloudWatch.

Siembre alinee los números de versión de ironpdf y ironpdf-engine-linux-x64 — mezclar versiones causará un fallo al iniciar. Consulte IronPDF for Java en Maven Central para la última cadena de versión.

¿Cómo se escribe el controlador Lambda? {#lambda-handler}

La clase handler de Lambda recibe un APIGatewayProxyRequestEvent, genera un PDF, y devuelve un APIGatewayProxyResponseEvent. Deben aparecer dos llamadas de configuración de IronPDF antes de la primera operación de renderizado: establecer el directorio de trabajo en /tmp y opcionalmente habilitar el registro de depuración.

Reemplace el contenido de App.java con lo siguiente:

//:path=App.java
import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyRequestEvent;
import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyResponseEvent;
import com.ironsoftware.ironpdf.PdfDocument;
import com.ironsoftware.ironpdf.Settings;

import java.nio.file.Paths;
import java.util.HashMap;
import java.util.Map;

public class App {
    public APIGatewayProxyResponseEvent handleRequest(
            final APIGatewayProxyRequestEvent input,
            final Context context) {

        APIGatewayProxyResponseEvent response = new APIGatewayProxyResponseEvent();

        // IronPDF must write its engine binaries and temporary files to /tmp.
        // This is the only writable path available in the Lambda execution environment.
        Settings.setIronPdfEngineWorkingDirectory(Paths.get("/tmp/"));

        // Enable debug logging to CloudWatch during initial testing.
        Settings.setDebug(true);

        try {
            context.getLogger().log("Starting PDF render");

            // Render a PDF from a live URL. Replace with your own HTML or URL as needed.
            PdfDocument pdf = PdfDocument.renderUrlAsPdf("https://www.google.com");

            context.getLogger().log("PDF render complete");

            // Save the rendered PDF to /tmp. Files in /tmp persist for the lifetime
            // of the Lambda execution environment (warm instance).
            pdf.saveAs("/tmp/output.pdf");

            Map<String, String> headers = new HashMap<>();
            headers.put("Content-Type", "application/json");

            return response
                    .withStatusCode(200)
                    .withHeaders(headers)
                    .withBody("PDF generated successfully.");

        } catch (Exception e) {
            context.getLogger().log("PDF render failed: " + e.getMessage());
            return response
                    .withStatusCode(500)
                    .withBody("{\"error\": \"" + e.getMessage() + "\"}");
        }
    }
}

//:path=App.java
import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyRequestEvent;
import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyResponseEvent;
import com.ironsoftware.ironpdf.PdfDocument;
import com.ironsoftware.ironpdf.Settings;

import java.nio.file.Paths;
import java.util.HashMap;
import java.util.Map;

public class App {
    public APIGatewayProxyResponseEvent handleRequest(
            final APIGatewayProxyRequestEvent input,
            final Context context) {

        APIGatewayProxyResponseEvent response = new APIGatewayProxyResponseEvent();

        // IronPDF must write its engine binaries and temporary files to /tmp.
        // This is the only writable path available in the Lambda execution environment.
        Settings.setIronPdfEngineWorkingDirectory(Paths.get("/tmp/"));

        // Enable debug logging to CloudWatch during initial testing.
        Settings.setDebug(true);

        try {
            context.getLogger().log("Starting PDF render");

            // Render a PDF from a live URL. Replace with your own HTML or URL as needed.
            PdfDocument pdf = PdfDocument.renderUrlAsPdf("https://www.google.com");

            context.getLogger().log("PDF render complete");

            // Save the rendered PDF to /tmp. Files in /tmp persist for the lifetime
            // of the Lambda execution environment (warm instance).
            pdf.saveAs("/tmp/output.pdf");

            Map<String, String> headers = new HashMap<>();
            headers.put("Content-Type", "application/json");

            return response
                    .withStatusCode(200)
                    .withHeaders(headers)
                    .withBody("PDF generated successfully.");

        } catch (Exception e) {
            context.getLogger().log("PDF render failed: " + e.getMessage());
            return response
                    .withStatusCode(500)
                    .withBody("{\"error\": \"" + e.getMessage() + "\"}");
        }
    }
}

La llamada a Settings.setIronPdfEngineWorkingDirectory(Paths.get("/tmp/")) es obligatoria. El entorno de ejecución de AWS Lambda monta el código de función en un directorio de solo lectura. El motor de IronPDF debe extraer archivos de soporte y crear sockets en el arranque — actividades que requieren acceso de escritura. El directorio /tmp es el único lugar en el que Lambda permite escrituras de archivos, por lo que IronPDF debe ser dirigido allí antes de que comience cualquier renderización. Si se omite esta configuración, el motor no se iniciará y cada llamada de renderización lanzará una excepción.

La llamada pdf.saveAs("/tmp/output.pdf") almacena el archivo renderizado en el sistema de archivos efímero /tmp. Si la función Lambda necesita devolver el PDF como una respuesta binaria o subirlo a S3, recupere los bytes con pdf.getBinaryData() en lugar de escribir en el disco. Para cargas de trabajo a gran escala, subir a Amazon S3 y devolver una URL prefirmada es el patrón recomendado.

¿Cómo se configura la plantilla SAM? {#sam-template}

El archivo template.yaml controla la asignación de recursos de la función Lambda. Tres configuraciones afectan directamente si IronPDF se ejecuta con éxito: Timeout, MemorySize, y EphemeralStorage.Size.

Actualice la sección Globals de template.yaml como sigue:

//:path=template.yaml
Globals:
  Function:
    Timeout: 400
    MemorySize: 2048
    EphemeralStorage:
      Size: 1024

//:path=template.yaml
Globals:
  Function:
    Timeout: 400
    MemorySize: 2048
    EphemeralStorage:
      Size: 1024

Tiempo de Espera está configurado a 400 segundos. En un arranque en frío, IronPDF debe extraer el motor de renderizado a /tmp y lanzar un proceso local de Chromium. Esta extracción puede tomar 30–60 segundos en la primera invocación. Un tiempo de espera más corto de 330 segundos causará que las invocaciones de arranque en frío fallen con un error de tiempo de espera de tarea. Las invocaciones calientes son mucho más rápidas, típicamente bajo 5 segundos para conversiones simples de HTML a PDF.

Tamaño de Memoria está configurado a 2048 MB. El motor de renderizado Chromium consume mucha memoria. La memoria mínima viable de AWS Lambda para IronPDF es de 1024 MB, pero 2048 MB reduce el riesgo de fallos por falta de memoria en páginas complejas y produce tiempos de renderizado notablemente más rápidos porque Lambda también escala la asignación de CPU proporcionalmente con la memoria.

EphemeralStorage.Size está configurado en 1024 MB. La asignación predeterminada de /tmp de Lambda es de 512 MB. IronPDF escribe los binarios del motor de renderizado, la caché de fuentes y los archivos de renderizado temporales en /tmp. Estos recursos pueden exceder los 512 MB al inicio en frío, lo que provoca que falle la extracción del motor. Configurar el almacenamiento efímero a al menos 1024 MB evita este modo de falla.

¿Cómo se construye el Dockerfile? {#dockerfile}

El Dockerfile es el núcleo de este despliegue. Realiza una construcción en múltiples etapas: la primera etapa compila el proyecto Java usando una imagen de construcción de Maven; la segunda etapa crea la imagen final del runtime de Lambda basada en Amazon Linux 2, instala los paquetes del sistema que requiere el motor Chromium de IronPDF y copia los artefactos compilados.

Abra Dockerfile del proyecto y reemplace su contenido con lo siguiente:

//:path=Dockerfile
# Stage 1: Build the Maven project
FROM public.ecr.aws/sam/build-java8.al2:latest AS build-image
WORKDIR /task
COPY src/ src/
COPY pom.xml ./
RUN mvn -q clean install
RUN mvn dependency:copy-dependencies -DincludeScope=compile

# Stage 2: Create the Lambda runtime image
FROM public.ecr.aws/lambda/java:8.al2

# Update the package index and install system libraries required by Chromium.
# These packages provide font rendering, graphics, audio, GTK3, and input
# method support — all needed by the headless browser inside IronPDF.
RUN yum update -y && \
    yum install -y \
        pango.x86_64 \
        libXcomposite.x86_64 \
        libXcursor.x86_64 \
        libXdamage.x86_64 \
        libXext.x86_64 \
        libXi.x86_64 \
        libXtst.x86_64 \
        cups-libs.x86_64 \
        libXScrnSaver.x86_64 \
        libXrandr.x86_64 \
        GConf2.x86_64 \
        alsa-lib.x86_64 \
        atk.x86_64 \
        gtk3.x86_64 \
        ipa-gothic-fonts \
        xorg-x11-fonts-100dpi \
        xorg-x11-fonts-75dpi \
        xorg-x11-utils \
        xorg-x11-fonts-cyrillic \
        xorg-x11-fonts-Type1 \
        xorg-x11-fonts-misc \
        glibc-devel.x86_64 \
        at-spi2-atk.x86_64 \
        mesa-libgbm.x86_64 \
        libxkbcommon \
        amazon-linux-extras && \
    amazon-linux-extras install epel -y && \
    yum install -y libgdiplus

# Ensure /tmp is writable by the Lambda execution user.
RUN chmod 777 /tmp/

# Copy the compiled classes and dependencies from the build stage.
COPY --from=build-image /task/target/classes /var/task/
COPY --from=build-image /task/target/dependency /var/task/lib

# Entry point: package.ClassName::methodName
CMD ["helloworld.App::handleRequest"]

Las imágenes base para ambas etapas utilizan la etiqueta java8.al2 en lugar de java8. El sufijo .al2 indica Amazon Linux 2, que es necesario para IronPDF. La imagen java8 más antigua se ejecuta en el Amazon Linux 1 original, que utiliza repositorios yum que ya no reciben actualizaciones y carecen de varios paquetes de los que depende IronPDF. Use siempre imágenes .al2 al desplegar IronPDF en Java 8.

El bloque yum install instala las bibliotecas relacionadas con X11, GTK3, Pango y fuentes que Chromium necesita para renderizar páginas. Omitir cualquiera de estos paquetes puede producir una salida PDF incompleta o hacer que el motor de renderizado falle con un error de biblioteca compartida faltante. El paquete libgdiplus es necesario para la compatibilidad con GDI+, que es utilizada por algunas operaciones de dibujo de IronPDF.

Actualice la instrucción CMD para que coincida con su nombre de paquete y clase real si difieren de helloworld.App.

¿Cómo se construye y despliega la función Lambda? {#build-deploy}

Con el archivo Dockerfile, template.yaml, pom.xml, y App.java todos configurados, ejecute los siguientes dos comandos SAM CLI desde la raíz del proyecto.

Paso 1 — Construir la imagen del contenedor:

//:path=build.sh
sam build -u

//:path=build.sh
sam build -u

El flag -u instruye a SAM para usar Docker (el modo "usar contenedor"). SAM ejecuta el Dockerfile en múltiples etapas, que compila el proyecto Maven y produce la imagen final de Lambda. Espere que este paso tome varios minutos en la primera ejecución mientras Docker descarga las imágenes base.

Paso 2 — Desplegar en AWS:

//:path=deploy.sh
sam deploy --guided

//:path=deploy.sh
sam deploy --guided

El flag --guided lanza un aviso interactivo que solicita el nombre de la pila, la región de AWS, el bucket S3 para los artefactos, y si desea confirmar los cambios antes del despliegue. Responda a las preguntas, y SAM empujará la imagen de contenedor a Amazon ECR y creará la función Lambda, API Gateway, y el rol IAM definido en template.yaml.

Después de completar el despliegue, SAM CLI muestra la URL del endpoint de la API. Abra la Consola de AWS Lambda para ver la función desplegada, ejecutar invocaciones de prueba e inspeccionar los registros de CloudWatch para obtener la salida de depuración de IronPDF.

En la primera invocación (arranque en frío), espere un tiempo de respuesta de 60 a 120 segundos mientras el entorno de ejecución de Lambda arranca e IronPDF extrae su motor de renderizado a /tmp. Las invocaciones subsiguientes en la misma instancia caliente devolverán en unos pocos segundos. Si la latencia de inicio en frío es una preocupación para cargas de trabajo de producción, considere usar Lambda Provisioned Concurrency para mantener instancias calientes.

También puede probar la función localmente antes de desplegar ejecutando sam local invoke con una carga de evento de prueba, siempre que Docker esté funcionando en la máquina de desarrollo.

¿Cuáles son los próximos pasos? {#next-steps}

La función Lambda está ahora desplegada y renderizando PDFs. Las siguientes guías cubren los pasos más comunes después de un despliegue exitoso de IronPDF:

• IronPDF for Java — Getting Started — visión general de toda la API de Java de IronPDF, incluyendo HTML a PDF, URL a PDF, y estampado de PDF.
• Cómo generar PDFs desde HTML en Java — renderizando cadenas HTML, archivos y plantillas a PDF.
• Cómo aplicar encabezados y pies de página a PDFs en Java — agregando números de página, logotipos y encabezados de texto a PDFs generados con Lambda.
• Cómo añadir marcas de agua a PDFs en Java — estampando la salida de PDF con marcas de agua de texto o imagen antes de devolverla al llamante.
• Licencias de IronPDF — opciones de licencia para despliegues de producción en Lambda, incluyendo licencias por conteo de despliegue.

Inicie una prueba gratuita de IronPDF for Java para generar y editar PDFs en su función Lambda sin restricciones durante la evaluación. Cuando esté listo para desplegar en producción, vea las opciones de licencia de IronPDF para encontrar el plan que se adapte a su carga de trabajo sin servidor.