Configure a traffic extension

Service Extensions enables Application Load Balancers to send callouts to backend services to inject custom processing in the processing path. Traffic extensions run last in the request processing path and first in the response processing path to modify headers and payloads without impacting the choice of the backend service. This page describes how to configure traffic extensions.

For an overview about Application Load Balancer extensions, see Cloud Load Balancing extensions overview.

Introduction

A traffic extension for an Application Load Balancer points to the following resources:

  • A forwarding rule to attach to
  • A callout backend service whose backends run the ext_proc gRPC API

A traffic extension groups related extension services into one or more chains. Each extension chain selects the traffic to act on by using Common Expression Language (CEL) match conditions. The load balancer evaluates a request against each chain's match condition in a sequential manner. When a request matches the conditions defined by a chain, all extensions in the chain act on the request. Only one chain matches a given request.

For information about the limits related to extensions, see the Quotas and limits page.

The extension references the load balancer forwarding rule to attach to. After you configure the resource, the load balancer starts sending matching requests to extension services.

Before you begin

Create the required resources as described in Configure a callout backend service.

Configure a traffic extension

The following example helps you configure a traffic extension to call when the host matches example.com. The traffic extension server in the callout-vm adds a response header, hello: service-extensions, to matching requests.

  1. Check if there's a match for example.com in the URL map.

    1. Establish an SSH connection to the client VM.

      Console

      1. In the Google Cloud console, go to the VM instances page.

        Go to VM instances

      2. In the list of virtual machine instances, click SSH in the row of the instance that you want to connect to.

      gcloud

      Use the gcloud compute ssh command.

      gcloud compute ssh CLIENT_VM \
    --zone=ZONE

      Replace the following:

      • CLIENT_VM: the name of the client VM
      • ZONE: the zone of the VM

    2. Run the following curl command against the forwarding rule in the client VM:

      curl -D - -H "host: example.com" FORWARDING_RULE_IP

      Replace FORWARDING_RULE_IP with the IP address of the forwarding rule. To find the IP address, use the gcloud compute forwarding-rules describe command.

      The output is similar to the following:

      HTTP/1.1 200 OK
...
content-length: 46
content-type: text/html
via: 1.1 google

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

    3. Close the SSH connection.

  2. Configure the traffic extension.

    Console

    1. In the Google Cloud console, go to the Service Extensions page.

      Go to Service Extensions

    2. Click Create extension.

      A wizard opens to guide you through some initial steps.

    3. For the product, select Load Balancing. Then, click Continue.

      A list of Application Load Balancers that support extensions appears.

    4. Select a load balancer type. For regional load balancers, also specify the region. Click Continue.

    5. For the service extension type, select Traffic extensions, click Continue, and then click Done.

      The Create service extension form opens. Notice that the preceding selections, which appear at the top of the page, are not editable.

    6. In the Basics section, do the following:

      1. Specify a unique name for the service extension.

        The name must start with a lowercase letter followed by up to 62 lowercase letters, numbers, or hyphens and must not end with a hyphen.

      2. Optional: Enter a brief description about the extension by using up to 1,024 characters.

      3. Optional: In the Labels section, click Add label. Then, in the row that appears, do the following:

        • For Key, enter a key name.
        • For Value, enter a value for the key.

        To add more key-value pairs, with the maximum limit being 64, click Add label.

        For more information about labels, see Create and update labels for projects.

    7. For Forwarding rules, select one or more forwarding rules to associate with the extension.

      Forwarding rules that are already associated with another extension cannot be selected and appear unavailable.

    8. For Extension chains, add one or more extension chains to execute for a matching request.

      To add an extension chain, click Add an extension chain, do the following, and then click Done:

      • For Extension chain name, specify a unique name.

        The name must conform with RFC-1034, use only lowercase letters, numbers, and hyphens, and have a maximum length of 63 characters. Additionally, the first character must be a letter and the last character must be a letter or a number.

      • To match requests for which the extension chain is executed, for Match condition, specify a Common Expression Language (CEL) expression.

        For more information, click Get syntax help or see CEL matcher language reference.

      • Add one or more extensions to execute for a matching request.

        For each extension, under Extensions, do the following, and then click Done:

        • For Extension name, specify a unique name.

          The name must conform with RFC-1034, use only lower-case letters, numbers, and hyphens, and have a maximum length of 63 characters. Additionally, the first character must be a letter and the last character must be a letter or a number.

        • For Authority, enter the authority header from the gRPC request sent from Envoy to the extension service.

        • For Backend service, select a backend service created by following the instructions in Configure a callout backend service.

        • For Timeout, specify a value between 10 and 1000 milliseconds after which a message on the stream times out.

        • For Events, select one or more HTTP event types that call the extension.

        • For Forward headers, click Add header, and then add HTTP headers to forward to the extension (from the client or the backend). If a header is not specified, all headers are sent.

        • For Fail open, select Enabled. If the call to the extension fails or times out, request or response processing continues without error. Any subsequent extensions in the extension chain are also run.

          By default, the Fail open field is not selected. In this case, if response headers have not been delivered to the downstream client, a generic 500 status code is returned to the client. If response headers have been delivered, the HTTP stream to the downstream client is reset.

    9. Click Create extension.

    gcloud

    1. Define the extension in a YAML file and associate it with the forwarding rule. Use the sample values provided.

      cat >traffic.yaml <<EOF
    name: traffic-ext
    forwardingRules:
    - https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/us-west1/forwardingRules/l7-ilb-forwarding-rule
    loadBalancingScheme: INTERNAL_MANAGED
    metadata: {"fr": "{forwarding_rule_id}", "key2": {"key3":"value"}}
    extensionChains:
    - name: "chain1"
      matchCondition:
        celExpression: 'request.host == "example.com"'
      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
        supportedEvents:
        - RESPONSE_HEADERS
EOF

      Replace PROJECT_ID with the project ID.

      The metadata field in the extension configuration lets you pass any JSON objects from the load balancer to the extension server. The metadata is sent in a ProcessingRequest message and encoded by using a protobuf.Struct type. Any text within the JSON object that matches the specified forwarding rule ID is replaced with the fully qualified resource URL of the forwarding rule associated with the client request.

    2. Import the traffic extension. Use the gcloud service-extensions lb-traffic-extensions import command with the following sample values.

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

  3. Verify that the traffic extension works as expected. Establish an SSH connection to the VM client and use the same curl command:

    curl -D - -H "host: example.com" FORWARDING_RULE_IP

    The output includes the hello: service-extensions response header.

    HTTP/1.1 200 OK
...
content-length: 46
content-type: text/
hello: service-extensions
via: 1.1 google

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

    To validate that the extension targets only example.com traffic, repeat the curl command without the host header.

    curl -D - FORWARDING_RULE_IP

    The output is similar to the following:

    HTTP/1.1 200 OK
...
content-length: 46
content-type: text/html
via: 1.1 google

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

Limitations for traffic extensions

Cross-project referencing between extensions and the forwarding rule is not supported.

What's next