Extensible Service Proxy V2 스타트업 옵션

OpenAPI | gRPC

Extensible Service Proxy V2 베타(ESPv2 베타)는 Cloud Endpoints가 API 관리 기능을 제공하도록 하는 Envoy 기반 프록시입니다. ESPv2를 구성하려면 ESPv2 서비스를 배포할 때 구성 플래그를 지정하면 됩니다.

구성 플래그 설정

ESPv2 구성 플래그를 설정하는 방법은 다음 섹션에 설명된 대로 배포 플랫폼에 따라 다릅니다.

Compute Engine VM

Compute Engine의 ESPv2 구성 플래그는 docker run 명령어에 지정됩니다. 예를 들면 다음과 같습니다.

sudo docker run \
    --detach \
    DOCKER_ARGUMENTS \
    gcr.io/endpoints-release/endpoints-runtime:2 \
    --service=SERVICE_NAME \
    --rollout_strategy=managed \
    --backend=YOUR_API_CONTAINER_NAME:8080

이 예시에서 --service, --rollout_strategy, --backend는 ESPv2 구성 플래그입니다.

GKE 및 Kubernetes

배포 매니페스트 파일의 args 필드에서 GKE 및 Kubernetes에 대한 구성 플래그를 지정할 수 있습니다. 예를 들면 다음과 같습니다.

containers:
- name: esp
  image: gcr.io/endpoints-release/endpoints-runtime:2
  args: [
    "--listener_port=8081",
    "--backend=127.0.0.1:8080",
    "--service=SERVICE_NAME",
    "--rollout_strategy=managed"
  ]

이 예시에서 --listener_port, --backend, --service, --rollout_strategy는 ESPv2 구성 플래그입니다.

서버리스 플랫폼용 Cloud Run

서버리스용 Cloud Run의 시작 옵션을 지정하려면 ESPv2_ARGS 환경 변수를 사용합니다. 변수는 gcloud run deploy 명령어에서 --set-env-vars 옵션을 사용하여 설정할 수 있습니다.

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

gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=--enable_debug

이 예시에서 --enable_debug는 ESPv2 구성 플래그입니다.

gcloud run deploy 명령어에 대한 자세한 내용은 OpenAPI용 Cloud Functions, OpenAPI용 Cloud Run 또는 gRPC용 Cloud Run을 참조하세요.

ESPv2_ARGS 환경 변수에 여러 인수를 설정하려면 커스텀 구분 기호를 지정하고 이 구분 기호를 사용하여 여러 인수를 구분합니다. 구분 기호로 쉼표를 사용하지 마세요. 캐럿으로 둘러싸인 ESPv2_ARGS 환경 변수의 시작 부분에 커스텀 구분 기호를 배치합니다.

다음 예시에서는 ++를 구분 기호로 사용합니다.

gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=^++^--cors_preset=basic++--cors_allow_origin=your_host.com

설정하는 플래그에 쉼표가 포함되어 있으면 gcloud_build_image 스크립트에서 ESPv2_ARGS 환경 변수를 설정해야 합니다.

예를 들어 --cors_allow_methods=PUT,POST,GET 플래그를 추가하려면 다음 명령어를 실행합니다.

gcloud_build_image 스크립트를 다운로드합니다.

아래에 표시된 대로 gcloud_build_image를 수정합니다.

cat <<EOF > Dockerfile
  FROM BASE_IMAGE

  ENV ENDPOINTS_SERVICE_PATH /etc/endpoints/service.json
  COPY service.json \ENDPOINTS_SERVICE_PATH

  ENV ESPv2_ARGS ^++^--cors_preset=basic++--cors_allow_method="GET,PUT,POST"++--cors_allow_credentials

  ENTRYPOINT ["/env_start_proxy.py"]
  EOF

gcloud_build_image 스크립트를 실행하여 이미지를 빌드합니다.

ESPv2 구성 플래그

ESPv2 구성 플래그는 다음 카테고리로 그룹화할 수 있습니다.

서버리스 외의 구성
로깅
추적
상태 확인
디버깅
로컬 테스트
Google Cloud 외부 배포
클라이언트 IP 추출
CORS 지원
TLS 지원
제한 시간 및 재시도
gRPC 트랜스코딩
요청 및 응답 수정
보안 옵션
JWT 인증

ESPv2 플래그의 추가적인 일반 예시와 도움말 텍스트는 GitHub 저장소에서 찾을 수 있습니다.

서버리스 외의 구성

이러한 플래그는 GKE, Compute Engine, Kubernetes 같은 서버리스 외의 플랫폼에서 ESPv2를 실행하는 데 필요합니다. 서버리스 플랫폼용 Cloud Run에 배포할 때는 이들을 설정할 수 없습니다.

참고: Kubernetes 사용자의 경우 구성 파일에서 필드 값을 따옴표로 묶지 마세요. 예를 들어 --cors_allow_origin="http://example.com"은 원래 의도된 문자열 값 http://example.com 대신 문자열 값 \"http://example.com\"을 cor_allow_origin 필드에 할당합니다.

