Add Flow Label to concepts in docs

This page is now the source of truth about flow labels. Previously it was partially documented in selector reference, now selector just links to Flow Label page. Also: * pulled out Service out of Selector (stub), * added stub pages for fluxmeters and classifier (so that we can link to them).
fluxninja · Sep 2, 2022 · 893ddbb · 893ddbb
1 parent 46456db
commit 893ddbb
Show file tree

Hide file tree

Showing 18 changed files with 327 additions and 164 deletions.
diff --git a/api/aperture/common/labelmatcher/v1/labelmatcher.proto b/api/aperture/common/labelmatcher/v1/labelmatcher.proto
@@ -4,7 +4,9 @@ package aperture.common.labelmatcher.v1;
 
 import "protoc-gen-openapiv2/options/annotations.proto";
 
-// Allows to define rules whether a map of labels should be considered a match or not
+// Allows to define rules whether a map of
+// [labels](/concepts/flow-control/label/label.md)
+// should be considered a match or not
 //
 // It provides three ways to define requirements:
 // - matchLabels

diff --git a/api/aperture/common/selector/v1/selector.proto b/api/aperture/common/selector/v1/selector.proto
@@ -52,24 +52,20 @@ message Selector {
     }
   }]; // @gotags: validate:"required"
 
-  // Label matcher allows to add _additional_ condition on labels that must
-  // also be satisfied (in addition to service+control point matching)
+  // Label matcher allows to add _additional_ condition on
+  // [flow labels](/concepts/flow-control/label/label.md)
+  // must also be satisfied (in addition to service+control point matching)
   //
-  // This matcher allows to match on flow labels and request labels.
-  // (Note: For classification we can only match flow labels that were created at
-  // some **previous** control point).
+  // :::note
+  // [Classifiers](#-v1classifier) _can_ use flow labels created by some other
+  // classifier, but only if they were created at some previous control point
+  // (and propagated in baggage).
   //
-  // Flow labels are available with the same label key as defined in
-  // classification rule.
-  //
-  // Request labels are always prefixed with `request_`. Available request
-  // labels are `id` (available as `request_id`), `method`, `path`, `host`,
-  // `scheme`, `size`, `protocol` (mapped from fields of
-  // [HttpRequest](https://github.com/envoyproxy/envoy/blob/637a92a56e2739b5f78441c337171968f18b46ee/api/envoy/service/auth/v3/attribute_context.proto#L102)).
-  // Also, (non-pseudo) headers are available as `request_header_<headername>`, where
-  // `<headername>` is a headername normalised to lowercase, eg. `request_header_user-agent`.
-  //
-  // Note: Request headers are only available for `traffic` control points.
+  // This limitation doesn't apply to selectors of other entities, like
+  // FluxMeters or actuators. It's valid to create a flow label on a control
+  // point using classifier, and immediately use it for matching on the same
+  // control point.
+  // :::
   common.labelmatcher.v1.LabelMatcher label_matcher = 4;
 }
 

diff --git a/api/aperture/policy/language/v1/classifier.proto b/api/aperture/policy/language/v1/classifier.proto
@@ -8,6 +8,10 @@ import "protoc-gen-openapiv2/options/annotations.proto";
 
 // Set of classification rules sharing a common selector
 //
+// :::info
+// See also [Classifier overview](/concepts/flow-control/label/classifier.md).
+// :::
+//
 // Example:
 // ```yaml
 // selector:
@@ -23,7 +27,9 @@ message Classifier {
   // Defines where to apply the flow classification rule.
   common.selector.v1.Selector selector = 1;
 
-  // A map of {key, value} pairs mapping from flow label names to rules that define how to extract and propagate them.
+  // A map of {key, value} pairs mapping from
+  // [flow label](/concepts/flow-control/label/label.md) keys to rules that define
+  // how to extract and propagate flow labels with that key.
   map<string, Rule> rules = 2;
 }
 
@@ -87,7 +93,8 @@ message Rule {
   }
 
   // Decides if the created label should be applied to the whole request chain
-  // (propagated in baggage) (default=true).
+  // (propagated in [baggage](/concepts/flow-control/label/label.md#baggage))
+  // (default=true).
   google.protobuf.BoolValue propagate = 3;
 
   // Decides if the created flow label should be hidden from the telemetry.
@@ -104,7 +111,7 @@ message Rule {
   bool hidden = 4;
 }
 
