Attach a new cluster to the mesh

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

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

Prerequisites 🔗︎

The Backyards 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 Backyards service.

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 backyards istio cluster status command.
Attach the peer cluster to the mesh using one of the following commands.
- To attach the cluster with the default options, run:
```
backyards istio cluster attach <PEER_CLUSTER_KUBECONFIG_FILE>
```
  Note: If the name of the cluster cannot be used as a Kubernetes resource name (for example, because it contains the underscore or another special character), you must manually specify a name to use when you are attaching the cluster to the service mesh.
  
  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:
```
backyards istio cluster attach <PEER_CLUSTER_KUBECONFIG_FILE> --name <kubernetes-compliant-cluster-name>
```
- To specify the network name, run:
```
backyards istio cluster attach <PEER_CLUSTER_KUBECONFIG_FILE> --network-name <network-name>
```
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:
```
backyards istio cluster status
```
The process is finished when you see Available in the Status field of all clusters.
(Optional) Open the Backyards dashboard and verify that the new peer cluster is visible in the Topology view.