Opciones de inicio del proxy de servicio extensible V2

OpenAPI   |  gRPC

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

Establece marcas de configuración

El método para establecer marcas de configuración de ESPv2 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 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 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.

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.

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

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

Marcas de configuración de ESPv2

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

• Configuración para plataformas sin servidores
• Logging
• Seguimiento
• Verificación de estado
• Depuración
• Pruebas locales
• Implementación que no es de Google Cloud
• Extracción del IP de 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 de JWT

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

Configuración para plataformas sin servidores

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

Nota: Para los usuarios de Kubernetes, NO rodees los valores de los campos con 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.

``

Marca	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.

Registros

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

Marca	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 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 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 implementado. El ID del proyecto se determina mediante una llamada al servidor de metadatos de la instancia de Google Cloud en el inicio. Si el ESPv2 se implementa fuera de Google Cloud (con la marca --non_gcp), el seguimiento se inhabilitará automáticamente, a menos que esta marca esté configurada de manera explícita.
--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	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. Ten en cuenta que el orden es importante: el contexto de seguimiento se derivará del primer encabezado que coincida. Los valores posibles son traceparent, x-cloud-trace-context y grpc-trace-bin. Si se omite, se revisarán los encabezados traceparent y x-cloud-trace-context (en orden). Para obtener más información, consulta Haz un seguimiento de tu API.
--tracing_outgoing_context	Configura el encabezado del contexto de seguimiento en la solicitud enviada al servicio de backend. Esta marca especifica los encabezado HTTP que se deben configurar, con valores de marcas separados por comas y sin espacios. Los valores posibles son traceparent, x-cloud-trace-context y grpc-trace-bin. Si se omite, se enviarán los encabezados traceparent y x-cloud-trace-context. Para obtener más información, consulta Haz un seguimiento de tu API.

Verificación de estado

Usa estas marcas con el fin de configurar las verificaciones de estado para ESPv2. La primera marca se puede usar para configurar un controlador de estado que responda a las llamadas de verificación de estado. Las otras marcas se pueden usar para habilitar la verificación de estado para el backend de gRPC.

/tbody>

Marca	Descripción
-z, --healthz	Define un extremo de verificación de estado. Por ejemplo, -z healthz hace que el ESPv2 muestre el código 200 para la ruta de acceso /healthz.
--health_check_grpc_backend	Habilita el ESPv2 para verificar de forma periódica el servicio de estado de gRPC del backend especificado por la marca --backend. El backend debe usar el protocolo gRPC y, luego, implementar el Protocolo de verificación de estado de gRPC. El extremo de verificación de estado habilitado por la marca --healthz reflejará el resultado de la verificación de estado del backend.
--health_check_grpc_backend_service	Especifica el nombre del servicio cuando llames al protocolo de verificación de estado de 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 configura, el valor predeterminado está vacío. Un nombre de servicio vacío es para consultar el estado general del servidor de gRPC.
--health_check_grpc_backend_interval	Especifica el intervalo de comprobación y el tiempo de espera de la solicitud cuando llames al servicio de 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 los minutos, “s” para los segundos y “ms” para los milisegundos.

Depuración

Usa estas marcas con el fin de configurar la depuración para el ESPv2. Estas marcas se pueden usar con el fin de configurar 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 a fin de escribir información a nivel de depuración en el registro.

Marca	Descripción
--status_port, --admin_port	Habilita el administrador de Envoy versión del ESPv2 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 que no es de Google Cloud

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

Marca	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 Google Cloud para recuperar un token de acceso.
--dns_resolver_addresses	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, ESPv2 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, v6only, v4preferred y all. El valor predeterminado es v4preferred. Ten en cuenta que auto es un valor heredado. Si estableces la marca en auto, obtendrás un comportamiento equivalente a v6preferred.
--non_gcp	De forma predeterminada, el proxy intenta conectarse al servidor de metadatos de Google Cloud para obtener la ubicación de la VM en las primeras solicitudes. Para omitir este paso, configura esta marca como verdadera.

Pruebas locales

El ESPv2 se puede implementar de forma local en tu estación de trabajo para realizar pruebas. Consulta Ejecuta el ESP de forma local o en otra plataforma para obtener más detalles.

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

