Skip to main content
logoTetrate Service BridgeVersion: 1.12.x

Profile

Alpha feature

The configuration profiles feature is in an alpha state, we will be making breaking changes to its API in release 1.12. Please contact Tetrate if you have any questions or concerns.

A Profile is a predefined configuration template that can be defined at the Organizations, Tenants, and Workspaces, and then can be attached to Organizations, Tenants, Workspaces and Groups. Profiles are intended for traffic-related settings and security policies that map to the resource itself, not for security policies (e.g. authorization policies) related to relationships between resources. They contain Default configurations, which can be overridden, and Mandates configurations, which can't be.

The following example creates a Profile named myprofile that enforces mutual TLS authenticated connections across the whole tetrate organization, also sets the default circuit breaking sensitivity to MEDIUM. It also configures the TCP KeepAlive as 300 seconds for all inbound connections to all the proxies in the tetrate organization.

apiVersion: profile.tsb.tetrate.io/v2
kind: Profile
metadata:
name: myprofile
organization: tetrate
spec:
displayName: "mTLS enforcement and default circuit breaking"
mandates:
authenticationSettings:
trafficMode: "REQUIRED"
defaults:
trafficSettings:
inbound:
resilience:
connectionPool:
tcp:
keepAlive:
idleTime: 300s
outbound:
upstreamTrafficSettings:
- hosts:
- '*'
settings:
resilience:
circuitBreakerSensitivity: MEDIUM

Profile

A Profile object can be created at Organization, Tenant, and Workspace levels. Once created, a profile can be attached at its own level or down the hierarchy at Organization, Tenant, Workspace and Groups levels. Once attached, all the configurations provided in the profile and compatible with the attachment point will be applied, the others will be ignored.

FieldDescriptionValidation Rule

deletionProtectionEnabled

bool
When set, prevents the resource from being deleted. In order to delete the resource this property needs to be set to false first.

defaults

tetrateio.api.tsb.profile.v2.ProfileConfig
Defaults section of the profile is meant for configurations which are allowed to be overwritten by subsequent profiles or by user defined configurations in the attached resources.

mandates

tetrateio.api.tsb.profile.v2.ProfileConfig
Mandates section of the profile is meant for configurations which can't be relaxed.

ProfileConfig

ProfileConfig holds the configuration objects that can be used as defaults or mandates.

FieldDescriptionValidation Rule

authenticationSettings

tetrateio.api.tsb.security.v2.AuthenticationSettings
Authentication settings is used to set workload-to-workload traffic and end-user/origin authentication configuration. This will be moved under a security section in the future.

wafSettings

tetrateio.api.tsb.security.v2.WAFSettings
WAF settings is used to set firewall rules. The WAF rules configured here only apply to workloads, not gateways. This will be moved under a security section in the future.

wasmExtensions

List of tetrateio.api.tsb.types.v2.WasmExtensionAttachment
Wasm Extensions specifies all the WasmExtensions assigned to this profile with the specific configuration for each extension. The WASM extensions configured here only apply to workloads, not gateways. This will be moved under a security section in the future.

unsetFields

List of string
Unset fields specify fields that must not have any value. In Mandates, fields in this list must remain unset, even if subsequent evaluated Profile Mandates define them. In Defaults, fields in this list are removed if defined in previously evaluated Profile Defaults. Items in this list are dot-separated paths to the fields, relative to the root of ProfileConfig. Field names are in camelCase, as in JSON/YAML. Paths that navigate lists or maps unset the sub-path for all elements. For example:

  • "traffic.outbound.reachability.hosts"
  • "traffic.inbound.resilience.meshTimeout.maxConnectionDuration"

repeated = {
  items: {string:{min_len:1}}
}

traffic

tetrateio.api.tsb.profile.v2.TrafficSettings
Traffic settings for proxy workloads. Proxy workloads without a specific traffic group will inherit these settings.

AuthenticationSettings

Configuration for connection authentication parameters. This allows the enforcement of mutual TLS connections to upstream services that do not have a sidecar. This ensures that gateways or mesh workloads do not communicate in plain text with services outside the mesh.

FieldDescriptionValidation Rule

trafficMode

tetrateio.api.tsb.profile.v2.AuthenticationSettings.AuthenticationMode
If set to REQUIRED, client sidecars under this configuration will be configured to initiate mTLS connections using mesh-generated client certificates to services that do not have a sidecar injected.

ClientTLSSettings

Configure TLS parameters for the client

FieldDescriptionValidation Rule

mode

tetrateio.api.tsb.profile.v2.TLSMode
Set this to DISABLED to disable TLS (not recommended from the security perspective), SIMPLE for one-way TLS and MUTUAL for mutual TLS (where client is required to present its certificate as well)

files

tetrateio.api.tsb.profile.v2.TLSFileSource oneof _tls_key_source
TLS key source from files.

secretName

string oneof _tls_key_source
TLS key source from a Kubernetes Secret. This is applicable for gateway workloads.

subjectAltNames

List of string
Subject alternative names is the list of names that are accepted as service name as part of TLS handshake

DownstreamResilienceSettings

DownstreamResilienceSettings control the reliability knobs in Envoy when accepting inbound connections.

