Sharding Reference

Planning for sharding typically involves considering the tradeoff between resources per system and number of systems in use. At the extremes, the two main approaches can be stated as follows:

• Scale vertically to make each system and instance as powerful as feasible, then scale horizontally by adding additional powerful nodes.

• Scale horizontally using multiple affordable but less powerful systems as a cost-effective alternative to one high-end, heavily-configured system.

In practice, in most situations, a combination of these approaches works best. Unlike other horizontal scaling approaches, InterSystems IRIS sharding is easily combined with InterSystems IRIS’s considerable vertical scaling capacities. In many cases, a cluster hosted on reasonably high-capacity systems with a range of from 4 to 16 data nodes will yield the greatest benefit.

To use these guidelines, you need to estimate several variables related to the amount of data to be stored on the cluster.

1. First, review the data you intend to store on the cluster to estimate the following:

   1. Total size of all the sharded tables to be stored on the cluster, including their indexes.

   2. Total size of the nonsharded tables (including indexes) to be stored on the cluster that will be frequently joined with sharded tables.

   3. Total size of all of the nonsharded tables (including indexes) to be stored on the cluster. (Note that the previous estimate is a subset of this estimate.)

2. Translate these totals into estimated working sets, based on the proportion of the data that is regularly queried.

   Estimating working sets can be a complex matter. You may be able to derive useful information about these working sets from historical usage statistics for your existing database cache(s). In addition to or in place of that, divide your tables into the three categories and determine a rough working set for each by doing the following:

   • For significant SELECT statements frequently made against the table, examine the WHERE clauses. Do they typically look at a subset of the data that you might be able to estimate the size of based on table and column statistics? Do the subsets retrieved by different SELECT statements overlap with each other or are they additive?

   • Review significant INSERT statements for size and frequency. It may be more difficult to translate these into working set, but as a simplified approach, you might estimate the average hourly ingestion rate in MB (records per second * average record size * 3600) and add that to the working set for the table.

   • Consider any other frequent queries for which you may be able to specifically estimate results returned.

   • Bear in mind that while queries joining a nonsharded table and a sharded table count towards the working set NonshardSizeJoinedWS, queries against that same nonsharded data table that do not join it to a sharded table count towards the working set NonshardSizeTotalWS; the same nonsharded data can be returned by both types of queries, and thus would count towards both working sets.

   You can then add these estimates together to form a single estimate for the working set of each table, and add those estimates to roughly calculate the overall working sets. These overall estimates are likely to be fairly rough and may turn out to need adjustment in production. Add a safety factor of 50% to each estimate, and then record the final total data sizes and working sets as the following variables:

   Cluster Planning Variables

   Variable	Value
   ShardSize, ShardSizeWS	Total size and working set of sharded tables (plus safety factor)
   NonshardSizeJoined, NonshardSizeJoinedWS	Total size and working set of nonsharded tables that are frequently joined to sharded tables (plus safety factor)
   NonshardSizeTotal, NonshardSizeTotalWS	Total size and working set of nonsharded tables (plus safety factor)
   NodeCount	Number of data node instances

In reviewing the guidelines in the table that follows, bear the following in mind:

• Generally speaking and all else being equal, more shards will perform faster due to the added parallelism, up to a point of diminishing returns due to overhead, which typically occurs at around 16 data nodes.

• The provided guidelines represent the ideal or most advantageous configuration, rather than the minimum requirement.

  For example, as noted in Evaluating the Benefits of Sharding, sharding improves performance in part by caching data across multiple systems, rather than all data being cached by a single nonsharded instance, and the gain is greatest when the data in regular use is too big to fit in the database cache of a nonsharded instance. As indicated in the guidelines, for best performance the database cache of each data node instance in a cluster would equal at least the combined size of the sharded data working set and the frequently joined nonsharded data working set, with performance decreasing as total cache size decreases (all else being equal). But as long as the total of all the data node caches is greater than or equal to the cache size of a given single nonsharded instance, the sharded cluster will outperform that nonsharded instance. Therefore, if it is not possible to allocate database cache memory on the data nodes equal to what is recommended, for example, get as close as you can. Furthermore, your initial estimates may turn out to need adjustment in practice.