Marca	Descripción
--service_json_path	Especifica una ruta para que el ESPv2 cargue la configuración del servicio del extremo. Con esta marca, el ESPv2 usará una estrategia de lanzamiento “fija” y se ignorarán las siguientes marcas: --service --version --rollout_strategy Esta marca evitará que el ESPv2 use la cuota de la API de Service Management.
--enable_backend_address_override	Las direcciones de backend se pueden especificar mediante la marca --backend o el campo backend.rule.address en la configuración de servicio. Para los usuarios de OpenAPI, ten en cuenta que el campo backend.rule.address se establece mediante el campo address en la extensión x-google-backend. Por lo general, la configuración del servicio por operación backend.rule.address se especifica para el enrutamiento sin servidores. De forma predeterminada, backend.rule.address tendrá prioridad sobre la marca --backend para cada operación individual. Habilita esta marca si deseas que la marca --backend tenga prioridad. Esto es útil si te estás desarrollando en una estación de trabajo local. Luego, puedes usar la misma configuración del servicio de producción, pero anular la dirección de backend a través de la marca --backend para pruebas locales. Nota: Solo se anulará la dirección. Se aplicarán todos los demás componentes de backend.rule (plazo, autenticación de backend, traducción de ruta, etcétera).

Extracción del IP de cliente

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

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

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

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

Cuando incluyes --cors_preset=basic o --cors_preset=cors_with_regex, sucede lo siguiente con el ESPv2:

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

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$" Cuando configuras esta opción en la secuencia de comandos de gcloud_build_image para Cloud Run, evita usar caracteres de escape y barras inversas, es posible que no se pasen de forma correcta de la secuencia de comandos de Bash al proxy en el inicio. Usa clases de caracteres en lugar de metaetiquetas. Por ejemplo: Original: \d Recommended: [0-9]

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
--cors_max_age	Configura Access-Control-Max-Age con 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 los minutos y “h” para las horas. Si no se configura, el valor predeterminado es "480h". Ejemplo: --cors_preset=basic --cors_max_age=24h

Compatibilidad con TLS

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

Marca	Descripción
--ssl_server_cert_path	Es la ruta de acceso del certificado del servidor del proxy. Cuando se configura, el ESPv2 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_server_cipher_suites	Conjuntos de algoritmos de cifrado para usar en conexiones descendentes, especificados como una lista separada por comas Consulta la configuración del conjunto de algoritmos de cifrado.
--ssl_backend_client_cert_path	Es la ruta de acceso del certificado del cliente del proxy. Cuando se configura, el ESPv2 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 para verificar el certificado de servidor de backend. Si no se especifica, el ESPv2 usa "/etc/ssl/certs/ca-certificates.crt" de forma predeterminada.
--ssl_backend_client_cipher_suites	Conjuntos de algoritmos de cifrado para usar en backends HTTPS, especificados como una lista separada por comas. Consulta la configuración del conjunto de algoritmos de cifrado.
--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). Encabezado de respuesta “Strict-Transport-Security” con el valor “max-age=31536000; includeSubdomains;” se agrega a todas las respuestas.
--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.

Marca	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.
--backend_retry_ons	Las condiciones en las que el ESPv2 vuelve a intentarlo en los backends. Se pueden especificar una o más condiciones retryOn con una lista separada por comas. El predeterminado es reset,connect-failure,refused-stream. Para inhabilitar los reintentos, configura esta marca como vacía. Consulta los siguientes vínculos para conocer las condiciones aceptadas: x-envoy-retry-on x-envoy-retry-grpc-on
--backend_retry_num	La cantidad permitida de reintentos. Debe ser >= 0; el valor predeterminado es 1.

Transcodificación de gRPC

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

Marca	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_stream_newline_delimited	Si es verdadero, usa el delimitador de línea nueva para separar los mensajes de transmisión de respuestas. Si es falso, todos los mensajes de transmisión de respuesta se transcodifican en un array JSON.
--transcoding_case_insensitive_enum_parsing	Por lo general, los valores de enum de proto deben estar en mayúsculas cuando se usan en JSON. Configura esta marca como verdadera 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 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.
--transcoding_query_parameters_disable_unescape_plus	De forma predeterminada, los signos más "+" en los parámetros de consulta no se escapan en el espacio " " en la transcodificación grpc-json. Esto es para la compatibilidad con HTML 2.0. Si no deseas hacerlo, configura esta marca como true para inhabilitar esta función.

Modificación de solicitudes y respuestas

Usa estas marcas para configurar el ESPv2 a fin de modificar solicitudes y respuestas de forma parcial.

Marca	Descripción
--add_request_header	Agrega un encabezado HTTP a la solicitud antes de enviarla al backend ascendente. Si el encabezado ya está incluido en la solicitud, será reemplazado por el valor 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	Agrega un encabezado HTTP a la solicitud antes de enviarla al backend ascendente. Si el encabezado ya está incluido en la solicitud, se agregará el valor nuevo. 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	Agrega un encabezado HTTP a la respuesta antes de enviarlo al cliente descendente. Si el encabezado ya está incluido en la respuesta, se reemplazará 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	Adjunta un encabezado HTTP a la respuesta antes de enviarla al cliente descendente. Si el encabezado ya está incluido en la respuesta, se agregará 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 definir aún mejor las solicitudes que permite el ESPv2.

