app.yaml 구성 파일

Go Java Node.js PHP Python Ruby .NET 커스텀

app.yaml 파일은 런타임의 구성 설정뿐만 아니라 일반적인 앱, 네트워크, 기타 리소스 설정까지 정의합니다.

.gcloudignore 파일에 app.yaml을 추가하지 마세요. 배포에 app.yaml가 필요할 수 있으며 .gcloudignore에 추가하면 배포가 실패합니다.

구문

app.yaml 파일의 구문은 YAML 형식입니다. YAML 형식은 해시태그(#) 문자로 시작하는 모든 줄이 무시되는 주석을 지원합니다. 예를 들면 다음과 같습니다.

# This is a comment.

URL 및 파일 경로 패턴은 대조 요소와 대조 클래스를 제외한 POSIX 확장 정규 표현식 구문을 사용합니다. 그룹화된 일치로의 역참조(예: \1)가 지원되며 Perl 확장명(\w \W \s \S \d \D)도 지원됩니다.

일반 설정

app.yaml 파일에는 이러한 일반 설정이 포함될 수 있습니다. 일부 설정은 필수입니다.

이름	설명
build_env_variables	선택사항. 빌드팩을 지원하는 런타임을 사용하는 경우 app.yaml 파일에 빌드 환경 변수를 정의할 수 있습니다. 자세한 내용은 빌드 환경 변수 사용을 참조하세요.
runtime	필수. 앱에서 사용되는 런타임 환경 이름입니다. 예를 들어 런타임 환경을 지정하려면 다음을 사용합니다.
env: flex	필수: 가변형 환경을 선택합니다.
service: service_name	서비스를 만들 경우 필수 항목입니다. 기본 서비스의 경우 선택 항목입니다. 각 서비스와 버전에는 이름이 있어야 합니다. 이름에는 숫자, 문자, 하이픈이 포함될 수 있습니다. 가변형 환경에서 VERSION-dot-SERVICE-dot-PROJECT_ID의 결합된 길이(VERSION는 버전 이름, SERVICE은 서비스 이름, PROJECT_ID는 프로젝트 ID)는 63자(영문)를 초과할 수 없으며 하이픈으로 시작하거나 끝날 수 없습니다. 서비스 이름을 지정하지 않고 배포할 경우 기본 서비스의 새 버전이 생성됩니다. 이미 존재하는 서비스 이름으로 배포할 경우 해당 서비스의 새 버전이 생성됩니다. 존재하지 않는 새 서비스 이름으로 배포할 경우 새 서비스 및 버전이 생성됩니다. 각 서비스-버전 조합에 고유한 이름을 사용하는 것이 좋습니다. 참고: 이전에는 서비스를 '모듈'이라고 했습니다.
service_account	선택사항. service_account 요소를 사용하면 사용자 관리 서비스 계정을 버전의 ID로 지정할 수 있습니다. 지정된 서비스 계정은 다른 Google Cloud 서비스에 액세스하고 작업을 실행할 때 사용됩니다. 서비스 계정은 다음 형식으로 제공해야 합니다. service_account: [SERVICE_ACCOUNT_NAME]@[PROJECT_ID].iam.gserviceaccount.com
skip_files	선택사항. skip_files 요소는 애플리케이션 디렉터리에서 App Engine에 업로드하지 않아야 하는 파일을 지정합니다. 이 값은 정규 표현식이거나 정규 표현식의 목록입니다. 정규 표현식과 일치하는 파일 이름은 애플리케이션이 업로드될 때 업로드할 파일 목록에서 생략됩니다. 예를 들어 이름이 .bak로 끝나는 파일을 건너뛰려면 다음과 같은 skip_files 섹션을 추가합니다. skip_files: - ^.*\.bak$

네트워크 설정

app.yaml 구성 파일에 네트워크 설정을 지정할 수 있습니다. 예를 들면 다음과 같습니다.

network:
  name: NETWORK_NAME
  instance_ip_mode: INSTANCE_IP_MODE
  instance_tag: TAG_NAME
  subnetwork_name: SUBNETWORK_NAME
  session_affinity: true
  forwarded_ports:
    - PORT
    - HOST_PORT:CONTAINER_PORT
    - PORT/tcp
    - HOST_PORT:CONTAINER_PORT/udp

네트워크 설정을 구성할 때 다음 옵션을 사용할 수 있습니다.

옵션	설명
name	가변형 환경의 모든 VM 인스턴스는 인스턴스가 만들어질 때 Google Compute Engine 네트워크에 할당됩니다. 네트워크 이름을 지정할 때 이 설정을 사용합니다. 리소스 경로가 아닌 짧은 이름을 지정합니다(예: https://www.googleapis.com/compute/v1/projects/my-project/global/networks/default 대신 default). 네트워크 이름을 지정하지 않으면 인스턴스가 프로젝트의 기본 네트워크(이름 default)에 할당됩니다. 서브네트워크 이름을 지정하려면 네트워크 이름을 지정해야 합니다.
instance_ip_mode	선택사항. 인스턴스가 임시 외부 IP 주소를 수신하지 못하도록 방지하려면 internal로 설정하고 비공개 Google 액세스를 사용 설정합니다. 인스턴스가 이전에 이 설정 없이 배포된 경우 또는 external로 설정하여 배포된 경우 internal 설정을 사용하여 다시 배포하면 인스턴스에서 임시 외부 IP 주소가 삭제됩니다. internal 설정에는 제한사항이 있습니다. 기본값은 external입니다.
instance_tag	선택사항. 인스턴스가 만들어질 때 서비스의 각 인스턴스에 해당 이름이 할당되는 태그입니다. 태그는 인스턴스 그룹에 작업을 타겟팅하는 gcloud 명령어에서 유용합니다. compute firewalls-create 명령어에 --source-tags 및 --target-tags 플래그를 사용하는 경우를 예시로 들 수 있습니다. 지정하지 않으면 공유 VPC가 사용되지 않는 경우 인스턴스에 aef-INSTANCE_ID 태그가 지정됩니다. 공유 VPC가 사용되는 경우 인스턴스에 aef-INSTANCE_ID and aef-instance. 태그가 모두 지정됩니다.
subnetwork_name	선택사항. 네트워크를 분류하고 커스텀 서브네트워크를 사용할 수 있습니다. 네트워크 name을 지정해야 합니다. 리소스 경로가 아닌 짧은 이름을 지정합니다(예: https://www.googleapis.com/compute/v1/projects/my-project/global/networks/default/subnetworks/default 대신 default). 서브네트워크는 애플리케이션과 동일한 리전에 있어야 합니다.
session_affinity	선택사항. 세션 중에 사용자 데이터를 로컬에 저장하는 경우와 같이 지정된 사용자에 대한 여러 순차 요청을 동일한 App Engine 인스턴스로 라우팅하도록 App Engine을 구성하려면 true로 설정합니다. 세션 어피니티는 동일한 사용자의 여러 요청을 식별하는 쿠키 값 검사를 사용 설정한 후 이러한 모든 요청을 동일한 인스턴스로 전달합니다. 인스턴스 수가 축소되었을 때 인스턴스가 재부팅되거나, 비정상 또는 과부하 상태이거나, 사용할 수 없는 상태가 되면 세션 어피니티가 손상되고 이후 요청이 다른 인스턴스로 라우팅됩니다. 세션 어피니티를 사용 설정하면 부하 분산 설정에 영향을 줄 수 있습니다. 이 매개변수는 기본적으로 사용 중지됩니다.
forwarded_ports	선택사항. 포트를 인스턴스(HOST_PORT)에서 Docker 컨테이너(CONTAINER_PORT)로 전달할 수 있습니다. HOST_PORT는 1024와 65535 사이여야 하며 포트 22, 8080, 8090, 8443, 10000, 10001, 10400-10500, 11211, 24231과 충돌할 수 없습니다. CONTAINER_PORT는 1에서 65535 사이여야 하며 포트 22, 10001, 10400-10500, 11211과 충돌할 수 없습니다. PORT만 지정할 경우, App Engine은 해당 포트가 호스트와 컨테이너에 있는 포트와 동일하다고 가정합니다. 기본적으로 TCP 트래픽과 UDP 트래픽이 모두 전달됩니다. 트래픽은 appspot.com 도메인이나 커스텀 도메인을 통해서가 아니라 대상 인스턴스의 IP 주소로 직접 전송되어야 합니다.

고급 네트워크 구성

Compute Engine 네트워크를 여러 개의 하위 네트워크로 분류할 수 있습니다. 이렇게 하면 기업 네트워크 내의 데이터베이스에 액세스하는 등의 VPN 시나리오를 사용 설정할 수 있습니다.

App Engine 애플리케이션에 하위 네트워크를 사용 설정하려면 다음 안내를 따르세요.

1. 커스텀 서브넷 네트워크를 만듭니다.

2. 위에서 지정한 대로 app.yaml 파일에 네트워크 이름과 서브네트워크 이름을 추가합니다.

3. 정적 라우팅 기반의 간단한 VPN을 설정하려면 커스텀 서브넷 네트워크를 위한 게이트웨이와 터널을 생성합니다. 그렇지 않은 경우 다른 유형의 VPN을 생성하는 방법을 참조하세요.

포트 전달

포트 전달을 이용하면 인스턴스의 Docker 컨테이너에 직접 연결할 수 있습니다. 이 트래픽은 모든 프로토콜을 통해 이동할 수 있습니다. 포트 전달은 디버거 또는 프로파일러를 연결해야 하는 상황에 도움을 주기 위한 것입니다. 트래픽은 appspot.com 도메인이나 커스텀 도메인을 통해서가 아니라 대상 인스턴스의 IP 주소로 직접 전송되어야 합니다.

기본적으로, 네트워크 외부에서 들어오는 트래픽은 Google Cloud Platform 방화벽을 통해 허용되지 않습니다. app.yaml 파일에 포트 전달을 지정한 후에는 열어 놓을 포트로부터 트래픽을 허용하는 방화벽 규칙을 추가해야 합니다.

Google Cloud 콘솔의 네트워킹 방화벽 규칙 페이지에서 또는 gcloud 명령어를 사용하여 방화벽 규칙을 지정할 수 있습니다.

예를 들어 포트 2222에서 들어오는 TCP 트래픽을 전달하려면 다음 안내를 따르세요.

1. app.yaml의 네트워크 설정에 다음을 포함시킵니다.

   network:
     forwarded_ports:
       - 2222/tcp
   

   1. Python 런타임을 사용하는 경우 다음을 포함하도록 app.yaml을 수정합니다.

      entrypoint: gunicorn -b :$PORT -b :2222 main:app
      

2. Google Cloud 콘솔에서 또는 gcloud compute firewall-rules create를 사용해 방화벽 규칙을 지정하여 모든 소스(0.0.0.0/0)와 tcp:2222에서 들어오는 트래픽을 허용합니다.

리소스 설정

이 설정은 컴퓨팅 리소스를 제어합니다. App Engine은 사용자가 지정한 CPU와 메모리의 크기에 따라 머신 유형을 할당합니다. 머신에는 최소한 사용자가 지정한 수준 이상의 리소스가 보장되며 그 이상의 리소스가 제공될 수도 있습니다.

리소스 설정에서 최대 8개의 tmpfs 볼륨을 지정할 수 있습니다. 그런 다음 tmpfs를 통해 공유된 메모리를 필요로 하는 워크로드를 사용 설정하고 파일 시스템 I/O를 개선할 수 있습니다.

예를 들면 다음과 같습니다.

resources:
  cpu: 2
  memory_gb: 2.3
  disk_size_gb: 10
  volumes:
  - name: ramdisk1
    volume_type: tmpfs
    size_gb: 0.5

리소스 설정을 구성할 때 다음 옵션을 사용할 수 있습니다.

옵션	설명	기본값
cpu	코어 수는 하나여야 하며 2~32 사이의 짝수이거나 32와 80 사이의 4의 배수여야 합니다.	1개의 코어
memory_gb	RAM(GB). 애플리케이션에 요청된 메모리이며, 일부 프로세스의 오버헤드에 필요한 0.4GB 이하의 메모리는 여기에 포함되지 않습니다 각 CPU 코어에 1.0~6.5GB 사이의 총 메모리가 필요합니다. 요청된 메모리를 계산하려면 다음을 사용하세요. memory_gb = cpu * [1.0 - 6.5] - 0.4 2개의 코어를 지정한 위의 예시에서는 1.6~12.6GB를 요청할 수 있습니다. 애플리케이션에 제공되는 총 메모리는 런타임 환경에서 환경 변수 GAE_MEMORY_MB로 설정합니다.	0.6GB
disk_size_gb	크기(GB). 최솟값은 10GB이고 최댓값은 10,240GB입니다.	13GB
name	볼륨을 사용할 경우 필수 항목이며, 볼륨의 이름입니다. 이름은 고유해야 하며 1~63자여야 합니다. 소문자, 숫자, 대시로 구성될 수 있습니다. 첫 번째 글자는 문자여야 하고, 마지막 글자는 대시가 아니어야 합니다. 볼륨은 앱 컨테이너에 /mnt/NAME으로 마운트됩니다.
volume_type	볼륨을 사용할 경우 필수 항목이며, tmpfs이어야 합니다.
size_gb	볼륨을 사용할 경우 필수 항목이며, 볼륨의 크기(GB)입니다. 최솟값은 0.001GB이고 최댓값은 애플리케이션 컨테이너와 기본 기기에 제공되는 메모리 양입니다. Google은 디스크 요구사항을 충족하기 위해 시스템에 추가 RAM을 추가하지 않습니다. tmpfs 볼륨에 할당되는 RAM은 앱 컨테이너에 제공되는 메모리에서 차감됩니다. 정밀도는 시스템에 따라 다릅니다.

분할 상태 확인

기본적으로 분할 상태 확인은 사용하도록 설정됩니다. 정기적인 상태 확인 요청을 통해 VM 인스턴스가 성공적으로 배포되었는지 확인하고 실행 중인 인스턴스가 정상 상태로 유지되는지 확인할 수 있습니다. 각 상태 확인에 대한 응답은 지정된 시간 간격 내에 이루어져야 합니다.

지정된 횟수만큼 연속으로 상태 확인 요청에 응답하지 못하는 인스턴스는 비정상 상태로 간주됩니다. 인스턴스가 활성 상태가 아니면 다시 시작됩니다. 인스턴스가 준비된 상태가 아니면 어떤 클라이언트 요청도 수신하지 못합니다. 사용 가능한 디스크 공간이 없으면 상태 확인에 실패할 수도 있습니다.

다음과 같은 두 가지 유형의 상태 확인을 사용할 수 있습니다.

• 활성 확인은 VM 및 Docker 컨테이너가 실행 중인지 확인합니다. App Engine이 비정상 인스턴스를 다시 시작합니다.
• 준비 확인은 인스턴스가 수신되는 요청을 수락할 수 있는지 확인합니다. 준비 확인에 실패한 인스턴스는 사용 가능한 인스턴스의 풀에 추가되지 않습니다.

경고: 이제 /_ah/health 경로를 사용한 기존 상태 확인이 지원 중단되었으므로 분할 상태 확인을 사용하도록 마이그레이션해야 합니다.

기본적으로, 상태 확인의 HTTP 요청은 애플리케이션 컨테이너로 전달되지 않습니다. 상태 확인을 애플리케이션으로 확장하려면 활성 확인 또는 준비 확인을 위한 경로를 지정합니다. 200 OK 응답 코드를 반환할 경우 애플리케이션의 커스텀 상태 확인에 성공한 것으로 간주됩니다.

활성 확인

활성 확인은 VM 및 Docker 컨테이너가 실행 중인지 확인합니다. 비정상으로 간주되는 인스턴스는 다시 시작됩니다.

선택사항인 liveness_check 섹션을 app.yaml 파일에 추가하여 활성 확인 요청을 맞춤설정할 수 있습니다. 예를 들면 다음과 같습니다.

liveness_check:
  path: "/liveness_check"
  check_interval_sec: 30
  timeout_sec: 4
  failure_threshold: 2
  success_threshold: 2

활성 확인에 다음 설정을 사용할 수 있습니다.

필드	기본값	범위(최소-최대)	설명
path	없음		활성 확인을 애플리케이션 컨테이너에 전달하려면 "/liveness_check"와 같은 URL 경로를 지정합니다.
timeout_sec	4초	1-300	각 요청의 제한 시간 간격(초)입니다.
check_interval_sec	30초	1-300	각 확인 사이의 시간 간격(초)입니다. 이 값은 timeout_sec보다 커야 합니다.
failure_threshold	4회 확인	1~10	이 횟수만큼 연속으로 확인에 실패하면 인스턴스가 비정상입니다.
success_threshold	2회 확인	1~10	비정상 인스턴스가 이 횟수만큼 연속으로 확인에 응답하는 데 성공하면 정상이 됩니다.
initial_delay_sec	300초	0-3600	인스턴스가 시작된 후에 상태 확인 응답이 무시되는 지연 시간(초)입니다. 이 설정은 새로 생성된 각 인스턴스에 적용되며 새 인스턴스의 준비 및 실행 시간을 늘릴 수 있습니다. 이 설정은 인스턴스를 시작하는 중에 인스턴스를 점검하고 조기에 다시 만들지 않도록 자동 복구를 지연합니다. 인스턴스가 RUNNING 모드이면 초기 지연 타이머가 시작됩니다. 예를 들어 애플리케이션이 초기화 작업 때문에 트래픽 처리 준비까지 시간이 오래 걸린다면 지연을 늘릴 수 있습니다.

준비 확인

준비 확인은 인스턴스가 수신되는 요청을 수락할 수 있는지 확인합니다. 준비 확인을 통과하지 못한 인스턴스는 사용 가능한 인스턴스의 풀에 추가되지 않습니다.

선택사항인 readiness_check 섹션을 app.yaml 파일에 추가하여 상태 확인 요청을 맞춤설정할 수 있습니다. 예를 들면 다음과 같습니다.

readiness_check:
  path: "/readiness_check"
  check_interval_sec: 5
  timeout_sec: 4
  failure_threshold: 2
  success_threshold: 2
  app_start_timeout_sec: 300

준비 확인에 다음 설정을 사용할 수 있습니다.

필드	기본값	범위(최소-최대)	설명
path	없음		준비 확인을 애플리케이션 컨테이너에 전달하려면 "/readiness_check"와 같은 URL 경로를 지정합니다.
timeout_sec	4초	1-300	각 요청의 제한 시간 간격(초)입니다.
check_interval_sec	5초	1-300	각 확인 사이의 시간 간격(초)입니다. 이 값은 timeout_sec보다 커야 합니다.
failure_threshold	2회 확인	1~10	이 횟수만큼 연속으로 확인에 실패하면 인스턴스가 비정상입니다.
success_threshold	2회 확인	1~10	비정상 인스턴스가 이 횟수만큼 연속으로 확인에 응답하는 데 성공하면 정상이 됩니다.
app_start_timeout_sec	300초	1-1800	이 설정은 개별 VM이 아닌 새 배포에 적용됩니다. 배포에서 충분한 수의 인스턴스가 상태 확인을 통과하는 데 필요한 최대 시간(초)을 지정합니다. 이 시간이 지나면 배포가 실패하여 롤백됩니다. 이 타이머는 Compute Engine 인스턴스가 프로비저닝되고 Load Balancer 백엔드 서비스가 생성되면 작동하기 시작합니다. 예를 들어 배포 중에 충분한 수의 인스턴스가 양호한 상태를 유지하도록 제한 시간을 늘리고 싶다면 제한 시간을 늘리면 됩니다.

상태 확인 빈도

가용성을 높이기 위해 App Engine에서는 각 상태 검사기의 중복 사본을 만듭니다. 상태 검사기가 실패하면 지연 시간 없이 중복 검사기가 그 역할을 대신합니다.

애플리케이션의 nginx.health_check 로그를 확인하면 사용자 설정까지 따르는 중복 상태 검사기 때문에 상태 확인 폴링이 사용자가 구성한 빈도보다 더 자주 일어나는 경우가 있습니다. 이 중복 상태 검사기는 자동으로 생성되며 사용자가 구성할 수 없습니다.

서비스 확장 설정

서비스의 확장을 제어하는 데 사용되는 키는 서비스에 할당하는 확장의 유형에 따라 다릅니다.

자동 확장 또는 수동 확장을 사용할 수 있습니다. 기본값은 자동 확장입니다.

자동 확장

app.yaml 파일에 automatic_scaling 섹션을 추가하여 자동 확장을 구성할 수 있습니다. 예를 들면 다음과 같습니다.

automatic_scaling:
  min_num_instances: 1
  max_num_instances: 15
  cool_down_period_sec: 180
  cpu_utilization:
    target_utilization: 0.6
  target_concurrent_requests: 100

다음 표에는 자동 확장에 사용할 수 있는 설정이 나와 있습니다.

이름	설명
automatic_scaling	기본적으로 자동 확장이 적용됩니다. 자동 확장 설정을 지정하려면 이 줄을 포함시킵니다.
min_num_instances	서비스에 제공되는 인스턴스의 최소 개수입니다. 서비스가 배포되면 트래픽에 따라 이 개수만큼 인스턴스와 확장이 제공됩니다. 1 이상이어야 하며, 지연 시간을 줄이기 위한 기본값은 2입니다. 참고: 일부 이벤트 중에 단기간 동안 실행 중인 인스턴스 수가 이 값 아래로 내려갈 수 있습니다. 애플리케이션을 특정 수의 인스턴스에서 계속 실행해야 하는 경우 오버프로비저닝을 사용하는 것이 좋습니다.
max_num_instances	서비스가 확장될 수 있는 인스턴스의 최대 개수입니다. 프로젝트 내 최대 인스턴스 수는 프로젝트의 리소스 할당량에 따라 제한됩니다. 기본값은 20입니다.
cool_down_period_sec	자동 확장 처리가 새로운 인스턴스에서 정보를 수집하기 전에 대기하는 시간(초)입니다. 이 설정은 인스턴스가 초기화될 때 자동 확장 처리가 정보를 수집하지 못하게 합니다. 초기화하는 동안 수집된 사용량은 정확하지 않기 때문입니다. 대기 시간은 60초 이상이어야 합니다. 기본값은 120입니다.
cpu_utilization	대상 CPU 사용률을 지정하려면 이 헤더를 사용하세요.
target_utilization	대상 CPU 사용률입니다. CPU 사용률은 실행 중인 모든 인스턴스의 평균으로 계산되며 인스턴스의 개수를 줄이거나 늘릴 시기를 결정하는 데 사용됩니다. 인스턴스가 종료 신호를 수신한 후 25초가 지나면 처리 중인 요청과 관계없이 인스턴스가 축소됩니다. 기본값은 0.5입니다.
target_concurrent_requests	(베타) 인스턴스당 동시 연결 수를 타겟팅합니다. 이 매개변수의 값을 지정하면 자동 확장 처리는 실행 중인 모든 인스턴스의 평균 동시 연결 수를 사용하여 인스턴스 수를 줄이거나 늘릴 시기를 결정합니다. 처리 중인 요청과 관계없이 종료 신호를 수신한 후 25초가 지나면 인스턴스가 축소됩니다. 이 매개변수의 값을 지정하지 않으면 자동 확장 처리가 인스턴스당 동시 연결 수를 타겟팅하지 않습니다. 연결은 요청과 다릅니다. 클라이언트는 연결을 재사용하여 여러 요청을 보낼 수 있습니다.

수동 확장

app.yaml 파일에 manual_scaling 섹션을 추가하여 수동 확장을 구성할 수 있습니다. 예를 들면 다음과 같습니다.

manual_scaling:
  instances: 5

다음 표에는 수동 확장과 함께 사용할 수 있는 설정이 나와 있습니다.

이름	설명
manual_scaling	서비스에 수동 확장을 사용 설정하는 데 필요합니다.
instances	서비스에 할당할 인스턴스의 개수입니다. 참고: 일부 이벤트 중에 단기간 동안 실행 중인 인스턴스 수가 이 값 아래로 내려갈 수 있습니다. 애플리케이션을 특정 수의 인스턴스에서 계속 실행해야 하는 경우 오버프로비저닝을 사용하는 것이 좋습니다.

환경 변수 정의

app.yaml에서 환경 변수를 정의하여 앱에서 사용할 수 있도록 합니다. 예를 들면 다음과 같습니다.

env_variables:
  MY_VAR: "my value"

여기서 MY_VAR 및 my value는 정의하려는 환경 변수의 이름과 값이며, 각 환경 변수 항목은 env_variables 요소 아래에 두 칸의 공백으로 들여쓰기됩니다.

환경 변수 사용