• Database cache refers to the database cache (global buffer pool) memory allocation that must be made for each instance. You can allocate the database cache on your instances as follows:

  • When using one of the automated deployment methods, you can override the default globals setting as part of deployment.

  • When deploying manually using the %SYSTEM.Cluster API or the Management Portal, you can use the manual procedure described in Memory and Startup Settings.

  For guidelines for allocating memory to an InterSystems IRIS instance’s routine and database caches as well as the shared memory heap, see Shared Memory Allocations .

• Default globals database indicates the target size of the database in question, which is the maximum expected size plus a margin for greater than expected growth. The file system hosting the database should be able to accommodate this total, with a safety margin there as well. For general information about InterSystems IRIS database size and expansion and the management of free space relative to InterSystems IRIS databases, and procedures for specifying database size and other characteristics when configuring instances manually, see Configuring Databases and Maintaining Local Databases.

  When deploying with the IKO, you can specify the size of the instance’s storage volume for data, which is where the default globals databases for the master and cluster namespaces are located, as part of deployment; this must be large enough to accommodate the target size of the default globals database.

  Important:

  When deploying manually, ensure that all instances have database directories and journal directories located on separate storage devices. This is particularly important when high volume data ingestion is concurrent with running queries. For guidelines for file system and storage configuration, including journal storage, see Storage Planning, File System Separation, and Journaling Best Practices.

• The number of data nodes (NodeCount) and the database cache size on each data node are both variables. The desired relationship between the sum of the data nodes’ database cache sizes and the total working set estimates can be created by varying the number of shards and the database cache size per data node. This choice can be based on factors such as the tradeoff between system costs and memory costs; where more systems with lower memory resources are available, you can allocate smaller amounts of memory to the database caches, and when memory per system is higher, you can configure fewer servers. Generally speaking and all else being equal, more shards will perform faster due to the added parallelism, up to a point of diminishing returns (caused in part by increased sharding manager overhead). The most favorable configuration is typically in the 4-16 shard range, so other factors aside, for example, 8 data nodes with M memory each are likely to perform better than 64 shards with M/8 memory each.

• Bear in mind that if you need to add data nodes after the cluster has been loaded with data, you can automatically redistribute the sharded data across the new servers, which optimizes performance; see Add Data Nodes and Rebalance Data for more information. On the other hand, you cannot remove a data node with sharded data on it, and a server’s sharded data cannot be automatically redistributed to other data nodes, so adding data nodes to a production cluster involves considerably less effort than reducing the number of data nodes, which requires dropping all sharded tables before removing the data nodes, then reloading the data after.

• Parallel query processing is only as fast as the slowest data node, so the best practice is for all data nodes in a sharded cluster to have identical or at least closely comparable specifications and resources. In addition, the configuration of all InterSystems IRIS instances in the cluster should be consistent; database settings such as collation and those SQL settings configured at instance level (default date format, for example) should be the same on all nodes to ensure correct SQL query results. Standardized procedures and use of an automated deployment method can help ensure this consistency.

The recommendations in the following table assume that you have followed the procedures for estimating total data and working set sizes described in the foregoing, including adding a 50% safety factor to the results of your calculations for each variable.

As described in Overview of InterSystems IRIS Sharding, compute nodes cache the data stored on data nodes and automatically process read-only queries, while all write operations (insert, update, delete, and DDL operations) are executed on the data nodes. The scenarios most likely to benefit from the addition of compute nodes to a cluster are as follows:

• When high volume data ingestion is concurrent with high query volume, one compute node per data node can improve performance by separating the query workload (compute nodes) from the data ingestion workload (data nodes)

• When high multiuser query volume is a significant performance factor, multiple compute nodes per data node increases overall query throughput (and thus performance) by permitting multiple concurrent sharded queries to run against the data on each underlying data node. (Multiple compute nodes do not increase the performance of individual sharded queries running one at a time, which is why they are not beneficial unless multiuser query workloads are involved.) Multiple compute nodes also maintain workload separation when a compute node fails, as queries can still be processed on the remaining compute nodes assigned to that data node.

When planning compute nodes, consider the following factors:

• If you are considering deploying compute nodes, the best approach is typically to evaluate the operation of your basic sharded cluster before deciding whether the cluster can benefit from their addition. Compute nodes can be easily added to an existing cluster using one of the automated deployment methods described in Automated Deployment Methods for Clusters or using the %SYSTEM.Cluster API. For information adding compute nodes, see Deploy Compute Nodes for Workload Separation and Increased Query Throughput.

• For best performance, a cluster’s compute nodes should be colocated with the data nodes (that is, in the same data center or availability zone) to minimize network latency.

• When compute nodes are added to a cluster, they are automatically distributed as evenly as possible across the data nodes. Bear in mind that adding compute nodes yields significant performance improvement only when there is at least one compute node per data node.

• The recommended best practice is to assign the same number of compute nodes to each data node. Therefore, if you are planning eight data nodes, for example, recommended choices for the number of compute nodes include zero, eight, sixteen, and so on.

• Because compute nodes support query execution only and do not store any data, their hardware profile can be tailored to suit those needs, for example by emphasizing memory and CPU and keeping storage to the bare minimum. All compute nodes in a sharded cluster should have closely comparable specifications and resources.

• Follow the data node database cache size recommendations (see Plan a Basic Cluster of Data Nodes) for compute nodes; ideally, each compute node should have the same size database cache as the data node to which it is assigned.

The distinction between data and compute nodes is completely transparent to applications, which can connect to any node's cluster namespace and experience the full dataset as if it were local. Application connections can therefore be load balanced across all of the data and compute nodes in a cluster, and under most applications scenarios this is the most advantageous approach. What is actually best for a particular scenario depends on whether you would prefer to optimize query processing or data ingestion. If sharded queries are most important, you can prioritize them by load balancing across the data nodes, so applications are not competing with shard-local queries for compute node resources; if high-speed ingestion using parallel load is most important, load balance across the compute nodes to avoid application activity on the data nodes. If queries and data ingestion are equally important, or you cannot predict the mix, load balance across all nodes.

The IKO allows you to automatically add a load balancer to your DATA node or COMPUTE node definitions; you can also create your own load balancing arrangement. For an important discussion of load balancing a web server tier distributing application connections across data nodes, see Load Balancing, Failover, and Mirrored Configurations.

Coordinated backup and restore of a sharded cluster always involves all of the data nodes in the cluster. The InterSystems IRIS Backup API includes a Backup.ShardedClusterOpens in a new tab class that supports three approaches to coordinated backup and restore of a cluster’s data nodes.

Bear in mind that the goal of all approaches is to restore all data servers to the same logical point in time, but the means of doing so varies. In one, it is the backups themselves that share a logical point in time, but in the others, InterSystems IRIS database journaling provides the common logical point in time, called a journal checkpoint, to which the databases are restored. The approaches include:

• Coordinated backups

• Uncoordinated backups followed by coordinated journal checkpoints

• A coordinated journal checkpoint included in uncoordinated backups

To understand how these approaches work, it is important that you understand the basics of InterSystems IRIS data integrity and crash recovery, which are discussed in Introduction to Data Integrity. Database journaling, a critical feature of data integrity and recovery, is particularly significant for this topic. Journaling records all updates made to an instance’s databases in journal files. This makes it possible to recover updates made between the time a backup was taken and the moment of failure, or another selected point, by restoring updates from the journal files following restore from backup. Journal files are also used to ensure transactional integrity by rolling back transactions that were left open by a failure. For detailed information about journaling, see Journaling.

