Specifying Startup Options for Extensible Service Proxy

Extensible Service Proxy is an NGINX-based proxy that provides API management features. The startup script writes the NGINX configuration file for the Extensible Service Proxy and launches the proxy.

You configure Extensible Service Proxy by specifying custom options when you start the ESP Docker container, as described in the Endpoints Tutorials for Kubernetes Engine and Compute Engine with Docker.

Specifying startup options

The Extensible Service Proxy Docker container image and the daemon script in the Extensible Service Proxy Debian package both rely on the same startup script to configure Extensible Service Proxy.

To run the startup script:

  1. Invoke the script with the required minimum of options as follows:

    sudo docker run -d [DOCKER_ARGUMENTS] gcr.io/endpoints-release/endpoints-runtime:1 [ENDPOINTS_PROXY_ARGUMENTS]
  2. Alternatively, if you wish to specify startup options, invoke the command above, appending the command line with the desired arguments from the table below:

    Short Option Long Option Description
    -s SERVICE_NAME --service SERVICE_NAME Sets the name of the Endpoints service.
    -v CONFIG_VERSION --version CONFIG_VERSION Sets the service config version to be used by ESP.
    -p HTTP1_PORT --http_port HTTP1_PORT Sets the ports to be exposed by the proxy for HTTP/1.x connections.1
    -P HTTP2_PORT --http2_port HTTP2_PORT Sets the ports to be exposed by the proxy for HTTP/2 connections.1
    -S SSL_PORT --ssl_port SSL_PORT Sets the ports to be exposed by the proxy for HTTPS connections.1
    -a BACKEND --backend BACKEND Sets the address for the HTTP/1.x application backend server.
    The default value for the backend address is "".
    -N STATUS_PORT --status_port STATUS_PORT Sets the status port (default: 8090).
    -n NGINX_CONFIG --nginx_config NGINX_CONFIG Sets the location for the custom NGINX configuration file.
    If you specify this option, the proxy fetches the service config file to /etc/nginx/endpoints/service.json and then immediately launches NGINX with the provided custom configuration file.
    -k SERVICE_ACCOUNT_KEY --service_account_key SERVICE_ACCOUNT_KEY Sets the service account credentials JSON file.
    If provided, the proxy uses this file to access the service control and the service management. By default, the proxy relies on the metadata service to fetch an access token.
    -z HEALTHZ_PATH --healthz HEALTHZ_PATH Define a health checking endpoint on the same ports as the application backend. For example, "-z healthz" makes ESP return code 200 for location "/healthz", instead of forwarding the request to the backend. Default: not used.

    1These ports are optional and must be distinct from each other. If you do not specify any port option, the proxy accepts HTTP/1.x connections on port 8080. For HTTPS connections, the proxy expects the TLS secrets to be located at /etc/nginx/ssl/nginx.crt and /etc/nginx/ssl/nginx.key.

Sample command line invocations:

Here are some examples how to use the custom command line arguments:

To start the proxy so that the proxy handles requests coming in at HTTP/1.x port 80 and HTTPS port 443 and sends application requests to

sudo docker run -d [DOCKER_ARGUMENTS] gcr.io/endpoints-release/endpoints-runtime:1 -s SERVICE_NAME -v CONFIG_VERSION -p 80 -S 443 -a

To start the proxy with a custom NGINX configuration, using the service account credentials file to fetch the service config and connect to the service control:

sudo docker run -d [DOCKER_ARGUMENTS] gcr.io/endpoints-release/endpoints-runtime:1 -s SERVICE_NAME -v CONFIG_VERSION -k CREDENTIALS_JSON -n /etc/nginx/custom/nginx.conf

Note that you should use Docker argument -v to mount the CREDENTIALS_JSON file and the custom NGINX config as volumes inside the proxy's Docker container.

Customizing Extensible Service Proxy on Compute Engine

To customize the proxy on a Compute Engine VM instance using the Debian package, you must provide custom arguments to the NGINX daemon script by editing /etc/default/nginx/:

  1. Use PORT=80 to change the default port (equivalent to -p option).

  2. Use STATUS_PORT=8090 to change the status port (equivalent to -N option).

  3. Modify DAEMON_ARGS variable to specify any additional command line arguments to the startup script.

  4. After editing the file, run the following command to restart the Extensible Service Proxy:

    sudo service nginx restart

Send feedback about...

Cloud Endpoints with gRPC