자바 앱 배포

App Engine에서 앱을 업로드하고 실행하려면 앱을 배포합니다. 앱을 배포할 때 해당 앱의 버전과 관련 서비스를 App Engine에서 만듭니다. 모든 소스 코드와 구성 파일을 포함한 전체 앱을 배포하거나 개별 버전이나 구성 파일을 배포하고 업데이트할 수 있습니다.

앱을 프로그래매틱 방식으로 배포하려면 Admin API를 사용합니다.

지원 중단된 appcfg 도구를 사용하여 앱을 배포하는 경우 도구 사용에 대한 자세한 내용은 appcfg 참조를 확인하세요.

시작하기 전에

앱을 배포하려면 다음 조건이 충족되어야 합니다.

Maven 빌드 도구를 사용하여 앱을 배포하려면 App Engine용 Maven 플러그인을 사용하도록 프로젝트를 설정해야 합니다.

gcloud 명령줄 도구 설치

gcloud 도구로 앱을 배포하려면 Cloud SDK를 다운로드, 설치, 초기화해야 합니다.

SDK 다운로드

이미 gcloud 도구가 설치되어 있고 초기화한 ID가 아닌 Cloud 프로젝트 ID를 사용하도록 구성하려면 Cloud SDK 구성 관리를 참조하세요.

프록시 사용

HTTP 또는 HTTPS 프록시를 사용하는 시스템에서 배포 명령어를 실행하려면 프록시를 통해 통신할 수 있도록 도구를 구성해야 합니다.

다음 명령어를 실행하여 gcloud 도구를 구성합니다.

gcloud config set proxy/type [PROXY_TYPE]
gcloud config set proxy/address [PROXY_ADDRESS]
gcloud config set proxy/port [PROXY_PORT]

프록시에 usernamepassword를 설정할 수도 있습니다. 자세한 내용은 gcloud config를 참조하세요.

앱 배포

App Engine에 앱을 배포하려면 애플리케이션의 루트 디렉터리에서 Maven 빌드 도구(권장) 또는 gcloud app deploy 명령어를 사용합니다.

Maven 빌드 도구를 사용하여 앱을 배포하려면 pom.xml 파일이 위치한 프로젝트의 최상위 디렉터리에서 다음 명령어를 실행합니다.

mvn package appengine:deploy -Dapp.deploy.projectId=PROJECT_ID

PROJECT_ID를 Cloud 프로젝트의 ID로 바꿉니다. pom.xml 파일에 이미 프로젝트 ID가 지정된 경우 실행할 명령어에 -Dapp.deploy.projectId 속성을 포함하지 않아도 됩니다.

지원 중단된 App Engine SDK 기반 Maven 플러그인을 사용하는 경우 mvn appengine:update 명령어를 사용하여 앱을 배포합니다.

gcloud 명령줄 사용

  gcloud app deploy [CONFIGURATION_FILES]

[CONFIGURATION_FILES]를 하나 이상의 구성 파일에 대한 경로로 바꾸어 주고, 단일 공백을 사용하여 경로 이름을 구분합니다.

선택적 플래그:

  • --version: 커스텀 버전 ID를 지정합니다. 버전 ID를 지정하지 않으면 App Engine에서 버전 ID를 생성합니다.
  • --no-promote: 전체 트래픽을 해당 버전으로 자동 라우팅하지 않고 앱을 배포합니다. 기본적으로 배포하는 각 버전은 트래픽 전체를 수신하도록 자동으로 구성됩니다.
  • --project: 대체 Cloud 프로젝트 ID를 gcloud 도구에서 기본값으로 초기화한 값으로 지정합니다.

자세한 내용은 gcloud app deploy 참조를 확인하거나 명령줄에서 gcloud help를 실행하세요.

고유한 버전 ID 선택

수동으로 확장된 인스턴스의 경우, 버전 ID는 숫자 인스턴스 ID와 구분되도록 문자로 시작해야 합니다. 이렇게 하면 요청이 올바른 대상으로 라우팅되며 다음과 같이 두 가지로 해석될 수 있는 123-dot-my-service.[REGION_ID].r.appspot.com과 같은 URL 패턴의 모호성을 방지할 수 있습니다.

  • 123 버전이 있는 경우 요청은 my-service 서비스의 123 버전으로 라우팅됩니다.
  • 123 버전이 없으면 요청은 my-service 서비스의 버전이 실행되는 인스턴스 ID 123으로 라우팅됩니다.

