Opciones de inicio de Extensible Service Proxy V2

OpenAPI   |  gRPC

El proxy de servicios extensible V2 (ESPv2) es un proxy basado en Envoy que permite a Cloud Endpoints proporcionar funciones de gestión de APIs. Para configurar ESPv2, puede especificar marcas de configuración al implementar el servicio ESPv2.

Definir marcas de configuración

El método para definir las marcas de configuración de ESPv2 varía en función de la plataforma de implementación, tal como se indica en las siguientes secciones.

VM de Compute Engine

Las marcas de configuración de ESPv2 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.

GKE y Kubernetes

Puedes especificar marcas de configuración para GKE y Kubernetes en el campo args de tu archivo de 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 de ESPv2.

Cloud Run para plataformas sin servidor

Para especificar las opciones de inicio de Cloud Run para la tecnología sin servidor, usa la variable de entorno ESPv2_ARGS. La variable se puede definir 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.

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

Para definir varios argumentos en la variable de entorno ESPv2_ARGS, especifica un delimitador personalizado y úsalo para separar los argumentos. No uses comas como delimitadores. Coloca el delimitador personalizado al principio de la variable de entorno ESPv2_ARGS, entre signos de intercalación.

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 está definiendo contiene comas, debe definir la variable de entorno ESPv2_ARGS en la secuencia de comandos gcloud_build_image.

Por ejemplo, para añadir la marca --cors_allow_methods=PUT,POST,GET, sigue estos pasos:

• Descarga la secuencia de comandos gcloud_build_image.
• Edita el 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

  Nota: Se usa un delimitador personalizado para separar varios argumentos.
• Ejecuta la secuencia de comandos gcloud_build_image para crear la imagen.

Marcas de configuración de ESPv2

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

• Configuración sin servidor
• Logging
• Trazado
• Revisión de salud
• Depuración
• Pruebas locales
• Non-Google Cloud Deployment
• Extracción de la IP del cliente
• Compatibilidad con CORS
• Compatibilidad con TLS
• Tiempo de espera y reintentos
• Transcodificación de gRPC
• Modificación de solicitudes y respuestas
• Opciones de seguridad
• Autenticación JWT

Puedes consultar más ejemplos genéricos y texto de ayuda sobre las marcas de ESPv2 en el repositorio de GitHub.

Configuración sin servidor

Estas marcas son necesarias para ejecutar ESPv2 en plataformas que no son sin servidor, como GKE, Compute Engine y Kubernetes. No se pueden definir cuando se implementan en Cloud Run para plataformas sin servidor.

Nota: Si usas Kubernetes, NO incluyas los valores de los campos entre comillas en los archivos de configuración. Por ejemplo, --cors_allow_origin="http://example.com" asignará el valor de cadena \"http://example.com\" al campo cor_allow_origin en lugar del valor de cadena previsto http://example.com.

``

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

Almacenamiento de registros

Usa estas marcas para configurar ESPv2 de forma que escriba información adicional en el registro de Stackdriver.

Bandera	Descripción
--log_request_headers	Registra los valores de los encabezados de solicitud especificados, separados por comas sin espacios. Por ejemplo, define esta marca de la siguiente manera: --log_request_headers=foo,bar Si los valores de los encabezados "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 sin espacios. Por ejemplo, define esta marca de la siguiente manera: --log_response_headers=baz,bing Si los valores de los encabezados "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 sin espacios. Por ejemplo, define esta marca de la siguiente manera: --log_jwt_payloads=sub,project_id,foo.foo_name Si los valores están disponibles en la carga útil del 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 de la carga útil del JWT deben ser campos primitivos (cadena o número entero). Los objetos y las matrices JSON no se registran.
--access_log	Si se especifica, la ruta al archivo local en el que se escribirán las entradas del registro de acceso.
--access_log_format	Formato de cadena para especificar el formato del registro de acceso. Si no se define, se usa la cadena de formato predeterminada. Para obtener información detallada sobre la gramática de formato, consulta la referencia de cadenas de formato.

