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.
Field | Description | Validation Rule |
---|---|---|
labels | map<string, string> | – |
annotations | map<string, string> | – |
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.
Field | Description | Validation Rule |
---|---|---|
topologyChoice | tetrateio.api.tsb.types.v2.FailoverSettings.TopologyChoice | enum = { |
failoverPriority | List of string 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 Example of failoverPriority using these labels:
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:
Example of failoverPriority using these labels:
| repeated = { |
regionalFailover | List of tetrateio.api.tsb.types.v2.RegionalFailover 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 likens-*
to mean all those namespaces starting byns-
Field | Description | Validation Rule |
---|---|---|
names | List of string
| repeated = { |
PortSelector
PortSelector is the criteria for specifying if a policy can be applied to a listener having a specific port.
Field | Description | Validation Rule |
---|---|---|
number | uint32 | uint32 = { |
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.
Field | Description | Validation Rule |
---|---|---|
from | string | – |
to | string | – |
ServiceSelector
ServiceSelector represents the match criteria to select services within a particular scope (namespace, workspace, cluster etc)
Field | Description | Validation Rule |
---|---|---|
serviceLabels | map<string, string> | map = { |
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.
Field | Description | Validation Rule |
---|---|---|
mode | tetrateio.api.tsb.types.v2.WorkloadMode | enum = { |
ports | List of tetrateio.api.tsb.types.v2.PortSelector If one of the given | – |
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
Field | Description | Validation Rule |
---|---|---|
fqn | string | string = { |
config | google.protobuf.Struct | – |
match | List of tetrateio.api.tsb.types.v2.TrafficSelector | – |
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.
Field | Description | Validation Rule |
---|---|---|
namespace | string | string = { |
labels | map<string, string> | map = { |
Object
Format for all API objects in TSB as exposed in the CLI.
Field | Description | Validation Rule |
---|---|---|
apiVersion | string | string = { |
kind | string | string = { |
metadata | – | |
spec | google.protobuf.Any | – |
status | map<string, string> | – |
ObjectMeta
Metadata associated with each API Object.
Field | Description | Validation Rule |
---|---|---|
name | string The name field must:
| – |
namespace | string | – |
tenant | string | – |
workspace | string | – |
group | string | – |
resourceVersion | string | – |
labels | map<string, string> | – |
annotations | map<string, string> | – |
displayName | string | – |
description | string | – |
organization | string | – |
application | string | – |
api | string | – |
service | string | – |
telemetrySource | string | – |
fqn | string | – |
cluster | string | – |
Extensions
Extensions extend TSB functionality.
Field | Description | Validation Rule |
---|---|---|
kong | tetrateio.api.tsb.types.v2.Kong The functionality provided by this extender will be added just before
routing is done. This means all other listener filters configured on the
gateway will be executed first such as RBAC (authorization policies) and
then the request will be proeccessed by the Please note that extending using Kong requires to run
| – |
Kong
Kong extension configuration.
Field | Description | Validation Rule |
---|---|---|
plugins | List of tetrateio.api.tsb.types.v2.Kong.Plugins | – |
Plugins
Plugin definition.
Only plugins mutating request and response are supported currently. Advanced plugins may not work. Please contact Tetrate to check if a plugin is supported.
Field | Description | Validation Rule |
---|---|---|
name | string This can be one of the Kong open source plugins or a custom plugin. Kong open source plugins are bundled with TSB and can run in the same
fashion as Kong. However providing | string = { |
priority | uint32 Priority is a concept of kong which decides the order of execution of plugins. Most of the bundled plugins come with a priority defined as per kong's plugin execution order TSB allows you to run both bundled and custom plugins in a different order by reassigning priorities. | – |
config | tetrateio.api.tsb.types.v2.Kong.Plugins.PluginConfig | – |
pluginSource | tetrateio.api.tsb.types.v2.Kong.Plugins.PluginSource A kong custom plugin is a user written custom logic written in lua and can be used along with bundled plugins. For more information, please refer: Kong's Documentation Required if this is a custom plugin. | – |
PluginConfig
Configuration for Kong plugin.
Field | Description | Validation Rule |
---|---|---|
inline | google.protobuf.Struct oneof _source The following is an example of a valid config for Kong's response-transformer plugin.
If the config fails plugin's schema vaildation, the
| – |
PluginSource
Reference to custom plugin files.
Field | Description | Validation Rule |
---|---|---|
configMap | string To create this configmap in the gateway install namespace, run:
and use the name In case the configMap cannot be loaded (not found, bad format or any
other issue reading it), the custom plugin will not be initialised and
the config will be rejected by the | string = { |
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.
Field | Description | Validation Rule |
---|---|---|
type | – |
TypeInfo
TypeInfo provides metadata describing a message type.
Field | Description | Validation Rule |
---|---|---|
generatesConfig | bool | – |
aggregatesStatus | bool | – |
dependencies | List of string | – |
lastEventXcpAccepted | bool | – |
supportsSegmentation | bool | – |
CreateIstioObjectRequest
Request to create an Istio Object
Field | Description | Validation Rule |
---|---|---|
parent | string | string = { |
name | string | string = { |
object | tetrateio.api.tsb.types.v2.IstioObject | message = { |
DeleteIstioObjectRequest
Request to delete a Istio Object.
Field | Description | Validation Rule |
---|---|---|
fqn | string | string = { |
GetIstioObjectRequest
Request to retrieve a Istio Object.
Field | Description | Validation Rule |
---|---|---|
fqn | string | string = { |
IstioObject
Wrapper for Istio direct mode objects with all the details needed to add it to the TSB resource hierarchy.
Field | Description | Validation Rule |
---|---|---|
metadata | tetrateio.api.tsb.types.v2.IstioObject.ConfigMeta | – |
spec | google.protobuf.Any | – |
ConfigMeta
Field | Description | Validation Rule |
---|---|---|
apiVersion | string | string = { |
kind | string | string = { |
name | string | – |
namespace | string | – |
labels | map<string, string> | – |
annotations | map<string, string> | – |
ListIstioObjectsRequest
Request to list Istio Object.
Field | Description | Validation Rule |
---|---|---|
parent | string | string = { |
ListIstioObjectsResponse
List of Istio direct mode objects
Field | Description | Validation Rule |
---|---|---|
objects | – |
ConfigMode
The configuration mode used by a traffic, security or a gateway group.
Field | Number | Description |
---|---|---|
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. |
ControlPlaneMode
Available Control Plane modes for the Control Plane deployment.
Field | Number | Description |
---|---|---|
UNSET | 0 | Default mode will be used. |
CONTROL | 1 | Default mode installed in Control plane clusters. The Control Plane will be deployed with the entire TSB feature set enabled for this cluster. |
OBSERVE | 2 | The Control Plane will be deployed with only service discovery and observability features enabled. Other features of TSB like configuration propagation, cross-cluster discovery, etc, will not be available in this cluster. |
TopologyChoice
TopologyChoice specifies the topology preference for traffic priority.
Field | Number | Description |
---|---|---|
NONE | 0 | Inherit from parent if possible. Otherwise treated as |
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.
Field | Number | Description |
---|---|---|
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.
Field | Number | Description |
---|---|---|
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).
Field | Number | Description |
---|---|---|
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. |