Extensible Service Proxy(ESP)는 Cloud Endpoints에 API 관리 기능을 제공하는 NGINX 기반 프록시입니다. ESP Docker 컨테이너를 시작할 때 옵션을 지정하여 ESP를 구성합니다. ESP 컨테이너가 시작되면 start_esp라는 스크립트를 실행합니다. 이 스크립트는 지정된 옵션을 사용하여 NGINX 구성 파일을 작성하고 ESP를 시작합니다.
docker run 명령어에서 ESP 시작 옵션을 지정합니다. 예를 들면 다음과 같습니다.
ESP 버전 1.7.0 이상에서 사용할 수 있습니다. managed 또는 fixed를 지정합니다. --rollout_strategy=managed 옵션은 ESP가 배포된 최신 서비스 구성을 사용하도록 구성합니다. 이 옵션을 지정하면 새 서비스 구성을 배포하고 최대 5분 후 ESP가 변경사항을 감지하고 자동으로 사용하기 시작합니다. ESP에 사용할 특정 구성 ID 대신 이 옵션을 지정하는 것이 좋습니다.
--rollout_strategy를 managed로 설정할 경우에는 --version 옵션을 지정할 필요가 없습니다.
-v CONFIG_ID
--version CONFIG_ID
ESP에서 사용할 서비스 구성 ID를 설정합니다. 이 옵션을 설정하는 데 필요한 정보는 서비스 이름 및 구성 ID 가져오기를 참조하세요.
--rollout_strategy=fixed을 지정하거나 --rollout_strategy 옵션을 포함하지 않는 경우에는 --version 옵션을 포함하고 구성 ID를 지정해야 합니다. 이 경우 새 Endpoints 구성을 배포할 때마다 새 구성 ID로 ESP를 다시 시작해야 합니다.
-p HTTP1_PORT
--http_port HTTP1_PORT
ESP가 HTTP/1.x 연결에 노출할 포트를 설정합니다.1
-P HTTP2_PORT
--http2_port HTTP2_PORT
ESP가 HTTP/2 연결에 노출할 포트를 설정합니다.1
-S SSL_PORT
--ssl_port SSL_PORT
ESP가 HTTPS 연결에 노출할 포트를 설정합니다.1
-a BACKEND
--backend BACKEND
HTTP/1.x 애플리케이션 백엔드 서버의 주소를 설정합니다. 백엔드 주소의 기본값은 http://127.0.0.1:8081입니다.
프로토콜 프리픽스를 다음과 같이 지정할 수 있습니다. --backend=https://127.0.0.1:8000
프로토콜 프리픽스를 지정하지 않으면 기본값은 http입니다.
백엔드 서버가 컨테이너의 Compute Engine에서 실행 중인 경우 컨테이너 이름과 포트를 다음과 같이 지정할 수 있습니다. --backend=my-api-container:8000
백엔드가 gRPC 트래픽을 수락하도록 지정하려면 grpc:// 프리픽스를 추가합니다. 예를 들면 다음과 같습니다. --backend=grpc://127.0.0.1:8000
백엔드 서버가 컨테이너의 Compute Engine에서 실행 중이며 gRPC 트래픽을 허용하는 경우 컨테이너 이름과 포트를 다음과 같이 지정할 수 있습니다. --backend=grpc://my-api-container:8000
-N STATUS_PORT
--status_port STATUS_PORT
상태 포트를 설정합니다(기본값: 8090).
없음
--disable_cloud_trace_auto_sampling
기본적으로 ESP에서 Cloud Trace로 1,000개의 요청마다 1개 또는 매 10초마다 1개씩 샘플링하도록 설정되어 있습니다. 이러한 자동 샘플링을 사용하지 않으려면 이 플래그를 설정합니다. Cloud Trace는 이 플래그 값과 관계없이 trace 컨텍스트를 사용하여 요청 HTTP 헤더에서 계속 사용 설정될 수 있습니다. 자세한 내용은 API 추적을 참조하세요.
-n NGINX_CONFIG
--nginx_config NGINX_CONFIG
커스텀 NGINX 구성 파일의 위치를 설정합니다. 이 옵션을 지정하면 ESP는 지정된 구성 파일을 가져온 후 제공된 커스텀 구성 파일을 사용하여 즉시 NGINX를 시작합니다.
자세한 내용은 GKE에 커스텀 nginx 구성 사용을 참조하세요.
-k SERVICE_ACCOUNT_KEY
--service_account_key SERVICE_ACCOUNT_KEY
서비스 계정 사용자 인증 정보 JSON 파일을 설정합니다. 서비스 계정이 제공되는 경우 ESP는 이 계정을 통해 액세스 토큰을 생성하여 Service Infrastructure API를 호출합니다.
이 옵션은 ESP가 로컬 데스크톱, Kubernetes, 다른 클라우드 제공업체와 같이 Google Cloud 이외의 플랫폼에서 실행될 때만 지정해야 합니다. 자세한 내용은 서비스 계정 만들기를 참조하세요.
-z HEALTHZ_PATH
--healthz HEALTHZ_PATH
애플리케이션 백엔드와 동일한 포트에서 상태 확인 엔드포인트를 정의합니다. 예를 들어 -z healthz는 요청을 백엔드로 전달하는 대신 ESP에서 /healthz 위치에 대해 코드 200을 반환하도록 합니다. 기본 값은 사용하지 않음입니다.
없음
--dns DNS_RESOLVER
DNS 리졸버를 지정합니다. 예를 들어 --dns 169.254.169.254는 GCP 메타데이터 서버를 DNS 리졸버로 사용합니다. 지정되지 않은 경우 기본값은 8.8.8.8입니다.
1 이러한 포트는 선택사항이며 서로 구분되어야 합니다.
포트 옵션을 하나도 지정하지 않으면 ESP는 포트 8080에서 HTTP/1.x 연결을 허용합니다.
HTTPS 연결의 경우 ESP는 TLS 보안 비밀이 /etc/nginx/ssl/nginx.crt 및 /etc/nginx/ssl/nginx.key에 있을 것으로 예상합니다.
샘플 명령줄 호출
다음 예시에서는 몇 가지 명령줄 인수를 사용하는 방법을 보여줍니다.
HTTP/1.x 포트 80 및 HTTPS 포트 443에서 들어오는 요청을 처리하고 127.0.0.1:8000에서 API 백엔드에 요청을 전송하도록 ESP를 시작하려면 다음 명령어를 사용합니다.
서비스 계정의 비공개 키와 커스텀 NGINX 구성 파일이 포함된 JSON 파일을 ESP의 Docker 컨테이너 안의 볼륨으로 마운트하려면 Docker 플래그 --volume 또는 --mount를 사용해야 합니다. 위 예시에서는 로컬 컴퓨터의 $HOME/Downloads 디렉터리를 컨테이너의 esp 디렉터리로 매핑합니다. 서비스 계정의 비공개 키 파일을 저장하면 일반적으로 Downloads 디렉터리로 다운로드됩니다. 원할 경우 비공개 키 파일을 다른 디렉터리에 복사할 수 있습니다. 자세한 내용은 Docker의 데이터 관리를 참조하세요.
ESP에 CORS 지원 추가
사용 가능한 CORS 지원 옵션에 대한 설명은 CORS 지원을 참조하세요. 이 섹션에서는 ESP 시작 플래그를 사용하여 CORS 지원을 설명합니다.
ESP에서 CORS 지원을 사용하려면 --cors_preset 옵션을 포함하고 basic 또는 cors_with_regex로 설정합니다. --cors_preset=basic 또는 --cors_preset=cors_with_regex를 포함할 때 ESP가 다음과 같이 동작합니다.
--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의 모든 하위 도메인인 원본을 허용합니다.
--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
ESP CORS 시작 옵션이 애플리케이션의 요구사항에 맞지 않으면 애플리케이션에 필요한 CORS 지원이 포함된 커스텀 nginx.conf 파일을 만들 수 있습니다. 자세한 내용은 CORS를 지원하는 커스텀 nginx.conf 만들기를 참조하세요.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2024-12-21(UTC)"],[[["\u003cp\u003eThe Extensible Service Proxy (ESP) is an NGINX-based proxy used with Cloud Endpoints for API management, configured via startup options when launching its Docker container.\u003c/p\u003e\n"],["\u003cp\u003eESP startup options, like \u003ccode\u003e--service\u003c/code\u003e, \u003ccode\u003e--rollout_strategy\u003c/code\u003e, and \u003ccode\u003e--backend\u003c/code\u003e, are specified in the \u003ccode\u003edocker run\u003c/code\u003e command or the Kubernetes deployment manifest's \u003ccode\u003eargs\u003c/code\u003e field, defining the behavior of the proxy.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003e--rollout_strategy=managed\u003c/code\u003e option is recommended as it allows ESP to automatically use the latest deployed service configuration without requiring a specific configuration ID.\u003c/p\u003e\n"],["\u003cp\u003eCORS support can be enabled in ESP using \u003ccode\u003e--cors_preset=basic\u003c/code\u003e or \u003ccode\u003e--cors_preset=cors_with_regex\u003c/code\u003e, allowing for configuration of \u003ccode\u003eAccess-Control-Allow-Origin\u003c/code\u003e and other related headers, and you can also use a custom \u003ccode\u003enginx.conf\u003c/code\u003e file to meet your applications needs.\u003c/p\u003e\n"],["\u003cp\u003eESP offers options for setting various ports (HTTP/1.x, HTTP/2, HTTPS), specifying backend server addresses, managing status ports, custom NGINX configurations, and integrating service account credentials for non-Google Cloud platforms.\u003c/p\u003e\n"]]],[],null,["# Extensible Service Proxy startup options\n\n[OpenAPI](/endpoints/docs/openapi/specify-proxy-startup-options \"View this page for the Cloud Endpoints OpenAPI docs\") \\| gRPC\n\n\u003cbr /\u003e\n\nThe [Extensible Service Proxy\n(ESP)](/endpoints/docs/grpc/glossary#extensible_service_proxy) is an\n[NGINX-based](/endpoints/docs/grpc/glossary#nginx) proxy that enables\nCloud Endpoints to provide API management features. You configure\nESP by specifying options when you start the ESP\nDocker container. When the ESP container starts, it runs a script\ncalled `start_esp`, which writes the NGINX configuration file by using the\noptions that you specified and launches ESP.\n\nYou specify ESP startup options in the `docker run` command, for example: \n\n```\nsudo docker run \\\n --detach \\\n DOCKER_ARGUMENTS \\\n gcr.io/endpoints-release/endpoints-runtime:1 \\\n --service=SERVICE_NAME \\\n --rollout_strategy=managed \\\n --backend=YOUR_API_CONTAINER_NAME:8080\n```\n\nIf you are deploying ESP to Kubernetes, you specify the startup\noptions in your deployment manifest file in the `args` field, for example: \n\n```\ncontainers:\n- name: esp\n image: gcr.io/endpoints-release/endpoints-runtime:1\n args: [\n \"--http_port=8081\",\n \"--backend=127.0.0.1:8080\",\n \"--service=SERVICE_NAME\",\n \"--rollout_strategy=managed\"\n ]\n```\n\nThe following table describes ESP's startup options.\n\n^1^ These ports are optional and must be distinct from each other.\nIf you don't specify any port option, ESP accepts HTTP/1.x\nconnections on port `8080`.\nFor HTTPS connections, ESP expects the TLS secrets to be\nlocated at `/etc/nginx/ssl/nginx.crt` and `/etc/nginx/ssl/nginx.key`.\n\nSample command-line invocations\n-------------------------------\n\nThe following examples show how to use some of the command-line arguments:\n\nTo start ESP to handle requests coming in at HTTP/1.x port `80`\nand HTTPS port `443` and send the requests to your API backend at\n`127.0.0.1:8000`: \n\n```\nsudo docker run \\\n --detach \\\n DOCKER_ARGUMENTS \\\n gcr.io/endpoints-release/endpoints-runtime:1\n --service=echo-api.endpoints.example-project-12345.cloud.goog \\\n --rollout_strategy=managed \\\n --http_port=80 \\\n --ssl_port=443 \\\n --backend=127.0.0.1:8000\n```\n\nTo start ESP with a custom NGINX configuration by using the\nservice account credentials file to fetch the service config and connect to the\nservice control: \n\n```\nsudo docker run \\\n --detach \\\n --volume=$HOME/Downloads:/esp \\\n DOCKER_ARGUMENTS \\\n gcr.io/endpoints-release/endpoints-runtime:1 \\\n --service=echo-api.endpoints.example-project-12345.cloud.goog \\\n --rollout_strategy=managed \\\n --service_account_key=/esp/serviceaccount.json \\\n --nginx_config=/esp/nginx.conf\n \n```\n\nNote that you must use the Docker flags `--volume` or `--mount` to mount the\nJSON file containing the private key for the service account and the custom\nNGINX config file as volumes inside ESP's Docker container. The\npreceding example maps the `$HOME/Downloads` directory on the local computer to\nthe `esp` directory in the container. When you save the private key file for the\nservice account, it is typically downloaded to the `Downloads` directory. You\ncan copy the private key file to another directory if you want to. See\n[Manage data in Docker](https://docs.docker.com/storage/)\nfor more information.\n\nAdding CORS support to ESP\n--------------------------\n\nPlease refer to [Support CORS](/endpoints/docs/openapi/support-cors) for a description of available CORS support options. This section describes using ESP startup flags to support CORS.\n\nTo enable CORS support in ESP, include the `--cors_preset` option\nand set it to either `basic` or `cors_with_regex`. When you include\n`--cors_preset=basic` or `--cors_preset=cors_with_regex`, ESP:\n\n- Assumes all location paths have the same CORS policy.\n- Responds to both [simple requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#simple_requests) and [preflight](https://developer.mozilla.org/docs/Web/HTTP/CORS#Preflighted_requests) `HTTP OPTIONS` requests.\n- Caches the result of the preflight `OPTIONS` request for up to 20 days (1728000 seconds).\n- Sets the response headers to the following values:\n\n ```scdoc\n Access-Control-Allow-Origin: *\n Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS\n Access-Control-Allow-Headers: DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization\n Access-Control-Expose-Headers: Content-Length,Content-Range\n ```\n\nTo override the default value of\n[`Access-Control-Allow-Origin`](https://developer.mozilla.org/docs/Web/HTTP/Headers/Access-Control-Allow-Origin),\nspecify one of the following options:\n\nAfter setting `--cors_preset=basic` or `--cors_preset=cors_with_regex` to enable\nCORS, you can override the default values of the other response headers by\nspecifying one or more of the following options:\n\nIf the ESP CORS startup options don't suit the needs of your\napplication, you can create a custom `nginx.conf` file with the CORS support\nthat your application requires. For more information, see\n[Creating a custom `nginx.conf` to support CORS](/endpoints/docs/grpc/custom-cors-nginx).\n\nWhat's next\n-----------\n\nLearn about:\n\n- [Deploying ESP and your API backend to Google Cloud](/endpoints/docs/grpc/deploy-api-backend)\n- [Running ESP locally or on another platform](/endpoints/docs/grpc/running-esp-localdev)\n- The [`start_esp`](https://github.com/cloudendpoints/esp/tree/master/start_esp) script on GitHub"]]
