You can use several different options to control when shards are placed on various container servers in the configuration. During startup, you might choose to delay the placement of shards. When you are running all of your container servers, you might need to suspend, resume, or change placement while you maintain servers.
Controlling placement during startup
You can control when shards begin to be placed while your environment is starting. Some control is in place by default. If you do not take any actions to control placement, shards begin to be placed immediately. When shards are placed immediately, the shards might not be placed evenly as subsequent container servers start, and further placement operations run to balance the distribution.
Suspending the balancing of shards prevents uneven shard placement. Before you start your container servers, use the xscmd -c suspendBalancing command to stop the balancing of shards for a specific data grid and map set. After the container servers are started, you can use the xscmd -c resumeBalancing command to begin the placement of shards on the container servers.
Set the placementDeferralInterval property in the server properties file for the catalog server. If you are using the embedded server API, use the setPlacementDeferralInterval method on the CatalogServerProperties interface. This property sets a number of milliseconds before shards are placed on the container servers. The default value for this property is 15 seconds. With the default value, when a container server starts, placement does not start until after the time specified in the property has passed. If multiple container servers are starting in succession, the deferral interval timer is reset if a new container server starts within the given interval. For example, if a second container server starts 10 seconds after the first container server, placement does not start until 15 seconds after the second container server started. However, if a third container server starts 20 seconds after the second container server, placement has already begun on the first two container servers.
When container servers become unavailable, placement is triggered as soon as the catalog server learns of the event so that recovery can occur as quickly as possible.
If you previously used the numInitialContainers attribute, you can continue using the attribute. However, the use of the xscmd -c suspendBalancing and xscmd -c resumeBalancing commands followed by the placementDeferralInterval are suggested over the numInitialContainers attribute to control placement. The numInitialContainers attribute specifies the number of container servers that are required before initial placement occurs for the shards in this mapSet element. The numInitialContainers attribute is in the deployment policy descriptor XML file. If you have both numInitialContainers and placementDeferralInterval set, note that until the numInitialContainers value has been met, no placement occurs, regardless of the value of the placementDeferralInterval property.
Controlling placement after initial startup
You can use the xscmd -c triggerPlacement -g my_OG -ms my_Map_Set command, where my_OG and my_Map_Set are set to values for your data grid and map set, to force placement to occur during a point in time at which placement might not occur otherwise. For example, you might run this command when the amount of time specified by the placementDeferralInterval property has not yet passed or when balancing is suspended.
Use the xscmd -c swapShardWithPrimary command to assign a replica shard to be the new primary shard. The previous primary shard becomes a replica.
Use the xscmd -c balanceShardTypes command to adjust the ratio of primary and replica shards to be equitable among the running container servers in the configuration. The ratio is consistent within one shard on each container server.
When a problem occurs with placing shards on a particular shard container, the shard container is placed in the disabled for shard placement list. The shard containers in this list cannot be used for placement until you re-enable the shard container, or the JVM that is hosting the shard container is recycled. When the JVM is stopped, the shard container is removed. When the JVM is restarted, the container count increments and a new name is used for the shard container for a specified data grid. Problems that might cause a shard container to be disabled include: long garbage collection cycles that are impacting JVM health, DNS or naming configuration problems, intermittent network outages, and other problems. Any shards that were successfully placed on the shard container are not moved off the container shard. It is possible that clients can access a shard, however, communication between container shards or between catalog servers and container servers is not working.
The shard containers that are in the disabled for shard placement list are designated as UNASSIGNED. Unless the JVM for the shard container is recycled, or another shard container stopped or started, the shards remain unassigned, unless you run the xscmd -c triggerPlacement command. The balance cycle does not automatically run when a shard container is disabled because it is possible the shard in question (or the data in the shard) could be causing the problem. To avoid propagating that shard to other shard containers, the balance cycle does not automatically run. You must investigate the issue, and run the xscmd -c triggerPlacement command before any container lifecycle changes.
To list the shard containers that are disabled, use the xscmd -c listDisabledForPlacement command.
The shard containers in this list cannot be used for placement until you re-enable the shard container. Resolve any issues with the shard container, then run the xscmd -c enableForPlacement -ct <shard_container> command.