Customize the Sample Configuration Files

To define the configuration you want ICM to deploy, you include the needed settings in two JSON-formatted configuration files: the defaults file and the definitions file. The former (defaults.json) contains settings that apply to the entire deployment — for example, your choice of cloud provider — while the latter (definitions.json) defines which types of nodes you want and how many of each, thereby determining whether you deploy a sharded cluster, a single stand-alone InterSystems IRIS instance, or some other configuration.

The /Samples directory in the ICM container provides sample configuration files for all four cloud providers. For example, sample configuration files for AWS are located in the /Samples/AWS directory. To customize these files, select the provider you want to use, then modify the sample defaults and definitions files for that provider as described in the tables that follow. To do this, you can use an editor such as vi to edit them directly within the container, or use the docker cp command on the local command line to copy them from the container to the local file system, and then back again after you have edited them, for example:

docker cp icm:/Samples/AWS/defaults.json .
docker cp icm:/Samples/AWS/definitions.json .
...
docker cp defaults.json icm:/Samples/AWS
docker cp definitions.json icm:/Samples/AWS

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.

Customize defaults.json

The following table details the minimum customization needed for the defaults files provided in the /Samples files, plus suggestions for optional changes. Any setting not covered here can be left as is in the sample file.

Each setting is linked to the relevant table in the ICM Configuration ParametersOpens in a new tab section of the “ICM Reference” chapter of the ICM Guide, where you will find more detailed descriptions; once there, search for the parameter you want. The rightmost column shows each parameter or set of parameters as they appear in the sample defaults files.

To review all of the settings that are common to all providers, see General ParametersOpens in a new tab in that section; to review all that are specific to a particular provider, see Provider-Specific ParametersOpens in a new tab.

