Extensible Service Proxy V2 스타트업 옵션

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 구성 플래그는 다음 카테고리로 그룹화할 수 있습니다.

서버리스 외의 구성

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

플래그 설명
--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에 요금이 청구됩니다.

--tracing_sample_rate

trace 샘플링 비율을 0.0에서 1.0 사이의 값으로 설정합니다. 이 값은 샘플링되는 요청 비율을 지정합니다.

기본값은 0.001이며 요청 1,000개 중 1개에 해당합니다.

--tracing_incoming_context

분산 트레이스의 경우 요청 헤더에 트레이스 ID를 지정하는 트레이스 컨텍스트가 포함될 수 있습니다. ESPv2가 새 트레이스 스팬을 만들어 Stackdriver로 전송할 때 트레이스 ID가 사용됩니다. 트레이스 ID를 사용하여 모든 분산 구성 요소의 요청에 대한 모든 트레이스 스팬을 검색할 수 있습니다. 요청에 트레이스 컨텍스트를 지정하지 않고 트레이스를 사용하면 모든 트레이스 스팬에 대해 무작위 트레이스 ID가 생성됩니다.

이 플래그는 공백없이 쉼표로 구분된 플래그 값을 사용하여 trace 컨텍스트를 확인할 HTTP 헤더를 지정합니다 예를 들어 이 플래그를 다음과 같이 설정합니다.

--tracing_incoming_context=x-cloud-trace-context

가능한 값에는 traceparentx-cloud-trace-context가 있습니다.

생략하면 트레이스 컨텍스트가 선택되지 않습니다.

x-cloud-trace-context에 대한 자세한 내용은 이 문제해결 자료를 참조하세요. traceparent에 대한 자세한 내용은 트레이스 컨텍스트 HTTP 헤더 형식을 참조하세요.

--tracing_outgoing_context

Cloud Functions 또는 Cloud Run과 같은 백엔드 서비스로 전송된 요청에서 트레이스 컨텍스트 헤더를 설정합니다. 트레이스 컨텍스트에 대한 자세한 내용은 위의 --tracing_incoming_context 설명을 참조하세요.

이 플래그는 설정할 HTTP 헤더를 공백 없이 쉼표로 플래그 값을 구분하여 지정합니다. 예를 들어 이 플래그를 다음과 같이 설정합니다.

--tracing_outgoing_context=traceparent

가능한 값에는 traceparentx-cloud-trace-context가 있습니다.

생략하면 추적 컨텍스트 헤더가 전송되지 않습니다.

x-cloud-trace-context에 대한 자세한 내용은 이 문제해결 자료를 참조하세요. traceparent에 대한 자세한 내용은 트레이스 컨텍스트 HTTP 헤더 형식을 참조하세요.

디버깅

이러한 플래그를 사용하여 ESPv2의 상태 확인 및 디버깅을 구성할 수 있습니다. 이 플래그는 상태 확인 호출에 응답하도록 상태 핸들러를 설정하거나, Envoy 관리 포트로 구성 및 통계를 가져오거나, Envoy를 디버그 모드에서 실행하여 디버그 수준 정보를 로그에 기록할 수 있습니다.

플래그 설명
-z, --healthz 상태 확인 엔드포인트를 정의합니다. 예를 들어 -z healthz는 ESPv2가 /healthz 경로에 대해 코드 200을 반환하도록 합니다.
--status_port --admin_port 이 포트에서 ESPv2 Envoy 관리를 사용 설정합니다. 자세한 내용은 Envoy 관리 인터페이스 참조를 확인하세요. 관리 포트는 기본적으로 사용 중지되어 있습니다.
--enable_debug 디버그 수준 로그를 사용 설정하고 디버그 헤더를 추가합니다.

GCP 플랫폼 이외 배포

ESPv2가 Google Cloud Platform(GCP)이 아닌 환경에 배포된 경우 다음 플래그가 필요할 수 있습니다.

플래그 설명
--service_account_key

Google 서비스에 액세스할 서비스 계정 키 JSON 파일을 지정합니다. 이 옵션을 생략하면 프록시가 GCP 메타데이터 서버에 접속하여 액세스 토큰을 가져옵니다.

--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입니다. 기본값은 autocode>입니다.
--non_gcp 기본적으로 프록시는 처음 몇 가지 요청 시 GCP 메타데이터 서버로 연결을 시도하여 VM 위치를 가져옵니다. 이 단계를 건너뛰려면 이 플래그를 true로 설정합니다.

클라이언트 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-Allow-Origin의 기본값을 재정의하려면 다음 옵션 중 하나를 지정합니다.

옵션 설명
--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$"

--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"

TLS 지원

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

플래그 설명
--ssl_server_cert_path 프록시의 서버 인증서 경로입니다. 구성된 경우 ESPv2는 listener_port에서 HTTP/1.x 및 HTTP/2 보안 연결만 허용합니다. 이 경로 내의 인증서와 키 파일 'server.crt' 및 'server.key'가 필요합니다.
--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_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입니다.

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_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입니다.

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

다음 단계

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