컨테이너 런타임 계약

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

지원 언어 및 이미지

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

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

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

다중 아키텍처 이미지를 배포하는 경우 매니페스트 목록에 linux/amd64가 포함되어야 합니다.

Cloud Run으로 배포된 함수의 경우 Google Cloud 빌드팩에서 게시한 Cloud Run 런타임 기본 이미지 중 하나를 사용하여 자동 보안 및 유지보수 업데이트를 받을 수 있습니다. 지원되는 런타임은 런타임 지원 일정을 참고하세요.

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

Cloud Run 서비스는 Cloud Run 인스턴스를 시작하여 들어오는 요청을 처리합니다. Cloud Run 인스턴스에는 항상 요청을 리슨하는 단일 인그레스 컨테이너 하나가 포함되며 필요한 경우 사이드카 컨테이너 하나 이상이 포함됩니다. 다음 포트 구성 세부정보는 사이드카가 아닌 인그레스 컨테이너에만 적용됩니다.

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

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

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 서비스 응답에 Set-Cookie 헤더가 포함되어 있으면 Cloud Run은 응답이 캐시되지 않도록 Cache-Control 헤더를 private으로 설정합니다. 이렇게 하면 다른 사용자가 쿠키를 검색할 수 없습니다.

환경 변수

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

서비스에 대한 환경 변수

다음 환경 변수는 PORT를 제외한 실행 중인 모든 컨테이너에 자동으로 추가됩니다. PORT 변수는 인그레스 컨테이너에만 추가됩니다.

