Comment exécuter IronPDF for Java dans Google Cloud

Pourquoi les images par défaut de Cloud Function ne fonctionnent-elles pas ?

Les images d'exécution par défaut de Google Cloud Function sont minimalistes par conception — elles incluent uniquement les packages nécessaires pour exécuter le code de fonction écrit dans des langages courants. Le moteur de rendu basé sur Chromium d'IronPDF dépend d'un ensemble plus large de bibliothèques système Linux (polices, bibliothèques graphiques, outils de sandbox) qui sont absentes des images standard.

Google publie une liste complète des packages système disponibles pour chaque environnement d'exécution dans la référence des packages systèmes de Google Cloud Functions. Les dépendances de Chromium ne sont incluses dans aucun des environnements d'exécution de 2e génération standard. Tenter de charger le moteur IronPDF dans l'image par défaut entraîne un échec de chargement de la bibliothèque native au démarrage.

La solution consiste à créer une image Docker personnalisée qui installe explicitement ces packages avant l'ajout du binaire de la fonction. Cette approche est entièrement supportée par les Google Cloud Functions et est la même stratégie recommandée pour toute fonction nécessitant des binaires natifs. Consultez le guide de déploiement Linux d'IronPDF pour la liste complète des packages à inclure.

Comment créer un Dockerfile personnalisé pour Google Cloud ?

Un Dockerfile personnalisé donne un contrôle total sur l'environnement d'exécution. Commencez par l'image de base Java officielle des Google Cloud Functions, puis installez les bibliothèques système requises par Chromium.

Le Dockerfile ci-dessous démontre le modèle recommandé. Remplacez les entrées COPY et CMD par les détails spécifiques de votre projet de fonction :

//:path=Dockerfile
# Use the official Google Cloud Functions Java 17 base image
FROM gcr.io/google-appengine/java17:latest

