---
title: "Cluster Expansion"
component: "tigergraph-server"
version: "4.3"
module: "cluster-and-ha-management"
html_url: "/tigergraph-server/4.3/cluster-and-ha-management/expand-a-cluster"
canonical_url: "https://www.tigergraph.com/docs/tigergraph-server/4.3/cluster-and-ha-management/expand-a-cluster"
markdown_url: "https://www.tigergraph.com/docs/tigergraph-server/4.3/cluster-and-ha-management/expand-a-cluster.md"
---

[View as HTML](https://www.tigergraph.com/docs/tigergraph-server/4.3/cluster-and-ha-management/expand-a-cluster)

# Cluster Expansion

Expanding a cluster adds more nodes to the cluster. During the expansion, the cluster's data is redistributed across the expanded cluster. You can also change replication factor or enable [region-awareness](https://www.tigergraph.com/docs/tigergraph-server/4.3/cluster-and-ha-management/region-aware.md) during an expansion.

Expanding a cluster may make sense for several reasons:

* to improve query performance
* to improve system availability
* to improve fault tolerance

Cluster expansion requires several minutes of cluster downtime. The exact amount of downtime varies depending on the size of your cluster.

During cluster expansion, the system enforces **locking** among other cluster-critical operations (including backup/restore, `CONFIG APPLY`, and upgrades). Only one such operation can hold the lock at a time; other operations will be rejected or canceled.

> [!NOTE]
> If your TigerGraph cluster uses a seeded license, please contact [TigerGraph support](mailto:support@tigergraph) to obtain an unseeded temporary license before expanding your cluster.

## 1\. Before you begin

> [!NOTE]
> You must adhere to all of the following requirements.

* The new nodes must already have **exactly the same version** of TigerGraph software installed as the nodes you are expanding from.
* The new nodes must not have any data you wish to keep.
* Ensure that the cluster is not using shared storage. Cluster expansion does not support shared storage.
* Ensure that no loading jobs, queries, or REST requests are running on the original or the expansion target.
* If the original cluster is a single node installation, make sure the IP used is not a [local loopback address](https://en.wikipedia.org/wiki/Localhost) such as 127.0.0.1.

> [!NOTE]
> You can check the IP address of your original cluster using `gadmin config get System.HostList`. If it is a loopback IP, you can update it to be the internal IP using the following script:
> 
> ```console
> $ gadmin config set System.HostList '[{"Hostname":"'$(ip a | grep "inet " | awk 'FNR == 2 {print $2}' | awk -F "/" '{print $1}')'","ID":"m1","Region":""}]'
> $ gadmin config apply -y
> $ gadmin restart all -y
> ```

> [!NOTE]
> Advice and Precautions
> 
> * Obtain a few key measures for the state of your data before the expansion, such as vertex counts/edge counts or certain query results. This will be useful in verifying data integrity after the expansion completes.
> * Perform a full backup of your existing system before performing the expansion.

## 2\. Procedure

### 2.1\. Identify new cluster replication and partition

Before running any commands to expand a cluster, make sure you have a clear idea of how the new cluster should be distributed. You should have the following information:

* The new replication factor of the cluster
* The new partitioning factor of the cluster
* The IP addresses of the new nodes to be added to the cluster

### 2.2\. Expand the cluster

To expand the cluster, run the `gadmin cluster expand` command as shown. If the expansion involves changing the replication factor, use the `--ha` option to indicate the new replication factor:

```console
$ gadmin cluster expand node_ip_list [--ha <replication_factor>]
```

`node_ip_list` is the machine aliases of the nodes you are adding to the cluster mapped to their IP addresses with a colon(`:`), and separated by a comma. Below is an example:

```console
$ gadmin cluster expand m3:10.128.0.81,m4:10.128.0.82 --ha 1
```

We suggest naming the new nodes following the convention of `m<count>`, such as `m1`, `m2`, and `m3` for a 3-node cluster. If you are adding a fourth node, then the fourth node would be named `m4`. If you decide to name them differently, make sure that all names are unique within the cluster.

#### 2.2.1\. Supply a staging location

Extra disk space is required during cluster expansion. If more space is not available on the same disk, you can supply a staging location on a different disk to hold temporary data:

```console
$ gadmin cluster expand m3:192.168.1.3,m4:192.168.1.4 --stagingPath /tmp/
```

If you choose to supply a staging location, make sure that the TigerGraph Linux user has write permission to the path you provide. The overall amount of space required for expansion on each node is `(1 + ceiling(oldPartition/newPartition) ) * dataRootSize`.`oldPartition` and `newPartition` stand for the partitioning factors of the cluster before and after expansion, respectively; `dataRootSize` stands for the size of the data root folder on the node.

For example, assume you are expanding from a 6-node cluster with a replication factor of 2 and a partitioning factor of 3, to a 10-node cluster with a replication factor of 2 and a partitioning factor of 5, and the size of the data root folder on a node is 50GB. You would need more than `(1 + ceiling(3/5)) * 50) = 100 GB` of free space on the staging path.

#### 2.2.2\. Configure region awareness

If you need to enable <region-aware>, the format of `node_ip_list` needs to include region information.

* Enable Region Aware
* Disable Region Aware

```console
$ gadmin cluster expand us-east-1:m3:192.168.1.3,us-east-2:m4:192.168.1.4 --region-aware
```

```console
$ gadmin cluster expand m3:192.168.1.3,m4:192.168.1.4 --region-aware=false
```

If you do not need to configure region aware, you do not need to specify `region-aware` option, and the option will be consistent with the current cluster.

### 2.3\. Verify success and delete temporary files

When the expansion completes, you should see a message confirming the completion of the cluster change. The message will also include the location of the temporary files created during the expansion.

Verify data integrity by comparing vertex/edge counts or query results. After confirming a successful expansion, delete the temporary files to free up disk space.