플래그	설명
`--service`	Endpoints 서비스의 이름을 설정합니다.
`--version`	Endpoints 서비스의 서비스 구성 ID를 설정합니다.
`--rollout_strategy`	서비스 구성 출시 전략인 [fixed\|managed]를 지정합니다. 기본값은 fixed입니다.
`--listener_port`	다운스트림 연결을 수락하는 포트를 식별합니다. HTTP/1.x, HTTP/2, gRPC 연결을 지원합니다. 기본값은 8080입니다.
`--backend`	로컬 백엔드 애플리케이션 서버 주소를 지정합니다. 유효한 스키마는 http, https, grpc, grpcs(포함된 경우)입니다. 기본 스키마는 >http입니다.

로깅

ESPv2를 구성하여 Stackdriver 로그에 추가 정보를 기록하려면 이 플래그를 사용합니다.

플래그	설명
`--log_request_headers`	지정된 요청 헤더의 값을 공백없이 쉼표로 구분하여 기록합니다. 예를 들어 이 플래그를 다음과 같이 설정합니다. `--log_request_headers=foo,bar` 요청에서 "foo" 및 "bar" 헤더 값을 사용할 수 있는 경우 Endpoints 로그에 다음이 포함됩니다. `request_headers: foo=foo_value;bar=bar_value`
`--log_response_headers`	지정된 응답 헤더의 값을 공백없이 쉼표로 구분하여 기록합니다. 예를 들어 이 플래그를 다음과 같이 설정합니다. `--log_response_headers=baz,bing` 응답에서 "baz" 및 "bing" 헤더 값을 사용할 수 있는 경우 Endpoints 로그에 다음이 포함됩니다. `response_headers: baz=baz_value;bing=bing_value`
`--log_jwt_payloads`	지정된 JWT 페이로드 기본 필드의 값을 공백없이 쉼표로 구분하여 기록합니다. 예를 들어 이 플래그를 다음과 같이 설정합니다. `--log_jwt_payload=sub,project_id,foo.foo_name` JWT 페이로드에서 값을 사용할 수 있는 경우 Endpoints 로그에 다음이 포함됩니다. `jwt_payloads: sub=sub_value;project_id=project_id_value; foo.foo_name=foo.foo_name_value` JWT 페이로드의 값은 기본 필드(문자열, 정수)여야 합니다. JSON 객체 및 배열은 기록되지 않습니다.
`--access_log`	이 플래그를 지정하면 로그 항목에 액세스하는 로컬 파일의 경로가 작성됩니다.
`--access_log_format`	액세스 로그의 형식을 지정하는 문자열 형식입니다. 설정하지 않으면 >기본 형식 문자열이 사용됩니다. 자세한 형식 문법은 형식 문자열 참조를 참고하세요.

추적

이러한 플래그를 사용하여 Stackdriver로 전송된 ESPv2 트레이스 데이터를 구성합니다. 이러한 플래그는 추적이 사용 가능한 경우에만 적용됩니다.

플래그	설명
`--disable_tracing`	추적을 사용 중지합니다. 기본적으로 추적은 사용하도록 설정되어 있습니다. 사용하도록 설정하면 ESPv2는 매 초마다 API에 대한 요청 일부를 샘플링하여 Stackdriver Trace로 전송하는 추적을 가져옵니다. 기본적으로 1,000개의 요청 중 1개가 샘플링됩니다. `--tracing_sample_rate` 플래그를 사용하여 샘플링 레이트을 변경합니다.
`--tracing_project_id`	Stackdriver 추적을 위한 Google 프로젝트 ID입니다. 추적은 유료 서비스입니다. 지정된 프로젝트에 추적을 위한 요금이 청구됩니다. 기본적으로 배포된 ESPv2 서비스의 프로젝트 ID에 요금이 청구됩니다. 프로젝트 ID는 시작 시 Google Cloud 인스턴스 메타데이터 서버를 호출하여 결정됩니다. ESPv2가 `--non_gcp`를 사용하여 Google Cloud 외부에 배포되는 경우 이 플래그를 명시적으로 설정하지 않으면 추적은 자동으로 사용 중지됩니다.
`--tracing_sample_rate`	trace 샘플링 레이트을 0.0에서 1.0 사이의 값으로 설정합니다. 이 값은 샘플링되는 요청 비율을 지정합니다. 기본값은 0.001이며 요청 1,000개 중 1개에 해당합니다.
`--tracing_incoming_context`	이 플래그는 공백없이 쉼표로 구분된 플래그 값을 사용하여 trace 컨텍스트를 확인할 HTTP 헤더를 지정합니다 순서가 중요합니다. trace 컨텍스트는 일치하는 첫 번째 헤더에서 파생됩니다. 가능한 값에는 `traceparent`, `x-cloud-trace-context`, `grpc-trace-bin`이 포함됩니다. 생략하면 `traceparent` 및 `x-cloud-trace-context` 헤더가 순서대로 확인됩니다. 자세한 내용은 API 추적을 참조하세요.
`--tracing_outgoing_context`	백엔드 서비스로 전송된 요청의 trace 컨텍스트 헤더를 설정합니다. 이 플래그는 설정할 HTTP 헤더를 공백 없이 쉼표로 플래그 값을 구분하여 지정합니다. 가능한 값에는 `traceparent`, `x-cloud-trace-context`, `grpc-trace-bin`이 포함됩니다. 생략하면 `traceparent` 및 `x-cloud-trace-context` 헤더가 전송됩니다. 자세한 내용은 API 추적을 참조하세요.