Trace

Usa estas marcas para configurar los datos de seguimiento de ESPv2 que se envían a Stackdriver. Estas marcas solo se aplican cuando la monitorización está habilitada.

Bandera	Descripción
--disable_tracing	Inhabilita el rastreo. La monitorización está habilitada de forma predeterminada. Cuando está habilitado, ESPv2 toma una muestra de un pequeño número de solicitudes a tu API cada segundo para obtener trazas que envía a Stackdriver Trace. De forma predeterminada, se toma una muestra de 1 de cada 1000 solicitudes. Usa la marca --tracing_sample_rate para cambiar la frecuencia de muestreo.
--tracing_project_id	El ID de proyecto de Google para el seguimiento de Stackdriver. El seguimiento es un servicio de pago. Se facturará al proyecto especificado por el rastreo. De forma predeterminada, se factura el ID de proyecto del servicio ESPv2 implementado. El ID del proyecto se determina llamando al servidor de metadatos de la instancia Google Cloud al inicio. Si ESPv2 se implementa fuera de Google Cloud (con la marca --non_gcp ), el seguimiento se inhabilitará automáticamente a menos que se defina explícitamente esta marca.
--tracing_sample_rate	Define la frecuencia de muestreo de la traza con un valor entre 0.0 y 1.0. Este valor especifica la fracción de solicitudes que se muestrean. El valor predeterminado es 0,001, lo que equivale a 1 de cada 1000 solicitudes.
--tracing_incoming_context	Esta marca especifica qué encabezados HTTP se deben comprobar en el contexto de la traza. Los valores de la marca se separan con comas sin espacios. Ten en cuenta que el orden es importante: el contexto de la traza se derivará de la primera encabezado que coincida. Entre los posibles valores se incluyen traceparent, x-cloud-trace-context y grpc-trace-bin. Si se omite, se comprobarán los encabezados traceparent y x-cloud-trace-context (en ese orden). Consulta más información en Monitorizar tu API.
--tracing_outgoing_context	Define el encabezado de contexto de la traza en la solicitud enviada al servicio de backend. Esta marca especifica qué encabezado HTTP se debe definir. Los valores de la marca se separan con comas y sin espacios. Entre los posibles valores se incluyen traceparent, x-cloud-trace-context y grpc-trace-bin. Si se omite, se enviarán los encabezados traceparent y x-cloud-trace-context. Consulta más información en Monitorizar tu API.

Comprobación del estado

Usa estas marcas para configurar las comprobaciones del estado de ESPv2. La primera marca se puede usar para configurar un controlador de estado que responda a las llamadas de comprobación del estado. Las otras marcas se pueden usar para habilitar la comprobación del estado del backend de gRPC.

/tbody>

Bandera	Descripción
-z, --healthz	Define un endpoint de comprobación del estado. Por ejemplo, -z healthz hace que ESPv2 devuelva el código 200 para la ruta /healthz.
--health_check_grpc_backend	Habilita ESPv2 para que compruebe periódicamente el servicio de estado de gRPC de un backend especificado por la marca --backend. El backend debe usar el protocolo gRPC e implementar el protocolo de comprobación de estado de gRPC. El endpoint de comprobación del estado habilitado por la marca --healthz reflejará el resultado de la comprobación del estado del backend.
--health_check_grpc_backend_service	Especifica el nombre del servicio al llamar al protocolo de comprobación de estado gRPC del backend. El valor de esta marca solo se aplica cuando se usa la marca --health_check_grpc_backend. Es opcional. Si no se define, el valor predeterminado es una cadena vacía. Si el nombre del servicio está vacío, se consulta el estado general del servidor gRPC.
--health_check_grpc_backend_interval	Especifica el intervalo de comprobación y el tiempo de espera de la solicitud al llamar al servicio de comprobación del estado de gRPC del backend. El valor de esta marca solo se aplica cuando se usa la marca --health_check_grpc_backend. El valor predeterminado es 1 segundo. El formato aceptado es una secuencia de números decimales, cada uno con una fracción opcional y un sufijo de unidad, como "5s", "100ms" o "2m". Las unidades de tiempo válidas son "m" para minutos, "s" para segundos y "ms" para milisegundos.

