Google Cloud에서 Java용 IronPDF 실행하는 방법

기본 Cloud Function 이미지가 작동하지 않는 이유는?

기본 Google Cloud Function 런타임 이미지는 설계상 최소화되어 있습니다 — 일반 언어로 작성된 함수 코드를 실행하는 데 필요한 패키지만 포함합니다. IronPDF의 Chromium 기반 렌더링 엔진은 표준 이미지에 없는 리눅스 시스템 라이브러리(폰트, 그래픽 라이브러리, 샌드박스 도구)에 의존합니다.

Google은 Google Cloud Functions 시스템 패키지 참조에서 각 런타임에 사용 가능한 시스템 패키지 목록 전체를 게시합니다. Chromium의 종속성은 표준 2세대 런타임 중 어느 것도 포함되어 있지 않습니다. 기본 이미지에서 IronPDF 엔진을 로드하려고 하면 시작 시 네이티브 라이브러리 로드 실패가 발생합니다.

해결책은 철저하게 해당 패키지를 설치한 후 함수 바이너리를 추가하는 맞춤 Docker 이미지를 빌드하는 것입니다. 이 접근법은 Google Cloud Functions에 의해 완전히 지원되며, 네이티브 바이너리가 필요한 모든 함수에 대해 권장되는 전략과 동일합니다. IronPDF Linux 배포 가이드를 참조하여 포함할 패키지 전체 목록을 확인하세요.

Google Cloud에 맞춤 Dockerfile을 빌드하는 방법은?

맞춤 Dockerfile은 런타임 환경에 대한 완벽한 제어를 제공합니다. 공식 Google Cloud Functions Java 기본 이미지에서 시작하여 Chromium이 필요한 시스템 라이브러리를 설치하세요.

아래의 Dockerfile은 권장 패턴을 보여줍니다. COPY 및 CMD 항목을 귀하의 기능 프로젝트에 맞는 구체적인 내용으로 대체하십시오:

//: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"]

chmod 777 /tmp/ 줄은 IronPDF가 초기화 과정에서 엔진 바이너리를 작성하고 실행해야 하기 때문에 필요합니다. 작업 디렉토리에 대한 실행 권한이 없으면 엔진이 시작하지 못할 것입니다.

Google Cloud 배포를 위한 pom.xml 구성 방법은?

표준 ironpdf Maven 아티팩트는 여러 플랫폼용 엔진 바이너리를 포함합니다. Google Cloud Functions (리눅스 x86-64에서 실행)는 플랫폼별 엔진 아티팩트를 추가하여 배포 이미지를 슬림하게 유지하고 필요한 바이너리가 항상 사용 가능하도록 해야 합니다:

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

항상 최신 IronPDF for Java 릴리스로 버전 번호를 업데이트하세요. ironpdf-engine-linux-x64 아티팩트는 핵심 ironpdf 아티팩트의 버전과 정확히 일치해야 합니다.

Maven Shade Plugin을 추가하는 방법은?

Google Cloud Functions에 uber-JAR(fat JAR)로 배포할 때, maven-shade-plugin는 모든 전이적 종속성의 서비스 로더 파일이 올바르게 병합되도록 보장합니다. 그렇지 않으면 일부 gRPC 서비스 등록이 조용히 제거되어 엔진 초기화에 실패할 수 있습니다.

<build><plugins> 섹션에 다음 플러그인 구성을 추가하십시오:

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

ServicesResourceTransformer 부분이 핵심입니다. 이는 모든 종속성 JAR 파일의 META-INF/services/ 항목을 단일 병합 파일로 결합합니다. gRPC는 Java의 ServiceLoader 메커니즘을 사용하므로, 런타임 시 전송 방식 선택(HTTP/2 대 일반 텍스트)이 작동하려면 병합된 서비스 파일이 필요합니다.

선택적인 gRPC 종속성을 추가하는 방법은?

일부 배포 구성 — 특히 Google Cloud Functions 프레임워크의 특정 버전과 함께 음영 처리된 JAR을 사용할 때 — 명시적인 gRPC 전송 종속성이 필요합니다. 함수가 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>

