Configure an edge extension

Service Extensions enablessupported Application Load Balancersto use plugins to insert custom processingin the processing path.Edge extensions runin the request processing path when the load balancer receives request headersand before it evaluates theURL map orcalls 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, seeCloud Load Balancing extensions overview.

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

  • A forwarding rule to attach to
  • A plugin

The extension references the load balancerforwarding rule to attach to.After you configure the resource, the load balancer starts sendingmatching requests to extension services. You can attach only one edge extensionto 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 theQuotas and limits page.

Configure using plugins

This section uses an example to show you how to configure an edge extension byusing a plugin that rewrites the:host request header toservice-extensions.com when the path matches/extensions. The earlier hostand the newly configured host are mapped to backend services in differentregions, 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'tconfigure Cloud Load Balancing extensions with plugins that are alreadyused in Media CDN extensions.

Before you begin

  1. Create a plugin that contains yourcustom code.

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

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

    • Name the backend service asservice-one.
    • Pointservice-one to a virtual machine (VM) instance in regionA.
    • Pointgl7-gxlb-url-map toservice-one by default.

  3. Set up an additional backend service,service-two and point it toa VM in regionB.

  4. To the URL map, add a path matcher pointing toservice-two. Use thegcloud compute url-maps add-path-matcher commandwith 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 runningcurl).

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 regionA:

      curlFORWARDING_RULE_IP

      ReplaceFORWARDING_RULE_IP with the IP addressof the forwarding rule. To find the IP address, use thegcloud compute forwarding-rules describe command.

      The output is similar to the following and indicates that the page isserved from a VM inregion A:

      Page served from region-A-vm

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

      curlFORWARDING_RULE_IP/extensions

      ReplaceFORWARDING_RULE_IP with the IP addressof the forwarding rule. To find the IP address, use thegcloud compute forwarding-rules describe command.

      The output indicates that there is no match for/extensions in the URLmap. 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.

    Console

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

      Go to Service Extensions

    2. ClickCreate extension.

      A wizard opens to guide you through some initial steps.

    3. For the product, selectLoad Balancing. Then, clickContinue.

      A list ofsupported Application Load Balancersappears.

    4. For the load balancer type, select global external Application Load Balancer.Then, clickContinue.

    5. For the extension type, selectEdge extensions, and then clickContinue.

    6. To open theCreate extension form, clickContinue.

      In theCreate extension form, notice that thepreceding selections aren't editable.

    7. In theBasics section, do the following:

      1. Specify a unique name for the extension.

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

      2. Optional: Enter a brief description about the extension by usinga maximum of 1,024 characters.

      3. Optional: In theLabels section, clickAdd label. Then, inthe row that appears, do the following:

        • ForKey, enter a key name.
        • ForValue, enter a value for the key.

        To add more key-value pairs, clickAdd label. You can add amaximum of 64 key-value pairs.

        For more information about labels, seeCreate and update labels for projects.

    8. ForForwarding rules, select one or more forwarding rules toassociate with the extension—for example,cr-xlb-forwarding-rule.

      Forwarding rules that are already associated with another extensioncan't be selected and appear disabled.

    9. ForExtension chains, add one or more extension chains toexecute for a matching request.

      To add an extension chain, do the following, and then clickDone:

    10. ClickCreate extension.

    gcloud

    1. Define the plugin in a YAML file and associate it with a globalforwarding 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_HEADERSEOF

      Replace the following:

      • PROJECT_ID: theproject ID
      • WASM_PLUGIN: the ID or the fullyqualified name of the plugin

      Edge extensions let you use only one regular expression perCEL expression.

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

      gcloud 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 pluginto be distributed across all locations. The time might vary acrosslocations because the plugin isn't delivered to all locations simultaneously.

  3. To verify that the edge extension works as expected, use the samecurlcommand:

    curlFORWARDING_RULE_IP/extensions

    The output is similar to the following and indicates that the page isserved from a VM inregion B:

    Page served from region-B-vm

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

    curlFORWARDING_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, seeLimitations for extensions.

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-17 UTC.