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.

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/v1alpha1/clusters/onboard-url
```
Where {server_name} is the 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/v1alpha1/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"
    },]
}

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.
`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.

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/v1alpha1/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/v1alpha1/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 v1alpha1/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/v1alpha1/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/v1alpha1/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/v1alpha1/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.