FieldDescriptionValidation Rule

connectionPool

tetrateio.api.tsb.profile.v2.DownstreamResilienceSettings.ConnectionPoolSettings
Configures tolerance and other settings for TCP/HTTP connections to the service.

meshTimeout

tetrateio.api.tsb.profile.v2.DownstreamResilienceSettings.MeshTimeout
Configures the max connection and stream durations for HTTP and TCP connections. This applies to the inbound connections at the Sidecars and Gateways coming from a mesh-internal service.

ConnectionPoolSettings

Connection pool settings for downstream connections.

FieldDescriptionValidation Rule

tcp

tetrateio.api.tsb.profile.v2.DownstreamResilienceSettings.ConnectionPoolSettings.TCP
TCP connection pool settings

TCP

TCP Settings for inbound requests.

FieldDescriptionValidation Rule

keepAlive

tetrateio.api.tsb.profile.v2.TcpKeepAlive
Keep Alive Settings.

MeshTimeout

Connection and Stream timeout settings for the mesh. These apply to the inbound connections at the Sidecars and Gateways.

FieldDescriptionValidation Rule

maxConnectionDuration

google.protobuf.Duration
This specifies the duration of time after which a downstream and upstream connection will be drained and/or closed, starting from when it was first established. If there are no active streams, the connection will be closed. If there are any active streams, the drain sequence will kick-in, and the connection will be force-closed after the drain period. The default value of max connection duration is 0 or unlimited, which means that the connections will never be closed due to aging. This setting applies to the entire HTTP connection and all streams (HTTP/2 and HTTP/3) the connection carries.

maxStreamDuration

google.protobuf.Duration
The max stream duration is the maximum time that a stream’s lifetime will span.

maxDownstreamConnectionDuration

google.protobuf.Duration
The maximum duration of a TCP connection. The duration is defined as the period since a connection was established. If not set, there is no max duration. When max_downstream_connection_duration is reached the connection will be closed. This can be used alongside with max_connection_duration.

proxyType

tetrateio.api.tsb.profile.v2.ProxyType
Specifies the type of proxy to which to apply the mesh timeout settings. The default is to apply the settings to both Gateways and Sidecars.

enum = {
  defined_only: true
}

ExternalRateLimitServiceSettings

Configuration for ratelimiting using an external ratelimit server The ratelimit server must expose Envoy's Rate Limit Service gRPC API.

If the rate limit service is called, and the response for any of the descriptors is over limit, a 429 response is returned. The rate limit filter also sets the x-envoy-ratelimited header.

If there is an error in calling rate limit service or rate limit service returns an error and failure_mode_deny is set to true, a 500 response is returned.

FieldDescriptionValidation Rule

domain

string
REQUIRED
The rate limit domain to use when calling the rate limit service. Ratelimit settings are namespaced to a domain.

string = {
  min_bytes: 1
}

failClosed

bool oneof __fail_closed
If the rate limit service is unavailable, the request will fail if failClosed is set to true. Defaults to false.

rateLimitServerUri

string
REQUIRED
The URI at which the external rate limit server can be reached.

string = {
  min_bytes: 1
}

rules

List of tetrateio.api.tsb.profile.v2.ExternalRateLimitServiceSettings.RateLimitRule
REQUIRED
A set of rate limit rules. Each rule describes a list of dimension to match on. Once matched, a list of descriptors are sent to the external rate limit server

repeated = {
  min_items: 1
}

timeout

google.protobuf.Duration
The timeout in seconds for the external rate limit server RPC. Defaults to 0.020 seconds (20ms). Traffic will not be allowed to the destination if failClosed is set to true and the request to the rate limit server times out.

tls

tetrateio.api.tsb.profile.v2.ClientTLSSettings
Configure TLS parameters to be used when connecting to the external rate limit server. By default, the client will not validate the certificates it is presented with.

RateLimitDimension

RateLimitDimension is a set of conditions to match HTTP requests Once the conditions are satisfied, corresponding descriptors (set of keys and values) are emitted and sent to the external rate limit server. The server is expected to make a rate limit decision based on these descriptors. Please go through the Envoy RateLimit descriptor to get more information on descriptors

FieldDescriptionValidation Rule

sourceCluster

tetrateio.api.tsb.profile.v2.ExternalRateLimitServiceSettings.RateLimitDimension.SourceCluster oneof _dimension_specifier
Rate limit on source envoy cluster.

destinationCluster

tetrateio.api.tsb.profile.v2.ExternalRateLimitServiceSettings.RateLimitDimension.DestinationCluster oneof _dimension_specifier
Rate limit on destination envoy cluster.

remoteAddress

tetrateio.api.tsb.profile.v2.ExternalRateLimitServiceSettings.RateLimitDimension.RemoteAddress oneof _dimension_specifier
Rate limit on remote address of client.

requestHeaders

tetrateio.api.tsb.profile.v2.ExternalRateLimitServiceSettings.RateLimitDimension.RequestHeaders oneof _dimension_specifier
Rate limit on the value of certain request headers.

headerValueMatch

