Istio

Supported Versions

Aperture supports the following version of Istio:

Platform	Extent of Support
Istio	1.14 and above

info

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

Envoy Filter

The Envoy Filter is used to customize the default configurations generated by the Istio. The Aperture Agent requires additional details and needs the following Configuration Patches to be added through the Envoy Filter.

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 address value aperture-agent.aperture-agent.svc.cluster.local. If you are running the Aperture Agent in Sidecar mode, use localhost as the target address.

1. The below patch merges the Access Log configuration of type Open Telemetry with extracted values from the filter, to the HTTP Connection Manager filter for the outbound listener, in the Istio sidecar running with the application.

   The OpenTelemetry configuration in the following patch 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.

   applyTo: NETWORK_FILTER
   match:
     context: SIDECAR_OUTBOUND
     listener:
       filterChain:
         filter:
           name: "envoy.filters.network.http_connection_manager"
   patch:
     operation: MERGE
     value:
       name: "envoy.filters.network.http_connection_manager"
       typed_config:
         "@type": "type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager"
         access_log:
           - name: envoy.access_loggers.open_telemetry
             typed_config:
               "@type": "type.googleapis.com/envoy.extensions.access_loggers.open_telemetry.v3.OpenTelemetryAccessLogConfig"
               common_config:
                 log_name: egress
                 grpc_service:
                   google_grpc:
                     target_uri: aperture-agent.aperture-agent.svc.cluster.local:4317
                     stat_prefix: fn_otlp_access_log
                 transport_api_version: V3
               body:
                 string_value: "%REQ(:METHOD)%"
               attributes:
                 values:
                   - key: aperture.source
                     value:
                       string_value: "envoy"
                   - key: aperture.check_response
                     value:
                       string_value: "%DYNAMIC_METADATA(envoy.filters.http.ext_authz:aperture.check_response)%"
                   - key: http.status_code
                     value:
                       string_value: "%RESPONSE_CODE%"
                   - key: authz_duration
                     value:
                       string_value: "%DYNAMIC_METADATA(envoy.filters.http.ext_authz:ext_authz_duration)%"
                   - key: BYTES_RECEIVED
                     value:
                       string_value: "%BYTES_RECEIVED%"
                   - key: BYTES_SENT
                     value:
                       string_value: "%BYTES_SENT%"
                   - key: DURATION
                     value:
                       string_value: "%DURATION%"
                   - key: REQUEST_DURATION
                     value:
                       string_value: "%REQUEST_DURATION%"
                   - key: REQUEST_TX_DURATION
                     value:
                       string_value: "%REQUEST_TX_DURATION%"
                   - key: RESPONSE_DURATION
                     value:
                       string_value: "%RESPONSE_DURATION%"
                   - key: RESPONSE_TX_DURATION
                     value:
                       string_value: "%RESPONSE_TX_DURATION%"

2. The below patch also merges the Access Log configuration of type Open Telemetry to the HTTP Connection Manager filter, but for the inbound listener in the Istio sidecar running with the application.

   The OpenTelemetry configuration in the following patch 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.

   applyTo: NETWORK_FILTER
   match:
     context: SIDECAR_INBOUND
     listener:
       filterChain:
         filter:
           name: "envoy.filters.network.http_connection_manager"
   patch:
     operation: MERGE
     value:
       name: "envoy.filters.network.http_connection_manager"
       typed_config:
         "@type": "type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager"
         access_log:
           - name: envoy.access_loggers.open_telemetry
             typed_config:
               "@type": "type.googleapis.com/envoy.extensions.access_loggers.open_telemetry.v3.OpenTelemetryAccessLogConfig"
               common_config:
                 log_name: ingress
                 grpc_service:
                   google_grpc:
                     target_uri: aperture-agent.aperture-agent.svc.cluster.local:4317
                     stat_prefix: fn_otlp_access_log
                 transport_api_version: V3
               body:
                 string_value: "%REQ(:METHOD)%"
               attributes:
                 values:
                   - key: aperture.source
                     value:
                       string_value: "envoy"
                   - key: aperture.check_response
                     value:
                       string_value: "%DYNAMIC_METADATA(envoy.filters.http.ext_authz:aperture.check_response)%"
                   - key: http.status_code
                     value:
                       string_value: "%RESPONSE_CODE%"
                   - key: authz_duration
                     value:
                       string_value: "%DYNAMIC_METADATA(envoy.filters.http.ext_authz:ext_authz_duration)%"
                   - key: BYTES_RECEIVED
                     value:
                       string_value: "%BYTES_RECEIVED%"
                   - key: BYTES_SENT
                     value:
                       string_value: "%BYTES_SENT%"
                   - key: DURATION
                     value:
                       string_value: "%DURATION%"
                   - key: REQUEST_DURATION
                     value:
                       string_value: "%REQUEST_DURATION%"
                   - key: REQUEST_TX_DURATION
                     value:
                       string_value: "%REQUEST_TX_DURATION%"
                   - key: RESPONSE_DURATION
                     value:
                       string_value: "%RESPONSE_DURATION%"
                   - key: RESPONSE_TX_DURATION
                     value:
                       string_value: "%RESPONSE_TX_DURATION%"

3. The below patch inserts the External Authorization before the Router sub-filter of the HTTP Connection Manager filter for inbound listener in the Istio sidecar running with the application.

   The External Authorization filter forwards the request to the Aperture Agent instance using gRPC with a timeout of 0.5s, having ingress value for key control-point metadata included in the streams initiated to the gRPC service. The filter 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.

   applyTo: HTTP_FILTER
   match:
     context: SIDECAR_INBOUND
     listener:
       filterChain:
         filter:
           name: "envoy.filters.network.http_connection_manager"
           subFilter:
             name: "envoy.filters.http.router"
   patch:
     operation: INSERT_BEFORE
     filterClass: AUTHZ
     value:
       name: envoy.filters.http.ext_authz
       typed_config:
         "@type": "type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz"
         transport_api_version: V3
         failure_mode_allow: true
         grpc_service:
           google_grpc:
             target_uri: aperture-agent.aperture-agent.svc.cluster.local:80
             stat_prefix: ext_authz
           timeout: 0.5s
           initial_metadata:
             - key: control-point
               value: ingress

4. The below patch also inserts the External Authorization before the Router sub-filter of the HTTP Connection Manager filter, but for the outbound listener in the Istio sidecar running with the application.

   The External Authorization filter forwards the request to the Aperture Agent instance using gRPC with a timeout of 0.5s, having egress value for key control-point metadata included in the streams initiated to the gRPC service. The filter 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.

   applyTo: HTTP_FILTER
   match:
     context: SIDECAR_OUTBOUND
     listener:
       filterChain:
         filter:
           name: "envoy.filters.network.http_connection_manager"
           subFilter:
             name: "envoy.filters.http.router"
   patch:
     operation: INSERT_BEFORE
     filterClass: AUTHZ
     value:
       name: envoy.filters.http.ext_authz
       typed_config:
         "@type": "type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz"
         transport_api_version: V3
         failure_mode_allow: true
         grpc_service:
           google_grpc:
             target_uri: aperture-agent.aperture-agent.svc.cluster.local:80
             stat_prefix: ext_authz
           timeout: 0.5s
           initial_metadata:
             - key: control-point
               value: egress

More information about the extracted values can be found on this site.

Prerequisites

You can do the installation using the aperturectl CLI tool or using Helm. Install the tool of your choice using the following links:

1. Helm

   1. Once the Helm CLI is installed, add the Aperture Agent Helm chart repository in your environment for install or upgrade:

      helm repo add aperture https://fluxninja.github.io/aperture/
      helm repo update

2. Aperturectl

   Refer

   Aperturectl install agent to see all the available command line arguments.

Installation

Below are the steps to install or upgrade the example Istio EnvoyFilter into your setup using the Aperture istioconfig Helm chart.

By following these instructions, you will have installed the Istio EnvoyFilter into your cluster.

1. Run the below command to install or upgrade the Istio EnvoyFilter:

   info

   Replace the value of ISTIOD_NAMESPACE_HERE with the namespace in which istiod is running. This way, the Istio EnvoyFilter will be applied to all the pods having Istio sidecar injected across namespaces.

   If you want to apply the Istio EnvoyFilter to a particular namespace, replace the value of ISTIOD_NAMESPACE_HERE with that namespace.

   Helm

   helm upgrade --install aperture-envoy-filter aperture/istioconfig --namespace ISTIOD_NAMESPACE_HERE

   aperturectl

   aperturectl install istioconfig --version v2.32.2 --namespace ISTIOD_NAMESPACE_HERE

   The default values for the Aperture Agent service namespace is aperture-agent, port is 8080 and sidecar mode is false. This makes the Aperture Agent target address aperture-agent.aperture-agent.svc.cluster.local:8080. If you have installed the Aperture Agent in a different namespace or different port, you can create or update the values.yaml file and pass it with the install command:

   envoyFilter:
     namespace: APERTURE_AGENT_NAMESPACE_HERE
     port: APERTURE_AGENT_SERVER_PORT_HERE
   Helm

   helm upgrade --install aperture-envoy-filter aperture/istioconfig --namespace ISTIOD_NAMESPACE_HERE -f values.yaml

   aperturectl

   aperturectl install istioconfig --version v2.32.2 --namespace ISTIOD_NAMESPACE_HERE --values-file values.yaml

2. If you want to apply the Istio EnvoyFilter to specific workloads, you can use the workloadSelector parameter. For example, if you want to apply the Istio EnvoyFilter to the pods having the label app.kubernetes.io/name=service1, you can create or update the values.yaml file and pass it with the install command:

   envoyFilter:
     workloadSelector:
       labels:
         app.kubernetes.io/name: service1
   Helm

   helm upgrade --install aperture-envoy-filter aperture/istioconfig --namespace ISTIOD_NAMESPACE_HERE -f values.yaml

   aperturectl

   aperturectl install istioconfig --version v2.32.2 --namespace ISTIOD_NAMESPACE_HERE --values-file values.yaml

3. If you want to modify the default parameters of the chart, for example sidecarMode, you can create or update the values.yaml file and pass it with install command:

   envoyFilter:
     sidecarMode: true
   Helm

   helm upgrade --install aperture-envoy-filter aperture/istioconfig --namespace ISTIOD_NAMESPACE_HERE -f values.yaml

   aperturectl

   aperturectl install istioconfig --version v2.32.2 --namespace ISTIOD_NAMESPACE_HERE --values-file values.yaml

   A list of configurable parameters for the installation can be found in the README.

Verifying the Installation

Once you have successfully deployed the resources, confirm that the Istio EnvoyFilter is created:

kubectl get envoyfilter aperture-envoy-filter -n ISTIOD_NAMESPACE_HERE

You should see a Kubernetes custom resource for the Istio EnvoyFilter.

Uninstall

You can uninstall the Istio EnvoyFilter installed above by following the following steps:

1. Uninstall the Aperture istioconfig:

   Helm

   helm uninstall aperture-envoy-filter

   aperturectl

   aperturectl uninstall istioconfig