--- title: "Get the list of all clusters that have been onboarded into the platform." method: GET path: "/v2/organizations/{organization}/clusters" tags: ["Clusters"] --- # Get the list of all clusters that have been onboarded into the platform. `GET /v2/organizations/{organization}/clusters` ## Request - Base URL: `https://docs.tetrate.io` (the document declares no server; this is the origin it was published from) - URL: `https://docs.tetrate.io/v2/organizations/{organization}/clusters` - Auth: none declared - TypeScript: (a function with typed inputs; its response is checked against the schema) ## Path parameters - `organization` string, required ## Query parameters - `fetchWorkloads` boolean ## Response `200` A successful response. - V2ListClustersResponse: List of clusters that are registered in the platform. - `clusters` V2Cluster[]: The list of clusters that are registered in the platform. - `fqn` string - `displayName` string - `etag` string - `description` string - `tokenTtl` string: 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` boolean: 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. - `namespaces` Tsbv2Namespace[] - `name` string - `services` Tsbv2Service[] - `hostname` string: The hostname by which this service is accessed. Can correspond to the hostname of an internal service or that of a virtual host on a gateway. - `namespace` string: namespace associated with the service. - `selector` object: label selectors associated with the service. - `ports` ServicePort[]: The set of ports on which this service is exposed. - `number` integer: A valid non-negative integer port number. - `name` string: Name assigned to the port. - `kubernetesNodePort` integer: Indicates the node port attached to a physical deployment on a kubernetes cluster. - `kubernetesServiceIp` string: For services running on Kubernetes, the cluster IP of the service in the cluster. - `kubernetesExternalAddresses` string[]: For kubernetes services of type load balancer, this field contains the list of lb hostnames or IPs assigned to the service. For services of type nodePort, this field contains the IP addresses of the nodes in the cluster. - `numKubernetesEndpoints` integer: The number of kubernetes pods providing this service. Note that a service could be hosted on both pods and VMs. - `numVmEndpoints` integer: The number of VMs providing this service. - `meshExternal` boolean - `gatewayHost` boolean: Indicates that this is a service representing a gateway host (used for multi-cluster scenarios). - `numHops` integer: The number of hops from the advertising cluster to the ingress gateway that is exposing the gateway host. If the advertiser is the cluster owning the ingress gateway host, the hops is 0. If the advertiser is a tier1 cluster exposing gateways via internal or external Servers, the path hops is 1. - `kubernetesServiceFqdn` string: If this is a gateway host service, this field will indicate the kubernetes service that is running as a gateway and exposing this host to the outside world. - `name` string - `subsets` string[] - `canonicalName` string: 17 to match xcp api and make conversion easier. - `workloads` V2Workload[]: Workloads implementing the Service. - `address` string: Routable address of the workload. - `name` string: Instance name of the workload. - `isVm` boolean: Indicates whether the workload is kubernetes endpoint or vm. - `proxy` WorkloadProxy: Info about proxy attached to a workload. - `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` object - `tier1GatewayHost` boolean: Indicates that this is a service representing a gateway host acting as a tier1 gateway. This field is being introduced specifically for the hostnames exposed through Tier1Gateway's ExternalServers. Fo all other hostnames that are exposed exposed on IngessGateways or Tier1Gateway's InternalServers gateway_host field is set to true because that is used for multicluster routing setup. For ExternalServer hostnames multicluster cluster routing is not setup and hence UI on finding gateway_host as false shows these hostnames as internal services incorrectly. To help UI, this field is being introduced. UI would look for either gateway_host or tier1_gateway_host to decide if the hostname is a gateway hostname. - `spiffeIds` string[]: List of SPIFFE identities used by the workloads of the service. - `labels` object - `locality` V2Locality: The region the cluster resides. Used for failover based routing when configured in the workspace or global settings. - `region` string, required: The geographic location of the cluster. - `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` V2NamespaceScoping: Configure the default scoping of namespaces in this cluster. - `scope` 'GLOBAL' | 'LOCAL': - GLOBAL: 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: Configures local scoping for namespaces, so that namespaces with the same name in different clusters will not be considered the same logical namespace. - `exceptions` 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. - `state` ClusterState - `lastSyncTime` string, date-time - `provider` string - `istioVersions` string[]: This shows currently running istio versions in the cluster. - `xcpVersion` string - `tsbCpVersion` string - `discoveredLocality` V2Locality: The region the cluster resides. Used for failover based routing when configured in the workspace or global settings. - `region` string, required: The geographic location of the cluster. - `serviceAccount` Tsbv2ServiceAccount: `ServiceAccount` represents a service account that can be used to access the TSB platform. Service accounts have a set of associated public and private keys that can be used to generate signed JWT tokens that are suitable to authenticate to TSB. A default key-pair is generated on service account creation and the public key is stored in TSB. Private keys are returned when service accounts are created, but TSB will not store them. It is up to the client to store them securely. - `fqn` string - `displayName` string - `etag` string - `description` string: A description of the resource. - `keys` ServiceAccountKeyPair[] - `id` string - `publicKey` string - `privateKey` string - `encoding` 'PEM' | 'JWK' - `defaultToken` string - `installTemplate` ClusterInstallTemplate: InstallTemplate provides templates ready to be used in the ControlPlane (cluster onboard) installation. - `message` string - `helm` V1alpha1Values: Values available for the TSB Control Plane chart. This is an alpha API, so future versions could include breaking changes. - `image` Commonv1alpha1Image: Values for the TSB operator image. - `registry` string: Registry used to download the operator image. - `tag` string: The tag of the operator image. - `spec` V1alpha1ControlPlaneSpec: ControlPlaneSpec defines the desired installed state of control plane components. Specifying a minimal ControlPlaneSpec with hub, clusterName, and managementPlane set will create an installation with sensible defaults. - `hub` string, required: TSB container hub path e.g. docker.io/tetrate. - `imagePullSecrets` InstallkubernetesLocalObjectReference[]: Pull secrets can be specified globally for all components, or defined into the `kubeSpec.serviceAccount` of every component if needed. In case both are defined, the most specific one (the one defined at the component) level is used. List of references to secrets in the same namespace to use for pulling any images in pods that reference this ServiceAccount. ImagePullSecrets are distinct from Secrets because Secrets can be mounted in the pod, but ImagePullSecrets are only accessed by the kubelet. More info: https://kubernetes.io/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/#service_account-v1-core - `name` string: Name of the referent. - `components` V1alpha1ControlPlaneComponentSet: The set of components that make up the control plane. Use this to override application settings or Kubernetes settings for each individual component. - `collector` V1alpha1OpenTelemetryCollector: Kubernetes settings for the OpenTelemetryCollector component. - … - `oap` V1alpha1Oap: Kubernetes settings for the OAP (SkyWalking) component. - … - `xcp` Controlplanev1alpha1XCP: Kubernetes settings for the XCP component. - … - `istio` V1alpha1Istio: Mesh and Kubernetes settings for Istio. - … - `rateLimitServer` V1alpha1RateLimitServer - … - `hpaAdapter` V1alpha1HpaAdapter: Kubernetes settings for the OAP (SkyWalking) HPA adapter component. - … - `onboarding` V1alpha1Onboarding: Settings for the `Workload Onboarding` component. - … - `satellite` V1alpha1Satellite: Kubernetes settings for the Satellite (SkyWalking-Satellite) component. - … - `ngac` V1alpha1NGAC: Kubernetes settings for the NGAC component. - … - `gitops` CommonGitOps: The GitOps component configures the features that allow integrating the Management Plane and/or the Control Plane cluster with Continuous Deployment pipelines. - … - `internalCertProvider` CommonInternalCertProvider: InternalCertProvider describes the certificate provider configuration for TSB internal purposes like kubernetes webhook certificate. TSB supports cert-manager out of the box. - … - `defaultKubeSpec` KubernetesKubernetesSpec: KubernetesSpec is a common set of Kubernetes resource configuration for the install CRs, that will be common to all of its components. - … - `wasmfetcher` V1alpha1WASMFetcher: Settings for the WASM Fetcher component. - … - `defaultLogLevel` string: The default log level for all components if the per component log level config is not specified. Note that the supported log level for different components can be different. - `route53Controller` V1alpha1Route53Controller: Kubernetes settings for the Route53 Integration Controller component. - … - `providerSettings` V1alpha1ProviderSettings: Configure Kubernetes provider specific settings. For example to configure EKS to use network load balancers (NLB) by default: ```yaml apiVersion: install.tetrate.io/v1alpha1 kind: ControlPlane metadata: name: controlplane namespace: istio-system spec: providerSettings: eks: useNlbByDefault: true ``` To configure Route53 the only option that you must specify is the Service Account name to use for IAM role. You should create the Service Account before enabling the Route53 integration controller. You can do that using `eksctl`. Example: ```bash SA_NAME=route53-controller CP_NAMESPACE=istio-system eksctl create iamserviceaccount \ --cluster $EKS_CLUSTER_NAME \ --name $SA_NAME \ --namespace $CP_NAMESPACE \ --attach-policy-arn $POLICY_ARN \ --approve ``` where: * $EKS_CLUSTER_NAME is the name of the EKS cluster. * $SA_NAME is the name of the Service Account to create. * $CP_NAMESPACE is the namespace where the Control Plane is installed. Usually istio-system. * $POLICY_ARN is the ARN of the policy to attach to the Service Account - the policy should allow the Service Account to manage Route53 resources. More details can be found in the [Publishing a Service docs](https://docs-preview.tetrate.io/service-express/Tech-Preview/getting-started/publish-service) After creating the Service Account you can enable the Route53 integration controller using the following configuration: ```yaml apiVersion: install.tetrate.io/v1alpha1 kind: ControlPlane metadata: name: controlplane namespace: istio-system spec: providerSettings: route53: serviceAccountName: $SA_NAME ``` - `eks` V1alpha1EKSSettings: Settings specific to Elastic Kubernetes Service (EKS). - … - `route53` V1alpha1Route53Settings: Settings for integration with Route53 service. - … - `managementPlane` V1alpha1ManagementPlaneSettings, required: Configure the management plane connection. ```yaml apiVersion: install.tetrate.io/v1alpha1 kind: ControlPlane metadata: name: controlplane namespace: istio-system spec: managementPlane: host: tsb.tetrate.io port: 8443 selfSigned: true clusterName: control-plane-cluster ``` - `host` string, required: Management plane host address (can be hostname or IPv4/IPv6 address). - `port` integer, required: Port management plane is listening on. - `selfSigned` boolean: Management plane uses a self signed or private TLS certificate. If true, the CA bundle used to verify the MP's TLS certificate must be in a secret `mp-certs` under the key `ca.crt`. - `clusterName` string, required: The name of the Cluster object that was created in the Management Plane representing this Control Plane cluster. - `meshExpansion` V1alpha1MeshExpansionSettings: Configure mesh expansion to connect workloads external to Kubernetes to the mesh. To enable mesh expansion set it to an empty object: ```yaml apiVersion: install.tetrate.io/v1alpha1 kind: ControlPlane metadata: name: controlplane namespace: istio-system spec: meshExpansion: {} ``` If external workloads are unable to communicate with the default mesh expansion gateway via external IPs or hostnames, then you must specify the gateway that enables them to do so. This custom gateway must be configured to forward this communication to the VM gateway service: ```yaml apiVersion: install.tetrate.io/v1alpha1 kind: ControlPlane metadata: name: controlplane namespace: istio-system spec: meshExpansion: customGateway: host: customgateway.tetrate.io port: 15443 ``` To automate onboarding of workloads from auto-scaling groups of VMs, you need to enable the `Workload Onboarding Plane`. `Workload Onboarding Agent`, a component that you install next to the workload, will connect to the `Workload Onboarding Plane` to authenticate itself, ask permission to join the mesh, register the workload into the mesh and retrieve boot configuration required to start `Istio Sidecar`. All communication between the `Workload Onboarding Agent` and the `Workload Onboarding Plane` must occur over TLS. Therefore, to enable `Workload Onboarding Plane` you must provide a TLS certificate for the endpoint that exposes `Workload Onboarding API` to `Workload Onboarding Agents`. Make sure that TLS certificate is signed by the certificate authority known to `Workload Onboarding Agents`. ```yaml apiVersion: install.tetrate.io/v1alpha1 kind: ControlPlane metadata: name: controlplane namespace: istio-system spec: meshExpansion: onboarding: endpoint: hosts: - onboarding.example.org secretName: onboarding-tls-cert tokenIssuer: jwt: expiration: 1h localRepository: {} ``` To onboard workloads from custom on-premise environments, you can leverage support for [OIDC ID Tokens](https://openid.net/specs/openid-connect-core-1_0.html#IDToken). If workloads in your custom environment can authenticate themselves by means of an [OIDC ID Token](https://openid.net/specs/openid-connect-core-1_0.html#IDToken), you can define a list of JWT issuers permitted by the `Workload Onboarding Plane`. For example, ```yaml apiVersion: install.tetrate.io/v1alpha1 kind: ControlPlane metadata: name: controlplane namespace: istio-system spec: meshExpansion: onboarding: endpoint: hosts: - onboarding.example.org secretName: onboarding-tls-cert localRepository: {} workloads: authentication: jwt: issuers: - issuer: "https://mycompany.corp" jwksUri: "https://mycompany.corp/jwks.json" shortName: "mycorp" tokenFields: attributes: jsonPath: .custom_attributes ``` To ensure there will be no traffic loss when an onboarded workload gets shutdown, you can configure the time period to delay the shutdown for after deregistering the workload from the mesh, which will give enough time to reconfigure all affected mesh nodes to not load balance requests to the deregistered workload before it becomes unavailable. For example, ```yaml apiVersion: install.tetrate.io/v1alpha1 kind: ControlPlane metadata: name: controlplane namespace: istio-system spec: meshExpansion: onboarding: endpoint: hosts: - onboarding.example.org secretName: onboarding-tls-cert localRepository: {} workloads: deregistration: propagationDelay: 15s ``` - `customGateway` MeshExpansionSettingsGateway: A custom mesh expansion gateway. This is required when the workload can't access the default gateway directly via the external IP or hostname. - … - `onboarding` V1alpha1MeshExpansionSettingsOnboardingPlane: Configuration of the `Workload Onboarding Plane`. - … - `telemetryStore` ControlPlaneSpecTelemetryStore, required: Configure the store that TSB will use to persist application telemetry data. Select one of the `TelemetryStore` settings to see complete examples. - `elastic` V1alpha1ElasticSearchSettings: Configure an Elasticsearch connection. ```yaml apiVersion: install.tetrate.io/v1alpha1 kind: ControlPlane metadata: name: controlplane namespace: istio-system spec: telemetryStore: elastic: host: elastic port: 5678 protocol: https selfSigned: true version: 7 ``` - … - `meshObservability` ControlPlaneSpecMeshObservability: Configure how the mesh should be observed, which observability functionalities should be enabled to observe your registered services in the mesh, and the store properties that TSB will use to persist application observability data like metrics, traces, logs. If omitted, the operator will assume a demo installation and for your convenience install a demo grade mesh observability setting. Select one of the `MeshObservability` settings to see complete examples. - `demoSettings` CommonMeshObservabilitySettings: Configure mesh observability. The following examples enable the analysis and generation of RED metrics for each endpoint of your registered services. Notice that both, ManagementPlane and ControlPlane, need to be aligned with this configuration. ```yaml apiVersion: install.tetrate.io/v1alpha1 kind: ManagementPlane metadata: name: managementplane spec: meshObservability: settings: apiEndpointMetricsEnabled: true ``` ```yaml apiVersion: install.tetrate.io/v1alpha1 kind: ControlPlane metadata: name: controlplane namespace: istio-system spec: meshObservability: settings: apiEndpointMetricsEnabled: true ``` - … - `settings` CommonMeshObservabilitySettings: Configure mesh observability. The following examples enable the analysis and generation of RED metrics for each endpoint of your registered services. Notice that both, ManagementPlane and ControlPlane, need to be aligned with this configuration. ```yaml apiVersion: install.tetrate.io/v1alpha1 kind: ManagementPlane metadata: name: managementplane spec: meshObservability: settings: apiEndpointMetricsEnabled: true ``` ```yaml apiVersion: install.tetrate.io/v1alpha1 kind: ControlPlane metadata: name: controlplane namespace: istio-system spec: meshObservability: settings: apiEndpointMetricsEnabled: true ``` - … - `tier1Cluster` boolean: **DEPRECATED**: This should not be set through Control plane API Instead use TSB Cluster API. Indicates that this cluster is used for tier1 gateways. Tier one clusters can only contain tier 1 gateways. Non-tier1 clusters contain tier2 gateways but not tier 1. - `secrets` V1alpha1Secrets: Secrets available in the ControlPlane installation. - `tsb` SecretsTSB: Secrets to reach the TSB Management Plane. - `cacert` string: CA certificate used to verify TLS certs exposed the Management Plane (front envoy). - `elasticsearch` SecretsElasticSearch: Secrets to reach the Elasticsearch. - `username` string: The username to access Elasticsearch. - `password` string: The password to access Elasticsearch. - `cacert` string: Elasticsearch CA cert TLS used by control plane to verify TLS connection. - `xcp` V1alpha1SecretsXCP: Secrets to reach the XCP Central in the Management Plane. - `autoGenerateCerts` boolean: Enabling this will auto generate XCP Edge certificate if mTLS is enabled to authenticate to XCP Central. Requires cert-manager. - `rootca` string: CA certificate of XCP components. - `rootcakey` string: Key of the CA certificate of XCP components. - `edge` XCPEdge: Secrets for the XCP Edge component. - … - `clusterServiceAccount` SecretsClusterServiceAccount: Cluster service account used to authenticate to the Management Plane. - `clusterFQN` string: TSB FQN of the onboarded cluster resource. This will be generate tokens for all Control Plane agents. - `JWK` string: Literal JWK used to generate and sign the tokens for all the Control Plane agents. - `encodedJWK` string: Base64-encoded JWK used to generate and sign the tokens for all the Control Plane agents. - `operator` V1alpha1Operator: Operator values for the TSB operator application. - `deployment` V1alpha1OperatorDeployment: Values for the TSB operator deployment. - `affinity` InstallkubernetesAffinity - … - `annotations` object - `env` InstallkubernetesEnvVar[] - … - `podAnnotations` object: Custom collection of annotations to add to the pod. - `replicaCount` integer: Number of replicas managed by the deployment. - `strategy` InstallkubernetesDeploymentStrategy - … - `tolerations` Corev1Toleration[] - … - `service` V1alpha1OperatorService: Values for the TSB operator service. - `annotations` object - `serviceAccount` V1alpha1OperatorServiceAccount: Values for the TSB operator service account. - `annotations` object: Custom collection of annotations to add to the service account. - `imagePullSecrets` string[]: Collection of secrets names required to be able to pull images from the registry. - `pullSecret` string - `pullUsername` string: Used along pull password and the provided image registry to generate a Docker config JSON that will be stored as a pull secret. - `pullPassword` string: Used along pull username and the provided image registry to generate a Docker config JSON that will be stored as a pull secret. ## Other responses - `default`: An unexpected error response. --- [API](https://skmtc.dev/tetrate/apis/tetrate-service-bridge-api.md) - [All operations](https://skmtc.dev/tetrate/apis/tetrate-service-bridge-api/llms.txt) - [OpenAPI document](https://skmtc.dev/tetrate/apis/tetrate-service-bridge-api/revisions/2f19c3a1ae57?raw)