topology

Encapsulates commands that manipulate store topologies. Examples are redistribution/rebalancing of nodes or changing replication factor. Topologies are created and modified using this command. They are then deployed by using the plan deploy-topology command. For more information, see plan deploy-topology. The subcommands are as follows:

topology change-repfactor

topology change-repfactor -name <name>  -pool <pool name>
    -zn <id> | -znname <name> -rf <replication factor>

Modifies the topology to change the replication factor of the specified zone to a new value. The replication factor may be decreased for secondary zones, but decreasing it for primary zones is not currently supported.

When increasing the replication factor, the command may create Replication Nodes or Arbiter Nodes and may remove Arbiter Nodes only in the zone specified in the command. If the change in replication factor increases the total primary replication factor equal to two and the zone is configured to allow Arbiters, then Arbiters are created in that zone. If the change in replication factor increases the total primary replication factor from two to a number greater than two and if the zone contained Arbiters, then the Arbiters are removed from the zone. If some other zone contained Arbiters, a topology rebalance must be performed to remove the Arbiters from the topology.

For more information on increasing the replication factor, see Increase Replication Factor.

When decreasing the replication factor for a secondary zone, the command will remove the replication nodes from the zone.

If you want to remove a secondary zone, then the replication factor for that secondary zone should be reduced to zero.

After reducing the replication factor to zero, do the following steps to remove the secondary zone:

Remove any admins in the zone using plan remove-admin command
Remove the Storage Nodes in the zone using plan remove-sn command
Remove the zone using plan remove-zone command

topology change-zone-arbiters

topology change-zone-arbiters -name <name>
    {-zn <id> | -znname <name>}  {-arbiter | -no-arbiter}

Modifies the topology to change the Arbiter Node attribute of the specified zone.

topology change-zone-master-affinity

topology change-zone-master-affinity -name <name>
    -zn <{-no-master-affinity | -master-affinity}

Modifies the topology of the existing specified zone to -no-master-affinity, or to -master-affinity. For example:

topology change-zone-master-affinity -name new-topo -zn zn1 -no-master-affinity

Use this command after initially deploying a topology (plan deploy-zone).

topology change-zone-type

topology change-zone-type -name <name>
    {-zn <id> | -znname <name>} -type {primary | secondary}

Modifies the topology to change the type of the specified zone to a new type.

If one or more zones have their type changed and the resulting topology is deployed using the plan deploy-topology command, the following rules apply:

The plan waits for up to five minutes for secondary nodes that are being converted to primary nodes to catch up with their masters.
The plan will fail, and print details about lagging zones and nodes, if a quorum of secondary nodes in each shard fails to catch up within the required amount of time. This behavior helps to reduce the time that a newly added primary node cannot become a master, and so is not able to contribute to availability.
Because this command can only be performed successfully if quorum can be maintained, it does not result in data loss.

topology clone

topology clone -from <from topology> -name <to topology>

topology clone -current -name <to topology>

Clones an existing topology so as to create a new candidate topology to be used for topology change operations.

topology contract

topology contract -name <name> -pool <pool name>

Modifies the named topology to contract storage nodes. For more information, see Contracting a Topology.

topology create

topology create -name <candidate name> -pool <pool name> [-json]
    -partitions <num>

Creates a new topology with the specified number of partitions using the specified storage pool.

You should avoid using the dollar sign (‘$’) character in topology candidate names. The CLI displays a warning when trying to create or clone topologies whose names contain the reserved character.

If the primary replication factor is equal to two, the topology create command will allocate Arbiter Nodes on the Storage Nodes in a zone that supports hosting Arbiter Nodes. During topology deployment, an error is issued if there are not enough Storage Nodes for Arbiter Node distribution. A valid Arbiter Node distribution is one in which the Arbiter Node is hosted on a Storage Node that does not contain other members of its Replication Group.

For more information on creating the first topology candidate, see Make the Topology Candidate.