Considerations when selecting an approach to coordinated backup and restore include the following:

• The degree to which activity is interrupted by the backup procedure.

• The frequency with which the backup procedure should be performed to guarantee sufficient recoverability.

• The complexity of the required restore procedure.

These issues are discussed in detail later in this section.

The methods in the Backup.ShardedClusterOpens in a new tab class can be invoked on any data node. All of the methods take a ShardMasterNamespace argument; this is the name of the master namespace on data node 1 (IRISDM by default) that is accessible from all nodes in the cluster.

The available methods are as follows:

• Backup.ShardedCluster.Quiesce() Opens in a new tab

  Blocks all activity on all data nodes of the sharded cluster, and waits until all pending writes have been flushed to disk. Backups of the cluster’s data nodes taken under Quiesce() represent a logical point in time.

• Backup.ShardedCluster.Resume()Opens in a new tab

  Resumes activity on the data nodes after they are paused by Quiesce().

• Backup.ShardedCluster.JournalCheckpoint()Opens in a new tab

  Creates a coordinated journal checkpoint and switches each data node to a new journal file, then returns the checkpoint number and the names of the precheckpoint journal files. The precheckpoint files are the last journal files on each data node that should be included in a restore; later journal files contain data that occurred after the logical point in time represented by the checkpoint.

• Backup.ShardedCluster.ExternalFreezeOpens in a new tab

  Freezes physical database writes, but not application activity, across the cluster, and then creates a coordinated journal checkpoint and switches each data node to a new journal file, returning the checkpoint number and the names of the precheckpoint journal files. The backups taken under ExternalFreeze() do not represent a logical point in time, but they include the precheckpoint journal files, thus enabling restore to the logical point in time represented by the checkpoint.

• Backup.ShardedCluster.ExternalThawOpens in a new tab

  Resumes disk writes after they are suspended by ExternalFreeze().

You can review the technical documentation of these calls in the InterSystems Class Reference.

The steps involved in the three coordinated backup and restore approaches provided by the Sharding API are described in the following sections.

• Create coordinated backups

  Quiesces all database activity for a period of time.

• Create uncoordinated backups followed by coordinated journal checkpoints

  Zero downtime required.

• Include a coordinated journal checkpoint in uncoordinated backups

  Zero downtime required.

Data node backups should, in general, include not only database files but all files used by InterSystems IRIS, including the journal directories, write image journal, and installation data directory, as well as any needed external files. The locations of these files depend in part on how the cluster was deployed (see Deploying the Sharded Cluster); the measures required to include them in backups may have an impact on your choice of approach.

For more detail on the %SYSTEM.Cluster API methods and instructions for calling them, see the %SYSTEM.ClusterOpens in a new tab class documentation in the InterSystems Class Reference.

Use the %SYSTEM.ClusterOpens in a new tab API methods in the following ways:

• Set up an InterSystems IRIS instance as the first node of a new sharded cluster by calling InitializeOpens in a new tab.

• Add an instance to a cluster as a data node by calling AttachAsDataNode on the instance being addedOpens in a new tab.

• Add an instance to a cluster as a compute node by calling AttachAsComputeNodeOpens in a new tab on the instance being added.

• Display a list of a cluster's nodes by calling ListNodesOpens in a new tab.

• Retrieve an overview of a cluster's metadata by calling GetMetaDataOpens in a new tab.

• Get the name of the cluster namespace for the current instance by calling ClusterNamespaceOpens in a new tab.

%SYSTEM.Cluster methods include the following; click the name of a method to open its Class Reference entry.

• $SYSTEM.Cluster.Initialize()Opens in a new tab

  Automatically and transparently performs all steps needed to enable the current InterSystems IRIS instance as the first node of a cluster

• $SYSTEM.Cluster.AttachAsDataNode()Opens in a new tab

  Attaches the current InterSystems IRIS instance to a specified cluster as a data node.

