주의: 앞으로 몇 개월에 걸쳐 Google은 콘텐츠를 보다 손쉽게 찾고 나머지 Google Cloud 제품과 더 잘 연동되도록 App Engine 문서 사이트를 재구성할 예정입니다. 제공되는 콘텐츠는 동일하지만, 이제 탐색 기능이 나머지 클라우드 제품과 일치하게 됩니다.

자바 17이 이제 정식 버전으로 제공됩니다.

자바 11/17 런타임 환경

컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

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

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

자바 17

runtime: java17

자바 11

runtime: java11

시작하기 전에

  1. Google Cloud CLI의 최신 버전을 다운로드하거나 gcloud CLI를 최신 버전으로 업데이트합니다.

    gcloud components update
    
  2. Maven을 사용하여 배포하려면 pom.xmlApp Engine Maven 플러그인을 추가해야 합니다.

    <plugin>
       <groupId>com.google.cloud.tools</groupId>
       <artifactId>appengine-maven-plugin</artifactId>
       <version>2.4.4</version>
    </plugin>

    gcloud app deploy 명령어 또는 App Engine Gradle 플러그인 사용을 포함한 다른 배포 옵션도 있습니다.

  3. 애플리케이션 프레임워크 안내를 따라 실행 가능한 JAR 파일을 구성합니다.

프레임워크 호환성

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

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

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

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

Maven 프로젝트를 소스 코드로 배포하고 App Engine Buildpacks를 사용하여 빌드하고 배포할 수 있습니다.

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

gcloud app deploy pom.xml

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

GraalVM 실행 파일 사용

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

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

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

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

자바 버전

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

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

런타임의 Open JDK 환경

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

  • 자바 11은 Ubuntu 18.04에서 실행됩니다.
  • 자바 17은 Ubuntu 22.04에서 실행됩니다.

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

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

App Engine 자바 출시 버전

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: java17 # 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 런타임과 자바 11/17 런타임 간의 차이점은 자바 8 런타임과 자바 11/17 런타임 간의 주요 차이점을 참조하세요.

환경 변수

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

환경 변수 설명
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 애플리케이션과 연결된 Cloud 프로젝트 ID입니다.
PORT HTTP 요청을 수신하는 포트입니다.

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

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/zone 인스턴스가 실행 중인 영역입니다.
/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 APIs에 애플리케이션을 인증하기 위해 사용할 수 있는 인증 토큰을 반환합니다.

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