자바 런타임 환경

자바 런타임은 웹 서비스의 코드와 종속 항목을 설치하고 서비스를 실행하는 소프트웨어 스택입니다.

app.yaml 파일에서 App Engine 표준 환경용 자바 런타임을 선언합니다. 예를 들면 다음과 같습니다.

runtime: javaVERSION

여기서 VERSION은 Java MAJOR 버전 번호입니다. 예를 들어 최신 Java 버전인 Java 21을 사용하려면 21을 지정합니다.

다른 지원되는 자바 버전과 자바 버전에 해당하는 Ubuntu 버전은 런타임 지원 일정을 참조하세요.

시작하기 전에

Google Cloud CLI의 최신 버전을 다운로드하거나 gcloud CLI를 최신 버전으로 업데이트합니다.
```
gcloud components update
```
Maven을 사용하여 배포하려면 pom.xml에 App Engine Maven 플러그인을 추가해야 합니다.
```
<plugin>
   <groupId>com.google.cloud.tools</groupId>
   <artifactId>appengine-maven-plugin</artifactId>
   <version>2.7.0</version>
</plugin>
```
gcloud app deploy 명령어 또는 App Engine Gradle 플러그인 사용을 포함한 다른 배포 옵션도 있습니다.
애플리케이션 프레임워크 안내를 따라 실행 가능한 JAR 파일을 구성합니다.

프레임워크 호환성

App Engine 자바 런타임에서는 실행 가능 JAR 파일을 배포할 수 있습니다. 이 런타임에는 웹 제공 프레임워크가 포함되지 않습니다. 즉, 서블릿 기반 프레임워크나 라이브러리만 사용하도록 제한되지 않습니다. 기본 종속 항목 또는 Netty 라이브러리와 같은 네트워킹 스택을 사용합니다.

Google Cloud GitHub 저장소에 인기 있는 Java 웹 프레임워크를 사용하는 hello world 샘플이 있습니다.

이러한 프레임워크에 대한 제한 없이 Grails, Blade, Play!, Vaadin 또는 jHipster 등 원하는 프레임워크를 사용하는 것이 좋습니다.

Maven 소스 프로젝트를 자바 런타임에 배포

Maven 프로젝트를 소스 코드로 배포하고 Google Cloud 빌드팩을 사용하여 빌드하고 배포할 수 있습니다.

Maven 프로젝트를 소스 코드로 배포하려면 프로젝트의 최상위 디렉터리로 이동하여 다음을 입력합니다.

gcloud app deploy pom.xml

빌드 및 배포 로그가 스트리밍되며 Cloud Console의 Cloud Build 기록 섹션에서 자세한 로그를 확인할 수 있습니다.

GraalVM 실행 파일 사용

App Engine 표준 환경 Java 런타임에서는 GraalVM 네이티브 이미지 실행 파일을 지원합니다. GraalVM 네이티브 이미지를 사용하여 자바 앱을 컴파일하면 app.yaml 파일의 entrypoint 설정을 사용하여 실행 파일을 가리킬 수 있습니다.

예를 들어 파일 이름이 myexecutable인 실행 파일에는 다음 app.yaml 구성 파일이 있을 수 있습니다.

runtime: java17 # or another supported runtime
entrypoint: ./myexecutable

Google Cloud 클라이언트 라이브러리를 사용하여 애플리케이션을 GraalVM 네이티브 이미지로 컴파일할 수 있습니다. 자세한 내용은 네이티브 이미지 컴파일 방법에 대한 문서를 참조하세요.

자바 버전

Java 런타임은 app.yaml 파일에 지정된 안정적인 최신 출시 버전을 사용합니다. App Engine은 새로운 패치 출시 버전으로 자동 업데이트되지만 부 버전은 자동으로 업데이트되지 않습니다.

예를 들어 애플리케이션은 Java 11.0.4에 배포된 이후 관리형 플랫폼을 배포할 때 Java 11.0.5 버전으로 자동으로 업데이트될 수 있지만 Java 12로 자동 업데이트되지는 않습니다.

Java 버전을 업그레이드하는 방법은 기존 애플리케이션 업그레이드를 참조하세요.

런타임의 Open JDK 환경

App Engine은 최신 Ubuntu Linux 배포판과 지원되는 자바 11용 openjdk-11-jdk 또는 자바 17 런타임용 openjdk-17-jdk에서 gVisor로 보호되는 컨테이너에서 자바 앱을 실행합니다.

