Cómo configurar una extensión de ruta

Service Extensions permite que los balanceadores de cargas de aplicaciones compatibles usen complementos o envíen llamadas a servicios de backend para insertar procesamiento personalizado en la ruta de procesamiento. Las extensiones de ruta se ejecutan en la ruta de procesamiento de solicitudes cuando el balanceador de cargas recibe encabezados de solicitud y antes de que evalúe el mapa de URL. En esta página, se describe cómo configurar las extensiones de ruta.

Para obtener una descripción general de las extensiones del balanceador de cargas de aplicaciones, consulta Descripción general de las extensiones de Cloud Load Balancing.

Una extensión de ruta para un balanceador de cargas de aplicaciones apunta a los siguientes recursos:

  • Regla de reenvío a la que se adjuntará
  • Un complemento o un servicio de backend de llamada cuyos backends ejecutan la API de gRPC de ext_proc

Una extensión de ruta agrupa los servicios de extensión relacionados en una cadena. Puedes configurar complementos y textos destacados en la misma cadena de extensiones. La cadena de extensión selecciona el tráfico en el que se actuará con las condiciones de coincidencia de Common Expression Language (CEL). El balanceador de cargas evalúa una solicitud en función de las condiciones de coincidencia de una cadena de forma secuencial. Cuando una solicitud coincide con las condiciones definidas por una cadena, todas las extensiones de la cadena actúan sobre la solicitud. Solo una cadena coincide con una solicitud determinada.

La extensión hace referencia a la regla de reenvío del balanceador de cargas a la que se adjuntará. Después de configurar el recurso, el balanceador de cargas comienza a enviar solicitudes coincidentes a los servicios de extensión.

Para obtener información sobre los límites relacionados con las extensiones del balanceador de cargas de aplicaciones, consulta la página Cuotas y límites.

Configuración con complementos

En esta sección, se usa un ejemplo para mostrarte cómo configurar una extensión de ruta con un complemento que reescribe el encabezado de la solicitud :host en service-extensions.com cuando la ruta coincide con /extensions. El host anterior y el host recién configurado se asignan a servicios de backend en diferentes regiones, lo que demuestra el comportamiento de enrutamiento.

Todos los recursos de extensión que hacen referencia a un complemento determinado deben ser del mismo tipo. Las extensiones también deben tener el mismo esquema de balanceo de cargas. No puedes configurar extensiones de Cloud Load Balancing con complementos que ya se usan en las extensiones de Media CDN.

Antes de comenzar

  1. Crea un complemento que contenga tu código personalizado.

  2. Crea y configura un balanceador de cargas de aplicaciones que admita complementos de extensión de rutas.

    Sigue las instrucciones de la página Configura un balanceador de cargas de aplicaciones interno entre regiones con backends de grupos de instancias de VM para todos los pasos, excepto los siguientes:

    • Nombra el servicio de backend como service-one.
    • El punto service-one apunta a una instancia de máquina virtual (VM) en la región A.
    • De forma predeterminada, el punto gl7-gilb-url-map apunta a service-one.

  3. Configura un servicio de backend adicional, service-two, y dirígelo a una VM en la región B.

  4. Al mapa de URL, agrega un comparador de rutas de acceso que apunte a service-two. Usa el comando gcloud compute url-maps add-path-matcher con los siguientes valores de muestra:

      gcloud compute url-maps add-path-matcher gl7-gilb-url-map \
      --path-matcher-name=rewrite-host \
      --default-service=service-two \
      --new-hosts=service-extensions.com \
      --location=global

  5. Configura una forma de enviar solicitudes de prueba a tu servicio (por ejemplo, ejecutando curl). Si usas un balanceador de cargas interno, crea una VM de cliente para realizar pruebas.

Configura una extensión de ruta con un complemento

  1. Comprueba el comportamiento antes de configurar una extensión.

    1. Verifica que una solicitud sin una ruta explícita vaya a la región A:

      curl FORWARDING_RULE_IP

      Reemplaza FORWARDING_RULE_IP por la dirección IP de la regla de reenvío. Para encontrar la dirección IP, usa el comando gcloud compute forwarding-rules describe.

      El resultado es similar al siguiente y muestra que la página se entrega desde una VM en region A:

      Page served from region-A-vm

    2. Verifica que no haya coincidencias para /extensions en el mapa de URL:

      curl FORWARDING_RULE_IP/extensions

      Reemplaza FORWARDING_RULE_IP por la dirección IP de la regla de reenvío. Para encontrar la dirección IP, usa el comando gcloud compute forwarding-rules describe.

      El resultado indica que no hay ninguna coincidencia para /extensions en el mapa de URL. El resultado es similar a lo siguiente:

      <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>404 Not Found</title>
