컨테이너 런타임 계약

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

이 페이지에는 Cloud Run 컨테이너의 주요 요구사항과 동작이 나와 있습니다. Cloud Run 서비스와 Cloud Run 작업 간에는 몇 가지 차이점이 있습니다. 이러한 작업은 적절한 경우에 호출됩니다.

지원 언어 및 이미지

컨테이너 이미지는 선택한 프로그래밍 언어로 작성된 코드를 실행하고 이 페이지에 나열된 제약조건을 준수하는 기본 이미지를 사용할 수 있습니다.

컨테이너 이미지의 실행 파일은 Linux 64비트용으로 컴파일되어야 합니다. Cloud Run에서는 특히 Linux x86_64 ABI 형식을 지원합니다.

Cloud Run은 Docker 이미지 매니페스트 V2, 스키마 1, 스키마 2, OCI 이미지 형식의 컨테이너 이미지를 허용합니다.

멀티 아키텍처 이미지에 사용되는 매니페스트 목록은 지원되지 않습니다.

올바른 포트에서 요청 리슨(서비스)

Cloud Run 서비스의 경우 컨테이너가 요청이 전송되는 포트의 0.0.0.0에서 요청을 리슨해야 합니다. 기본적으로 요청은 8080으로 전송되지만 원하는 포트로 요청을 전송하도록 Cloud Run을 구성할 수 있습니다. Cloud Run은 PORT 환경 변수를 컨테이너에 삽입합니다. Cloud Run 컨테이너 인스턴스 내에서 PORT 환경 변수 값은 항상 요청이 전송되는 포트를 반영합니다. 기본값은 8080입니다.

완료 시 작업 실행에서 실행 중인 컨테이너를 종료해야 함

Cloud Run 작업의 경우 컨테이너는 작업이 성공적으로 완료되면 종료 코드 0으로 종료되고 작업이 실패하면 0이 아닌 종료 코드로 종료되어야 합니다.

작업은 요청을 처리하면 안 되므로 컨테이너는 포트에서 리슨하거나 웹 서버를 시작하면 안 됩니다.

전송 계층 암호화(TLS)

컨테이너가 전송 계층 보안을 직접 구현해서는 안 됩니다. TLS는 HTTPS 및 gRPC를 위해 Cloud Run에 의해 종료된 후 요청이 TLS 없이 컨테이너에 HTTP/1 또는 gRPC로 프록시됩니다.

HTTP/2 엔드 투 엔드를 사용하도록 Cloud Run 서비스를 구성하는 경우 TLS가 여전히 Cloud Run에 의해 자동으로 종료되므로 컨테이너에서 HTTP/2 일반 텍스트(h2c) 형식의 요청을 처리해야 합니다.

응답(서비스)

Cloud Run 서비스의 경우 컨테이너 인스턴스는 컨테이너 인스턴스 시작 시간을 포함하여 요청을 받은 후 요청 제한 시간 설정에 지정된 시간 내에 응답을 보내야 합니다. 그러지 않으면 요청이 종료되고 504 오류가 반환됩니다.

환경 변수

Cloud Run 서비스 및 작업에는 여러 환경 변수 세트를 사용할 수 있습니다.

서비스에 대한 환경 변수

다음 환경 변수는 실행 중인 컨테이너에 자동으로 추가됩니다.

이름 설명 예시
PORT HTTP 서버가 리슨하는 포트입니다. 8080
K_SERVICE 실행되는 Cloud Run 서비스의 이름입니다. hello-world
K_REVISION 실행되는 Cloud Run 버전의 이름입니다. hello-world.1
K_CONFIGURATION 버전을 만든 Cloud Run 구성의 이름입니다. hello-world

작업에 대한 환경 변수

Cloud Run 작업의 경우 다음 환경 변수가 설정됩니다.

