Controllers

As the architecture diagram shows, the controller is the core entity to control kinds of working. There are two kinds of controllers overall:

  • System Controller: It is created one and only one instance in every Easegress node, which can’t be deleted. They mainly aim to control essential system-level stuff.
  • Business Controller: It could be created, updated, deleted by admin operation. They control various resources such as mesh traffic, service discovery, faas, and so on.

In another view, Easegress as a traffic orchestration system, we could classify them into traffic controller and non-traffic controller:

  • Traffic Controller: It invokes TrafficController to handle its specific traffic, such as MeshController.
  • Non-Traffic Controller: It doesn’t handle business traffic, such as EurekaServiceRegistry, even though it has admin traffic with Eureka.

The two categories are conceptual, which means they are not strict distinctions. We just use them as terms to clarify controllers technically.

System Controllers

For now, all system controllers can not be configured. It may gain this capability if necessary in the future.

ServiceRegistry

We use the system controller ServiceRegistry as the service hub for all service registries. Current drivers are

The drivers need to offer notifying change periodically, and operations to the external service registry.

TrafficController

TrafficController handles the lifecycle of Traffic Gates (like HTTPServer) and Pipeline and their relationship. It manages the resource in a namespaced way. Traffic gates accepts incoming traffic and routes it to Pipelines in the same namespace. Most other controllers could handle traffic by leverage the ability of TrafficController..

RawConfigTrafficController

RawConfigTrafficController maps all traffic static configurations to TrafficController in the namespace default. We could use egctl to manage the configuration of servers and pipelines in the default namespace.

HTTPServer

HTTPServer is a server that listens on one port to route all traffic to available pipelines. Its simplest config looks like:

kind: HTTPServer
name: http-server-example
port: 80
rules:
  - paths:
    - pathPrefix: /pipeline
      backend: http-pipeline-example
NameTypeDescriptionRequired
http3boolWhether to support HTTP3(QUIC)No
portuint16The HTTP port listening onYes
keepAliveboolWhether to support keepaliveYes (default: false)
keepAliveTimeoutstringThe timeout of keepaliveYes (default: 60s)
maxConnectionsuint32The max connections with clientsYes (default: 10240)
httpsboolWhether to use HTTPSYes (default: false)
cacheSizeuint32The size of cache, 0 means no cacheNo
xForwardedForboolWhether to set X-Forwarded-For header by own ipNo
tracingtracing.SpecDistributed tracing settingsNo
certBase64stringPublic key of PEM encoded data in base64 encoded formatNo
keyBase64stringPrivate key of PEM encoded data in base64 encoded formatNo
certsmap[string]stringPublic keys of PEM encoded data, the key is the logic pair name, which must match keysNo
keysmap[string]stringPrivate keys of PEM encoded data, the key is the logic pair name, which must match certsNo
ipFilteripfilter.SpecIP Filter for all traffic under the serverNo
routerKindstringKind of router. see routersNo (default: Order)
rules[]httpserver.RuleRouter rulesNo
autoCertboolDo HTTP certification automaticallyNo
clientMaxBodySizeint64Max size of request body. the default value is 4MB. Requests with a body larger than this option are discarded. When this option is set to -1, Easegress takes the request body as a stream and the body can be any size, but some features are not possible in this case, please refer Stream for more information.No
caCertBase64stringDefine the root certificate authorities that servers use if required to verify a client certificate by the policy in TLS Client Authentication.No
globalFilterstringName of GlobalFilter for all backendsNo
accessLogFormatstringFormat of access log, default is [{{Time}}] [{{RemoteAddr}} {{RealIP}} {{Method}} {{URI}} {{Proto}} {{StatusCode}}] [{{Duration}} rx:{{ReqSize}}B tx:{{RespSize}}B] [{{Tags}}], variable is delimited by “{{” and “}}”, please refer Access Log Variable for all built-in variablesNo
AccessLogVariable
NameDescription
TimeStart time for handling the request
RemoteAddrNetwork address that sent the request
RealIPReal IP of the request
MethodHTTP method (GET, POST, PUT, etc.) for the request
URIUnmodified request-target of the Request-Line
ProtoProtocol version for the request
StatusCodeHTTP status code for the response
DurationDuration time for handing the request
ReqSizeSize read from the request
RespSizeSize write to the response
ReqHeadersRequest HTTP headers
RespHeadersResponse HTTP headers
TagsTags for handing the request

GRPCServer

The GRPCServer in Easegress provides robust functionality tailored to gRPC protocol interactions. With its IP filtering feature, traffic can be selectively allowed or blocked, ensuring that only desired clients can communicate with the services. Additionally, the server’s routing rules offer flexible methods to determine how each incoming request is processed and forwarded, based on host, method, headers, and other criteria.

name: server-grpc
kind: GRPCServer
port: 8080

---
title: The maximum number of connections allowed by gRPC Server.
linkTitle: The maximum number of connections allowed by gRPC Server.
weight: 1
---
---
title: Default value 10240
linkTitle: Default value 10240
weight: 1
---
maxConnections: 10240

---
title: IP Filter for all traffic under the server
linkTitle: IP Filter for all traffic under the server
weight: 1
---
ipFilter:
  blockIPs: []
  allowIPs: []
  blockByDefault: false

---
title: routing rules
linkTitle: routing rules
weight: 1
---
rules:
---
title: Rules for host matching.
linkTitle: Rules for host matching.
weight: 1
---
---
title: If not match, GRPCServer will check next rule.
linkTitle: If not match, GRPCServer will check next rule.
weight: 1
---
- host: <your-host>
  hostRegexp: <your-host-regexp>

  methods: 
  - method: /Sale/AddProduct # Exact method match
    backend: sale-pipeline

  - methodPrefix: /IT        # Matches method with the given prefix
    backend: it-pipeline

  - headers:                 # Matches by header
    - key: x-geo-country
      values: ["CN", "EU", "US"]
    - key: user-agent
      values: ["SaleClient/1.0.0"]
    matchAllHeader: false
    backend: header-pipeline

  - methodRegexp: .*         # Match by regexp
    backend: other-pipeline

---
title: more rules
linkTitle: more rules
weight: 1
---
- methods:
  ...
Example Requests
  • A gRPC request with method /Sale/AddProduct will be routed to the sale-pipeline.
  • Any request with a method starting with /IT (e.g., /IT/UpdateSoftware) will be directed to the it-pipeline.
  • If a client sends a request with headers x-geo-country set to CN and user-agent set to SaleClient/1.0.0, it will be handled by the header-pipeline.
  • All other requests (due to the wildcard methodRegexp) will be sent to the other-pipeline.
Configuration

The below parameters will help manage connections better

NameTypeDescriptionRequired
maxConnectionsuint32The maximum number of connections allowed by gRPC Server , default value 10240, min is 1No
minTimeClientSendPingdurationThe minimum amount of time a client should wait before sending a keepalive ping, default value is 5 minutesNo
permitClintSendPingWithoutStreamdurationIf true, server allows keepalive pings even when there are no active streams(RPCs). If false, and client sends ping when there are no active streams, server will send GOAWAY and close the connection. default falseNo
maxConnectionIdledurationA duration for the amount of time after which an idle connection would be closed by sending a GoAway. Idleness duration is defined since the most recent time the number of outstanding RPCs became zero or the connection establishment. default value is infinityNo
maxConnectionAgedurationA duration for the maximum amount of time a connection may exist before it will be closed by sending a GoAway. A random jitter of ±10% will be added to MaxConnectionAge to prevent connection storms. default value is infinityNo
maxConnectionAgeGracedurationAn additive period after MaxConnectionAge after which the connection will be forcibly closed. default value is infinityNo
keepaliveTimedurationAfter a duration of this time if the server doesn’t see any activity it pings the client to see if the transport is still alive. If set below 1s, a minimum value of 1s will be used instead. default value is 2 hours.No
keepaliveTimeoutdurationAfter having pinged for keepalive check, the server waits for a duration of Timeout and if no activity is seen even after that the connection is closed. default value is 20 secondsNo
ipFilteripfilter.SpecIP Filter for all trafficNo
rules[]grpcserver.RuleRouter rulesNo

