Extensible Service Proxy(ESP)는 Cloud Endpoints에 API 관리 기능을 제공하는 NGINX 기반 프록시입니다. ESP Docker 컨테이너를 시작할 때 옵션을 지정하여 ESP를 구성합니다. ESP 컨테이너가 시작되면 start_esp
라는 스크립트를 실행합니다. 이 스크립트는 지정된 옵션을 사용하여 NGINX 구성 파일을 작성하고 ESP를 시작합니다.
docker run
명령어에서 ESP 시작 옵션을 지정합니다. 예를 들면 다음과 같습니다.
sudo docker run \ --detach \ DOCKER_ARGUMENTS \ gcr.io/endpoints-release/endpoints-runtime:1 \ --service=SERVICE_NAME \ --rollout_strategy=managed \ --backend=YOUR_API_CONTAINER_NAME:8080
ESP를 Kubernetes에 배포하는 경우에는 배포 매니페스트 파일의 args
필드에 시작 옵션을 지정합니다. 예를 들면 다음과 같습니다.
containers: - name: esp image: gcr.io/endpoints-release/endpoints-runtime:1 args: [ "--http_port=8081", "--backend=127.0.0.1:8080", "--service=SERVICE_NAME", "--rollout_strategy=managed" ]
다음 표에서는 ESP의 시작 옵션을 설명합니다.
짧은 옵션 | 긴 옵션 | 설명 |
---|---|---|
-s SERVICE_NAME |
--service SERVICE_NAME |
Endpoints 서비스의 이름을 설정합니다. |
-R ROLLOUT_STRATEGY |
--rollout_strategy ROLLOUT_STRATEGY |
ESP 버전 1.7.0 이상에서 사용할 수 있습니다. |
-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 |
-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를 시작하려면 다음 명령어를 사용합니다.
sudo docker run \ --detach \ DOCKER_ARGUMENTS \ gcr.io/endpoints-release/endpoints-runtime:1 --service=echo-api.endpoints.example-project-12345.cloud.goog \ --rollout_strategy=managed \ --http_port=80 \ --ssl_port=443 \ --backend=127.0.0.1:8000
서비스 계정 사용자 인증 정보 파일을 사용하여 서비스 구성을 가져오고 서비스 제어에 연결하는 커스텀 NGINX 구성으로 ESP를 시작하는 방법은 다음과 같습니다.
sudo docker run \ --detach \ --volume=$HOME/Downloads:/esp \ DOCKER_ARGUMENTS \ gcr.io/endpoints-release/endpoints-runtime:1 \ --service=echo-api.endpoints.example-project-12345.cloud.goog \ --rollout_strategy=managed \ --service_account_key=/esp/serviceaccount.json \ --nginx_config=/esp/nginx.conf
서비스 계정의 비공개 키와 커스텀 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 정책이 있다고 가정합니다.
- 단순 요청 및 실행 전
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_regex |
--cors_preset=cors_with_regex 와 함께 사용합니다. 정규 표현식을 사용하여 Access-Control-Allow-Origin 을 설정할 수 있습니다.예시:
--cors_preset=cors_with_regex
앞의 예시에서 정규 표현식은 |
--cors_preset=basic
또는 --cors_preset=cors_with_regex
를 설정하여 CORS를 사용 설정한 후에는 다음 옵션을 한 개 이상 지정하여 다른 응답 헤더의 기본값을 재정의할 수 있습니다.
옵션 | 설명 |
---|---|
--cors_allow_methods |
Access-Control-Allow-Methods 를 지정된 HTTP 메서드로 설정합니다. 각 HTTP 메서드를 쉼표로 구분하여 문자열로 HTTP 메서드를 지정합니다.예:
--cors_preset=basic
|
--cors_allow_headers |
Access-Control-Allow-Headers 를 지정된 HTTP 헤더로 설정합니다. 각 HTTP 헤더를 쉼표로 구분하여 HTTP 헤더를 문자열로 지정합니다.예:
--cors_preset=basic
|
--cors_allow_credentials |
응답에 true 값이 있는 Access-Control-Allow-Credentials 헤더를 포함합니다. 기본적으로 Access-Control-Allow-Credentials 헤더는 응답에 포함되지 않습니다.예시:
--cors_preset=basic
|
--cors_expose_headers |
Access-Control-Expose-Headers 를 지정된 헤더로 설정합니다. 각 헤더를 쉼표로 구분하여 응답의 일부로 공개할 수 있는 헤더를 문자열로 지정합니다.예:
--cors_preset=basic
|
ESP CORS 시작 옵션이 애플리케이션의 요구사항에 맞지 않으면 애플리케이션에 필요한 CORS 지원이 포함된 커스텀 nginx.conf
파일을 만들 수 있습니다. 자세한 내용은 CORS를 지원하는 커스텀 nginx.conf
만들기를 참조하세요.
다음 단계
다음 사항에 대해 알아보세요.
- Google Cloud에 ESP와 API 백엔드 배포
- ESP를 로컬 또는 다른 플랫폼에서 실행
- GitHub의
start_esp
스크립트