Policy Language Specification
Reference for all objects used in the Policy language.
The top-level object representing a policy is Policy.
Objects
AdaptiveLoadScheduler
The Adaptive Load Scheduler adjusts the accepted token rate based on the deviation of the input signal from the setpoint.
- dry_run
(bool)
Decides whether to run the load scheduler in dry-run mode. In dry run mode the scheduler acts as pass through to all flow and does not queue flows. It is useful for observing the behavior of load scheduler without disrupting any real traffic.
- dry_run_config_key
(string)
Configuration key for setting dry run mode through dynamic configuration.
- in_ports
Collection of input ports for the Adaptive Load Scheduler component.
- out_ports
Collection of output ports for the Adaptive Load Scheduler component.
- parameters
(AdaptiveLoadSchedulerParameters)
Parameters for the Adaptive Load Scheduler component.
AdaptiveLoadSchedulerIns
Input ports for the Adaptive Load Scheduler component.
- overload_confirmation
(InPort)
The
overload_confirmation
port provides additional criteria to determine overload state which results in Flow throttling at the service.- setpoint
(InPort)
The setpoint input to the controller.
- signal
(InPort)
The input signal to the controller.
AdaptiveLoadSchedulerOuts
Output ports for the Adaptive Load Scheduler component.
- desired_load_multiplier
(OutPort)
Desired Load multiplier is the ratio of desired token rate to the incoming token rate.
- is_overload
(OutPort)
A Boolean signal that indicates whether the service is in overload state.
- observed_load_multiplier
(OutPort)
Observed Load multiplier is the ratio of accepted token rate to the incoming token rate.
AdaptiveLoadSchedulerParameters
Parameters for the Adaptive Load Scheduler component.
- alerter
Configuration parameters for the embedded Alerter.
- gradient
(GradientControllerParameters)
Parameters for the Gradient Controller.
- load_multiplier_linear_increment
(float64, default:
0.0025
)Linear increment to load multiplier in each execution tick when the system is not in the overloaded state, up until the
max_load_multiplier
is reached.- load_scheduler
Parameters for the Load Scheduler.
- max_load_multiplier
(float64, default:
2
)The maximum load multiplier that can be reached during recovery from an overload state.
- Helps protect the service from request bursts while the system is still recovering.
- Once this value is reached, the scheduler enters the pass-through mode, allowing requests to bypass the scheduler and be sent directly to the service.
- Any future overload state is detected by the control policy, and the load multiplier increment cycle is restarted.
AddressExtractor
Display an Address as a single string, for example,
<ip>:<port>
IP addresses in attribute context are defined as objects with separate IP and port fields. This is a helper to display an address as a single string.
This might introduce high-cardinality flow label values.
Example:
from: "source.address # or destination.address"
- from
(string, required)
Attribute path pointing to some string - for example,
source.address
.
Alerter
Alerter reacts to a signal and generates alert to send to alert manager.
- in_ports
Input ports for the Alerter component.
- parameters
Alerter configuration
AlerterIns
Inputs for the Alerter component.
- signal
(InPort)
Signal which Alerter is monitoring. If the signal greater than 0, Alerter generates an alert.
AlerterParameters
Alerter Parameters configure parameters such as alert name, severity, resolve timeout, alert channels and labels.
- alert_channels
([]string)
A list of alert channel strings.
- alert_name
(string, required)
Name of the alert.
- labels
(map of string)
Additional labels to add to alert.
- resolve_timeout
(string, default:
"5s"
)Duration of alert resolver. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.
- severity
(string, one of:
info | warn | crit
, default:"info"
)Severity of the alert, one of 'info', 'warn' or 'crit'.
And
Logical AND.
Signals are mapped to Boolean values as follows:
Zero is treated as false.
Any non-zero is treated as true.
Invalid inputs are considered unknown.
noteTreating invalid inputs as "unknowns" has a consequence that the result might end up being valid even when some inputs are invalid. For example,
unknown && false == false
, because the result would end up false no matter if first signal was true or false. Conversely,unknown && true == unknown
.
- in_ports
(AndIns)
Input ports for the And component.
- out_ports
(AndOuts)
Output ports for the And component.
AndIns
Inputs for the And component.
- inputs
([]InPort)
Array of input signals.
AndOuts
Output ports for the And component.
- output
(OutPort)
Result of logical AND of all the input signals.
Will always be 0 (false), 1 (true) or invalid (unknown).
ArithmeticCombinator
Type of Combinator that computes the arithmetic operation on the operand signals
- in_ports
Input ports for the Arithmetic Combinator component.
- operator
(string, one of:
add | sub | mul | div | xor | lshift | rshift
)Operator of the arithmetic operation.
The arithmetic operation can be addition, subtraction, multiplication, division, XOR, right bit shift or left bit shift. In case of XOR and bit shifts, value of signals is cast to integers before performing the operation.
- out_ports
Output ports for the Arithmetic Combinator component.
ArithmeticCombinatorIns
Inputs for the Arithmetic Combinator component.
- lhs
(InPort)
Left hand side of the arithmetic operation.
- rhs
(InPort)
Right hand side of the arithmetic operation.
ArithmeticCombinatorOuts
Outputs for the Arithmetic Combinator component.
- output
(OutPort)
Result of arithmetic operation.
AutoScale
AutoScale components are used to scale a service.
- auto_scaler
AutoScaler provides auto-scaling functionality for any scalable resource.
- pod_scaler
PodScaler provides pod horizontal scaling functionality for scalable Kubernetes resources.
AutoScaler
AutoScaler provides auto-scaling functionality for any scalable resource. Multiple Controllers can be defined on the AutoScaler for performing scale-out or scale-in. The AutoScaler can interface with infrastructure APIs such as Kubernetes to perform auto-scale.
- dry_run
(bool)
Dry run mode ensures that no scaling is invoked by this auto scaler. This is useful for observing the behavior of auto scaler without disrupting any real deployment. This parameter sets the default value of dry run setting which can be overridden at runtime using dynamic configuration.
- dry_run_config_key
(string)
Configuration key for overriding dry run setting through dynamic configuration.
- scale_in_controllers
List of Controllers for scaling in.
- scale_out_controllers
List of Controllers for scaling out.
- scaling_backend
- scaling_parameters
Parameters that define the scaling behavior.
AutoScalerScalingBackend
- kubernetes_replicas
AutoScalerScalingBackendKubernetesReplicas
KubernetesReplicas defines a horizontal pod scaler for Kubernetes.
- kubernetes_object_selector
The Kubernetes object on which horizontal scaling is applied.
- max_replicas
(string, default:
"9223372036854775807"
)The maximum replicas to which the AutoScaler can scale-out.
- min_replicas
(string, default:
"0"
)The minimum replicas to which the AutoScaler can scale-in.
- out_ports
(AutoScalerScalingBackendKubernetesReplicasOuts)
Output ports for Kubernetes Replicas.
AutoScalerScalingBackendKubernetesReplicasOuts
Outputs
AutoScalerScalingParameters
- cooldown_override_percentage
(float64, default:
50
)Cooldown override percentage defines a threshold change in scale-out beyond which previous cooldown is overridden. For example, if the cooldown is 5 minutes and the cooldown override percentage is 10%, then if the scale-increases by 10% or more, the previous cooldown is cancelled. Defaults to 50%.
- max_scale_in_percentage
(float64, default:
1
)The maximum decrease of scale (for example, pods) at one time. Defined as percentage of current scale value. Can never go below one even if percentage computation is less than one. Defaults to 1% of current scale value.
- max_scale_out_percentage
(float64, default:
10
)The maximum increase of scale (for example, pods) at one time. Defined as percentage of current scale value. Can never go below one even if percentage computation is less than one. Defaults to 10% of current scale value.
- scale_in_alerter
Configuration for scale-in Alerter.
- scale_in_cooldown
(string, default:
"120s"
)The amount of time to wait after a scale-in operation for another scale-in operation. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.
- scale_out_alerter
Configuration for scale-out Alerter.
- scale_out_cooldown
(string, default:
"30s"
)The amount of time to wait after a scale-out operation for another scale-out or scale-in operation. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.
BoolVariable
Component that emits a constant Boolean signal which can be changed at runtime through dynamic configuration.
- config_key
(string)
Configuration key for overriding value setting through dynamic configuration.
- constant_output
(bool)
The constant Boolean signal emitted by this component. The value of the constant Boolean signal can be overridden at runtime through dynamic configuration.
- out_ports
Output ports for the BoolVariable component.
BoolVariableOuts
Outputs for the BoolVariable component.
- output
(OutPort)
The value is emitted to the output port.
Circuit
Circuit is graph of inter-connected signal processing components.
See also Circuit overview.
Signals flow between components through ports. As signals traverse the circuit, they get processed, stored within components or get acted upon (for example, load-shed, rate-limit, auto-scale and so on). Circuit is evaluated periodically to respond to changes in signal readings.
Signals are floating point values.
A signal can also have a special Invalid value. It's usually used to communicate that signal does not have a meaningful value at the moment, for example, PromQL emits such a value if it cannot execute a query. Components know when their input signals are invalid and can act accordingly. They can either propagate the invalid signal, by making their output itself invalid (for example, ArithmeticCombinator) or use some different logic, for example, Extrapolator. Refer to a component's docs on how exactly it handles invalid inputs.
- components
Defines a signal processing graph as a list of components.
- evaluation_interval
(string, default:
"10s"
)Evaluation interval (tick) is the time between consecutive runs of the policy circuit. This interval is typically aligned with how often the corrective action (actuation) needs to be taken. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.
Classifier
Set of classification rules sharing a common selector
See also Classifier overview.
selectors:
- agent_group: demoapp
service: service1-demo-app.demoapp.svc.cluster.local
control_point: ingress
label_matcher:
match_labels:
user_tier: gold
match_expressions:
- key: user_type
operator: In
rules:
user:
extractor:
from: request.http.headers.user-agent
telemetry: false
- rego
(Rego)
Rego based classification
Rego is a policy language used to express complex policies in a concise and declarative way. It can be used to define flow classification rules by writing custom queries that extract values from request metadata. For simple cases, such as directly reading a value from header or a field from JSON body, declarative extractors are recommended.
- rules
(map of Rule)
A map of {key, value} pairs mapping from flow label keys to rules that define how to extract and propagate flow labels with that key.
- selectors
([]Selector, required)
Selectors for flows that will be classified by this Classifier.
Component
Computational block that forms the circuit
See also Components overview.
Signals flow into the components from input ports and results are emitted on output ports. Components are wired to each other based on signal names forming an execution graph of the circuit.
Loops are broken by the runtime at the earliest component index that is part of the loop. The looped signals are saved in the tick they're generated and served in the subsequent tick.
See also Policy for a higher-level explanation of circuits.
- alerter
(Alerter)
Alerter reacts to a signal and generates alert to send to alert manager.
- and
(And)
Logical AND.
- arithmetic_combinator
Applies the given operator on input operands (signals) and emits the result.
- auto_scale
AutoScale components are used to scale the service.
- bool_variable
BoolVariable emits a constant Boolean signal which can be changed at runtime through dynamic configuration.
- decider
(Decider)
Decider emits the binary result of comparison operator on two operands.
- differentiator
Differentiator calculates rate of change per tick.
- ema
(EMA)
Exponential Moving Average filter.
- extrapolator
Takes an input signal and emits the extrapolated value; either mirroring the input value or repeating the last known value up to the maximum extrapolation interval.
- first_valid
Picks the first valid input signal and emits it.
- flow_control
FlowControl components are used to regulate requests flow.
- gradient_controller
Gradient controller calculates the ratio between the signal and the setpoint to determine the magnitude of the correction that need to be applied. This controller can be used to build AIMD (Additive Increase, Multiplicative Decrease) or MIMD style response.
- holder
(Holder)
Holds the last valid signal value for the specified duration then waits for next valid value to hold.
- integrator
Accumulates sum of signal every tick.
- inverter
(Inverter)
Logical NOT.
- max
(Max)
Emits the maximum of the input signals.
- min
(Min)
Emits the minimum of the input signals.
- nested_circuit
Nested circuit defines a sub-circuit as a high-level component. It consists of a list of components and a map of input and output ports.
- nested_signal_egress
Nested signal egress is a special type of component that allows to extract a signal from a nested circuit.
- nested_signal_ingress
Nested signal ingress is a special type of component that allows to inject a signal into a nested circuit.
- or
(Or)
Logical OR.
- pulse_generator
Generates 0 and 1 in turns.
- query
(Query)
Query components that are query databases such as Prometheus.
- signal_generator
Generates the specified signal.
- sma
(SMA)
Simple Moving Average filter.
- switcher
(Switcher)
Switcher acts as a switch that emits one of the two signals based on third signal.
- unary_operator
Takes an input signal and emits the square root of the input signal.
- variable
(Variable)
Emits a variable signal which can be changed at runtime through dynamic configuration.
ConstantSignal
Special constant input for ports and Variable component. Can provide either a constant value or special Nan/+-Inf value.
- special_value
(string, one of:
NaN | +Inf | -Inf
)A special value such as NaN, +Inf, -Inf.
- value
(float64)
A constant value.
Decider
Type of Combinator that computes the comparison operation on LHS and RHS signals
The comparison operator can be greater-than, less-than, greater-than-or-equal, less-than-or-equal, equal, or not-equal.
This component also supports time-based response (the output) transitions
between 1.0 or 0.0 signal if the decider condition is true or false for at least
true_for
or false_for
duration. If true_for
and false_for
durations are
zero then the transitions are instantaneous.
- false_for
(string, default:
"0s"
)Duration of time to wait before changing to false state. If the duration is zero, the change will happen instantaneously. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.
- in_ports
Input ports for the Decider component.
- operator
(string, one of:
gt | lt | gte | lte | eq | neq
)Comparison operator that computes operation on LHS and RHS input signals.
- out_ports
Output ports for the Decider component.
- true_for
(string, default:
"0s"
)Duration of time to wait before changing to true state. If the duration is zero, the change will happen instantaneously.``` This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.
DeciderIns
Inputs for the Decider component.
- lhs
(InPort)
Left hand side input signal for the comparison operation.
- rhs
(InPort)
Right hand side input signal for the comparison operation.
DeciderOuts
Outputs for the Decider component.
- output
(OutPort)
Selected signal (1.0 or 0.0).
DecreasingGradient
Decreasing Gradient defines a controller for scaling in based on Gradient Controller.
- in_ports
Input ports for the Gradient.
- parameters
(DecreasingGradientParameters)
Gradient parameters for the controller. Defaults and constraints:
slope
= 1min_gradient
= -Inf (must be less than 1)max_gradient
= 1 (cannot be changed)
DecreasingGradientIns
Inputs for Gradient.
DecreasingGradientParameters
This allows subset of parameters with constrained values compared to a regular gradient controller. For full documentation of these parameters, refer to the GradientControllerParameters.
- min_gradient
(float64, default:
-1.7976931348623157e+308
)- slope
(float64, default:
1
)
Differentiator
Differentiator calculates rate of change per tick.
- in_ports
Input ports for the Differentiator component.
- out_ports
Output ports for the Differentiator component.
- window
(string, default:
"5s"
)The window of time over which differentiator operates. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.
DifferentiatorIns
Inputs for the Differentiator component.
- input
(InPort)
DifferentiatorOuts
Outputs for the Differentiator component.
- output
(OutPort)
EMA
Exponential Moving Average (EMA) is a type of moving average that applies exponentially more weight to recent signal readings
At any time EMA component operates in one of the following states:
- Warm up state: The first
warmup_window
samples are used to compute the initial EMA. If an invalid reading is received during thewarmup_window
, the last good average is emitted and the state gets reset back to beginning of warm up state. - Normal state: The EMA is computed using following formula.
The EMA for a series is calculated recursively as:
The coefficient represents the degree of weighting decrease, a constant smoothing factor between 0 and 1. A higher discounts older observations faster. The is computed using ema_window:
- in_ports
(EMAIns)
Input ports for the EMA component.
- out_ports
(EMAOuts)
Output ports for the EMA component.
- parameters
Parameters for the EMA component.
EMAIns
Inputs for the EMA component.
- input
(InPort)
Input signal to be used for the EMA computation.
- max_envelope
(InPort)
Upper bound of the moving average.
When the signal exceeds
max_envelope
it is multiplied bycorrection_factor_on_max_envelope_violation
once per tick.noteIf the signal deviates from
max_envelope
faster than the correction faster, it might end up exceeding the envelope.- min_envelope
(InPort)
Lower bound of the moving average.
Behavior is similar to
max_envelope
.
EMAOuts
Outputs for the EMA component.
- output
(OutPort)
Exponential moving average of the series of reading as an output signal.
EMAParameters
Parameters for the EMA component.
- correction_factor_on_max_envelope_violation
(float64, minimum:
0
, default:1
)Correction factor to apply on the output value if its in violation of the max envelope.
- correction_factor_on_min_envelope_violation
(float64, default:
1
)Correction factor to apply on the output value if its in violation of the min envelope.
- ema_window
(string, required)
Duration of EMA sampling window. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.
- valid_during_warmup
(bool, default:
false
)Whether the output is valid during the warm-up stage.
- warmup_window
(string, required)
Duration of EMA warming up window.
The initial value of the EMA is the average of signal readings received during the warm up window. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.
EqualsMatchExpression
Label selector expression of the equal form label == value
.
- label
(string, required)
Name of the label to equal match the value.
- value
(string)
Exact value that the label should be equal to.
Extractor
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.
- address
Display an address as a single string -
<ip>:<port>
.- from
(string)
Use an attribute with no conversion
Attribute path is a dot-separated path to attribute.
Should be either:
- one of the fields of Attribute Context, or
- a special
request.http.bearer
pseudo-attribute. For example,request.http.method
orrequest.http.header.user-agent
Note: The same attribute path syntax is shared by other extractor variants, wherever attribute path is needed in their "from" syntax.
Example:
from: request.http.headers.user-agent
- json
Parse JSON, and extract one of the fields.
- jwt
Parse the attribute as JWT and read the payload.
- path_templates
Match HTTP Path to given path templates.
Extrapolator
Extrapolates the input signal by repeating the last valid value during the period in which it is invalid
It does so until maximum_extrapolation_interval
is reached, beyond which it
emits invalid signal unless input signal becomes valid again.
- in_ports
Input ports for the Extrapolator component.
- out_ports
Output ports for the Extrapolator component.
- parameters
Parameters for the Extrapolator component.
ExtrapolatorIns
Inputs for the Extrapolator component.
- input
(InPort)
Input signal for the Extrapolator component.
ExtrapolatorOuts
Outputs for the Extrapolator component.
- output
(OutPort)
Extrapolated signal.
ExtrapolatorParameters
Parameters for the Extrapolator component.
- max_extrapolation_interval
(string, required)
Maximum time interval to repeat the last valid value of input signal. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.
FirstValid
Picks the first valid input signal from the array of input signals and emits it as an output signal
- in_ports
Input ports for the FirstValid component.
- out_ports
Output ports for the FirstValid component.
FirstValidIns
Inputs for the FirstValid component.
- inputs
([]InPort)
Array of input signals.
FirstValidOuts
Outputs for the FirstValid component.
- output
(OutPort)
First valid input signal as an output signal.
FlowControl
Flow Control encompasses components that manage the flow of requests or access to features within a service.
- adaptive_load_scheduler
Adaptive Load Scheduler component is based on additive increase and multiplicative decrease of token rate. It takes a signal and setpoint as inputs and reduces token rate proportionally (or any arbitrary power) based on deviation of the signal from setpoint.
- load_ramp
(LoadRamp)
Load Ramp smoothly regulates the flow of requests over specified steps.
- load_scheduler
Load Scheduler provides service protection by creating a prioritized workload queue in front of the service using Weighted Fair Queuing.
- quota_scheduler
- rate_limiter
Rate Limiter provides service protection by applying rate limits using the token bucket algorithm.
- sampler
(Sampler)
Sampler is a component that regulates the flow of requests to the service by allowing only the specified percentage of requests or sticky sessions.
FlowControlResources
FlowControl Resources
- classifiers
Classifiers are installed in the data-plane and are used to label the requests based on payload content.
The flow labels created by Classifiers can be matched by Flux Meters to create metrics for control purposes.
- flux_meters
(map of FluxMeter)
Flux Meters are installed in the data-plane and form the observability leg of the feedback loop.
Flux Meter created metrics can be consumed as input to the circuit through the PromQL component.
FluxMeter
Flux Meter gathers metrics for the traffic that matches its selector. The histogram created by Flux Meter measures the workload latency by default.
See also Flux Meter overview.
static_buckets:
buckets:
[
5.0,
10.0,
25.0,
50.0,
100.0,
250.0,
500.0,
1000.0,
2500.0,
5000.0,
10000.0,
]
selectors:
- agent_group: demoapp
service: service1-demo-app.demoapp.svc.cluster.local
control_point: ingress
attribute_key: response_duration_ms
- attribute_key
(string, default:
"workload_duration_ms"
)Key of the attribute in access log or span from which the metric for this flux meter is read.
infoFor list of available attributes in Envoy access logs, refer Envoy Filter
- exponential_buckets
- exponential_buckets_range
- linear_buckets
- selectors
([]Selector, required)
Selectors for flows that will be metered by this Flux Meter.
- static_buckets
FluxMeterExponentialBuckets
ExponentialBuckets creates count
number of buckets where the lowest bucket has
an upper bound of start
and each following bucket's upper bound is factor
times the previous bucket's upper bound. The final +inf bucket is not counted.
- count
(int32, minimum:
0
)Number of buckets.
- factor
(float64)
Factor to be multiplied to the previous bucket's upper bound to calculate the following bucket's upper bound.
- start
(float64)
Upper bound of the lowest bucket.
FluxMeterExponentialBucketsRange
ExponentialBucketsRange creates count
number of buckets where the lowest
bucket is min
and the highest bucket is max
. The final +inf bucket is not
counted.
- count
(int32, minimum:
0
)Number of buckets.
- max
(float64)
Highest bucket.
- min
(float64)
Lowest bucket.
FluxMeterLinearBuckets
LinearBuckets creates count
number of buckets, each width
wide, where the
lowest bucket has an upper bound of start
. The final +inf bucket is not
counted.
- count
(int32, minimum:
0
)Number of buckets.
- start
(float64)
Upper bound of the lowest bucket.
- width
(float64)
Width of each bucket.
FluxMeterStaticBuckets
StaticBuckets holds the static value of the buckets where latency histogram will be stored.
- buckets
([]float64, default:
[5,10,25,50,100,250,500,1000,2500,5000,10000]
)The buckets in which latency histogram will be stored.
GradientController
Gradient controller is a type of controller which tries to adjust the control variable proportionally to the relative difference between setpoint and actual value of the signal
The gradient
describes a corrective factor that should be applied to the
control variable to get the signal closer to the setpoint. It's computed as
follows:
gradient
is then clamped to [min_gradient, max_gradient]
range.
The output of gradient controller is computed as follows:
Note the additional optimize
signal, that can be used to "nudge" the
controller into desired idle state.
The output can be optionally clamped to desired range using max
and min
input.
- in_ports
Input ports of the Gradient Controller.
- manual_mode
(bool)
In manual mode, the controller does not adjust the control variable. It emits the same output as the control variable input. This setting can be adjusted at runtime through dynamic configuration without restarting the policy.
- manual_mode_config_key
(string)
Configuration key for overriding
manual_mode
setting through dynamic configuration.- out_ports
Output ports of the Gradient Controller.
- parameters
(GradientControllerParameters)
Gradient Parameters.
GradientControllerIns
Inputs for the Gradient Controller component.
- control_variable
(InPort)
Actual current value of the control variable.
This signal is multiplied by the gradient to produce the output.
- max
(InPort)
Maximum value to limit the output signal.
- min
(InPort)
Minimum value to limit the output signal.
- setpoint
(InPort)
Setpoint to be used for the gradient computation.
- signal
(InPort)
Signal to be used for the gradient computation.
GradientControllerOuts
Outputs for the Gradient Controller component.
- output
(OutPort)
Computed desired value of the control variable.
GradientControllerParameters
Gradient Parameters.
- max_gradient
(float64, default:
1.7976931348623157e+308
)Maximum gradient which clamps the computed gradient value to the range,
[min_gradient, max_gradient]
.- min_gradient
(float64, default:
-1.7976931348623157e+308
)Minimum gradient which clamps the computed gradient value to the range,
[min_gradient, max_gradient]
.- slope
(float64, required)
Slope controls the aggressiveness and direction of the Gradient Controller.
Slope is used as exponent on the signal to setpoint ratio in computation of the gradient (see the main description for exact equation). This parameter decides how aggressive the controller responds to the deviation of signal from the setpoint. for example:
- : when signal is too high, increase control variable,
- : when signal is too high, decrease control variable,
- : when signal is too high, decrease control variable gradually.
The sign of slope depends on correlation between the signal and control variable:
- Use if there is a positive correlation between the signal and the control variable (for example, Per-pod CPU usage and total concurrency).
- Use if there is a negative correlation between the signal and the control variable (for example, Per-pod CPU usage and number of pods).
noteYou need to set negative slope for a positive correlation, as you're describing the action which controller should make when the signal increases.
The magnitude of slope describes how aggressively should the controller react to a deviation of signal. With , the controller will aim to bring the signal to the setpoint in one tick (assuming linear correlation with signal and setpoint). Smaller magnitudes of slope will make the controller adjust the control variable gradually.
Setting (for example, ) is recommended. If you experience overshooting, consider lowering the magnitude even more. Values of aren't recommended.
noteRemember that the gradient and output signal can be (optionally) clamped, so the slope might not fully describe aggressiveness of the controller.
Holder
Holds the last valid signal value for the specified duration then waits for next
valid value to hold. If it is holding a value that means it ignores both valid
and invalid new signals until the hold_for
duration is finished.
- hold_for
(string, default:
"5s"
)Holding the last valid signal value for the
hold_for
duration. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.- in_ports
Input ports for the Holder component.
- out_ports
Output ports for the Holder component.
HolderIns
Inputs for the Holder component.
- input
(InPort)
The input signal.
- reset
(InPort)
Resets the holder output to the current input signal when reset signal is valid and non-zero.
HolderOuts
Outputs for the Holder component.
- output
(OutPort)
The output signal.
InPort
Components receive input from other components through InPorts
- constant_signal
Constant value to be used for this InPort instead of a signal.
- signal_name
(string)
Name of the incoming Signal on the InPort.
IncreasingGradient
Increasing Gradient defines a controller for scaling out based on Gradient Controller.
- in_ports
Input ports for the Gradient.
- parameters
(IncreasingGradientParameters)
Gradient parameters for the controller. Defaults and constraints:
slope
= 1min_gradient
= 1 (cannot be changed)max_gradient
= +Inf (must be greater than 1)
IncreasingGradientIns
Inputs for Gradient.
IncreasingGradientParameters
This allows subset of parameters with constrained values compared to a regular gradient controller. For full documentation of these parameters, refer to the GradientControllerParameters.
- max_gradient
(float64, default:
1.7976931348623157e+308
)- slope
(float64, default:
1
)
InfraMeter
InfraMeter is a resource that sets up OpenTelemetry pipelines. It defines
receivers, processors, and a single metrics pipeline which will be exported to
the configured Prometheus instance. Environment variables can be used in the
configuration using format ${ENV_VAR_NAME}
.
- agent_group
(string, default:
"default"
)AgentGroup is the agent group to sync this InfraMeter with.
- per_agent_group
(bool, default:
false
)PerAgentGroup marks the pipeline to be instantiated only once per agent group. This is helpful for receivers that scrape for example, some cluster-wide metrics. When not set, pipeline will be instantiated on every Agent.
- pipeline
Pipeline is an OTel metrics pipeline definition, which only uses receivers and processors defined above. Exporter would be added automatically.
If there are no processors defined or only one processor is defined, the pipeline definition can be omitted. In such cases, the pipeline will automatically use all given receivers and the defined processor (if any). However, if there are more than one processor, the pipeline must be defined explicitly.
- processors
(map of any )
Processors define processors to be used in custom metrics pipelines. This should be in OTel format.
- receivers
(map of any )
Receivers define receivers to be used in custom metrics pipelines. This should be in OTel format.
InfraMeterMetricsPipeline
MetricsPipelineConfig defines a custom metrics pipeline.
- processors
([]string)
- receivers
([]string)
Integrator
Accumulates sum of signal every tick.
- in_ports
Input ports for the Integrator component.
- initial_value
(float64, default:
0
)Initial value of the integrator.
- out_ports
Output ports for the Integrator component.
IntegratorIns
Inputs for the Integrator component.
- input
(InPort)
The input signal.
- max
(InPort)
The maximum output.
- min
(InPort)
The minimum output.
- reset
(InPort)
Resets the integrator output to zero when reset signal is valid and non-zero. Reset also resets the max and min constraints.
IntegratorOuts
Outputs for the Integrator component.
- output
(OutPort)
Inverter
Logical NOT.
See And component on how signals are mapped onto Boolean values.
- in_ports
Input ports for the Inverter component.
- out_ports
Output ports for the Inverter component.
InverterIns
Inputs for the Inverter component.
- input
(InPort)
Signal to be negated.
InverterOuts
Output ports for the Inverter component.
- output
(OutPort)
Logical negation of the input signal.
Will always be 0 (false), 1 (true) or invalid (unknown).
JSONExtractor
Parse JSON, and extract one of the fields
Example:
from: request.http.body
pointer: /user/name
- from
(string, required)
Attribute path pointing to some strings - for example,
request.http.body
.- pointer
(string)
JSON pointer represents a parsed JSON pointer which allows to select a specified field from the payload.
Note: Uses JSON pointer syntax, for example,
/foo/bar
. If the pointer points into an object, it'd be converted to a string.
JWTExtractor
Parse the attribute as JWT and read the payload
Specify a field to be extracted from payload using json_pointer
.
Note: The signature is not verified against the secret (assuming there's some other part of the system that handles such verification).
Example:
from: request.http.bearer
json_pointer: /user/email
- from
(string, required)
JWT (JSON Web Token) can be extracted from any input attribute, but most likely you'd want to use
request.http.bearer
.- json_pointer
(string)
JSON pointer allowing to select a specified field from the payload.
Note: Uses JSON pointer syntax, for example,
/foo/bar
. If the pointer points into an object, it'd be converted to a string.
K8sLabelMatcherRequirement
Label selector requirement which is a selector that contains values, a key, and an operator that relates the key and values.
- key
(string, required)
Label key that the selector applies to.
- operator
(string, one of:
In | NotIn | Exists | DoesNotExists
)Logical operator which represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist.
- values
([]string)
An array of string values that relates to the key by an operator. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty.
KubernetesObjectSelector
Describes which pods a control or observability component should apply to.
- agent_group
(string, default:
"default"
)Which agent-group this selector applies to.
- api_version
(string, required)
API version of Kubernetes resource
- kind
(string, required)
Kubernetes resource type.
- name
(string, required)
Kubernetes resource name.
- namespace
(string, required)
Kubernetes namespace that the resource belongs to.
LabelMatcher
Allows to define rules whether a map of labels should be considered a match or not
It provides three ways to define requirements:
- match labels
- match expressions
- arbitrary expression
If multiple requirements are set, they're all combined using the logical AND operator. An empty label matcher always matches.
- expression
An arbitrary expression to be evaluated on the labels.
- match_expressions
([]K8sLabelMatcherRequirement)
List of Kubernetes-style label matcher requirements.
Note: The requirements are combined using the logical AND operator.
- match_labels
(map of string)
A map of {key,value} pairs representing labels to be matched. A single {key,value} in the
match_labels
requires that the labelkey
is present and equal tovalue
.Note: The requirements are combined using the logical AND operator.
LoadRamp
The Load Ramp produces a smooth and continuous traffic load that changes progressively over time, based on the specified steps.
Each step is defined by two parameters:
- The
target_accept_percentage
. - The
duration
for the signal to change from the previous step'starget_accept_percentage
to the current step'starget_accept_percentage
.
The percentage of requests accepted starts at the target_accept_percentage
defined in the first step and gradually ramps up or down linearly from the
previous step's target_accept_percentage
to the next
target_accept_percentage
, over the duration
specified for each step.
- in_ports
- out_ports
- parameters
- pass_through_label_values
([]string)
Specify certain label values to be always accepted by the Sampler regardless of accept percentage.
- pass_through_label_values_config_key
(string)
Configuration key for setting pass through label values through dynamic configuration.
LoadRampIns
Inputs for the Load Ramp component.
- backward
(InPort)
Whether to progress the Load Ramp towards the previous step.
- forward
(InPort)
Whether to progress the Load Ramp towards the next step.
- reset
(InPort)
Whether to reset the Load Ramp to the first step.
LoadRampOuts
Outputs for the Load Ramp component.
- accept_percentage
(OutPort)
The percentage of flows being accepted by the Load Ramp.
- at_end
(OutPort)
A Boolean signal indicating whether the Load Ramp is at the end of signal generation.
- at_start
(OutPort)
A Boolean signal indicating whether the Load Ramp is at the start of signal generation.
LoadRampParameters
Parameters for the Load Ramp component.
- sampler
Parameters for the Sampler.
- steps
([]LoadRampParametersStep, required)
LoadRampParametersStep
- duration
(string, required)
Duration for which the step is active. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.
- target_accept_percentage
(float64, minimum:
0
, maximum:100
)The value of the step.
LoadScheduler
Load Scheduler creates a queue for flows in front of a service to provide active service protection
See also Load Scheduler overview.
To make scheduling decisions the Flows are mapped into Workloads by providing match rules. A workload determines the priority and cost of admitting each Flow that belongs to it. Scheduling of Flows is based on Weighted Fair Queuing principles. Load Scheduler measures and controls the incoming tokens per second, which can translate to (avg. latency * in-flight requests) (Little's Law) in concurrency limiting use-case.
The signal at port load_multiplier
determines the fraction of incoming tokens
that get admitted.
- dry_run
(bool)
Decides whether to run the load scheduler in dry-run mode. In dry run mode the scheduler acts as pass through to all flow and does not queue flows. It is useful for observing the behavior of load scheduler without disrupting any real traffic.
- dry_run_config_key
(string)
Configuration key for setting dry run mode through dynamic configuration.
- in_ports
Input ports for the LoadScheduler component.
- out_ports
Output ports for the LoadScheduler component.
- parameters
LoadSchedulerIns
Input for the LoadScheduler component.
- load_multiplier
(InPort)
Load multiplier is proportion of incoming token rate that needs to be accepted.
LoadSchedulerOuts
Output for the LoadScheduler component.
- observed_load_multiplier
(OutPort)
Observed load multiplier is the proportion of incoming token rate that is being accepted.
LoadSchedulerParameters
Parameters for Load Scheduler component
- scheduler
Configuration of Weighted Fair Queuing-based workload scheduler.
Contains configuration of per-agent scheduler
- selectors
([]Selector, required)
Selectors for the component.
- workload_latency_based_tokens
(bool, default:
true
)Automatically estimate the size flows within each workload, based on historical latency. Each workload's
tokens
will be set to average latency of flows in that workload during the last few seconds (exact duration of this average can change). This setting is useful in concurrency limiting use-case, where the concurrency is calculated as `(avg. latency \* in-flight flows)
.The value of tokens estimated takes a lower precedence than the value of
tokens
specified in the workload definition andtokens
explicitly specified in the flow labels.
MatchExpression
MatchExpression has multiple variants, exactly one should be set.
Example:
all:
of:
- label_exists: foo
- label_equals:
label: app
value: frobnicator
- all
The expression is true when all sub expressions are true.
- any
The expression is true when any sub expression is true.
- label_equals
The expression is true when label value equals given value.
- label_exists
(string)
The expression is true when label with given name exists.
- label_matches
The expression is true when label matches given regular expression.
- not
The expression negates the result of sub expression.
MatchExpressionList
List of MatchExpressions that is used for all or any matching
for example, {any: {of: [expr1, expr2]}}
.
- of
List of sub expressions of the match expression.
MatchesMatchExpression
Label selector expression of the form label matches regex
.
- label
(string, required)
Name of the label to match the regular expression.
- regex
(string, required)
Regular expression that should match the label value. It uses Go's regular expression syntax.
Max
Takes a list of input signals and emits the signal with the maximum value
Max: output = max([]inputs).
- in_ports
(MaxIns)
Input ports for the Max component.
- out_ports
(MaxOuts)
Output ports for the Max component.
MaxIns
Inputs for the Max component.
- inputs
([]InPort)
Array of input signals.
MaxOuts
Output for the Max component.
- output
(OutPort)
Signal with maximum value as an output signal.
Min
Takes an array of input signals and emits the signal with the minimum value Min: output = min([]inputs).
- in_ports
(MinIns)
Input ports for the Min component.
- out_ports
(MinOuts)
Output ports for the Min component.
MinIns
Inputs for the Min component.
- inputs
([]InPort)
Array of input signals.
MinOuts
Output ports for the Min component.
- output
(OutPort)
Signal with minimum value as an output signal.
NestedCircuit
Nested circuit defines a sub-circuit as a high-level component. It consists of a list of components and a map of input and output ports.
- components
List of components in the nested circuit.
- in_ports_map
(map of InPort)
Maps input port names to input ports.
- name
(string)
Name of the nested circuit component. This name is displayed by graph visualization tools.
- out_ports_map
(map of OutPort)
Maps output port names to output ports.
- short_description
(string)
Short description of the nested circuit component. This description is displayed by graph visualization tools.
NestedSignalEgress
Nested signal egress is a special type of component that allows to extract a signal from a nested circuit.
- in_ports
Input ports for the NestedSignalEgress component.
- port_name
(string)
Name of the port.
NestedSignalEgressIns
Inputs for the NestedSignalEgress component.
- signal
(InPort)
Egress signal.
NestedSignalIngress
Nested signal ingress is a special type of component that allows to inject a signal into a nested circuit.
- out_ports
Output ports for the NestedSignalIngress component.
- port_name
(string)
Name of the port.
NestedSignalIngressOuts
Outputs for the NestedSignalIngress component.
- signal
(OutPort)
Ingress signal.
Or
Logical OR.
See And component on how signals are mapped onto Boolean values.
OrIns
Inputs for the Or component.
- inputs
([]InPort)
Array of input signals.
OrOuts
Output ports for the Or component.
- output
(OutPort)
Result of logical OR of all the input signals.
Will always be 0 (false), 1 (true) or invalid (unknown).
OutPort
Components produce output for other components through OutPorts
- signal_name
(string)
Name of the outgoing Signal on the OutPort.
PathTemplateMatcher
Matches HTTP Path to given path templates
HTTP path will be matched against given path templates. If a match occurs, the value associated with the path template will be treated as a result. In case of multiple path templates matching, the most specific one will be chosen.
- template_values
(map of string)
Template value keys are OpenAPI-inspired path templates.
- Static path segment
/foo
matches a path segment exactly /{param}
matches arbitrary path segment. (The parameter name is ignored and can be omitted ({}
))- The parameter must cover whole segment.
- Additionally, path template can end with
/*
wildcard to match arbitrary number of trailing segments (0 or more). - Multiple consecutive
/
are ignored, as well as trailing/
. - Parametrized path segments must come after static segments.
*
, if present, must come last.- Most specific template "wins" (
/foo
over/{}
and/{}
over/*
).
See also https://swagger.io/specification/#path-templating-matching
Example:
/register: register
"/user/{userId}": user
/static/*: other- Static path segment
PeriodicDecrease
PeriodicDecrease defines a controller for scaling in based on a periodic timer.
- period
(string, required)
The period of the timer. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.
- scale_in_percentage
(float64, minimum:
0
, maximum:100
, required)The percentage of scale to reduce.
PodScaler
Component for scaling pods based on a signal.
- dry_run
(bool)
Dry run mode ensures that no scaling is invoked by this pod scaler. This is useful for observing the behavior of pod scaler without disrupting any real deployment. This parameter sets the default value of dry run setting which can be overridden at runtime using dynamic configuration.
- dry_run_config_key
(string)
Configuration key for overriding dry run setting through dynamic configuration.
- in_ports
Input ports for the PodScaler component.
- kubernetes_object_selector
The Kubernetes object to which this pod scaler applies.
- out_ports
Output ports for the PodScaler component.
PodScalerIns
Inputs for the PodScaler component.
- replicas
(InPort)
The number of replicas to configure for the Kubernetes resource
PodScalerOuts
Outputs for the PodScaler component.
- actual_replicas
(OutPort)
The number of replicas that are currently running.
- configured_replicas
(OutPort)
The number of replicas that are desired.
Policy
Policy expresses observability-driven control logic.
See also Policy overview.
Policy specification contains a circuit that defines the controller logic and resources that need to be setup.
- circuit
(Circuit)
Defines the control-loop logic of the policy.
- resources
Resources (such as Flux Meters, Classifiers) to setup.
PromQL
Component that runs a Prometheus query periodically and returns the result as an output signal
- evaluation_interval
(string, default:
"10s"
)Describes the interval between successive evaluations of the Prometheus query. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.
- out_ports
Output ports for the PromQL component.
- query_string
(string)
Describes the PromQL query to be run.
noteThe query must return a single value either as a scalar or as a vector with a single element.
Usage with Flux MeterFlux Meter metrics can be queried using PromQL. Flux Meter defines histogram type of metrics in Prometheus. Therefore, one can refer to
flux_meter_sum
,flux_meter_count
andflux_meter_bucket
. The particular Flux Meter can be identified with theflux_meter_name
label. There are additional labels available on a Flux Meter such asvalid
,flow_status
,http_status_code
anddecision_type
.Usage with OpenTelemetry MetricsAperture supports OpenTelemetry metrics. See reference for more details.
PromQLOuts
Output for the PromQL component.
- output
(OutPort)
The result of the Prometheus query as an output signal.
PulseGenerator
Generates 0 and 1 in turns.
- false_for
(string, default:
"5s"
)Emitting 0 for the
false_for
duration. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.- out_ports
Output ports for the PulseGenerator component.
- true_for
(string, default:
"5s"
)Emitting 1 for the
true_for
duration. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.
PulseGeneratorOuts
Outputs for the PulseGenerator component.
- output
(OutPort)
Query
Query components that are query databases such as Prometheus.
- promql
(PromQL)
Periodically runs a Prometheus query in the background and emits the result.
QuotaScheduler
Schedules the traffic based on token-bucket based quotas.
- in_ports
- rate_limiter
- scheduler
- selectors
([]Selector, required)
RateLimiter
Limits the traffic on a control point to specified rate
See also Rate Limiter overview.
RateLimiting is done on per-label-value (label_key
) basis and it uses the
Token Bucket Algorithm.
- in_ports
Input ports for the RateLimiter component
- parameters
Parameters for the RateLimiter component
- selectors
([]Selector, required)
Selectors for the component.
RateLimiterIns
Inputs for the RateLimiter component
- bucket_capacity
(InPort)
Capacity of the bucket.
- fill_amount
(InPort)
Number of tokens to fill within an
interval
.- pass_through
(InPort)
PassThrough port determines whether all requests
RateLimiterParameters
- continuous_fill
(bool, default:
true
)Continuous fill determines whether the token bucket should be filled continuously or only on discrete intervals.
- interval
(string, required)
Interval defines the time interval in which the token bucket will fill tokens specified by
fill_amount
signal. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.- label_key
(string)
Specifies which label the rate limiter should be keyed by.
Rate limiting is done independently for each value of the label with given key. For example, to give each user a separate limit, assuming you have a user flow label set up, set
label_key: "user"
. If no label key is specified, then all requests matching the selectors will be rate limited based on the global bucket.- lazy_sync
(RateLimiterParametersLazySync)
Configuration of lazy-syncing behavior of rate limiter
- max_idle_time
(string, default:
"7200s"
)Max idle time before token bucket state for a label is removed. If set to 0, the state is never removed. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.
- tokens_label_key
(string, default:
"tokens"
)Flow label key that will be used to override the number of tokens for this request. This is an optional parameter and takes highest precedence when assigning tokens to a request. The label value must be a valid uint64 number.
RateLimiterParametersLazySync
- enabled
(bool, default:
false
)Enables lazy sync
- num_sync
(int64, minimum:
0
, default:4
)Number of times to lazy sync within the
interval
.
Rego
Rego define a set of labels that are extracted after evaluating a Rego module.
You can use the live-preview feature to first preview the input to the classifier before writing the labeling logic.
Example of Rego module which also disables telemetry visibility of label:
rego:
labels:
user:
telemetry: false
module: |
package user_from_cookie
cookies := split(input.attributes.request.http.headers.cookie, "; ")
user := user {
cookie := cookies[_]
startswith(cookie, "session=")
session := substring(cookie, count("session="), -1)
parts := split(session, ".")
object := json.unmarshal(base64url.decode(parts[0]))
user := object.user
}
- labels
(map of RegoLabelProperties, required)
A map of {key, value} pairs mapping from flow label keys to queries that define how to extract and propagate flow labels with that key. The name of the label maps to a variable in the Rego module. It maps to
data.<package>.<label>
variable.- module
(string, required)
Source code of the Rego module.
noteMust include a "package" declaration.
RegoLabelProperties
- telemetry
(bool, default:
true
)Decides if the created flow label should be available as an attribute in OLAP telemetry and propagated in baggage
noteThe flow label is always accessible in Aperture Policies regardless of this setting.
cautionWhen using FluxNinja ARC extension, telemetry enabled labels are sent to FluxNinja ARC for observability. Telemetry should be disabled for sensitive labels.
Resources
Resources that need to be setup for the policy to function
See also Resources overview.
- flow_control
FlowControlResources are resources that are provided by flow control integration.
- infra_meters
(map of InfraMeter)
Infra Meters configure custom metrics OpenTelemetry collector pipelines, which will receive and process telemetry at the agents and send metrics to the configured Prometheus. Key in this map refers to OTel pipeline name. Prefixing pipeline name with
metrics/
is optional, as all the components and pipeline names would be normalized.Example:
infra_meters:
rabbitmq:
agent_group: default
per_agent_group: true
processors:
batch:
send_batch_size: 10
timeout: 10s
receivers:
rabbitmq:
collection_interval: 10s
endpoint: http://<rabbitmq-svc-fqdn>:15672
password: secretpassword
username: admincautionValidate the OTel configuration before applying it to the production cluster. Incorrect configuration will get rejected at the agents and might cause shutdown of the agent(s).
- telemetry_collectors
TelemetryCollector configures OpenTelemetry collector integration. Deprecated: v2.8.0. Use
infra_meters
instead.
Rule
Rule describes a single classification Rule
Example of a JSON extractor:
extractor:
json:
from: request.http.body
pointer: /user/name
- extractor
High-level declarative extractor.
- telemetry
(bool, default:
true
)Decides if the created flow label should be available as an attribute in OLAP telemetry and propagated in baggage
noteThe flow label is always accessible in Aperture Policies regardless of this setting.
cautionWhen using FluxNinja ARC extension, telemetry enabled labels are sent to FluxNinja ARC for observability. Telemetry should be disabled for sensitive labels.
SMA
Simple Moving Average (SMA) is a type of moving average that computes the average of a fixed number of signal readings.
- in_ports
(SMAIns)
Input ports for the SMA component.
- out_ports
(SMAOuts)
Output ports for the SMA component.
- parameters
Parameters for the SMA component.
SMAIns
- input
(InPort)
Signal to be used for the moving average computation.
SMAOuts
- output
(OutPort)
Computed moving average.
SMAParameters
- sma_window
(string, required)
Window of time over which the moving average is computed. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.
- valid_during_warmup
(bool, default:
false
)Whether the output is valid during the warm-up stage.
Sampler
Sampler is a component that regulates the load at a Control Point by allowing only a specified percentage of flows at random or by sticky sessions.
See also Sampler overview.
- in_ports
Input ports for the Sampler.
- parameters
Parameters for the Sampler.
- pass_through_label_values
([]string)
Specify certain label values to be always accepted by this Sampler regardless of accept percentage.
- pass_through_label_values_config_key
(string)
Configuration key for setting pass through label values through dynamic configuration.
SamplerIns
- accept_percentage
(InPort)
The percentage of requests to accept.
SamplerParameters
- label_key
(string)
The flow label key for identifying sessions.
- When label key is specified, Sampler acts as a sticky filter. The series of
flows with the same value of label key get the same decision provided that the
accept_percentage
is same or higher. - When label key is not specified, Sampler acts as a stateless filter. Percentage of flows are selected randomly for rejection.
- When label key is specified, Sampler acts as a sticky filter. The series of
flows with the same value of label key get the same decision provided that the
- selectors
([]Selector, required)
Selectors for the component.
ScaleInController
- alerter
Configuration for embedded Alerter.
- controller
Controller
ScaleInControllerController
- gradient
- periodic
ScaleOutController
- alerter
Configuration for embedded Alerter.
- controller
(ScaleOutControllerController)
Controller
ScaleOutControllerController
- gradient
Scheduler
Weighted Fair Queuing-based workload scheduler
Each Agent instantiates an independent copy of the scheduler, but output signals for accepted and incoming token rate are aggregated across all agents.
- decision_deadline_margin
(string, default:
"0.01s"
)Decision deadline margin is the amount of time that the scheduler will subtract from the request deadline to determine the deadline for the decision. This is to ensure that the scheduler has enough time to make a decision before the request deadline happens, accounting for processing delays. The request deadline is based on the gRPC deadline or the
grpc-timeout
HTTP header.Fail-open logic is use for flow control APIs, so if the gRPC deadline reaches, the flow will end up being unconditionally allowed while it is still waiting on the scheduler. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.
- default_workload_parameters
Parameters to be used if none of workloads specified in
workloads
match.- tokens_label_key
(string, default:
"tokens"
)- Key for a flow label that can be used to override the default number of tokens for this flow.
- The value associated with this key must be a valid uint64 number.
- If this parameter is not provided, the number of tokens for the flow will be determined by the matched workload's token count.
- workloads
List of workloads to be used in scheduler.
Categorizing flows into workloads allows for load throttling to be "intelligent" instead of queueing flows in an arbitrary order. There are two aspects of this "intelligence":
- Scheduler can more precisely calculate concurrency if it understands that flows belonging to different classes have different weights (for example, insert queries compared to select queries).
- Setting different priorities to different workloads lets the scheduler avoid dropping important traffic during overload.
Each workload in this list specifies also a matcher that is used to determine which flow will be categorized into which workload. In case of multiple matching workloads, the first matching one will be used. If none of workloads match,
default_workload
will be used.info
SchedulerWorkload
Workload defines a class of flows that preferably have similar properties such as response latency and desired priority.
- label_matcher
Label Matcher to select a Workload based on flow labels.
- name
(string)
Name of the workload.
- parameters
Parameters associated with flows matching the label matcher.
SchedulerWorkloadParameters
Parameters such as priority and tokens that are applicable to flows within a workload.
- priority
(string, default:
"1"
)Describes priority level of the flows within the workload. Priority level is unbounded and can be any positive integer. Higher numbers means higher priority level. The following formula is used to determine the position of a flow in the queue based on virtual finish time:
- queue_timeout
(string)
Timeout for the flow in the workload. If timeout is provided on the Check call as well, we pick the minimum of the two. If this override is not provided, the timeout provided in the check call is used. 0 timeout value implies that the request will not wait in the queue and will be accepted/dropped immediately. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.
- tokens
(string)
Tokens determines the cost of admitting a single flow in the workload, which is typically defined as milliseconds of flow latency (time to response or duration of a feature) or simply equal to 1 if the resource being accessed is constrained by the number of flows (3rd party rate limiters). This override is applicable only if tokens for the flow aren't specified in the flow labels.
Selector
Selects flows based on control point, flow labels, agent group and the service that the flow control component will operate on.
See also Selector overview.
Example:
control_point: ingress
label_matcher:
match_labels:
user_tier: gold
match_expressions:
- key: query
operator: In
values:
- insert
- delete
expression:
label_matches:
- label: user_agent
regex: ^(?!.*Chrome).*Safari
- agent_group
(string, default:
"default"
)Agent Group this selector applies to.
infoAgent Groups are used to scope policies to a subset of agents connected to the same controller. The agents within an agent group receive exact same policy configuration and form a peer to peer cluster to constantly share state.
- control_point
(string, required)
Control Point identifies location within services where policies can act on flows. For an SDK based insertion, a Control Point can represent a particular feature or execution block within a service. In case of service mesh or middleware insertion, a Control Point can identify ingress or egress calls or distinct listeners or filter chains.
- label_matcher
Label Matcher can be used to match flows based on flow labels.
- service
(string, default:
"any"
)The Fully Qualified Domain Name of the service to select.
In Kubernetes, this is the FQDN of the Service object.
infoany
matches all services.infoAn entity (for example, Kubernetes pod) might belong to multiple services.
SignalGenerator
The Signal Generator component generates a smooth and continuous signal by following a sequence of specified steps. Each step has two parameters:
target_output
: The desired output value at the end of the step.duration
: The time it takes for the signal to change linearly from the previous step'starget_output
to the current step'starget_output
.
The output signal starts at the target_output
of the first step and changes
linearly between steps based on their duration
. The Signal Generator can be
controlled to move forwards, backwards, or reset to the beginning based on input
signals.
- in_ports
- out_ports
- parameters
Parameters for the Signal Generator component.
SignalGeneratorIns
Inputs for the Signal Generator component.
- backward
(InPort)
Whether to progress the Signal Generator towards the previous step.
- forward
(InPort)
Whether to progress the Signal Generator towards the next step.
- reset
(InPort)
Whether to reset the Signal Generator to the first step.
SignalGeneratorOuts
Outputs for the Signal Generator component.
- at_end
(OutPort)
A Boolean signal indicating whether the Signal Generator is at the end of signal generation.
- at_start
(OutPort)
A Boolean signal indicating whether the Signal Generator is at the start of signal generation.
- output
(OutPort)
The generated signal.
SignalGeneratorParameters
Parameters for the Signal Generator component.
- steps
([]SignalGeneratorParametersStep, required)
SignalGeneratorParametersStep
- duration
(string, required)
Duration for which the step is active. This field employs the Duration JSON representation from Protocol Buffers. The format accommodates fractional seconds up to nine digits after the decimal point, offering nanosecond precision. Every duration value must be suffixed with an "s" to indicate 'seconds.' For example, a value of "10s" would signify a duration of 10 seconds.
- target_output
The value of the step.
Switcher
Type of Combinator that switches between on_signal
and off_signal
signals
based on switch input
on_signal
will be returned if switch input is valid and not equal to 0.0 ,
otherwise off_signal
will be returned.
- in_ports
Input ports for the Switcher component.
- out_ports
Output ports for the Switcher component.
SwitcherIns
Inputs for the Switcher component.
- off_signal
(InPort)
Output signal when switch is invalid or 0.0.
- on_signal
(InPort)
Output signal when switch is valid and not 0.0.
- switch
(InPort)
Decides whether to return
on_signal
oroff_signal
.
SwitcherOuts
Outputs for the Switcher component.
- output
(OutPort)
Selected signal (
on_signal
oroff_signal
).
TelemetryCollector
TelemetryCollector defines the telemetry configuration to be synced with the
agents. Deprecated: v2.8.0. Use InfraMeter
instead. It consists of two parts:
- Agent Group: Agent group to sync telemetry configuration with
- Infra Meters: OTel compatible metrics pipelines
- agent_group
(string, default:
"default"
)- infra_meters
(map of InfraMeter)
Infra Meters configure custom metrics OpenTelemetry collector pipelines, which will receive and process telemetry at the agents and send metrics to the configured Prometheus. Key in this map refers to OTel pipeline name. Prefixing pipeline name with
metrics/
is optional, as all the components and pipeline names would be normalized.Example:
telemetry_collectors:
- agent_group: default
infra_meters:
rabbitmq:
processors:
batch:
send_batch_size: 10
timeout: 10s
receivers:
rabbitmq:
collection_interval: 10s
endpoint: http://<rabbitmq-svc-fqdn>:15672
password: secretpassword
username: admin
per_agent_group: truecautionValidate the OTel configuration before applying it to the production cluster. Incorrect configuration will get rejected at the agents and might cause shutdown of the agent(s).
UnaryOperator
Takes an input signal and emits the output after applying the specified unary operator
- in_ports
Input ports for the UnaryOperator component.
- operator
(string, one of:
abs | acos | acosh | asin | asinh | atan | atanh | cbrt | ceil | cos | cosh | erf | erfc | erfcinv | erfinv | exp | exp2 | expm1 | floor | gamma | j0 | j1 | lgamma | log | log10 | log1p | log2 | round | roundtoeven | sin | sinh | sqrt | tan | tanh | trunc | y0 | y1
)Unary Operator to apply.
The unary operator can be one of the following:
abs
: Absolute value with the sign removed.acos
:arccosine
, in radians.acosh
: Inverse hyperbolic cosine.asin
:arcsine
, in radians.asinh
: Inverse hyperbolic sine.atan
:arctangent
, in radians.atanh
: Inverse hyperbolic tangent.cbrt
: Cube root.ceil
: Least integer value greater than or equal to input signal.cos
:cosine
, in radians.cosh
: Hyperbolic cosine.erf
: Error function.erfc
: Complementary error function.erfcinv
: Inverse complementary error function.erfinv
: Inverse error function.exp
: The base-e exponential of input signal.exp2
: The base-2 exponential of input signal.expm1
: The base-e exponential of input signal minus 1.floor
: Greatest integer value less than or equal to input signal.gamma
: Gamma function.j0
: Bessel function of the first kind of order 0.j1
: Bessel function of the first kind of order 1.lgamma
: Natural logarithm of the absolute value of the gamma function.log
: Natural logarithm of input signal.log10
: Base-10 logarithm of input signal.log1p
: Natural logarithm of input signal plus 1.log2
: Base-2 logarithm of input signal.round
: Round to nearest integer.roundtoeven
: Round to nearest integer, with ties going to the nearest even integer.sin
:sine
, in radians.sinh
: Hyperbolic sine.sqrt
: Square root.tan
:tangent
, in radians.tanh
: Hyperbolic tangent.trunc
: Truncate to integer.y0
: Bessel function of the second kind of order 0.y1
: Bessel function of the second kind of order 1.
- out_ports
Output ports for the UnaryOperator component.
UnaryOperatorIns
Inputs for the UnaryOperator component.
- input
(InPort)
Input signal.
UnaryOperatorOuts
Outputs for the UnaryOperator component.
- output
(OutPort)
Output signal.
Variable
Component that emits a constant signal which can be changed at runtime through dynamic configuration.
- config_key
(string)
Configuration key for overriding value setting through dynamic configuration.
- constant_output
The constant signal emitted by this component. The value of the constant signal can be overridden at runtime through dynamic configuration.
- out_ports
Output ports for the Variable component.
VariableOuts
Outputs for the Variable component.
- output
(OutPort)
The value is emitted to the output port.