Depuración

Usa estas marcas para configurar la depuración de ESPv2. Estas marcas se pueden usar para configurar un puerto de administrador de Envoy con el fin de obtener estadísticas y configuraciones, o bien para ejecutar Envoy en modo de depuración y escribir información de nivel de depuración en el registro.

Bandera	Descripción
--status_port, --admin_port	Habilita el administrador de Envoy de ESPv2 en este puerto. Consulta la referencia de la interfaz de administración de Envoy para obtener más información. El puerto de administrador está inhabilitado de forma predeterminada.
--enable_debug	Habilita los registros de nivel de depuración y añade encabezados de depuración.

Implementación sinGoogle Cloud

Si ESPv2 se implementa en un entorno que no es de Google Cloud , es posible que se necesiten las siguientes marcas.

Bandera	Descripción
--service_account_key	Especifica el archivo JSON de la clave de cuenta de servicio para acceder a los servicios de Google. Si se omite la opción, el proxy se pondrá en contacto con el servidor de metadatos Google Cloud para obtener un token de acceso.
--dns_resolver_addresses	Las direcciones de los resoluciones de DNS. Cada dirección debe tener el formato IP_ADDR o IP_ADDR:PORT y estar separada por un punto y coma (;). En el caso de IP_ADDR, se usará el puerto DNS predeterminado 52. Por ejemplo: --dns_resolver_addresses=127.0.0.1;127.0.0.2;127.0.0.3:8000) Si no se define, ESPv2 usará el resolvedor predeterminado configurado en /etc/resolv.conf.
--backend_dns_lookup_family	Define la familia de búsqueda de DNS para todos los back-ends. Las opciones son auto, v4only, v6only, v4preferred y all. El valor predeterminado es v4preferred. Tenga en cuenta que auto es un valor antiguo. Si asigna el valor auto a la marca, el comportamiento será equivalente al de v6preferred.
--non_gcp	De forma predeterminada, el proxy intenta conectarse al Google Cloud servidor de metadatos para obtener la ubicación de la VM en las primeras solicitudes. Para saltarte este paso, asigna el valor true a esta marca.

Pruebas locales

ESPv2 se puede implementar de forma local en tu estación de trabajo para hacer pruebas. Consulta Ejecutar el ESP localmente o en otra plataforma para obtener más información.

Usa estas marcas junto con las marcas de no implementaciónGoogle Cloud para facilitar la implementación local y las pruebas en la integración continua.

Bandera	Descripción
--service_json_path	Especifica una ruta para que ESPv2 cargue la configuración del servicio de endpoint. Con esta marca, ESPv2 usará una estrategia de lanzamiento "fija" y se ignorarán las siguientes marcas: --service --version --rollout_strategy Esta marca evitará que ESPv2 use la cuota de la API Service Management.
--enable_backend_address_override	Las direcciones de backend se pueden especificar con la marca --backend o con el campo backend.rule.address en la configuración del servicio. En el caso de los usuarios de OpenAPI, tenga en cuenta que el campo backend.rule.address se define en el campo address de la extensión x-google-backend. La configuración de servicio por operación backend.rule.address se suele especificar para el enrutamiento sin servidor. De forma predeterminada, el backend.rule.address tendrá prioridad sobre la marca --backend en cada operación. Habilita esta opción si quieres que la opción --backend tenga prioridad. Esto resulta útil si estás desarrollando en una estación de trabajo local. Después, puedes usar la misma configuración de servicio de producción, pero anular la dirección del backend mediante la marca --backend para hacer pruebas locales. Nota: Solo se modificará la dirección. El resto de los componentes de backend.rule se seguirán aplicando (fechas límite, autenticación de backend, traducción de rutas, etc.).

Extracción de IP de cliente

Usa estas marcas para configurar la extracción de la IP del cliente en ESPv2.