이름	설명	예
`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씩 증분하며, 최대 태스크 수에서 1을 뺀 값까지 증가합니다. `--parallelism`을 1보다 크게 설정하면 태스크가 색인 순서를 따르지 않을 수 있습니다. 예를 들어 태스크 2가 태스크 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 서비스는 모든 수신 요청, 이벤트, CPU 사용률을 처리하는 데 필요한 인스턴스 수에 맞게 자동으로 확장됩니다.

모든 인스턴스는 고정된 수의 컨테이너(인그레스 컨테이너 한 개 및 원하는 경우 사이드카 컨테이너 한 개 이상)를 실행합니다.

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

시작

Cloud Run 서비스의 경우 인스턴스는 시작 후 4분 이내에 요청을 리슨해야 하고 인스턴스 내의 모든 컨테이너가 정상이어야 합니다. 이 시작 시간 동안 인스턴스에는 CPU가 할당됩니다. 시작 CPU 부스트를 사용 설정하면 시작 지연 시간을 줄이기 위해 인스턴스 시작 중에 CPU 할당을 일시적으로 늘릴 수 있습니다.

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

인스턴스를 기다리는 요청은 다음과 같이 큐에서 대기 상태로 유지됩니다.

수평 확장 시와 같이 새 인스턴스가 시작되는 경우 요청은 최소한 이 서비스의 컨테이너 인스턴스 평균 시작 시간만큼 대기합니다. 여기에는 0에서 확장하는 경우와 같이 요청이 수평 확장을 시작하는 경우가 포함됩니다.
시작 시간이 10초 미만이면 요청이 최대 10초 동안 대기합니다.
시작 프로세스에 인스턴스가 없고 요청이 수평 확장을 시작하지 않은 경우 요청은 최대 10초 동안 대기합니다.

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

멀티 컨테이너 인스턴스로 구성된 Cloud Run 서비스의 경우 컨테이너 시작 순서를 구성하여 인스턴스 내에서 컨테이너가 시작되는 순서를 지정할 수 있습니다.

요청 처리

Cloud Run 서비스의 경우 Cloud Run 버전이 요청을 하나 이상 처리하는 한 CPU가 항상 인스턴스 내 사이드카를 포함하는 모든 컨테이너에 할당됩니다.

유휴 상태

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

유휴 상태의 인스턴스에 있는 모든 컨테이너에 할당되는 CPU는 구성된 CPU 할당에 따라 달라집니다.

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

종료

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

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

강제 종료

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

작업

Cloud Run 작업의 경우 컨테이너 인스턴스는 컨테이너 인스턴스가 종료될 때까지, 또는 태스크 시간 제한에 도달하거나 컨테이너가 비정상 종료될 때까지 실행됩니다.

강제 종료

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

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

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

SIGTERM 신호를 포착하는 방법은 SIGTERM 코드 샘플을 참조하세요.

컨테이너 인스턴스 리소스

CPU

인스턴스의 각 Cloud Run 컨테이너에는 기본적으로 구성된 vCPU가 할당됩니다(기본 1개). 각 컨테이너에 개별적으로 CPU 한도를 구성할 수 있습니다.

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

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

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

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

시작 CPU 부스트를 사용 설정하면 시작 지연 시간을 줄이기 위해 인스턴스 시작 중에 CPU 할당을 일시적으로 늘릴 수 있습니다.

메모리

각 Cloud Run 컨테이너에는 기본적으로 구성된 메모리가 할당됩니다(기본적으로 512MiB). 각 컨테이너에 개별적으로 메모리 한도를 구성할 수 있습니다.

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

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

GPU

Cloud Run 인스턴스에서 GPU에 액세스하도록 컨테이너를 구성할 수 있습니다. Cloud Run 서비스가 사이드카 컨테이너로 배포된 경우 배포의 컨테이너 하나만 GPU에 액세스할 수 있습니다. 요구사항 및 세부정보는 GPU 구성을 참조하세요.

NVIDIA 라이브러리

기본적으로 모든 NVIDIA L4 드라이버 라이브러리가 /usr/local/nvidia/lib64 아래에 마운트됩니다.

서비스에서 제공된 라이브러리를 찾을 수 없으면 Dockerfile에 ENV LD_LIBRARY_PATH /usr/local/nvidia/lib64:${LD_LIBRARY_PATH} 줄을 추가하여 동적 링커의 검색 경로를 업데이트합니다.

기존 이미지가 있고 업데이트된 Dockerfile로 이미지를 다시 빌드하고 싶지 않은 경우 LD_LIBRARY_PATH를 Cloud Run 서비스의 환경 변수로 설정할 수도 있습니다.

12.2보다 높은 CUDA 버전을 사용하려면 가장 쉬운 방법은 이후 버전과의 호환성 패키지가 이미 설치된 최신 NVIDIA 기본 이미지를 사용하는 것입니다. 또 다른 방법은 수동으로 NVIDIA 이후 버전과의 호환성 패키지를 설치하고 LD_LIBRARY_PATH에 추가하는 것입니다. NVIDIA의 호환성 매트릭스를 참고하여 제공된 NVIDIA 드라이버 버전(535.129.03)과 이후 버전이 호환되는 CUDA 버전을 확인합니다.

동시 실행(서비스)

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

컨테이너 샌드박스

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

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

2세대 실행 환경은 별도의 프로세스 네임스페이스에서 서비스 코드를 실행하므로 특수한 프로세스 시맨틱스를 갖는 컨테이너 init 프로세스로 시작됩니다. 1세대 실행 환경에서는 서비스 코드가 컨테이너 init 프로세스로 실행되지 않습니다.

인스턴스 메타데이터 서버

Cloud Run 인스턴스는 프로젝트 ID, 리전, 인스턴스 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 서비스나 작업의 서비스 ID 이메일입니다.
`/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 호환 파일 이름이 있는 머신에서 Docker 빌드를 실행하고 UTF-8과 호환되지 않는 이름이 포함된 컨테이너에 파일을 복사하지 마세요.

파일 이름이 UTF-8과 호환되지 않으면 컨테이너 배포가 실패합니다. 파일 내에서 사용하는 문자 인코딩에는 제한이 없습니다.

아웃바운드 연결

아웃바운드 요청 제한 시간

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

아웃바운드 연결 재설정

컨테이너에서 VPC 및 인터넷으로의 연결 스트림은 기본 인프라가 다시 시작되거나 업데이트될 때 종료될 수 있습니다. 애플리케이션이 장기적으로 지속되는 연결을 재사용하는 경우 끊어진 연결을 재사용하지 않도록 연결을 다시 설정하도록 애플리케이션을 구성하는 것이 좋습니다.