• $SYSTEM.Cluster.AttachAsComputeNode()Opens in a new tab

  Attaches the current InterSystems IRIS instance to a specified cluster as a compute node.

• $SYSTEM.Cluster.Detach()Opens in a new tab

  Detaches the current InterSystems IRIS instance from the cluster to which it is currently attached.

• $SYSTEM.Cluster.ListNodes()Opens in a new tab

  Lists the nodes of the cluster to which the current InterSystems IRIS instance belongs to the console or to a specified output file.

• $SYSTEM.Cluster.GetMetaData()Opens in a new tab

  Retrieves an overview of the metadata of the cluster to which the current InterSystems IRIS instance belongs.

• $SYSTEM.Cluster.ClusterNamespace()Opens in a new tab

  Gets the name of the cluster namespace on the current InterSystems IRIS instance.

For more detail on the %SYSTEM.Sharding API methods and instructions for calling them, see the %SYSTEM.ShardingOpens in a new tab class documentation in the InterSystems Class Reference.

Use the %SYSTEM.ShardingOpens in a new tab API methods in the following ways:

• Enable an InterSystems IRIS instance to act as a shard master or shard server by calling the EnableShardingOpens in a new tab method.

• Define the set of shards belonging to a master namespace by making repeated calls to AssignShardOpens in a new tab in the master namespace, one call for each shard.

• Once shards have been assigned, verify that they are reachable and correctly configured by calling VerifyShardsOpens in a new tab.

• If additional shards are assigned to a namespace that already contains sharded tables, and the new shards can't be reached for automatic verification during the calls to AssignShardOpens in a new tab, you can call ActivateNewShardsOpens in a new tab to activate them once they are reachable.

• List all the shards assigned to a master namespace by calling ListShardsOpens in a new tab.

• When converting a nonmirrored cluster to a mirrored cluster, after creating a mirror on each existing data node, add the master database and shard databases to their respective mirrors by calling AddDatabasesToMirrors.

• Rebalance existing sharded data across the cluster after adding data nodes/shard data servers with $SYSTEM.Sharding.Rebalance()Opens in a new tab (see Add Data Nodes and Rebalance Data).

• Assign a shard data server to a different shard namespace at a different address by calling ReassignShardOpens in a new tab.

• Remove a shard from the set belonging to a master namespace by calling DeassignShardOpens in a new tab.

• Set sharding configuration options by calling SetOptionOpens in a new tab, and retrieve their current values by calling GetOptionOpens in a new tab.

%SYSTEM.Sharding methods include the following; click the name of a method to open its Class Reference entry.

• $SYSTEM.Sharding.EnableSharding()Opens in a new tab

  Enables the current InterSystems IRIS instance to act as a shard master or shard server.

• $SYSTEM.Sharding.AssignShard()Opens in a new tab

  Assigns a shard to a master namespace.

• $SYSTEM.Sharding.VerifyShards()Opens in a new tab

  Verifies that assigned shards are reachable and are correctly configured.

• $SYSTEM.Sharding.ListShards()Opens in a new tab

  Lists the shards assigned to a specified master namespace, to the console or current device.

• $SYSTEM.Sharding.ActivateNewShards()Opens in a new tab

  Activates shards that could not be activated by prior calls to AssignShardOpens in a new tab.

• $SYSTEM.Sharding.AddDatabasesToMirrors()Opens in a new tab

  Adds the master and shard databases of data nodes that have been added as mirror failover members to their respective mirrors.

• $SYSTEM.Sharding.Rebalance()Opens in a new tab

  Rebalances existing sharded data across the cluster after adding data nodes/shard data servers.

• $SYSTEM.Sharding.ReassignShard()Opens in a new tab

  Reassigns a shard by assigning its shard number to a different shard namespace at a different address.

• $SYSTEM.Sharding.DeassignShard()Opens in a new tab

  Deassigns (unassigns) a shard from a master namespace to which it had previously been assigned. This removes the shard from the set of shards belonging to the master namespace.

