Version: development

Consul

Supported Versions

Aperture supports the following versions of Consul:

Platform	Extent of Support
Consul	1.17 and above
Consul Data Plane	1.2.2 and above

info

This integration is currently only supported with the self-hosted version of Aperture Agent.

Envoy Extensions

The Envoy Extensions in Consul is used to modify the behavior of Envoy.

The Aperture Agent requires additional details and needs the External Authorization and OpenTelemetry Access Logging Envoy Extensions to be added through the Service Defaults.

info

Consul also supports Proxy Defaults but as of now, Aperture Agent does not support it.

The reason being, the Proxy Defaults are applied to all the proxies in the Consul Data Plane, which includes the proxies running in the Aperture Agent itself. This will create a loop of requests from the Aperture Agent to itself.

Note: In all the below patches, it is presumed that the Aperture Agent is installed with DaemonSet mode and is installed in the aperture-agent namespace, which makes the target service name aperture-agent and namespace aperture-agent. If you are running the Aperture Agent in Sidecar mode, use localhost as the target address.

As the External Authorization and OpenTelemetry Access Logging support gRPC, the below Service Defaults configures the protocol of the Aperture Agent to gRPC.
```
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceDefaults
metadata:
  name: aperture-agent
  namespace: aperture-agent
spec:
  protocol: grpc
```

The below Service Defaults adds OpenTelemetry Access Logging Envoy Extension for the outbound listener, in the Consul Proxy running with the application.

The OpenTelemetry configuration in the following has extracted values, which are forwarded to the Aperture Agent instance using gRPC.

The prepared log has the request method value as log body and egress as the log name to differentiate between different access logs coming from the same Envoy.

name: builtin/otel-access-logging
required: true
arguments:
  listenerType: outbound
  config:
    attributes:
      aperture.source: "envoy"
      aperture.check_response: "%DYNAMIC_METADATA(envoy.filters.http.ext_authz:aperture.check_response)%"
      http.status_code: "%RESPONSE_CODE%"
      authz_duration: "%DYNAMIC_METADATA(envoy.filters.http.ext_authz:ext_authz_duration)%"
      BYTES_RECEIVED: "%BYTES_RECEIVED%"
      BYTES_SENT: "%BYTES_SENT%"
      DURATION: "%DURATION%"
      REQUEST_DURATION: "%REQUEST_DURATION%"
      REQUEST_TX_DURATION: "%REQUEST_TX_DURATION%"
      RESPONSE_DURATION: "%RESPONSE_DURATION%"
      RESPONSE_TX_DURATION: "%RESPONSE_TX_DURATION%"
    body: "%REQ(:METHOD)%"
    logName: "egress"
    grpcService:
      target:
        service:
          name: aperture-agent
          namespace: aperture-agent

The below Service Defaults adds OpenTelemetry Access Logging Envoy Extension, but for the inbound listener, in the Consul Proxy running with the application.

The OpenTelemetry configuration in the following has extracted values, which are forwarded to the Aperture Agent instance using gRPC.

The prepared log has the request method value as log body and ingress as the log name to differentiate between different access logs coming from the same Envoy.

name: builtin/otel-access-logging
required: true
arguments:
  listenerType: inbound
  config:
    attributes:
      aperture.source: "envoy"
      aperture.check_response: "%DYNAMIC_METADATA(envoy.filters.http.ext_authz:aperture.check_response)%"
      http.status_code: "%RESPONSE_CODE%"
      authz_duration: "%DYNAMIC_METADATA(envoy.filters.http.ext_authz:ext_authz_duration)%"
      BYTES_RECEIVED: "%BYTES_RECEIVED%"
      BYTES_SENT: "%BYTES_SENT%"
      DURATION: "%DURATION%"
      REQUEST_DURATION: "%REQUEST_DURATION%"
      REQUEST_TX_DURATION: "%REQUEST_TX_DURATION%"
      RESPONSE_DURATION: "%RESPONSE_DURATION%"
      RESPONSE_TX_DURATION: "%RESPONSE_TX_DURATION%"
    body: "%REQ(:METHOD)%"
    logName: "ingress"
    grpcService:
      target:
        service:
          name: aperture-agent
          namespace: aperture-agent

