애플리케이션 테스트 및 배포

애플리케이션을 로컬에서 실행 및 배포하고 App Engine에서 테스트하는 방법을 알아봅니다.

로컬에서 실행

배포 전에 애플리케이션을 테스트하려면 일반적으로 사용하는 개발 도구를 사용하여 로컬 환경에서 애플리케이션을 실행합니다.

애플리케이션 배포

Cloud Build 서비스는 배포를 컨테이너 이미지로 자동 빌드하고 이 이미지를 App Engine 가변형 환경에 배포합니다. 컨테이너에는 런타임 이미지에 적용된 모든 로컬 수정사항이 포함됩니다.

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

시작하기 전에

애플리케이션을 배포하기 전에 다음을 확인합니다.

• Google Cloud 프로젝트의 소유자가 App Engine용 Google Cloud 프로젝트를 설정해야 합니다.

• 사용자 계정에 필요한 권한이 있는지 확인합니다.

서비스 배포

애플리케이션의 서비스 버전과 각 구성 파일을 배포하여 App Engine에 애플리케이션을 배포합니다.

• 각 파일을 개별적으로 타겟팅하고 배포하여 서비스의 다른 구성 파일을 배포할 수 있습니다. 예를 들면 다음과 같습니다.

  gcloud app deploy cron.yaml
  gcloud app deploy dispatch.yaml
  gcloud app deploy index.yaml
  

• 커스텀 버전 ID를 지정하려면 --version 플래그를 사용합니다.

• 트래픽이 자동으로 새 버전으로 라우팅되지 않게 하려면 --no-promote 플래그를 사용합니다.

• 특정 Google Cloud 프로젝트에 배포하려면 --project 플래그를 사용합니다.

예를 들어 app.yaml 파일에서 정의된 서비스를 특정 Google Cloud 프로젝트에 배포하려면 서비스에 커스텀 버전 ID를 할당하고 트래픽이 새 버전으로 라우팅되지 않도록 합니다.

gcloud app deploy --project PROJECT_ID --version VERSION_ID --no-promote

자세한 내용은 gcloud app deploy 참조 문서를 확인하세요.

gcloud CLI의 속성을 설정하고 SDK 구성을 만들고 관리하면 배포할 때마다 --project와 같은 플래그를 지정할 필요가 없습니다.

파일 무시

서비스를 배포할 때 .gcloudignore 파일을 사용하여 Google Cloud에 업로드하지 않을 파일과 디렉터리를 지정할 수 있습니다. 이 작업은 배포를 통해 업로드하지 않아도 되는 빌드 아티팩트와 기타 파일을 무시하는 경우에 유용합니다.

.gcloudignore 파일의 구문에 대해 자세한 내용은 gcloud 참조를 확인하세요.

수동으로 배포용 컨테이너 빌드

Google Cloud 외부에서 컨테이너 이미지를 빌드하려면 다음 안내를 따르세요.

1. Artifact Registry 저장소에 이미지를 업로드합니다. 자세한 내용은 이미지 내보내기 및 가져오기를 참고하세요.
2. gcloud app deploy 명령어를 사용하여 App Engine에 배포합니다.

예를 들어 Docker를 사용하여 컨테이너 이미지를 로컬로 빌드하려면 이미지를 Artifact Registry로 내보내고 이미지의 URL을 명령어의 --image-url 플래그에 지정하면 됩니다.

gcloud app deploy --image-url LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE

다음과 같이 바꿉니다.

• LOCATION을 이미지가 저장된 저장소의 위치로 바꿉니다.

• PROJECT-ID를 Google Cloud 프로젝트 ID로 바꿉니다.

• REPOSITORY를 이미지가 저장된 저장소의 이름으로 바꿉니다.

• IMAGE을 컨테이너 이미지 이름으로 바꿉니다.

자동화된 지속적 배포 파이프라인 사용

Cloud Build를 사용하여 지속적인 배포 파이프라인에서 배포를 자동화할 수 있습니다. 자세한 내용은 Cloud Build 문서에서 App Engine에 배포 및 빌드 트리거 만들기 및 관리를 참고하세요.

