Skip to main content
logoTetrate Service BridgeVersion: next

Common Object Types

Definition of objects shared by different APIs.

ConfigGenerationMetadata

ConfigGenerationMetadata allows to setup extra metadata that will be added in the final Istio generated configurations. Like new labels or annotations. Defining the config generation metadata in tenancy resources (like organization, tenant, workspace or groups) works as default values for those configs that belong to it. Defining same config generation metadata in configuration resources (like ingress gateways, service routes, etc.) will replace the ones defined in the tenancy resources.

FieldDescriptionValidation Rule

labels

map<string, string>
Set of key value paris that will be added into the metadata.labels field of the Istio generated configurations.

annotations

map<string, string>
Set of key value paris that will be added into the metadata.annotations field of the Istio generated configurations.

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.types.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.types.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.

NamespaceSelector

NamespaceSelector selects a set of namespaces across one or more clusters in a tenant. Namespace selectors can be used at Workspace level to carve out a chunk of resources under a tenant into an isolated configuration domain. They can be used in a Traffic, Security, or a Gateway group to further scope the set of namespaces that will belong to a specific configuration group. Names in namespaces selector must be in the form cluster/namespace where:

  • cluster must be a cluster name or an * to mean all clusters

  • namespace must be a namespace name, an * to mean all namespaces or a prefix like ns-* to mean all those namespaces starting by ns-

FieldDescriptionValidation Rule

names

List of string
REQUIRED
Under the tenant/workspace/group:

  • */ns1 implies ns1 namespace in any cluster.

  • c1/ns1 implies ns1 namespace from c1 cluster.

  • c1/* implies all namespaces in c1 cluster.

  • */* implies all namespaces in all clusters.

  • c1/ns* implies all namespaces prefixes by ns in c1 cluster.

