Skip to main content

Define the Deployment

Define the Deployment

To provide the needed parameters to ICM, you must select values for a number of fields, based on your goal and circumstances, and then incorporate these into the defaults and definitions files to be used for your deployment. You can begin with the template defaults.json and definitions.json files provided within in the ICM container in the /Samples directory tree, for example /Samples/AWS.

As noted in Configuration, State and Log Files, defaults.json is often used to provide shared settings for multiple deployments in a particular category, for example those that are provisioned on the same platform, while separate definitions.json files define the node types that must be provisioned and configured for each deployment. For example, the separate definitions files illustrated here define the two target deployments described at the start of this chapter: the distributed cache cluster includes two DM nodes as a mirrored data server, three load-balanced AM nodes as application servers, and an arbiter (AR) node, while the sharded cluster includes six DATA nodes configured as three load-balanced mirrored data nodes, plus an arbiter node. At the same time, the deployments can share a defaults.json file because they have a number of characteristics in common; for example, they are both on AWS. use the same credentials, provision in the same region and availability zone, and deploy the same InterSystems IRIS image.

While some fields (such as Provider) must appear in defaults.json and some (such as Role) in definitions.json, others can be used in either depending on your needs. In this case, for example, the InstanceType field appears in the shared defaults file and both definitions files, because the DM, AM, DATA, and AR nodes all require different compute resources; for this reason a single defaults.json setting, while establishing a default instance type, is not sufficient.

The following sections explain how you can customize the configuration of the InterSystems IRIS instances you deploy and review the contents of both the shared defaults file and the separate definitions files. Each field/value pair is shown as it would appear in the configuration file.

Bear in mind that ICM allows you to modify the definitions file of an existing deployment and then reprovision and/or redeploy to add or remove nodes or to alter existing nodes. For more information, see Reprovisioning the Infrastructure and Redeploying Services.

Important:

Both field names and values are case-sensitive; for example, to select AWS as the cloud provider you must include “Provider”:”AWS” in the defaults file, not “provider”:”AWS”, “Provider”:”aws”, and so on.

Note:

The fields included here represent a subset of the potentially applicable fields; see ICM Configuration Parameters for comprehensive lists of all required and optional fields, both general and provider-specific.

Shared Defaults File

The field/value pairs shown in the table in this section represent the contents of a defaults.json file that can be used for both the distributed cache cluster deployment and the sharded cluster deployment. As described at the start of this section, this file can be created by making a few modifications to the /Samples/AWS/default.json file, which is illustrated in the following:

{
    "Provider": "AWS",
    "Label": "Sample",
    "Tag": "TEST",
    "DataVolumeSize": "10",
    "SSHUser": "ubuntu",
    "SSHPublicKey": "/Samples/ssh/insecure-ssh2.pub",
    "SSHPrivateKey": "/Samples/ssh/insecure",
    "DockerRegistry": "https://containers.intersystems.com",
    "DockerImage": "containers.intersytems.com/intersystems/iris:some-tag",
    "DockerUsername": "xxxxxxxxxxxx",
    "DockerPassword": "xxxxxxxxxxxx",
    "TLSKeyDir": "/Samples/tls/",
    "LicenseDir": "/Samples/license/",
    "Region": "us-east-1",
    "Zone": "us-east-1a",
    "AMI": "ami-07267eded9a267f32",
    "DockerVersion": "5:20.10.17~3-0~ubuntu-jammy",
    "InstanceType": "m5.large",
    "Credentials": "/Samples/AWS/sample.credentials",
    "ISCPassword": "",
    "Mirror": "false",
    "UserCPF": "/Samples/cpf/iris.cpf"
}

The order of the fields in the table matches the order of this sample defaults file.

In the defaults file for a different provider, some of the fields have different provider-specific values, while others are replaced by different provider-specific fields. For example, in the Tencent defaults file, the value for InstanceType is S2.MEDIUM4, a Tencent-specific instance type that would be invalid on AWS, while the AWS AMI field is replaced by the equivalent Tencent field, ImageId. You can review these differences by examining the varying defaults.json files in the /Samples directory tree and referring to the General Parameters and Provider-Specific Parameters tables in the “ICM Reference” chapter.

Note:

The pathnames provided in the fields specifying security files in this sample defaults file assume you have placed your AWS credentials in the /Samples/AWS directory and used the keygen*.sh scripts to generate the keys as described in Obtain Security-Related Files. If you have generated or obtained your own keys, these may be replaced by internal paths to external storage volumes mounted when the ICM container is run, as described in the Launch ICM. For additional information about these files, see ICM Security and Security-Related Parameters in the “ICM Reference” chapter.