상태 확인

이러한 플래그를 사용하여 ESPv2의 상태 확인을 구성합니다. 첫 번째 플래그는 상태 확인 호출에 응답하도록 상태 핸들러를 설정하는 데 사용될 수 있습니다. 다른 플래그는 gRPC 백엔드의 상태 확인을 사용 설정하는 데 사용될 수 있습니다.

/tbody>

플래그	설명
`-z, --healthz`	상태 확인 엔드포인트를 정의합니다. 예를 들어 `-z healthz`는 ESPv2가 `/healthz` 경로에 대해 코드 200을 반환하도록 합니다.
`--health_check_grpc_backend`	ESPv2를 사용 설정하여 정기적으로 `--backend` 플래그로 지정된 백엔드의 gRPC 상태 서비스를 확인합니다. 백엔드는 gRPC 프로토콜을 사용하고 gRPC 상태 확인 프로토콜을 구현해야 합니다. `--healthz` 플래그로 사용 설정된 상태 확인 엔드포인트는 백엔드 상태 확인 결과를 반영합니다.
`--health_check_grpc_backend_service`	백엔드 gRPC 상태 확인 프로토콜을 호출할 때 서비스 이름을 지정합니다. 이 플래그 값은 `--health_check_grpc_backend` 플래그가 사용되는 경우에만 적용됩니다. 선택사항이며 설정하지 않으면 기본값은 비어 있습니다. gRPC 서비스 전체 상태를 쿼리하기 위한 용도로 서비스 이름이 비어 있습니다.
`--health_check_grpc_backend_interval`	백엔드 gRPC 상태 서비스를 호출할 때 확인 간격과 요청 제한 시간을 지정합니다. 이 플래그 값은 `--health_check_grpc_backend` 플래그가 사용되는 경우에만 적용됩니다. 기본값은 1초입니다. 허용되는 형식은 일련의 10진수이며 각각 '5s', '100ms' 또는 '2m'와 같이 소수 값과 단위 서픽스(선택사항)가 포함됩니다. 유효한 시간 단위는 'm'(분), 's'(초), 'ms'(밀리초)입니다.

디버깅

이러한 플래그를 사용하여 ESPv2의 디버깅을 구성합니다. 이 플래그는 Envoy 관리 포트에서 구성과 통계를 가져오도록 설정하거나 Envoy를 디버그 모드에서 실행하여 디버그 수준 정보를 로그에 기록하는 데 사용될 수 있습니다.

플래그	설명
`--status_port` `--admin_port`	이 포트에서 ESPv2 Envoy 관리를 사용 설정합니다. 자세한 내용은 Envoy 관리 인터페이스 참조를 확인하세요. 관리 포트는 기본적으로 사용 중지되어 있습니다.
`--enable_debug`	디버그 수준 로그를 사용 설정하고 디버그 헤더를 추가합니다.

Google Cloud 외부 배포

ESPv2가 Google Cloud 외부 환경에 배포된 경우 다음 플래그가 필요할 수 있습니다.

플래그	설명
`--service_account_key`	Google 서비스에 액세스할 서비스 계정 키 JSON 파일을 지정합니다. 이 옵션을 생략하면 프록시가 Google Cloud 메타데이터 서버에 접속하여 액세스 토큰을 가져옵니다.
`--dns_resolver_addresses`	DNS 리졸버 주소. 각 주소는 `IP_ADDR` 또는 `IP_ADDR:PORT` 형식이어야 하며 세미콜론(;)으로 구분되어야 합니다. `IP_ADDR`에는 기본 DNS 포트 52가 사용됩니다. (예: `--dns_resolver_addresses=127.0.0.1;127.0.0.2;127.0.0.3:8000`) 설정되지 않은 경우 ESPv2는 `/etc/resolv.conf`에 구성된 기본 리졸버를 사용합니다.
`--backend_dns_lookup_family`	모든 백엔드의 DNS 조회 모음을 정의합니다. 옵션은 auto, v4only, v6only, v4preferred, all입니다. 기본값은 v4preferred입니다. auto는 레거시 값입니다. 플래그를 auto로 설정하면 v6preferred와 동일한 동작이 발생합니다.
`--non_gcp`	기본적으로 프록시는 처음 몇 가지 요청 시 Google Cloud 메타데이터 서버로 연결을 시도하여 VM 위치를 가져옵니다. 이 단계를 건너뛰려면 이 플래그를 true로 설정합니다.

로컬 테스트

ESPv2를 워크스테이션에 로컬로 배포하여 테스트할 수 있습니다. 자세한 내용은 로컬 또는 다른 플랫폼에서 ESP 실행을 참조하세요.

지속적 통합에서 로컬 배포 및 테스트를 더 쉽게 수행하려면 Google Cloud 외부 배포 플래그와 함께 이 플래그를 사용하세요.

플래그 설명