자동 확장 또는 기본 확장으로 구성된 인스턴스는 지원되지 않으므로, 이 인스턴스 버전에 원하는 대로 이름을 지정할 수 있습니다.

여러 서비스 애플리케이션 배포

애플리케이션이 여러 서비스에 반영되어 있으면 개별적으로 타겟팅된 서비스나 모든 서비스를 동시에 배포하고 업데이트할 수 있습니다. 서비스에 업데이트를 배포하는 작업에는 개별 구성 파일 업데이트 또는 해당 버전의 소스 코드 업데이트가 포함될 수 있습니다.

예를 들어 각 버전이 자체 서비스에서 실행되는 버전 두 개를 App Engine에서 배포하고 만들 수 있습니다. 한 버전은 앱의 프런트엔드 서비스로 작동하고 다른 버전은 백엔드로 작동합니다. 그런 다음 개별 구성 파일을 배포하여 서비스의 설정만 업데이트할 수 있습니다. 뿐만 아니라, 프런트엔드나 백엔드의 소스 코드를 업데이트하거나 두 소스 코드를 동시에 업데이트하기 위해 서비스에 새 버전을 배포할 수도 있습니다.

여러 서비스 요구사항

다음 요구사항에 따라 동일한 배포 명령어를 사용하여 애플리케이션의 여러 서비스를 배포하고 업데이트할 수 있습니다.

  • 먼저 애플리케이션 버전을 default 서비스로 배포해야 이후에 서비스를 만들고 배포할 수 있습니다.

  • 해당 버전의 appengine-web.xml 구성 파일에서 서비스 ID를 지정해야 합니다. 서비스 ID를 지정하려면 구성 파일마다 module: [YOUR_SERVICE_ID] 요소 정의를 포함합니다. 기본적으로 구성 파일에서 이 요소 정의를 제외하면 해당 버전이 default 서비스에 배포됩니다.

  • 여러 서비스를 동시에 배포하려면 배포 명령어에 해당되는 모든 appengine-web.xml 구성 파일을 지정해야 합니다. default 서비스가 가장 먼저 목록에 표시되어야 합니다.

여러 서비스 배포

구성 파일이 있는 애플리케이션의 루트 디렉터리에서 배포 명령어를 실행하여 각 서비스의 appengine-web.xml 파일에 상대 경로와 파일 이름을 지정합니다.

Maven 빌드 도구 사용

프로젝트의 루트 디렉터리에 내 서비스만 있는 경우 Maven 명령어 하나로 이러한 모든 서비스를 배포할 수 있습니다.

Maven 배포 명령어는 프로젝트의 각 서비스를 반복하여 구성 파일을 찾은 다음 각 서비스를 배포합니다.

Maven 플러그인을 사용하여 여러 서비스를 배포하려면 다음을 따릅니다.

  1. appengine-maven-plugin이 상위 pom.xml 파일에 추가되었는지 확인합니다.
  2. 다음 명령어를 실행합니다.

    mvn package appengine:deploy -Dapp.deploy.projectId=PROJECT_ID

    PROJECT_ID를 Cloud 프로젝트의 ID로 바꿉니다. pom.xml 파일에 이미 프로젝트 ID가 지정된 경우 실행할 명령어에 -Dapp.deploy.projectId 속성을 포함하지 않아도 됩니다.

gcloud 사용

    gcloud app deploy [CONFIGURATION_FILES]

[CONFIGURATION_FILES]를 하나 이상의 구성 파일에 대한 경로로 바꾸어 주고, 단일 공백을 사용하여 경로 이름을 구분합니다.

각 서비스가 성공적으로 배포되면 명령줄을 통해 인증을 받습니다.

색인 업데이트

앱이 사용하는 색인을 만들거나 업데이트하려면 datastore-indexes.xml 구성 파일을 Datastore에 업로드합니다. 아직 존재하지 않는 색인은 구성 파일이 업로드된 후에 만들어집니다.

Datastore가 모든 색인을 생성하는 데 시간이 걸릴 수 있으므로 App Engine에서 색인을 바로 사용할 수 없습니다. 앱이 이미 트래픽을 수신하도록 구성된 경우 아직 생성 중인 색인을 필요로 하는 쿼리에서 예외가 발생할 수 있습니다.