tetrateio.api.tsb.profile.v2.ExternalRateLimitServiceSettings.RateLimitDimension.HeaderValueMatch oneof _dimension_specifier
Rate limit on the existence of certain request headers.

DestinationCluster

Emit descriptor entry - a key-value pair of the form ("destination_cluster", "\<routed target cluster\>") where destination_cluster is the destination envoy cluster to which traffic is bound to.

HeaderValueMatch

Emit descriptor entry - a key-value pair of the form ("header_match", "\<descriptor_value\>"), where descriptor_value is a user specified value corresponding to a header match event.

FieldDescriptionValidation Rule

headers

map<string, tetrateio.api.tsb.profile.v2.StringMatch>
REQUIRED
Specifies a set of headers that the rate limit action should match on. The action will check the request’s headers against all the specified headers in the config. A match will happen if all the headers in the config are present in the request with the same values (or based on presence if the value field is not in the config). The header keys must be lowercase and use hyphen as the separator, e.g. x-request-id.

map = {
  min_pairs: 1
}

descriptorValue

string
REQUIRED
The value to use in the descriptor entry.

string = {
  min_bytes: 1
}

dontMatch

bool oneof __dont_match
If set to true, the condition will be met when the header value does not match. Default value is false.

RemoteAddress

Emit descriptor entry - a key-value pair of the form ("remote_address", "\<trusted address from x-forwarded-for\>")

RequestHeaders

Emit descriptor entry - a key-value pair of the form ("\<descriptor_key\>", "\<header_value_queried_from_header\>") where descriptor_key is a user specified key to emit when the HTTP header is seen.

FieldDescriptionValidation Rule

headerName

string
REQUIRED
The header name to be queried from the request headers. The header’s value is used to populate the value of the descriptor entry for the descriptor_key.

string = {
  min_bytes: 1
}

descriptorKey

string
REQUIRED
The key to use in the descriptor entry.

string = {
  min_bytes: 1
}

SourceCluster

Emit descriptor entry - a key-value pair of the form ("source_cluster", "\<local service cluster\>") where source_cluster is the source envoy cluster (corresponding to the --service-cluster flag value set by Istio).

RateLimitRule

FieldDescriptionValidation Rule

dimensions

List of tetrateio.api.tsb.profile.v2.ExternalRateLimitServiceSettings.RateLimitDimension
REQUIRED
A list of dimensions that are to be applied for this rate limit configuration. Order matters as the dimensions are processed sequentially and the descriptor is composed by appending descriptor entries in that sequence. If the condition for a dimension is not satisfied and cannot append a descriptor entry, no descriptor list is generated for the entire setting.

repeated = {
  min_items: 1
}

FailoverSettings

Failover settings for all proxies connecting to a host exposed in this workspace/organization based on the settings definition scope. Note that this is a server side setting.

FieldDescriptionValidation Rule

topologyChoice

tetrateio.api.tsb.profile.v2.FailoverSettings.TopologyChoice
TopologyChoice specifies the topology preference for traffic priority. If not specified, the default value is CLUSTER. If failoverPriority is specified then this value is ignored.

enum = {
  defined_only: true
}

failoverPriority

List of string
FailoverPriority specifies the failover priority for traffic. FailoverPriority is an ordered list of labels used to sort endpoints to do priority based load balancing. This is to support traffic failover across different groups of endpoints. Internally these labels will be matched on both the client and endpoints to determine the priorities for the respective endpoints based on clients. Note: For a label to be considered for match, the previous labels must match, i.e. nth label would be considered matched only if first n-1 labels match. If for a particular client-endpoint pair, all the n labels match, the endpoint will be considered P(0).bool If first n-1 labels match, the endpoint will be considered P(1) and so on.

For getting the labels to be populated on the endpoints generated by the TSB for multicluster and eastwest scenario, you will need to label the kubernetes service of your gateway or east-west exposed service using a label with prefix failover.tetrate.io/. For example failover.tetrate.io/version=v1 should be the label present on the kubernetes service of remote gateway or exposed service for east west traffic.

Example of failoverPriority using these labels:

failoverPriority:
- "failover.tetrate.io/version=v1"
- "failover.tetrate.io/domain"

Another way to label the endpoints for eastwest scenario is to create a ServiceRoute object for the service and specify the labels in the ServiceRoute object. If there is any pod with such label present in the remote cluster, the endpoints for it will have these labels and thus it could be used in failoverPriority API.

For example: Suppose if one of your clusters has service reviews only with version v1 and a second cluster with reviews only with version v2, Then use the below serviceroute object to populate service labels to the endpoints dynamically:

apiVersion: traffic.tsb.tetrate.io/v2
kind: ServiceRoute
metadata:
name: reviews
group: t1
workspace: w1
tenant: mycompany
organization: myorg
spec:
service: ns1/reviews.ns1.svc.cluster.local
subsets:
- name: v1
labels:
version: v1
- name: v2
labels:
version: v2

Example of failoverPriority using these labels:

failoverPriority:
- "version=v1"
- "failover.tetrate.io/domain"

repeated = {
  items: {string:{min_len:1}}
}

regionalFailover

List of tetrateio.api.tsb.profile.v2.RegionalFailover
Locality routing settings for all gateways in the Workspace/Organization for which this is defined.

Explicitly specify the region traffic will land on when endpoints in the local region become unhealthy. Should be used together with OutlierDetection to detect unhealthy endpoints. Note: if no OutlierDetection specified, this will not take effect.

HTTPRetry

HTTPRetry defines the parameters for retrying API calls to a service.

FieldDescriptionValidation Rule

attempts

int32 oneof __attempts
REQUIRED
Number of retries for a given request. The interval between retries will be determined automatically (25ms+).

Actual number of retries attempted depends on the httpReqTimeout. google.protobuf.Int32Value attempts = 1 [(validate.rules).int32.gte = 0, (google.api.field_behavior) = REQUIRED];

The above field is defined as optional to allow users to specify 0 attempts (zero value) when using it from config profiles.

int32 = {
  gte: 0
}

perTryTimeout

google.protobuf.Duration
Timeout per retry attempt for a given request. format: 1h/1m/1s/1ms. MUST BE >=1ms.

retryOn

string
Specifies the conditions under which retry takes place. One or more policies can be specified using a ‘,’ delimited list. See the retry policies and gRPC retry policies for more details.

string = {
  pattern: ^$|^(5xx|gateway-error|reset|connect-failure|envoy-ratelimited|retriable-4xx|refused-stream|retriable-status-codes|retriable-headers|cancelled|deadline-exceeded|internal|resource-exhausted|unavailable)(,(5xx|gateway-error|reset|connect-failure|envoy-ratelimited|retriable-4xx|refused-stream|retriable-status-codes|retriable-headers|cancelled|deadline-exceeded|internal|resource-exhausted|unavailable))*$
}

InboundTrafficSetting

Configuration for inbound traffic.

FieldDescriptionValidation Rule

rateLimiting

tetrateio.api.tsb.profile.v2.RateLimiting
Configuration for rate limiting requests. Only applies to sidecars in traffic group today.

resilience

tetrateio.api.tsb.profile.v2.DownstreamResilienceSettings
Resiliency configuration for inbound connections.

failoverSettings

tetrateio.api.tsb.profile.v2.FailoverSettings
Failover settings apply to all clients accessing the hostname defined in this section. While the configuration is set by the user on the server/service side, TSB ensures that client proxies implement these settings.

LoadBalancerSettings

Defines Load Balancing policies to be applied on the client requests.

FieldDescriptionValidation Rule

simple

tetrateio.api.tsb.profile.v2.LoadBalancerSettings.SimpleLB oneof _lb_policy
Use standard load balancing algorithms that require no tuning.

enum = {
  defined_only: true
}

consistentHash

tetrateio.api.tsb.profile.v2.LoadBalancerSettings.ConsistentHashLB oneof _lb_policy
Use consistent hash load balancing which can provide soft session affinity.

ConsistentHashLB

Consistent Hash-based load balancing can be used to provide soft session affinity based on HTTP headers, cookies or other properties. The affinity to a particular destination host may be lost when one or more hosts are added/removed from the destination service.

Note: consistent hashing is less reliable at maintaining affinity than common "sticky sessions" implementations, which often encode a specific destination in a cookie, ensuring affinity is maintained as long as the backend remains. With consistent hash, the guarantees are weaker; any host addition or removal can break affinity for 1/backends requests.

Warning: consistent hashing depends on each proxy having a consistent view of endpoints. This is not the case when locality load balancing is enabled. Locality load balancing and consistent hash will only work together when all proxies are in the same locality, or a high level load balancer handles locality affinity.

FieldDescriptionValidation Rule

httpHeaderName

string oneof _hash_key
Hash based on a specific HTTP header.

httpCookie

tetrateio.api.tsb.profile.v2.LoadBalancerSettings.ConsistentHashLB.HTTPCookie oneof _hash_key
Hash based on HTTP cookie.

useSourceIp

bool oneof _hash_key
Hash based on the source IP address. This is applicable for both TCP and HTTP connections.

httpQueryParameterName

string oneof _hash_key
Hash based on a specific HTTP query parameter.

ringHash

tetrateio.api.tsb.profile.v2.LoadBalancerSettings.ConsistentHashLB.RingHash oneof _hash_algorithm
The ring/modulo hash load balancer implements consistent hashing to backend hosts.

maglev

tetrateio.api.tsb.profile.v2.LoadBalancerSettings.ConsistentHashLB.MagLev oneof _hash_algorithm
The Maglev load balancer implements consistent hashing to backend hosts.

HTTPCookie

Describes a HTTP cookie that will be used as the hash key for the Consistent Hash load balancer. If the cookie is not present, it will be generated.

FieldDescriptionValidation Rule

name

string
REQUIRED
Name of the cookie.

string = {
  min_len: 1
}

path

string
Path to set for the cookie.

ttl

google.protobuf.Duration
REQUIRED
Lifetime of the cookie.

duration = {
  required: true
}

MagLev

Implements consistent hashing to upstream hosts. It can be used as a drop in replacement for RingHash. It has higher speed than RingHash with faster hash table lookups. Please refer https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/load_balancing/load_balancers#maglev

FieldDescriptionValidation Rule

