Oracle Cloud Infrastructureドキュメント

インスタンス・メタデータの更新

Oracle Cloud Infrastructure Computeサービスでは、「コマンド・ライン・インタフェース(CLI)」またはREST APIを使用して、インスタンスのカスタム・メタデータを追加および更新できます。

LaunchInstance操作を使用してインスタンスを作成する場合、LaunchInstanceDetailsデータ型metadataまたはextendedMetadata属性でインスタンスのカスタム・メタデータを指定できます。 インスタンス・メタデータを更新するには、UpdateInstance操作を使用して、UpdateInstanceDetailsデータ型metadataまたはextendedMetadata属性でカスタム・メタデータを指定します。 metadata属性ではキーと値の文字列のペアがサポートされ、extendedMetadata属性ではネストされたJSONオブジェクトがサポートされます。

必要なIAMポリシー

Oracle Cloud Infrastructureを使用するには、管理者が作成するポリシーで、コンソールまたはSDK、CLIまたはその他のツールを使用したREST APIのどちらを使用しているかにかかわらず、必要なタイプのアクセスを付与する必要があります。 アクションを実行しようとしたときに、権限のないメッセージや権限のないメッセージを取得する場合は、管理者に付与されているアクセスのタイプと作業するコンパートメントを確認してください。

管理者向け: 「ユーザーがコンピュート・インスタンスを起動できるようにします」のポリシーには、インスタンスの名前を変更する機能が含まれています。 指定したグループがインスタンスを起動したり、ボリュームをアタッチしたりする必要がない場合は、そのポリシーを簡素化してmanage instance-familyのみを組み込み、volume-familyvirtual-network-familyを含むステートメントを削除することができます。

新しいポリシーの場合は、「ポリシーの開始」「共通ポリシー」を参照してください。 インスタンス、クラウド・ネットワーク、またはその他の「コア・サービスAPI」リソースのポリシーを作成する方法について詳しくは、「コア・サービスの詳細」を参照してください。

APIの使用

UpdateInstance操作を使用する場合、インスタンス・メタデータは、UpdateInstanceDetailsデータ型metadataまたはextendedMetadata属性で指定された値の組合せになります。 UpdateInstance 操作でこれらの属性に対して指定されたキー/バリュー・ペアのセットによって、これらの属性の既存の値が置換されるため、追加するものだけでなく、インスタンスのすべてのメタデータ値を各コールに含める必要があります。 UpdateInstanceをコールする際にこの属性を空のままにすると、その属性の既存のメタデータ値が使用されます。 同じメタデータ・キーに値を2回指定できないため、キーが重複しているためにUpdateInstance 操作が失敗します。

このことを理解するには、LaunchInstance操作を使用してインスタンスを作成し、metadata 属性に次のキーと値のペアを指定した例を考えてみます:

"myCustomMetadataKey" : "myCustomMetadataValue"

次にUpdateInstance 操作を呼び出し、追加のキー/バリュー・ペアをextendedMetadata属性で指定して新しいメタデータを追加しますが、metadata 属性を空のままにした場合は、extendedMetadata属性にmyCustomMetadataKey キー/バリューを含めないでください。そのキーがすでに存在するため、これにより操作が失敗します。 メタデータ属性の値を指定する場合、それをインスタンス・メタデータに保持するには、myCustomMetadataKeyキー/バリューを含める必要があります。 この場合、いずれかの属性で指定できます。

2つの予約キー(user_data)とssh_authorized_keysがあり、この予約キーは起動時にインスタンスに対してのみ設定できますが、後で更新することはできません。 メタデータ属性を使用してインスタンスにメタデータを追加または更新する場合、これらの両方のキーの起動時に指定した値が含まれていることを確認する必要があります。含まれていない場合、UpdateInstance 操作は失敗します。

インスタンス・メタデータを更新するベスト・プラクティス

UpdateInstance操作を使用する場合、Oracleは次のことを推奨します:

  • GetInstance操作を使用してインスタンスの既存のカスタム・メタデータを取得し、UpdateInstanceをコールする際に適切な属性に保持する値を含めるようにします。 メタデータ値は、「インスタンス」metadataおよびextendedMetadata属性で返されます。 これを説明するコード例については、「SDK for Java」UpdateInstanceExampleを参照してください。

  • metadata属性を使用して追加されたカスタム・メタデータを更新する場合を除き、extendedMetadata属性を使用してカスタム・メタデータを追加します。 それ以外の場合は、user_dataおよびssh_authorized_keys予約キーの起動時間の値を含める必要があります。 metadata属性を使用して値を追加した場合、これらの予約キーの値を離れるか、これらに別の値を指定すると、UpdateInstanceのコールは失敗します。