Classifier

info

See also Classifier reference

The Classifier can be used to create additional Flow Labels based on request metadata without requiring any changes to your service, if the existing flow labels aren't sufficient.

To define a Classifier, it needs to be added as a resource in a policy. It specifies a set of rules to create new flow labels based on request metadata. Envoy's External Authorization definition is used by Aperture to describe the request metadata, specifically the AttributeContext. An example of how the request attributes might look can be seen in the INPUT section at this Rego playground.

note

At Feature Control Points, developers can already provide arbitrary flow labels by setting baggage or directly as arguments to the Check() call. As flow labels can be effortlessly provided at Feature control points by the developers, Classifiers are available only at HTTP control points.

Any Flow Labels created through the Classifier are immediately available for use in other components at the same Control Point. Additionally, the Flow Label is injected as baggage, so it will be available on every subsequent control point too (assuming you have baggage propagation configured in your system). If you're a FluxNinja ARC extension user, such flow label will also be available for analytics.

note

Both these behaviors (baggage propagation and inclusion in telemetry) can be disabled.

caution

Although Classifier is defined as a resource in a Policy, Flow Labels aren't isolated in any way and are shared across policies.

Selectors

Each Classifier needs to specify which control point it will be run at. For instance, the following selector is for the "ingress" control point at a service:

selectors:
  - service: service1.default.svc.cluster.local
    control_point: ingress

You can be more precise by adding a Label Matcher and, for example, gate the Classifier to particular paths.

Live Previewing Requests

You can discover the request attributes flowing through services and control points using aperturectl.

For example:

aperturectl flow-control preview --kube service1-demo-app.demoapp.svc.cluster.local ingress --http

Returns:

{
  "samples": [
    {
      "attributes": {
        "destination": {
          "address": {
            "socketAddress": {
              "address": "10.244.1.20",
              "portValue": 8099
            }
          }
        },
        "metadataContext": {},
        "request": {
          "http": {
            "headers": {
              ":authority": "service1-demo-app.demoapp.svc.cluster.local",
              ":method": "POST",
              ":path": "/request",
              ":scheme": "http",
              "content-length": "201",
              "content-type": "application/json",
              "cookie": "session=eyJ1c2VyIjoia2Vub2JpIn0.YbsY4Q.kTaKRTyOIfVlIbNB48d9YH6Q0wo",
              "user-agent": "k6/0.42.0 (https://k6.io/)",
              "user-id": "19",
              "user-type": "guest",
              "x-forwarded-proto": "http",
              "x-request-id": "26f01736-ec45-4b07-a202-bdec8930c7f8"
            },
            "host": "service1-demo-app.demoapp.svc.cluster.local",
            "id": "14553976531353216255",
            "method": "POST",
            "path": "/request",
            "protocol": "HTTP/1.1",
            "scheme": "http"
          },
          "time": "2023-01-15T07:07:48.693035Z"
        },
        "source": {
          "address": {
            "socketAddress": {
              "address": "10.244.2.36",
              "portValue": 35388
            }
          }
        }
      },
      "parsed_body": null,
      "parsed_path": ["request"],
      "parsed_query": {},
      "truncated_body": false,
      "version": {
        "encoding": "protojson",
        "ext_authz": "v3"
      }
    }
  ]
}

Alternatively, you can use the Introspection API directly on a aperture-agent local to the service instances (pods):

curl -X POST localhost:8080/v1/flowcontrol/preview/http_requests/service1-demo-app.demoapp.svc.cluster.local/ingress?samples=1

Rules (reference)

In addition to the selectors, a Classifier needs to specify classification rules. Each classification rule consists of:

• Flow Label key,
• A rule how to extract the flow label value based on request metadata.

There are two ways to specify a classification rule: using declarative extractors and Rego modules. See examples in reference.

Request body availability

The possibility of extracting values from the request body depends on how External Authorization in Envoy was configured. The Sample Istio Configuration provided by FluxNinja does not enable request body buffering by default, as it might break some streaming APIs.

Extractors (reference)

Extractors are declarative recipes how to extract flow label value from metadata. Provided extractors include:

• Extracting values from headers
• Parsing a field from JSON encoded request payload
• Parsing JWT tokens

Aperture aims to expand the set of extractors to cover the most-common use cases.

caution

Keys of flow labels created by extractors must be valid Rego identifiers (alphanumeric characters and underscore are allowed; also, label name cannot be a Rego keyword, like if or default).

note

Extracting the value from the header might not seem useful, as the value is already available as Flow Label (as http.request.header.<header>), but adding flow label explicitly might still be useful, as it enables baggage propagation and telemetry for this flow label.

Rego (reference)

For more advanced cases, you can define the extractor in the Rego language.

Example

See full example in reference