tableSize

uint32
REQUIRED
The table size for Maglev hashing. This helps in controlling the disruption when the backend hosts change. Increasing the table size reduces the amount of disruption.

uint32 = {
  gte: 1
}

RingHash

Implements consistent hashing to upstream hosts. Each upstream host is mapped onto a circle (ring) by hashing its address, each request is then routed using some hash property of the request. Please refer https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/load_balancing/load_balancers#ring-hash

FieldDescriptionValidation Rule

minimumRingSize

uint32
The minimum number of virtual nodes to use for the hash ring. Defaults to 1024. Larger ring sizes result in more granular load distributions. If the number of hosts in the load balancing pool is larger than the ring size, each host will be assigned a single virtual node.

OutboundTrafficSetting

FieldDescriptionValidation Rule

reachability

tetrateio.api.tsb.profile.v2.ReachabilitySettings
The set of services and hosts accessed by a workload (and hence its sidecar) in the mesh. Defining the set of services accessed by a workload (i.e. its dependencies) in advance reduces the memory and CPU consumption both the Istio control plane and the individual Envoy proxy workloads in the data plane.

egress

tetrateio.api.tsb.profile.v2.OutboundTrafficSetting.EgressGateway
Specifies the details of the egress proxy to which traffic to services that are not part to the mesh should be forwarded to from the proxy workloads. If not specified, the proxy workloads will send this traffic directly to the IP requested by the application.

upstreamTrafficSettings

List of tetrateio.api.tsb.profile.v2.UpstreamTrafficSettings
List of hosts and the associated traffic settings to be used by the clients sending traffic to them.

EgressGateway

EgressGateway specifies the gateway where traffic external to the mesh will be redirected.

FieldDescriptionValidation Rule

host

string
REQUIRED
Specifies the egress gateway hostname. Must be in \<namespace\>/\<fqdn\> format.

string = {
  pattern: ^[^/]+/[^/]+$
}

RateLimitSettings

Configuration for ratelimiting HTTP/gRPC requests This has a list of rate limit rules that can be configured. With each rule a list of dimensions can be defined. A request counts towards the limit if all of the dimensions match the attributes of the request. When the matched requests exceed the limit, a 429 response is returned.

FieldDescriptionValidation Rule

rules

List of tetrateio.api.tsb.profile.v2.RateLimitSettings.RateLimitRule
REQUIRED
A list of rules for ratelimiting. Each rule defines a list of dimensions to match on and the rate limit value for the rule. Each rule is independant of the other.

repeated = {
  min_items: 1
}

failClosed

bool oneof __fail_closed
If the rate limit service is unavailable, the request will fail if failClosed is set to true. Defaults to false.

timeout

google.protobuf.Duration
The timeout in seconds for the rate limit server RPC. Defaults to 0.020 seconds (20ms). Traffic will not be allowed to the destination if failClosed is set to true and the request to the rate limit server times out.

RateLimitDimension

RateLimitDimension is a condition to match HTTP requests that should be rate limited.

FieldDescriptionValidation Rule

remoteAddress

tetrateio.api.tsb.profile.v2.RateLimitSettings.RateLimitDimension.RemoteAddress oneof _dimension_specifier
Rate limit on the remote address of client.

header

tetrateio.api.tsb.profile.v2.RateLimitSettings.RateLimitDimension.Header oneof _dimension_specifier
Rate limit on certain HTTP headers. Special header names such as :path and :method can also be used.

Header

RateLimit based on certain headers

FieldDescriptionValidation Rule

name

string
REQUIRED
Name of the header to match on.

string = {
  min_len: 1
}

value

tetrateio.api.tsb.profile.v2.StringMatch
Value of the header to match on if matching on a specific value. If not specified, ratelimit on every unique value of the header.

dontMatch

bool oneof __dont_match
If set to true, the condition will be met when the header value does not match. Default value is false.

RemoteAddress

RateLimit based on the client's remote address, extracted from the trusted X-Forwarded-For header.

FieldDescriptionValidation Rule

value

string
REQUIRED
Ratelimit on a specific remote address. If the value is set to "*", ratelimit on every unique remote address.

string = {
  min_len: 1
}

RateLimitRule

RateLimitRule is the block to define each internal ratelimit configuration.

FieldDescriptionValidation Rule

dimensions

List of tetrateio.api.tsb.profile.v2.RateLimitSettings.RateLimitDimension
REQUIRED
A list of dimensions to define each ratelimit rule. Requests count towards the ratelimit value only when each and every condition in a dimension is matched for a given HTTP request.

repeated = {
  min_items: 1
}

limit

tetrateio.api.tsb.profile.v2.RateLimitSettings.RateLimitValue
REQUIRED
The ratelimit value that will be configured for the above rules.

message = {
  required: true
}

RateLimitValue

RateLimitValue specifies the values that will be used to determine the rate limit.

FieldDescriptionValidation Rule

requestsPerUnit

uint32 oneof __requests_per_unit
REQUIRED
Specifies the value of the rate limit.

unit

tetrateio.api.tsb.profile.v2.RateLimitSettings.RateLimitValue.Unit
REQUIRED
Specifies the unit of time for rate limit.