플래그	설명
`--service_json_path`	ESPv2의 경로를 지정하여 엔드포인트 서비스 구성을 로드합니다. 이 플래그를 사용하면 ESPv2에서 '고정' 출시 전략을 사용하며 다음 플래그가 무시됩니다. `--service` `--version` `--rollout_strategy` 이 플래그는 ESPv2가 Service Management API 할당량을 사용하지 못하게 합니다.
`--enable_backend_address_override`	서비스 구성에 `--backend` 플래그 또는 `backend.rule.address` 필드를 사용하여 백엔드 주소를 지정할 수 있습니다. OpenAPI 사용자의 경우 `backend.rule.address` 필드는 `x-google-backend` 확장자의 `address` 필드로 설정됩니다. 작업별 `backend.rule.address` 서비스 구성은 일반적으로 서버리스 라우팅에 지정됩니다. 기본적으로 `backend.rule.address`는 각 개별 작업의 `--backend` 플래그보다 우선합니다. `--backend` 플래그를 대신 우선시하려면 이 플래그를 사용 설정합니다. 이는 로컬 워크스테이션에서 개발하는 경우에 유용합니다. 동일한 프로덕션 서비스 구성을 사용할 수 있지만 로컬 테스트를 위해 `--backend` 플래그를 통해 백엔드 주소를 재정의할 수 있습니다. 참고: 주소만 재정의됩니다. `backend.rule`의 다른 모든 구성요소(기한, 백엔드 인증, 경로 변환 등)는 계속 적용됩니다.

--service_json_path

ESPv2의 경로를 지정하여 엔드포인트 서비스 구성을 로드합니다. 이 플래그를 사용하면 ESPv2에서 '고정' 출시 전략을 사용하며 다음 플래그가 무시됩니다.

--service
--version
--rollout_strategy

이 플래그는 ESPv2가 Service Management API 할당량을 사용하지 못하게 합니다.

--enable_backend_address_override

서비스 구성에 --backend 플래그 또는 backend.rule.address 필드를 사용하여 백엔드 주소를 지정할 수 있습니다. OpenAPI 사용자의 경우 backend.rule.address 필드는 x-google-backend 확장자의 address 필드로 설정됩니다.

작업별 backend.rule.address 서비스 구성은 일반적으로 서버리스 라우팅에 지정됩니다. 기본적으로 backend.rule.address는 각 개별 작업의 --backend 플래그보다 우선합니다.

--backend 플래그를 대신 우선시하려면 이 플래그를 사용 설정합니다. 이는 로컬 워크스테이션에서 개발하는 경우에 유용합니다. 동일한 프로덕션 서비스 구성을 사용할 수 있지만 로컬 테스트를 위해 --backend 플래그를 통해 백엔드 주소를 재정의할 수 있습니다.

참고: 주소만 재정의됩니다. backend.rule의 다른 모든 구성요소(기한, 백엔드 인증, 경로 변환 등)는 계속 적용됩니다.

클라이언트 IP 추출

이러한 플래그를 사용하여 ESPv2용 클라이언트 IP 추출을 구성합니다.

플래그	설명
`--envoy_use_remote_address`	Envoy HttpConnectionManager 구성의 자세한 내용은 Envoy 참조 문서를 확인하세요. 기본값은 사용하지 않음으로 설정되어 있습니다.
`--envoy_xff_num_trusted_hops`	Envoy HttpConnectionManager 구성의 자세한 내용은 Envoy 참조 문서를 확인하세요. 기본값은 2입니다.

CORS 지원

사용 가능한 CORS 지원 옵션에 대한 설명은 CORS 지원을 참조하세요. 이 섹션에서는 ESPv2 시작 플래그를 사용하여 CORS 지원을 설명합니다.

ESPv2에서 CORS 지원을 사용하도록 설정하려면 --cors_preset 옵션을 포함하고 다음 플래그 중 하나를 설정합니다.

--cors_preset=basic
--cors_preset=cors_with_regex

--cors_preset=basic 또는 --cors_preset=cors_with_regex를 포함하면 ESPv2입니다.

모든 위치 경로에 동일한 CORS 정책이 있다고 가정합니다.
단순 요청 및 실행 전 HTTP OPTIONS 요청 모두에 응답합니다.
실행 전 OPTIONS 요청의 결과를 최대 20일(1728000초) 동안 캐시에 저장합니다.

응답 헤더를 다음 값으로 설정합니다.

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization
Access-Control-Expose-Headers: Content-Length,Content-Range
Access-Control-Max-Age: 1728000

Access-Control-Allow-Origin의 기본값을 재정의하려면 다음 옵션 중 하나를 지정합니다.

옵션 설명

--cors_allow_origin --cors_preset=basic과 함께 사용하여 Access-Control-Allow-Origin을 특정 원본으로 설정합니다.
예시:
--cors_preset=basic --cors_allow_origin=http://example.com

옵션	설명
`--cors_allow_origin`	`--cors_preset=basic`과 함께 사용하여 `Access-Control-Allow-Origin`을 특정 원본으로 설정합니다. 예시: `--cors_preset=basic --cors_allow_origin=http://example.com`
`--cors_allow_origin_regex`	`--cors_preset=cors_with_regex`와 함께 사용합니다. 정규 표현식을 사용하여 `Access-Control-Allow-Origin`을 설정할 수 있습니다. 예시: `--cors_preset=cors_with_regex --cors_allow_origin_regex=^https?://.+\.example\.com$` 앞의 예시에서 정규 표현식은 http 또는 https로 시작되고 `example.com`의 모든 하위 도메인을 허용합니다. Kubernetes 구성 파일에서 이 옵션을 설정할 때는 백슬래시 문자를 추가하여 문자열에서 \의 두 인스턴스를 모두 이스케이프 처리해야 합니다. 예를 들면 다음과 같습니다. `"--cors_preset","cors_with_regex", "--cors_allow_origin_regex","^https?://.+\\.example\\.com$"` Cloud Run용 gcloud_build_image 스크립트에서 이 옵션을 설정할 때 이스케이프 문자와 백슬래시를 사용하지 않도록 하세요. 시작 시 bash 스크립트에서 프록시로 올바르게 전달되지 않을 수도 있습니다. 메타 시퀀스 대신 문자 클래스를 사용하세요. 예를 들면 다음과 같습니다. `Original: \d Recommended: [0-9]`

