Opciones de inicio del ESP

El proxy de servicio extensible (ESP) es un proxy basado en NGINX que permite a Cloud Endpoints proporcionar características de administración para API. Puedes configurar el ESP mediante la especificación de opciones cuando inicias el contenedor de Docker del ESP. Cuando se inicia el contenedor del ESP, ejecuta una secuencia de comandos llamada start_esp, que escribe el archivo de configuración NGINX con las opciones que especificaste y, también, inicia el ESP.

Puedes especificar las opciones de inicio del ESP 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 implementas el ESP en Kubernetes, debes especificar las opciones de inicio en tu archivo de manifiesto de implementación en el campo args, 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 del ESP.

Opción corta Opción larga Descripción
-s SERVICE_NAME --service SERVICE_NAME Configura el nombre del servicio de Endpoints.
-R ROLLOUT_STRATEGY --rollout_strategy ROLLOUT_STRATEGY

Disponible en las versiones 1.7.0 y posteriores del ESP. Especifica managed o fixed. Con la opción --rollout_strategy=managed, se configura el ESP para usar la configuración del servicio implementado más reciente. Cuando especificas esta opción, hasta 5 minutos después de implementar una nueva configuración de servicio, el ESP detecta el cambio y comienza a usarlo automáticamente. Recomendamos que especifiques esta opción en lugar de un ID de configuración específico para que use el ESP. No es necesario especificar la opción --version cuando configuras --rollout_strategy en managed.

-v CONFIG_ID --version CONFIG_ID Establece el ID de configuración de servicio que va a usar el ESP. Consulta Cómo obtener el nombre del servicio y el ID de configuración con el fin de obtener la información necesaria para configurar esta opción. Cuando especificas --rollout_strategy=fixed o no incluyes la opción --rollout_strategy, debes incluir la opción --version y especificar un ID de configuración. En este caso, cada vez que implementes una configuración de Endpoints nueva, debes reiniciar el ESP con el ID de configuración nuevo.
-p HTTP1_PORT --http_port HTTP1_PORT Configura los puertos que el ESP expone para las conexiones HTTP/1.x.1
-P HTTP2_PORT --http2_port HTTP2_PORT Configura los puertos que ESP expone para las conexiones HTTP/2.1
-S SSL_PORT --ssl_port SSL_PORT Configura los puertos que el ESP expone para las conexiones HTTPS.1
-a BACKEND --backend BACKEND Configura la dirección para el servidor de backend de la aplicación HTTP/1.x. El valor predeterminado para la dirección de 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 lo haces, el valor predeterminado será http.
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
. Si quieres especificar que el backend acepte el tráfico gRPC, agrega el prefijo grpc://. Por ejemplo,
--backend=grpc://127.0.0.1:8000
Si tu servidor de backend se ejecuta en Compute Engine en un contenedor y acepta tráfico de 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 Configura el puerto de estado (predeterminado: 8090).
ninguno --disable_cloud_trace_auto_sampling De forma predeterminada, el ESP hace un muestreo de 1 solicitud de cada 1,000 o, cada 10 segundos, habilita 1 solicitud con Cloud Trace. Configura esta marca para inhabilitar el muestreo automático. Cloud Trace aún se puede habilitar desde los encabezados HTTP de solicitud con contexto de seguimiento, independientemente de este valor de marca. Para obtener más información, consulta Cómo hacer un seguimiento de la API.
-n NGINX_CONFIG --nginx_config NGINX_CONFIG Configura la ubicación del archivo de configuración NGINX personalizado. Si especificas esta opción, el ESP recupera el archivo de configuración especificado y, luego, inicia NGINX de inmediato con el archivo de configuración personalizado proporcionado.
-k SERVICE_ACCOUNT_KEY --service_account_key SERVICE_ACCOUNT_KEY Configura el archivo JSON de las credenciales de la cuenta de servicio. Si se proporciona, el ESP usa la cuenta de servicio a fin de generar un token de acceso para llamar a las API de Service Infrastructure. La única ocasión en que debes especificar esta opción es cuando el ESP se ejecuta en plataformas distintas de Google Cloud, como tu computadora de escritorio local, Kubernetes o cualquier otro proveedor de servicios en la nube. Para obtener más información, consulta Crear una cuenta de servicio.
-z HEALTHZ_PATH --healthz HEALTHZ_PATH Define un extremo de verificación de estado en los mismos puertos que el backend de la aplicación. Por ejemplo, -z healthz hace que el ESP muestre el código 200 para la ubicación /healthz, en lugar de reenviar la solicitud al backend. Predeterminado: no se usa.

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

