Expand 6-node ARTESCA with 2 MongoDB shards

Prior to ARTESCA v4.1, 6-node clusters were deployed with 1 MongoDB shard. Upgrading to 4.3.3 or higher does not reconfigure the sharding topology.

This guide explains how to reconfigure the sharding topology for improved scalability.

Prerequisites

Before expanding your cluster, ensure you have:

• A 6-node cluster deployed with ARTESCA v4.1.0 or higher.

• Access to the ARTESCA bootstrap node.

• The latest ARTESCA base ISO installed. This procedure must be run after upgrading to ARTESCA v4.1.0 or higher.

Considerations

Important

The procedure is not reversible.

Expansion Procedure

Ensure MongoDB Config Server has a Primary Member Running

1. Check the status of the MongoDB Config Server. The Config Server will be in charge of rebalancing the data, after the new shards are deployed.

   [artesca-os@bootstrap ~]$
   

   sudo kubectl --kubeconfig /etc/kubernetes/admin.conf exec data-db-mongodb-sharded-configsvr-0 -n zenko -c mongodb -- \
      bash -c "mongosh --quiet \$MONGODB_APP_DATABASE -u root -p \$MONGODB_ROOT_PASSWORD --authenticationDatabase admin --eval \
      'rs.status().members.forEach(member => print(member.name + \" \" + member.stateStr))'"
   

2. Ensure one of the members is in the PRIMARY state. If not, follow the instructions in Full Sync a MongoDB Member.

Create New MongoDB Volumes

Before deploying additional shards, you need to create new volumes for the MongoDB instances through the ARTESCA UI.

Note

This manual volume creation procedure is only required when expanding existing 6-nodes clusters which were installed on older ARTESCA versions. For fresh installations, the installer automatically handles MongoDB volume creation and labeling.

1. Access the ARTESCA UI and navigate to Platform > Volumes > Create Volume.

2. Create volumes for the new MongoDB shard. You must create volumes on nodes that will host the new shard replicas. Target the nodes that are not already hosting a MongoDB shard volume.

   Important

   • Never place two volumes on the same node. Create one volume per node for the new shard (typically 3 nodes for a replica set).

   • All volumes must have the same size as other existing volumes.

   • Use the same storage class and device configuration as your existing MongoDB volumes. You may get the current volume size with the following command:

     [artesca-os@bootstrap ~]$
     

     sudo kubectl --kubeconfig=/etc/kubernetes/admin.conf get pv -l app.kubernetes.io/name=mongodb -o jsonpath='{.items[0].spec.capacity.storage}'
     

   For a 6-node cluster expanding from 1 to 2 shards, create volumes on 3 additional nodes with the following configuration:

   Field	Value	Description
   Name	data-mongodb-shard1.<node_name>	Volume name for the new MongoDB shard.
   Node	Select target node.	Choose nodes that don’t already have MongoDB shard volumes.
   Labels	app.kubernetes.io/part-of: zenko app.kubernetes.io/name: mongodb-shard1	Required labels for MongoDB shard identification.
   Storage Class	ssd-ext4	Use the same storage class as existing MongoDB volumes.
   Type	LVMLogicalVolume	Standard type for MongoDB data volumes.
   Volume Capacity	The same capacity as the existing MongoDB volumes.	Ensures consistent volume sizing across shards.
   Volume Group Name	vgartesca	Standard volume group for Artesca storage.
   Force LV creation	Set to NO.	Use default LV creation behavior.

3. Repeat the volume creation for all three nodes that will participate in the new shard.

4. Verify the volumes are created and available, with the right labels:

   [artesca-os@bootstrap ~]$
   

   sudo kubectl --kubeconfig=/etc/kubernetes/admin.conf wait --for=jsonpath='{.status.phase}'=Available pv -l app.kubernetes.io/name=mongodb-shard1,app.kubernetes.io/part-of=zenko --timeout=15m
   

Deploy New Shards

1. Scale the mongos instances to ensure they can route queries to the new shards:

   [artesca-os@bootstrap ~]$
   

   sudo kubectl --kubeconfig=/etc/kubernetes/admin.conf scale statefulset data-db-mongodb-sharded-mongos -n zenko --replicas=6
   

   Then wait for the new mongos pods to be deployed:

   [artesca-os@bootstrap ~]$
   

   sudo kubectl --kubeconfig=/etc/kubernetes/admin.conf rollout status --watch --timeout=10m sts/data-db-mongodb-sharded-mongos -n zenko
   

2. Deploy the new shards by upgrading the data services:

   [artesca-os@bootstrap ~]$
   

   sudo ./artesca-installer upgrade data post
   

   Note

   The upgrade process will automatically detect the new volumes created through the UI and configure the additional MongoDB shards accordingly. The upgrade command:

   • Detects existing MongoDB StatefulSets to determine current shard configuration

   • Automatically configures additional shards if new volumes with appropriate labels are found

   • Skips multi-shard configuration if additional volumes are not present

   • Does not require any configuration file changes

Rebalance Data Across Servers

After expanding your cluster with new shards, a rebalance may happen. This process is done in the background and may slightly affect ARTESCA performances until it is completed.

To monitor the balancing process, you can access the MongoDB Grafana dashboard. In the ARTESCA UI, open the Data Management menu and select the Data Services tab, then click Advanced Metrics.