Docker 기본 이미지

커스텀 런타임 애플리케이션을 빌드하려면 Docker 파일 만들기를 참조하세요.

애플리케이션 보기

애플리케이션을 App Engine에 배포한 후 다음 명령어를 실행하면 브라우저를 시작하고 https://PROJECT_ID.REGION_ID.r.appspot.com에서 애플리케이션을 볼 수 있습니다.

gcloud app browse

App Engine에서 테스트

새 버전에서 트래픽을 수신하도록 구성하기 전에 App Engine에서 버전을 테스트할 수 있습니다. 예를 들어 default 서비스의 새 버전을 테스트하려면 다음 안내를 따르세요.

1. promote 매개변수를 false로 설정하여 새 버전 그리고 --no-promote 플래그를 포함합니다.

   gcloud app deploy --no-promote

2. 다음 URL로 이동하여 새 버전에 액세스합니다.

   https://VERSION_ID-dot-default-dot-PROJECT_ID.REGION_ID.r.appspot.com

   이제 App Engine 런타임 환경에서 새 버전을 테스트할 수 있습니다. Google Cloud 콘솔 로그 탐색기에서 로그를 확인하여 애플리케이션을 디버깅할 수 있습니다. 자세한 내용은 애플리케이션 로그 작성을 참조하세요.

   https://PROJECT_ID.REGION_ID.r.appspot.com으로 전송된 요청은 여전히 이전에 트래픽을 수신하도록 구성된 버전으로 라우팅됩니다.

3. 트래픽을 새 버전으로 전송하려면 Google Cloud 콘솔을 사용하여 트래픽을 마이그레이션합니다.

   버전 관리하기

   방금 배포한 버전을 선택하고 트래픽 마이그레이션을 클릭합니다.

URL의 default를 서비스 이름으로 바꾸면 동일한 프로세스를 사용하여 다른 서비스의 새 버전을 테스트할 수 있습니다.

https://VERSION-dot-SERVICE-dot-PROJECT_ID.REGION_ID.r.appspot.com

특정 서비스와 버전 타겟팅에 대한 자세한 내용은 요청이 라우팅되는 방식을 참조하세요.

빌드 환경 변수 사용

빌드팩을 지원하는 런타임용 빌드 환경 변수를 설정할 수 있습니다.

빌드 환경 변수는 앱 배포를 위해 사용하는 빌드팩을 구성하기 위해 지정할 수 있는 키-값 쌍입니다. 예를 들어 컴플라이어 옵션을 지정해야 할 수 있습니다.

시작하기 전에 다음 사항을 확인하세요.

• 키는 대문자 ASCII 문자로 시작해야 하며 대문자 ASCII 문자, 숫자, 밑줄만 포함할 수 있습니다.
• GOOGLE_* 키 프리픽스를 사용하여 변수를 만들지 않아야 합니다.
• Google에서 사용하도록 예약된 키는 다음과 같습니다.
  • GOOGLE_RUNTIME
  • GOOGLE_RUNTIME_VERSION
  • GOOGLE_ENTRYPOINT
  • GOOGLE_DEVMODE
• 빌드팩에서 지원되는 모든 키를 사용할 수 있습니다.

빌드팩에 환경 변수를 사용하려면 app.yaml 파일에서 build_env_variables 필드를 지정합니다.

빌드팩에 대해 여기서 자세히 알아보세요.

Cloud Trace 사용

Cloud Trace는 요청이 애플리케이션을 통해 전파되는 방식을 이해하는 데 유용합니다. 단일 요청의 상세 지연 시간 정보를 조사하거나 애플리케이션 전반의 지연 시간 합계를 확인할 수 있습니다.

Trace 세부정보를 볼 수 있습니다. Trace 탐색기에서 특정 App Engine 서비스 및 버전을 기준으로 필터링할 수 있습니다.

문제 해결

다음은 앱을 배포할 때 발생할 수 있는 일반적인 오류 메시지입니다.