</head><body>
...

  2. Configura la extensión de ruta.

    Console

    1. En la consola de Google Cloud , ve a la página Extensiones de servicio.

      Ir a Extensiones del servicio

    2. Haz clic en Crear extensión.

      Se abrirá un asistente que te guiará por algunos pasos iniciales.

    3. En el producto, selecciona Load Balancing. Luego, haz clic en Continuar.

      Aparecerá una lista de los balanceadores de cargas de aplicaciones admitidos.

    4. En el tipo de balanceador de cargas, selecciona Balanceador de cargas de aplicaciones interno entre regiones. Luego, haga clic en Continuar.

    5. En el tipo de extensión, selecciona Extensiones de ruta y, luego, haz clic en Continuar.

    6. Para abrir el formulario Crear extensión, haz clic en Continuar.

      En el formulario Crear extensión, observa que las selecciones anteriores, que aparecen en la parte superior de la página, no se pueden editar.

    7. En la sección Básicos, haz lo siguiente:

      1. Especifica un nombre único para la extensión.

        El nombre debe comenzar con una letra minúscula seguida por un máximo de 62 letras minúsculas, números o guiones, y no puede terminar con un guion.

      2. Opcional: Ingresa una breve descripción sobre la extensión con un máximo de 1,024 caracteres.

      3. Opcional: En la sección Etiquetas, haz clic en Agregar etiqueta. Luego, en la fila que aparece, haz lo siguiente:

        • En Clave, ingresa un nombre de clave.
        • En Valor, ingresa un valor para la clave.

        Para agregar más pares clave-valor, haz clic en Agregar etiqueta. Puedes agregar un máximo de 64 pares clave-valor.

        Para obtener más información sobre las etiquetas, consulta Crea y actualiza etiquetas para proyectos.

    8. En Reglas de reenvío, selecciona una o más reglas de reenvío para asociarlas con la extensión, por ejemplo, cr-ilb-forwarding-rule.

      No se pueden seleccionar las reglas de reenvío que ya están asociadas con otra extensión y aparecen inhabilitadas.

    9. En Cadenas de extensiones, agrega una o más cadenas de extensiones para ejecutar una solicitud coincidente.

      Para agregar una cadena de extensiones, haz lo siguiente y, luego, haz clic en Listo:

      • En Cadena de extensión nueva, especifica un nombre único.

        El nombre debe cumplir con RFC-1034, usar solo letras minúsculas, números y guiones, y tener una longitud máxima de 63 caracteres. Además, el primer carácter debe ser una letra y el último debe ser una letra o un número.

      • Para que coincidan las solicitudes en las que se ejecuta la cadena de extensión, en Condición de coincidencia, especifica una expresión de Common Expression Language (CEL), por ejemplo, request.path.startsWith("/extensions").

        Para obtener más información sobre las expresiones de CEL, haz clic en Obtener ayuda con la sintaxis o consulta la referencia del lenguaje del comparador de CEL.

      • Agrega una extensión para que se ejecute en una solicitud coincidente. En el caso de las extensiones de ruta, solo puedes especificar una extensión.

        En Extensiones, haz lo siguiente y, luego, haz clic en Listo:

        • En Tipo de programabilidad, selecciona Complementos.

        • En Nombre de la extensión, especifica un nombre único.

          El nombre debe cumplir con la RFC-1034, usar solo letras minúsculas, números y guiones, y tener una longitud máxima de 63 caracteres. Además, el primer carácter debe ser una letra y el último, una letra o un número.

        • En Complemento, selecciona un complemento creado con extensiones de servicio para el mismo producto y tipo de extensión.

        • En Forward headers, haz clic en Add header y, luego, agrega encabezados HTTP para reenviar a la extensión (desde el cliente o el backend). Si no se especifica un encabezado, se envían todos.

        • Opcional: Si la extensión agota el tiempo de espera o falla, y deseas que continúe el procesamiento de la solicitud o la respuesta, selecciona Habilitado en Fail open.

          De forma predeterminada, la opción Fail open no está seleccionada. En este caso, cuando se produce un error, se detiene el procesamiento de la solicitud o la respuesta. Si no se entregaron los encabezados de respuesta al cliente de nivel inferior, se devuelve un código de estado HTTP 500 genérico al cliente. Si se entregaron los encabezados de respuesta, se restablece el flujo HTTP al cliente.

          La opción predeterminada de mantener Fail open sin seleccionar es preferible cuando se prioriza la seguridad o la integridad. Habilitar Fail open, en especial para las operaciones no críticas, ayuda a priorizar la disponibilidad.

    10. Haz clic en Crear extensión.

    gcloud

    1. Define el complemento en un archivo YAML y asócialo con una regla de reenvío global, por ejemplo, cr-ilb-forwarding-rule.

      cat >route-plugin.yaml <<EOF
    name: route-ext
    forwardingRules:
    - https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/forwardingRules/cr-ilb-forwarding-rule
    loadBalancingScheme: INTERNAL_MANAGED
    extensionChains:
    - name: "chain1"
      matchCondition:
        celExpression: 'request.path.startsWith("/extensions")'
      extensions:
      - name: 'ext1'
        service: projects/PROJECT_ID/locations/LOCATION/wasmPlugins/WASM_PLUGIN
        failOpen: false
        supportedEvents:
        - REQUEST_HEADERS