Invocaciones de líneas de comando de muestra

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

Si quieres iniciar el ESP para controlar las solicitudes provenientes del puerto HTTP/1.x 80 y del puerto HTTPS 443 y enviar las solicitudes al backend de la API en 127.0.0.1:8000, haz lo siguiente:

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

Si quieres iniciar el ESP con una configuración NGINX personalizada mediante el archivo de credenciales de la cuenta de servicio con el fin de recuperar la configuración del servicio y conectarte al control de servicios, haz lo siguiente:

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 a fin de activar el archivo JSON que contiene la clave privada de la cuenta de servicio y el archivo de configuración NGINX personalizado como volúmenes dentro del contenedor de Docker del ESP. En el ejemplo anterior, se asigna el directorio $HOME/Downloads de la computadora local al directorio esp del contenedor. Cuando guardas el archivo de claves privada de la cuenta de servicio, por lo general, se descarga en el directorio Downloads. Puedes copiar el archivo de claves privadas y pegarlo en otro directorio si así lo deseas. Para obtener más información, consulta Administrar datos en Docker.

Agregar compatibilidad CORS al ESP

El CORS (uso compartido de recursos multiorigen) es un mecanismo estándar que permite que las llamadas XMLHttpRequest (XHR) que se ejecutan en una página web interactúen con recursos de orígenes diferentes. Sin el CORS, la política del mismo origen que aplican a todos los navegadores evitará las solicitudes multiorigen. Para obtener más información sobre el CORS, consulta los documentos web de Mozilla Developer Network (MDN).

Para habilitar la compatibilidad con CORS en el ESP, debes incluir la opción --cors_preset y configurarla en basic o cors_with_regex. Cuando incluyes --cors_preset=basic o --cors_preset=cors_with_regex, el ESP realiza lo siguiente:

  • Supone que todas las rutas de ubicación tienen la misma política de CORS.
  • Responde a solicitudes simples y a solicitudes de comprobación previa HTTP OPTIONS.
  • Almacena en caché el resultado de la solicitud de comprobación previa OPTIONS durante un máximo de 20 días (1728000 segundos).
  • Configura los encabezados de respuesta en los valores siguientes:

    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
    

Si quieres anular el valor predeterminado de Access-Control-Allow-Origin, debes especificar una de las opciones siguientes:

Opción Descripción
--cors_allow_origin Úsalo con --cors_preset=basic a fin de configurar Access-Control-Allow-Origin en 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 configurar Access-Control-Allow-Origin.
Ejemplo:
--cors_preset=cors_with_regex
--cors_allow_origin_regex=^https?://.+\.example\.com$

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

Luego de configurar --cors_preset=basic o --cors_preset=cors_with_regex a fin de habilitar el CORS, puedes anular los valores predeterminados de los otros encabezados de respuesta mediante la especificación de una o más de las opciones siguientes:

Opción Descripción
--cors_allow_methods Configura Access-Control-Allow-Methods con los métodos HTTP especificados. Especifica los métodos HTTP como una string, con cada método separado por una coma.
Ejemplo:
--cors_preset=basic
--cors_allow_methods=GET,POST,PUT,OPTIONS
--cors_allow_headers Configura Access-Control-Allow-Headers para los encabezados HTTP especificados. Especifica los encabezados HTTP como una string, con cada uno 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 está incluido en las respuestas.
Ejemplo:
--cors_preset=basic
--cors_allow_credentials
--cors_expose_headers Configura Access-Control-Expose-Headers en los encabezados especificados. Especifica cuáles encabezados pueden exponerse como parte de la respuesta como una string, con cada encabezado separado por una coma.
Ejemplo:
--cors_preset=basic
--cors_expose_headers=Content-Length

Si las opciones de inicio del CORS del ESP no satisfacen las necesidades de tu aplicación, puedes crear un archivo nginx.conf personalizado con la compatibilidad con CORS que requiera. Para obtener más información, consulta Crea un nginx.conf personalizado compatible con CORS.

Próximos pasos

Obtén más información sobre los siguientes temas: