Opciones de inicio del proxy de servicio extensible V2 Beta

El proxy de servicio extensible V2 Beta (ESPv2 Beta) es un proxy basado en Envoy que le permite a Cloud Endpoints proporcionar características de administración de API. Para configurar el ESPv2 Beta, puedes especificar marcas de configuración cuando implementes el servicio del ESPv2 Beta.

Establecer marcas de configuración

El método para configurar las marcas de configuración del ESPv2 Beta varía según la plataforma de implementación, como se describe en las siguientes secciones.

VM de Compute Engine

Las marcas de configuración del ESPv2 Beta para Compute Engine se especifican en el comando docker run. Por ejemplo:

sudo docker run \
    --detach \
    DOCKER_ARGUMENTS \
    gcr.io/endpoints-release/endpoints-runtime:2 \
    --service=SERVICE_NAME \
    --rollout_strategy=managed \
    --backend=YOUR_API_CONTAINER_NAME:8080

En este ejemplo, --service, --rollout_strategy y --backend son las marcas de configuración de ESPv2 Beta.

GKE y Kubernetes

Puedes especificar marcas de configuración para GKE y Kubernetes en el campo args del archivo del manifiesto de implementación. Por ejemplo:

containers:
- name: esp
  image: gcr.io/endpoints-release/endpoints-runtime:2
  args: [
    "--listener_port=8081",
    "--backend=127.0.0.1:8080",
    "--service=SERVICE_NAME",
    "--rollout_strategy=managed"
  ]

En este ejemplo, --listener_port, --backend, --service y --rollout_strategy son las marcas de configuración del ESPv2 Beta.

Cloud Run para plataformas sin servidores

Si quieres especificar las opciones de inicio de Cloud Run para plataformas sin servidores, usa la variable de entorno ESPv2_ARGS. La variable se puede configurar en el comando gcloud run deploy mediante la opción --set-env-vars.

Por ejemplo:

gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=--enable_debug

En este ejemplo, --enable_debug es la marca de configuración de ESPv2 Beta.

Consulta Cloud Functions para OpenAPI, Cloud Run para OpenAPI o Cloud Run para gRPC para obtener más información sobre el comando gcloud run deploy.

Para configurar varios argumentos en la variable de entorno ESPv2_ARGS, especifica un delimitador personalizado y usa ese delimitador para separar varios argumentos. No uses una coma como delimitador. Coloca el delimitador personalizado al principio de la variable de entorno ESPv2_ARGS, rodeado de carets.

En el siguiente ejemplo, se usa ++ como delimitador:

gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=^++^--cors_preset=basic++--cors_allow_origin=your_host.com

Si la marca que configuras contiene comas, debes establecer la variable de entorno ESPv2_ARGS en la secuencia de comandos gcloud_build_image.

Por ejemplo, para agregar la marca --cors_allow_methods=PUT,POST,GET, haz lo siguiente:

  • Descarga la secuencia de comandos gcloud_build_image.
  • Edita gcloud_build_image como se muestra a continuación:
    cat <<EOF > Dockerfile
      FROM BASE_IMAGE
    
      ENV ENDPOINTS_SERVICE_PATH /etc/endpoints/service.json
      COPY service.json \ENDPOINTS_SERVICE_PATH
    
      ENV ESPv2_ARGS ^++^--cors_preset=basic++--cors_allow_method="GET,PUT,POST"++--cors_allow_credentials
    
      ENTRYPOINT ["/env_start_proxy.py"]
      EOF
  • Ejecuta la secuencia de comandos gcloud_build_image para compilar la imagen.

Marcas de configuración del ESPv2 Beta

Las marcas de configuración del ESPv2 Beta se pueden agrupar en las siguientes categorías:

Configuración para plataformas sin servidores

Estas marcas son necesarias para ejecutar el ESPv2 Beta en plataformas sin servidores, como GKE, Compute Engine y Kubernetes. No se pueden configurar cuando se implementan en Cloud Run para plataformas sin servidores.

Flag Descripción
--service Configura el nombre del servicio de Endpoints.
--version Configura el ID de configuración de servicio del servicio de Endpoints.
--rollout_strategy Especifica la estrategia de lanzamiento de la configuración de servicio, [fixed|managed]. El valor predeterminado es fixed.
--listener_port Identifica el puerto para aceptar conexiones descendentes. Admite conexiones con HTTP/1.x, HTTP/2 y gRPC. El valor predeterminado es 8080.
--backend Especifica la dirección del servidor de la aplicación de backend local. Los esquemas válidos son http, https, grpc y grpcs, si se incluyen. El esquema predeterminado es >http.

Logging

Usa estas marcas para configurar el ESPv2 Beta a fin de escribir información adicional en el registro de Stackdriver.

Flag Descripción
--log_request_headers

Registra los valores de los encabezados de solicitud especificados, separados por comas y sin espacios. Por ejemplo, configura esta marca de la siguiente manera:

--log_request_headers=foo,bar

Si los valores para el encabezado "foo" y "bar" están disponibles en la solicitud, el registro de Endpoints contiene lo siguiente:

request_headers: foo=foo_value;bar=bar_value

--log_response_headers

Registra los valores de los encabezados de respuesta especificados, separados por comas y sin espacios. Por ejemplo, configura esta marca de la siguiente manera:

--log_response_headers=baz,bing

Si los valores para el encabezado "baz" y "bing" están disponibles en la respuesta, el registro de Endpoints contiene lo siguiente:

response_headers: baz=baz_value;bing=bing_value

--log_jwt_payloads

Registra los valores de los campos primitivos de la carga útil de JWT especificados, separados por comas y sin espacios. Por ejemplo, configura esta marca de la siguiente manera:

--log_jwt_payload=sub,project_id,foo.foo_name

Si los valores están disponibles en la carga útil de JWT, el registro de Endpoints contiene lo siguiente:

jwt_payloads: sub=sub_value;project_id=project_id_value; foo.foo_name=foo.foo_name_value

Los valores en la carga útil de JWT deben ser campos primitivos (string, número entero). Los objetos y arreglos JSON no se registran.

--access_log

Si se especifica, es la ruta de acceso al archivo local en el que se escribirán las entradas de registro de acceso.

--access_log_format

Es el formato de string para especificar el formato del registro de acceso. Si no se configura, se usa la >string de formato predeterminada. Para obtener la gramática de formato detallada, consulta la referencia de las strings de formato.

Seguimiento

Usa estas marcas para configurar los datos de seguimiento del ESPv2 Beta enviados a Stackdriver. Estas marcas solo se aplican cuando el seguimiento está habilitado.

Marca Descripción
--disable_tracing

Inhabilitar el seguimiento. De forma predeterminada, el seguimiento está habilitado.

Cuando está habilitado, el ESPv2 Beta envía muestras con una pequeña cantidad de solicitudes a tu API cada segundo para obtener los seguimientos que envía a Stackdriver Trace. De forma predeterminada, se muestra una de cada 1,000 solicitudes. Usa la marca --tracing_sample_rate para cambiar la tasa de muestreo.

--tracing_project_id

El ID del proyecto de Google para el seguimiento de Stackdriver.

El seguimiento es un servicio pagado. En el proyecto especificado, se facturará el seguimiento.

De forma predeterminada, la facturación se aplica al ID del proyecto del servicio del ESPv2 Beta implementado.

--tracing_sample_rate

Establece la tasa de muestreo de seguimientos en un valor de 0.0 a 1.0. Este valor especifica la fracción de las solicitudes que se envían en la muestra.

El valor predeterminado es 0.001, que equivale a 1 de cada 1,000 solicitudes.

--tracing_incoming_context

Para el seguimiento distribuido, un encabezado de solicitud puede contener un contexto de seguimiento que especifique un ID de seguimiento. El ID de seguimiento se usa cuando el ESPv2 crea nuevos intervalos de seguimiento y los envía a Stackdriver. El ID de seguimiento se puede usar para buscar todos los intervalos de seguimiento de una solicitud desde todos los componentes distribuidos. Si no se especifica ningún contexto de seguimiento en la solicitud y el seguimiento está habilitado, se genera un ID de seguimiento aleatorio para todos los intervalos de seguimiento.

Esta marca especifica los encabezados HTTP que se deben verificar para el contexto de seguimiento, con valores de marcas separados por comas y sin espacios. Por ejemplo, configura esta marca de la siguiente manera:

--tracing_incoming_context=x-cloud-trace-context

Los valores posibles son traceparent y x-cloud-trace-context.

Si se omite, no se verificará el contexto de seguimiento.

Consulta este artículo sobre cómo solucionar problemas para obtener más información acerca de x-cloud-trace-context. Consulta el Formato de los encabezados HTTP del contexto de seguimiento para obtener más información sobre el traceparent.

--tracing_outgoing_context

Configura el encabezado del contexto de seguimiento en la solicitud enviada al servicio de backend, como Cloud Functions o Cloud Run. Consulta la descripción de --tracing_incoming_context que aparece con anterioridad para obtener más información sobre el contexto de seguimiento.

Esta marca especifica los encabezado HTTP que se deben configurar, con valores de marcas separados por comas y sin espacios. Por ejemplo, puedes configurar esta marca de la siguiente manera:

--tracing_outgoing_context=traceparent

Los valores posibles son traceparent y x-cloud-trace-context.

Si se omite, no se envía ningún encabezado del contexto de seguimiento.

Consulta este artículo sobre cómo solucionar problemas para obtener más información acerca de x-cloud-trace-context. Consulta el Formato de los encabezados HTTP del contexto de seguimiento para obtener más información sobre el traceparent.

Depuración

Usa estas marcas con el fin de configurar las verificaciones de estado y la depuración para el ESPv2 Beta. Estas marcas se pueden usar con el fin de configurar un controlador de estado para que responda a las llamadas de verificación de estado o un puerto de administrador de Envoy para recuperar la configuración y las estadísticas, o para ejecutar Envoy en el modo de depuración con el fin de escribir información a nivel de depuración en el registro.

Flag Descripción
-z, --healthz Define un extremo de verificación de estado. Por ejemplo, -z healthz hace que el ESPv2 Beta muestre el código 200 para la ruta de acceso /healthz.
--status_port, --admin_port Habilita el administrador de Envoy versión del ESPv2 Beta en este puerto. Consulta la referencia de la interfaz de administración de Envoy para obtener más detalles. El puerto del administrador está inhabilitado de forma predeterminada.
--enable_debug Habilita los registros a nivel de depuración y agrega encabezados de depuración.

Implementación para plataformas que no sean GCP

Si el ESPv2 Beta se implementa en un entorno que no es de Google Cloud Platform (GCP), es posible que se necesiten las siguientes marcas.

Flag Descripción
--service_account_key

Especifica el archivo JSON de la clave de la cuenta de servicio para acceder a los servicios de Google. Si se omite la opción, el proxy se comunica con el servidor de metadatos de GCP para recuperar un token de acceso.

--dns_resolver_addresses Son las direcciones de los agentes de resolución de DNS. Cada dirección debe estar en el formato IP_ADDR o IP_ADDR:PORT, y debe estar separada por un punto y coma (;). Para IP_ADDR, se usará el puerto 52 de DNS predeterminado. (Por ejemplo: --dns_resolver_addresses=127.0.0.1;127.0.0.2;127.0.0.3:8000). Si no se configura, el ESPv2 Beta usará el agente de resolución predeterminado configurado en /etc/resolv.conf.
--backend_dns_lookup_family Define la familia de búsqueda de DNS para todos los backends. Las opciones son auto, v4only y v6only. El valor predeterminado es autocode>.
--non_gcp De manera predeterminada, el proxy intenta conectarse al servidor de metadatos de GCP para obtener la ubicación de la VM en las primeras solicitudes. Para omitir este paso, configura esta marca como verdadera.

Extracción del IP de cliente

Usa estas marcas a fin de configurar la extracción del IP de cliente para el ESPv2 Beta.

Flag Descripción
--envoy_use_remote_address

Para obtener información detallada sobre la configuración de HttpConnectionManager de Envoy, consulta la referencia de Envoy. La opción predeterminada es apagado.

--envoy_xff_num_trusted_hops Para obtener información detallada sobre la configuración de HttpConnectionManager de Envoy, consulta la referencia de Envoy. El valor predeterminado es 2.

Compatibilidad con CORS

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 ESPv2 Beta para admitir CORS.

Para habilitar la compatibilidad con CORS en el ESPv2 Beta, incluye la opción --cors_preset y configúrala con una de las siguientes marcas:

  • >--cors_preset=basic
  • >--cors_preset=cors_with_regex

Cuando incluyes --cors_preset=basic o --cors_preset=cors_with_regex, el ESPv2 Beta hace 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 con https y cualquier subdominio de example.com.

Cuando configuras esta opción en un archivo de configuración de Kubernetes, debes agregar una barra inversa adicional para escapar ambas instancias de \ en la string, por ejemplo:

"--cors_preset","cors_with_regex",
"--cors_allow_origin_regex","^https?://.+\\.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 verdadero 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"

Compatibilidad con TLS

Usa estas marcas para configurar el ESPv2 Beta con el fin de usar conexiones de TLS.

Flag Descripción
--ssl_server_cert_path Es la ruta de acceso del certificado del servidor del proxy. Cuando se configura, el ESPv2 Beta solo acepta conexiones seguras con HTTP/1.x y HTTP/2 en listener_port. Requiere el certificado y los archivos de claves "server.crt" y "server.key" dentro de esta ruta.
--ssl_backend_client_cert_path Es la ruta de acceso del certificado del cliente del proxy. Cuando se configura, el ESPv2 Beta habilita la autenticación mutua de TLS para backends HTTPS. Requiere el certificado y los archivos de claves "client.crt" y "client.key" dentro de esta ruta.
--ssl_backend_client_root_certs_file Es la ruta de archivo de los certificados raíz que usa el ESPv2 Beta para verificar el certificado de servidor de backend. Si no se especifica, el ESPv2 Beta usa "/etc/ssl/certs/ca-certificates.crt" de forma predeterminada.
--ssl_minimum_protocol Es la versión mínima del protocolo de TLS para la conexión del cliente. Consulta esta versión.
--ssl_maximum_protocol Es la versión máxima del protocolo de TLS para la conexión del cliente. Consulta esta versión.
--enable_strict_transport_security Habilita HSTS (HTTP con Seguridad de Transporte Estricta). El encabezado de respuesta “Strict-Transport-Security” con el valor “max-age=31536000; includeSubdomains;” se agrega en todas las respuestas del backend local. No es válido para los backends remotos.
--generate_self_signed_cert Genera una clave y certificado autofirmado al inicio y, luego almacénalos en “/tmp/ssl/endpoints/server.crt” y “/tmp/ssl/endpoints/server.key”. Esto es útil cuando solo se necesita un certificado autofirmado aleatorio para entregar solicitudes HTTPS. El certificado generado tendrá el nombre común "localhost" y será válido durante 10 años.

Tiempo de espera y reintentos

Usa estas marcas para configurar el tiempo de espera de llamada HTTP remota y los reintentos para el ESPv2 Beta.

Flag Descripción
--http_request_timeout_s

Establece el tiempo de espera en segundos para las solicitudes realizadas a servicios externos, excepto backend y el control de servicios de Google. Incluye ServiceManagement de Google, el servidor de metadatos y el servidor de IAM de Google. Debe ser > 0, y el valor predeterminado es de 30 segundos si no se establece.

--service_control_network_fail_open

En el caso de que ocurran fallas de red cuando se conecta al control de servicios de Google, se permitirán las solicitudes si esta marca está activada. El valor predeterminado es activada.

--service_control_check_timeout_ms Establece el tiempo de espera en milisegundos para la solicitud de verificación del control del servicios. Debe ser > 0, y el valor predeterminado es de 1000 si no se configura.
--service_control_report_timeout_ms Establece el tiempo de espera en milisegundos para la solicitud de informe del control de servicios. Debe ser > 0, y el valor predeterminado es de 1000 si no se configura.
--service_control_quota_timeout_ms Establece el tiempo de espera en milisegundos para la solicitud de cuota del control del servicios. Debe ser > 0, y el valor predeterminado es de 1000 si no se configura.
--service_control_check_retries Establece los tiempos de reintento para la solicitud de verificación del control de servicios. Debe ser >= 0, y el valor predeterminado es de 3 si no se configura.
--service_control_report_retries Establece los tiempos de reintento para la solicitud de informe del control de servicios. Debe ser >= 0, y el valor predeterminado es de 5 si no se configura.
--service_control_quota_retries Establece los tiempos de reintento para la solicitud de cuota del control de servicios. Debe ser >= 0, y el valor predeterminado es de 1 si no se configura.

Transcodificación de gRPC

Usa estas marcas con el fin de configurar el ESPv2 Beta para la transcodificación de HTTP/JSON a gRPC.

Flag Descripción
--transcoding_always_print_primitive_fields

Especifica si se deben imprimir los campos primitivos para la transcodificación de gRPC y JSON. De forma predeterminada, los campos primitivos con valores predeterminados se omitirán en el resultado de JSON. Por ejemplo, se omitirá un campo int32 que esté establecido en 0. Configurar esta marca como verdadero anulará el comportamiento predeterminado e imprimirá los campos primitivos, sin importar sus valores. La configuración predeterminada es falso.

--transcoding_always_print_enums_as_ints

Especifica si se deben imprimir las enumeraciones como ints para la transcodificación de gRPC y JSON. De forma predeterminada, se procesan como strings. La configuración predeterminada es false.

--transcoding_preserve_proto_field_names

Especifica si se deben conservar los nombres de los campos proto para la transcodificación de gRPC y JSON. De manera predeterminada, protobuf generará nombres de campos de JSON mediante la opción json_name, o minúsculas o las minúsculas intermedias, en ese orden. Configurar esta marca conservará los nombres de campos originales. La configuración predeterminada es false.

--transcoding_ignore_query_parameters

Es una lista de parámetros de consulta separados por comas que se deben ignorar para la asignación de métodos de transcodificación en la transcodificación de gRPC y JSON. De forma predeterminada, el filtro de transcodificador no transcodificará una solicitud con parámetros de consulta desconocidos o no válidos.

--transcoding_ignore_unknown_query_parameters

Especifica si se deben ignorar los parámetros de consulta que no se puedan asignar a un campo protobuf correspondiente en la transcodificación de gRPC y JSON. Usa esto si no puedes controlar los parámetros de consulta y no los conoces de antemano. De lo contrario, usa --transcoding_ignore_query_parameters. La configuración predeterminada es falso.

Puedes encontrar ejemplos genéricos y texto de ayuda para las marcas del ESPv2 Beta en el repositorio de GitHub.

¿Qué sigue?

Más información sobre: