Skip to main content
Version: 2.34.0

Istio

Istio

Istio

Supported Versions

Aperture supports the following version of Istio:

PlatformExtent of Support
Istio1.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 upgrade --install aperture-envoy-filter aperture/istioconfig --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 upgrade --install aperture-envoy-filter aperture/istioconfig --namespace ISTIOD_NAMESPACE_HERE -f 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 upgrade --install aperture-envoy-filter aperture/istioconfig --namespace ISTIOD_NAMESPACE_HERE -f 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 upgrade --install aperture-envoy-filter aperture/istioconfig --namespace ISTIOD_NAMESPACE_HERE -f 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 uninstall aperture-envoy-filter