Onboard a Cluster Using the CLI

In addition to onboarding a cluster from the Tanzu Service Mesh UI and through the API, you can onboard a cluster using the Tanzu CLI. Onboarding involves registering a cluster with Tanzu Service Mesh and installing the necessary software components on the cluster.

Onboarding a cluster involves registering the cluster with Tanzu Service Mesh. Before you begin onboarding the cluster, you must prepare a registration YAML file to describe the cluster configuration required for the registration. During onboarding, to register the cluster with Tanzu Service Mesh, you must apply the configuration from the registration YAML file to the cluster.

Using the registration YAML file, you can specify a cluster identifier and a cluster name and configure different onboarding options. For example, if you want to the cluster to connect to Tanzu Service Mesh through your organization's web proxy server, you can describe the proxy settings in the YAML file. If you want to enable automatic Istio sidecar injection for some of the namespaces in the cluster, you can define appropriate namespace inclusion rules in the file. For more information about the onboarding process and these and other onboarding options, see Onboard a Cluster in the Getting Started with VMware Tanzu Service Mesh Guide.

To create a registration YAML file, you must retrieve the cluster registration specification from the Tanzu Service Mesh API and then provide values for the fields in the specification. The following procedure includes instructions on how to create a registration YAML file.

Prerequisites

Verify that your environment meets the requirements listed in Tanzu Service Mesh Environment Requirements and Supported Platforms.
Install the CLI.
Log in to the Tanzu Service Mesh CLI.
Install jq, a command-line JSON processor, and install yq, a command-line YAML, JSON and XML processor. Some of the commands included in the following procedure use jq and yq.

Procedure

To create a registration YAML file, perform the following steps.
1. To retrieve the cluster registration specification from the Tanzu Service Mesh API, run the following command.
```
tanzu sm get spec clusters
```
  The output contains the following specification.
```
apiVersion: clusters.tsm.vmware.com/v1
kind: Cluster
metadata:
  labels:
    projectId: string
  name: string
spec:
  autoInstallServiceMesh: true
  autoInstallServiceMeshConfig:
    restrictDefaultExternalAccess: true
  caLabels:
  - key: string
    value: string
  description: string
  displayName: string
  enableInternalGateway: true
  enableNamespaceExclusions: true
  enableNamespaceInclusions: true
  labels:
  - key: string
    value: string
  namespaceExclusions:
  - match: string
    type: string
  namespaceInclusions:
  - match: string
    type: string
  proxyConfig:
    certificate: string
    host: string
    password: string
    port: 1.2
    protocol: HTTP
    proxy: Explicit
    username: string
  registryAccount: string
  tags:
  - string
```
2. Copy the specification into a YAML file and provide values for the fields.
  - Set name to the ID of the cluster. The cluster ID as a required parameter in making certain calls to the Tanzu Service Mesh API. In the Tanzu Service Mesh Console UI, the cluster ID appears on the cluster details page. After you onboard the cluster, you cannot change the cluster ID. To help identify the cluster in Tanzu Service Mesh, use a friendly cluster ID.
  - Set displayName to the display name for the cluster, that is, the name that you want your cluster to have in the Tanzu Service Mesh Console. The cluster display name can be the same as the cluster ID or can be different. The cluster display name can include only lowercase letters and cannot contain special characters, such as a number sign (#), at sign (@), apostrophe ('), underscore (_), and uppercase letters. To help identify the cluster in Tanzu Service Mesh, use a friendly display name.
  - Set projectId to default.
  - You don't need to include all the fields from the specification in your registration YAML file. Some of the fields are optional. For information about the meaning of the fields in the specification, which fields are mandatory and which are optional, and what value to provide for each field, see the schema of the /v1alpha2/{projectId}/default/clusters/{clusterId} API in API Explorer in Tanzu Service Mesh. Perform the following steps.
    
    Access the Tanzu Service Mesh Console.
    
    In Tanzu Service Mesh Console, click API Explorer on the bottom bar.
    
    In the API Explorer, expand PUT /v1alpha2/{projectId}/default/clusters/{clusterId}.
    
    Under Request Body, click Schema.
    
    The mandatory fields are marked with a red asterisk (*).
  - You can onboard more than one cluster, using a registration YAML file. Make sure that you put --- at the end of the configuration for each cluster in the file.
  - See an example of a registration YAML file below.
  This example of a registration YAML file shows a cluster registration configuration with the minimum required fields.
```
apiVersion: clusters.tsm.vmware.com/v1
kind: Cluster
metadata:
  labels:
    projectId: default
  name: my-sample-cluster
spec:
  displayName: my-sample-cluster
  description: ''
  tags: []
  labels: []
  caLabels:
  - key: CertificateAuthority
    value: TSM
  namespaceExclusions: []
  autoInstallServiceMesh: true
  enableNamespaceExclusions: true
  enableInternalGateway: false
```
3. Save the changes in the file.
To generate a security token for use during onboarding, run this command.
```
token=`tanzu sm apply -f {cluster-registration-file-name}.yaml | jq -r .token`
```
This security token is used to establish a secure connection between Tanzu Service Mesh and your cluster during onboarding.

{cluster-registration-file-name}.yaml is the name of the registration YAML file that you created in step 1.
The command applies the registration YAML file, generates a security token, extracts the token from the output, and stores it in a token variable.
To generate the URL of the Tanzu Service Mesh Saas server where the cluster will be onboarded (the onboarding URL), run the following command.
```
url=`tanzu sm get clusteronboardurls | yq .url`
```
The command generates the onboarding URL for the cluster, extracts the URL from the output, and stores the URL in a url variable.
To apply the configuration from the registration YAML file to the cluster, run the following command.
```
kubectl apply -f  "$url"
```
To create a Kubernetes secret to store the security token and then use the security token from the secret to establish a secure connection between the cluster and Tanzu Service Mesh during onboarding, run the following command.
```
kubectl -n vmware-system-tsm create secret generic cluster-token --from-literal=token=$token
```

Results

The cluster is registered with the specified Tanzu Service Mesh SaaS server based on the onboarding URL, and the Tanzu Service Mesh software components are installed on the cluster. The onboarding takes a few minutes to complete.

To verify that the cluster has been successfully onboarded, run the following command.

tanzu sm get cluster {cluster-id} | yq  .status

If the message field in the output is Tanzu Service Mesh installed and the state field is Ready, the cluster has been successfully onboarded.

Note:

As the onboarding progresses, the output of the command shows the current onboarding state. Repeat the command until you see the Ready state in the output.