Cluster Service - Jimmy Song

Service to manage clusters onboarded in TSB.

Clusters

The Clusters service exposes methods to manage the registration of clusters that are managed by TSB. Before TSB can takeover networking for a given cluster, it must be onboarded in the platform. This onboarding process usually involves two steps:

Creating the cluster object so the platform knows about it.
Generate the agent tokens for the cluster, so the TSB agents installed in the actual cluster can talk to TSB.

Once a cluster has been onboarded into TSB, it will start receiving configuration updates from the management plane, and the agents will keep the management updated with the status of the cluster.

CreateCluster

rpc CreateCluster (tetrateio.api.tsb.v2.CreateClusterRequest) returns (tetrateio.api.tsb.v2.Cluster)

Requires CREATE

Creates a new cluster object in TSB. This is needed during cluster onboarding to let the management plane know about the existence of a cluster. Once a cluster has been created and fully onboarded, the management plane will manage the mesh for that cluster and keep this cluster entity up to date with the information that is reported by the cluster agents. This method returns the created cluster, that will be continuously updated by the local cluster agents. This entity can be monitored to have an overview of the resources (namespaces, services, etc) that are known to be running in the cluster.

This action will also create a service account with permissions to manage this cluster. This service account (aka cluster service account) can be used in the ControlPlane installation to authenticate it through the ManagementPlane.

As part of the response, a template will be provided (in the field installTemplate) with minimum configuration to be able to install the TSB Operator in the cluster running as ControlPlane. This data is not stored and will be only available in the response of this action.

GetCluster

rpc GetCluster (tetrateio.api.tsb.v2.GetClusterRequest) returns (tetrateio.api.tsb.v2.Cluster)

Requires READ

Get the last known state for an onboarded cluster. Once a cluster has been onboarded into the platform, the agents will keep it up to date with its runtime status. Getting the cluster object will return the last known snapshot of existing namespaces and services running in it.

UpdateCluster

rpc UpdateCluster (tetrateio.api.tsb.v2.Cluster) returns (tetrateio.api.tsb.v2.Cluster)

Requires WRITE

Modify an existing cluster. Updates a cluster with the given data. Note that most of the data in the cluster is read-only and automatically populated by the local cluster agents.

ListClusters

rpc ListClusters (tetrateio.api.tsb.v2.ListClustersRequest) returns (tetrateio.api.tsb.v2.ListClustersResponse)

Get the list of all clusters that have been onboarded into the platform.

DeleteCluster

rpc DeleteCluster (tetrateio.api.tsb.v2.DeleteClusterRequest) returns (google.protobuf.Empty)

Requires DELETE

Unregisters a cluster from the platform. Deleting a cluster will unregister it from the management plane, and the agents will stop receiving configuration updates. Agent tokens for the cluster are revoked as well, so agents that are still running will fail to report back cluster status to the management plane. Note that unregistering the cluster is a management plane only operation. This does not uninstall the agents from the local cluster. Agents will continue running and the services that are deployed in that cluster will be able to continue operating with the last applied configuration. Unregistering a cluster from the management plane should not generate downtime to services that are running on that cluster.

GenerateTokens

rpc GenerateTokens (tetrateio.api.tsb.v2.GenerateTokensRequest) returns (tetrateio.api.tsb.v2.ClusterStatus)

Requires WriteCluster

Generate the tokens for the cluster agents so they can talk to the management plane. Once a cluster object has been registered in the management plane, this method can be used to generate the JWT tokens that need to be configured in the local cluster agents in order to let them talk to the management plane. These tokens contain the necessary permissions to allow the agents to download the configuration for their cluster and to push cluster status updates to the management plane.

CreateClusterRequest

Request to create a cluster and register it in the management plane so configuration can be generated for it.

Field	Description	Validation Rule
parent	string REQUIRED Parent resource where the cluster will be created. This is the FQN of the organization or the tenant.	string = { min_len: `1` }
name	string REQUIRED The short name for the resource to be created.	string = { min_len: `1` }
cluster	tetrateio.api.tsb.v2.Cluster REQUIRED Details of the cluster to be created.	message = { required: `true` }

DeleteClusterRequest

Request to delete a cluster.

Field	Description	Validation Rule
fqn	string REQUIRED Fully-qualified name of the cluster.	string = { min_len: `1` }

GenerateTokensRequest

Request to generate the cluster agent tokens.

Field	Description	Validation Rule
fqn	string REQUIRED Fully-qualified name of the cluster.	string = { min_len: `1` }

GetClusterRequest

Request to retrieve a cluster.

Field	Description	Validation Rule
fqn	string REQUIRED Fully-qualified name of the cluster.	string = { min_len: `1` }
fetchWorkloads	bool Flag to fetch the workload information as well. Note that by default workload information is not returned as it may be expensive to retrieve.	–
includeInstallTemplate	bool Flag to return the install template required to install this cluster. This will generate a new API key pair for the cluster service account.	–

ListClustersRequest

Request to list clusters.

Field	Description	Validation Rule
parent	string REQUIRED Parent resource to list clusters from. This is the FQN of the organization or the tenant.	string = { min_len: `1` }
fetchWorkloads	bool Flag to fetch the workload information for all the clusters as well. Note that by default workload information is not returned as it may be expensive to retrieve.	–

ListClustersResponse

List of clusters that are registered in the platform.

Field	Description	Validation Rule
clusters	List of tetrateio.api.tsb.v2.Cluster The list of clusters that are registered in the platform.	–