예외 발생을 방지하려면 모든 색인이 생성될 때까지 기다려야 합니다. 예를 들면 다음과 같습니다.

  • 버전을 배포하기 전에 Datastore에 index.xml 구성 파일을 업로드합니다.

    1. index.xml 파일을 Datastore에 업로드합니다.

      gcloud datastore indexes create index.yaml
      자세한 내용은 gcloud datastore 참조를 확인하세요.

    2. Cloud Console을 사용하여 모든 색인의 상태를 모니터링합니다.

      Datastore 페이지로 이동

    3. 색인 생성 작업이 모두 완료되면 App Engine에 새 버전을 배포합니다.

  • 버전에 트래픽을 마이그레이션하거나 분할하기 전에 색인을 생성합니다.

    1. 앱의 appengine-web.xml 파일에 새 버전 ID를 정의합니다.
    2. 새 버전을 배포합니다.
    3. Cloud Console을 사용하여 모든 색인의 상태를 모니터링합니다.

      Datastore 페이지로 이동

    4. 모든 색인이 빌드되면 Cloud Console을 사용하여 트래픽을 버전으로 마이그레이션하거나 분할합니다.

      버전 페이지로 이동

색인에 대한 자세한 내용은 Datastore 색인 구성을 참조하세요.

문제해결

다음은 일반적으로 발생할 수 있는 오류 메시지입니다.

PERMISSION_DENIED: Operation not allowed
The "appengine.applications.create" permission is required.
Cloud 프로젝트에 필수 App Engine 애플리케이션이 포함되어 있지 않은 경우 gcloud app create 명령어 실행을 시도하면 gcloud app deploy 명령어가 실패할 수 있습니다. 소유자 역할이 있는 계정에만 App Engine 애플리케이션을 생성하는 데 필요한 권한이 있습니다.
Command not found
지원 중단된 App Engine SDK를 설치할 때 dev_appserver.sh 도구의 심볼릭 링크를 만들지 않았으면 도구를 실행할 전체 디렉터리 경로(예: [PATH_TO_APP_ENGINE_SDK]/dev_appserver.sh)를 지정해야 할 수도 있습니다.
Import Error
Cloud SDK와 원본 App Engine SDK를 모두 설치하면 PATH에 대한 항목이 서로 충돌하여 가져오기 오류가 발생할 수 있습니다. Cloud SDK 명령어를 실행할 때 오류가 발생하면 원본 App Engine SDK를 명시적으로 사용해 보세요. 원본 App Engine SDK의 항목을 PATH의 앞쪽으로 옮겨 해당 명령어가 우선순위를 갖도록 할 수 있습니다. 또는 전체 디렉터리 경로([PATH_TO_APP_ENGINE_SDK]/java_dev_appserver.sh)를 지정하여 명령어를 실행할 수도 있습니다.
[400] The first service (module) you upload to a new application must be the 'default' service (module)
애플리케이션의 여러 서비스를 배포하고 만들려면 먼저 default 서비스를 배포하고 만들어야 합니다. default 서비스에 버전을 배포하는 방법에 대한 자세한 내용은 여러 서비스 애플리케이션 배포를 참조하세요.
Too Many Versions (403)
App Engine에는 애플리케이션의 배포 버전 수에 대한 제한이 있습니다. 이러한 제한은 무료 애플리케이션과 배포된 애플리케이션에서 서로 다르게 적용됩니다. Cloud Console을 사용하여 이전 버전을 삭제한 후 최신 코드를 업로드할 수 있습니다. You do not have permission to modify this app (403)
이는 승인된 계정에 명령어 또는 appengine-web.xml에 지정된 애플리케이션 ID에 배포할 수 있는 권한이 없는 경우 발생할 수 있습니다. 애플리케이션 ID가 정확하고 Cloud Console 프로젝트 ID 값과 일치하는지 확인합니다. 그런 다음 Console에서 프로젝트 권한을 확인하고 계정이 앱을 배포하기에 충분한 권한 수준이 있는지 확인합니다.
기타 배포 오류
배포에 실패하면 Cloud Build API가 프로젝트에 사용 설정되어 있는지 확인합니다. 앱을 처음 배포할 때 App Engine은 이 API를 자동으로 사용 설정하지만 이후 누군가가 API를 중지하면 배포가 실패합니다.

다음 단계