Service Extensions enables supported Application Load Balancers to use plugins or send callouts to backend services to insert 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.
A traffic extension for an Application Load Balancer points to the following resources:
- A forwarding rule to attach to
- A plugin or a callout backend service whose backends run the
ext_proc
gRPC API
A traffic extension groups related extension services into one or more chains. You can configure both plugins and callouts in the same extension chain. 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.
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.
For information about the limits related to extensions, see the Quotas and limits page.
Configure using plugins
This section shows you how to configure a traffic extension by using a plugin.
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
Create a plugin that has your custom code.
Create and configure an Application Load Balancer that supports traffic extension plugins.
For example, set up a global external Application Load Balancer with VM instance group backends.
Set up a way to send test requests to your service—for example, by running curl. If you're using an internal load balancer, create a client VM for testing.
Configure a traffic extension by using a plugin
The following example helps you configure a traffic extension by using a plugin
that adds a response header, hello: service-extensions
, when the host matches
example.com
.
Check if there's a match for
example.com
in the URL map.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 thegcloud 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
Configure the traffic extension.
Console
In the Google Cloud console, go to the Service Extensions page.
Click Create extension.
A wizard opens to guide you through some initial steps.
For the product, select Load Balancing. Then, click Continue.
A list of supported Application Load Balancers appears.
For the load balancer type, select either global external Application Load Balancer or cross-region internal Application Load Balancer. Then, click Continue.
For the extension type, select Traffic extensions, and then click Continue.
To open the Create extension form, click Continue.
In the Create extension form, notice that the preceding selections, which appear at the top of the page, are not editable.
In the Basics section, do the following:
Specify a unique name for the 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.
Optional: Enter a brief description about the extension by using up to 1,024 characters.
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, click Add label. You can add a maximum of 64 key-value pairs.
For more information about labels, see Create and update labels for projects.
For Forwarding rules, select one or more forwarding rules to associate with the extension—for example,
http-content-rule
.Forwarding rules that are already associated with another extension can't be selected and appear unavailable.
For Extension chains, add one or more extension chains to execute for a matching request.
To add an extension chain, do the following, and then click Done:
For New extension chain, 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 example,
request.host == "example.com"
.For more information about CEL expressions, 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 Programmability type, select Plugins.
For Extension 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.
For Plugin, select a plugin created using Service Extensions for the same product and extension type.
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 isn't 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 isn't 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.
Click Create extension.
gcloud
Define the plugin in a YAML file and associate it with a forwarding rule—for example,
http-content-rule
.cat >traffic-plugin.yaml <<EOF name: traffic-ext forwardingRules: - https://www.googleapis.com/compute/v1beta1/projects/PROJECT_ID/regions/global/forwardingRules/http-content-rule loadBalancingScheme: EXTERNAL_MANAGED extensionChains: - name: "chain1" matchCondition: celExpression: 'request.host == "example.com"' extensions: - name: 'ext1' service: projects/PROJECT_ID/locations/global/wasmPlugins/WASM_PLUGIN failOpen: false supportedEvents: - RESPONSE_HEADERS EOF
Replace the following:
PROJECT_ID
: the project IDWASM_PLUGIN
: the ID or the fully qualified name of the plugin
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-plugin.yaml \ --location=global
After a traffic 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.
To verify that the traffic extension works as expected, 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
To validate that the extension targets only
example.com
traffic, repeat thecurl
command without thehost
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
Configure using callouts
This section shows you how to configure a traffic extension by using a callout.
Before you begin
Create the required resources as described in Configure a callout backend service.
Configure a traffic extension by using a callout
The following example helps you configure a traffic extension by using a
callout 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.
Check if there's a match for
example.com
in the URL map.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 thegcloud 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
Configure the traffic extension.
Console
In the Google Cloud console, go to the Service Extensions page.
Click Create extension.
A wizard opens to guide you through some initial steps.
For the product, select Load Balancing. Then, click Continue.
A list of supported Application Load Balancers appears.
Select a load balancer type. For regional load balancers, also specify the region. Click Continue.
For the extension type, select Traffic extensions, and then click Continue.
To open the Create extension form, click Continue.
In the Create extension form, notice that the preceding selections, which appear at the top of the page, are not editable.
In the Basics section, do the following:
Specify a unique name for the 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.
Optional: Enter a brief description about the extension by using up to 1,024 characters.
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, click Add label. You can add a maximum of 64 key-value pairs.
For more information about labels, see Create and update labels for projects.
For Forwarding rules, select one or more forwarding rules to associate with the extension—for example,
l7-ilb-forwarding-rule
.Forwarding rules that are already associated with another extension can't be selected and appear unavailable.
For Extension chains, add one or more extension chains to execute for a matching request.
To add an extension chain, do the following, and then click Done:
For Programmability type, select Callouts.
For New 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 example,
request.host == "example.com"
.For more information about CEL expressions, 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 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.
For Authority, enter the
authority
header from the gRPC request sent from the load balancer 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 isn't 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 isn't 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.
Click Create extension.
gcloud
Define the callout 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 aProcessingRequest
message and encoded by using aprotobuf.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.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
Verify that the traffic extension works as expected. 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 thecurl
command without thehost
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 isn't supported.
What's next
- View Rust and C++ plugin examples and testing tools in the Service Extensions GitHub repository for plugins.
- View Python and Go samples of
ext-proc
servers in the Service Extensions GitHub repository for callouts. - Configure route extensions
- Manage extensions
- Manage plugins