이름 설명 예시
CLOUD_RUN_JOB 실행되는 Cloud Run 작업의 이름입니다. hello-world
CLOUD_RUN_EXECUTION 실행되는 Cloud Run 실행의 이름입니다. hello-world-abc
CLOUD_RUN_TASK_INDEX 각 태스크에 대해 0에서 태스크 수에서 1을 뺀 값 사이의 고유한 값으로 설정됩니다. 0
CLOUD_RUN_TASK_ATTEMPT 이 태스크가 다시 시도된 횟수입니다. 첫 시도는 0에서 시작합니다. 최대 재시도 값까지 연속 재시도마다 1씩 증가합니다. 0
CLOUD_RUN_TASK_COUNT --tasks 매개변수에 정의된 태스크 수입니다. 1

요청 및 응답 헤더 요구사항(서비스)

Cloud Run 서비스의 경우 헤더 이름은 공백이 아닌 ASCII로 제한되며 콜론을 포함할 수 없습니다. IETF RFC 7230에 따라 헤더 값은 표시된 ASCII 문자, 공백, 가로 탭으로 제한됩니다.

파일 시스템 액세스

컨테이너의 파일 시스템은 쓰기가 가능하고 다음과 같은 동작이 적용됩니다.

  • 메모리 내 파일 시스템이므로 컨테이너 인스턴스의 메모리를 사용합니다.
  • 파일 시스템에 쓴 데이터는 컨테이너 인스턴스가 중지되면 유지되지 않습니다.

컨테이너 인스턴스 수명 주기

Cloud Run 작업 및 서비스에 대한 수명 주기 특성이 다르므로, 다음 하위 섹션에서 별도로 설명합니다.

서비스

다음은 서비스에만 적용됩니다.

서비스 확장

Cloud Run 서비스의 경우 수신 요청에 따라 서비스가 특정 수의 컨테이너 인스턴스로 자동 확장되며 각 인스턴스는 배포된 컨테이너 이미지를 실행합니다.

버전이 트래픽을 수신하지 않을 경우 구성된 최소 컨테이너 인스턴스 수로 축소됩니다(기본적으로 0개).

시작

Cloud Run 서비스의 경우 컨테이너 인스턴스는 시작 후 4분 이내에 요청을 리슨해야 합니다. 이 시작 시간 동안 컨테이너 인스턴스에는 CPU가 할당됩니다.

요청은 구성된 포트에서 리슨하는 즉시 컨테이너 인스턴스로 전송됩니다.

컨테이너 인스턴스가 시작되기를 기다리는 요청은 최대 10초 동안 큐에 보관됩니다.

시작 프로브를 구성하여 컨테이너가 시작되었고 요청을 처리할 준비가 되었는지 여부를 확인할 수 있습니다.

요청 처리

컨테이너 인스턴스가 요청을 최소 하나 이상 처리할 때 항상 CPU가 할당됩니다.

유휴

Cloud Run 서비스의 경우 유휴 컨테이너 인스턴스는 요청을 처리하지 않는 인스턴스입니다.

유휴 컨테이너 인스턴스에 할당되는 CPU는 구성된 CPU 할당에 따라 다릅니다.

최소 컨테이너 인스턴스 수 구성 설정으로 인해 컨테이너 인스턴스를 유휴 상태로 유지해야 하는 경우가 아니라면 15분 이상 유휴 상태로 유지되지 않습니다.

종료

Cloud Run 서비스의 경우 최소 인스턴스 수를 통해 웜(warm) 상태로 유지되는 컨테이너 인스턴스 등 컨테이너 유휴 인스턴스를 언제든지 종료할 수 있습니다. 요청을 처리하는 컨테이너 인스턴스를 종료해야 하는 경우 새로 수신되는 요청이 다른 인스턴스로 라우팅되고 현재 처리 중인 요청에 완료 시간이 제공됩니다.

