Download the release bundle from Download Edge-Native Defender. New to Edge-Native Defender? Start with Edge-Native Defender overview.

Watch the install (6 minutes): Defender on GKE, the Apigee console before and after, the installer's preflight and install, allowed and blocked requests, Apigee's Debug for each request, and removing it.

At a glance

Deployment architecture

Defender protects Apigee X proxies through Apigee's own ExternalCallout policy. Two shared flows do the work, attached to every proxy in an environment by flow hooks:

• defender-request, on the Pre-proxy hook: sends each request to Defender, and when Defender blocks, answers the client with your policy's status and block page.
• defender-response, on the Post-target hook: sends the response so Defender can complete the request's analytics.

  BEFORE

    client ---> Apigee proxy ------------------------------> your target


  AFTER

    client ---> Apigee proxy ------------------------------> your target
                  |  defender-request      defender-response
                  v                        v
               Defender service  (GKE over Private Service Connect, or Cloud Run)
                  |
                  +---> your Cequence tenant: policies in, analytics out,
                        in the background

What stays the same. Your proxies, their policies, targets and routes. The flow hooks apply Defender to every proxy in the environments you choose, with nothing to change in each proxy, and removing them takes Defender out at once.

What Defender does with a request. A blocked request is answered by Apigee with your tenant's block page and never reaches your target. An allowed request is forwarded byte for byte, and your client receives the response byte for byte: Defender inspects a copy of each body, up to your tenant's capture settings, and never changes what it forwards.

What is sent to Cequence. For each request: its headers and URL, the response status and headers, and the inspected body copies, masked first with your tenant's Sensitive Data rules. Your traffic filters decide whether a request is reported at all.

Installation

Prerequisites

• Apigee X: an organization and the environments to protect.
• Where Defender runs, one of:
• GKE over Private Service Connect (recommended, fastest): a GKE cluster in the same region as your Apigee instance;
• Cloud Run: a Google Cloud project with the Cloud Run and Secret Manager APIs. Apigee cannot authenticate to Cloud Run, so this service accepts unauthenticated calls.
• The defender-extproc image copied into your Artifact Registry. Cequence support gives you access to the image for your release.
• gcloud, signed in with rights to manage Apigee (and GKE or Cloud Run), on the machine you install from, with curl, python3, tar and zip.
• Your tenant's name, client ID and client secret.

1. Run Defender

On GKE over Private Service Connect. From the unpacked defender-for-apigee bundle:

1. Apply gke/defender.yaml in namespace defender, as its header describes (your tenant's configuration, the client secret and a TLS certificate -- self-signed is fine).
2. Create a Private Service Connect subnet in the cluster's network and region, then apply gke/gke-psc.yaml. Its header has the commands.
3. In your firewall, allow that subnet's range to reach the GKE nodes on port
4. Without it every call fails, and because Apigee lets requests through when Defender cannot be reached, nothing else tells you.
5. Note the service attachment's path for the next step: kubectl -n defender get serviceattachment defender-extproc-psc -o jsonpath='{.status.serviceAttachmentURL}'.

On Cloud Run the installer deploys Defender for you in the next step.

2. Install with defenderctl-apigee

Fill in defender.conf from defender.conf.example:

CEQUENCE_TENANT=<your tenant>
CEQUENCE_CLIENT_ID=<client id>
APIGEE_ORG=<your Apigee organization>
APIGEE_ENVS=<environments, comma-separated>

For GKE, add:

APIGEE_CALLOUT=endpoint
APIGEE_SERVICE_ATTACHMENT=projects/<project>/regions/<region>/serviceAttachments/<name>

For Cloud Run, add:

APIGEE_CALLOUT=cloudrun
APIGEE_CLOUDRUN_PUBLIC=yes
GCP_PROJECT=<project>
GCP_REGION=<region of your Apigee instance>
GCP_IMAGE=<region>-docker.pkg.dev/<project>/<repository>/defender-extproc:<version>

Then:

export CEQUENCE_CLIENT_SECRET=<client secret>
./bin/defenderctl-apigee preflight
./bin/defenderctl-apigee install

The installer creates the target server, imports and deploys the two shared flows, and attaches the flow hooks last, so traffic goes through Defender only once everything is in place. It refuses to replace anything it did not create: if your environment already uses a flow hook, it tells you how to add Defender to your existing shared flow instead.

3. Check it before you go live

1. Run APIGEE_VERIFY_URL=https://<your API host> ./bin/defenderctl-apigee verify. It checks that an ordinary request passes and that a request matching a test policy is blocked.
2. Send a request that one of your own policies blocks, and check it is blocked.
3. ./bin/defenderctl-apigee status shows the target server, the deployed shared flows and the hooks in each environment.
4. In the Apigee console, a Debug session on one of your proxies shows each request: a blocked one ends at the pre-proxy flow hook's Defender callout with 403 and never reaches the target; an allowed one goes on to it.

Behind an outbound proxy

If Defender reaches the internet only through a proxy, add a proxy section to its configuration (defender.json):

"proxy": { "url": "http://proxy.internal:3128", "username": "<proxy username>", "no_proxy": ["<hosts reached directly>"] }

url is an HTTP proxy (http://; your HTTPS calls to Cequence go through it with CONNECT and stay encrypted end to end), a proxy you reach over TLS (https://), or SOCKS5 (socks5://, or socks5h:// to have the proxy resolve host names). On GKE, put the password in the Secret under proxy-password (kubectl -n defender create secret generic defender-tenant --from-file=client-secret=<file> --from-file=proxy-password=<file>); gke/defender.yaml reads it from there. A password in defender.json, or credentials in the url, is refused. Defender logs the proxy it uses when it starts, never the password. The installer does not set a proxy for Defender on Cloud Run.

Upgrades and rollback

./bin/defenderctl-apigee upgrade

from the new bundle imports and deploys new shared-flow revisions, and on Cloud Run deploys a new service revision. Apigee switches revisions without dropping requests. To roll back, run upgrade from the previous bundle. On GKE, update the image in gke/defender.yaml; the pods are replaced one at a time.

Performance and sizing

Measured on an Apigee X organization in us-central1, alternating runs with and without Defender and with each path confirmed in use. Defender's own decision takes about a millisecond; most of the rest is Apigee's call to it. Each request makes two calls, one for the request and one for the response.

Cost

Cequence charges nothing for the infrastructure. On GKE, Defender is two small pods on a cluster you run; on Cloud Run, one instance stays running so policies and analytics keep flowing. Google's usual GKE, Cloud Run and Private Service Connect charges apply.

Availability

• If Cequence is slow or unreachable, your traffic is unaffected. Defender keeps enforcing the policies it last received, and sends the analytics it holds once Cequence is reachable again.
• If Defender is unreachable or slow, Apigee lets requests through to your target after the 500 ms timeout, uninspected. Run at least two pods on GKE.
• If you need Defender off the path at once, run ./bin/defenderctl-apigee uninstall, or detach the two flow hooks in Apigee.
• A fresh install blocks nothing until your tenant's first policy publish arrives.

Known limits

• block and add-header policies are enforced. challenge, rate-limit and redirect policies are reported but not applied: the request is forwarded.
• Apigee X is supported. Apigee hybrid works through the shared flows, but the installer does not set it up yet.
• On flows with streaming turned on, Apigee does not send bodies, so body policies cannot match there.

If something is wrong

• Nothing is blocked. The most likely cause is that Apigee cannot reach Defender: check the firewall rule in step 1, and in an Apigee debug session look for externalcallout.EC-Defender-Request.failed. verify points to the same.
• The installer refuses to attach. An environment already uses the flow hook: add a FlowCallout to defender-request at the start of your existing hook's shared flow, and install with APIGEE_ATTACH=none.
• No policies loaded. Defender's logs say why it cannot reach your tenant: outbound access, the client ID or the secret.

Removing it

./bin/defenderctl-apigee uninstall

detaches the flow hooks first, so traffic stops going through Defender, then removes the shared flows, the target server and what it created for the callout. The client secret is kept unless you add --delete-secret.