Opciones de inicio del ESP

OpenAPI | gRPC

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 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.¹
`-P HTTP2_PORT`	`--http2_port HTTP2_PORT`	Configura los puertos que el ESP expone para las conexiones HTTP/2.¹
`-S SSL_PORT`	`--ssl_port SSL_PORT`	Configura los puertos que expone el ESP para las conexiones HTTPS.¹
`-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`).
ninguna	`--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. Consulta Usa una configuración de nginx personalizada para GKE a fin de obtener más información.
`-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.
ninguna	`--dns DNS_RESOLVER`	Especifica un agente de resolución de DNS. Por ejemplo, `--dns 169.254.169.254` usa el servidor de metadatos de GCP como agente de resolución de DNS. Si no se especifica, el valor predeterminado es `8.8.8.8`.

¹ 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

Consulta Compatibilidad con CORS para obtener una descripción de las opciones de compatibilidad con CORS disponibles. En esta sección, se describe el uso de marcas de inicio del ESP para la compatibilidad con CORS.

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 HTTP OPTIONS preliminares.
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.

¿Qué sigue?

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

Implementa el ESP y el backend de tu API en Google Cloud
Ejecuta el ESP de forma local o en otra plataforma
La secuencia de comandos start_esp en GitHub