• $SYSTEM.Sharding.SetOption()Opens in a new tab

  Sets a specified sharding configuration option to a specified value within the scope of a specified master namespace.

• $SYSTEM.Sharding.GetOption()Opens in a new tab

  Gets the value of a specified sharding configuration option within the scope of a specified master namespace.

• $SYSTEM.Sharding.SetNodeIPAddress()Opens in a new tab

  Configures a specified IP address rather than a node’s hostname as its address for cluster communications (must be used on all nodes).

• $SYSTEM.Sharding.GetConfig()Opens in a new tab

  Retrieves configuration information about the sharded cluster to which the specified master or cluster namespace belongs.

• $SYSTEM.Sharding.Reinitialize()Opens in a new tab

  Reinitializes the internal mappings, connections, and cluster metadata of a sharded cluster which has been cloned (as described in Cloning a Sharded Cluster).

• $SYSTEM.Sharding.GetFederatedTableInfo()Opens in a new tab

  Returns information about the specified federated table.

• $SYSTEM.Sharding.Help()Opens in a new tab

  Displays a summary of the methods of %SYSTEM.ShardingOpens in a new tab.

Identify the needed number of networked host systems (physical, virtual, or cloud) — one host each for the shard master and the shard data servers.

If you want to deploy mirror cluster, provision two hosts for the shard master data server, and two or more (depending on whether you want to a DR async members) for each shard data server.

This procedure assumes that each system hosts or will host a single InterSystems IRIS instance.

1. Deploy an instance of InterSystems IRIS, either by creating a container from an InterSystems-provided image (as described in Running InterSystems Products in Containers) or by installing InterSystems IRIS from a kit (as described in the Installation Guide).

   Important:

   Be sure to review deploy InterSystems IRIS on the data nodes for requirements and best practices for the InterSystems IRIS instances in a sharded cluster.

2. Ensure that the storage device hosting each instance’s databases is large enough to accommodate the target globals database size, as described in Estimate the Database Cache and Database Sizes.

   All instances should have database directories and journal directories located on separate storage devices, if possible. This is particularly important when high volume data ingestion is concurrent with running queries. For guidelines for file system and storage configuration, including journal storage, see Storage Planning, File System Separation, and Journaling Best Practices.

3. Allocate the database cache (global buffer pool) for each instance, depending on its eventual role in the cluster, according to the sizes you determined in Estimate the Database Cache and Database Sizes. For the procedure for allocating the database cache, see Memory and Startup Settings.

   Note:

   In some cases, it may be advisable to increase the size of the shared memory heap on the cluster members. For information on how to allocate memory to the shared memory heap, see gmheap.

   For guidelines for allocating memory to an InterSystems IRIS instance’s routine and database caches as well as the shared memory heap, see System Resource Planning and Management.

Once you have provisioned or identified the infrastructure and installed InterSystems IRIS on the cluster nodes, follow the steps in this section to configure the namespace-level cluster using the Management Portal.

For information about opening the Management Portal in your browser, see the instructions for an instance deployed in a container or one installed from a kit.

Prepare the Shard Data Servers

Do the following on each desired instance to prepare it to be added to the cluster as a shard data server.

Note:

Under some circumstances, the API (which underlies the Management Portal) may be unable to resolve the hostnames of one or more nodes into IP addresses that are usable for interconnecting the nodes of a cluster. When this is the case, you can call $SYSTEM.Sharding.SetNodeIPAddress()Opens in a new tab (see %SYSTEM.Sharding API) to specify the IP address to be used for each node. To use $SYSTEM.Sharding.SetNodeIPAddress(), you must call it on every intended cluster node before making any other %SYSTEM.Sharding API calls on those nodes, for example:

set status = $SYSTEM.Sharding.SetNodeIPAddress("00.53.183.209")

When this call is used, you must use the IP address you specify for each shard data server node, rather than the hostname, when assigning the shards to the master namespace, as described in Configure the Shard Master Data Server and Assign the Shard Data Servers.

