Create an ApigeeBackendService

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

This page describes how to create an ApigeeBackendService and the required traffic extension on the Google Kubernetes Engine (GKE) Gateway running in your cluster.

This approach is an alternative to using the APIMExtensionPolicy to identify the Apigee data plane as the Policy Decision Point (PDP) for the GKE Gateway. When you create an ApigeeBackendService, the Apigee Operator for Kubernetes automatically creates an APIMExtensionPolicy with the same name and namespace as the ApigeeBackendService. This is the backing APIMExtensionPolicy.

We recommend this approach if you create and manage Cloud Load Balancing traffic extensions and want to add Apigee as an extension in your traffic extension resource. You must use the ApigeeBackendService if the Apigee traffic extension works in conjunction with other traffic extensions.

Before you begin

Before you begin this task, complete the following steps:

  • Confirm that your GKE implementation uses GKE version 1.34.x or later.
  • Confirm that your GKE cluster has a Workload Identity configured. See Create a workload identity for the required steps.
  • Confirm that your cluster has a GKE Gateway configured and working. See Deploying gateways for more details.
  • Install the Apigee Operator for Kubernetes. See Install Apigee Operator for Kubernetes for installation instructions.

Required roles

If you assigned the required roles to your service account as described in Install the Apigee Operator for Kubernetes, no additional IAM roles or permissions are necessary to complete these tasks.

You can authorize actions on resources in your Google Kubernetes Engine cluster using the built-in role-based access control (RBAC) mechanism in Kubernetes. For more information, see Authorize actions in clusters using role-based access control.

Create the ApigeeBackendService Resource

To configure a traffic service extension on your GKE Gateway, create two main resources:

  • ApigeeBackendService: This custom resource specifies the Apigee data plane as the Policy Decision Point (PDP) and configures network details for Private Service Connect (PSC) Network Endpoint Groups (NEGs).
  • GCPTrafficExtension: This GKE Gateway API resource defines the extension chain, including how traffic directs to the ApigeeBackendService.

Create an ApigeeBackendService

The ApigeeBackendService resource specifies the Apigee data plane as the PDP for a GCPTrafficExtension.

To create an ApigeeBackendService:

  1. Create a YAML file named apigee-backend-service.yaml with the following content:
    2. # apigee-backend-service.yaml
kind: ApigeeBackendService
apiVersion:  apim.googleapis.com/v1
metadata:
  name: my-apigee-extension-backend-service
spec:
  apigeeEnv: ENV_NAME # optional for Apigee, required for hybrid
  defaultSecurityEnabled: SECURITY_ENABLED
  locations: # required field
  - name: REGION_NAME_1
    network: NETWORK_NAME_1
    subnet: SUBNET_NAME_1
  - name: REGION_NAME_2
    network: NETWORK_NAME_2
    subnet: SUBNET_NAME_2

    Where:

    • ENV_NAME is the Apigee environment to use. This is similar to the apigeeEnv field in the APIMExtensionPolicy. This field is optional for Apigee and required for hybrid.
    • SECURITY_ENABLED (Optional) specifies whether default Apigee policies for API key validation and Quota checks are automatically enabled. Defaults to true if not specified.
    • REGION_NAME_1 specifies the region where you deploy the GKE Gateway.
    • NETWORK_NAME_1 and SUBNET_NAME_1 specify the full resource URIs of the network and subnetworkwhere the PSC NEGs are created. For example, projects/my-project/global/networks/my-default and projects/my-project/regions/us-central1/subnetworks/my-default. Typically, these are the same as the network and subnetwork of the GKE cluster.
    • REGION_NAME_2, NETWORK_NAME_2, and SUBNET_NAME_2 are optional. You need them if you deploy the Apigee traffic extension in multiple regions.

  2. Apply the YAML file to your cluster in the default namespace: 
    kubectl apply -f apigee-backend-service.yaml
  3. Confirm that the ApigeeBackendService created successfully: 
    kubectl get apigeebackendservice

    The output should look similar to the following:

    NAMESPACE   NAME                          STATE     ERRORMESSAGE
default     default-ext-lb1-apim-policy   CREATED

When you create an ApigeeBackendService, the Apigee Operator for Kubernetes automatically creates an APIMExtensionPolicy with the same name and namespace as the ApigeeBackendService. This is the backing APIMExtensionPolicy.

If defaultSecurityEnabled is set to true, the Apigee Operator for Kubernetes automatically adds the default API key and Quota policies to the APIMExtensionPolicy. To add additional policies, see Add policies to the GKE Gateway.

Create a GCPTrafficExtension resource

TheGCPTrafficExtension resource defines an extension for Apigee and references the ApigeeBackendService created in the previous step as its backendRef. For more details on configuring a GCPTrafficExtension, see Configure service extensions.

The supportedEvents field specifies which parts of the request and response lifecycle are exposed to the extension. The Apigee Operator for Kubernetes supports the following events:

  • RequestHeaders
  • RequestBody
  • RequestTrailers
  • ResponseHeaders
  • ResponseBody
  • ResponseTrailers
For policies that require inspecting or modifying the request or response body (e.g., JSONThreatProtection), you must include RequestBody and ResponseBody in the supportedEvents list. For more information on supported events, see the Cloud Load Balancing traffic extensions documentation.

To create a GCPTrafficExtension:

  1. Create a YAML file named gcp-traffic-extension.yaml with the following content: 
    # gcp-traffic-extension.yaml
kind: GCPTrafficExtension
apiVersion: networking.gke.io/v1
metadata:
  name: my-apigee-extension
spec:
  targetRefs:
  - group: "gateway.networking.k8s.io"
    kind: Gateway
    name: GATEWAY_NAME  # Replace with your GKE Gateway name
  extensionChains:
  - name: EXTENSION_CHAIN_NAME
    matchCondition:
      celExpressions:
      - celMatcher: request.path.startsWith("/")
    extensions:
    - name: EXTENSION_NAME
      metadata:
        # This metadata label must match the name of the ApigeeBackendService
        apigee-extension-processor : APIGEE_BACKEND_SERVICE_NAME
      failOpen: false
      supportedEvents:
      - SUPPORTED_EVENT1
      - SUPPORTED_EVENT2
      timeout: 1s
      requestBodySendMode: FullDuplexStreamed
      backendRef: # References the ApigeeBackendService by kind and name
        kind: ApigeeBackendService
        name: APIGEE_BACKEND_SERVICE_NAME
        Port: 443

    Where:

    • GATEWAY_NAME is the name of the GKE Gateway to which the extension applies.
    • EXTENSION_CHAIN_NAME is the name of the extension chain.
    • EXTENSION_NAME is the name of the traffic service extension.
    • APIGEE_BACKEND_SERVICE_NAME is the name of the ApigeeBackendService created earlier. This label inside the extensions block must match the metadata.name of the ApigeeBackendService created earlier.
    • The supportedEvents field specifies which parts of the request and response lifecycle are exposed to the extension. The Apigee Operator for Kubernetes supports the following events:
      • RequestHeaders
      • RequestBody
      • RequestTrailers
      • ResponseHeaders
      • ResponseBody
      • ResponseTrailers
      For policies that require inspecting or modifying the request or response body (e.g., JSONThreatProtection), you must include RequestBody and ResponseBody in the supportedEvents list. For more information on supported events, see the Cloud Load Balancing traffic extensions documentation.
  2. Apply the YAML file to your cluster: 
    kubectl apply -f gcp-traffic-extension.yaml

Next Steps