diff --git a/website/content/docs/connect/proxies/envoy-extensions/usage/apigee-ext-authz.mdx b/website/content/docs/connect/proxies/envoy-extensions/usage/apigee-ext-authz.mdx
new file mode 100644
index 000000000000..fff6bb28574f
--- /dev/null
+++ b/website/content/docs/connect/proxies/envoy-extensions/usage/apigee-ext-authz.mdx
@@ -0,0 +1,199 @@
+---
+layout: docs
+page_title: Delegate authorization to Apigee
+description: Learn how to use the `ext-authz` Envoy extension to delegate data plane authorization requests to Apigee.
+---
+
+# Delegate authorization to Apigee
+
+This topic describes how to use the external authorization Envoy extension to delegate data plane authorization requests to Apigee.
+
+For more detailed guidance, refer to the [`learn-consul-apigee-external-authz` repo on GitHub](https://github.com/hashicorp-education/learn-consul-apigee-external-authz).
+
+## Workflow
+
+Complete the following steps to use the external authorization extension with Apigee:
+
+1. Deploy the Apigee Adapter for Envoy and register the service in Consul.
+1. Configure the `EnvoyExtensions` block in a service defaults or proxy defaults configuration entry.
+1. Apply the configuration entry.
+
+## Deploy the Apigee Adapter for Envoy
+
+The [Apigee Adapter for Envoy](https://cloud.google.com/apigee/docs/api-platform/envoy-adapter/v2.0.x/concepts) is an Apigee-managed API gateway that uses Envoy to proxy API traffic.
+
+To download and install Apigee Adapter for Envoy, refer to the [getting started documentation](https://cloud.google.com/apigee/docs/api-platform/envoy-adapter/v2.0.x/getting-started) or follow along with the [`learn-consul-apigee-external-authz` repo on GitHub](https://github.com/hashicorp-education/learn-consul-apigee-external-authz).
+
+After you deploy the service in your desired runtime, create a service defaults configuration entry for the service's gRPC protocol.
+
+
+
+
+
+```hcl
+Kind = "service-defaults"
+Name = "apigee-remote-service-envoy"
+Protocol = "grpc"
+```
+
+
+
+
+
+```json
+{
+ "kind": "service-defaults",
+ "name": "apigee-remote-service-envoy",
+ "protocol": "grpc"
+}
+```
+
+
+
+
+
+
+```yaml
+apiVersion: consul.hashicorp.com/v1alpha1
+kind: ServiceDefaults
+metadata:
+ name: apigee-remote-service-envoy
+ namespace: apigee
+spec:
+ protocol: grpc
+```
+
+
+
+
+## Configure the `EnvoyExtensions`
+
+Add Envoy extension configurations to a proxy defaults or service defaults configuration entry. Place the extension configuration in an `EnvoyExtensions` block in the configuration entry.
+
+- When you configure Envoy extensions on proxy defaults, they apply to every service.
+- When you configure Envoy extensions on service defaults, they apply to all instances of a service with that name.
+
+
+ Adding Envoy extensions default proxy configurations may have unintended consequences. We recommend configuring `EnvoyExtensions` in service defaults configuration entries in most cases.
+
+
+Consul applies Envoy extensions configured in proxy defaults before it applies extensions in service defaults. As a result, the Envoy extension configuration in service defaults may override configurations in proxy defaults.
+
+The following example configures the default behavior for all services named `api` so that the Envoy proxies running as sidecars for those service instances target the apigee-remote-service-envoy service for gRPC authorization requests:
+
+
+
+
+
+```hcl
+Kind = "service-defaults"
+Name = "api"
+EnvoyExtensions = [
+ {
+ Name = "builtin/ext-authz"
+ Arguments = {
+ ProxyType = "connect-proxy"
+ Config = {
+ GrpcService = {
+ Target = {
+ Service = {
+ Name = "apigee-remote-service-envoy"
+ }
+ }
+ }
+ }
+ }
+ }
+]
+```
+
+
+
+
+
+
+```json
+{
+ "Kind": "service-defaults",
+ "Name": "api",
+ "EnvoyExtensions": [{
+ "Name": "builtin/ext-authz",
+ "Arguments": {
+ "ProxyType": "connect-proxy",
+ "Config": {
+ "GrpcService": {
+ "Target": {
+ "Service": {
+ "Name": "apigee-remote-service-envoy"
+ }
+ }
+ }
+ }
+ }
+ }
+ ]
+}
+```
+
+
+
+
+
+
+
+```yaml
+apiVersion: consul.hashicorp.com/v1alpha1
+kind: ServiceDefaults
+metadata:
+ name: api
+ namespace: default
+spec:
+ envoyExtensions:
+ - name: builtin/ext-authz
+ arguments:
+ proxyType: connect-proxy
+ config:
+ grpcService:
+ target:
+ service:
+ name: apigee-remote-service-envoy
+ namespace: apigee
+```
+
+
+
+
+Refer to the [external authorization extension configuration reference](/consul/docs/connect/proxies/envoy-extensions/configuration/ext-authz) for details on how to configure the extension.
+
+Refer to the [proxy defaults configuration entry reference](/consul/docs/connect/config-entries/proxy-defaults) and [service defaults configuration entry reference](/consul/docs/connect/config-entries/service-defaults) for details on how to define the configuration entries.
+
+## Apply the configuration entry
+
+On the CLI, you can use the `consul config write` command and specify the names of the configuration entries to apply them to Consul. For Kubernetes-orchestrated networks, use the `kubectl apply` command to update the relevant CRD.
+
+
+
+
+```shell-session
+$ consul config write apigee-remote-service-envoy.hcl
+$ consul config write api-auth-service-defaults.hcl
+```
+
+
+
+
+```shell-session
+$ consul config write apigee-remote-service-envoy.json
+$ consul config write api-auth-service-defaults.json
+```
+
+
+
+
+```shell-session
+$ kubectl apply -f apigee-remote-service-envoy.yaml
+$ kubectl apply -f api-auth-service-defaults.yaml
+```
+
+
+
diff --git a/website/content/docs/connect/proxies/envoy-extensions/usage/ext-authz.mdx b/website/content/docs/connect/proxies/envoy-extensions/usage/ext-authz.mdx
index 76852e6c1c8c..a0e6630b74d0 100644
--- a/website/content/docs/connect/proxies/envoy-extensions/usage/ext-authz.mdx
+++ b/website/content/docs/connect/proxies/envoy-extensions/usage/ext-authz.mdx
@@ -57,24 +57,26 @@ EnvoyExtensions = [
```json
-"Kind": "service-defaults",
-"Name": "api",
-"EnvoyExtensions": [{
- "Name": "builtin/ext-authz",
- "Arguments": {
- "ProxyType": "connect-proxy",
- "Config": {
- "GrpcService": {
- "Target": {
- "Service": {
- "Name": "authz"
+{
+ "Kind": "service-defaults",
+ "Name": "api",
+ "EnvoyExtensions": [{
+ "Name": "builtin/ext-authz",
+ "Arguments": {
+ "ProxyType": "connect-proxy",
+ "Config": {
+ "GrpcService": {
+ "Target": {
+ "Service": {
+ "Name": "authz"
+ }
}
}
}
}
}
- }
-]
+ ]
+}
```
diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json
index d72338edfe41..d3591ada7e0b 100644
--- a/website/data/docs-nav-data.json
+++ b/website/data/docs-nav-data.json
@@ -503,6 +503,10 @@
{
"title": "Usage",
"routes": [
+ {
+ "title": "Delegate authorization to Apigee",
+ "path": "connect/proxies/envoy-extensions/usage/apigee-ext-authz"
+ },
{
"title": "Delegate authorization to external services",
"path": "connect/proxies/envoy-extensions/usage/ext-authz"