-// Defines a high-level way to specify how to extract a flow label given http request metadata, without a need to write rego code
+// Defines a high-level way to specify how to extract a flow label value given http request metadata, without a need to write rego code
 //
 // There are multiple variants of extractor, specify exactly one.
 message Extractor {

diff --git a/api/aperture/policy/language/v1/policy.proto b/api/aperture/policy/language/v1/policy.proto
@@ -608,9 +608,10 @@ message RateLimiter {
 
   // Specifies which label the ratelimiter should be keyed by.
   //
-  // Rate limiting is done independently for each value of the label with given
-  // key. Eg., to give each user a separate limit, assuming you have a _user_
-  // flow label set up, set `label_key: "user"`.
+  // Rate limiting is done independently for each value of the
+  // [label](/concepts/flow-control/label/label.md) with given key.
+  // Eg., to give each user a separate limit, assuming you have a _user_ flow
+  // label set up, set `label_key: "user"`.
   //
   // TODO make it possible for this field to be optional – to achieve global ratelimit.
   string label_key = 4 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
@@ -696,19 +697,19 @@ message Scheduler {
       }
     }]; // @gotags: default:"1"
 
-    // Fairness key is a label key that can be used to provide fairness within a workload
-    //
-    // Any label that could be used in label matcher can be used here. Eg. if
+    // Fairness key is a label key that can be used to provide fairness within a workload.
+    // Any [flow label](/concepts/flow-control/label/label.md) can be used here. Eg. if
     // you have a classifier that sets `user` flow label, you might want to set
     // `fairness_key = "user"`.
     string fairness_key = 3;
   }
 
   message WorkloadAndLabelMatcher {
-    // Workload associated with requests matching the label matcher.
+    // Workload associated with flows matching the label matcher.
     Workload workload = 1;
 
-    // Label Matcher to select a Workload.
+    // Label Matcher to select a Workload based on
+    // [flow labels](/concepts/flow-control/label/label.md).
     common.labelmatcher.v1.LabelMatcher label_matcher = 2;
   }
 