EOF

      Reemplaza lo siguiente:

      • PROJECT_ID: la ID del proyecto
      • REGION: Es la región de la regla de reenvío. El valor debe coincidir con el valor especificado para la ubicación del complemento.
      • LOCATION: Es la ubicación del complemento como global o una región.
      • WASM_PLUGIN: Es el ID o el nombre completamente calificado del complemento.

    2. Importa la extensión de ruta. Usa el comando gcloud service-extensions lb-route-extensions import con los siguientes valores de muestra.

      gcloud service-extensions lb-route-extensions import route-ext \
    --source=route-plugin.yaml \
    --location=global

    Después de crear una extensión de ruta, el nuevo complemento tarda un poco en distribuirse en todas las ubicaciones. La hora puede variar según la ubicación, ya que el complemento no se entrega a todas las ubicaciones de forma simultánea.

  3. Para verificar que la extensión de ruta funcione según lo previsto, usa el mismo comando curl:

    curl FORWARDING_RULE_IP/extensions

    El resultado es similar al siguiente y muestra que la página se entrega desde una VM en region B:

    Page served from region-B-vm

    Para verificar que el complemento solo se ejecute para las solicitudes con el prefijo de ruta /extension, repite el comando curl sin una ruta.

    curl FORWARDING_RULE_IP

    El resultado es similar a lo siguiente:

    Page served from region-A-vm

Configuración con textos destacados

En esta sección, se muestra cómo configurar una extensión de ruta con una llamada.

Antes de comenzar

Crea los recursos necesarios como se describe en Configura un servicio de backend de texto destacado.

Configura una extensión de ruta con un texto destacado

En el siguiente ejemplo, se muestra cómo configurar una extensión de ruta para que se llame cuando la ruta coincida con /extensions. El servidor de llamadas de ruta en callout-vm cambia el encabezado Host a service-extensions.com, establece la ruta de acceso en / y, luego, envía una instrucción al balanceador de cargas para que vuelva a calcular la ruta. Luego, el tráfico fluye a l7-ilb-backend-service2 en lugar de l7-ilb-backend-service.

  1. Verifica si hay una coincidencia para /extensions en el mapa de URL.

    1. Ejecuta el siguiente comando curl en la regla de reenvío de la VM del cliente:

      curl FORWARDING_RULE_IP/extensions

      Reemplaza FORWARDING_RULE_IP por la dirección IP de la regla de reenvío. Para encontrar la dirección IP, usa el comando gcloud compute forwarding-rules describe.

      El resultado indica que no hay ninguna coincidencia para /extensions en el mapa de URL. El resultado es similar a lo siguiente:

      <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>404 Not Found</title>