대부분의 경우, grpc-netty-shaded을 포함하는 것으로 실제 배포에 충분합니다. grpc-okhttp 전송 방식은 이미지 크기를 최소화하는 것이 최우선 과제일 때 유용한 경량 대안입니다. 트레이싱 어노테이션 누락에 대한 클래스패스 경고가 발생하는 경우에만 perfmark-api을 추가하십시오.

Google Cloud Functions의 리소스 제한 설정 방법은?

IronPDF는 첫 번째 호출 시 Cloud Function 컨테이너 내에서 Chromium 하위 프로세스를 시작합니다. Chromium의 시작과 초기 렌더링은 메모리 집약적이며, 엔진이 초기화될 때까지 기능이 살아있어야 합니다. Cloud Functions의 기본 리소스 제한은 안정적인 작동에 비해 너무 낮습니다.

함수를 배포할 때 Google Cloud Console 또는 gcloud CLI를 통해 다음 제한 사항을 구성하십시오:

이 값은 시작점입니다. 고성능 또는 복잡한 PDF 생성에는 더 높은 메모리 할당이 필요할 수 있습니다. Cloud Function 메모리 사용량 메트릭을 Google Cloud 콘솔에서 모니터링하고, 메모리 부족 오류가 발생하면 제한을 늘리세요.

작업 디렉토리 및 파일 권한을 구성하는 방법은?

IronPDF 엔진은 시작 시 바이너리를 작업 디렉터리에 추출합니다. Google Cloud Functions에서는 /tmp/ 경로만이 쓰기 및 실행이 가능합니다. any IronPDF API를 호출하기 전에 작업 디렉토리를 명시적으로 설정하고, 해당 경로에 필요한 권한이 Dockerfile에 부여되도록 하세요.

초기 설정 함수 진입점의 맨 위에 이 설정 호출을 추가하세요.

//:path=/static-assets/pdf/content-code-examples/tutorials/google-cloud/configure-working-directory.java
import com.ironsoftware.ironpdf.설정s;
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.
        설정s.setIronPdfEngineWorkingDirectory(Paths.get("/tmp/"));
    }
}

//:path=/static-assets/pdf/content-code-examples/tutorials/google-cloud/configure-working-directory.java
import com.ironsoftware.ironpdf.설정s;
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.
        설정s.setIronPdfEngineWorkingDirectory(Paths.get("/tmp/"));
    }
}

그런 다음 Dockerfile에 해당 권한 명령을 추가하세요:

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

static {} 초기화 블록을 사용하면 함수 내의 어떤 클래스도 IronPDF 엔진을 로드하기 전에 작업 디렉터리가 구성되도록 보장합니다. 인스턴스 메서드나 요청 핸들러에서 이를 설정할 경우, 경로가 구성되기 전에 다른 스레드가 엔진을 초기화할 위험이 있습니다.

다음 단계는 무엇인가요?

이 가이드는 맞춤 Docker 컨테이너를 사용하여 Google Cloud Function 내에서 IronPDF for Java를 실행하기 위한 전체 구성을 다룹니다. 주요 사항은 다음과 같습니다: Chrome 시스템 종속성을 설치하는 사용자 정의 Dockerfile을 사용하고, ironpdf-engine-linux-x64 Maven 아티팩트를 포함하고, 작업 디렉터리를 /tmp/로 설정하며, 타임아웃을 최소 330초, 메모리를 최소 2,048MB로 설정하고, 서비스 로더 파일을 병합하기 위해 maven-shade-plugin를 추가하는 것입니다.

IronPDF for Java 문서를 방문하여 IronPDF for Java의 더 많은 기능을 탐색하거나 다음 가이드 중 하나를 시도하세요:

• IronPDF for Java on Linux — Linux 배포를 위한 Chrome 종속성 전체 목록 이해하기
• IronPDF for Java on AWS Lambda — AWS 용 Docker 기반 배포 가이드
• HTML to PDF conversion in Java — 기능 로직용 핵심 렌더링 워크플로우

무료 체험 라이선스 받기 하여 Google Cloud 환경에서 IronPDF for Java를 테스트하세요. 생산 배포를 위해서는 라이선스 키가 필요합니다. 라이브로 나갈 준비가 되었을 때, 라이선스 구매하세요.