Attach a new cluster to the mesh

Service Mesh Manager automates the process of creating the resources necessary for the peer cluster, generates and sets up the kubeconfig for that cluster, and attaches the cluster to the mesh.

Note: If you are using Service Mesh Manager with a commercial license in a multi-cluster scenario, Service Mesh Manager automatically synchronizes the license to the attached clusters. If the peer cluster already has a license, it is automatically deleted and replaced with the license of the primary Service Mesh Manager cluster. Detaching a peer cluster automatically deletes the license from the peer cluster.

To attach a new cluster to the service mesh managed by Service Mesh Manager, complete the following steps. For an overview of the network settings of the cluster, see Cluster network.

Prerequisites

The Service Mesh Manager CLI tool installed on your computer.
Access to the KUBECONFIG file of the cluster you want to attach to the service mesh.
Access to the KUBECONFIG file of the cluster that runs the primary Service Mesh Manager service.
Network connectivity properly configured between the participating clusters.

Steps

Find out the name of the network you want to attach the cluster to.
- By default, every cluster belongs to its own network, where the name of the network is the name of the cluster.
- If you want to attach the cluster to an existing network, you must manually specify the name of the network when you are attaching the cluster to the service mesh using the --network-name option in the next step.
If you have to specify the network name manually, note the name of the network you want to use. You can check the existing network names using the smm istio cluster status command.
On the primary Service Mesh Manager cluster, attach the peer cluster to the mesh using one of the following commands.

Note: To understand the difference between the remote Istio and primary Istio clusters, see the Istio control plane models section in the official Istio documentation. The short summary is that remote Istio clusters do not have a separate Istio control plane, while primary Istio clusters do.

The following commands automate the process of creating the resources necessary for the peer cluster, generate and set up the kubeconfig for that cluster, and attach the cluster to the mesh.
- To attach a remote Istio cluster with the default options, run:
```
smm istio cluster attach <PEER_CLUSTER_KUBECONFIG_FILE>
```
- To attach a primary Istio cluster (one that has an active Istio control plane installed), run:
```
smm istio cluster attach <PEER_CLUSTER_KUBECONFIG_FILE> --active-istio-control-plane
```
  Note: If the name of the cluster cannot be used as a Kubernetes resource name (for example, because it contains the underscore, colon, or another special character), you must manually specify a name to use when you are attaching the cluster to the service mesh. For example:
```
smm istio cluster attach <PEER_CLUSTER_KUBECONFIG_FILE> --name <KUBERNETES_COMPLIANT_CLUSTER_NAME> --active-istio-control-plane
```
  Otherwise, the following error occurs when you try to attach the cluster:
```
could not attach peer cluster: graphql: Secret "example-secret" is invalid: metadata.name: Invalid value: "gke_gcp-cluster_region": a DNS-1123 subdomain must consist of lower case alphanumeric characters, '-' or '.'**
```
- To override the name of the cluster, run:
```
smm istio cluster attach <PEER_CLUSTER_KUBECONFIG_FILE> --name <kubernetes-compliant-cluster-name>
```
- To specify the network name, run:
```
smm istio cluster attach <PEER_CLUSTER_KUBECONFIG_FILE> --network-name <network-name>
```
Note: If you are using Service Mesh Manager with a commercial license in a multi-cluster scenario, Service Mesh Manager automatically synchronizes the license to the attached clusters. If the peer cluster already has a license, it is automatically deleted and replaced with the license of the primary Service Mesh Manager cluster. Detaching a peer cluster automatically deletes the license from the peer cluster.
Wait until the peer cluster is attached. Attaching the peer cluster takes some time, because it can be completed only after the ingress gateway address works. You can verify that the peer cluster is attached successfully with the following command:
```
smm istio cluster status
```
The process is finished when you see Available in the Status field of all clusters.
(Optional) Open the Service Mesh Manager dashboard and verify that the new peer cluster is visible on the MENU > TOPOLOGY page.

If you are looking to deploy your own application, check out Deploy custom application into the mesh for some guidelines.
To detach a cluster, see Detach a cluster from the mesh.