</head><body>
...

  2. Configura la extensión de ruta.

    Console

    1. En la consola de Google Cloud , ve a la página Extensiones de servicio.

      Ir a Extensiones del servicio

    2. Haz clic en Crear extensión.

      Se abrirá un asistente que te guiará por algunos pasos iniciales.

    3. En el producto, selecciona Load Balancing. Luego, haz clic en Continuar.

      Aparecerá una lista de los balanceadores de cargas de aplicaciones admitidos.

    4. Selecciona un tipo de balanceador de cargas. En el caso de los balanceadores de cargas regionales, también debes especificar la región. Haz clic en Continuar.

    5. En el tipo de extensión, selecciona Extensiones de ruta y, luego, haz clic en Continuar.

    6. Para abrir el formulario Crear extensión, haz clic en Continuar.

      En el formulario Crear extensión, observa que las selecciones anteriores, que aparecen en la parte superior de la página, no se pueden editar.

    7. En la sección Básicos, haz lo siguiente:

      1. Especifica un nombre único para la extensión.

        El nombre debe comenzar con una letra minúscula seguida por un máximo de 62 letras minúsculas, números o guiones, y no puede terminar con un guion.

      2. Opcional: Ingresa una breve descripción sobre la extensión con un máximo de 1,024 caracteres.

      3. Opcional: En la sección Etiquetas, haz clic en Agregar etiqueta. Luego, en la fila que aparece, haz lo siguiente:

        • En Clave, ingresa un nombre de clave.
        • En Valor, ingresa un valor para la clave.

        Para agregar más pares clave-valor, haz clic en Agregar etiqueta. Puedes agregar un máximo de 64 pares clave-valor.

        Para obtener más información sobre las etiquetas, consulta Crea y actualiza etiquetas para proyectos.

    8. En Reglas de reenvío, selecciona una o más reglas de reenvío para asociarlas con la extensión, por ejemplo, l7-ilb-forwarding-rule.

      No se pueden seleccionar las reglas de reenvío que ya están asociadas con otra extensión y aparecen inhabilitadas.

    9. En Cadenas de extensiones, agrega una o más cadenas de extensiones para ejecutar una solicitud coincidente.

      Para agregar una cadena de extensión, haz lo siguiente y, luego, haz clic en Listo.

      • En Cadena de extensión nueva, especifica un nombre único.

        El nombre debe cumplir con el RFC-1034, usar solo letras minúsculas, números y guiones, y tener una longitud máxima de 63 caracteres. Además, el primer carácter debe ser una letra y el último debe ser una letra o un número.

      • Para que coincidan las solicitudes en las que se ejecuta la cadena de extensión, en Condición de coincidencia, especifica una expresión de Common Expression Language (CEL), por ejemplo, request.path.startsWith("/extensions").

        Para obtener más información sobre las expresiones de CEL, haz clic en Obtener ayuda con la sintaxis o consulta la referencia del lenguaje del comparador de CEL.

      • Agrega una extensión para que se ejecute en una solicitud coincidente. En el caso de las extensiones de ruta, solo puedes especificar una extensión.

        En Extensiones, haz lo siguiente y, luego, haz clic en Listo:

        • En Tipo de programabilidad, selecciona Textos destacados.

        • En Nombre de la extensión, especifica un nombre único.

          El nombre debe cumplir con la RFC-1034, usar solo letras minúsculas, números y guiones, y tener una longitud máxima de 63 caracteres. Además, el primer carácter debe ser una letra y el último, una letra o un número.

        • Para Authority, ingresa el encabezado authority de la solicitud gRPC que se envió desde el balanceador de cargas al servicio de extensión.

        • En Servicio de backend, selecciona un servicio de backend creado siguiendo las instrucciones en Configura un servicio de backend de llamada.

        • En Tiempo de espera, especifica un valor entre 10 y 1,000 milisegundos, después de lo cual se agotará el tiempo de espera de un mensaje en la transmisión mientras el balanceador de cargas sigue esperando una respuesta del servicio ext_proc.

        • En Forward headers, haz clic en Add header y, luego, agrega encabezados HTTP para reenviar a la extensión (desde el cliente o el backend). Si no se especifica un encabezado, se envían todos.

        • Opcional: Si la extensión agota el tiempo de espera o falla, y deseas que continúe el procesamiento de la solicitud o la respuesta, selecciona Habilitado en Fail open. También se ejecutan las extensiones posteriores de la cadena.

          De forma predeterminada, la opción Fail open no está seleccionada. En este caso, cuando se produce un error, se detiene el procesamiento de la solicitud o la respuesta. Si no se entregaron los encabezados de respuesta al cliente de nivel inferior, se devuelve un código de estado HTTP 500 genérico al cliente. Si se entregaron los encabezados de respuesta, se restablece el flujo HTTP al cliente.

          La opción predeterminada de mantener Fail open sin seleccionar es preferible cuando se prioriza la seguridad o la integridad. Habilitar Fail open, en especial para las operaciones no críticas, ayuda a priorizar la disponibilidad.

        • En Metadatos, haz clic en Agregar metadatos y especifica valores de muestra como se sugiere. En Clave, especifica key y, en Valor, especifica value.

          Haz clic en Agregar metadatos para agregar otro par clave-valor. En Clave, especifica fr y, en Valor, especifica forwarding_rule_id.

          El campo Metadata te permite pasar cualquier información adicional del balanceador de cargas al servidor de extensiones. Los metadatos se envían en un mensaje ProcessingRequest y se codifican como protobuf.Struct. Todo el texto dentro de los metadatos que coincida con el ID de regla de reenvío especificado se reemplaza por la URL del recurso completamente calificada de la regla de reenvío asociada con la solicitud del cliente.

          El tamaño total de los metadatos debe ser inferior a 1 KiB. La cantidad total de claves en los metadatos debe ser inferior a 16. La longitud de cada clave debe ser inferior a 64 caracteres. La longitud de cada valor debe ser inferior a 1,024 caracteres. Todos los valores deben ser cadenas.

    10. Haz clic en Crear extensión.

    gcloud

    1. Define el texto destacado en un archivo YAML y asócialo con la regla de reenvío. Usa los valores de muestra proporcionados.

      cat >route.yaml <<EOF
    name: route-ext
    forwardingRules:
    - https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/us-west1/forwardingRules/l7-ilb-forwarding-rule
    loadBalancingScheme: INTERNAL_MANAGED
    extensionChains:
    - name: "chain1"
      matchCondition:
        celExpression: 'request.path.startsWith("/extensions")'
      extensions:
      - name: 'ext11'
        authority: ext11.com
        service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/us-west1/backendServices/l7-ilb-callout-service
        failOpen: false
        timeout: 0.1s
        metadata:
          "key": "value"
          "fr": "forwarding_rule_id"