Bandera	Descripción
--envoy_use_remote_address	Configuración de Envoy HttpConnectionManager. Consulta la referencia de Envoy para obtener información detallada. El valor predeterminado es desactivado.
--envoy_xff_num_trusted_hops	Configuración de Envoy HttpConnectionManager. Consulta la referencia de Envoy para obtener información detallada. El valor predeterminado es 2.

Compatibilidad con CORS

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

Para habilitar la compatibilidad con CORS en ESPv2, incluya la opción --cors_preset y asígnele una de las siguientes marcas:

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

Cuando incluyes --cors_preset=basic o --cors_preset=cors_with_regex, ESPv2 hace lo siguiente:

• 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
  Access-Control-Max-Age: 1728000

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. Cuando definas esta opción en un archivo de configuración de Kubernetes, tendrás que añadir una barra invertida adicional para escapar ambas instancias de \ en la cadena. Por ejemplo: "--cors_preset","cors_with_regex", "--cors_allow_origin_regex","^https?://.+\\.example\\.com$" Cuando configures esta opción en la secuencia de comandos gcloud_build_image para Cloud Run, intenta no usar caracteres de escape ni barras invertidas, ya que es posible que no se transfieran correctamente de la secuencia de comandos de Bash al proxy al iniciarse. Usa clases de caracteres en lugar de metasecuencias. Por ejemplo: Original: \d Recommended: [0-9]

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
--cors_max_age	Define Access-Control-Max-Age en la duración especificada. El formato aceptable es una secuencia de números decimales, cada uno con un valor fraccionario opcional y un sufijo de unidad, como "300m", "1.5h" o "2h45m". Las unidades de tiempo válidas son "m" para minutos y "h" para horas. Si no se define ningún valor, el valor predeterminado es "480h". Ejemplo: --cors_preset=basic --cors_max_age=24h

Compatibilidad con TLS

Usa estas marcas para configurar ESPv2 de forma que use conexiones TLS.

Bandera	Descripción
--ssl_server_cert_path	Ruta del certificado de servidor del proxy. Cuando se configura, ESPv2 solo acepta conexiones seguras HTTP/1.x y HTTP/2 en listener_port. Requiere los archivos de certificado y clave "server.crt" y "server.key" en esta ruta.
--ssl_server_cipher_suites	Conjuntos de cifrado que se van a usar en las conexiones de descarga, especificados como una lista separada por comas. Consulta Configuración de conjuntos de cifrado.
--ssl_backend_client_cert_path	Ruta del certificado de cliente del proxy. Cuando se configura, ESPv2 habilita la autenticación TLS mutua para los back-ends HTTPS. Requiere los archivos de certificado y clave "client.crt" y "client.key" en esta ruta.
--ssl_backend_client_root_certs_file	Ruta de archivo de los certificados raíz que usa ESPv2 para verificar el certificado del servidor backend. Si no se especifica, ESPv2 usa "/etc/ssl/certs/ca-certificates.crt" de forma predeterminada.
--ssl_backend_client_cipher_suites	Conjuntos de cifrado que se van a usar en los back-ends HTTPS, especificados como una lista separada por comas. Consulta Configuración de conjuntos de cifrado.
--ssl_minimum_protocol	Versión mínima del protocolo TLS para la conexión del lado del cliente. Consulta este artículo.
--ssl_maximum_protocol	Versión máxima del protocolo TLS para la conexión del lado del cliente. Consulta este artículo.
--enable_strict_transport_security	Habilita HSTS (seguridad de transporte estricta mediante HTTP). Se añade el encabezado de respuesta "Strict-Transport-Security" con el valor "max-age=31536000; includeSubdomains;" a todas las respuestas.
--generate_self_signed_cert	Genera un certificado y una clave autofirmados al inicio y, a continuación, guárdalos en "/tmp/ssl/endpoints/server.crt" y "/tmp/ssl/endpoints/server.key". Esto resulta útil cuando solo se necesita un certificado autofirmado aleatorio para atender 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 y los reintentos de las llamadas HTTP remotas de ESPv2.

