Opciones de inicio de Extensible Service Proxy

El proxy de servicios extensible (ESP) es un proxy basado en NGINX que permite a Cloud Endpoints proporcionar funciones de gestión de APIs. Para configurar ESP, especifica las opciones al iniciar el contenedor de Docker de ESP. Cuando se inicia el contenedor ESP, ejecuta una secuencia de comandos llamada start_esp, que escribe el archivo de configuración de NGINX con las opciones que has especificado e inicia ESP.

Las opciones de inicio del ESP se especifican en el comando docker run. Por ejemplo:

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

Si vas a desplegar ESP en Kubernetes, especifica las opciones de inicio en el campo args del archivo de manifiesto de tu despliegue. Por ejemplo:

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

En la siguiente tabla se describen las opciones de inicio de ESP.

Opción breve Opción larga Descripción
-s SERVICE_NAME --service SERVICE_NAME Define el nombre del servicio Endpoints.
-R ROLLOUT_STRATEGY --rollout_strategy ROLLOUT_STRATEGY

Disponible en ESP 1.7.0 y versiones posteriores. Especifica managed o fixed. La opción --rollout_strategy=managed configura ESP para que use la última configuración de servicio implementada. Si especifica esta opción, el ESP detectará el cambio y empezará a usarlo automáticamente en un plazo de 5 minutos después de que implemente una nueva configuración de servicio. Te recomendamos que especifiques esta opción en lugar de un ID de configuración específico para que lo use ESP. No es necesario que especifiques la opción --version cuando asignes el valor managed a --rollout_strategy.
-v CONFIG_ID --version CONFIG_ID Define el ID de configuración del servicio que debe usar ESP. Consulta la sección Obtener el nombre del servicio y el ID de configuración para saber qué información necesitas para definir esta opción. Cuando especifiques --rollout_strategy=fixed o no incluyas la opción --rollout_strategy, debes incluir la opción --version y especificar un ID de configuración. En ese caso, cada vez que implementes una nueva configuración de Endpoints, deberás reiniciar ESP con el nuevo ID de configuración.
-p HTTP1_PORT --http_port HTTP1_PORT Define los puertos que expone ESP para las conexiones HTTP/1.x.1
-P HTTP2_PORT --http2_port HTTP2_PORT Define los puertos que expone ESP para las conexiones HTTP/2.1
-S SSL_PORT --ssl_port SSL_PORT Define los puertos que expone ESP para las conexiones HTTPS.1
-a BACKEND --backend BACKEND Define la dirección del servidor backend de la aplicación HTTP/1.x. El valor predeterminado de la dirección del backend es http://127.0.0.1:8081.
Puedes especificar un prefijo de protocolo, por ejemplo:
--backend=https://127.0.0.1:8000
Si no especificas ningún prefijo de protocolo, se usará http de forma predeterminada.
Si tu servidor backend se ejecuta en Compute Engine en un contenedor, puedes especificar el nombre del contenedor y el puerto. Por ejemplo:
--backend=my-api-container:8000
Para especificar que el backend acepta tráfico de gRPC, añade el prefijo grpc://. Por ejemplo:
--backend=grpc://127.0.0.1:8000
Si tu servidor backend se ejecuta en Compute Engine en un contenedor y acepta tráfico gRPC, puedes especificar el nombre del contenedor y el puerto. Por ejemplo:
--backend=grpc://my-api-container:8000
-N STATUS_PORT --status_port STATUS_PORT Define el puerto de estado (valor predeterminado: 8090).
ninguno --disable_cloud_trace_auto_sampling De forma predeterminada, ESP toma una muestra de cada 1000 solicitudes o una muestra de cada 10 segundos con Cloud Trace. Define esta marca para inhabilitar este muestreo automático. Cloud Trace se puede seguir habilitando desde los encabezados HTTP de las solicitudes con contexto de rastreo, independientemente del valor de esta marca. Consulta Monitorizar tu API para obtener más información.
-n NGINX_CONFIG --nginx_config NGINX_CONFIG Define la ubicación del archivo de configuración personalizado de NGINX. Si especificas esta opción, ESP obtiene el archivo de configuración especificado y, a continuación, inicia NGINX inmediatamente con el archivo de configuración personalizado proporcionado. Para obtener más información, consulta el artículo Usar una configuración de nginx personalizada en GKE.
-k SERVICE_ACCOUNT_KEY --service_account_key SERVICE_ACCOUNT_KEY Define el archivo JSON de las credenciales de la cuenta de servicio. Si se proporciona, ESP usa la cuenta de servicio para generar un token de acceso con el que llamar a las APIs de Service Infrastructure. Solo tienes que especificar esta opción cuando ESP se ejecute en plataformas que no sean Google Cloud, como tu ordenador local, Kubernetes u otro proveedor de nube. Consulta más información en el artículo Crear una cuenta de servicio.
-z HEALTHZ_PATH --healthz HEALTHZ_PATH Define un endpoint de comprobación de estado en los mismos puertos que el backend de la aplicación. Por ejemplo, -z healthz hace que el ESP devuelva el código 200 para la ubicación /healthz, en lugar de reenviar la solicitud al backend. Valor predeterminado: no se usa.
ninguno --dns DNS_RESOLVER Especifica un resolvedor de DNS. Por ejemplo, --dns 169.254.169.254 usa el servidor de metadatos de GCP como resolvedor de DNS. Si no se especifica, el valor predeterminado es 8.8.8.8.