EOF

      Reemplaza PROJECT_ID por el ID del proyecto.

      El campo metadata en la configuración de la extensión te permite pasar cualquier información adicional del balanceador de cargas al servidor de extensión. Los metadatos se envían en un mensaje ProcessingRequest y se codifican como protobuf.Struct. Todo el texto dentro de los metadatos que coincida con el ID de regla de reenvío especificado se reemplaza por la URL del recurso completamente calificada de la regla de reenvío asociada a la solicitud del cliente.

      El tamaño total de metadata debe ser inferior a 1 KiB. La cantidad total de claves en los metadatos debe ser inferior a 16. La longitud de cada clave debe ser inferior a 64 caracteres. La longitud de cada valor debe ser inferior a 1,024 caracteres. Todos los valores deben ser cadenas.

    2. Importa la extensión de ruta. Usa el comando gcloud service-extensions lb-route-extensions import con los siguientes valores de muestra.

      gcloud service-extensions lb-route-extensions import route-ext \
    --source=route.yaml \
    --location=us-west1

  3. Verifica que la extensión de ruta funcione según lo esperado. Usa el mismo comando curl:

    curl FORWARDING_RULE_IP/extensions

    El resultado indica que el tráfico coincidió con el host virtual service-extensions.com y llegó al servicio l7-ilb-backend-service2, aunque la solicitud original no lo hizo. El resultado es similar al siguiente:

    Page served from second backend service

    Para validar que la llamada se dirige solo a las solicitudes con el prefijo /extension, repite el comando curl sin el prefijo path.

    curl FORWARDING_RULE_IP

    El resultado es similar a lo siguiente:

    Page served from: l7-ilb-backend-example-1c7t

Limitaciones de las extensiones de ruta

  • Las extensiones de ruta no admiten el procesamiento del cuerpo HTTP.
  • Las extensiones de ruta no admiten una respuesta directa de la extensión al cliente. Si tu servidor de extensión de ruta responde a una solicitud de procesamiento con una respuesta de procesamiento que contiene una respuesta directa, el balanceador de cargas ignora la respuesta de procesamiento.

Para conocer las limitaciones que se aplican a todas las extensiones, consulta Limitaciones de las extensiones.

¿Qué sigue?