Configure a user-managed callout backend service

Service Extensions lets supported Application Load Balancers send callouts from the data processing path to callout backend services managed by the user. This helps Application Load Balancers use custom logic in the processing path. This page describes how to configure a user-managed callout backend service.

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

Before you begin

Ensure that you have either a project owner or editor role or the following Compute Engine IAM roles:
- To create instances: compute.instanceAdmin.v1
- To create Cloud Load Balancing components: compute.networkAdmin
Enable these APIs: Compute Engine API and Network Services API.
Console
1. In the Google Cloud console, go to the Enable access to APIs page.
  
  Go to Enable access to APIs
2. Follow the instructions.
gcloud
Use the gcloud services enable command:
```
gcloud services enable compute.googleapis.com networkservices.googleapis.com
```
Create and configure an Application Load Balancer that supports extensions. For this example, set up a regional internal Application Load Balancer with VM instance group backends. Use the sample values mentioned.
Create a client VM for testing.
For route extensions only. Set up an additional backend service and update the URL map to add a host matcher that routes traffic to this backend service for all traffic with the HTTP host matching the specified condition.
Console
1. In the Google Cloud console, go to the Create an instance page.
  
  Go to Create an instance
  
  Specify the following sample values:
  - Name: l7-ilb-backend2-vm
  - Tags: allow-ssh and load-balanced-backend
  - Zone: us-west1-a
  - Network: lb-network
  - Subnetwork: backend-subnet
  - Image: debian-11
  - Family: debian-cloud
  - Advanced options > Management > Automation:
    
    '#! /bin/bash apt-get update apt-get install apache2 -y a2ensite default-ssl a2enmod ssl echo "Page served from second backend service" | tee /var/www/html/index.html systemctl restart apache2'
2. Create an unmanaged instance group.
  
  Specify the following sample values:
  - Name: l7-ilb-backend-service2-ig
  - Zone: us-west1-a
3. Add the new VM to the instance group.
  
  For VM instances, specify l7-ilb-backend2-vm.
4. In the Google Cloud console, go to the Load balancing page.
  
  Go to Load balancing
5. Update the load balancer by creating a backend service and adding a backend to it.
  
  For the backend service, specify the following sample values:
  - Name: l7-ilb-backend-service2
  - Protocol: HTTP
  - Health check > Name: l7-ilb-basic-check
  - Health check > Region: us-west1
  For the backend, specify the following sample values:
  - Instance group: l7-ilb-backend-service2-ig
  - Balancing mode: Utilization
6. Add a host matcher to the URL map of the backend service.
  
  Specify the following sample values:
  - Name: l7-ilb-map
  - Host: service-extensions.com
  - Path: callouts
  - Protocol: HTTP
  - Backend: l7-ilb-backend-service2
gcloud
1. Create a VM instance. Use the gcloud compute instances create command with the following sample values:
  gcloud compute instances create l7-ilb-backend2-vm \ --zone=us-west1-a \ --network=lb-network \ --subnet=backend-subnet \ --tags=allow-ssh,load-balanced-backend \ --image-family=debian-11 \ --image-project=debian-cloud \ --metadata=startup-script='#! /bin/bash apt-get update apt-get install apache2 -y a2ensite default-ssl a2enmod ssl echo "Page served from second backend service" | tee /var/www/html/index.html systemctl restart apache2'
2. Create an unmanaged instance group. Use the gcloud compute instance-groups unmanaged create command with the following sample values:
  gcloud compute instance-groups unmanaged create l7-ilb-backend-service2-ig \ --zone us-west1-a
3. Add the new VM to the instance group. Use the gcloud compute instance-groups unmanaged add-instances command with the following sample values:
  gcloud compute instance-groups unmanaged add-instances l7-ilb-backend-service2-ig \ --zone=us-west1-a \ --instances=l7-ilb-backend2-vm
4. Create a backend service. Use the gcloud compute backend-services create command with the following sample values:
  gcloud compute backend-services create l7-ilb-backend-service2 \ --load-balancing-scheme=INTERNAL_MANAGED \ --protocol=HTTP \ --health-checks=l7-ilb-basic-check \ --health-checks-region=us-west1 \ --region=us-west1
5. Add a backend to the backend service. Use the gcloud compute backend-services add-backend command with the following sample values:
  gcloud compute backend-services add-backend l7-ilb-backend-service2 \ --balancing-mode=UTILIZATION \ --instance-group=l7-ilb-backend-service2-ig \ --instance-group-zone=us-west1-a \ --region=us-west1
6. Add a host matcher to the URL map of the backend service. Use the gcloud compute url-maps add-path-matcher command with the following sample values:
  gcloud compute url-maps add-path-matcher l7-ilb-map \ --path-matcher-name=callouts \ --default-service=l7-ilb-backend-service2 \ --new-hosts=service-extensions.com \ --region=us-west1