1 Estos puertos son opcionales y deben ser distintos entre sí. Si no especifica ninguna opción de puerto, ESP acepta conexiones HTTP/1.x en el puerto 8080. En el caso de las conexiones HTTPS, ESP espera que los secretos de TLS se encuentren en /etc/nginx/ssl/nginx.crt y /etc/nginx/ssl/nginx.key.

Ejemplos de invocaciones de línea de comandos

En los siguientes ejemplos se muestra cómo usar algunos de los argumentos de línea de comandos:

Para iniciar ESP para gestionar las solicitudes que llegan al puerto HTTP/1.x 80 y al puerto HTTPS 443, y enviar las solicitudes a tu backend de API en 127.0.0.1:8000, sigue estos pasos:

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

Para iniciar ESP con una configuración de NGINX personalizada mediante el archivo de credenciales de la cuenta de servicio para obtener la configuración del servicio y conectarse al control del servicio, sigue estos pasos:

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

Ten en cuenta que debes usar las marcas de Docker --volume o --mount para montar el archivo JSON que contiene la clave privada de la cuenta de servicio y el archivo de configuración de NGINX personalizado como volúmenes dentro del contenedor de Docker de ESP. En el ejemplo anterior, se asigna el directorio $HOME/Downloads del ordenador local al directorio esp del contenedor. Cuando guardas el archivo de clave privada de la cuenta de servicio, normalmente se descarga en el directorio Downloads. Si quieres, puedes copiar el archivo de clave privada en otro directorio. Consulta Gestionar datos en Docker para obtener más información.

Añadir compatibilidad con CORS a ESP

Consulta Compatibilidad con CORS para ver una descripción de las opciones de compatibilidad con CORS disponibles. En esta sección se describe cómo usar las marcas de inicio de ESP para admitir CORS.

Para habilitar la compatibilidad con CORS en ESP, incluya la opción --cors_preset y asígnele el valor basic o cors_with_regex. Cuando incluyas --cors_preset=basic o --cors_preset=cors_with_regex, ESP:

  • Supone que todas las rutas de ubicación tienen la misma política de CORS.
  • Responde tanto a solicitudes sencillas como a solicitudes de preparación HTTP OPTIONS.
  • Almacena en caché el resultado de la solicitud de comprobación previa OPTIONS durante un máximo de 20 días (1.728.000 segundos).

  • Asigna los siguientes valores a los encabezados de respuesta:

    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

Para anular el valor predeterminado de Access-Control-Allow-Origin, especifique una de las siguientes opciones:

Opción Descripción
--cors_allow_origin Úsalo con --cors_preset=basic para asignar a Access-Control-Allow-Origin un origen específico.
Ejemplo:
--cors_preset=basic
--cors_allow_origin=http://example.com
--cors_allow_origin_regex Úsalo con --cors_preset=cors_with_regex. Te permite usar una expresión regular para definir Access-Control-Allow-Origin.
Ejemplo:
--cors_preset=cors_with_regex
--cors_allow_origin_regex=^https?://.+\.example\.com$

La expresión regular del ejemplo anterior permite un origen con http o https y cualquier subdominio de example.com.

Después de definir --cors_preset=basic o --cors_preset=cors_with_regex para habilitar CORS, puede anular los valores predeterminados de los demás encabezados de respuesta especificando una o varias de las siguientes opciones:

Opción Descripción
--cors_allow_methods Define Access-Control-Allow-Methods en los métodos HTTP especificados. Especifica los métodos HTTP como una cadena en la que cada método HTTP esté separado por una coma.
Ejemplo:
--cors_preset=basic
--cors_allow_methods=GET,POST,PUT,OPTIONS
--cors_allow_headers Define Access-Control-Allow-Headers en los encabezados HTTP especificados. Especifica los encabezados HTTP como una cadena en la que cada encabezado HTTP está separado por una coma.
Ejemplo:
--cors_preset=basic
--cors_allow_headers=Origin,Content-Type,Accept
--cors_allow_credentials Incluye el encabezado Access-Control-Allow-Credentials con el valor true en las respuestas. De forma predeterminada, el encabezado Access-Control-Allow-Credentials no se incluye en las respuestas.
Ejemplo:
--cors_preset=basic
--cors_allow_credentials
--cors_expose_headers Define Access-Control-Expose-Headers en los encabezados especificados. Especifica qué encabezados se pueden exponer como parte de la respuesta como una cadena con cada encabezado separado por una coma.
Ejemplo:
--cors_preset=basic
--cors_expose_headers=Content-Length

Si las opciones de inicio de CORS de ESP no se ajustan a las necesidades de tu aplicación, puedes crear un archivo nginx.conf personalizado con la compatibilidad con CORS que requiera tu aplicación. Para obtener más información, consulta el artículo Crear un nginx.conf personalizado para admitir CORS.

Siguientes pasos

Puedes informarte sobre lo siguiente: