meshmodel.md

Protocol Documentation

Table of Contents

• meshmodel.proto

  • CircuitBreaker
  • CustomResourceKind
  • HTTPMatch
  • HTTPRouteGroup
  • IdentityBindingSubject
  • Ingress
  • IngressPath
  • IngressRule
  • LoadBalance
  • MatchRule
  • MatchRule.HeadersEntry
  • Mock
  • MockRule
  • MockRule.HeadersEntry
  • Observability
  • ObservabilityMetrics
  • ObservabilityMetricsDetail
  • ObservabilityOutputServer
  • ObservabilityTracings
  • ObservabilityTracingsDetail
  • ObservabilityTracingsOutputConfig
  • RateLimiter
  • RateLimiterPolicy
  • Resilience
  • Retry
  • Service
  • ServiceCanary
  • ServiceInstance
  • ServiceInstance.LabelsEntry
  • ServiceSelector
  • ServiceSelector.MatchInstanceLabelsEntry
  • Sidecar
  • StringMatch
  • Tenant
  • TimeLimiter
  • TrafficRules
  • TrafficRules.HeadersEntry
  • TrafficTarget
  • TrafficTargetRule
  • URLRule

• Scalar Value Types

Top

meshmodel.proto

Copyright 2021 easegress-io Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

CircuitBreaker

CircuitBreaker is used for blocking all in-coming requests when the the failure numbers reach the configured limitation. You can declare an CircuitBreaker with COUNT_BASED or TIME_BASED type. It has three types of states, open, closed and half-close. One service can declare its desired CircuitBreaker, and the upstream clients will active the same CircuitBreaker

Field	Type	Label	Description
slidingWindowType	string		SlidingWindowType is the sliding window type of this break, only "COUNT_BASED" or "TIME_BASED" allowed.
failureRateThreshold	uint32		FailureRateThreshold configures the failure rate threshold in percentage. When the failure rate is equal or greater than the threshold the CircuitBreaker transitions to open and starts short-circuiting calls.
slowCallRateThreshold	uint32		SlowCallRateThreshold Configures a threshold in percentage. The CircuitBreaker considers a call as slow when the call duration is greater than slowCallDurationThreshold When the percentage of slow calls is equal or greater the threshold, the CircuitBreaker transitions to open and starts short-circuiting calls.
slidingWindowSize	uint32		SlidingWindowSize configures the size of the sliding window which is used to record the outcome of calls when the CircuitBreaker is closed.
permittedNumberOfCallsInHalfOpenState	uint32		PermittedNumberOfCallsInHalfOpenState configures the number of permitted calls when the CircuitBreaker is half open.
minimumNumberOfCalls	uint32		MinimumNumberOfCalls configures the minimum number of calls which are required (per sliding window period) before the CircuitBreaker can calculate the error rate or slow call rate. For example, if minimumNumberOfCalls is 10, then at least 10 calls must be recorded, before the failure rate can be calculated. If only 9 calls have been recorded the CircuitBreaker will not transition to open even if all 9 calls have failed.
slowCallDurationThreshold	string		SlowCallDurationThreshold configures the duration threshold above which calls are considered as slow and increase the rate of slow calls.
maxWaitDurationInHalfOpenState	string		MaxWaitDurationInHalfOpenState configures a 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 Circuit Breaker would wait infinitely in HalfOpen State until all permitted calls have been completed.
waitDurationInOpenState	string		WaitDurationInOpenState configures the duration that the CircuitBreaker should wait before transitioning from open to half-open,e.g.,60000ms.

CustomResourceKind

CustomResourceKind defines a custom resource kind.

Field	Type	Label	Description
name	string		Name is the name of the custom resource kind.
jsonSchema	google.protobuf.Struct		JSONSchema is the json schema to validate a custom resource of this kind.

HTTPMatch

HTTPMatch defines an individual route for HTTP traffic.

Field	Type	Label	Description
name	string		Name is the name of the HTTP match.
methods	string	repeated	Methods configures allowed HTTP method string, e.g. "GET","DELETE","POST".
pathRegex	string		PathRegex is a regular expression defining the route.

HTTPRouteGroup

HTTPRouteGroup defines the spec of a HTTP route group.

Field	Type	Label	Description
name	string		Name is the name for referencing a HTTPRouteGroup.
matches	HTTPMatch	repeated	Matches is a list of HTTPMatch to match traffic.

IdentityBindingSubject

IdentityBindingSubject is a subject which should be allowed access to the TrafficTarget.

Field	Type	Label	Description
kind	string		Kind is the type of Subject to allow access, must be "Service" by now.
name	string		Name of the Subject, i.e. ServiceName.

Ingress

Ingress is the spec of mesh ingress.

Field	Type	Label	Description
name	string		Name is the identify of this ingress.
rules	IngressRule	repeated	Rules is an array of ingress routing rules.

IngressPath

IngressPath is the path for a mesh ingress rule

Field	Type	Label	Description
path	string		Path is a regular expression for matching the target HTTP URL.
rewriteTarget	string		RewriteTarget is a regular expression for rewriting original URL when the HTTP URL path match the Path field.
backend	string		Backend is the mesh service's name.

IngressRule

IngressRule is the rule for mesh ingress.

Field	Type	Label	Description
host	string		Host is the RFC3986 defined host name.
paths	IngressPath	repeated	Paths is an array for mapping HTTP paths to mesh services.

LoadBalance

LoadBalance configures how to distribute the traffic inside this mesh.

Field	Type	Label	Description
policy	string		Policy including four kinds of load balancing scheme, including random, weightedRandom,ipHash, headerHash
headerHashKey	string		HeaderHashKey configures the key in HTTP header when the policy is headerHash.

MatchRule

Field	Type	Label	Description
path	string		Path is the exact path for matching request.
pathPrefix	string		PathPrefix is the prefix matching for request.
headers	MatchRule.HeadersEntry	repeated	Headers is the HTTP header fields for matching.
matchAllHeaders	bool		matchAllHeaders configures whether all the headers rule need to be matched.

MatchRule.HeadersEntry

Field	Type	Label	Description
key	string
value	StringMatch

Mock

Mock is the spec of mocking service's HTTP responses. Once enabled, this service won't need to be deployed, and other services visit it will get the configured response directly.

Field	Type	Label	Description
enabled	bool		Enable configures this mesh service's mocking switch.
rules	MockRule	repeated	Rules are the array for this mocking service.

MockRule

MockRule is one rule for mocking service.

Field	Type	Label	Description
match	MatchRule
code	int32		Code is the HTTP response code.
headers	MockRule.HeadersEntry	repeated	Headers is the HTTP header fields for response.
body	string		Body is the HTTP response body.
delay	string		Delay is the waiting duration for HTTP reponse.

MockRule.HeadersEntry

Field	Type	Label	Description
key	string
value	string

Observability

Observability consists of three components, outputServer, tracing, and metrics.

Field	Type	Label	Description
outputServer	ObservabilityOutputServer		OutputServer configures JavaAgent's tracing output target.
tracings	ObservabilityTracings		Tracings configures whether JavaAgent should deal with tracing HTTP header or not.
metrics	ObservabilityMetrics		Metrics configures the metrics JavaAgent should collect.

ObservabilityMetrics

Field	Type	Label	Description
enabled	bool		Enabled configures the global switch for this mesh service.
access	ObservabilityMetricsDetail		Access configures the access log about metrics.
request	ObservabilityMetricsDetail		Request configures this mesh service's HTTP APIs metrics.
jdbcStatement	ObservabilityMetricsDetail		JdbcStatement configures this mesh service's JDBC statement metrics.
jdbcConnection	ObservabilityMetricsDetail		JdbcConnection configures this mesh service's JDBC connection related metrics.
rabbit	ObservabilityMetricsDetail		Rabbit configures this mesh service's RabbitMQ requesting metrics.
kafka	ObservabilityMetricsDetail		Kafka configures this mesh service's Kafka requesting metrics.
redis	ObservabilityMetricsDetail		Redis configures this mesh service's redis requesting metrics.
jvmGc	ObservabilityMetricsDetail		JvmGc configures this mesh service's JVM GC related metrics.
jvmMemory	ObservabilityMetricsDetail		JvmMemory configures this mesh service's JVM memory usage related metrics.
md5Dictionary	ObservabilityMetricsDetail		Md5Dictionary configures this service's md5Dictionary for reporting complete SQL Sentence and signature.

ObservabilityMetricsDetail

ObservabilityMetricsDetail is the metrics detail of observability.

Field	Type	Label	Description
enabled	bool		Enabled configures the switch for one kind metric.
interval	int32		Interval configures the million seconds for metric reporting.
topic	string		Topic configures the metrics' reporting Kafka topic.

ObservabilityOutputServer

ObservabilityOutputServer configures how to report observability data to Kafka.

Field	Type	Label	Description
enabled	bool		Enabled configures whether reporting observability data to Kafka or not.
bootstrapServer	string		BootstrapServer configures the Kafka bootstrap servers.
timeout	int32		Timeout configures the timeout million second for requesting Kafka.

ObservabilityTracings

ObservabilityTracings configure the tracings of observability.