The below Service Defaults adds External Authorization Envoy Extension, for the outbound listener, in the Consul Proxy running with the application.
The External Authorization extension forwards the request to the Aperture Agent instance using gRPC with a timeout of 0.25s, having egress value for key control-point metadata included in the streams initiated to the gRPC service. The extension will accept the client request even if the communication with the authorization service has failed, or if the authorization service has returned an HTTP 5xx error.
```
name: builtin/ext-authz
required: true
arguments:
  listenerType: outbound
  config:
    statPrefix: ext_authz
    timeout: 0.25s
    grpcService:
      target:
        service:
          name: aperture-agent
          namespace: aperture-agent
      initialMetadata:
        - key: control-point
          value: "egress"
```
The below Service Defaults adds External Authorization Envoy Extension, but for the inbound listener, in the Consul Proxy running with the application.
The External Authorization extension forwards the request to the Aperture Agent instance using gRPC with a timeout of 0.25s, having ingress value for key control-point metadata included in the streams initiated to the gRPC service. The extension will accept the client request even if the communication with the authorization service has failed, or if the authorization service has returned an HTTP 5xx error.
```
name: builtin/ext-authz
required: true
arguments:
  listenerType: inbound
  config:
    statPrefix: ext_authz
    timeout: 0.25s
    grpcService:
      target:
        service:
          name: aperture-agent
          namespace: aperture-agent
      initialMetadata:
        - key: control-point
          value: "ingress"
```

Installation

The complete Service Defaults configuration as an example for the Consul Proxy running with the application is as follows:

service1-demo-app-service-defaults.yaml

apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceDefaults
metadata:
  name: service1-demo-app
  namespace: demoapp
spec:
  protocol: http
  envoyExtensions:
  - name: builtin/ext-authz
    required: true
    arguments:
      listenerType: inbound
      config:
        statPrefix: ext_authz
        timeout: 0.25s
        grpcService:
          target:
            service:
              name: aperture-agent
              namespace: aperture-agent
          initialMetadata:
          - key: control-point
            value: "ingress"
  - name: builtin/otel-access-logging
    required: true
    arguments:
      listenerType: inbound
      config:
        attributes:
          aperture.source: "envoy"
          aperture.check_response: "%DYNAMIC_METADATA(envoy.filters.http.ext_authz:aperture.check_response)%"
          http.status_code: "%RESPONSE_CODE%"
          authz_duration: "%DYNAMIC_METADATA(envoy.filters.http.ext_authz:ext_authz_duration)%"
          BYTES_RECEIVED: "%BYTES_RECEIVED%"
          BYTES_SENT: "%BYTES_SENT%"
          DURATION: "%DURATION%"
          REQUEST_DURATION: "%REQUEST_DURATION%"
          REQUEST_TX_DURATION: "%REQUEST_TX_DURATION%"
          RESPONSE_DURATION: "%RESPONSE_DURATION%"
          RESPONSE_TX_DURATION: "%RESPONSE_TX_DURATION%"
        body: "%REQ(:METHOD)%"
        logName: "ingress"
        grpcService:
          target:
            service:
              name: aperture-agent
              namespace: aperture-agent
  - name: builtin/ext-authz
    required: true
    arguments:
      listenerType: outbound
      config:
        statPrefix: ext_authz
        timeout: 0.25s
        grpcService:
          target:
            service:
              name: aperture-agent
              namespace: aperture-agent
          initialMetadata:
          - key: control-point
            value: "egress"
  - name: builtin/otel-access-logging
    required: true
    arguments:
      listenerType: outbound
      config:
        attributes:
          aperture.source: "envoy"
          aperture.check_response: "%DYNAMIC_METADATA(envoy.filters.http.ext_authz:aperture.check_response)%"
          http.status_code: "%RESPONSE_CODE%"
          authz_duration: "%DYNAMIC_METADATA(envoy.filters.http.ext_authz:ext_authz_duration)%"
          BYTES_RECEIVED: "%BYTES_RECEIVED%"
          BYTES_SENT: "%BYTES_SENT%"
          DURATION: "%DURATION%"
          REQUEST_DURATION: "%REQUEST_DURATION%"
          REQUEST_TX_DURATION: "%REQUEST_TX_DURATION%"
          RESPONSE_DURATION: "%RESPONSE_DURATION%"
          RESPONSE_TX_DURATION: "%RESPONSE_TX_DURATION%"
        body: "%REQ(:METHOD)%"
        logName: "egress"
        grpcService:
          target:
            service:
              name: aperture-agent
              namespace: aperture-agent

To install the above Service Defaults, run the following command:

kubectl apply -f service1-demo-app-service-defaults.yaml

Verifying the Installation

To verify the installation, run the following command:

kubectl get servicedefaults -n demoapp service1-demo-app -o yaml

Uninstall

To uninstall the Service Defaults, run the following command:

kubectl delete servicedefaults -n demoapp service1-demo-app

Supported Versions​

Envoy Extensions​

Installation​

Verifying the Installation​

Uninstall​

Supported Versions

Envoy Extensions

Installation

Verifying the Installation

Uninstall