Pipeline

Pipeline is used to orchestrate filters. Its simplest config looks like:

name: http-pipeline-example1
kind: Pipeline
flow:
- filter: proxy

filters:
- name: proxy
  kind: Proxy
  pools:
  - servers:
    - url: http://127.0.0.1:9095

The flow defines the execution order of filters. You can use jumpIf to change the order.

For example, if a request’s header doesn’t have the key X-Id or its value is not user1 or user2, then the validator filter returns result invalid and the pipeline jumps to END.

name: http-pipeline-example2
kind: Pipeline
flow:
- filter: validator
  jumpIf:
    # END is a built-in filter, it stops the execution of the pipeline.
    invalid: END
- filter: proxy

filters:
- name: validator
  kind: Validator
  headers:
    X-Id:
      values: ["user1", "user2"]
- name: proxy
  kind: Proxy
  pools:
  - servers:
    - url: http://127.0.0.1:9095

jumpIf can only jump to filters behind the current filter.

The resilience field defines resilience policies, if a filter implements the filters.Resiliencer interface (for now, only the Proxy filter implements the interface), the pipeline injects the policies into the filter instance after creating it. A filter can implement the filters.Resiliencer interface to support resilience. There are two kinds of resilience, Retry and CircuitBreaker. Check resilience for more details. The following config adds a retry policy to the proxy filter:

name: http-pipeline-example3
kind: Pipeline
flow:
- filter: proxy

filters:
- name: proxy
  kind: Proxy
  pools:
  - servers:
    - url: http://127.0.0.1:9095
    retryPolicy: retry

resilience:
- name: retry
  kind: Retry
  maxAttempts: 3

In this case, if proxy returns non-empty results, then resilience retry reruns the proxy filter until proxy returns empty results or gets the max attempts.

The flow also supports namespace, so the pipeline can support workflows that contain multiple requests and responses.

name: http-pipeline-example4
kind: Pipeline
flow:
- filter: validator
  jumpIf:
    invalid: END
- filter: requestBuilderFoo
  namespace: foo
- filter: proxyFoo
  namespace: foo
- filter: requestBuilderBar
  namespace: bar
- filter: proxyBar
  namespace: bar
- filter: responseBuilder

filters:
- name: requestBuilder
  kind: RequestBuilder
  ...
...

In this case, requestBuilderFoo creates a request in namespace foo, and proxyFoo sends foo request and puts the response into namespace foo. requestBuilderBar creates a request in namespace bar and proxyBar sends bar request and puts the response into namespace bar. Finally, requestBuilder creates a response and puts it into the default namespace.

If not set, the filter works in the default namespace DEFAULT.

The alias in flow gives a filter an alias to help re-use the filter so that we can use the alias to distinguish each of its appearances in the flow.

name: http-pipeline-example5
kind: Pipeline
flow:
- filter: validator
  jumpIf:
    invalid: proxy2
- filter: proxy
---
title: when meeting filter END, the pipeline execution stops and returns.
linkTitle: when meeting filter END, the pipeline execution stops and returns.
weight: 1
---
- filter: END
- filter: proxy
  alias: proxy2
- filter: responseAdaptor

filters:
- name: proxy
  kind: Proxy
  ...

In this case, we give second proxy alias proxy2, so request is invalid, it jumps to second proxy.

The data field defines static user data for the pipeline, which can be accessed by filters. For example, in the below pipeline, the body of the result request of the RequestBuilder will be hello world, which is the value of data item foo.

name: http-pipeline-example6
kind: Pipeline
flow:
  ...

filters:
- name: requestBuilder
  kind: RequestBuilder
  template: |
    body: {{.data.PIPELINE.foo}}    

data:
  foo: "hello world"
NameTypeDescriptionRequired
flow[]FlowNodeThe execution order of filters, if empty, will use the order of the filter definitions.No
filters[]map[string]interface{}Defines filters, please refer Filters for details of a specific filter kind.Yes
resilience[]map[string]interface{}Defines resilience policies, please refer Resilience Policy for details of a specific resilience policy.No
datamap[string]interface{}Static user data of the pipeline.No