Marca	Descripción
--underscores_in_headers	Permite que los nombres de encabezado contengan guiones bajos para pasar. La configuración predeterminada es false. El carácter de guion bajo está permitido en los nombres de encabezado deRFC 7230. Sin embargo, este comportamiento se implementa como una 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 configura, Envoy decide de forma predeterminada. Consulta Configuración del objeto de escucha de Envoy.
--disable_normalize_path	Inhabilita la normalización del encabezado path HTTP de acuerdo con RFC 3986. Recomendamos mantener esta opción habilitada si tu backend realiza la normalización de rutas de forma predeterminada. En la siguiente tabla, se proporcionan ejemplos de la solicitud path que el backend recibirá del ESPv2 según 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, el ESPv2 normalizará las rutas de acceso. Inhabilita la función solo si tu tráfico se ve afectado por el comportamiento. Nota: Después de RFC 3986, esta opción no quita los caracteres de barra codificados por porcentaje. Consulta la marca --disallow_escaped_slashes_in_path para habilitar este comportamiento que no cumple con las políticas. Nota: No se admite la normalización de casos de RFC 3986, incluso si esta opción está habilitada. Para obtener más detalles, consulta Información sobre las plantillas de ruta.
--disable_merge_slashes_in_path	Inhabilita la combinación de barras diagonales en el encabezado HTTP path. Te recomendamos mantener esta opción habilitada si tu backend realiza la combinación de forma predeterminada. En la siguiente tabla, se proporcionan ejemplos de la solicitud path que el backend recibirá del ESPv2 según la configuración de esta marca. ----------------------------------------------------------------- | Request Path | Without Normalization | With Normalization | ----------------------------------------------------------------- | /hello//world | Rejected | /hello/world | | /hello/// | Rejected | /hello | ----------------------------------------------------------------- De forma predeterminada, el ESPv2 combinará barras. Inhabilita la función solo si tu tráfico se ve afectado por el comportamiento. Para obtener más detalles, consulta Información sobre las plantillas de ruta.
--disallow_escaped_slashes_in_path	No permite solicitudes con caracteres de barra codificados por porcentaje con escape: %2F o %2f se tratan como un / %5C o %5c se tratan como un \ Cuando está habilitado, el comportamiento depende del protocolo que se usa: Para los backends de OpenAPI, las rutas de solicitud con barras codificadas en porcentaje con escape se quitarán automáticamente mediante un redireccionamiento. Para los backends de gRPC, se rechazarán las rutas de solicitud con barras codificadas en porcentaje con escape (gRPC no admite redireccionamientos). Esta opción no cumple con RFC 3986, por lo que está desactivada de forma predeterminada. Si tu backend no cumple con RFC 3986 y omite las barras, debes habilitar esta opción en el ESPv2. Esto evitará los ataques de confusión en la ruta que generen la aplicación de los requisitos de seguridad. Para obtener más detalles, consulta Información sobre las plantillas de ruta.

Autenticación de JWT

Usa estas marcas para configurar el ESPv2 a fin de recuperar JWKS remotos con reintentos.

Marca	Descripción
--jwks_fetch_num_retries	Especifica la cantidad de reintentos en la política de reintento de recuperación de JWKS remoto. El valor predeterminado es 0, no reintentar.
--jwks_fetch_retry_back_off_base_interval_ms	Especifica el intervalo base de retirada exponencial de reintentos de recuperación de JWKS en milisegundos. El valor predeterminado es 200 ms, si no se configura.
--jwks_fetch_retry_back_off_max_interval_ms	Especifica el intervalo máximo de retirada exponencial de reintentos de recuperación de JWKS en milisegundos. El valor predeterminado es 32 s si no se establece.
--jwks_cache_duration_in_s	Especifica la duración de la caché de clave pública de JWT en segundos. El valor predeterminado es 5 minutos, si no se configura.
--jwks_async_fetch_fast_listener	Solo se aplica cuando no se establece la marca --disable_jwks_async_fetch. Esta marca determina si el ESPv2 esperará la recuperación inicial de jwks para completar antes de vincular el puerto del objeto de escucha. Si es falso, esperará. La configuración predeterminada es False.
--jwt_cache_size	Especifica la cantidad de tokens de JWT únicos como el 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 la memoria para la caché JWT. La memoria caché utilizada es de aproximadamente (tamaño del token + 64 bytes) por token. Si no se especifica, el valor predeterminado es 100000.
--disable_jwt_audience_service_name_check	Por lo general, el campo aud de JWT se compara con los públicos especificados en el campo x-google-audiences de OpenAPI. Esta marca cambia el comportamiento cuando no se especifica el campo x-google-audiences. Cuando no se especifica el campo x-google-audiences y no se usa esta marca, se usa el nombre del servicio para verificar el campo aud de JWT. Si se usa esta marca, el campo aud de JWT no se verificará.

¿Qué sigue?

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

• Migra al proxy de servicio extensible V2
• Extensiones de OpenAPI