Java 버전에 지원되는 Ubuntu 버전은 런타임 지원 일정을 참조하세요.

App Engine은 기본 이미지를 유지하고 앱을 다시 배포할 필요 없이 OpenJDK 11 및 OpenJDK 17 패키지를 업데이트합니다.

배포된 앱은 런타임의 /workspace 디렉터리에 있습니다. /srv에서 기호화된 링크를 통해서도 액세스할 수 있습니다.

App Engine Java 출시 버전

2.x.x 버전으로 시작하는 모든 출시 아티팩트는 오픈소스 출시 메커니즘을 사용합니다. 1.9.9xx 이전 버전으로 시작하는 출시 아티팩트는 내부 빌드 시스템을 사용합니다. 자세한 내용은 GitHub 저장소를 참조하세요.

종속 항목

종속 항목 선언 및 관리에 대한 자세한 내용은 종속 항목 지정을 참조하세요.

애플리케이션 시작

Spring Boot, Micronaut, Ktor 등의 프레임워크는 기본적으로 실행 가능 uber JAR을 빌드합니다. Maven 또는 Gradle 빌드 파일이 실행 가능 Uber JAR을 생성할 때 런타임은 Uber JAR 애플리케이션을 실행하여 애플리케이션을 시작합니다.

또는 App Engine이 app.yaml 파일에서 선택적인 entrypoint 필드의 콘텐츠를 사용합니다. 예를 들면 다음과 같습니다.

runtime: java21 # or another supported runtime
entrypoint: java -Xmx64m -jar YOUR-ARTIFACT.jar

여기에서 YOUR-ARTIFACT.jar 애플리케이션 jar의 예시는 다음과 같아야 합니다.

app.yaml 파일이 있는 루트 디렉터리에 있어야 합니다.
해당 META-INF/MANIFEST.MF 메타데이터 파일에 Main-Class 항목을 포함해야 합니다.
선택적으로 다른 종속된 jar의 상대 경로 목록이 있는 Class-Path 항목을 포함해야 합니다. 이는 애플리케이션에 자동으로 업로드됩니다.

앱이 HTTP 요청을 수신하려면 진입점은 PORT 환경 변수에 지정된 포트에서 수신 대기하는 웹 서버를 시작해야 합니다. PORT 환경 변수 값은 App Engine 제공 환경에서 동적으로 설정됩니다. app.yaml 파일의 env_variables 섹션에서는 이 값을 설정할 수 없습니다.

커스텀 진입점을 사용하면 애플리케이션 코드 및 직접 종속 항목만 포함하는 씬 JAR 파일로 애플리케이션을 생성하고 패키징할 수 있습니다. 애플리케이션을 배포할 때 App Engine 플러그인은 전체 uber JAR 패키지 대신 변경된 파일만 업로드합니다.

PORT 환경 변수를 사용해야 함

앱 로그 파일에 포트 8080 및 NGINX에 대한 경고가 나타나면 앱의 웹 서버가 기본 포트 8080에서 리슨하는 중입니다. 이렇게 하면 App Engine이 NGINX 레이어를 사용하여 HTTP 응답을 압축하는 것을 방지할 수 있습니다. PORT 환경 변수(일반적으로 8081)로 지정된 포트에서 HTTP 요청에 응답하도록 웹 서버를 구성하는 것이 좋습니다. 예를 들면 다음과 같습니다.

