Clusters

Each Kubernetes cluster managed by Service Bridge should be onboarded first before configurations can be applied to the services in the cluster. Onboarding a cluster is a two step process. First, create a cluster object under the appropriate tenant. Once a cluster object is created, its status field should provide the set of join tokens that will be used by the Service Bridge agent on the cluster to talk to Service Bridge management plane. The second step is to deploy the Service Bridge agent on the cluster with the join tokens and deploy Istio on the cluster. The following example creates a cluster named c1 under the tenant mycompany, indicating that the cluster is deployed on a network "vpc-01" corresponding to the AWS VPC where it resides.

apiVersion: api.tsb.tetrate.io/v2
kind: Cluster
metadata:
  name: c1
  organization: myorg
  labels:
    env: uat-demo
spec:
  tokenTtl: "1h"
  network: vpc-01

Note that configuration profiles such as traffic, security and gateway groups will flow to the Bridge agents in the cluster as long their requested cluster exists in the Service Bridge hierarchy.

Cluster

A Kubernetes cluster managing both pods and VMs.

Field	Description	Validation Rule
tokenTtl	google.protobuf.Duration Lifetime of the tokens. Defaults to 1hr.	–
network	string The network (e.g., VPC) where this cluster is present. All clusters within the same network will be assumed to be reachable for the purposes of multi-cluster routing. In addition, networks marked as reachable from one another in SystemSettings will also be used for multi-cluster routing.	–
tier1Cluster	google.protobuf.BoolValue Deprecated: This flag is still honored for backward compatibility but will be ignored in future releases. It is advisable not to set it, as all clusters can now host both Tier1 and IngressGateways. Indicates whether this cluster is hosting a tier1 gateway or not. Tier1 clusters cannot host other gateways or workloads. Defaults to false if not specified.	–
locality	tetrateio.api.tsb.v2.Locality Deprecated. For backward compatibility, still honoured but will be ignored in future releases, so better not to set it. Locality of the service endpoints will be dynamically discovered by the xcp-edge Location information about the cluster which can be used for routing.	–
trustDomain	string Trust domain for this cluster, used for multi-cluster routing. It must be unique for every cluster and should match the one configured in the local control plane. This value is optional, and will be updated by the local control plane agents. However, it is recommended to set it, if known, so that multi-cluster routing works without having to wait for the local control planes to update it.	–
namespaceScope	tetrateio.api.tsb.v2.NamespaceScoping Configure the default scoping of namespaces in this cluster.	–
state	tetrateio.api.tsb.v2.Cluster.State OUTPUT_ONLY	–
serviceAccount	tetrateio.api.tsb.v2.ServiceAccount OUTPUT_ONLY The service account created with permissions to manage the current cluster. The service account is not stored and it is only returned in the ClusterCreate response.	–
installTemplate	tetrateio.api.tsb.v2.Cluster.InstallTemplate OUTPUT_ONLY Template to be used to install this TSB cluster in the k8s cluster	–

InstallTemplate

InstallTemplate provides templates ready to be used in the ControlPlane (cluster onboard) installation.

Field	Description	Validation Rule
message	string OUTPUT_ONLY can provide useful information to the user	–
helm	tetrateio.api.install.helm.controlplane.v1alpha1.Values OUTPUT_ONLY valid values.yaml to be used with controlplane helm chart. This field is an alpha API, so future versions could include breaking changes.	–

State

State represents the cluster info learned from the onboarded cluster

Field	Description	Validation Rule
lastSyncTime	google.protobuf.Timestamp last time xcp edge(cp) synced with central(mp) in the UTC format	–
provider	string cluster provider. Ex: GKE, EKS, AKS	–
istioVersions	List of string This shows currently running istio versions in the cluster.	–
xcpVersion	string xcp-edge version which is running at the cluster	–
tsbCpVersion	string TSB controlplane version	–
discoveredLocality	tetrateio.api.tsb.v2.Locality Discovered locality is the locality/region of the cluster as discovered by the xcp from the k8s endpoints	–
mode	tetrateio.api.tsb.types.v2.ControlPlaneMode Mode in which the Control Plane is deployed.	–
istioRevisions	List of tetrateio.api.tsb.v2.Cluster.State.IstioRevision Metadata of different Istio revision found in the cluster. An empty istio revisions field represents there was no Istio discovered in the cluster. Field should not be empty in ControlMode as TSB will install and depend on Istio. In Observe mode, an empty field represents that a vanilla kubernetes cluster.	–

IstioRevision

IstioRevision represents the Istio revisions in the ControlPlane Cluster.

Field	Description	Validation Rule
revision	string Istio revision found in the cluster	–
version	string Istio version found in the cluster.	–
distribution	tetrateio.api.tsb.v2.Cluster.State.IstioRevision.Distribution Istio distribution found in the cluster.	–

ClusterOnboardingConfig

Configuration for onboarding a cluster.

Field	Description	Validation Rule
namespaces	List of tetrateio.api.tsb.v2.ClusterOnboardingConfig.NamespaceConfig REQUIRED Set of namespaces configuration for the cluster.	repeated = {   min_items: 1 }

NamespaceConfig

Configuration for a namespace.

Field	Description	Validation Rule
name	string REQUIRED The name of the namespace.	string = {   min_len: 1 }
desiredState	tetrateio.api.tsb.v2.NamespaceDesiredState The desired state of the namespace.	–

ClusterOnboardingStatus

The onboarding status for a cluster.

Field	Description	Validation Rule
namespaces	List of tetrateio.api.tsb.v2.ClusterOnboardingStatus.NamespaceStatus The status of the namespaces in the cluster.	–

NamespaceStatus