Bandera	Descripción
--http_request_timeout_s	Define el tiempo de espera en segundos de las solicitudes realizadas a servicios externos, excepto Backend y Google Service Control. Incluye Google Service Management, el servidor de metadatos y el servidor de gestión de identidades y accesos de Google. Debe ser > 0 y, si no se define, el valor predeterminado es 30 segundos.
--service_control_network_fail_policy	En caso de que se produzcan fallos en la red al conectarse al control de servicios de Google, las solicitudes se permitirán si esta marca está abierta. El valor predeterminado es open.
--service_control_check_timeout_ms	Define el tiempo de espera en milisegundos para la solicitud de comprobación del control de servicio. Debe ser > 0 y el valor predeterminado es 1000 si no se define.
--service_control_report_timeout_ms	Define el tiempo de espera en milisegundos para la solicitud Report de Service Control. Debe ser > 0 y el valor predeterminado es 1000 si no se define.
--service_control_quota_timeout_ms	Define el tiempo de espera en milisegundos para la solicitud de cuota de control de servicio. Debe ser > 0 y el valor predeterminado es 1000 si no se define.
--service_control_check_retries	Define el número de reintentos de la solicitud de comprobación de control de servicio. Debe ser >= 0 y el valor predeterminado es 3 si no se define.
--service_control_report_retries	Define el número de reintentos de la solicitud Report de Service Control. Debe ser >= 0 y el valor predeterminado es 5 si no se define ningún valor.
--service_control_quota_retries	Define el número de reintentos de la solicitud de cuota de control de servicios. Debe ser >= 0. Si no se define ningún valor, el valor predeterminado es 1.
--backend_retry_ons	Las condiciones en las que ESPv2 vuelve a intentar la conexión con los back-ends. Se pueden especificar una o varias condiciones retryOn mediante una lista separada por comas. El valor predeterminado es reset,connect-failure,refused-stream. Para inhabilitar los reintentos, asigna un valor vacío a esta marca. Consulta los siguientes enlaces para ver las condiciones aceptadas: x-envoy-retry-on x-envoy-retry-grpc-on
--backend_retry_num	Número de reintentos permitidos. Debe ser igual o superior a 0. El valor predeterminado es 1.

Transcodificación de gRPC

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

Bandera	Descripción
--transcoding_always_print_primitive_fields	Especifica si se deben imprimir campos primitivos para la transcodificación de grpc-json. De forma predeterminada, los campos primitivos con valores predeterminados se omitirán en la salida JSON. Por ejemplo, se omitirá un campo int32 definido en 0. Si asignas el valor true a esta marca, se anulará el comportamiento predeterminado y se imprimirán los campos primitivos independientemente de sus valores. El valor predeterminado es false.
--transcoding_always_print_enums_as_ints	Especifica si se deben imprimir las enumeraciones como números enteros para la transcodificación de grpc-json. De forma predeterminada, se renderizan como cadenas. El valor predeterminado es false.
--transcoding_stream_newline_delimited	Si es true, usa el delimitador de nueva línea para separar los mensajes de streaming de la respuesta. . Si es false, todos los mensajes de streaming de la respuesta se transcodifican en una matriz JSON.
--transcoding_case_insensitive_enum_parsing	Normalmente, los valores de enumeración de proto deben estar en mayúsculas cuando se usan en JSON. Asigna el valor true a esta marca si tu solicitud JSON usa valores de enumeración que no están en mayúsculas.
--transcoding_preserve_proto_field_names	Especifica si se deben conservar los nombres de los campos proto para la transcodificación de grpc-json. De forma predeterminada, protobuf generará nombres de campo JSON con la opción json_name o con minúsculas y mayúsculas, en ese orden. Si se define esta marca, se conservarán los nombres de campo originales. El valor predeterminado es false.
--transcoding_ignore_query_parameters	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-json. De forma predeterminada, el filtro de transcodificación 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 pueden asignar a un campo protobuf correspondiente en la transcodificación de grpc-json. Úsalo si no puedes controlar los parámetros de consulta y no los conoces de antemano. Si no, usa --transcoding_ignore_query_parameters. El valor predeterminado es false.
--transcoding_query_parameters_disable_unescape_plus	De forma predeterminada, los signos más "+" de los parámetros de consulta se convierten en espacios " " en la transcodificación de grpc-json. Esto se debe a que se admite HTML 2.0. Si no quieres que se muestre, asigna el valor "true" a esta marca para inhabilitar la función.