Shared characteristic /Samples/AWS/defaults.json Customization example Customization explanation
Platform to provision infrastructure on, in this case Amazon Web Services; see Provisioning Platforms in the “Essential ICM Elements” chapter. "Provider": "AWS", n/a If value is changed to GCP, Azure, Tencent, vSphere, or PreExisting, different fields and values from those shown here are required.

Naming pattern for provisioned nodes is Label-Role-Tag-NNNN, where Role is the value of the Role field in the definitions file, for example ANDY-DATA-TEST-0001. Modify these so that node names indicate ownership and purpose.

"Label": "Sample",

"Tag": "TEST",

"Label": "ANDY",

"Tag": "TEST",

Update to identify owner.
Size (in GB) of the persistent data volume to create for InterSystems IRIS containers; see Storage Volumes Mounted by ICM in the “ICM Reference” chapter. Can be overriden for specific node types in the definitions file. “DataVolumeSize”: “10”,

“DataVolumeSize”:”250”,

If all deployments using the defaults file consist of sharded cluster (DATA) nodes only, enlarging the default size of the data volume is recommended.

Nonroot account with sudo access, used by ICM for SSH access to provisioned nodes. On AWS, the required value depends on the AMI, but is typically ubuntu for Ubuntu AMIs; see Security-Related Parameters in the “ICM Reference” chapter.

"SSHUser": "ubuntu",

 n/a If value is changed to GCP, Azure, Tencent, vSphere, or PreExisting, different fields and values from those shown here are required.

Locations of needed security key files; see Obtain Security-Related Files and Security-Related Parameters. Because provider is AWS, the SSH2–format public key in /Samples/ssh/ is specified.

"SSHPublicKey": "/Samples/ssh/secure-ssh2.pub",

"SSHPrivateKey": "/Samples/ssh/secure-ssh2",

"TLSKeyDir": "/Samples/tls/",

"SSHPublicKey": "/mydir/keys/mykey.pub",

“SSHPrivateKey": "/mydir/keys/mykey.ppk",

"TLSKeyDir": "/mydir/keys/tls/",

 If you stage your keys on a mounted external volume, update the paths to reflect this.
The Docker version to be installed on provisioned nodes; typically you can keep the default value.

"DockerVersion": "5:20.10.5~3-0~ubuntu-bionic",

 "DockerVersion": "18.06.1~ce~3-0~ubuntu", The version in each /Samples/.../defaults.json is generally correct for the platform. However. if your organization uses a different version of Docker, you may want that version installed on the cloud nodes instead.

The Docker image to deploy on provisioned nodes; see Docker Repositories in the “Elements of ICM” chapter, The icm run Command, and General Parameters in the “ICM Reference” chapter. This field can also be included in a node definition in definitions.json, overriding the defaults file value, as illustrated in Distributed Cache Cluster Definitions File.

"DockerImage": "intersystems/iris:stable",

“DockerImage”: “acme/iris:latest-em" If you pushed the InterSystems IRIS image to your organization’s registry, update the image spec.

Note: InterSystems IRIS images for standard platforms are named iris; those for ARM platforms are named iris-arm64.
Credentials to log in to the Docker registry in which the image specified by the previous field is stored; see Downloading the ICM Image.

"DockerUsername": "xxxxxxxxxxxx",

"DockerPassword": "xxxxxxxxxxxx",

"DockerUsername": "AndyB",

"DockerPassword": "password",

 Update to use your Docker credentials for the specified registry.
Location of InterSystems IRIS license keys staged in the ICM container and individually specified by the LicenseKey fields in the definitions file; see InterSystems IRIS Licensing for ICM in the “ICM Reference” chapter. “LicenseDir”: “/Samples/Licenses”,

“LicenseDir”: “/mydir/licenses”,

If you stage your licenses on a mounted external volume, update the paths to reflect this.
Geographical region of provider’s compute resources in which infrastructure is to be provisioned; see General Parameters. "Region": "us-west-1", "Region": "us-east-2", If you want to provision in another valid combination of region and availability zone, update the values to reflect this.
Availability zone within specified region in which to locate provisioned nodes; see General Parameters. "Zone": "us-west-1c", "Zone": "us-east-2a",  
AMI to use as platform and OS template for nodes to be provisioned; see Amazon Web Services (AWS) Parameters in the “ICM Reference” chapter. "AMI": "ami-0121ef35996ede438", “AMI”: “ami-e24b7d9d”, If you want to provision from another valid combination of AMI and instance type, update the values to reflect this.

Instance type to use as compute resources template for nodes to be provisioned; see Amazon Web Services (AWS) Parameters.

"InstanceType": "m4.large", "InstanceType": "m5ad.large",  

Credentials for AWS account; see Amazon Web Services (AWS) Parameters.

"Credentials": "/Samples/AWS/sample.credentials",

 “Credentials”: “/mydir/aws-credentials”, If you stage your credentials on a mounted external volume, update the path to reflect this.

Password for deployed InterSystems IRIS instances. Recommended approach is to specify on the deployment command line (see Deploy and Manage Services) to avoid displaying password in a configuration file

“ISCPassword”: "",

 (delete) Remove in favor of specifying password by using -password option of icm run command.

Whether specific node types (including DM and DATA) defined in even numbers are deployed as mirrors (see Rules for Mirroring).

"Mirror": "true"

 n/a Both deployments are mirrored.
The configuration merge file to be used to override initial CPF settings for deployed InterSystems IRIS instances (see Deploying with Customized InterSystems IRIS Configurations in the “ICM Reference” chapter) . "UserCPF": "/Samples/cpf/iris.cpf"   Remove unless you are familiar with the configuration merge feature and CPF settings (see Automating Configuration of InterSystems IRIS with Configuration MergeOpens in a new tab).
Important:

The major versions of the image from which you launched ICM and the InterSystems IRIS image you specify using the DockerImage field must match; for example, you cannot deploy a 2022.2 version of InterSystems IRIS using a 2022.1 version of ICM. For information about upgrading ICM before you upgrade your InterSystems containers, see Upgrading ICM Using Distributed Management Mode in the appendix “Sharing Deployments in Distributed Management Mode”.

Distributed Cache Cluster Definitions File

The definitions.json file for the distributed cache cluster must define the following nodes:

  • Two data servers (role DM), configured as a mirror

  • Three application servers (role AM)

  • Load balancer for application servers

  • Arbiter node for data server mirror

This configuration is illustrated in the following:

Distributed Cache Cluster to be Deployed by ICM
null

The table that follows lists the field/value pairs that are required for this configuration.

Important:

A standalone InterSystems IRIS instance, nonmirrored or mirrored—that is, a DM node or two DM nodes forming a mirror—can be deployed with a standard license, as can a distributed cache cluster (DM node or mirrored DM nodes plus AM nodes). In all sharded cluster configurations, node-level or namespace-level and nonmirrored or mirrored, all nodes on which an InterSystems IRIS container is deployed require a sharding-enabled InterSystems IRIS license. For example, if a nonmirrored or mirrored standalone instance with a standard license has DS nodes added to it, the license used for all of the nodes must be upgraded to a sharding license.

Definition Field: Value

Two data servers (DM) using a standard InterSystems IRIS license, configured as a mirror because “Mirror”: “true” in shared defaults file.

Instance type, OS volume size, data volume size override settings in defaults file to meet data server resource requirements.

"Role": "DM",

"Count": "2",

"LicenseKey": "ubuntu-standard-iris.key,”

"InstanceType": "m4.xlarge",

"OSVolumeSize": "32",

"DataVolumeSize": "150",

Three application servers (AM) using a standard InterSystems IRIS license.

Numbering in node names starts at 0003 to follow DM nodes 0001 and 0002.

Load balancer for application servers is automatically provisioned.

"Role": "AM",

"Count": "3",

"LicenseKey": "ubuntu-standard-iris.key”,

"StartCount": "3",

"LoadBalancer": "true",

One arbiter (AR) for data server mirror, no license required, use of arbiter image overrides InterSystems IRIS image specified in defaults file.

Node is numbered 0006.

Instance type overrides defaults file because arbiter requires only limited resources.

"Role": “AR”,

"Count": "1",

"DockerImage": "intersystems/arbiter:latest-em",

"StartCount": "6",

"InstanceType": "t2.small",

A definitions.json file incorporating the settings in the preceding table would look like this:

[
    {
        "Role": "DM",
        "Count": "2",
        "LicenseKey": "ubuntu-standard-iris.key”,
        "InstanceType": "m4.xlarge",
        "OSVolumeSize": "32",
        "DataVolumeSize": "150"
    },
    {
        "Role": "AM",
        "Count": "3",
        "LicenseKey": "ubuntu-standard-iris.key”,
        "StartCount": "3",
        "LoadBalancer": "true"
    },
    {
        "Role": "AR",
        "Count": "1",
        "DockerImage": "intersystems/arbiter:latest-em",
        "StartCount": "6",
        "InstanceType": "t2.small"
    }
]

Sharded Cluster Definitions File

The definitions.json file for the sharded cluster configuration must define three load-balanced mirrored DATA nodes. This is illustrated in the following:

Sharded Cluster to be Deployed by ICM
null

The table that follows lists the field/value pairs that are required for this configuration.

Definition Field: Value

  • Six data nodes (DATA) using a sharding-enabled InterSystems IRIS license, configured as three mirrors because “Mirror”: “true” in shared defaults file

  • Instance type and data volume size override settings in defaults file to meet data node resource requirements

  • Load balancer for data nodes is automatically provisioned

"Role": "DATA"

"Count": "6"

"LicenseKey": "ubuntu-sharding-iris.key”

"InstanceType": "m4.4xlarge"

“DataVolumeSize": "250"

"LoadBalancer": "true"

  • One arbiter (AR) for data server mirror, no license required, use of arbiter image overrides InterSystems IRIS image specified in defaults file

  • Node is numbered 0007

  • Instance type overrides defaults file because arbiter requires only limited resources

"Role": “AR”

"Count": "1"

"DockerImage": "intersystems/arbiter:latest-em"

"StartCount": "7"

"InstanceType": "t2.small"

A definitions.json file incorporating the settings in the preceding table would look like this:

[
    {
        "Role": "DATA",
        "Count": "6",
        "LicenseKey": "sharding-iris.key”,
        "InstanceType": "m4.xlarge",
        "DataVolumeSize": "250",
        "LoadBalancer": "true"
    },
    {
        "Role": "AR",
        "Count": "1",
        "DockerImage": "intersystems/arbiter:latest-em",
        "StartCount": "7",
        "InstanceType": "t2.small"
    }
]
Note:

The DATA and COMPUTE node types were added to ICM in Release 2019.3 to support the node-level sharding architecture. Previous versions of this document described the namespace-level sharding architectureOpens in a new tab, which involves a different, larger set of node types. The namespace-level architecture remains in place as the transparent foundation of the node-level architecture and is fully compatible with it, and the node types used to deploy it are still available in ICM. For information about all available node types, see ICM Node Types.

For more detailed information about the specifics of deploying a sharded cluster, such as database cache size and data volume size requirements, see Deploying the Sharded ClusterOpens in a new tab in the “Horizontally Scaling for Data Volume with Sharding” chapter of the Scalability Guide.

The recommended best practice is to load-balance application connections across all of the data nodes in a cluster.

Customizing InterSystems IRIS Configurations

Every InterSystems IRIS instance, including those running in the containers deployed by ICM, is installed with a predetermined set of configuration settings, recorded in its configuration parameters file (CPF). You can use the UserCPF field in your defaults file (as illustrated in the /Samples/AWS/defaults.json file in Shared Defaults File) to specify a configuration merge file, allowing you to override one or more of these configuration settings for all of the InterSystems IRIS instances you deploy, or in your definitions file to override different settings for different node types, such as the DM and AM nodes in a distributed cache cluster or the DATA and COMPUTE nodes in a sharded cluster. For example, as described in Planning an InterSystems IRIS Sharded ClusterOpens in a new tab in the “Sharding” chapter of the Scalability Guide, you might want to adjust the size of the database caches on the data nodes in a sharded cluster, which you could do by overriding the value of the [config]/globals CPF setting for the DATA definitions only. For information about using a merge file to override initial CPF settings, see Deploying with Customized InterSystems IRIS Configurations in the “ICM Reference” chapter.

A simple configuration merge file is provided in the /Samples/cpf directory in the ICM container, and the sample defaults files in all of the /Samples provider subdirectories include the UserCPF field, pointing to this file. Remove UserCPF from your defaults file unless you are sure you want to merge its contents into the default CPFs of deployed InterSystems IRIS instances.

Information about InterSystems IRIS configuration settings, their effects, and their installed defaults is provided in the Installation GuideOpens in a new tab, the System Administration GuideOpens in a new tab, and the Configuration Parameter File ReferenceOpens in a new tab.

Next sectionProvision the Infrastructure
Previous sectionObtain Security-Related Files
FeedbackOpens in a new tab