StatusSyncController

No config.

Business Controllers

GlobalFilter

GlobalFilter is a special pipeline that can be executed before or/and after all pipelines in a server. For example:

name: globalFilter-example
kind: GlobalFilter
beforePipeline:
  flow:
  - filter: validator

  filters:
  - name: validator
    kind: Validator
    ...
---
name: server-example
kind: HTTPServer
globalFilter: globalFilter-example
...

In this case, all requests in HTTPServer server-example go through GlobalFilter globalFilter-example before executing any other pipelines.

NameTypeDescriptionRequired
beforePipelinepipeline.SpecSpec for before pipelineNo
afterPipelinepipeline.SpecSpec for after pipelineNo

EaseMonitorMetrics

EaseMonitorMetrics is adapted to monitor metrics of Easegress and send them to Kafka. The config looks like:

kind: EaseMonitorMetrics
name: easemonitor-metrics-example
kafka:
  brokers: ["127.0.0.1:9092"]
  topic: metrics
NameTypeDescriptionRequired
kafkaeasemonitormetrics.KafkaKafka related configYes

FaaSController

A FaaSController is a business controller for handling Easegress and FaaS products integration purposes. It abstracts FaasFunction, FaaSStore and, FaasProvider. Currently, we only support Knative type FaaSProvider.

For the full reference document please check - FaaS Controller

IngressController

The IngressController is an implementation of Kubernetes ingress controller, it watches Kubernetes Ingress, Service, Endpoints, and Secrets then translates them to Easegress HTTP server and pipelines. The config looks like:

kind: IngressController
name: ingress-controller-example
kubeConfig:
masterURL:
namespaces: ["default"]
ingressClass: easegress
httpServer:
  port: 8080
  https: false
  keepAlive: true
  keepAliveTimeout: 60s
  maxConnections: 10240
NameTypeDescriptionRequired
kubeConfigstringPath of the Kubernetes configuration file.No
masterURLstringThe address of the Kubernetes API server.No
namespaces[]stringAn array of Kubernetes namespaces which the IngressController needs to watch, all namespaces are watched if left empty.No
ingressClassstringThe IngressController only handles Ingresses with ingressClassName set to the value of this option.No (default: easegress)
httpServerhttpserver.SpecBasic configuration for the shared HTTP traffic gate. The routing rules will be generated dynamically according to Kubernetes ingresses and should not be specified here.Yes

Note: IngressController uses kubeConfig and masterURL to connect to Kubernetes, at least one of them must be specified when deployed outside of a Kubernetes cluster, and both are optional when deployed inside a cluster.

ConsulServiceRegistry

ConsulServiceRegistry supports service discovery for Consul as backend. The config looks like:

kind: ConsulServiceRegistry
name: consul-service-registry-example
address: '127.0.0.1:8500'
scheme: http
syncInterval: 10s
NameTypeDescriptionRequired
addressstringConsul server addressYes (default: 127.0.0.1:8500)
schemestringCommunication schemeYes (default: http)
datacenterstringDatacenter nameNo
tokenstringACL token for communicationNo
namespacestringNamespace to useNo
syncIntervalstringInterval to synchronize dataYes (default: 10s)
serviceTags[]stringService tags to queryNo

EtcdServiceRegistry

EtcdServiceRegistry support service discovery for Etcd as backend. The config looks like:

kind: EtcdServiceRegistry
name: etcd-service-registry-example
endpoints: ['127.0.0.1:12379']
prefix: "/services/"
cacheTimeout: 10s
NameTypeDescriptionRequired
endpoints[]stringEndpoints of Etcd serversYes
prefixstringPrefix of the keys of servicesYes (default: /services/)
cacheTimeoutstringTimeout of cacheYes (default: 60s)

EurekaServiceRegistry

EurekaServiceRegistry supports service discovery for Eureka as backend. The config looks like:

kind: EurekaServiceRegistry
name: eureka-service-registry-example
endpoints: ['http://127.0.0.1:8761/eureka']
syncInterval: 10s
NameTypeDescriptionRequired
endpoints[]stringEndpoints of Eureka serversYes (default: http://127.0.0.1:8761/eureka)
syncIntervalstringInterval to synchronize dataYes (default: 10s)

ZookeeperServiceRegistry

ZookeeperServiceRegistry supports service discovery for Zookeeper as backend. The config looks like:

kind: ZookeeperServiceRegistry
name: zookeeper-service-registry-example
zkservices: [127.0.0.1:2181]
prefix: /services
conntimeout: 6s
syncInterval: 10s
NameTypeDescriptionRequired
zkservices[]stringZookeeper service addressesYes (default: 127.0.0.1:2181)
connTimeoutstringTimeout of connectionYes (default: 6s)
prefixstringPrefix of servicesYes (default: /)
syncIntervalstringInterval to synchronize dataYes (default: 10s)

NacosServiceRegistry

NacosServiceRegistry supports service discovery for Nacos as backend. The config looks like:

kind: NacosServiceRegistry
name: nacos-service-registry-example
syncInterval: 10s
servers:
  - scheme: http
    port: 8848
    contextPath: /nacos
    ipAddr: 127.0.0.1
NameTypeDescriptionRequired
servers[]nacosServerSpecServers of NacosYes
syncIntervalstringInterval to synchronize dataYes (default: 10s)
namespacestringThe namespace of NacosNo
usernamestringThe username of clientNo
passwordstringThe password of clientNo

AutoCertManager

AutoCertManager automatically manage HTTPS certificates. The config looks like:

kind: AutoCertManager
name: autocert
email: someone@megaease.com
directoryURL: https://acme-v02.api.letsencrypt.org/directory
renewBefore: 720h
enableHTTP01: true
enableTLSALPN01: true
enableDNS01: true
domains:
  - name: "*.megaease.com"
    dnsProvider:
      name: dnspod
      zone: megaease.com
      apiToken: <token value>
NameTypeDescriptionRequired
emailstringAn email address for CA accountYes
directoryURLstringThe endpoint of the CA directoryNo (default to use Let’s Encrypt)
renewBeforestringA certificate will be renewed before this duration of its expire timeNo (default 720 hours)
enableHTTP01boolEnable HTTP-01 challenge (Easegress need to be accessable at port 80 when true)No (default true)
enableTLSALPN01boolEnable TLS-ALPN-01 challenge (Easegress need to be accessable at port 443 when true)No (default true)
enableDNS01boolEnable DNS-01 challengeNo (default true)
domains[]DomainSpecDomains to be managedYes

Common Types

tracing.Spec

NameTypeDescriptionRequired
serviceNamestringThe service name of top levelYes
attributesmap[string]stringAttributes to include to every span.No
tagsmap[string]stringDeprecated. Tags to include to every span. This option will be kept until the next major version incremented release.No
spanLimitsspanlimits.SpecSpanLimitsSpec represents the limits of a span.No
sampleRatefloat64The sample rate for collecting metrics, the range is [0, 1]. For backward compatibility, if the exporter is empty, the default is to use zipkin.sampleRateNo (default: 1)
batchLimitsbatchlimits.SpecBatchLimitsSpec describes BatchSpanProcessorOptionsNo
exporterexporter.SpecExporterSpec describes exporter. exporter and zipkin cannot both be emptyNo
zipkinzipkin.DeprecatedSpecZipkinDeprecatedSpec describes Zipkin. If exporter is configured, this option does not take effect. This option will be kept until the next major version incremented release.No
headerFormatstringHeaderFormat represents which format should be used for context propagation. options: trace-conext,b3. For backward compatibility, the historical Zipkin configuration remains in b3 format.No (default: trace-conext)

spanlimits.Spec

NameTypeDescriptionRequired
attributeValueLengthLimitintAttributeValueLengthLimit is the maximum allowed attribute value length, Setting this to a negative value means no limit is appliedNo (default:-1)
attributeCountLimitintAttributeCountLimit is the maximum allowed span attribute countNo (default:128)
eventCountLimitintEventCountLimit is the maximum allowed span event countNo (default:128)
linkCountLimitintLinkCountLimit is the maximum allowed span link countNo (default:128)
attributePerEventCountLimitintAttributePerEventCountLimit is the maximum number of attributes allowed per span eventNo (default:128)
attributePerLinkCountLimitintAttributePerLinkCountLimit is the maximum number of attributes allowed per span linkNo (default:128)

batchlimits.Spec

NameTypeDescriptionRequired
maxQueueSizeintMaxQueueSize is the maximum queue size to buffer spans for delayed processingNo (default:2048)
batchTimeoutintBatchTimeout is the maximum duration for constructing a batchNo (default:5000 msec)
exportTimeoutintExportTimeout specifies the maximum duration for exporting spansNo (default:30000 msec)
maxExportBatchSizeintMaxExportBatchSize is the maximum number of spans to process in a single batchNo (default:512)

exporter.Spec

NameTypeDescriptionRequired
jaegerjaeger.SpecJaegerSpec describes JaegerNo
zipkinzipkin.SpecZipkinSpec describes ZipkinNo
otlpotlp.SpecOTLPSpec describes OpenTelemetry exporterNo

jaeger.Spec

NameTypeDescriptionRequired
modestringJaeger’s access modeYes (options: agent,collector)
endpointstringIn agent mode, endpoint must be host:port, in collector mode it is urlNo
usernamestringThe username used in collector modeNo
passwordstringThe password used in collector modeNo

zipkin.Spec

NameTypeDescriptionRequired
endpointstringThe zipkin server URLYes

otlp.Spec

NameTypeDescriptionRequired
protocolstringConnection protocol of otlpYes (options: http,grpc)
endpointstringEndpoint of the otlp collectorYes
insecureboolWhether to allow insecure connectionsNo (default: false)
compressionstringCompression describes the compression used for payloads sent to the collectorNo (options: gzip)

zipkin.DeprecatedSpec

NameTypeDescriptionRequired
hostPortstringDeprecated. The host:port of the serviceNo
serverURLstringThe zipkin server URLYes
sampleRatefloat64The sample rate for collecting metrics, the range is [0, 1]Yes
disableReportboolDeprecated. Whether to report span model data to zipkin serverNo
sameSpanboolDeprecated. Whether to allow to place client-side and server-side annotations for an RPC call in the same spanNo
id128BitboolDeprecated. Whether to start traces with 128-bit trace idNo

ipfilter.Spec

NameTypeDescriptionRequired
blockByDefaultboolSet block is the default action if not matchingYes (default: false)
allowIPs[]stringIPs to be allowed to pass (support IPv4, IPv6, CIDR)No
blockIPs[]stringIPs to be blocked to pass (support IPv4, IPv6, CIDR)No

httpserver.Rule

NameTypeDescriptionRequired
ipFilteripfilter.SpecIP Filter for all traffic under the ruleNo
hoststringExact host to matchNo
hostRegexpstringHost in regular expression to matchNo
hosts[]httpserver.HostHosts to matchNo
paths[]httpserver.PathPath matching rules, empty means to match nothing. Note that multiple paths are matched in the order of their appearance in the spec, this is different from Nginx.No

Note: if host or hostRegexp is not empty, they will be added into hosts at runtime, and if the result hosts is empty, all hosts are matched.

httpserver.Host

NameTypeDescriptionRequired
isRegexpboolWhether value is regular expression or exact value, default is falseNo
valuestringHost value to matchYes

httpserver.Path

NameTypeDescriptionRequired
ipFilteripfilter.SpecIP Filter for all traffic under the pathNo
pathstringExact path to matchNo
pathPrefixstringPrefix of the path to matchNo
pathRegexpstringPath in regular expression to matchNo
rewriteTargetstringUse pathRegexp.ReplaceAllString(path, rewriteTarget) or pathPrefix strings.Replace to rewrite request pathNo
methods[]stringMethods to match, empty means to allow all methodsNo
headers[]httpserver.HeaderHeaders to match (the requests matching headers won’t be put into cache)No
backendstringbackend name (pipeline name in static config, service name in mesh)Yes
clientMaxBodySizeint64Max size of request body, will use the option of the HTTP server if not set. the default value is 4MB. Requests with a body larger than this option are discarded. When this option is set to -1, Easegress takes the request body as a stream and the body can be any size, but some features are not possible in this case, please refer Stream for more information.No
matchAllHeaderboolMatch all headers that are defined in headers, default is false.No
matchAllQueryboolMatch all queries that are defined in queries, default is false.No

httpserver.Header

There must be at least one of values and regexp.

NameTypeDescriptionRequired
keystringHeader key to matchYes
values[]stringHeader values to matchNo
regexpstringHeader value in regular expression to matchNo

pipeline.Spec

NameTypeDescriptionRequired
flowpipeline.FlowNodeFlow of pipelineNo
filters[]filters.FilterFilter definitions of pipelineYes
resilience[]resilience.PolicyResilience policy for backend filtersNo

pipeline.FlowNode

NameTypeDescriptionRequired
filterstringThe filter nameYes
jumpIfmap[string]stringJump to another filter conditionally, the key is the result of the current filter, the value is the target filter name/alias. END is the built-in value for the ending of the pipelineNo
namespacestringNamespace of the filterNo
aliasstringAlias name of the filterNo

filters.Filter

The self-defining specification of each filter references to filters.

NameTypeDescriptionRequired
namestringName of filterYes
kindstringKind of filterYes
self-defining fields---

grpcserver.Rule

NameTypeDescriptionRequired
hoststringExact host to matchNo
hostRegexpstringHost in regular expression to matchNo
methods[]grpcserver.MethodMethod matching rules, empty means to match nothing.No
ipFilteripFilter.SpecIP Filter for all traffic under the ruleNo

grpcserver.Method

NameTypeDescriptionRequired
methodstringExact method to matchNo
methodPrefixstringPrefix of the method to matchNo
methodRegexpstringMethod in regular expression to matchNo
backendstringbackend name (pipeline name in static config, service name in mesh)No
headers[]grpcserver.HeaderHeaders to matchNo
matchAllHeaderboolMatch all headers that are defined in headers, default is false.No
ipFilteripFilter.SpecIP Filter for all traffic under the methodNo

grpcserver.Header

NameTypeDescriptionRequired
keystringHeader key to matchYes
values[]stringHeader values to matchNo
regexpstringHeader value in regular expression to matchNo

easemonitormetrics.Kafka

NameTypeDescriptionRequired
brokers[]stringBroker addressesYes (default: localhost:9092)
topicstringProduce topicYes

nacos.ServerSpec

NameTypeDescriptionRequired
ipAddrstringThe ip addressYes
portuint16The portYes
schemestringThe scheme of protocol (support http, https)No
contextPathstringThe context pathNo

autocertmanager.DomainSpec

NameTypeDescriptionRequired
namestringThe name of the domainYes
dnsProvidermap[string]stringDNS provider informationNo (Yes if DNS-01 chanllenge is desired)

The fields in dnsProvider vary from DNS providers, but:

  • name and zone are required for all DNS providers.
  • nsAddress and nsNetwork are optional name server information for all DNS providers, if provided, AutoCertManager will leverage them to speed up the DNS record lookup. nsAddress is the address of the name server, must always include the port number, nsNetwork is the network protocol of name server, it should be udp in most cases.

Below table list other required fields for each supported DNS provider (Note: google is temporarily disabled due to dependency conflict):

DNS Provider NameRequired Fields
alidnsaccessKeyId, accessKeySecret
azuretenantId, clientId, clientSecret, subscriptionId, resourceGroupName
cloudflareapiToken
digitaloceanapiToken
dnspodapiToken
duckdnsapiToken
googleproject
hetznerauthApiToken
route53accessKeyId, secretAccessKey, awsProfile
vultrapiToken

resilience.Policy

NameTypeDescriptionRequired
namestringName of filterYes
kindstringKind of filterYes
other kind specific fields of the policy kind---

Retry Policy

A retry policy configures how to retry a failed request.

NameTypeDescriptionRequired
maxAttemptsintThe maximum number of attempts (including the initial one). Default is 3No
waitDurationstringThe base wait duration between attempts. Default is 500msNo
backOffPolicystringThe back-off policy for wait duration, could be EXPONENTIAL or RANDOM and the default is RANDOM. If configured as EXPONENTIAL, the base wait duration becomes 1.5 times larger after each failed attemptNo
randomizationFactorfloat64Randomization factor for actual wait duration, a number in interval [0, 1], default is 0. The actual wait duration used is a random number in interval [(base wait duration) * (1 - randomizationFactor), (base wait duration) * (1 + randomizationFactor)]No

CircuitBreaker Policy

CircuitBreaker leverges a finite state machine to implement the processing logic, the state machine has three states: CLOSED, OPEN, and HALF_OPEN. When the state is CLOSED, requests pass through normally, state transits to OPEN if request failure rate or slow request rate reach a configured threshold and requests will be shor-circuited in this state. After a configured duration, state transits from OPEN to HALF_OPEN, in which a limited number of requests are permitted to pass through while other requests are still short-circuited, and state transit to CLOSED or OPEN based on the results of the permitted requests.

When CLOSED, it uses a sliding window to store and aggregate the result of recent requests, the window can either be COUNT_BASED or TIME_BASED. The COUNT_BASED window aggregates the last N requests and the TIME_BASED window aggregates requests in the last N seconds, where N is the window size.

Below is an example configuration with both COUNT_BASED and TIME_BASED policies.

Policy circuit-breaker-example-count short-circuits requests if more than half of recent requests failed.

Policy circuit-breaker-example-time short-circuits requests if more than 60% of recent requests failed.

failed means that backend filter returns non-empty results.

kind: CircuitBreaker
name: circuit-breaker-example-count
slidingWindowType: COUNT_BASED
failureRateThreshold: 50
slidingWindowSize: 100

---
kind: CircuitBreaker
name: circuit-breaker-example-time
slidingWindowType: TIME_BASED
failureRateThreshold: 60
slidingWindowSize: 100
NameTypeDescriptionRequired
slidingWindowTypestringType of the sliding window which is used to record the outcome of requests when the CircuitBreaker is CLOSED. Sliding window can either be COUNT_BASED or TIME_BASED. If the sliding window is COUNT_BASED, the last slidingWindowSize requests are recorded and aggregated. If the sliding window is TIME_BASED, the requests of the last slidingWindowSize seconds are recorded and aggregated. Default is COUNT_BASEDNo
failureRateThresholdint8Failure rate threshold in percentage. When the failure rate is equal to or greater than the threshold the CircuitBreaker transitions to OPEN and starts short-circuiting requests. Default is 50No
slowCallRateThresholdint8Slow rate threshold in percentage. The CircuitBreaker considers a request as slow when its duration is greater than slowCallDurationThreshold. When the percentage of slow requests is equal to or greater than the threshold, the CircuitBreaker transitions to OPEN and starts short-circuiting requests. Default is 100No
slowCallDurationThresholdstringDuration threshold for slow callNo
slidingWindowSizeuint32The size of the sliding window which is used to record the outcome of requests when the CircuitBreaker is CLOSED. Default is 100No
permittedNumberOfCallsInHalfOpenStateuint32The number of permitted requests when the CircuitBreaker is HALF_OPEN. Default is 10No
minimumNumberOfCallsuint32The minimum number of requests which are required (per sliding window period) before the CircuitBreaker can calculate the error rate or slow requests rate. For example, if minimumNumberOfCalls is 10, then at least 10 requests must be recorded before the failure rate can be calculated. If only 9 requests have been recorded the CircuitBreaker will not transition to OPEN even if all 9 requests have failed. Default is 10No
maxWaitDurationInHalfOpenStatestringThe maximum wait duration which controls the longest amount of time a CircuitBreaker could stay in HALF_OPEN state before it switches to OPEN. Value 0 means CircuitBreaker would wait infinitely in HALF_OPEN State until all permitted requests have been completed. Default is 0No
waitDurationInOpenStatestringThe time that the CircuitBreaker should wait before transitioning from OPEN to HALF_OPEN. Default is 60sNo

See more details about Retry, CircuitBreaker or other resilience polcies in here.