enum = {
  defined_only: true
}

RateLimiting

Configuration for ratelimiting HTTP/gRPC requests can be rate limited based on a variety of attributes in the request such as headers (including cookies), URL path/prefixes, client remote address etc.

FieldDescriptionValidation Rule

settings

tetrateio.api.tsb.profile.v2.RateLimitSettings oneof _ratelimit_specifier
Use Envoy and TSB's rateLimit server for ratelimiting HTTP Requests

externalService

tetrateio.api.tsb.profile.v2.ExternalRateLimitServiceSettings oneof _ratelimit_specifier
Configure ratelimiting using an external ratelimit server. This configuration only configures Envoy's ratelimit filters The user is expected to provision and configure their own external ratelimit server with the appropriate ratelimit values

ReachabilitySettings

ReachabilitySettings define the set of services and hosts accessed by a workload (and hence its sidecar) in the mesh. Defining the set of services accessed by a workload (i.e. its dependencies) in advance reduces the memory and CPU consumption both the Istio control plane and the individual Envoy proxy workloads in the data plane.

FieldDescriptionValidation Rule

mode

tetrateio.api.tsb.profile.v2.ReachabilitySettings.Mode
A short cut for specifying the set of services accessed by the workload.

hosts

List of string
When the mode is CUSTOM, hosts specify the set of services that the sidecar should be able to reach. Must be in the \<namespace\>/\<fqdn\> format.

  • ./* indicates all services in the namespace where the sidecar resides.

  • ns1/* indicates all services in the ns1 namespace.

  • ns1/svc1.com indicates svc1.com service in ns1 namespace.

  • */svc1.com indicates svc1.com service in any namespace.

RegionalFailover

Specify the traffic failover policy across regions. Since zone and sub-zone failover is supported by default this only needs to be specified for regions when the operator needs to constrain traffic failover so that the default behavior of failing over to any endpoint globally does not apply. This is useful when failing over traffic across regions would not improve service health or may need to be restricted for other reasons like regulatory controls.

FieldDescriptionValidation Rule

from

string
Originating region.

to

string
Destination region the traffic will fail over to when endpoints in the 'from' region become unhealthy.

StringMatch

Describes how to match a given string in HTTP headers. Match is case-sensitive.

FieldDescriptionValidation Rule

exact

string oneof _match_type
Exact string match.

prefix

string oneof _match_type
Prefix-based match.

regex

string oneof _match_type
ECMAscript style regex-based match.

TLSFileSource

TLSFileSource is used to load the keys and certificates from files accessible to the workload

FieldDescriptionValidation Rule

clientCertificate

string oneof __client_certificate
Certificate file to authenticate the client. This is mandatory for mutual TLS and must not be specified for simple (one-way) TLS

privateKey

string oneof __private_key
Private key file associated with the client certificate. This is mandatory for mutual TLS and must not be specified for simple TLS

caCertificates

string oneof __ca_certificates
File containing CA certificates to verify the certificates presented by the server. This is mandatory for both simple and mutual TLS. Here are some common paths for the system CA bundle on Linux and can be specified here if the server certificate is signed by a well known authority, already part of the system CA bundle on the host - /etc/ssl/certs/ca-certificates.crt (Debian/Ubuntu/Gentoo etc.) /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem (CentOS/RHEL 7) /etc/pki/tls/certs/ca-bundle.crt (Fedora/RHEL 6)

TcpKeepAlive

FieldDescriptionValidation Rule

probes

google.protobuf.UInt32Value
The total number of unacknowledged probes to send before deciding the connection is dead. Default is to use the OS level configuration, Linux defaults to 9.

idleTime

google.protobuf.UInt32Value
The number of seconds a connection needs to be idle before keep-alive probes start being sent. Default is to use the OS level configuration, Linux defaults to 7200s.

interval

google.protobuf.UInt32Value
The number of seconds between keep-alive probes. Default is to use the OS level configuration, Linux defaults to 75s.

TrafficSettings

Traffic settings is used to configure inbound and outbound traffic of proxy workloads belonging to traffic groups or workspaces via profiles. When applied to a traffic group, missing fields will inherit values from the workspace-wide setting if any.

FieldDescriptionValidation Rule

inbound

tetrateio.api.tsb.profile.v2.InboundTrafficSetting
Configures inbound traffic. Applicable when service acts as a server.

outbound

tetrateio.api.tsb.profile.v2.OutboundTrafficSetting
Configures outbound traffic. Applicable when service acts as a client.

UpstreamResilienceSettings

UpstreamResilienceSettings controls the reliability knobs for client connections to the upstream hosts.

FieldDescriptionValidation Rule

connectionPool

tetrateio.api.tsb.profile.v2.UpstreamResilienceSettings.ConnectionPoolSettings
Configures tolerance and other settings for TCP/HTTP connections to the service.

circuitBreakerSensitivity

tetrateio.api.tsb.profile.v2.UpstreamResilienceSettings.Sensitivity
Circuit breakers in Envoy are applied per endpoint in a load balancing pool. By default, circuit breakers are disabled. If set, the sensitivity level determines the maximum number of consecutive failures that Envoy will tolerate before ejecting an endpoint from the load balancing pool.

enum = {
  defined_only: true
}

outlierDetection

tetrateio.api.tsb.profile.v2.UpstreamResilienceSettings.OutlierDetection
Outlier detection settings for the upstream host when custom mode is used.

ConnectionPoolSettings

Connection pool settings for the upstream host.

FieldDescriptionValidation Rule

http

tetrateio.api.tsb.profile.v2.UpstreamResilienceSettings.ConnectionPoolSettings.HTTP
HTTP connection pool settings

tcp

tetrateio.api.tsb.profile.v2.UpstreamResilienceSettings.ConnectionPoolSettings.TCP
TCP connection pool settings

HTTP

HTTP Settings for outbound requests.

FieldDescriptionValidation Rule

requestTimeout

google.protobuf.Duration
Timeout for HTTP requests. format: 1h/1m/1s/1ms. MUST BE >=1ms. Disabled if not set.

retries

tetrateio.api.tsb.profile.v2.HTTPRetry
Retry policy for HTTP requests. Disabled if not set.

maxRequests

uint32 oneof __max_requests
Maximum number of active requests to the service. Applicable to both HTTP/1.1 and HTTP2. Default 0, meaning "unlimited", up to 2^32 - 1.

maxRequestsPerConnection

uint32 oneof __max_requests_per_connection
Maximum number of requests per connection to the service. If set to 1, it disables keep alive. Default 0, meaning "unlimited", up to 2^29.

TCP

TCP Settings for outbound requests.

FieldDescriptionValidation Rule

keepAlive

tetrateio.api.tsb.profile.v2.TcpKeepAlive
Keep Alive Settings.

maxConnections

uint32 oneof __max_connections
Maximum number of HTTP1 /TCP connections to the service. Default 0, meaning "unlimited", up to 2^32 - 1.

connectTimeout

google.protobuf.Duration
TCP connection timeout. format: 1h/1m/1s/1ms. MUST BE >=1ms. Default is 10s.

duration = {
  gte: {nanos:1000000}
}

OutlierDetection

Outlier detection settings for the upstream host.

FieldDescriptionValidation Rule

consecutiveGatewayFailure

google.protobuf.UInt32Value
The number of consecutive gateway failures (502, 503, 504 status codes) before a consecutive gateway failure ejection occurs. Defaults to circuitBreakerSensitivity of MEDIUM(5) in TSB.

enforcingConsecutiveGatewayFailure

google.protobuf.UInt32Value
The percentage of a host to be ejected when an outlier status is detected through consecutive gateway failures. This setting can be used to disable ejection or to ramp it up slowly. Defaults to 100 in TSB.

uint32 = {
  lte: 100
}

consecutive5xx

google.protobuf.UInt32Value
The number of consecutive server-side error responses (for HTTP traffic, 5xx responses; for TCP traffic, connection failures; for Redis, failure to respond PONG; etc.) before a consecutive 5xx ejection occurs. Defaults to 5.

enforcingConsecutive5xx

google.protobuf.UInt32Value
The percentage of a host to be actually ejected when an outlier status is detected through consecutive 5xx. This setting can be used to disable ejection or to ramp it up slowly. Defaults to 0 in TSB.

uint32 = {
  lte: 100
}

splitExternalLocalOriginErrors

bool oneof __split_external_local_origin_errors
Determines whether to distinguish local origin failures from external errors. Local Origin Failures are errors that occur within the Envoy process itself, before the request is actually sent to the upstream host. example of these are connection timeout, TCP reset etc. External errors are errors that occur after the request is sent to the upstream host. example of these are 5xx errors, connection refused etc. If set to true, consecutiveLocalOriginFailure and enforcingConsecutiveLocalOriginFailure will be taken into account. Defaults to false.

The number of consecutive locally originated failures before ejection occurs. Defaults to 5. Parameter takes effect only when splitExternalLocalOriginErrors is set to true.

consecutiveLocalOriginFailure

google.protobuf.UInt32Value

enforcingConsecutiveLocalOriginFailure

google.protobuf.UInt32Value
The percentage of a host to be actually ejected when an outlier status is detected through consecutive locally originated failures. This setting can be used to disable ejection or to ramp it up slowly. Defaults to 100. Parameter takes effect only when splitExternalLocalOriginErrors is set to true.

uint32 = {
  lte: 100
}

interval

google.protobuf.Duration
The time interval between ejection analysis sweeps. This can result in both new ejections as well as hosts being returned to service. Defaults to 10000ms or 10s.

duration = {
  gt: {nanos:0}
}

baseEjectionTime

google.protobuf.Duration
The base time that a host is ejected for. The real time is equal to the base time multiplied by the number of times the host has been ejected. Defaults to 30000ms or 30s.

duration = {
  gt: {nanos:0}
}

maxEjectionTime

google.protobuf.Duration
The maximum time that a host is ejected for. If not specified, the default value (300000ms or 300s) or baseEjectionTime value is applied, whatever is larger.

duration = {
  gt: {nanos:0}
}

maxEjectionPercent

google.protobuf.UInt32Value
The maximum % of an upstream cluster that can be ejected due to outlier detection. Defaults to 100%.