/*
 * Copyright 2019 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.example.appengine;

import com.sun.net.httpserver.HttpServer;
import java.io.IOException;
import java.io.OutputStream;
import java.net.InetSocketAddress;

public class Main {

  public static void main(String[] args) throws IOException {
    // Create an instance of HttpServer bound to port defined by the 
    // PORT environment variable when present, otherwise on 8080.
    int port = Integer.parseInt(System.getenv().getOrDefault("PORT", "8080"));
    HttpServer server = HttpServer.create(new InetSocketAddress(port), 0);

    // Set root URI path.
    server.createContext("/", (var t) -> {
      byte[] response = "Hello World!".getBytes();
      t.sendResponseHeaders(200, response.length);
      try (OutputStream os = t.getResponseBody()) {
        os.write(response);
      }
    });

    // Create a second URI path.
    server.createContext("/foo", (var t) -> {
      byte[] response = "Foo!".getBytes();
      t.sendResponseHeaders(200, response.length);
      try (OutputStream os = t.getResponseBody()) {
        os.write(response);
      }
    });

    server.start();
  }
}

이전 자바 버전과의 호환성

자바 8과 지원되는 최신 자바 버전 간의 차이점은 자바 8과 자바 11 이상 런타임 간의 주요 차이점을 참조하세요.

환경 변수

다음 환경 변수는 런타임에서 설정됩니다.

환경 변수	설명
`GAE_APPLICATION`	App Engine 애플리케이션 ID입니다. 이 ID는 유럽에 배포된 애플리케이션의 'e~'와 같이 '`region code`~'로 시작됩니다.
`GAE_DEPLOYMENT_ID`	현재 배포 ID입니다.
`GAE_ENV`	App Engine 환경입니다. `standard`로 설정합니다.
`GAE_INSTANCE`	서비스가 현재 실행되고 있는 인스턴스 ID입니다.
`GAE_MEMORY_MB`	애플리케이션 프로세스에 제공되는 메모리 양(MB)입니다.
`GAE_RUNTIME`	`app.yaml` 파일에 지정된 런타임입니다.
`GAE_SERVICE`	`app.yaml` 파일에 지정된 서비스 이름입니다. 서비스 이름을 지정하지 않으면 `default`로 설정됩니다.
`GAE_VERSION`	서비스의 현재 버전 라벨입니다.
`GOOGLE_CLOUD_PROJECT`	애플리케이션과 연결된 Google Cloud 프로젝트 ID입니다.
`PORT`	HTTP 요청을 수신하는 포트입니다.
`NODE_ENV`(Node.js 런타임에서만 사용 가능)	서비스가 배포되면 `production`으로 설정하세요.

app.yaml 파일에 추가 환경 변수를 정의할 수 있지만 NODE_ENV 외에는 위 값을 재정의할 수 없습니다.

HTTPS 및 전달 프록시

App Engine은 부하 분산기에서 HTTPS 연결을 종료하고 애플리케이션에 요청을 전달합니다. 일부 애플리케이션에서는 원본 요청 IP와 프로토콜을 확인해야 합니다. 사용자의 IP 주소는 표준 X-Forwarded-For 헤더에서 제공됩니다. 이 정보가 필요한 애플리케이션은 프록시를 신뢰하도록 웹 프레임워크를 구성해야 합니다.

파일 시스템 액세스

런타임에는 읽기 전용 액세스 권한이 있는 다른 모든 디렉터리와 함께 쓰기 가능한 /tmp 디렉터리가 포함됩니다. /tmp에 쓰는 데 시스템 메모리가 사용됩니다.

메타데이터 서버

애플리케이션의 각 인스턴스는 App Engine 메타데이터 서버를 사용하여 인스턴스와 프로젝트에 대한 정보를 쿼리할 수 있습니다.

다음 엔드포인트를 통해 메타데이터 서버에 액세스할 수 있습니다.

http://metadata
http://metadata.google.internal

메타데이터 서버로 전송되는 요청에는 요청 헤더 Metadata-Flavor: Google이 포함되어야 합니다. 이 헤더는 요청이 메타데이터 값을 검색하기 위해 전송되었음을 나타냅니다.

다음 표에는 특정 메타데이터에 대해 HTTP 요청을 수행할 수 있는 엔드포인트가 나열되어 있습니다.

메타데이터 엔드포인트	설명
`/computeMetadata/v1/project/numeric-project-id`	프로젝트에 할당된 프로젝트 번호입니다.
`/computeMetadata/v1/project/project-id`	프로젝트에 할당된 프로젝트 ID입니다.
`/computeMetadata/v1/instance/region`	인스턴스가 실행 중인 리전입니다.
`/computeMetadata/v1/instance/service-accounts/default/aliases`
`/computeMetadata/v1/instance/service-accounts/default/email`	프로젝트에 할당된 기본 서비스 계정 이메일입니다.
`/computeMetadata/v1/instance/service-accounts/default/`	프로젝트의 모든 기본 서비스 계정이 나열됩니다.
`/computeMetadata/v1/instance/service-accounts/default/scopes`	기본 서비스 계정에 지원되는 모든 범위가 나열됩니다.
`/computeMetadata/v1/instance/service-accounts/default/token`	다른 Google Cloud API에 애플리케이션을 인증하기 위해 사용할 수 있는 인증 토큰을 반환합니다.

예를 들어 프로젝트 ID를 검색하려면 http://metadata.google.internal/computeMetadata/v1/project/project-id에 요청을 보냅니다.