PERMISSION_DENIED: Operation not allowed

The "appengine.applications.create" permission is required.

Google Cloud 프로젝트에 필수 App Engine 애플리케이션이 포함되어 있지 않은 경우 gcloud app create 명령어 실행을 시도하면 gcloud app deploy 명령어가 실패할 수 있습니다. 소유자 역할이 있는 계정에만 App Engine 애플리케이션을 생성하는 데 필요한 권한이 있습니다.

502 Bad Gateway

app.yaml이 잘못 구성된 경우 Google Cloud 프로젝트를 시작할 수 없습니다. 자세한 오류 메시지는 앱 로그를 확인하세요.

[13] An internal error occurred while creating a Cloud Storage bucket.

App Engine이 애플리케이션을 만드는 리전과 동일한 리전에서 기본 Cloud Storage 멀티 리전 버킷을 만듭니다. 애플리케이션의 콘텐츠를 저장하려면 이 버킷이 필요합니다. 이 버킷을 만들 수 없는 경우(예: 다음 시나리오) 이 오류가 반환됩니다.

• App Engine 가변형 환경 서비스 에이전트가 프로젝트에 없거나 App Engine flexible environment Service Agent 역할이 없습니다. 에이전트의 서비스 계정에 올바른 IAM 권한을 부여하여 이를 프로젝트에 다시 추가하면 됩니다. 삭제된 서비스 에이전트 복원을 참고하세요.

• 프로젝트에 기본 App Engine 서비스 계정이 없습니다. 삭제 후 30일이 지나기 전에 App Engine 서비스 계정이 삭제된 경우 복원할 수 있습니다.

• 프로젝트가 constraints/gcp.resourceLocations 정책을 시행하는 조직에 속하며 조직에서 App Engine이 있는 동일한 리전에서의 리소스 생성을 허용하지 않습니다 프로젝트에 적용된 constraints/gcp.resourceLocations 정책을 재정의하고 App Engine 앱이 만들어진 동일한 리전에서 멀티 리전 위치를 허용해야 합니다.

예를 들어 리전이 europe-west1 위치에 매핑되더라도 App Engine 앱이 europe-west 리전에서 생성된 경우에는 모든 EU 리전이 포함된 in:eu-locations의 리소스를 허용하도록 제약조건을 수정해야 합니다. 이는 App Engine에서 만든 버킷이 멀티 리전 버킷이므로 필요합니다. App Engine 앱을 US 리전에서 만든 경우 in:us-locations를 허용하고 앱을 ASIA 리전에서 만든 경우 in:asia-locations를 허용해야 합니다.

[13] An internal error occurred.

이 오류는 공유 VPC 설정을 사용하여 네트워크 구성으로 서비스를 배포하는 경우에 발생할 수 있습니다. 다음을 시도해 보세요.

1. app.yaml 구성이 유효한지 확인합니다.
2. App Engine 가변형 환경이 공유 VPC 설정의 모든 요구사항을 충족하는지 확인합니다. 공유 VPC 네트워크에서 App Engine 가변형 환경 사용을 참조하세요.
3. 프로젝트에 구성된 서비스 계정이 있는지 확인합니다. 그렇지 않은 경우 계정을 복원해야 합니다. 공유 VPC 호스트 프로젝트의 서브넷 리전은 App Engine 환경이 만들어진 위치와 일치해야 합니다.

문제가 지속되면 Google Cloud SDK를 사용하여 서비스를 다시 배포합니다. --verbosity=debug 플래그를 추가해야 합니다. Google Cloud 지원팀에 문의하여 명령어의 출력을 제공합니다.

IP space of {USER_SUBNETWORK_NAME} is exhausted and needs to be expanded.

이 오류 메시지와 함께 배포가 실패하면 App Engine 서비스에 구성된 네트워크에 서비스의 새 인스턴스에 할당하기 위해 남아 있는 주소가 없음을 의미합니다. 이 문제를 해결하려면 App Engine 가변형 환경 서비스에 구성된 서브넷에서 VPC 범위를 확장합니다.