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 |
-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.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 de backend se ejecuta en un contenedor en Compute Engine, puedes especificar el nombre del contenedor y el puerto, por ejemplo: --backend=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 .
|
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
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_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
La expresión regular en el ejemplo anterior permite un origen con |
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_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_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_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
|
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 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