The status of the namespaces in the cluster.

Field	Description	Validation Rule
name	string The name of the namespace.	–
desiredState	tetrateio.api.tsb.v2.NamespaceDesiredState The current state of the namespace.	–
currentState	tetrateio.api.tsb.v2.NamespaceCurrentState The actual state of the namespace.	–
currentStateDetails	string Details about the actual state of the namespace.	–

ClusterStatus

The status message for a cluster resource contains the set of join tokens that should be used by Service Bridge's agents on the cluster.

Field	Description	Validation Rule
tokens	map<string, string> Tokens for various agents.	–

IstioStatus

IstioStatus provides information about the Istio injection status of the namespace.

Field	Description	Validation Rule
istioInjection	tetrateio.api.tsb.v2.IstioStatus.IstioInjection Istio injection status for the namespace.	–
istioRevision	string Istio revision of the namespace.	–

Locality

The region the cluster resides. Used for failover based routing when configured in the workspace or global settings.

Field	Description	Validation Rule
region	string REQUIRED The geographic location of the cluster.	string = {   min_len: 1 }

NamespaceScoping

Configure the default scoping of namespaces in this cluster.

Field	Description	Validation Rule
scope	tetrateio.api.tsb.v2.NamespaceScoping.Scope Default scope for namespaces in this cluster (global, local)	–
exceptions	List of string Namespaces to be excluded form the default scope. If the scope is set to global, this list will contain namespaces that are considered local. If the scope is set to local, this list will contain namespaces that are considered global.	–

Port

Field	Description	Validation Rule
number	uint32 A valid non-negative integer port number.	–
name	string Name assigned to the port.	–
kubernetesNodePort	uint32 Indicates the node port attached to a physical deployment on a kubernetes cluster.	–

Workload

Info about individual workload implementing the service.

Field	Description	Validation Rule
address	string Routable address of the workload.	–
name	string Instance name of the workload.	–
isVm	bool Indicates whether the workload is kubernetes endpoint or vm.	–
proxy	tetrateio.api.tsb.v2.Workload.Proxy Proxy details.	–

Proxy

Info about proxy attached to a workload.

Field	Description	Validation Rule
controlPlaneAddress	string Address/service of control plane entity controlling the proxy like istiod.istio-system.svc:15012.	–
envoyVersion	string Envoy version of the proxy.	–
istioVersion	string Istio version of the proxy.	–
status	map<string, string> Sync status for each xDS component. For example: status["CDS"] = "SYNCED" XDS components are: LDS, RDS, EDS CDS and SRDS. Refer to Envoy go-control-plane ConfigStatus for possible status values values: https://github.com/envoyproxy/go-control-plane/blob/main/envoy/service/status/v3/csds.pb.go	–

Distribution

Type of distribution for the Istio version

Field	Number	Description
UNKNOWN	0	Unknown Istio distribution
TSB	1	TSB istio distribution
TID	2	TID istio distribution

IstioInjection

Istio injection status for the namespace.

Field	Number	Description
ISTIO_INJECTION_UNDEFINED	0	The TSB CP is not able to determine the Istio injection status of the namespace.
ISTIO_INJECTION_ENABLED	1	The namespace is configured with Istio injection.
ISTIO_INJECTION_DISABLED	2	The namespace is not configured with Istio injection.

NamespaceCurrentState

The current state of a namespace.

Field	Number	Description
CURRENT_UNDEFINED	0	Undefined state.
CURRENT_UNKNOWN	1	The TSB CP is not able to determine the state of the namespace.
CURRENT_SYSTEM	2	The namespace has been detected as TSB system namespace, as cloud provider system namespace, or as a namespace with system components specified in the Cluster Onboarding Config as DESIRED_SYSTEM. It should not have sidecars injected and should not be configured with Istio injection.
CURRENT_DISABLED	3	The namespace has been detected with no sidecars injected and is not configured with Istio injection. Check the current_state_details field for more information.
CURRENT_ENABLED	4	The namespace has been detected with sidecars injected and is configured with Istio injection.

NamespaceDesiredState

The desired state of a namespace.

Field	Number	Description
DESIRED_UNDEFINED	0	Undefined state.
DESIRED_UNASSIGNED	1	The user did not specify a desired state for the namespace.
DESIRED_DISABLED	2	The namespace should have no sidecars injected and don't be configured with Istio injection.
DESIRED_IGNORED	3	TSB should not modify the Istio injection.
DESIRED_ONBOARDED	4	The namespace should have a sidecars injected and be configured with Istio injection.
DESIRED_SYSTEM	5	The namespace should be considered as a system namespace. Which means that the namespace contain system components and should not have sidecars injected and don't be configured with Istio injection. It is similar in terms of sidecar injection to DESIRED_DISABLED but it is used to mark the namespace as a system namespace as well.

Scope

Field	Number	Description
GLOBAL	0	Global configures namespaces in this cluster to be considered global. Namespaces that exist in other clusters with the same name will be considered to be the same logical namespace.
LOCAL	1	Configures local scoping for namespaces, so that namespaces with the same name in different clusters will not be considered the same logical namespace.

State

State denotes the interactions the service can have with the mesh. A service can exist in one of the states which represents the set of interactions(Observability and Control) the mesh can have with these services.

Field	Number	Description
INVALID_STATE	0
EXTERNAL	1	An external service is a service that is known, but that cannot be observed (we can't get metrics for it) and cannot be controlled.
OBSERVED	2	An observed service is a known service that we can have metrics for. For example, a service running the Skywalking agents.
CONTROLLED	3	A controlled service is a service that is part of the mesh, has a proxy we can configure and can be observed with Skywalking agents.