# Install Chrome system dependencies required by IronPDF's rendering engine
RUN apt-get update && apt-get install -y \
    libglib2.0-0 \
    libnss3 \
    libatk1.0-0 \
    libatk-bridge2.0-0 \
    libcups2 \
    libdrm2 \
    libxkbcommon0 \
    libxcomposite1 \
    libxdamage1 \
    libxfixes3 \
    libxrandr2 \
    libgbm1 \
    libasound2 \
    libpango-1.0-0 \
    libpangocairo-1.0-0 \
    --no-install-recommends \
    && rm -rf /var/lib/apt/lists/*

# Grant execute permissions on /tmp so the IronPDF engine can extract there
RUN chmod 777 /tmp/

# Copy the compiled JAR and set the entry point
COPY target/your-function.jar /app/function.jar
CMD ["java", "-jar", "/app/function.jar"]

La ligne chmod 777 /tmp/ est nécessaire car IronPDF doit écrire et exécuter le binaire du moteur pendant l'initialisation. Sans autorisation d'exécution sur le répertoire de travail, le moteur ne pourra pas démarrer.

Comment configurer pom.xml pour le déploiement Google Cloud ?

L'artefact Maven standard ironpdf regroupe des binaires de moteur pour plusieurs plateformes. Pour Google Cloud Functions (qui s'exécutent sur Linux x86-64), ajoutez l'artéfact de moteur spécifique à la plateforme pour garder l'image de déploiement légère et pour s'assurer que le binaire correct est toujours disponible :

//:path=pom.xml
<dependencies>

    <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>
</dependencies>

//:path=pom.xml
<dependencies>

    <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>
</dependencies>

Mettez toujours à jour le numéro de version à la dernière version d'IronPDF for Java. L'artefact ironpdf-engine-linux-x64 doit correspondre précisément à la version de l'artefact principal ironpdf.

Comment ajouter le plugin Maven Shade ?

Lors du déploiement chez Google Cloud Functions en tant qu'uber-JAR (fat JAR), le maven-shade-plugin assure que les fichiers de chargeur de service de toutes les dépendances transitives sont fusionnés correctement. Sans cela, certains enregistrements de services gRPC peuvent être discrètement abandonnés, entraînant un échec de l'initialisation du moteur.

Ajoutez la configuration de plugin suivante à la section <build><plugins> de votre pom.xml :

//:path=pom.xml
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <version>3.2.4</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>shade</goal>
            </goals>

            <configuration>
                <transformers>
                    <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
                </transformers>
            </configuration>
        </execution>
    </executions>
</plugin>

//:path=pom.xml
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <version>3.2.4</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>shade</goal>
            </goals>

            <configuration>
                <transformers>
                    <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
                </transformers>
            </configuration>
        </execution>
    </executions>
</plugin>

Le ServicesResourceTransformer est l'élément critique. Il combine les entrées META-INF/services/ de chaque JAR de dépendance en un seul fichier fusionné. gRPC utilise le mécanisme ServiceLoader de Java, donc des fichiers de service fusionnés sont nécessaires pour que le transport sélectionné (HTTP/2 vs texte brut) fonctionne à l'exécution.

Comment ajouter des dépendances gRPC facultatives ?

Dans certaines configurations de déploiement — notamment lors de l'utilisation d'un JAR éclaté avec certaines versions du cadre Google Cloud Functions — des dépendances de transport gRPC explicites sont nécessaires. Ajoutez-les si la fonction ne parvient pas à démarrer avec une erreur de transport ou de canal gRPC :

//:path=pom.xml
<dependencies>

    <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>
</dependencies>

//:path=pom.xml
<dependencies>

    <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>
</dependencies>

Dans la plupart des cas, l'inclusion de grpc-netty-shaded est suffisante pour la production. Le transport grpc-okhttp est une alternative plus légère utile lorsque la réduction de la taille de l'image doit être une priorité. Ajoutez perfmark-api seulement si vous rencontrez des avertissements de chemin de classe concernant des annotations de traçage manquantes.

Comment définir les limites de ressources pour Google Cloud Functions ?

IronPDF démarre un sous-processus Chromium à l'intérieur du conteneur Cloud Function lors de sa première invocation. Le démarrage de Chromium et le rendu initial sont gourmands en mémoire, et la fonction doit rester active suffisamment longtemps pour que le moteur s'initialise. Les limites de ressources par défaut des Cloud Functions sont trop basses pour un fonctionnement fiable.

Configurez les limites suivantes dans la console Google Cloud ou via le CLI gcloud lors du déploiement de la fonction :

Ces valeurs sont des points de départ. Une génération de PDF de volume élevé ou complexe peut nécessiter des allocations de mémoire plus élevées. Surveillez les métriques d'utilisation de mémoire des Cloud Functions dans la console Google Cloud et augmentez les limites si vous observez des erreurs de mémoire insuffisante.

Comment configurer le répertoire de travail et les autorisations des fichiers ?

Le moteur IronPDF extrait son binaire vers un répertoire de travail au démarrage. Sur Google Cloud Functions, le seul chemin accessible en écriture et exécution est /tmp/. Définissez explicitement le répertoire de travail avant d'appeler n'importe quelle API d'IronPDF, et assurez-vous que le Dockerfile accorde les autorisations nécessaires sur ce chemin.

Ajoutez cet appel de configuration en haut de votre point d'entrée de fonction, avant toute opération PDF :

//:path=/static-assets/pdf/content-code-examples/tutorials/google-cloud/configure-working-directory.java
import com.ironsoftware.ironpdf.Settings;
import java.nio.file.Paths;

public class PdfFunction {
    static {
        // Must be called before any IronPDF operation.
        // /tmp/is the only writable and executable directory in Cloud Functions.
        Settings.setIronPdfEngineWorkingDirectory(Paths.get("/tmp/"));
    }
}

//:path=/static-assets/pdf/content-code-examples/tutorials/google-cloud/configure-working-directory.java
import com.ironsoftware.ironpdf.Settings;
import java.nio.file.Paths;

public class PdfFunction {
    static {
        // Must be called before any IronPDF operation.
        // /tmp/is the only writable and executable directory in Cloud Functions.
        Settings.setIronPdfEngineWorkingDirectory(Paths.get("/tmp/"));
    }
}

Ajoutez ensuite la commande d'autorisation correspondante à votre Dockerfile :

//:path=Dockerfile
# Ensure the IronPDF engine can extract and run binaries from /tmp/
RUN chmod 777 /tmp/

Utiliser un bloc d'initialisation static {} garantit que le répertoire de travail est configuré avant que toute classe de votre fonction ne tente de charger le moteur IronPDF. Si vous le définissez dans une méthode d'instance ou un gestionnaire de requête, il existe un risque qu'un autre thread initialise le moteur avant que le chemin ne soit configuré.

Quelles sont les prochaines étapes?

Ce guide couvre la configuration complète pour exécuter IronPDF for Java à l'intérieur d'une Google Cloud Function à l'aide d'un conteneur Docker personnalisé. Les points clés sont : utilisez un Dockerfile personnalisé qui installe les dépendances système de Chrome, incluez l'artefact Maven ironpdf-engine-linux-x64, configurez le répertoire de travail vers /tmp/, réglez le délai à au moins 330 secondes et la mémoire à au moins 2 048 Mo, et ajoutez le maven-shade-plugin pour fusionner les fichiers de chargeur de service.

Pour explorer davantage ce que peut faire IronPDF for Java, consultez la documentation IronPDF for Java ou essayez une de ces guides :

• IronPDF for Java sur Linux — Comprendre la liste complète des dépendances Chrome pour les déploiements Linux
• IronPDF for Java sur AWS Lambda — Guide similaire de déploiement basé sur Docker pour AWS
• Conversion de HTML en PDF en Java — Flux de rendu de base pour votre logique de fonction

Obtenez une licence d'essai gratuite pour tester IronPDF for Java dans votre environnement Google Cloud. Une clé de licence est requise pour les déploiements en production. Achetez une licence lorsque vous êtes prêt à passer en ligne.