Skip to content

Commit

Permalink
Add Flow Label to concepts in docs (#294)
Browse files Browse the repository at this point in the history 
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).
  • Loading branch information
@krdln
krdln authored Sep 2, 2022
1 parent 46456db commit 4e0cf9e
Show file tree
Hide file tree
Showing 18 changed files with 327 additions and 164 deletions.
4 changes: 3 additions & 1 deletion api/aperture/common/labelmatcher/v1/labelmatcher.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
28 changes: 12 additions & 16 deletions api/aperture/common/selector/v1/selector.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}

Expand Down
13 changes: 10 additions & 3 deletions api/aperture/policy/language/v1/classifier.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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;
}

Expand Down Expand Up @@ -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.
Expand All @@ -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 {
Expand Down
21 changes: 11 additions & 10 deletions api/aperture/policy/language/v1/policy.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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) = {
Expand Down Expand Up @@ -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;
}

Expand All @@ -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`).
Expand All @@ -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
Expand Down
70 changes: 40 additions & 30 deletions api/gen/openapiv2/aperture.swagger.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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`).
Expand Down Expand Up @@ -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: |-
Expand Down
4 changes: 3 additions & 1 deletion api/gen/proto/go/aperture/common/labelmatcher/v1/labelmatcher.pb.go
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

28 changes: 12 additions & 16 deletions api/gen/proto/go/aperture/common/selector/v1/selector.pb.go
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

13 changes: 10 additions & 3 deletions api/gen/proto/go/aperture/policy/language/v1/classifier.pb.go
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading

0 comments on commit 4e0cf9e

Please sign in to comment.