Setting	Description	Entry in sample defaults.json file
ProviderOpens in a new tab	Identifies the cloud infrastructure provider; keep the value in the sample defaults.json.	“Provider”:[”AWS”\|"GCP"\|"Azure"\|"Tencent"],
LabelOpens in a new tab	Field in naming scheme for provisioned nodes, Label-Role-Tag-NNNN (see Role below); update to identify the owner and purpose of the deployment, for example use your company name and “TEST” to create node names like Acme-DATA-TEST-0001.	"Label": "Sample",
TagOpens in a new tab	(see Label above)	"Tag": "TEST",
DataVolumeSizeOpens in a new tab	Size of the persistent data volume to be provisioned with each node, which can be overridden in individual node definitions in the definitions.json file; accept the value in the sample defaults.json unless you are provisioning on Tencent, in which case change it to 60.	"DataVolumeSize": "10",
SSHUserOpens in a new tab	Nonroot account with sudo access on provisioned nodes, used by ICM for access; you can keep the default in the sample defaults.json, but if you change the machine image (below) on AWS or Tencent, you may need to update this entry.	"SSHUser": "ubuntu", (AWS & Tencent) "SSHUser": "sample", (GCP & Azure)
SSHPublicKeyOpens in a new tab	Location of the SSH public key. If you used the key generation scripts discussed in Generate Security Keys, the keys are located in the directories specified in the sample files, so make no changes; if you are providing your own keys, use docker cp to copy them from the local file system to these locations.	"SSHPublicKey": "/Samples/ssh/insecure-ssh2.pub",
SSHPrivateKeyOpens in a new tab	Location of the SSH private key; see SSHPublicKey above.	"SSHPrivateKey": "/Samples/ssh/insecure",
TLSKeyDirOpens in a new tab	Location of TILS files; see SSHPublicKey above.	"TLSKeyDir": "/Samples/tls/",
DockerVersionOpens in a new tab	The Docker version to be installed on provisioned nodes; keep the default value.	"DockerVersion": "5:19.03.8~3-0~ubuntu-bionic",
DockerImageOpens in a new tab	The image to be deployed on provisioned nodes; update to reflect the repository and image information you identified in Identify Docker Repository and Credentials.	"DockerImage": "containers.intersystems.con/intersystems/iris:latest-em",
DockerUsernameOpens in a new tab DockerPasswordOpens in a new tab	The credentials needed to download image specified by DockerImage if in a private repository; update to reflect the repository information and credentials you identified in Identify Docker Repository and Credentials.	"DockerUsername": "xxxxxxxxxxxx", "DockerPassword": "xxxxxxxxxxxx",
LicenseDirOpens in a new tab	Staging directory for InterSystems IRIS licenses; place your container-specific InterSystems IRIS sharding license in this directory.	“LicenseDir”: “/Samples/Licenses”,
RegionOpens in a new tab, LocationOpens in a new tab (Azure)	Geographical region of provider’s compute resources in which to provision infrastructure; accept the default in the sample defaults.json or select another combination of region and zone (below) from the provider.	"Region": "us-west-1", (AWS) "Region": "us-east1", (GCP) "Location": "Central US", (Azure) "Region": "na-siliconvalley", (Tencent)
ZoneOpens in a new tab	Availability zone within the selected region (above); accept the default in the sample defaults.json or select another combination of region and zone from the provider.	"Zone": "us-west-1c", (AWS) "Zone": "us-east1-b", (GCP) "Zone": "1", (Azure) "Zone": "na-siliconvalley-1", (Tencent)
Machine image (provider-specific)	Template for platform and OS of provisioned nodes; accept the defaults in the sample defaults.json or select a different combination of machine image and instance type (below) from the provider.	"AMI": "ami-c509eda6", (AWSOpens in a new tab) "Image": "ubuntu-os-cloud/ubuntu-1804-bionic-v20180617", (GCPOpens in a new tab) "PublisherName": "Canonical", (AzureOpens in a new tab) "Offer": "UbuntuServer",(Azure) "Sku": "18.04-LTS",(Azure) "Version": "18.04.201804262",(Azure) "ImageID": "img-pi0ii46r", (TencentOpens in a new tab)
Instance type (provider-specific)	Template for compute resources of provisioned nodes; accept the value in the sample defaults.json or select a different combination of machine image (above) and instance type from the provider.	"InstanceType": "m4.large", (AWSOpens in a new tab) "MachineType": "n1-standard-1", (GCPOpens in a new tab) "Size": "Standard_DS2_v2", (AzureOpens in a new tab) "InstanceType": "S2.MEDIUM4", (TencentOpens in a new tab)
Credentials and account settings (provider-specific)	Files or IDs needed by ICM to authenticate to the provider, differing by provider; update to specify the needed file locations or IDs for your account (for instructions click the provider link).	“Credentials”:”/Samples/AWS/credentials”, (AWSOpens in a new tab) "Credentials": "/Samples/GCP/sample.credentials", (GCPOpens in a new tab) "Project": "dp-icmdevelopment", (GCP) "SubscriptionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", (AzureOpens in a new tab) "ClientId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", (Azure) "ClientSecret": "xxxxxxxxxxxx/xxxxxxxxxxxxxxx/xxxxxxxxxxxxxx=", (Azure) "TenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", (Azure) "SecretID": "xxxxxxxxxxxx", (TencentOpens in a new tab) "SecretKey": "xxxxxxxxxxxx", (Tencent)
ISCPasswordOpens in a new tab	Password for predefined accounts in deployed InterSystems IRIS images; to provide the password interactively with masked input during the deployment phase (as recommended for security), remove this field, otherwise change to your preferred password.	"ISCPassword": "",
MirrorOpens in a new tab	Determines whether InterSystems IRIS instances deployed on DATA, DM, and DS nodes are configured as mirrors; retain the default.	“Mirror”: “false”
UserCPF	Specifies the configuration merge file to be used to override initial CPF settings for deployed instances. (Remove this entry if you are not familiar with the configuration merge feature or the CPF; for information about configuration merge, see Deploying with Customized InterSystems IRIS Configurations in the “ICM Reference” chapter of the ICM Guide.	"UserCPF": "/Samples/cpf/iris.cpf"

The following tabs show the contents of the sample defaults.json files for AWS, GCP, Azure, and Tencent:

{
    "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.intersystems.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"
}

{
    "Provider": "GCP",
    "Label": "Sample",
    "Tag": "TEST",
    "DataVolumeSize": "10",
    "SSHUser": "sample",
    "SSHPublicKey": "/Samples/ssh/insecure.pub",
    "SSHPrivateKey": "/Samples/ssh/insecure",
    "DockerRegistry": "https://containers.intersystems.com",
    "DockerImage": "containers.intersystems.com/intersystems/iris:some-tag",
    "DockerUsername": "xxxxxxxxxxxx",
    "DockerPassword": "xxxxxxxxxxxx",
    "TLSKeyDir": "/Samples/tls/",
    "LicenseDir": "/Samples/license/",
    "Credentials": "/Samples/GCP/sample.credentials",
    "Project": "sample-project",
    "MachineType": "n1-standard-1",
    "Region": "us-east1",
    "Zone": "us-east1-b",
    "Image": "ubuntu-os-cloud/ubuntu-2204-jammy-v20220607",
    "DockerVersion": "5:20.10.17~3-0~ubuntu-jammy",
    "ISCPassword": "",
    "Mirror": "false",
    "UserCPF": "/Samples/cpf/iris.cpf"
}

{
    "Provider": "Azure",
    "Label": "Sample",
    "Tag": "TEST",
    "DataVolumeSize": "10",
    "SSHUser": "sample",
    "SSHPublicKey": "/Samples/ssh/insecure.pub",
    "SSHPrivateKey": "/Samples/ssh/insecure",
    "DockerRegistry": "https://containers.intersystems.com",
    "DockerImage": "containers.intersystems.com/intersystems/iris:some-tag",
    "DockerUsername": "xxxxxxxxxxxx",
    "DockerPassword": "xxxxxxxxxxxx",
    "TLSKeyDir": "/Samples/tls/",
    "LicenseDir": "/Samples/license/",
    "Location": "Central US",
    "Zone": "1",
    "PublisherName": "Canonical",
    "Offer": "0001-com-ubuntu-server-jammy",
    "Sku": "22_04-lts",
    "Version": "22.04.202206040",
    "DockerVersion": "5:20.10.17~3-0~ubuntu-jammy",
    "Size": "Standard_DS2_v2",
    "AccountTier": "Standard",
    "AccountReplicationType": "LRS",
    "SubscriptionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "ClientId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "ClientSecret": "xxxxxxxxxxxx/xxxxxxxxxxxxxxx/xxxxxxxxxxxxxx=",
    "TenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "ISCPassword": "",
    "Mirror": "false",
    "UserCPF": "/Samples/cpf/iris.cpf"
}

{
    "Provider": "Tencent",
    "Label": "Sample",
    "Tag": "TEST",
    "DataVolumeSize": "60",
    "SSHUser": "ubuntu",
    "SSHPublicKey": "/Samples/ssh/insecure.pub",
    "SSHPrivateKey": "/Samples/ssh/insecure",
    "DockerRegistry": "https://containers.intersystems.com",
    "DockerImage": "containers.intersystems.com/intersystems/iris:some-tag",
    "DockerUsername": "xxxxxxxxxxxx",
    "DockerPassword": "xxxxxxxxxxxx",
    "TLSKeyDir": "/Samples/tls/",
    "LicenseDir": "/Samples/license/",
    "SecretID": "xxxxxxxxxxxx",
    "SecretKey": "xxxxxxxxxxxx",
    "InstanceType": "S2.MEDIUM4",
    "Region": "na-siliconvalley",
    "Zone": "na-siliconvalley-1",
    "ImageId": "img-22trbn9x",
    "DockerVersion": "5:20.10.10~3-0~ubuntu-focal",
    "ISCPassword": "",
    "Mirror": "false",
    "UserCPF": "/Samples/cpf/iris.cpf"
}

Customize definitions.json

The sample definitions.json file in the /Samples directories, which is the same for all providers, defines a sharded cluster with two data nodes and two compute nodes, as shown in the following:

[
   {
    "Role": "DATA",
    "Count": "2",
    "LicenseKey": "ubuntu-sharding-iris.key"
    },
    {
    "Role": "COMPUTE",
    "Count": "2",
    "StartCount": "3",
    "LicenseKey": "ubuntu-sharding-iris.key"
    }
]

The Role field identifies the node types being provisioned, which in this case are DATA and COMPUTE. The Count field indicates how many of that type to provision; StartCount starts numbering at 0003 for the COMPUTE nodes. The LicenseKey field indicates the name of an InterSystems IRIS license file located in the directory specified by the LicenseDir field in the defaults file.

For this exercise, remove the COMPUTE definition, leaving only the DATA definitions, as follows:

[
   {
    "Role": "DATA",
    "Count": "2",
    "LicenseKey": "ubuntu-sharding-iris.key"
   }
]

When a sharded cluster is deployed, all nodes must have a sharding license. Use docker cp to copy a sharding license to the location within the container specified by LicenseDir, such as /Samples/Licenses, and update the LicenseKey setting in the DATA node definition to specify license key to use.

Those are the only definitions.json changes required to provision the basic sharded cluster. To provision a stand-alone InterSystems IRIS instance instead, use this definition:

[
   {
    "Role": "DM",
    "Count": "1",
    "LicenseKey": "standard-iris.key""
    },
]