kv-> topology create -name mytopo -pool snpool -json -partitions 20
{
	"operation" : "topology create",
	"returnCode" : 5000,
	"description" : "Operation ends successfully",
	"returnValue" : {
		"store" : "mystore",
		"numPartitions" : 20,
		"sequence" : 32,
		"zone" : [ {
		"id" : "zn1",
		"name" : "1",
		"repfactor" : 1,
		"type" : "PRIMARY"
		}, {
	"id" : "zn2",
	"name" : "2",
	"repfactor" : 1,
	"type" : "PRIMARY"
	}, {
	"id" : "zn3",
	"name" : "3",
	"repfactor" : 1,
	"type" : "PRIMARY"
	} ],
	"sns" : [ {
	"id" : "sn1",
	"zone_id" : "zn1",
	"host" : "localhost",
	"port" : 20000,
	"capacity" : 1,
	"rns" : [ "rg1-rn1" ],
	"ans" : [ ]
	}, {
	"id" : "sn2",
	"zone_id" : "zn2",
	"host" : "localhost",
	"port" : 21000,
	"capacity" : 1,
	"rns" : [ "rg1-rn2" ],
	"ans" : [ ]
	}, {
	"id" : "sn3",
	"zone_id" : "zn3",
	"host" : "localhost",
	"port" : 22000,
	"capacity" : 1,
	"rns" : [ "rg1-rn3" ],
	"ans" : [ ]
	} ],
	"shards" : [ {
		"id" : "rg1",
		"numPartitions" : 20,
		"rns" : [ "rg1-rn1", "rg1-rn2", "rg1-rn3" ],
		"ans" : [ ]
		} ],
	"name" : "mytopo"
	}
}

topology delete

topology delete -name <name>

Deletes a topology.

topology list

topology list

Lists existing topologies.

topology preview

topology preview -name <name> [-start <from topology>]

Describes the actions that would be taken to transition from the starting topology to the named, target topology. If -start is not specified, the current topology is used. This command should be used before deploying a new topology.

topology rebalance

topology rebalance -name <name> -pool <pool name>
    [-zn <id> | -znname <name>]

Purpose of topoplogy rebalance command

In a data store, the topology rebalance command modifies a non-compliant topology to a compliant topology state, making it a balanced topology. For a compliant topology, you must ensure that topologies follow a specific set of rules. For more information, see Determining Your Store’s Configuration.

The arguments for the topology rebalance command include:

-name: The name of the topology you want to balance.
-pool: The name of the Storage Node pool.
-zn <id> or -zname <name>: These arguments are optional, and you can either provide the id or name of the zone.

Note: If the optional -zn or -zname flag is used, only Storage Nodes from the specified zone are used for the operation.

If there are any changes made to the physical characteristics of the data store, it could become unbalanced, for example:

The capacity of the Storage Node is increased or decreased resulting in overcapacity or undercapacity respectively.
There are changes in the disk sizes of Storage Nodes, Replication Nodes.
The Arbiter Nodes are present when the topology does not support them.
The Arbiter Nodes are not present when the topology supports them.
The Arbiter Nodes are present in a zone with Replication Factor greater than zero when a zone with zero Replication Factor exists.
There are changes in the shard configurations, such as changes in the number of partitions in a shard due to an elasticity change, and so on.

The command ensures compliance by resolving violations and notes arising from the physical changes. It adds, moves, or removes Arbiter Nodes and Replication Nodes. For example, the topology rebalance command:

Moves the Replication Nodes to match the new capacity of the Storage Nodes.
Adds Arbiter Nodes if the new topology supports them and the old topology does not.
Removes Arbiter Nodes if the old topology supported them and the new one does not.
Moves Arbiter Nodes to a zero Replication Factor zone if they are hosted in a zone with Replication Factor greater than zero.
Initiates partition migration when there is a change in the shard configurations.

To understand more about the scenarios in which you can use the command, see Usage of topology rebalance command.

You can verify the topology of the data store by using the verify command. For more information, see Verifying the Store.

verify configuration

Note: The topology rebalance command will not be needed when the topology is fully compliant with no changes in the physical characteristics.

Usage of topology rebalance command

When you initially deploy the data store, you establish its configuration, or topology, during setup, ensuring it meets all requirements without needing rebalancing. If there is any change in the physical characteristics of the topology, such as the store’s configuration, capacity, and so on, then:

Run the verify configuration command to view any violations or verification notes.
Run the topology rebalance command to fix the non-compliant topology.

Following are some of the scenarios where the use of the topology rebalance command can fix violations/verification notes and help in the transition of a non-complaint topology to a compliant topology:

Replication Node allocation violations:
- When you modify a storage node’s defined capacity using the command plan change-parameters to a value insufficient to host all its Replication Nodes, it causes an imbalance, resulting in overcapacity.
```
Verification violation: [sn1]  sn1 has 2 repNodes and is over its capacity limit of 1
```
- If Storage Nodes have more capacity than the Replication Nodes they host, the data store underutilizes its resources, resulting in undercapacity.
```
Verification note: [sn1]  sn1 has 0 RepNodes and is under its capacity limit of 1
```
  Note:
  - The topology rebalance command resolves overcapacity and undercapacity by moving the Replication Nodes from overutilized Storage Nodes to underutilized ones. This optimizes the use of all available resources.
  - If there is no overcapacity issue, the topology rebalance command can't actively resolve undercapacity, conversely, if there is no undercapacity issue, it can't resolve overcapacity.
Arbiter Node allocation violations:
- Considering there is a primary zone with a Replication Factor of two, deploy a new zone with zero Storage Node capacity and Replication Factor. This new zone can only host Arbiter Nodes. In this case, you see a violation due to insufficient Arbiter Nodes. For more information, see Arbiter Nodes in Concepts Guide.
```
Verification violation: [rg1]  The shard rg1 does not have an Arbiter.
```
  The topology rebalance command will resolve the issue by moving the Arbiter Node in the same shard along with the other Replication Nodes.
- Consider a topology already hosting Arbiter Nodes, and you deploy a new zone containing a Storage node with capacity one and arbiters set to false. Since the updated topology can’t host Arbiter Nodes, you will receive a verification note for excess Arbiter Nodes.
```
Verification note: [rg1]  Shard rg1 has an Arbiter when it should not.
```
  The topology rebalance command resolves the issue by replacing the Arbiter Node with the added Storage Node in the same shard.
- In the topology, an Arbiter Node is in a zone with other Replication Nodes, while another zone exists with a Replication Factor of zero, known as an Arbiter-only zone. The violation indicates that you must move the Arbiter Node to a zone with a zero Replication Factor.
```
Verification violation: [rg1-an1]  rg1-an1 is hosted in zone zn1; a better zone host is zn2
```
  For high availability and better performance, the topology rebalance command will move the Arbiter Node to a zone with a zero Replication Factor.
- When you allow arbiters in a zone initially and then change the configuration to disallow arbiters, the verify configuration command still shows the initial setting with arbiters set to true.
```
Verification violation: [rg1-an1]  sn3 doesn't allow arbiters but hosts rg1-an1
```
  The topology rebalance command will fix the violation by removing the Arbiter Node and updating the topology’s configuration.
When there is a change in the disk configuration of Storage Nodes in a shard, the topology rebalance command will initiate a partition migration. This forms a balance in the partitions across the shards proportional to the disk sizes.
```
Verification note: [rg1]  rg1 should have 80 partitions if balanced, but has 50
Verification note: [rg2]  rg2 should have 20 partitions if balanced, but has 50
```
Note:
- The topology rebalance command does not migrate partitions if there are changes in the minimum number of Storage Nodes in a shard that is less that is less than half of total. It only performs partition distribution to resolve violations or verification notes without introducing new ones and moves partitions only if the disk space on all Replication Nodes in the shard supports the change.
- During the topology rebalance, the data store’s performance is lower and the chance of a loss of write quorum higher, see Quorum. Therefore, you should perform the topology rebalance operation during the quiet time for the data store.

The topology rebalance command resolves most of the violations to transition the non-compliant topology to a compliant topology. However, you must manually resolve some violations or verification notes for optimal results. See, Violations and Solutions table.

For more information on balancing a non-compliant topology, see Balance a Non-Compliant Topology.

topology redistribute

topology redistribute -name <name> -pool <pool name>

Modifies the named topology to redistribute resources to more efficiently use those available.

For more information on redistributing resources to enhance write throughput, see Increase Data Distribution.

topology validate

topology validate [-name <name>]

Validates the specified topology. If no topology is specified, the current topology is validated. Validation generates violations and notes.

Violations are issues that can cause problems and should be investigated.

Notes are informational and highlight configuration oddities that can be potential issues or may be expected.

For more information, see Validate the Topology Candidate.

topology view

topology view -name <name>

Displays details of the specified topology. Also displays any available Arbiter Node information.