컨테이너 인스턴스를 종료하기 전에 Cloud Run은 실제 종료가 발생하기 전 10초 기간 시작을 나타내는 SIGTERM 신호를 전송합니다. 이때 Cloud Run은 SIGKILL 신호를 전송합니다. 이 기간에는 컨테이너 인스턴스에 CPU가 할당되고 요금이 청구됩니다. 컨테이너 인스턴스에서 SIGTERM 신호를 포착하지 않으면 즉시 종료됩니다. SIGTERM 신호를 포착하는 방법은 코드 샘플을 참조하세요.

강제 종료

허용된 메모리 한도를 초과하는 Cloud Run 컨테이너 인스턴스가 종료됩니다. 계속 컨테이너 인스턴스에서 처리 중인 모든 요청이 HTTP 500 오류로 종료됩니다.

작업

Cloud Run 작업의 경우 컨테이너 인스턴스는 컨테이너 인스턴스가 종료될 때까지, 또는 태스크 시간 제한에 도달하거나 컨테이너가 비정상 종료될 때까지 실행됩니다. 컨테이너 인스턴스에서 SIGTERM 신호를 포착하지 않으면 즉시 종료됩니다. SIGTERM 신호를 포착하는 방법은 코드 샘플을 참조하세요.

강제 종료

허용된 메모리 한도를 초과하는 Cloud Run 컨테이너 인스턴스가 종료됩니다. 계속 컨테이너 인스턴스에서 처리 중인 모든 요청이 HTTP 500 오류로 종료됩니다.

태스크가 태스크 시간 제한을 초과하면 Cloud Run은 실제 종료가 발생하기 전 10초 기간의 시작을 나타내는 'SIGTERM' 신호를 보냅니다. Cloud Run이 SIGKILL 신호를 보는 시점에 컨테이너 인스턴스를 종료합니다.

이 기간 동안 컨테이너 인스턴스에는 전체 수명 주기 동안 CPU가 할당되며 요금이 청구됩니다.

컨테이너 인스턴스 리소스

CPU

각 Cloud Run 컨테이너 인스턴스에는 기본적으로 구성된 vCPU가 할당됩니다(기본적으로 1개).

vCPU는 기본 하드웨어를 추상화한 형태로 구현되어 가변 CPU 플랫폼의 단일 하드웨어 하이퍼 스레드에 그에 상응하는 대략적인 CPU 시간을 제공합니다. Cloud Run에서 사용하는 모든 CPU 플랫폼은 AVX2 명령 집합을 지원합니다. 컨테이너 계약에는 추가 CPU 플랫폼 세부정보가 포함되어 있지 않습니다.

컨테이너 인스턴스는 여러 코어에서 동시에 실행될 수 있습니다.

Cloud Run 서비스의 경우 인스턴스 수명 동안 항상 할당되거나 컨테이너 인스턴스 시작 및 요청 처리 중에만 할당되도록 CPU를 지정할 수 있습니다. 자세한 내용은 CPU 할당을 참조하세요.

최소 인스턴스 수를 구성한 경우 이러한 인스턴스에도 CPU 할당 구성이 적용됩니다.

메모리

각 Cloud Run 컨테이너 인스턴스에는 기본적으로 구성된 메모리가 할당됩니다(기본적으로 512MiB).

메모리의 일반적인 용도는 다음과 같습니다.

  • 서비스 실행을 위해 메모리에 로드되는 코드
  • 파일 시스템에 쓰기
  • nginx 서버와 같이 컨테이너에서 실행되는 추가 프로세스
  • PHP OpCache와 같은 인메모리 캐싱 시스템
  • 요청당 메모리 사용량

동시 실행(서비스)

Cloud Run 서비스의 경우 각 Cloud Run 컨테이너 인스턴스는 기본적으로 여러 번 동시 실행되도록 설정되며 각 컨테이너 인스턴스에서 동시에 요청을 두 개 이상 수신할 수 있습니다. 동시 실행을 설정하여 이를 변경할 수 있습니다.

컨테이너 인스턴스 샌드박스

