Onboard a Cluster to Tanzu Service Mesh

To manage the microservices in your application with Tanzu Service Mesh, you must onboard the clusters where the microservices are deployed. Onboarding involves registering the cluster with Tanzu Service Mesh and installing Tanzu Service Mesh on the cluster.

During the onboarding, you must apply a YAML file to the cluster. The YAML file contains the Kubernetes configuration required for the registration of the cluster with Tanzu Service Mesh.

You also generate a security token during the onboarding. This security token is used to establish and maintain a secure connection between Tanzu Service Mesh and your cluster while it is being registered.

You must also provide the identifier for the cluster in Tanzu Service Mesh. This identifier can be different from the name of the cluster in your environment.

In your API call to onboard the cluster (see step 3), you can set a adminOwnedNamespaceManagement parameter to specify that a cluster administrator will own the labeling of namespaces for Istio injection in the cluster. If this parameter is set, the cluster administrator will be able to manually label namespaces in the cluster using kubetcl, without Tanzu Service Mesh overriding the labeling changes. For more information about customer-mananaged namespace labeling, see Customer-Managed Namespace Labeling. With this parameter set, Tanzu Service Mesh-managed namespace inclusion rules for the cluster become unavailable in the UI. If you set the parameter and also define namespace inclusion rules for the cluster in your request, the inclusion rules will not take effect on the cluster. For more information about namespace inclusion rules, see Define Namespace Inclusions.

Caution:

When the adminOwnedNamespaceManagement parameter is set for a cluster, Tanzu Service Mesh delegates namespace labeling to the cluster administrator, so labeling for sidecar injection will be performed with kubectl. In this case, Tanzu Service Mesh no longer owns namespace labeling on the cluster and does not have visibility into the actual namespace labeling state.

If the adminOwnedNamespaceManagement parameter is set to false for the cluster at a later stage, Tanzu Service Mesh may not have the most up-to-date state of labels on the namespaces. Consider the following example:

A user sets adminOwnedNamespaceManagement to true for a cluster to delegate all responsibility for namespace labeling to the cluster administrator.
The cluster administrator performs labeling on the cluster and sets istio-injection=enabled for a namespace on the cluster or removes a label that was previously set.
If at a later stage the user sets adminOwnedNamespaceManagement to false to return control over namespace labeling to Tanzu Service Mesh, the namespace inclusions list for the cluster in the Tanzu Service Mesh UI may not show the most up-to-date namespace inclusion state for Istio injection.

If the adminOwnedNamespaceManagement parameter is set to false, it is up to the Tanzu Service Mesh administrator to make sure that the namespaces that need to be injected with sidecars are selected and that no labels have been accidentally removed by Tanzu Service Mesh due to lack of constant visibility of the labeling state.

In a later release, a mechanism will be provided to reconcile the inclusions list when the ownership of namespace labeling is switched back and forth between Tanzu Service Mesh and the cluster administrator.

Prerequisites

Verify that the following prerequisites are met:

Your environment meets the requirements listed in Tanzu Service Mesh Hardware and Software Requirements.
You have an API token and an access code to authenticate your requests to the Tanzu Service Mesh API. You must use the access code in the csp-auth-token header in your requests. For information about generating an API token and getting an access code, see Authentication with the Tanzu Service Mesh REST API.

Procedure

To get the URL of the registration YAML file for your cluster, submit the following request.
```
GET https://{server_name}/tsm/v1alpha2/clusters/onboarding-url
```
Where {server_name} is the host name of the Tanzu Service Mesh server (for example, prod-1.nsxservicemesh.vmware.com).

The response contains the URL of the registration YAML.
In a terminal window, to apply the registration YAML to your cluster, run the following kubectl command, including the returned URL in the command.
```
kubectl --context {cluster_name} apply -f https://{server_name}/cluster-registration/k8s/operator-deployment.yaml
```
Where {cluster_name} is the name of your cluster, and {server_name} is the name of the Tanzu Service Mesh server.

Submit the following request.

PUT https://{server_name}/tsm/v1alpha2/projects/default/clusters/{cluster_id}?createOnly=true