1. Open the Management Portal for the instance and select System Administration > Configuration > System Configuration > Sharding > Enable Sharding, and on the dialog that displays, click OK. (The value of the Maximum Number of ECP Connections setting need not be changed as the default is appropriate for virtually all clusters.)

2. Restart the instance. (There is no need to close the browser window or tab containing the Management Portal; you can simply reload it after the instance has fully restarted.)

3. To create the shard namespace, navigate to the Configure Namespace-Level page (System Administration > Configuration > System Configuration > Sharding > Configure Namespace-Level) and click the Create Namespace button, then follow the instructions in Create/Modify a Namespace. (The namespace need not be interoperability-enabled.) Although the shard namespaces on the different shard data servers can have different names, you may find it more convenient to give them the same name.

   In the process, create a new database for the default globals database, making sure that it is located on a device with sufficient free space to accommodate the target size for the shard namespaces, as described in Estimate the Database Cache and Database Sizes. If data ingestion performance is a significant consideration, set the initial size of the database to its target size. Also select the globals database you created as the namespace’s default routines database.

   Important:

   If you are preparing an existing mirror to be a shard data server, when you create the default globals database for the shard namespace on each member — the primary first, then the backup, then any DR asyncs — select Yes at the Mirrored database? prompt to include the shard namespace globals database in the mirror.

   Note:

   As noted in the Estimate the Database Cache and Database Sizes, the shard master data server and shard data servers all share a single default globals database physically located on the shard master and known as the master globals database. The default globals database created when a shard namespace is created remains on the shard, however, becoming the local globals database, which contains the data stored on the shard. Because the shard data server does not start using the master globals database until assigned to the cluster, for clarity, the planning guidelines and instructions in this document refer to the eventual local globals database as the default globals database of the shard namespace.

   A new namespace is automatically created with IRISTEMP configured as the temporary storage database; do not change this setting for the shard namespace.

4. For a later step, record the DNS name or IP address of the host system, the superserver (TCP) port of the instance, and the name of the shard namespace you created.

   Note:

   From the perspective of another node (which is what you need in this procedure), the superserver port of a containerized InterSystems IRIS instance depends on which host port the superserver port was published or exposed as when the container was created. For details on and examples of this, see Running an InterSystems IRIS Container with Durable %SYS and Running an InterSystems IRIS Container: Docker Compose Example and see Container networkingOpens in a new tab in the Docker documentation.

   The default superserver port number of a noncontainerized InterSystems IRIS instance that is the only such on its host is 1972. To see or set the instance’s superserver port number, select System Administration > Configuration > System Configuration > Memory and Startup in the instance’s Management Portal. (For information about opening the Management Portal for the instance and determining the superserver port, see the instructions for an instance deployed in a container or one installed from a kit.)

Once you have provisioned or identified the infrastructure and installed InterSystems IRIS on the cluster nodes, follow the steps in this section to configure the namespace-level cluster using the API. Consult the %SYSTEM.Sharding class documentationOpens in a new tab in the InterSystems Class Reference for complete information about the calls described here, as well as other calls in the API.

Note:

Under some circumstances, the API may be unable to resolve the hostnames of one or more nodes into IP addresses that are usable for interconnecting the nodes of a cluster. When this is the case, you can call $SYSTEM.Sharding.SetNodeIPAddress()Opens in a new tab (see %SYSTEM.Sharding API) to specify the IP address to be used for each node. To use $SYSTEM.Sharding.SetNodeIPAddress(), you must call it on every intended cluster node before making any other %SYSTEM.Sharding API calls on those nodes, for example:

set status = $SYSTEM.Sharding.SetNodeIPAddress("00.53.183.209")

When this call is used, you must use the IP address you specify for each node, rather than the hostname, as the shard-host argument when calling $SYSTEM.Sharding.AssignShard()Opens in a new tab on the shard master to assign the node to the cluster, as described in the following procedure.