Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adding Apigee for ext_authz, minor fix in the default ext_authz docs #18796

Merged
merged 6 commits into from
Sep 18, 2023
Merged

Adding Apigee for ext_authz, minor fix in the default ext_authz docs #18796

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
9512348
adding apigee for ext_authz, minor fix
gautambaghel Sep 14, 2023
0f66724
adding the Apigee docs to nav
gautambaghel Sep 14, 2023
d932e8f
Apply suggestions from code review
gautambaghel Sep 14, 2023
f0d753b
addressing feedback
gautambaghel Sep 15, 2023
0fca72f
Apply suggestions from code review
gautambaghel Sep 18, 2023
80ccf2d
Merge branch 'main' into docs/ext-authz-apigee
gautambaghel Sep 18, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
203 changes: 203 additions & 0 deletions website/content/docs/connect/proxies/envoy-extensions/usage/apigee-ext-authz.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,203 @@
---
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 a more detailed walkthrough follow [this learn guide](https://github.com/hashicorp-education/learn-consul-apigee-external-authz).
gautambaghel marked this conversation as resolved.
Show resolved Hide resolved

## Workflow

Complete the following steps to use the external authorization extension:

1. Deploy the `apigee-remote-service-envoy` service and register the service in Consul
gautambaghel marked this conversation as resolved.
Show resolved Hide resolved
1. Configure an `EnvoyExtensions` block in a service defaults or proxy defaults configuration entry.
1. Apply the configuration entry.

## Configure the `apigee-remote-service-envoy` service default
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Per comment above, there is an inconsistency between the steps as described above and this heading. I'm not certain which is intended to be correct.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @boruszak! very helpful, let me know how the latest commit looks.

I didn't write the full statements in workflows as headings because they we too long


The following example shows the service defaults configuration entry for the `apigee-remote-service-envoy` service that directs the authorization requests to Apigee:

<Tabs>
<Tab heading="HCL" group="hcl">
<CodeBlockConfig filename="apigee-remote-service-envoy.hcl">

```hcl
Kind = "service-defaults"
Name = "apigee-remote-service-envoy"
Protocol = "grpc",
gautambaghel marked this conversation as resolved.
Show resolved Hide resolved
```
</CodeBlockConfig>
</Tab>
<Tab heading="JSON" group="json">
<CodeBlockConfig filename="apigee-remote-service-envoy.json">

```json
{
"kind": "service-defaults",
"name": "apigee-remote-service-envoy",
"protocol": "grpc",
gautambaghel marked this conversation as resolved.
Show resolved Hide resolved
}
```

</CodeBlockConfig>
</Tab>
<Tab heading="Kubernetes" group="yaml">
gautambaghel marked this conversation as resolved.
Show resolved Hide resolved
<CodeBlockConfig filename="apigee-remote-service-envoy.yaml">

```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceDefaults
metadata:
name: apigee-remote-service-envoy
namespace: apigee
spec:
protocol: grpc
```
</CodeBlockConfig>
</Tab>
</Tabs>

## Add 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 a specific service.
gautambaghel marked this conversation as resolved.
Show resolved Hide resolved

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.
gautambaghel marked this conversation as resolved.
Show resolved Hide resolved

The following example shows a service defaults configuration entry for the `api` service that directs the Envoy proxy to make gRPC authorization requests to the `authz` service:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you add more to this description of the example below? I don't quite understand what you mean to say here because the apigee-remote-service-envoy service isn't mentioned in this description. Try the following format:

"The following example configures a 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."

I'm not sure if that's correct - just trying to demonstrate names-in-code-font mixed with terms in the example config (defaults, target, gRPC) as a way to fully describe what the configuration does.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, that is correct and that actually sounds much better

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @boruszak


<Tabs>
<Tab heading="HCL" group="hcl">
<CodeBlockConfig filename="api-auth-service-defaults.hcl">

```hcl
Kind = "service-defaults"
Name = "api"
EnvoyExtensions = [
{
Name = "builtin/ext-authz"
Arguments = {
ProxyType = "connect-proxy"
Config = {
GrpcService = {
Target = {
Service = {
Name = "apigee-remote-service-envoy"
}
}
}
}
}
}
]
```
</CodeBlockConfig>
</Tab>
<Tab heading="JSON" group="json">
gautambaghel marked this conversation as resolved.
Show resolved Hide resolved
<CodeBlockConfig filename="api-auth-service-defaults.json">

```json
{
"Kind": "service-defaults",
"Name": "api",
"EnvoyExtensions": [{
"Name": "builtin/ext-authz",
"Arguments": {
"ProxyType": "connect-proxy",
"Config": {
"GrpcService": {
"Target": {
"Service": {
"Name": "apigee-remote-service-envoy"
}
}
}
}
}
}
]
}
```

</CodeBlockConfig>
</Tab>
<Tab heading="Kubernetes" group="yaml">
gautambaghel marked this conversation as resolved.
Show resolved Hide resolved
gautambaghel marked this conversation as resolved.
Show resolved Hide resolved
<CodeBlockConfig filename="api-auth-service-defaults.yaml">

```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
```
</CodeBlockConfig>
</Tab>
</Tabs>

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.

!> **Warning:** Adding Envoy extensions default proxy configurations may have unintended consequences. We recommend configuring `EnvoyExtensions` in service defaults configuration entries in most cases.

gautambaghel marked this conversation as resolved.
Show resolved Hide resolved
### Unsupported Envoy configuration fields

The following Envoy configurations are not supported:
gautambaghel marked this conversation as resolved.
Show resolved Hide resolved

| Configuration | Workaround |
| --- | --- |
gautambaghel marked this conversation as resolved.
Show resolved Hide resolved
| `deny_at_disable` | Disable filter by removing it from the service’s configuration in the configuration entry. |
gautambaghel marked this conversation as resolved.
Show resolved Hide resolved
| `failure_mode_allow` | Set the `EnvoyExtension.Required` field to `true` in the [service defaults configuration entry](/consul/docs/connect/config-entries/service-defaults#envoyextensions) or [proxy defaults configuration entry](/consul/docs/connect/config-entries/proxy-defaults#envoyextensions). |
| `filter_enabled` | Set the `EnvoyExtension.Required` field to `true` in the [service defaults configuration entry](/consul/docs/connect/config-entries/service-defaults#envoyextensions) or [proxy defaults configuration entry](/consul/docs/connect/config-entries/proxy-defaults#envoyextensions). |
| `filter_enabled_metadata` | Set the `EnvoyExtension.Required` field to `true` in the [service defaults configuration entry](/consul/docs/connect/config-entries/service-defaults#envoyextensions) or [proxy defaults configuration entry](/consul/docs/connect/config-entries/proxy-defaults#envoyextensions). |
| `transport_api_version` | Consul only supports v3 of the transport API. As a result, there is no workaround for implementing the behavior of this field. |
gautambaghel marked this conversation as resolved.
Show resolved Hide resolved

## Apply the configuration entry

If your network is deployed to virtual machines, use the `consul config write` command and specify the proxy defaults or service defaults configuration entry to apply the configuration. For Kubernetes-orchestrated networks, use the `kubectl apply` command. The following example applies the extension in a proxy defaults configuration entry.
gautambaghel marked this conversation as resolved.
Show resolved Hide resolved

<Tabs>
<Tab heading="HCL" group="hcl">

```shell-session
$ consul config write apigee-remote-service-envoy.hcl
$ consul config write api-auth-service-defaults.hcl
```

</Tab>
<Tab heading="JSON" group="json">

```shell-session
$ consul config write apigee-remote-service-envoy.json
$ consul config write api-auth-service-defaults.json
```

</Tab>
<Tab heading="Kubernetes" group="kubernetes">
gautambaghel marked this conversation as resolved.
Show resolved Hide resolved

```shell-session
$ kubectl apply -f apigee-remote-service-envoy.yaml
$ kubectl apply -f api-auth-service-defaults.yaml
```

</Tab>
</Tabs>
28 changes: 15 additions & 13 deletions website/content/docs/connect/proxies/envoy-extensions/usage/ext-authz.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,24 +57,26 @@ EnvoyExtensions = [
<CodeBlockConfig filename="api-auth-service-defaults.json">

```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"
}
}
}
}
}
}
}
]
]
}
```

</CodeBlockConfig>
Expand Down
4 changes: 4 additions & 0 deletions website/data/docs-nav-data.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
Loading