--cors_allow_origin_regex

--cors_preset=cors_with_regex와 함께 사용합니다. 정규 표현식을 사용하여 Access-Control-Allow-Origin을 설정할 수 있습니다.
예시:


--cors_preset=cors_with_regex

--cors_allow_origin_regex=^https?://.+\.example\.com$

앞의 예시에서 정규 표현식은 http 또는 https로 시작되고 example.com의 모든 하위 도메인을 허용합니다.

Kubernetes 구성 파일에서 이 옵션을 설정할 때는 백슬래시 문자를 추가하여 문자열에서 \의 두 인스턴스를 모두 이스케이프 처리해야 합니다. 예를 들면 다음과 같습니다.


"--cors_preset","cors_with_regex",

"--cors_allow_origin_regex","^https?://.+\\.example\\.com$"

Cloud Run용 gcloud_build_image 스크립트에서 이 옵션을 설정할 때 이스케이프 문자와 백슬래시를 사용하지 않도록 하세요. 시작 시 bash 스크립트에서 프록시로 올바르게 전달되지 않을 수도 있습니다. 메타 시퀀스 대신 문자 클래스를 사용하세요. 예를 들면 다음과 같습니다. Original: \d Recommended: [0-9]

--cors_preset=basic 또는 --cors_preset=cors_with_regex를 설정하여 CORS를 사용 설정한 후에는 다음 옵션을 한 개 이상 지정하여 다른 응답 헤더의 기본값을 재정의할 수 있습니다.

옵션	설명
`--cors_allow_methods`	`Access-Control-Allow-Methods`를 지정된 HTTP 메서드로 설정합니다. 각 HTTP 메서드를 쉼표로 구분하여 문자열로 HTTP 메서드를 지정합니다. 예: `--cors_preset=basic --cors_allow_methods=GET,POST,PUT,OPTIONS`
`--cors_allow_headers`	`Access-Control-Allow-Headers`를 지정된 HTTP 헤더로 설정합니다. 각 HTTP 헤더를 쉼표로 구분하여 HTTP 헤더를 문자열로 지정합니다. 예: `--cors_preset=basic --cors_allow_headers=Origin,Content-Type,Accept`
`--cors_allow_credentials`	응답에 true 값이 있는 `Access-Control-Allow-Credentials` 헤더를 포함합니다. 기본적으로 `Access-Control-Allow-Credentials` 헤더는 응답에 포함되지 않습니다. 예시: `--cors_preset=basic --cors_allow_credentials`
`--cors_expose_headers`	`Access-Control-Expose-Headers`를 지정된 헤더로 설정합니다. 각 헤더를 쉼표로 구분하여 응답의 일부로 공개할 수 있는 헤더를 문자열로 지정합니다. 예: `--cors_preset=basic --cors_expose_headers=Content-Length`
`--cors_max_age`	`Access-Control-Max-Age`를 지정된 기간으로 설정합니다. 허용되는 형식은 일련의 10진수이며 각각 '300m', '1.5h' 또는 '2h45m'과 같이 소수 값과 단위 서픽스(선택사항)가 포함됩니다. 유효한 시간 단위는 'm'(분), 'h'(시간)입니다. 설정하지 않을 경우 기본값은 '480h'입니다. 예: `--cors_preset=basic --cors_max_age=24h`

TLS 지원

이러한 플래그를 사용하여 TLS 연결을 사용하도록 ESPv2를 구성합니다.

