Concepts
This page provides an overview of Tetrate Service Bridge (TSB) core concepts and APIs. The TSB APIs allow you to manage your users, teams, map your physical infrastructure into a logical model, and apply policies again those entities. Using the model, your teams can configure traffic policy and see L7 metrics for the applications they own without worrying about the clusters they are deployed on.
Model
TSB exposes a hierarchy. At the root is a Tenant; you have access to exactly one Tenant. A set of Environments can be created under your Tenant, and within these environments you can create Applications. Applications group a set of related Services in the same Environment together.
note
Typically, you'll only need to interact with the APIs for Applications and Services. Your teams will be populated automatically from your existing permission system (e.g. LDAP) by Tetrate agents, and similarly your physical infrastructure will be kept up to date by Tetrate agents syncing with the deployment (e.g. your Kubernetes clusters).
In the following sections we'll give a brief outline of each resource. Then we'll discuss how you can use those resources to apply policy to your deployments.
Tenants
The Tenant serves as the root of the hierarchy; each TSB installation has exactly one tenant. Today policy cannot be attached to the Tenant itself; in the future you'll be able to attach access control policy as well as default routing behavior that applies across all Environments.
While the ID for your Tenant is static and won't change (i.e. it could be hard coded into tooling you create), listing Tenants is the easiest way to bootstrap a program that needs to know which Tenant to work with without having to hard code or pass in your Tenant ID as a parameter. You'll only get one response back in the list - your single Tenant.
curl --request GET \
--url http://${TSBIP}:8443/v1/tenants \
--header 'accept: application/json'
Your Tenant will look something like:
[
{
"name": "tenants/235676543",
"id": "235676543",
"description": "Tenant for Acme Corporation"
}
]
Environments
An Environment is a group of Applications and a set of physical Clusters. An Environment can
have a default set of ClientSettings that applies to all Services across all Clusters in that
Environment.
You can list your Environments using the Tenant ID you extracted above:
curl --request GET \
--url http://${TSBIP}:8443/v1/tenants/${TENANT_ID}/environments \
--header 'accept: application/json'
Your Environments should look something like:
[{
"name": "tenants/235676543/environments/dev",
"tenant": "235676543",
"id": "dev",
"description": "DEV Environment",
"clientSettings": {
"httpRequestTimeout": "5s",
"httpRetries": {
"attempts": 2,
"perTryTimeout": "2s",
"retryOn": "5xx"
},
"circuitBreakerSensitivity": "LOW"
}
}, ...]
Applications
An Application is a group of Services within an Environment. The Services in an Application
can be in one or more namespaces. These namespaces indicate the physical Namespace IDs in the
set of clusters in the Environment: an Application with namespaces acme, example, test will
automatically match all Namespaces with id: acme, id: example, id: test in the set of Clusters
in the Environment.
info
This means that if you have a set of Kubernetes clusters in a TSB Environment and in each of
those clusters you assign the billing team the Kubernetes namespace billing, then you should
create a TSB Application that contains billing as one of its namespaces. TSB will automatically
connect the services deployed in the billing namespaces in each cluster with the TSB billing
Application.
note
TSB requires each Kubernetes namespace to contain services that are part of only one application. That is : a namespace cannot have more than one application. However, an application can contain services across multiple namespaces.
Just like Environments, Applications allow you to specify a set of ClientSettings that apply to
all services in the application. See the Traffic Policy section below for details on how
ClientSettings interact down the hierarchy.
You can list your Applications using the Tenant ID and Environment ID you extracted above:
curl --request GET \
--url http://${TSBIP}:8443/v1/tenants/${TENANT_ID}/environments/${ENVIRONMENT_ID}/applications \
--header 'accept: application/json'
Your Application should look something like:
[{
"name": "tenants/235676543/environments/dev/applications/bookinfo",
"tenant": "235676543",
"environment": "dev",
"id": "bookinfo",
"description": "BookInfo App in Dev",
"namespaces" : [ "bookinfo", "bookinfo-aux" ],
}, ...]
Services
A Service represents a set of physical Deployments that implement the same contract (API).
Services in a namespace match one-to-N with physical Deployments by id. A Service with
id: frontend in namespace acme will match with all Deployments in namespace acme with
id: frontend in all Clusters in the Environment.
There are three types of Services that TSB recognizes. INTERNAL (default type) Services are
those that are visible only inside the Application. LOADBALANCER Services are visible outside
the Application, while EXTERNAL Services represent the Application's dependencies on third
party Services. To expose an Application to the outside world, you need to deploy a TSB
gateway in the physical Cluster in a physical Namespace that is part of the Application. All
Services running the TSB gateway are automatically recognized as a LOADBALANCER type service.
note
In TSB we say "physical Deployment", but when mapping a Kubernetes cluster into TSB we actually map Kubernetes Services by name to TSB Physical Deployments. So the ID for a TSB Service must match the name of a Kubernetes Service, not the Kubernetes Deployment backing the Kubernetes Service.
You can apply RoutingInfo and TLSSettings at the Service level. These settings will apply to
all deployments of the Service. ClientSettings are inherited from the Application and cannot
be set directly per service.
You can list your Services using the Tenant, Environment, and Application IDs you extracted above:
curl --request GET \
--url http://${TSBIP}:8443/v1/tenants/${TENANT_ID}/environments/${ENVIRONMENT_ID}/applications/${APP_IP}/services \
--header 'accept: application/json'
Your Service should look something like:
[{
"name": "tenants/235676543/environments/dev/applications/bookinfo/services/productpage",
"tenant": "235676543",
"environment": "dev",
"application": "bookinfo",
"id": "productpage",
"description": "ProductPage frontend webserver",
"hostname": "productpage.acme.com",
"ports": [
{
"number": 80,
"protocol": "HTTP"
}
],
"etag": ""
}, ...]
note
Services are the first object we've seen in this guide that include an etag field. The etag is
used to guard against concurrent updates to objects. To correctly update a value in a Service
object, simply calling Update Service is not enough - if the etag in your update doesn't match
the server's current etag it will reject your update request (with a 409 Conflict error).
Instead, you need to call Update in a Read-Modify-Write loop. See the TSB API Usage Guide for
details about how we use etags across our APIs and recipes for building clients that are
etag-aware.
System Application
The System Application (id: system) hosts shared resources across the entire mesh. These include
shared load balancers across many Applications, service mesh control plane components, etc.
Only load balancer services in the System Application can route traffic to any Application in
the same Cluster. Load balancer Services in other Applications can only route traffic to other
Services in the same Application in the Cluster.