Configure an edge extension

Service Extensions enables supported Application Load Balancers to use plugins to insert custom processing in the processing path. Edge extensions run in the request processing path when the load balancer receives request headers and before it evaluates the URL map or calls Cloud CDN, which lets you influence caching and routing. This page describes how to configure edge extensions.

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

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

  • A forwarding rule to attach to
  • A plugin

An edge extension groups related extension services into a chain. The extension chain selects the traffic to act on by using Common Expression Language (CEL) match conditions. The load balancer evaluates a request against match conditions for a chain 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.

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. You can attach only one edge extension to a forwarding rule and include only one plugin in an edge extension chain.

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

Configure using plugins

This section uses an example to show you how to configure an edge extension by using a plugin that rewrites the :host request header to service-extensions.com when the path matches /extensions. The earlier host and the newly configured host are mapped to backend services in different regions, which demonstrates the routing behavior.

All extension resources that reference a given plugin must be of the same type. The extensions must also have the same load balancing scheme. You can't configure Cloud Load Balancing extensions with plugins that are already used in Media CDN extensions.

Before you begin

  1. Create a plugin that contains your custom code.

  2. Create and configure an Application Load Balancer that supports edge extension plugins.

    Follow the instructions on the Set up a global external Application Load Balancer with VM instance group backends page for all steps, except the following:

    • Name the backend service as service-one.
    • Point service-one to a virtual machine (VM) instance in region A.
    • Point gl7-gxlb-url-map to service-one by default.

  3. Set up an additional backend service, service-two and point it to a VM in region B.

  4. To the URL map, add a path matcher pointing to service-two. Use the gcloud compute url-maps add-path-matcher command with the following sample values:

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

  5. Set up a way to send test requests to your service (for example, by running curl).

Configure an edge extension by using a plugin

  1. Check the behavior before an extension is configured.

    1. Verify that a request without an explicit path goes to region A:

      curl 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 and indicates that the page is served from a VM in region A:

      Page served from region-A-vm

    2. Verify that there is no match for /extensions in the URL map:

      curl FORWARDING_RULE_IP/extensions

      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 indicates that there is no match for /extensions in the URL map. The output is similar to the following:

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

  2. Configure the edge extension.

    gcloud

    1. Define the plugin in a YAML file and associate it with a global forwarding rule—for example, cr-xlb-forwarding-rule.

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

      Replace the following:

      • PROJECT_ID: the project ID
      • WASM_PLUGIN: the ID or the fully qualified name of the plugin

      Edge extensions let you use only one regular expression per CEL expression.

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

      gcloud beta service-extensions lb-edge-extensions import edge-ext \
    --source=edge-plugin.yaml \
    --___location=global

    After an edge extension is created, it takes a little time for the new plugin to be distributed across all locations. The time might vary across locations because the plugin isn't delivered to all locations simultaneously.

  3. To verify that the edge extension works as expected, use the same curl command:

    curl FORWARDING_RULE_IP/extensions

    The output is similar to the following and indicates that the page is served from a VM in region B:

    Page served from region-B-vm

    To verify that the plugin runs only for requests with the /extension path prefix, repeat the curl command without a path.

    curl FORWARDING_RULE_IP

    The output is similar to the following:

    Page served from region-A-vm

Limitations for edge extensions

  • You can attach only one edge extension to a forwarding rule.
  • Edge extensions don't support HTTP body processing.
  • Edge extensions let you use only one regular expression per CEL expression.

For limitations that are applicable to all extensions, see Limitations for extensions.

What's next