플래그	설명
`--ssl_server_cert_path`	프록시의 서버 인증서 경로입니다. 구성된 경우 ESPv2는 listener_port에서 HTTP/1.x 및 HTTP/2 보안 연결만 허용합니다. 이 경로 내의 인증서와 키 파일 'server.crt' 및 'server.key'가 필요합니다.
`--ssl_server_cipher_suites`	다운스트림 연결에 사용할 암호화 스위트(쉼표로 구분된 목록으로 지정). 암호화 스위트 구성을 참조하세요.
`--ssl_backend_client_cert_path`	프록시의 클라이언트 인증서 경로입니다. 구성된 경우 ESPv2는 HTTPS 백엔드에 TLS 상호 인증을 사용 설정합니다. 이 경로 내의 인증서와 키 파일 'client.crt' 및 'client.key'가 필요합니다.
`--ssl_backend_client_root_certs_file`	ESPv2가 백엔드 서버 인증서를 확인하는 데 사용하는 루트 인증서의 파일 경로입니다. 지정하지 않으면 ESPv2가 기본적으로 '/etc/ssl/certs/ca-certificates.crt'를 사용합니다.
`--ssl_backend_client_cipher_suites`	HTTPS 백엔드에 사용할 암호화 스위트(쉼표로 구분된 목록으로 지정). 암호화 스위트 구성을 참조하세요.
`--ssl_minimum_protocol`	클라이언트 측 연결을 위한 최소 TLS 프로토콜 버전입니다. 여기를 참조하세요.
`--ssl_maximum_protocol`	클라이언트 측 연결의 최대 TLS 프로토콜 버전입니다. 여기를 참조하세요.
`--enable_strict_transport_security`	HSTS(HTTP Strict Transport Security)를 사용 설정합니다. 'Strict-Transport-Security' 응답 헤더 값이 'max-age=31536000; includeSubdomains'인 경우 모든 응답에 추가됩니다.
`--generate_self_signed_cert`	시작할 때 자체 서명 인증서 및 키를 생성한 다음 '/tmp/ssl/endpoints/server.crt' 및 '/tmp/ssl/endpoints/server.key'에 저장합니다. 이 방법은 HTTPS 요청을 처리하기 위한 임의의 자체 서명 인증서가 필요할 경우에만 유용합니다. 생성된 인증서는 일반 이름 'localhost'를 가지며 10년 동안 유효합니다.

제한 시간 및 재시도

이러한 플래그를 사용하여 ESPv2에서 원격 HTTP 호출 제한 시간 및 재시도를 구성합니다.

플래그	설명
`--http_request_timeout_s`	백엔드 및 Google Service Control을 제외한 외부 서비스에 대한 요청의 제한 시간을 초 단위로 설정합니다. 여기에는 Google ServiceManagement, 메타데이터 서버, Google IAM 서버가 포함됩니다. > 0이어야 하며 설정되지 않은 경우 기본값은 30초입니다.
`--service_control_network_fail_open`	Google Service Control에 연결할 때 네트워크 장애가 발생하는 경우 이 플래그가 사용 설정되어 있으면 요청이 허용됩니다. 기본값은 사용입니다.
`--service_control_check_timeout_ms`	서비스 제어 검사 요청에 대한 제한 시간을 밀리초 단위로 설정합니다. > 0이어야 하며 설정하지 않은 경우 기본값은 1000입니다.
`--service_control_report_timeout_ms`	서비스 제어 보고서 요청에 대한 제한 시간을 밀리초 단위로 설정합니다. > 0이어야 하며 설정하지 않은 경우 기본값은 1000입니다.
`--service_control_quota_timeout_ms`	서비스 제어 할당량 요청의 제한 시간을 밀리초 단위로 설정합니다. > 0이어야 하며 설정하지 않은 경우 기본값은 1000입니다.
`--service_control_check_retries`	서비스 제어 확인 요청의 재시도 시간을 설정합니다. >= 0이어야 하며 설정하지 않은 경우 기본값은 3입니다.
`--service_control_report_retries`	서비스 제어 보고 요청의 재시도 시간을 설정합니다. >= 0이어야 하며 설정하지 않은 경우 기본값은 5입니다.
`--service_control_quota_retries`	서비스 제어 할당량 요청의 재시도 시간을 설정합니다. >= 0이어야 하며 설정하지 않은 경우 기본값은 1입니다.
`--backend_retry_ons`	ESPv2가 백엔드에서 재시도하는 조건입니다. 쉼표로 구분된 목록을 사용하여 하나 이상의 `retryOn` 조건을 지정할 수 있습니다. 기본값은 `reset,connect-failure,refused-stream`입니다. 이 플래그를 빈 값으로 설정하여 재시도를 중지합니다. 허용되는 조건은 다음 링크를 참조하세요. x-envoy-retry-on x-envoy-retry-grpc-on
`--backend_retry_num`	허용된 재시도 횟수입니다. >= 0이어야 하며 기본값은 1입니다.

gRPC 트랜스코딩

이러한 플래그를 사용하여 HTTP/JSON용 ESPv2를 gRPC 트랜스코딩으로 구성합니다.