Modificación de solicitudes y respuestas

Usa estas marcas para configurar ESPv2 de forma que modifique parcialmente las solicitudes y las respuestas.

Bandera	Descripción
--add_request_header	Añade un encabezado HTTP a la solicitud antes de enviarla al backend upstream. Si el encabezado ya está en la solicitud, su valor se sustituirá por el nuevo. Admite variables personalizadas de Envoy. Este argumento se puede repetir varias veces para especificar varios encabezados. Por ejemplo: --add_request_header=key1=value1 --add_request_header=key2=value2.
--append_request_header	Añade un encabezado HTTP a la solicitud antes de enviarla al backend upstream. Si el encabezado ya está en la solicitud, se añadirá el nuevo valor. Admite variables personalizadas de Envoy. Este argumento se puede repetir varias veces para especificar varios encabezados. Por ejemplo: --append_request_header=key1=value1 --append_request_header=key2=value2.
--add_response_header	Añade un encabezado HTTP a la respuesta antes de enviarla al cliente de nivel inferior. Si el encabezado ya está en la respuesta, se sustituirá por el nuevo. Admite variables personalizadas de Envoy. Este argumento se puede repetir varias veces para especificar varios encabezados. Por ejemplo: --add_response_header=key1=value1 --add_response_header=key2=value2.
--append_response_header	Añade un encabezado HTTP a la respuesta antes de enviarla al cliente de nivel inferior. Si el encabezado ya está en la respuesta, se añadirá el nuevo. Admite variables personalizadas de Envoy. Este argumento se puede repetir varias veces para especificar varios encabezados. Por ejemplo: --append_response_header=key1=value1 --append_response_header=key2=value2.

Opciones de seguridad

Usa estas marcas para acotar aún más las solicitudes que permite ESPv2.

Bandera	Descripción
--underscores_in_headers	Permite que los nombres de encabezado que contengan guiones bajos se transfieran. El valor predeterminado es false. El carácter de subrayado se permite en los nombres de encabezado según la RFC-7230. Sin embargo, este comportamiento se implementa como medida de seguridad porque algunos sistemas tratan _ y - como intercambiables.
--envoy_connection_buffer_limit_bytes	Configura la cantidad máxima de datos que se almacenan en búfer para cada cuerpo de solicitud o respuesta, en bytes. Si no se define, Envoy decide el valor predeterminado. Consulta la configuración del listener de Envoy.
--disable_normalize_path	Inhabilita la normalización del encabezado HTTP path según RFC 3986. Te recomendamos que mantengas esta opción habilitada si tu backend realiza la normalización de rutas de forma predeterminada. En la siguiente tabla se muestran ejemplos de la solicitud path que recibirá el backend de ESPv2 en función de la configuración de esta marca. ----------------------------------------------------------------- | Request Path | Without Normalization | With Normalization | ----------------------------------------------------------------- | /hello/../world | Rejected | /world | | /%4A | /%4A | /J | | /%4a | /%4a | /J | ----------------------------------------------------------------- De forma predeterminada, ESPv2 normalizará las rutas. Inhabilita la función solo si el comportamiento afecta a tu tráfico. Nota: De acuerdo con RFC 3986, esta opción no elimina el carácter de escape de las barras codificadas con el símbolo de porcentaje. Consulta la marca --disallow_escaped_slashes_in_path para habilitar este comportamiento no conforme. Nota: La normalización de mayúsculas y minúsculas de RFC 3986 no se admite, aunque esta opción esté habilitada. Para obtener más información, consulta Información sobre las plantillas de ruta.
--disable_merge_slashes_in_path	Inhabilita la combinación de barras diagonales adyacentes en el encabezado HTTP path. Te recomendamos que mantengas esta opción habilitada si tu backend combina los datos de forma predeterminada. En la siguiente tabla se muestran ejemplos de la solicitud path que recibirá el backend de ESPv2 en función de la configuración de esta marca. ----------------------------------------------------------------- | Request Path | Without Normalization | With Normalization | ----------------------------------------------------------------- | /hello//world | Rejected | /hello/world | | /hello/// | Rejected | /hello | ----------------------------------------------------------------- De forma predeterminada, ESPv2 combinará las barras. Inhabilita la función solo si el comportamiento afecta a tu tráfico. Para obtener más información, consulta Información sobre las plantillas de ruta.
--disallow_escaped_slashes_in_path	No permite solicitudes con caracteres de barra invertida codificados con porcentaje: %2F o %2f se trata como / %5C o %5c se trata como \ Si está habilitada, el comportamiento depende del protocolo utilizado: En el caso de los back-ends de OpenAPI, las rutas de solicitud con barras con codificación de porcentaje escapadas se desescaparán automáticamente mediante una redirección. En el caso de los back-ends de gRPC, se rechazarán las rutas de solicitud con barras diagonales codificadas con porcentaje de escape (gRPC no admite redirecciones). Esta opción no cumple el estándar RFC 3986, por lo que está desactivada de forma predeterminada. Si tu backend no cumple el RFC 3986 y escapa las barras diagonales, debes habilitar esta opción en ESPv2. De esta forma, se evitan los ataques de confusión de rutas que provocan que no se apliquen los requisitos de seguridad. Para obtener más información, consulta Información sobre las plantillas de ruta.

