基本的な ICM の要素
この章では、ICM の使用に関係がある、基本的な要素について説明します。
InterSystems Cloud Manager イメージ
ICM は Docker イメージとして提供されます。これを実行すると、ICM コンテナが起動されます。例えば Terraform、Docker クライアント、構成ファイルのテンプレートなど、プロビジョニング、導入、および管理のタスクを実行するために ICM が必要とするすべてがこのコンテナに含まれています。ICM コンテナについての詳細は、"ICM の起動" を参照してください。
ICM を起動するシステムは、Docker コンテナをホストするプラットフォームとして Docker によってサポートされている必要があり、Docker がインストール済みで、インフラストラクチャのプロビジョニングとコンテナの導入を行うプロビジョニング・プラットフォーム、または導入を行う既存のインフラストラクチャへの十分な接続性を備えていることが必要です。
導入に含めるノードの定義
プロビジョニング対象ノードごとに 1 つの InterSystems IRIS インスタンスが ICM によって導入され、各インスタンスが InterSystems IRIS 構成で担当するロールは Role フィールドの値によって決まります。ノードとそのインスタンスは、そのロールの下でプロビジョニング、導入、および構成されます。
ICM の使用準備の際に、構成に含めるノードのタイプと数を選択することによってターゲット構成を定義する必要があります (“ICM の使用” の章にある "導入の定義" を参照)。例えば、InterSystems IRIS シャード・クラスタを導入する場合は、クラスタに含めるデータ・ノードおよび (オプションで) 計算ノードの数と、データ・ノードをミラーリングするかどうかを事前に決定しておく必要があります。その後、ICM に必要な入力を提供するために、対象のノードの仕様を定義ファイルに入力します ("構成ファイル、状態ファイル、およびログ・ファイル" を参照)。以下の単純化した例にこれを示します。ここでは、4 つのデータ・ノードと 8 つの計算ノードを定義します。
[
{
"Role": "DATA",
"Count": "4",
"LicenseKey": "ubuntu-sharding-iris.key"
},
{
"Role": "COMPUTE",
"Count": "8",
"StartCount": "5",
"LicenseKey": "ubuntu-sharding-iris.key"
}
]
データ・ノードをミラーリングするかどうかを決定する Mirror フィールドは、既定値ファイルで指定します。ミラー導入については、"ICM クラスタのトポロジとミラーリング" で詳しく説明します。
フィールド値
ICM によって行われるプロビジョニング、導入、および構成の作業は、ユーザが指定するいくつかのフィールド値によって決まります。例えば、Provider フィールドは、使用するプロビジョニング・プラットフォームを指定します。値が AWS ならば、指定されたノードは AWS 上でプロビジョニングされます。
フィールド値を指定するには、以下の 2 つの方法があります。
ほとんどの ICM フィールドには既定値もあります。優先度が高い順に、これらの指定の順位は以下のとおりです。
-
コマンド行オプション
-
definitions.json 構成ファイルのエントリ
-
defaults.json 構成ファイルのエントリ
-
ICM の既定値
これにより、よく使用されるフィールドを繰り返し指定することなく、柔軟な指定が可能です。既定値ファイル (defaults.json) を使用して、特定のカテゴリに属する複数の導入に値を指定できます (値が必須の場合、または既定値をオーバーライドする場合)。例えば、同じプラットフォーム上でプロビジョニングされる導入のためにこのファイルを使用できます。定義ファイル (definitions.json) は、クラスタ内のノードとそれを識別するラベルを指定するなど、特定の導入に対して値を指定します。ただし、特定の導入で特定のノード・タイプの defaults.json 値をオーバーライドするために、既定値ファイルに含まれるフィールドを指定することもできます。コマンド行オプションとしてフィールド値を指定すると、特定の導入で特定のコマンドのコンテキストにおいて両方の構成ファイルをオーバーライドできます。
以下の図は、1 つの defaults.json ファイルを共有し、異なる definitions.json ファイル (1 つ目は分散キャッシュ・クラスタのもので、2 つ目はシャード・クラスタのもの) を使用する 2 つの導入を示しています。
導入を定義する ICM 構成ファイル
これらのファイルで指定できる必須のフィールドとオプションのフィールドの包括的なリストについては、“ICM リファレンス” の章にある "ICM の構成パラメータ" を参照してください。
コマンド行
ICM コマンド行インタフェースにより、ユーザは調整プロセスのアクションを指定できます (例えば、インフラストラクチャをプロビジョニングする icm provision や、指定したコンテナを実行して導入を行う icm run)。また、コンテナのアップグレードや InterSystems IRIS への接続など、コンテナやサービスの管理コマンドを指定することもできます。ICM は、構成ファイルからの情報を使用してこれらのコマンドを実行します。入力構成ファイルのどちらか ("構成ファイル、状態ファイル、およびログ・ファイル" を参照) がコマンド行で指定されない場合、ICM は現在の作業ディレクトリに存在するファイル (definitions.json または defaults.json) を使用します。一方または両方のファイルが指定されず、存在しない場合、コマンドは失敗します。
コマンド行を使用して、オプションを指定することもできます。以下のように、オプションにはいくつかの目的があります。
-
単一のコマンドのみを対象に、構成ファイル内の情報をオーバーライドするため。例えば、以下に示すように、構成ファイルに指定されているものとは別の Docker イメージを導入するため。
icm run –image image
-
情報が維持されることを避ける理由で構成ファイルに含めない情報を指定するため。例えば、以下のようにパスワードを指定します。
icm run -iscPassword password
-
導入内の 1 つ以上のノード上で実行されるコマンドに関連した情報を指定するため。例えば、以下のようにクエリを指定します。
icm sql -role DATA -namespace namespace -command "query"
オプションが異なるコマンドで使用される場合、オプションの目的は異なることがあります。例えば、icm run コマンドでは、-container オプションは指定イメージから起動される新規コンテナの名前を指定しますが、icm ps コマンドでは、状態情報を表示する既存の導入済みコンテナの名前を指定します。
ICM コマンドとコマンド行オプションの総合的なリストについては、"ICM コマンドおよびオプション" を参照してください。
構成ファイル、状態ファイル、およびログ・ファイル
ICM は、以下のように JSON ファイルを入力と出力の両方として使用します。
-
入力としては、構成ファイルでは ICM でタスクの実行に必要な情報を提供します (使用するプロビジョニング・プラットフォームや、プロビジョニングするノードのタイプと数など)。これらのファイルはユーザによって提供されます。これらは ICM に付属するテンプレートから変更して作成することも、手動で作成することも、スクリプトまたは UI の出力によって作成することもできます。
-
出力としては、ICM によって生成されるファイルは ICM のタスクの結果を記述します。
ICM タスクの結果、新規または変更されたデータ (例えば、IP アドレス) が生成される場合、その情報は後続のタスクが使用するために JSON 形式で記録されます。ICM では、認識されないフィールドや、現在のタスクに適用されないフィールドをすべて無視しますが、これらのフィールドを後続のタスクに渡し、エラーは生成しません。この動作には、以下の利点があります。
-
前のフェーズ (プロビジョニングなど) で指定された情報が後のフェーズ (導入など) で使用され、複数の構成ファイルを編集したり保守したりする必要がありません。
-
複数の ICM バージョン間で一定の前方互換性と後方互換性がサポートされます。
-
複数のプロバイダに対して 1 つの構成ファイルを使用するために必要な作業が最小限になります。
-
JSON 標準では、コンテンツをコメント化する手段は正式には提供されていませんが、名前を変更することによってフィールドを "コメント化" できます。
ICM によって使用される JSON ファイルには、以下のものがあります。
-
定義ファイルと既定値ファイル。これは、ICM のプロビジョニング・フェーズと導入フェーズへの入力としてユーザによって提供されます。既定では、これらのファイルは現在の作業ディレクトリにあることが想定されます (これらのファイルで指定できる必須のフィールドとオプションのフィールドの包括的なリストについては、“ICM リファレンス” の章にある "ICM の構成パラメータ" を参照してください)。
-
インスタンス・ファイル。これは、プロビジョニング・フェーズの最後に ICM によって生成され、導入フェーズへの入力として使用されます。既定では、このファイルは現在の作業ディレクトリに作成されます。
-
Terraform 状態ファイル。これは、プロビジョニング・フェーズ中に ICM によって生成され、プロビジョニング解除など、以後のインフラストラクチャ関連の操作への入力として使用されます。既定では、これらのファイルは、現在の作業ディレクトリの下に ICM によって生成される状態ディレクトリに配置されます。
ICM はほかにも、いくつかのログ・ファイル、出力ファイル、およびエラー・ファイルを生成します。これらは、現在の作業ディレクトリ、または状態ディレクトリに配置されます。
定義ファイル
定義ファイル (definitions.json) は、特定の導入のためにプロビジョニングされるホスト・ノードのセットを記述します。ICM は、現在の作業ディレクトリで見つかった定義ファイルを使用します。
この定義ファイルは、ノード定義を表す一連の JSON オブジェクトから成ります。それぞれのオブジェクトは、属性のリスト、およびそのタイプのノードをいくつ作成する必要があるかを指示するカウントを含みます。必須のフィールドとオプションのフィールドがあり、一部のフィールドはプロバイダ固有です (つまり、AWS、Google Cloud Platform、Microsoft Azure、Tencent、VMware vSphere、または PreExisting で使用)。
このファイルにはほとんどのフィールドを入力でき、ノード定義ごとに必要なだけ繰り返すことができます。ただし、フィールドによっては、1 つの導入された構成全体で一致している必要があるので、定義ファイルのエントリによって既定値から変更することはできません。また、既定値がない場合に、フィールドを指定することもできません。Provider フィールドは分かりやすい例です (明らかな理由から)。definitions.json ファイルに含めることができないその他のフィールド (含めるとエラーが発生します) は、Label および Tag です。
ノード・タイプ (Role など) によって異なるフィールドは、definitions.json のノード定義に含める必要があります。definitions.json は、特定のノード・タイプについて ICM の既定値または defaults.json ファイルの設定をオーバーライドする場合にも使用されます。例えば、以下の例は、AWS 上のミラーリングされたデータ・サーバ ("Role": "DM"")、3 つのアプリケーション・サーバ ("Role": "AM")、およびミラー・アービター・ノード ("Role": "AR") で構成される分散キャッシュ・クラスタをプロビジョニングするためのサンプル definitions.json ファイルの内容を示しています。
-
DataVolumeSize フィールドは、DM ノードについてのみ指定されています。他のノードは ICM の既定値を使用するからです。
-
DM ノードおよび AR ノードの定義には、defaults.json で指定されている既定のインスタンス・タイプをオーバーライドする InstanceType フィールドが含まれています。
-
AR ノードの定義には、defaults.json 内の該当フィールドをオーバーライドする DockerImage フィールドが含まれています。AR ノードには InterSystems IRIS コンテナではなく、アービター・コンテナが導入されるからです。
一部のフィールドは特定のノード・タイプに限定されているので、definitions.json で指定する必要があります。例えば、この AM ノードの定義には、AM ノードについてロード・バランサを自動的にプロビジョニングする "LoadBalancer": "true" が含まれています。この設定は WS ノードでも使用できますが、他のノード・タイプに適用するとエラーが発生します。
[
{
"Role": "DM",
"Count": "2",
"DataVolumeSize": "50",
"InstanceType": "m4.xlarge"
},
{
"Role": "AM",
"Count": "3",
"StartCount": "3",
"LoadBalancer": "true"
},
{
"Role": "AR",
"Count": "1",
"StartCount": "6",
"InstanceType": "t2.small",
"DockerImage": "intersystems/arbiter:2022.2.0.221.0"
}
]
definitions.json ファイルを変更した後、再プロビジョニングや再導入を行うことによって、ノードを追加または削除したり、既存のノードを変更したりして、既存の構成を弾力的に拡張/縮小および変更することができます。
既定値ファイル
一般に、既定値ファイルは特定のタイプの導入すべてにわたって同一フィールドを定義します (特定のクラウド・プラットフォームでプロビジョニングされるものなど)。ICM は、現在の作業ディレクトリで見つかった既定値ファイルを使用します。
"定義ファイル" で説明したように、ほとんどのフィールドはどちらの入力ファイルにも指定できますが、一部は導入全体にわたって一致している必要があり、ノード・タイプごとに別個に指定することはできません (例えば、Provider)。これらのフィールドのほかに、場合によってはすべての導入にわたってすべてのノードにフィールドを適用し、必要に応じてコマンド行または定義ファイルでこれらをオーバーライドしたいこともあります。両方のタイプのフィールドが defaults.json ファイルに含まれています。既定値ファイルに可能な限り多くのフィールドを含めることにより、定義ファイルが小さく保たれ、管理しやすくなります。
既定値ファイルの形式は、単一の JSON オブジェクトです。このファイルに含まれている値は、コマンド行オプションまたは定義ファイルで値が指定されていない (または null である) すべてのフィールドに適用されます。
"定義ファイル" で示した definitions.json ファイルと共に使用されるサンプル defaults.json ファイルの内容を以下に示します。OSVolumeSize、DataVolumeSize、InstanceType など、既定値ファイルで指定される既定値の一部は定義ファイルによってオーバーライドされます。
{
"Provider": "AWS",
"Label": "Sample",
"Tag": "TEST",
"DataVolumeSize": "10",
"SSHUser": "ubuntu",
"SSHPublicKey": "/Samples/ssh/insecure-ssh2.pub",
"SSHPrivateKey": "/Samples/ssh/insecure",
"DockerRegistry": "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"
}
インスタンス・ファイル
インスタンス・ファイル (instances.json) は、プロビジョニング・フェーズ中に ICM によって生成され、正常にプロビジョニングされたホスト・ノードのセットを記述します。この情報は導入および管理フェーズへの入力となるので、このフェーズ中にファイルが使用可能であることが必要で、ファイルが現在の作業ディレクトリにない場合はパスを ICM に対して指定する必要があります。インスタンス・ファイルは現在の作業ディレクトリに作成されます。
定義ファイルにはノード・タイプごとにただ 1 つのエントリが含まれ、各エントリにはそのタイプのノード数を指定する Count 値が含まれていますが、インスタンス・ファイルには実際にプロビジョニングされるノードごとにエントリがあります。例えば、前記のサンプル定義ファイルには 3 つのエントリがありますが (3 つのアプリケーション・サーバ用に 1 つ、2 つのデータ・サーバ用に 1 つ、アービター用に 1 つ)、作成されるインスタンス・ファイルにはプロビジョニングされるノードごとに 1 つずつ、6 つのオブジェクトが含まれます。
各ノードの定義を構成するすべてのパラメータ (定義ファイルと既定値ファイル内のパラメータ、既定値のある構成ファイルで指定されていないパラメータ、内部 ICM パラメータなど) がエントリに含まれるほか、ノードのマシン名 (Label、Role、および Tag の各フィールドから構成される)、ノードの IP アドレス、および DNS 名も含まれます。導入環境の状態ディレクトリ内にあるそのノードのサブディレクトリの場所も含まれます。
状態ディレクトリと状態ファイル
ICM は、プロビジョニングされたインフラストラクチャの存続中に使用されるいくつかの状態ファイル (ログ、生成されるスクリプトなど) を state サブディレクトリに書き込みます。state サブディレクトリは、既定で現在の作業ディレクトリ内に作成されます。
プロビジョニング時に生成される状態ファイルには、Terraform オーバーライド・ファイルと状態ファイル (terraform.tfvars と terraform.tfstate) のほか、Terraform 出力ファイル、エラー・ファイル、およびログ・ファイルが含まれます。これらの Terraform に関連した一連のファイルは、定義ファイル内のノード・タイプ定義ごとに別々のサブディレクトリ内に作成されます。例を以下に示します。
./state/Acme-DM-TEST
./state/Acme-AM-TEST
./state/Acme-AR-TEST
独自の状態ディレクトリを別の名前で作成する場合や別の場所に作成する場合は、icm provision コマンドで -stateDir コマンド行オプションを使用して既定の場所をオーバーライドできますが、その後も -stateDir オプションを引き続き使用して、インフラストラクチャをプロビジョニング解除する場合など、後続のすべてのプロビジョニング・コマンドでその場所を指定する必要があります。
Important:
ICM は、作成する状態ファイルを使用して、プロビジョニングしたインフラストラクチャに関する正確な最新情報を取得します。これらのファイルがなければ、ICM がプロビジョニング状態を再構成することが困難または不可能になり、エラーが発生するほか、場合によっては手動での介入が必要になります。この理由から、状態ディレクトリは信頼性が高く確実にアクセスできるストレージに配置し、適切なバックアップ・メカニズムを実行することをインターシステムズは強くお勧めします。
ログ・ファイルおよび InterSystems Cloud Manager のその他のファイル
ICM は、いくつかのログ・ファイル、出力ファイル、およびエラー・ファイルを現在の作業ディレクトリと state ディレクトリ・ツリー内に書き込みます。現在の作業ディレクトリ内の icm.log ファイルは、ICM の情報メッセージ、警告メッセージ、およびエラー・メッセージを記録します。state ディレクトリ・ツリー内にあるその他のファイルは、コマンドの結果 (エラーを含む) を記録します。例えば、プロビジョニング・フェーズ中のエラーは、通常は terraform.err ファイルに記録されます。
Important:
ICM の操作中にエラーが発生した場合、ICM はログ・ファイルを示すメッセージを表示します。このログ・ファイルで、エラーに関する情報を確認できます。ICM の導入を開始する前に、ログ・ファイルとその場所をよく理解しておいてください。
Docker リポジトリ
ICM によって導入されるそれぞれのイメージは、Docker リポジトリからプル (ダウンロード) されます。多くの Docker イメージはパブリック Docker リポジトリから自由にダウンロードできます。ただし、インターシステムズのリポジトリなど、プライベート・リポジトリにアクセスするには Docker ログインが必要です。
Docker リポジトリへのログイン
導入フェーズの一環として、ICM はユーザが提供する資格情報を使用して、ユーザが指定する Docker リポジトリに各ノードをログインさせます。これは、構成ファイルのいずれかの DockerImage フィールドによって指定されたイメージ、または -image option を使用してコマンド行で指定されたイメージを導入する前に行われます。(リポジトリ名がイメージの指定に含まれている必要があります。)以下の 3 つのフィールドを defaults.json ファイルに組み込んで、必要な情報を指定できます。
-
DockerRegistry
DockerImage によって指定されるイメージを保管する Docker リポジトリのホスト・サーバの DNS 名。このフィールドが含まれていない場合、ICM は docker.comOpens in a new tab にある Docker のパブリック・レジストリを使用します。
DockerImage によって指定されるリポジトリが、DockerRegistry によって指定されるサーバに存在しない場合、導入は失敗してエラーが返されます。
InterSystems Container Registry (ICR) の使用の詳細は、“ICM の使用” の章の "ICM イメージのダウンロード" を参照してください。
-
DockerUsername
Docker ログインに使用されるユーザ名。パブリック・リポジトリの場合は必要ありません。このフィールドが含まれておらず、DockerImage によって指定されるリポジトリがプライベートの場合、ログインは失敗します。
-
DockerPassword
Docker ログインに使用されるパスワード。パブリック・リポジトリの場合は必要ありません。このフィールドが含まれておらず、DockerImage によって指定されるリポジトリがプライベートの場合、パスワードを入力するように求められます (入力内容はマスクされます)。
Note:
$、|、(、) などの特殊文字が DockerPassword フィールドの値に含まれる場合は、2 つの \ 文字でエスケープする必要があります。例えば、パスワード abc$def は、abc\\$def として指定する必要があります。