Set up a callout backend service

For this example, a basic Python-based extension server implementing Envoy's ext_proc gRPC API is available. A docker container with this server is at us-docker.pkg.dev/service-extensions-samples/callouts/python-example-basic:main in the Service Extensions GitHub repository of Google Cloud. This repository contains several other Python and Go samples of ext_proc servers to do tasks such as header mutation and body mutation.

To create and set up a callout backend service, follow these steps:

Create a virtual machine (VM) instance for the callout backend service that's running the sample Python extension server.
Console
Create an instance by using a container image.
1. In the Google Cloud console, go to the Create an instance page.
  
  Go to Create an instance
2. Specify the following sample values:
  - Name: callouts-vm
  - Zone: us-west1-a
  - Network: lb-network
  - Subnetwork: backend-subnet
  - Tags: allow-ssh and load-balanced-backend
  - Container image: us-docker.pkg.dev/service-extensions-samples/callouts/python-example-basic:main
gcloud
Create an instance by using a container image. Use the gcloud compute instances create-with-container command with the following sample values:
```
gcloud compute instances create-with-container callouts-vm \
  --container-image=us-docker.pkg.dev/service-extensions-samples/callouts/python-example-basic:main \
  --network=lb-network \
  --subnet=backend-subnet \
  --zone=us-west1-a \
  --tags=allow-ssh,load-balanced-backend
```
Add the VM to an unmanaged instance group.
Console
Create an unmanaged instance group.
1. In the Google Cloud console, go to the Instance groups page.
  
  Go to Instance groups
  
  Specify the following sample values:
  - Name: callouts-ig
  - Zone: us-west1-a
2. Set a port for the instance group.
  
  For Port mapping, specify these port names and values: http:80 and grpc:443.
3. Add the new VM to the instance group.
  
  For VM instances, specify callouts-vm.
gcloud
1. Create an unmanaged instance group. Use the gcloud compute instance-groups unmanaged create command with the following sample values:
  gcloud compute instance-groups unmanaged create callouts-ig \ --zone=us-west1-a
2. Set a port for the instance group. Use the gcloud compute instance-groups unmanaged set-named-ports command with the following sample values:
  gcloud compute instance-groups unmanaged set-named-ports callouts-ig \ --named-ports=http:80,grpc:443 \ --zone=us-west1-a
3. Add the new VM instance to the unmanaged instance group. Use the gcloud compute instance-groups unmanaged add-instances command with the following sample values:
  gcloud compute instance-groups unmanaged add-instances callouts-ig \ --zone=us-west1-a \ --instances=callouts-vm
Create a callout backend service and add a backend. Like other backend servers, callout servers might need firewall rules to allow proxy traffic.
Console
Create a callout backend service that uses the HTTP/2 protocol and has an HTTP health check.
1. In the Google Cloud console, go to the Cloud Load Balancing Backends page.
  
  Go to Backends
2. Add a regional backend service with the following sample values:
  - Name: l7-ilb-callout-service
  - Region: us-west1
  - Load balancer type: Regional external Application Load Balancer (EXTERNAL_MANAGED)
  - Protocol: HTTP2
  - Port name: grpc
  - Health check > Name: callouts-hc
  - Health check > Port number: 80
  - Cloud Armor backend security policy: None
3. Add the instance group with the extension server as a backend to the backend service. The instance group runs the ext_proc service.
  
  Specify the following sample values:
  - Instance group: callouts-ig
  - Balancing mode: Utilization
gcloud
1. Create a basic HTTP health check for the instance. Use the gcloud compute health-checks create http command with the following sample values:
  gcloud compute health-checks create http callouts-hc \ --region=us-west1 \ --port=80
2. Create a callout backend service that uses the HTTP/2 protocol. Use the gcloud compute backend-services create command.
  gcloud compute backend-services create l7-ilb-callout-service \ --load-balancing-scheme=INTERNAL_MANAGED \ --protocol=HTTP2 \ --port-name=grpc \ --health-checks=callouts-hc \ --health-checks-region=us-west1 \ --region=us-west1
3. Add the instance group with the extension server as a backend to the backend service. The instance group runs the ext_proc service. Use the gcloud compute backend-services add-backend command with the following sample values:
  gcloud compute backend-services add-backend l7-ilb-callout-service \ --balancing-mode=UTILIZATION \ --instance-group=callouts-ig \ --instance-group-zone=us-west1-a \ --region=us-west1

Having set up a backend service, you can configure route, authorization, and traffic extensions.

Configure a user-managed callout backend service

Before you begin

Console

gcloud

Console

gcloud

Set up a callout backend service

Console

gcloud

Console

gcloud

Console

gcloud

What's next