Field	Type	Label	Description
enabled	bool		Enable configures this mesh service's global tracing switch.
sampleByQPS	int32		SampleByQPS configures the QPS value for tracing sampling. The exceeded request will be ignored.
output	ObservabilityTracingsOutputConfig		Output configures the tracing output topic, queue and thread.
request	ObservabilityTracingsDetail		Request configures the tracing switch for this mesh service's HTTP APIs.
remoteInvoke	ObservabilityTracingsDetail		RemoteInvoke configures the tracing switch for this mesh service's HTTP RPC tracing.
kafka	ObservabilityTracingsDetail		Kafka configures the tracing switch for this mesh service's Kafka requesting.
jdbc	ObservabilityTracingsDetail		Jdbc configures the tracing switch for this mesh service's JDBC requesting.
redis	ObservabilityTracingsDetail		Redis configures the tracing switch for this mesh service's redis requesting.
rabbit	ObservabilityTracingsDetail		Rabbit configures the tracing switch for this mesh service's rabbitMQ requesting.

ObservabilityTracingsDetail

ObservabilityTracingsDetail

Field	Type	Label	Description
enabled	bool		Enabled configures whether reporting this tracing component or not.
servicePrefix	string		ServicePrefix is used to be combined with the tracing component's.

ObservabilityTracingsOutputConfig

Field	Type	Label	Description
enabled	bool		Enabled configures whether reporting to tracing output or not.
reportThread	int32		ReportThread configures the thread number for JavaAgent's reporting process.
topic	string		Topic configures the Kafka topic for tracing output target.
messageMaxBytes	int32		MessageMaxBytes configures the max bytes for one tracing report message.
queuedMaxSpans	int32		QueuedMaxSpans configures the max spans number for reporting queued.
queuedMaxSize	int32		QueuedMaxSize configures the max size of reporting queue.
messageTimeout	int32		MessageTimeout configures the timeout for the message queue.

RateLimiter

RateLimiter configures a limiter which can establish your services' high availability and reliability, also it can be used for scaling APIs. RateLimiter can protect servers from overwhelm by the peak traffic.

Field	Type	Label	Description
policies	RateLimiterPolicy	repeated	Policies contains different limiting configurations for this RateLimiter to use.
defaultPolicyRef	string		DefaultPolicyRef is the default reference policy name.
urls	URLRule	repeated	Urls describe the HTTP request matching schemes for this limiter to filter.

RateLimiterPolicy

RateLimiterPolicy configures the limiting policy used for Resilience component RateLimiter. It contains the basic configurations for the limiter, including the permission number, the duration for request waiting and the permission count refreshing period.

Field	Type	Label	Description
name	string		Name is the identify of this policy.
timeoutDuration	string		TimeoutDuration is the duration for one request should wait for a permission,e.g.,500ms.
limitRefreshPeriod	string		LimitRefreshPeriod is the period of a limit refresh. After each period the rate limiter sets its permissions count back to the limitForPeriod value.
limitForPeriod	int32		LimitForPeriod is the number of permissions available during one limit refresh period.

Resilience

Resilience configures four key types of features, RateLimiter, CircuitBreaker, Retry and Timeout.

Field	Type	Label	Description
rateLimiter	RateLimiter		RateLimiter configuration.
circuitBreaker	CircuitBreaker		CircuitBreaker configuration.
retry	Retry		Retry configuration.
timeLimiter	TimeLimiter		TimeLimiter configuration
failureCodes	int32	repeated	FailureCodes is the codes indicating the circuit breaker and retry to count the response as a failure.

Retry

Retry can perform an API calling retry when the service HTTP response code indicated its in temporary unavailable states. The up-stream client should make sure this API is idempotent. The service can declare an Retry for its desired APIs and active in client side.

Field	Type	Label	Description
maxAttempts	int32		MaxAttempts configures the maximum number of attempts. (including the initial call as the first attempt)
waitDuration	string		WaitDuration configures the based and fixed wait duration between retry attempts.
backOffPolicy	string		BackOffPolicy configures the two kinds of policy, random and exponential.
randomizationFactor	double		RandomizationFactor configures the factor used for backoff, value between 0 and 1.

Service

Service is the basic element in EaseMesh to describe a user's business microservices' name, belonging tenant, and governance specs. One service should belongs to a dedicated tenant.

Field	Type	Label	Description
registryName	string		Registry name is the registry name, it means mesh registry if empty.
name	string		Name is the mesh service's name.
registerTenant	string		RegisterTenant is the tenant's name this service belongs to.
resilience	Resilience		Resilience configuration, optional.
loadBalance	LoadBalance		LoadBalance configuration, optional.
sidecar	Sidecar		Sidecar configuration, optional.
observability	Observability		Observability configuration, optional.
mock	Mock		Mock configuration, optional.

ServiceCanary

