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"