@@ -718,7 +719,7 @@ message Scheduler {
     //
     // :::info
     // **Accepted tokens** are tokens associated with
-    // [flows](/concepts/flow-control/flow-control.md#what-is-a-flow) that were accepted by
+    // [flows](/concepts/flow-control/flow-control.md#flow) that were accepted by
     // this scheduler. Number of tokens for a flow is determined by a
     // [workload](#-schedulerworkload) that the flow was assigned to (either
     // via `auto_tokens` or explicitly by `Workload.tokens`).
@@ -741,7 +742,7 @@ message Scheduler {
 
   // List of workloads to be used in scheduler.
   //
-  // Categorizing [flows](/concepts/flow-control/flow-control.md#what-is-a-flow) into workloads
+  // Categorizing [flows](/concepts/flow-control/flow-control.md#flow) into workloads
   // allows for load-shedding to be "smarter" than just "randomly deny 50% of
   // requests". There are two aspects of this "smartness":
   // * Scheduler can more precisely calculate concurrency if it understands

diff --git a/api/gen/openapiv2/aperture.swagger.yaml b/api/gen/openapiv2/aperture.swagger.yaml
@@ -232,10 +232,10 @@ definitions:
       fairness_key:
         type: string
         description: |-
-          Any label that could be used in label matcher can be used here. Eg. if
+          Fairness key is a label key that can be used to provide fairness within a workload.
+          Any [flow label](/concepts/flow-control/label/label.md) can be used here. Eg. if
           you have a classifier that sets `user` flow label, you might want to set
           `fairness_key = "user"`.
-        title: Fairness key is a label key that can be used to provide fairness within a workload
       priority:
         type: integer
         format: int64
@@ -257,10 +257,12 @@ definitions:
     properties:
       label_matcher:
         $ref: '#/definitions/v1LabelMatcher'
-        description: Label Matcher to select a Workload.
+        description: |-
+          Label Matcher to select a Workload based on
+          [flow labels](/concepts/flow-control/label/label.md).
       workload:
         $ref: '#/definitions/SchedulerWorkload'
-        description: Workload associated with requests matching the label matcher.
+        description: Workload associated with flows matching the label matcher.
   apertureflowcontrolv1FluxMeter:
     type: object
     properties:
@@ -318,9 +320,10 @@ definitions:
         description: |-
           Specifies which label the ratelimiter should be keyed by.
 
-          Rate limiting is done independently for each value of the label with given
-          key. Eg., to give each user a separate limit, assuming you have a _user_
-          flow label set up, set `label_key: "user"`.
+          Rate limiting is done independently for each value of the
+          [label](/concepts/flow-control/label/label.md) with given key.
+          Eg., to give each user a separate limit, assuming you have a _user_ flow
+          label set up, set `label_key: "user"`.
 
           TODO make it possible for this field to be optional – to achieve global ratelimit.
         x-go-validate: required
@@ -654,11 +657,18 @@ definitions:
         type: object
         additionalProperties:
           $ref: '#/definitions/v1Rule'
-        description: A map of {key, value} pairs mapping from flow label names to rules that define how to extract and propagate them.
+        description: |-
+          A map of {key, value} pairs mapping from
+          [flow label](/concepts/flow-control/label/label.md) keys to rules that define
+          how to extract and propagate flow labels with that key.
       selector:
         $ref: '#/definitions/v1Selector'
         description: Defines where to apply the flow classification rule.
     description: |-
+      :::info
+      See also [Classifier overview](/concepts/flow-control/label/classifier.md).
+      :::
+
       Example:
       ```yaml
       selector:
@@ -1010,7 +1020,7 @@ definitions:
         $ref: '#/definitions/v1PathTemplateMatcher'
         description: Match HTTP Path to given path templates.
     description: There are multiple variants of extractor, specify exactly one.
-    title: Defines a high-level way to specify how to extract a flow label given http request metadata, without a need to write rego code
+    title: Defines a high-level way to specify how to extract a flow label value given http request metadata, without a need to write rego code
   v1Extrapolator:
     type: object
     properties:
@@ -1251,7 +1261,10 @@ definitions:
 
       If multiple requirements are set, they are all ANDed.
       An empty label matcher always matches.
-    title: Allows to define rules whether a map of labels should be considered a match or not
+    title: |-
+      Allows to define rules whether a map of
+      [labels](/concepts/flow-control/label/label.md)
+      should be considered a match or not
   v1LimiterDecision:
     type: object
     properties:
@@ -1603,7 +1616,8 @@ definitions:
         type: boolean
         description: |-
           Decides if the created label should be applied to the whole request chain
-          (propagated in baggage) (default=true).
+          (propagated in [baggage](/concepts/flow-control/label/label.md#baggage))
+          (default=true).
       rego:
         $ref: '#/definitions/RuleRego'
         description: Rego module to extract a value from the rego module.
@@ -1700,7 +1714,7 @@ definitions:
         description: |-
           List of workloads to be used in scheduler.
 
-          Categorizing [flows](/concepts/flow-control/flow-control.md#what-is-a-flow) into workloads
+          Categorizing [flows](/concepts/flow-control/flow-control.md#flow) into workloads
           allows for load-shedding to be "smarter" than just "randomly deny 50% of
           requests". There are two aspects of this "smartness":
           * Scheduler can more precisely calculate concurrency if it understands
@@ -1736,7 +1750,7 @@ definitions:
 
           :::info
           **Accepted tokens** are tokens associated with
-          [flows](/concepts/flow-control/flow-control.md#what-is-a-flow) that were accepted by
+          [flows](/concepts/flow-control/flow-control.md#flow) that were accepted by
           this scheduler. Number of tokens for a flow is determined by a
           [workload](#-schedulerworkload) that the flow was assigned to (either
           via `auto_tokens` or explicitly by `Workload.tokens`).
@@ -1764,24 +1778,20 @@ definitions:
       label_matcher:
         $ref: '#/definitions/v1LabelMatcher'
         description: |-
-          This matcher allows to match on flow labels and request labels.
-          (Note: For classification we can only match flow labels that were created at
-          some **previous** control point).
-
-          Flow labels are available with the same label key as defined in
-          classification rule.
-
-          Request labels are always prefixed with `request_`. Available request
-          labels are `id` (available as `request_id`), `method`, `path`, `host`,
-          `scheme`, `size`, `protocol` (mapped from fields of
-          [HttpRequest](https://github.com/envoyproxy/envoy/blob/637a92a56e2739b5f78441c337171968f18b46ee/api/envoy/service/auth/v3/attribute_context.proto#L102)).
-          Also, (non-pseudo) headers are available as `request_header_<headername>`, where
-          `<headername>` is a headername normalised to lowercase, eg. `request_header_user-agent`.
-
-          Note: Request headers are only available for `traffic` control points.
+          :::note
+          [Classifiers](#-v1classifier) _can_ use flow labels created by some other
+          classifier, but only if they were created at some previous control point
+          (and propagated in baggage).
+
+          This limitation doesn't apply to selectors of other entities, like
+          FluxMeters or actuators. It's valid to create a flow label on a control
+          point using classifier, and immediately use it for matching on the same
+          control point.
+          :::
         title: |-
-          Label matcher allows to add _additional_ condition on labels that must
-          also be satisfied (in addition to service+control point matching)
+          Label matcher allows to add _additional_ condition on
+          [flow labels](/concepts/flow-control/label/label.md)
+          must also be satisfied (in addition to service+control point matching)
       service:
         type: string
         description: |-

diff --git a/api/gen/proto/go/aperture/common/labelmatcher/v1/labelmatcher.pb.go b/api/gen/proto/go/aperture/common/labelmatcher/v1/labelmatcher.pb.go
diff --git a/api/gen/proto/go/aperture/common/selector/v1/selector.pb.go b/api/gen/proto/go/aperture/common/selector/v1/selector.pb.go
diff --git a/api/gen/proto/go/aperture/policy/language/v1/classifier.pb.go b/api/gen/proto/go/aperture/policy/language/v1/classifier.pb.go