Field	Type	Label	Description
name	string		Name is the name of service canary.
priority	int32		Priority must be [1, 9], the default is 5 if user does not set it. The smaller number get higher priority. The order is sorted by name alphabetically in the same priority.
selector	ServiceSelector		Selector is the service selector to choose service instances.
trafficRules	TrafficRules		TrafficRules is the traffic rules to be colored as the current canary.

ServiceInstance

ServiceInstance is the runnable entity of a Mesh Service.

Field	Type	Label	Description
registryName	string		registryName is the name of registry.
serviceName	string		ServiceName is the name of service this instance belongs to.
instanceID	string		InstanceID is the identity of this instance.
ip	string		IP is this instance's address in EaseMesh.
port	int32		Port is the port this instance listening to.
registryTime	string		RegistryTime is the time this instance registered.
labels	ServiceInstance.LabelsEntry	repeated	Labels is a map for storing service labels. This field is used for Canary Deployment.
status	string		Status is the status of this mesh service instance.
agentType	string		AgentType is the type of agent, which supports EaseAgent, GoSDK, None(same as empty value).

ServiceInstance.LabelsEntry

Field	Type	Label	Description
key	string
value	string

ServiceSelector

Field	Type	Label	Description
matchServices	string	repeated	MatchServices is the service list.
matchInstanceLabels	ServiceSelector.MatchInstanceLabelsEntry	repeated	MatchInstanceLabels is the instance labels.

ServiceSelector.MatchInstanceLabelsEntry

Field	Type	Label	Description
key	string
value	string

Sidecar

Sidecar configures the sidecar for every mesh service instances. It works inside the same pod with the workload instance.

Field	Type	Label	Description
discoveryType	string		DiscoveryType configures the type of service register/discovery type, its value are among "eureka","consul", and "nacos".
address	string		Address is the registry center address for workload to visit.
ingressPort	int32		IngressPort is the port for ingress traffic.
ingressProtocol	string		IngressProtocol is the protocol for ingress traffic. Its value is "http".
egressPort	int32		EgressPort is the port for egress traffic.
egressProtocol	string		EgressProtocol is the protocol for egress traffic. Its value is "http"

StringMatch

StringMatch configures how to match string in different ways. Its priority is according to the field order. StringMatch will try exactly matching firstly, then try to check has the same prefix, at last, it will use the regular expression to match the string if it's provided

Field	Type	Label	Description
exact	string		Exact configures the exactly URL value to match.
prefix	string		Prefix configures the prefix for URL to match.
regex	string		Regex configures the regular expression for URL to match.

Tenant

Tenant is the logic group of mesh services. Inside the same tenant, services can visit each other directly. There are two kinds of tenant, one is the common type of tenants and the other is system reserved "global" tenant which's access scope is globally inside the mesh . If one mesh service is created with "global" tenant filed, it can be visible to all the service inside the mesh.

Field	Type	Label	Description
name	string		Name is the identify of this tenant.
services	string	repeated	Services are the array of mesh service name in this tenant.
description	string		Descriptions for this tenant.

TimeLimiter

Timeout configures the amount of time the client should wait for replies from a given service, it will be running in upstream clients and declared in downstream relied services.

Field	Type	Label	Description
timeout	string		timeout configures the duration for timeout, e.g.,500ms.

TrafficRules

Field	Type	Label	Description
headers	TrafficRules.HeadersEntry	repeated	Headers configure HTTP requests matching configurations with "OR" relation. Once HTTP requests match one element in this array, it will be regarded as the colored traffic.

TrafficRules.HeadersEntry

Field	Type	Label	Description
key	string
value	StringMatch

TrafficTarget

TrafficTarget is the specification of a TrafficTarget.

Field	Type	Label	Description
name	string		Name is the name for referencing a TrafficTarget.
destination	IdentityBindingSubject		Destination is the service to allow ingress traffic.
sources	IdentityBindingSubject	repeated	Sources are the services to allow egress traffic.
rules	TrafficTargetRule	repeated	Rules are the traffic rules to allow (HTTPRoutes).

TrafficTargetRule

TrafficTargetRule is the TrafficSpec to allow for a TrafficTarget, TrafficSpec can only be HTTPRouteGroup by now.

Field	Type	Label	Description
kind	string		Kind is the kind of TrafficSpec to allow, must be "HTTPRouteGroup" by now.
name	string		Name of the TrafficSpec to use.
matches	string	repeated	Matches is a list of TrafficSpec routes to allow traffic for, TrafficSpec routes can only be HTTPMatch by now.

URLRule

URLRule can be used to filter HTTP request by using HTTP method and URL.

Field	Type	Label	Description
methods	string	repeated	Methods configures allowed HTTP method string, e.g. "GET","DELETE","POST".
url	StringMatch		Url configures how to match the HTTP request URL.
policyRef	string		PolicyRef configures which policy this URLRule references to.

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)