Se usó la API de Cloud Translation para traducir esta página.
Switch to English

Opciones de inicio del proxy de servicio extensible V2

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
  • 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

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.

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 GCP en el inicio. Si el ESPv2 se implementa fuera de GCP (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.

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

Si se omite, se verificará el encabezado traceparent.

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á el encabezado traceparent.

Para obtener más información, consulta Haz un seguimiento de tu API.

Depuración

Usa estas marcas con el fin de configurar las verificaciones de estado y la depuración para el ESPv2. 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.

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.
--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 para plataformas que no sean GCP

Si el ESPv2 se implementa en un entorno que no es de Google Cloud Platform (GCP), 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 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 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 de la 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 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$"

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"

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

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.

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

Opciones de seguridad

Usa estas marcas para definir aún mejor las solicitudes que permite el ESPv2.

Flag Descripción
--underscores_in_headers

Permite que se transfieran los nombres de encabezado que contienen guiones bajos. La configuración predeterminada es false.

El carácter de guion bajo está permitido en los nombres de encabezado mediante RFC-7230. Sin embargo, este comportamiento se implementa como una medida de seguridad porque algunos sistemas tratan a _ y - como intercambiables.

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

¿Qué sigue?

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