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
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
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.
Both these behaviors (baggage propagation and inclusion in telemetry) can be disabled.
Although Classifier is defined as a resource in a Policy, Flow Labels aren't isolated in any way and are shared across policies.
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:
- service: service1.default.svc.cluster.local
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
aperturectl flow-control preview --kube service1-demo-app.demoapp.svc.cluster.local ingress --http
"user-agent": "k6/0.42.0 (https://k6.io/)",
Alternatively, you can use the
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
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.
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 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.
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
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.
For more advanced cases, you can define the extractor in the Rego language.