플래그	설명
`--transcoding_always_print_primitive_fields`	grpc-json 트랜스코딩을 위한 기본 필드를 인쇄할지 여부를 지정합니다. 기본적으로 기본값을 사용하는 기본 필드는 JSON 출력에서 생략됩니다. 예를 들어 0으로 설정된 int32 필드는 생략됩니다. 이 플래그를 true로 설정하면 기본값과 관계없이 기본 동작을 재정의하고 기본 필드가 인쇄됩니다. 기본값은 false입니다.
`--transcoding_always_print_enums_as_ints`	grpc-json 트랜스코딩을 위한 열거형을 int로 인쇄할지 지정합니다. 기본적으로 문자열로 렌더링됩니다. 기본값은 false입니다.
`--transcoding_stream_newline_delimited`	true인 경우 새 줄 구분 기호를 사용하여 응답 스트리밍 메시지를 구분합니다. false인 경우 모든 응답 스트리밍 메시지가 JSON 배열로 트랜스코딩됩니다.
`--transcoding_case_insensitive_enum_parsing`	일반적으로 JSON에서 사용할 때 proto enum 값은 대문자여야 합니다. JSON 요청에서 대문자가 아닌 열거형 값을 사용하는 경우 이 플래그를 true로 설정합니다.
`--transcoding_preserve_proto_field_names`	grpc-json 트랜스코딩을 위한 proto 필드 이름을 보존할지 여부를 지정합니다. 기본적으로 protobuf는 json_name 옵션 또는 더 낮은 카멜 표기법의 순서를 사용하여 JSON 필드 이름을 생성합니다. 이 플래그를 설정하면 원래 필드 이름이 유지됩니다. 기본값은 false입니다.
`--transcoding_ignore_query_parameters`	grpc-json 트랜스코딩의 트랜스코딩 메서드 매핑에서 무시할 쉼표로 구분된 쿼리 매개변수 목록입니다. 기본적으로 트랜스코더 필터는 알 수 없거나 잘못된 쿼리 매개변수가 있는 요청을 트랜스코딩하지 않습니다.
`--transcoding_ignore_unknown_query_parameters`	grpc-json 트랜스코딩의 해당 protobuf 필드에 매핑할 수 없는 쿼리 매개변수를 무시할지 여부를 지정합니다. 쿼리 매개변수를 제어할 수 없고 미리 알지 못하는 경우 이 매개변수를 사용합니다. 그렇지 않은 경우 `--transcoding_ignore_query_parameters`를 사용합니다. 기본값은 false입니다.
`--transcoding_query_parameters_disable_unescape_plus`	기본적으로 쿼리 매개변수의 더하기 기호 `"+"`는 grpc-json 트랜스코딩의 공간 `" "`로 이스케이프되지 않습니다. 이는 HTML 2.0을 지원하기 위한 것입니다. 원하지 않는 경우 이 플래그를 true로 설정하여 이 기능을 중지합니다.

요청 및 응답 수정

요청 및 응답을 부분적으로 수정하도록 ESPv2를 구성하려면 이 플래그를 사용합니다.

플래그	설명
`--add_request_header`	HTTP 헤더를 업스트림 백엔드로 보내기 전에 요청에 추가합니다. 헤더가 이미 요청에 있으면 해당 값이 새 헤더로 바뀝니다. Envoy 커스텀 변수를 지원합니다. 이 인수를 여러 번 반복하여 여러 헤더를 지정할 수 있습니다. 예를 들면 다음과 같습니다. `--add_request_header=key1=value1 --add_request_header=key2=value2`.
`--append_request_header`	요청을 업스트림 백엔드로 보내기 전에 요청에 HTTP 헤더를 추가합니다. 헤더가 이미 요청에 있는 경우 새 값이 추가됩니다. Envoy 커스텀 변수를 지원합니다. 이 인수를 여러 번 반복하여 여러 헤더를 지정할 수 있습니다. 예를 들면 다음과 같습니다. `--append_request_header=key1=value1 --append_request_header=key2=value2`.
`--add_response_header`	HTTP 헤더를 다운스트림 클라이언트에 보내기 전에 응답에 추가합니다. 이미 응답에 있는 헤더는 새 헤더로 교체됩니다. Envoy 커스텀 변수를 지원합니다. 이 인수를 여러 번 반복하여 여러 헤더를 지정할 수 있습니다. 예를 들면 다음과 같습니다. `--add_response_header=key1=value1 --add_response_header=key2=value2`.
`--append_response_header`	HTTP 헤더를 다운스트림 클라이언트에 보내기 전에 응답에 추가합니다. 헤더가 이미 응답에 있는 경우, 새 헤더가 추가됩니다. Envoy 커스텀 변수를 지원합니다. 이 인수를 여러 번 반복하여 여러 헤더를 지정할 수 있습니다. 예를 들면 다음과 같습니다. `--append_response_header=key1=value1 --append_response_header=key2=value2`.

보안 옵션

이러한 플래그를 사용하여 ESPv2에서 허용하는 요청을 더욱 세분화할 수 있습니다.

