Clusters

The differences between TSB and TSE API

Tetrate Service Express (TSE) utilizes many of the same components as the Tetrate Service Bridge(TSB) product but has the several distinctions. Go to Comparing TSE and TSB for more details.

Each Kubernetes cluster managed by Service Express 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 Express agent on the cluster to talk to Service Express management plane. The second step is to deploy the Service Express 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: tse
  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 agents in the cluster as long their requested cluster exists in the Service Express 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	–

ClusterStatus

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

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

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	–

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.