Autenticación JWT

Usa estas marcas para configurar ESPv2 de forma que obtenga Jwks remotos con reintentos.

Bandera	Descripción
--jwks_fetch_num_retries	Especifica el número de reintentos en la política de reintentos de obtención de JWKS remota. El valor predeterminado es 0, es decir, no se vuelve a intentar.
--jwks_fetch_retry_back_off_base_interval_ms	Especifica el intervalo base del tiempo de espera exponencial de reintento de obtención de JWKS en milisegundos. Si no se define ningún valor, el valor predeterminado es 200 ms.
--jwks_fetch_retry_back_off_max_interval_ms	Especifica el intervalo máximo de tiempo de espera exponencial para reintentar la obtención de JWKS, en milisegundos. Si no se define ningún valor, el valor predeterminado es 32 s.
--jwks_cache_duration_in_s	Especifica la duración de la caché de claves públicas JWT en segundos. Si no se define, el valor predeterminado es 5 minutos.
--jwks_async_fetch_fast_listener	Solo se aplica cuando no se ha definido la marca --disable_jwks_async_fetch. Esta marca determina si ESPv2 esperará a que se complete la jwksobtención inicial antes de vincular el puerto del listener. Si es "false", esperará. El valor predeterminado es "false".
--jwt_cache_size	Especifica el número de tokens JWT únicos como tamaño máximo de la caché de JWT. La caché solo almacena tokens verificados. Si es 0, la caché de JWT está inhabilitada. Esta marca limita el uso de memoria de la caché de JWT. La memoria utilizada por la caché es aproximadamente (tamaño del token + 64 bytes) por token. Si no se especifica, el valor predeterminado es 100.000.
--disable_jwt_audience_service_name_check	Normalmente, el campo aud de JWT se compara con las audiencias especificadas en el campo x-google-audiences de OpenAPI. Esta marca cambia el comportamiento cuando no se especifica el campo x-google-audiences. Si no se especifica el campo x-google-audiences y no se usa esta marca, se usa el nombre del servicio para comprobar el campo aud del JWT. Si se usa esta marca, no se comprobará el campo aud de JWT.

Siguientes pasos

Puedes informarte sobre lo siguiente:

• Migrar a Extensible Service Proxy V2
• Extensiones de OpenAPI