플래그	설명
`--underscores_in_headers`	밑줄이 포함된 헤더 이름을 통과하도록 허용합니다. 기본값은 false입니다. RFC-7230은 헤더 이름에 밑줄 문자 사용을 허용합니다. 하지만 일부 시스템에서는 `_`와 `-`를 서로 교환 가능한 것으로 취급하기 때문에 이 동작은 보안 조치로 구현됩니다.
`--envoy_connection_buffer_limit_bytes`	각 요청/응답 본문에 버퍼링되는 최대 데이터 양(바이트)을 구성합니다. 설정하지 않으면 Envoy에서 기본값을 결정합니다. Envoy의 리스너 구성을 참조하세요.
`--disable_normalize_path`	RFC 3986에 따라 `path` HTTP 헤더의 정규화를 사용 중지합니다. 백엔드가 기본적으로 경로 정규화를 수행하는 경우 이 옵션을 사용 설정하는 것이 좋습니다. 다음 표에는 이 플래그의 구성에 따라 백엔드가 ESPv2에서 수신하는 `path` 요청의 예시가 나와 있습니다. ----------------------------------------------------------------- \| Request Path \| Without Normalization \| With Normalization \| ----------------------------------------------------------------- \| /hello/../world \| Rejected \| /world \| \| /%4A \| /%4A \| /J \| \| /%4a \| /%4a \| /J \| ----------------------------------------------------------------- 기본적으로 ESPv2는 경로를 정규화합니다. 트래픽이 이 동작에 영향을 받는 경우에만 이 기능을 사용 중지합니다. 참고: RFC 3986에 따라 이 옵션은 퍼센트로 인코딩된 슬래시 문자를 이스케이프 해제하지 않습니다. 이 규정 미준수 동작을 사용 설정하려면 `--disallow_escaped_slashes_in_path` 플래그를 참조하세요. 참고: 이 옵션을 사용 설정해도 RFC 3986의 케이스 정규화는 지원되지 않습니다. 자세한 내용은 경로 템플릿 이해를 참조하세요.
`--disable_merge_slashes_in_path`	`path` HTTP 헤더에서 인접한 슬래시 병합을 사용 중지합니다. 백엔드가 기본적으로 병합을 수행하는 경우 이 옵션을 사용 설정하는 것이 좋습니다. 다음 표에는 이 플래그의 구성에 따라 백엔드가 ESPv2에서 수신하는 `path` 요청의 예시가 나와 있습니다. ----------------------------------------------------------------- \| Request Path \| Without Normalization \| With Normalization \| ----------------------------------------------------------------- \| /hello//world \| Rejected \| /hello/world \| \| /hello/// \| Rejected \| /hello \| ----------------------------------------------------------------- 기본적으로 ESPv2는 슬래시를 병합합니다. 트래픽이 이 동작에 영향을 받는 경우에만 이 기능을 사용 중지합니다. 자세한 내용은 경로 템플릿 이해를 참조하세요.
`--disallow_escaped_slashes_in_path`	이스케이프 처리된 퍼센트 인코딩 슬래시 문자가 있는 요청을 허용하지 않습니다. `%2F` 또는 `%2f`는 `/`로 취급됩니다. `%5C` 또는 `%5c`는 `\`로 취급됩니다. 사용 설정되면 동작은 사용된 프로토콜에 따라 달라집니다. OpenAPI 백엔드의 경우 이스케이프 처리된 퍼센트 인코딩 슬래시가 있는 요청 경로는 리디렉션을 통해 자동으로 이스케이프 해제됩니다. gRPC 백엔드의 경우 이스케이프 처리된 퍼센트 인코딩 슬래시가 있는 요청 경로는 거부됩니다(gRPC는 리디렉션을 지원하지 않음). 이 옵션은 RFC 3986을 준수하지 않으므로 기본적으로 사용 중지되어 있습니다. 백엔드가 RFC 3986을 준수하지 않고 슬래시를 이스케이프 처리하는 경우 ESPv2에서 이 옵션을 사용 설정해야 합니다. 이렇게 하면 보안 요구사항이 적용되지 않아 발생하는 경로 혼동 공격을 방지할 수 있습니다. 자세한 내용은 경로 템플릿 이해를 참조하세요.

JWT 인증

이러한 플래그를 사용하여 재시도를 통해 원격 Jwks를 가져오도록 ESPv2를 구성합니다.

플래그	설명
`--jwks_fetch_num_retries`	원격 JWKS 가져오기 재시도 정책에 재시도 횟수를 지정합니다. 기본값은 0이며 재시도하지 않습니다.
`--jwks_fetch_retry_back_off_base_interval_ms`	JWKS 가져오기 재시도 지수 백오프 기본 간격(밀리초)을 지정합니다. 설정하지 않은 경우 기본값은 200밀리초입니다.
`--jwks_fetch_retry_back_off_max_interval_ms`	JWKS 가져오기 재시도 지수 백오프 최대 간격(밀리초)을 지정합니다. 설정하지 않은 경우 기본값은 32초입니다.
`--jwks_cache_duration_in_s`	JWT 공개 키 캐시 기간을 초 단위로 지정합니다. 설정하지 않으면 기본값은 5분입니다.
`--jwks_async_fetch_fast_listener`	`--disable_jwks_async_fetch` 플래그가 설정되지 않은 경우에만 적용됩니다. 이 플래그는 ESPv2가 리스너 포트를 바인딩하기 전에 초기 `jwks` 가져오기가 완료될 때까지 기다릴 것인지 여부를 결정합니다. false이면 대기합니다. 기본값은 false입니다.
`--jwt_cache_size`	고유한 JWT 토큰 수를 최대 JWT 캐시 크기로 지정합니다. 캐시에는 확인된 토큰만 저장됩니다. 0이면 JWT 캐시가 사용 중지됩니다. 이 플래그는 JWT 캐시의 메모리 사용량을 제한합니다. 사용된 캐시 메모리는 토큰당 대략(토큰 크기 + 64바이트)입니다. 지정되지 않은 경우 기본값은 100000입니다.
`--disable_jwt_audience_service_name_check`	일반적으로 JWT `aud` 필드는 OpenAPI `x-google-audiences` 필드에 지정된 대상에 대해 확인됩니다. 이 플래그는 `x-google-audiences` 필드가 지정되지 않은 경우 동작을 변경합니다. `x-google-audiences` 필드가 지정되지 않고 이 플래그를 사용하지 않는 경우 서비스 이름이 JWT `aud` 필드를 확인하는 데 사용됩니다. 이 플래그를 사용하면 JWT `aud` 필드가 확인되지 않습니다.

다음 단계

다음 사항에 대해 알아보세요.