{cluster_id} is the identifier that you want to give to your cluster in Tanzu Service Mesh. The cluster_id cannot contain special characters, such as a number sign (#), at sign (@), apostrophe ('), and underscore (_), and uppercase letters.

Set the createOnly parameter in the request to true to register your cluster with Tanzu Service Mesh.

To enable automatic Istio sidecar injection for namespaces in the cluster and define namespace inclusion rules, use enableNamespaceInclusions and namespaceInclusions. For more information, see Define Namespace Inclusions.

Note:

Set createOnly to false only if you want to update an existing cluster.

Request Body

{
  "displayName": "string",
  "description": "string",
  "tags": [
    "string"
  ],
  "labels": [
    {
      "key": "string",
      "value": "string"
    }
  ],
  "autoInstallServiceMesh": false,
  "enableNamespaceExclusions": false,
  "namespaceExclusions": [],
  "proxyConfig": {
    "proxy": "Explicit",
    "protocol": "HTTP",
    "host": "string",
    "port": 0,
    "username": "string",
    "password": "string",
    "certificate": "string"
  },
  "autoInstallServiceMeshConfig": {
    "restrictDefaultExternalAccess": true
  },
  "registryAccount": "string",
  "caLabels": [
    {
      "key": "string",
      "value": "string"
    }
  ],
  "enableInternalGateway": false,
  "enableNamespaceInclusions": true,
  "namespaceInclusions": [{
      "match": "prod-cluster",
      "type": "EXACT"
    }, 
    {"match": "acme",
      "type": "START_WITH"
    },],
   "adminOwnedNamespaceManagement": true
}

Table 1. Request Body Properties
Property	Data type	Required/Optional	Description
`displayName`	String	Required	The name that you want the cluster to have in the Tanzu Service Mesh Console user interface. This parameter has a minimum length of 2 characters and a maximum length of 256 characters. Note: The `displayName` can be the same as the `cluster_id` or can be different from `cluster_id` .
`description`	String	Optional	Optional description of the cluster.
`tags[]`	List	Required	Tags applied to the cluster. Currently not used. Leave this property empty.
`labels[]`	List	Optional	Configuration labels associated with the cluster. Currently not used. Leave this property empty.
`autoInstallServiceMesh`	Boolean	Required	Specifies whether to automatically install the default available version of Tanzu Service Mesh on the cluster. To choose the version to install, set this parameter to `false`. You install the version you choose by submitting a PUT request to clusters/{cluster_id}/apps/{appID}(see step 7). Note: If you set this parameter to `true`, the default available version of Tanzu Service Mesh will be installed on the cluster.
`caLabels[]`	List	Optional	Contains a certificate authority (CA) label that is associated with a specific CA configuration.
`caLabels[].key`	String	Optional	CA label key value. Set this field to `CertificateAuthority`.
`caLabels[].value`	String	Optional	A CA label associated with a specific CA configuration. Passing a CA label in the request will apply the associated CA configuration to the cluster.
`enableNamespaceExclusions`	Boolean	Optional	This parameter is used to set namespace exclusions and is being deprecated. It is included for backward compatibility. Set the parameter to `false`.
`namespaceExclusions[]`	List	Optional	This array is used with `enableNamespaceExclusions` to define namespace exclusion rules and is being deprecated. Leave the array empty.
`enableNamespaceInclusions`	Boolean	Optional	This parameter is used to set namespace inclusions and is used with `namespaceInclusions`. For more information about namespace inclusions, see Define Namespace Inclusions.
`namespaceInclusions[]`	List	Optional	This array is used with `enableNamespaceInclusions` to define namespace inclusion rules. For more information about namespace inclusion rules, see Define Namespace Inclusions.
`adminOwnedNamespaceManagement`	Boolean	Optional	To specify that a cluster administrator will own the labeling of namespaces for Istio injection in the cluster, set `adminOwnedNamespaceManagement` to `true`. Important: When you set `adminOwnedNamespaceManagement` to `true`, you delegate all responsibility for namespace labeling, including selection for inclusion, to the cluster administrator who operates the cluster. This makes it no longer possible to create namespace inclusion rules through the API. For more information about the Cluster admin owned setting and how it affects namespace labeling, see Customer-Managed Namespace Labeling. To be able to define namespace inclusion rules in the `namespaceInclusions` array, set this parameter to `false`. If your request contains `adminOwnedNamespaceManagement` set to `true` and defines namespace inclusion rules within `namespaceInclusions`, the inclusion rules will not take effect on the cluster.

Important:

If you set both enableNamespaceInclusions and enableNamespaceExclusions to false, the system will exclude namespaces from automatic Istio sidecar injection based on the conditions provided in the namespaceExclusions field. If no namespace exclusion conditions are given, all the namespaces in the cluster, except Kubernetes system namespaces such as kube-system and kube-public, will be included for automatic sidecar injection.

Because the cluster is not registered with Tanzu Service Mesh, the registered field in the response contains false, and the token field contains the security token for the cluster.

Note:

If a cluster is already registered with Tanzu Service Mesh, the registered field contains true, and token is empty.
systemNamespaceExclusions in the response contains a list of the system namespaces that are excluded from Tanzu Service Mesh.

To establish a secure connection between the cluster and Tanzu Service Mesh and register the cluster with Tanzu Service Mesh, run the following kubectl command.
```
kubectl -n vmware-system-tsm create secret generic cluster-token --from-literal=token={token}
```
Replace {token} with the security token returned by the API for a request to PUT https://{server_name}/tsm/v1alpha2/clusters/{cluster_id} in step 3.
To check the status of the connection between the cluster and Tanzu Service Mesh, submit the following request.
```
GET https://{server_name}/tsm/v1alpha2/clusters/{cluster_id}
```
Where {cluster_id} is the identifier that you provided for the cluster in step 3.
The response includes the following information.
```
{
   "name": string,
   "status":{
      "state": string
   }
}
```
If the connection is established, the state is Connected. The state can be Connecting if the connection is still being established. Wait a few minutes and resend the request. For information about all the possible states that the API returns, see the schema for the GET v1alpha2/clusters/{cluster_id} endpoint in the API Explorer. For information about how to access the API Explorer, see the API Reference section in Overview of the Tanzu Service Mesh REST API.
To install Tanzu Service Mesh on the cluster, submit the following request.

Note:
If you set autoInstallServiceMesh to true in step 3, skip this step.
```
PUT https://{server_name}/tsm/v1alpha2/clusters/{cluster_id}/apps/{app_id} 
```
Replace cluster_id with the identifier you provided for the cluster in step 3 and replace app_id with tsm.

Use the following properties in the request body.
```
{
   "version":"{version}"
}
```
To install the latest available version of Tanzu Service Mesh on the cluster, set version to default. To install a specific version on the cluster, set version to that version (for example, v3.0.0). To get a list of versions available for your cluster, submit a GET request to https://{server_name}/tsm/v1alpha2/clusters/{cluster_id}/apps. In the response, inside availableVersions, the versions that are available for the cluster have the installable field set to true.
The response contains the identifier of the installation job.
To check the status of the installation on the cluster, submit the following request.
```
GET https://{server_name}/tsm/v1alpha2/clusters/{cluster_id}
```
The API returns the following response.
```
{
   "name": string,
   "status":{
      "state": string
   }
}
```
If the state is Ready, Tanzu Service Mesh has been successfully installed on the cluster. The state can be Installing. This state means that the installation is still in progress. Wait a few minutes and rerun the command.
To onboard additional clusters, repeat steps 1–8.

Results

The cluster is onboarded. Tanzu Service Mesh also starts monitoring the services in the cluster and collecting infrastructure and service metrics (such as number of nodes and services, requests per second, latency, and CPU usage). The cluster appears in the Tanzu Service Mesh Console user interface with the display name you specified. You can view summary information about the cluster's infrastructure, a topology graph of the services in the cluster, and key metrics on the Home page of the Tanzu Service Mesh Console user interface. For more information, see View the Summary Infrastructure and Service Information in Getting Started with Tanzu Service Mesh.