1세대 실행 환경을 사용하는 경우 Cloud Run 컨테이너 인스턴스는 gVisor 컨테이너 런타임 샌드박스를 통해 샌드박스 처리됩니다. gVisor syscall 호환성 참조의 설명대로 일부 시스템 호출은 이 컨테이너 샌드박스에서 지원되지 않을 수 있습니다.

2세대 실행 환경을 사용하면 전체 Linux 호환성이 제공됩니다. Cloud Run 작업은 항상 2세대 실행 환경을 사용합니다. 2세대 실행 환경 내에서 /sys/class/dmi/id/product_nameGoogle Compute Engine으로 설정됩니다.

컨테이너 인스턴스 메타데이터 서버

Cloud Run 컨테이너 인스턴스는 프로젝트 ID, 리전, 인스턴스 ID 또는 서비스 계정과 같은 컨테이너 인스턴스에 대한 세부정보를 검색하는 데 사용할 수 있는 메타데이터 서버를 노출합니다. 런타임 서비스 계정의 토큰을 생성하는 데도 사용될 수 있습니다.

Metadata-Flavor: Google 헤더로 http://metadata.google.internal/ 엔드포인트에 대한 간단한 HTTP 요청을 사용하여 메타데이터 서버에서 이 데이터에 액세스할 수 있습니다. 이때 클라이언트 라이브러리는 필요하지 않습니다. 자세한 내용은 메타데이터 가져오기를 참조하세요.

다음 표에는 사용 가능한 메타데이터 서버 정보 중 일부가 나와 있습니다.

경로 설명
/computeMetadata/v1/project/project-id Cloud Run 서비스 또는 작업이 포함된 프로젝트의 프로젝트 ID입니다.
/computeMetadata/v1/project/numeric-project-id Cloud Run 서비스 또는 작업이 포함된 프로젝트의 프로젝트 번호입니다.
/computeMetadata/v1/instance/region 이 Cloud Run 서비스 또는 작업의 리전으로 projects/PROJECT-NUMBER/regions/REGION을 반환합니다.
/computeMetadata/v1/instance/id 컨테이너 인스턴스의 고유 식별자입니다(로그에서도 확인 가능).
/computeMetadata/v1/instance/service-accounts/default/email 이 Cloud Run 서비스 또는 작업의 런타임 서비스 계정 이메일입니다.
/computeMetadata/v1/instance/service-accounts/default/token 이 Cloud Run 서비스 또는 작업의 서비스 계정에 대한 OAuth2 액세스 토큰을 생성합니다. Cloud Run 서비스 에이전트는 토큰을 가져오는 데 사용됩니다. 이 엔드포인트는 access_token 속성과 함께 JSON 응답을 반환합니다. 이 액세스 토큰을 추출하고 사용하는 방법을 자세히 알아보세요.

Cloud Run에서는 컨테이너 인스턴스가 실행 중인 Google Cloud 영역에 대한 세부정보를 제공하지 않습니다. 따라서 메타데이터 속성 /computeMetadata/v1/instance/zone은 항상 projects/PROJECT-NUMBER/zones/REGION-1을 반환합니다.

파일 이름

컨테이너에 사용되는 파일 이름은 UTF-8이나 UTF-8로 안전하게 자동 변환할 수 있는 이름과 호환되는 UTF-8과 호환되어야 합니다. 그렇지 않으면 컨테이너 이미지가 배포되지 않을 수 있습니다. 이 제한사항은 파일 이름에만 적용되며 파일 콘텐츠에 사용되는 문자 인코딩에는 제한사항이 없습니다.

다른 인코딩으로 처리된 파일 이름을 사용하는 경우 배포를 시도하기 전에 파일 이름을 UTF-8로 변환해야 합니다.

아웃바운드 요청 제한 시간

Cloud Run 서비스의 경우 컨테이너에서 VPC로 보내는 요청의 경우 유휴 시간 2분 후에 제한 시간이 발생합니다. 컨테이너에서 인터넷으로 보내는 요청의 경우 유휴 시간 20분 후에 제한 시간이 발생합니다.