repeated = {
  min_items: 1
  items: {string:{pattern:^(\\*|[^/*]+)/(\\*|[^/*]+\\*?)$}}
}

PortSelector

PortSelector is the criteria for specifying if a policy can be applied to a listener having a specific port.

FieldDescriptionValidation Rule

number

uint32
REQUIRED
Port number

uint32 = {
  lte: 65535
  gte: 1
}

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.

ServiceSelector

ServiceSelector represents the match criteria to select services within a particular scope (namespace, workspace, cluster etc)

FieldDescriptionValidation Rule

serviceLabels

map<string, string>
REQUIRED
One or more labels that indicate a specific set of services within a particular scope

map = {
  min_pairs: 1
  keys: {string:{min_len:1}}
  values: {string:{min_len:1}}
}

TrafficSelector

TrafficSelector provides a mechanism to select a specific traffic flow for which this Wasm Extension will be enabled. When all the sub conditions in the TrafficSelector are satisfied, the traffic will be selected.

FieldDescriptionValidation Rule

mode

tetrateio.api.tsb.types.v2.WorkloadMode
Criteria for selecting traffic by their direction. Note that CLIENT and SERVER are analogous to OUTBOUND and INBOUND, respectively. For the gateway, the field should be CLIENT or CLIENT_AND_SERVER. If not specified, the default value is CLIENT_AND_SERVER.

enum = {
  defined_only: true
}

ports

List of tetrateio.api.tsb.types.v2.PortSelector
Criteria for selecting traffic by their destination port. More specifically, for the outbound traffic, the destination port would be the port of the target service. On the other hand, for the inbound traffic, the destination port is the port bound by the server process in the same Pod.

If one of the given ports is matched, this condition is evaluated to true. If not specified, this condition is evaluated to true for any port.

WasmExtensionAttachment

WasmExtensionAttachment defines the WASM extension attached to this resource including the name to identify the extension and also the specific configuration that will override the global extension configuration. Only those extensions globally enabled will be considered although they can be associated to the target resources. Match configuration allows you to specify which traffic is sent through the Wasm extension. Users can select the traffic based on different workload modes and ports.

apiVersion: gateway.tsb.tetrate.io/v2
kind: IngressGateway
metadata:
name: ingress-bookinfo
group: g1
workspace: w1
tenant: mycompany
organization: myorg
spec:
workloadSelector:
namespace: ns1
labels:
app: gateway
extension:
- fqn: hello-world # fqn of imported extensions in TSB
config:
foo: bar
match:
- ports:
- number: 80
mode: CLIENT_AND_SERVER
http:
- name: bookinfo
port: 80
hostname: bookinfo.com
routing:
rules:
- route:
host: ns1/productpage.ns1.svc.cluster.local
FieldDescriptionValidation Rule

fqn

string
REQUIRED
Fqn of the extension to be executed.

string = {
  min_len: 1
}

config

google.protobuf.Struct
Configuration parameters sent to the WASM plugin execution. This configuration will overwrite the one specified globally in the extension. This config will be passed as-is to the extension. It is up to the extension to deserialize the config and use it.

match

List of tetrateio.api.tsb.types.v2.TrafficSelector
Specifies the criteria to determine which traffic is passed to WasmExtension. If a traffic satisfies any of TrafficSelectors, the traffic passes to the WasmExtension.

WorkloadSelector

WorkloadSelector selects one or more workloads in a namespace. WorkloadSelector can be used in TrafficSetting, SecuritySetting, and Gateway APIs in BRIDGED mode to scope the configuration to a specific set of workloads.

FieldDescriptionValidation Rule

namespace

string
REQUIRED
The namespace where the workload resides.

string = {
  min_len: 1
}

labels

map<string, string>
REQUIRED
One or more labels that indicate a specific set of pods/VMs in the namespace. If omitted, the TrafficSetting or SecuritySetting configuration will apply to all workloads in the namespace. Labels are required for Gateway API resources.

map = {
  min_pairs: 1
  keys: {string:{min_len:1}}
  values: {string:{min_len:1}}
}

Object

Format for all API objects in TSB as exposed in the CLI.

FieldDescriptionValidation Rule

apiVersion

string
REQUIRED
api.tsb.tetrate.io/v2, traffic.tsb.tetrate.io/v2, security.tsb.tetrate.io/v2, gateway.tsb.tetrate.io/v2, networking.istio.io/v1beta1, security.istio.io/v1beta1, etc.

string = {
  min_len: 1
}

kind

string
REQUIRED
Workspace, Cluster, Tenant, Team, User, WorkspaceSetting, Group (under traffic.tsb.tetrate.io and security.tsb.tetrate.io), TrafficSetting, SecuritySetting, etc.

string = {
  min_len: 1
}

metadata

tetrateio.api.tsb.types.v2.ObjectMeta
REQUIRED

spec

google.protobuf.Any
The API payload.

status

map<string, string>
Contains errors, tokens (in case of cluster onboarding, and other information).

ObjectMeta

Metadata associated with each API Object.

FieldDescriptionValidation Rule

name

string
Name associated with the object. The object name must be unique within the kind and the parent. For example, all workspaces under a tenant should have a unique name. Traffic groups under a workspace should have a unique name, while names are not required to be unique across traffic groups in different workspaces.

The name field must:

  1. Begin and End with a lowercase alphanumeric character.
  2. Contain only lowercase alphanumeric characters and -.
  3. Be limited to a maximum of 63 characters.

namespace

string
Applicable when using Istio objects.

tenant

string
The tenant to which the object belongs to.

workspace

string
The workspace to which the object belongs to.

group

string
The traffic/security/gateway group to which the object belongs to.

resourceVersion

string
Resource version is used internally to track propagation of resources to the data planes.

labels

map<string, string>
User specified labels to attach to the objects. This is only available for Istio resources when applying configuration in DIRECT mode. Labels applied to TSB resources will be ignored.

annotations

map<string, string>
Istio artifacts must contain 4 annotations: tsb.tetrate.io/organization, tsb.tetrate.io/tenant, tsb.tetrate.io/workspace, and one of tsb.tetrate.io/trafficGroup, tsb.tetrate.io/securityGroup, tsb.tetrate.io/gatewayGroup or tsb.tetrate.io/istioInternalGroup This is only available for Istio resources when applying configuration in DIRECT mode. Labels applied to TSB resources will be ignored.

displayName

string
User friendly name for the resource.

description

string
A description of the resource.

organization

string
The organization to which the object belongs to

application

string
The application to which the resource belongs to

api

string
The API to which the resource belongs to

service

string
The service which the resource belongs to.

telemetrySource

string
The telemetry source the resource belongs to.

fqn

string
The fully-qualified name of a resource.

IstioObjectSpec

Contains the raw type of an Istio object. This is used to generate the documentation examples when showing the serialized form of Istio direct mode resources.

FieldDescriptionValidation Rule

type

string

TypeInfo

TypeInfo provides metadata describing a message type.

FieldDescriptionValidation Rule

generatesConfig

bool
Indicates that the type has a configuration status and that it will go through several stages after creation until it is fully ready.

aggregatesStatus

bool
Indicates that the type has its status aggregated from the status of its child resources.

dependencies

List of string
If not empty, it indicates on what resources it's dependent.

lastEventXcpAccepted

bool
By setting this to true, the last expected event for the resource will be XCP_ACCEPTED, and its status will be set to READY after the event is received. This should be set in resources that need to become READY when they are accepted by XCP Central without waiting for the XCP Edges.

CreateIstioObjectRequest

Request to create an Istio Object

FieldDescriptionValidation Rule

parent

string
REQUIRED
Parent resource where the Istio Object will be created.

string = {
  min_len: 1
}

name

string
REQUIRED
The short name for the Istio Object to be created. Maximum allowed length for these objects is 60 instead of 63 as per RFC1123, as TSB appends td- prefix while storing these objects.

string = {
  min_len: 1
  max_len: 60
  pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$
}

object

tetrateio.api.tsb.types.v2.IstioObject
REQUIRED
Details of the Istio Object to be created.

message = {
  required: true
}

DeleteIstioObjectRequest

Request to delete a Istio Object.

FieldDescriptionValidation Rule

fqn

string
REQUIRED
Fully-qualified name of the IstIo Object.

string = {
  min_len: 1
}

GetIstioObjectRequest

Request to retrieve a Istio Object.

FieldDescriptionValidation Rule

fqn

string
REQUIRED
Fully-qualified name of the Istio Object.

string = {
  min_len: 1
}

IstioObject

Wrapper for Istio direct mode objects with all the details needed to add it to the TSB resource hierarchy.

FieldDescriptionValidation Rule

metadata

tetrateio.api.tsb.types.v2.IstioObject.ConfigMeta
Metadata for the Istio object

spec

google.protobuf.Any
The Istio API object

ConfigMeta

FieldDescriptionValidation Rule

apiVersion

string
REQUIRED
networking.istio.io/v1beta1, security.istio.io/v1beta1, etc.

string = {
  min_len: 1
}

kind

string
REQUIRED
VirtualService, Gateway, DestinationRule, Sidecar, etc.

string = {
  min_len: 1
}

name

string
Short name associated with the object. The object name must be unique within the kind and the parent. For example, all workspaces under a tenant should have a unique name. Traffic groups under a workspace should have a unique name, while names are not required to be unique across traffic groups in different workspaces.

namespace

string
Namespace where the Istio object applies.

labels

map<string, string>
User specified labels to attach to the object.

annotations

map<string, string>
Istio artifacts must contain 4 annotations: tsb.tetrate.io/organization, tsb.tetrate.io/tenant, tsb.tetrate.io/workspace, and one of tsb.tetrate.io/trafficGroup, tsb.tetrate.io/securityGroup, tsb.tetrate.io/gatewayGroup or tsb.tetrate.io/istioInternalGroup

ListIstioObjectsRequest

Request to list Istio Object.

FieldDescriptionValidation Rule

parent

string
REQUIRED
Parent resource to list Istio Objects from.

string = {
  min_len: 1
}

ListIstioObjectsResponse

List of Istio direct mode objects

FieldDescriptionValidation Rule

objects

List of tetrateio.api.tsb.types.v2.IstioObject

ConfigMode

The configuration mode used by a traffic, security or a gateway group.

FieldNumberDescription

BRIDGED

0

Indicates that the configurations to be added to the group will use macro APIs that automatically generate Istio APIs under the hood.

DIRECT

1

Indicates that the configurations to be added to the group will directly use Istio APIs.

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.

IdentityMatch

IdentityMatch defines the strategy for utilizing service identities during the evaluation of authorization (authz) rules. It specifies how the identity of a service or workload is verified and used in the context of authz policies. The strictness of identity verification progresses in the following order: UNKNOWN < PERMISSIVE < PEER_CERTIFICATE < SOURCE_IDENTITY.

FieldNumberDescription

UNKNOWN

0

UNKNOWN represents the default state when identityMatch is not explicitly set. In practice, it behaves identically to the PERMISSIVE mode, allowing for a flexible approach to identity verification. This mode is typically used as a fallback or when the specific identity verification strategy is undecided.

PEER_CERTIFICATE

1

PEER_CERTIFICATE mode mandates the use of Mutual TLS (mTLS) certificates for identity verification. Specifically, it utilizes the SPIFFE(Secure Production Identity Framework For Everyone) IDs presented in peer certificates as the basis for authz decision-making. This mode aligns with Istio's Principal match authorization policies, offering a secure method of asserting service identities through cryptographic certificates. It is suitable for environments where strong, certificate-based identity validation is required.

PERMISSIVE

2

PERMISSIVE mode offers a flexible, transitional approach to identity verification, allowing the evaluation of authz rules based on either SOURCE_IDENTITY or PEER_CERTIFICATE identities. This mode is designed to facilitate gradual adoption of identity verification practices or to ease system upgrades. It is particularly useful in mixed environments where some services use SPIFFE IDs and others use a different form of service identity.

In ALLOW rules contexts, PERMISSIVE mode authorizes workloads if either their SOURCE_IDENTITY or PEER_CERTIFICATE matches the allowed principals. This approach broadens the range of clients that can be permitted, offering more flexibility during policy enforcement.

Conversely, in DENY rules contexts, PERMISSIVE mode restricts access to workloads if either their SOURCE_IDENTITY or PEER_CERTIFICATE matches the denied principals. This results in a more conservative set of clients being allowed, enhancing security by restricting access more broadly.

SOURCE_IDENTITY

3

SOURCE_IDENTITY mode strictly uses the service identity for authz rules evaluation. This identity is propagated from the originating client to the target service workload, which then assesses authz rules based on this received identity. The mode ensures that authz decisions are made based on the explicit identity of the requesting service, facilitating fine-grained access control and enhancing security by strictly adhering to the principle of least privilege.

This mode is optimal in environments that require strict enforcement of service identities, where the assurance of the caller's identity is paramount for secure access control.

PropagationStrategy

The PropagationStrategy is the key differentiating factor to decide how a security policy should be propagated and applied at runtime across clusters. The default propagation strategy is REPLACE, in which a lower level SecuritySetting in the configuration hierarchy replaces a higher level SecuritySetting. The STRICTER PropagationStrategy on the other hand makes sure the default SecuritySettings configured at the parent level are always enforced and propagated down the hierarchy unless additional SecuritySettings are defined and restricted further in the configuration hierarchy.

  • REPLACE should be used when resources in the hierarchy are allowed to override the default settings configured at the higher levels.
  • STRICTER should be used when the default settings must prevail, and the settings can only be made more restrictive by child resources at lower levels of the hierarchy.

When a resource or property of it affected by the propagation strategy is propagated down the hierarchy, regardless of the defined strategy (REPLACE or STRICTER), a parent defined resource or a property of the resource will be used (propagated) in absence of a child resource or a property of it.

For example, the following policy configures optional mTLS for traffic within the workspace, but it allows SecuritySettings to modify it. The example shows a workspace that configures service-to-service access so that only services in the same workspace can talk to each other. The REPLACE propagation policy allows individual settings to override it. In the example, the SecuritySettings allows services within that group to be reachable from any service in the cluster, regardless for the workspace they belong to, even though the Workspace restricts service-to-service access to only services in the Workspace.

apiVersion: api.tsb.tetrate.io/v2
kind: WorkspaceSetting
metadata:
name: w1-settings
workspace: w1
tenant: mycompany
organization: myorg
spec:
defaultSecuritySetting:
propagationStrategy: REPLACE
authorization:
mode: WORKSPACE
---
apiVersion: security.tsb.tetrate.io/v2
kind: SecuritySetting
metadata:
name: defaults
group: t1
workspace: w1
tenant: mycompany
organization: myorg
spec:
authorization:
mode: CLUSTER

STRICTER propagation configures defaults that can be only be restricted down the hierarchy. The following example configures the same WorkspaceSetting but with a STRICTER propagation mode. The defaults SecuritySetting further narrows down that access to the GROUP scope, which is allowed because GROUP is more strict than WORKSPACE. However, the defaults-invalid SecuritySetting configures CLUSTER access, which would widen the scope defined at the Workspace. That settings will not be allowed based on the STRICTER propagation policy.

apiVersion: api.tsb.tetrate.io/v2
kind: WorkspaceSetting
metadata:
name: w1-settings
workspace: w1
tenant: mycompany
organization: myorg
spec:
defaultSecuritySetting:
propagationStrategy: STRICTER
authorization:
mode: WORKSPACE
---
apiVersion: security.tsb.tetrate.io/v2
kind: SecuritySetting
metadata:
name: defaults
group: t1
workspace: w1
tenant: mycompany
organization: myorg
spec:
authorization:
mode: GROUP
---
apiVersion: security.tsb.tetrate.io/v2
kind: SecuritySetting
metadata:
name: defaults-invalid
group: t2
workspace: w1
tenant: mycompany
organization: myorg
spec:
authorization:
mode: CLUSTER

Further details of how security settings are resolved between in STRICTER mode between a parent and a child resource can be found in the SecuritySettings reference.

FieldNumberDescription

REPLACE

0

Is the default configuration propagation strategy. A lower defined configuration in the hierarchy will replace a higher configuration in the hierarchy. Otherwise, if a lower configuration is not defined, the configuration higher up in the hierarchy will prevail. For instance, a defined default propagation strategy for workspace default security settings will replace tenant's defined default security settings.

STRICTER

1

STRICTER propagation strategy propagates the strictest configuration between a defined higher level and a defined lower level configuration in the hierarchy. If a lower level configuration in the hierarchy is not defined, the higher one will prevail. Which configuration is stricter than the other is defined by each concrete configuration that allows specifying a propagation strategy.

WorkloadMode

WorkloadMode allows selection of the role of the underlying workload in network traffic. A workload is considered as acting as a SERVER if it is the destination of the traffic (that is, traffic direction, from the perspective of the workload is inbound). If the workload is the source of the network traffic, it is considered to be in CLIENT mode (traffic is outbound from the workload).

FieldNumberDescription

UNDEFINED

0

Default value, which will be interpreted by its own usage.

CLIENT

1

Selects for scenarios when the workload is the source of the network traffic. In addition, if the workload is a gateway, selects this.

SERVER

2

Selects for scenarios when the workload is the destination of the network traffic.

CLIENT_AND_SERVER

3

Selects for scenarios when the workload is either the source or destination of the network traffic.