uint32 = {
  lte: 100
}

UpstreamTrafficSettings

Traffic settings for the clients that are downstreams to the defined upstream hosts.

FieldDescriptionValidation Rule

hosts

List of string
List of hosts for which the settings will be created. Can contain wildcard hosts. The host should be a service from the service registry or a host declared by ServiceEntries.

repeated = {
  items: {string:{min_len:1}}
}

settings

tetrateio.api.tsb.profile.v2.UpstreamTrafficSettings.Settings
A single setting to be applied to all the clients connecting to the upstream hosts.

Settings

Traffic settings to be applied to the clients of the upstream hosts.

FieldDescriptionValidation Rule

resilience

tetrateio.api.tsb.profile.v2.UpstreamResilienceSettings
Resilience settings for the clients.

loadBalancer

tetrateio.api.tsb.profile.v2.LoadBalancerSettings
Load balancing settings for the clients.

authentication

tetrateio.api.tsb.profile.v2.AuthenticationSettings
Configuration for connection authentication parameters.

AuthenticationMode

AuthenticationMode configures whether to initiate only mutual TLS connections or to allow plaintext traffic as well.

FieldNumberDescription

UNSET

0

Default is UNSET.

OPTIONAL

1

Accept both plaintext and mTLS authenticated connections.

REQUIRED

2

Always initiate mutual TLS authenticated connections, and fail if the upstream does not support it.

TopologyChoice

TopologyChoice specifies the topology preference for traffic priority.

FieldNumberDescription

NONE

0

Inherit from parent if possible. Otherwise treated as CLUSTER.

CLUSTER

1

Prefer traffic to stay in the cluster as much as possible.

LOCALITY

2

Prefer traffic to stay in the region/zone/subzone as much as possible irrespective of the cluster.

SimpleLB

Standard load balancing algorithms that require no tuning.

FieldNumberDescription

UNSPECIFIED

0

No load balancing algorithm has been specified by the user. An appropriate default will be used.

RANDOM

2

The random load balancer selects a random healthy host. The random load balancer generally performs better than round robin if no health checking policy is configured.

PASSTHROUGH

3

This option will forward the connection to the original IP address requested by the caller without doing any form of load balancing. This option must be used with care. It is meant for advanced use cases. Refer to Original Destination load balancer in Envoy for further details.

ROUND_ROBIN

4

A basic round robin load balancing policy. This is generally unsafe for many scenarios (e.g. when enpoint weighting is used) as it can overburden endpoints. In general, prefer to use LEAST_REQUEST as a drop-in replacement for ROUND_ROBIN.

LEAST_REQUEST

5

The least request load balancer spreads load across endpoints, favoring endpoints with the least outstanding requests. This is generally safer and outperforms ROUND_ROBIN in nearly all cases. Prefer to use LEAST_REQUEST as a drop-in replacement for ROUND_ROBIN.

ProxyType

ProxyType defines the type of a proxy within the service mesh.

This enum is used to apply configurations based on the type of the proxy.

FieldNumberDescription

ANY

0

ANY is the default proxy type that represents both sidecar, and gateway proxies. Use this value to apply configurations to both sidecars and gateways.

SIDECAR

1

SIDECAR represents a sidecar proxy that runs alongside an application. Use this value to apply configurations only to the sidecars.

GATEWAY

2

GATEWAY represents a gateway proxy that runs standalone and, acts as an entry/exit point into/out of the service mesh. Use this value to apply configurations only to the gateways.

Unit

Units of time.

FieldNumberDescription

UNKNOWN

0

SECOND

1

MINUTE

2

HOUR

3

DAY

4

Mode

A short cut for defining the common reachability patterns

FieldNumberDescription

UNSET

0

Inherit from parent if possible. Otherwise treated as CLUSTER.

NAMESPACE

1

The workload may talk to any service in its own namespace.

GROUP

2

The workload may talk to any service in the traffic group.

WORKSPACE

3

The workload may talk to any service in the workspace.

CLUSTER

4

The workload may talk to any service in the cluster.

CUSTOM

5

The workload may talk to services defined explicitly.

TLSMode

Describes how authentication is performed as part of establishing TLS connection

FieldNumberDescription

DISABLED

0

TLS is not used and communication is in plaintext.

SIMPLE

1

Only the server is authenticated.

MUTUAL

2

Both the peers in the communication must present their certificate for TLS authentication

Sensitivity

Available sensitivity levels for the circuit breaker.

FieldNumberDescription

UNSET

0

Default values will be used.

LOW

1

Tolerate up to 20 consecutive 5xx or connection failures from an endpoint before ejecting it temporarily from the load balancing pool.

MEDIUM

2

Tolerate up to 10 consecutive 5xx or connection failures from an endpoint before ejecting it temporarily from the load balancing pool.

HIGH

3

Tolerate up to 5 consecutive 5xx or connection failures from an endpoint before ejecting it temporarily from the load balancing pool.

CUSTOM

4

When selected, the outlier detection settings must be specified in the resilience.outlierDetection field. If that field is set but the mode is not CUSTOM, those settings will be ignored.