インスタンスでのコマンドの実行

コマンド実行機能を使用してインスタンス内のスクリプトを実行することで、コンピュート・インスタンスをリモートで構成、管理およびトラブルシューティングできます。

たとえば、コマンド実行機能は、セカンダリ仮想ネットワーク・インタフェース・カード(VNIC)の構成、アイデンティティ・プロバイダへのインスタンスの結合、SSH接続のトラブルシューティング、クロスリージョン・ディザスタ・リカバリ・シナリオへの対応などのタスクの自動化に役立ちます。

インスタンスにSSHアクセス権がない場合やインバウンド・ポートが開いていない場合でも、インスタンスでコマンドを実行できます。

コマンド実行機能は、Oracle Cloud Agentソフトウェアによって管理されるコンピュート・インスタンスのコマンド実行・プラグインを使用します。

注意

コマンド実行機能を使用して、パスワード、シークレットまたはその他の機密情報をプレーン・テキストで提供または取得しないでください。機密情報を安全に提供および取得するには、オブジェクト・ストレージの場所を使用して、スクリプト・ファイルおよびレスポンスを格納します。Oracle Cloud Infrastructure Vaultを使用して、キーおよびシークレット資格証明を管理します。

サポートされているイメージ

コマンド実行機能は、次のプラットフォーム・イメージを使用するコンピュート・インスタンスでサポートされています:

  • Oracle Autonomous Linux
  • Oracle Linux
  • CentOS
  • Windows Server

サポートされているプラットフォーム・イメージに基づくカスタム・イメージも、コマンド実行機能をサポートしています。

制限事項および考慮事項

  • Linuxインスタンスでは、スクリプトはデフォルトでBashシェルで実行されます。別のプログラムでスクリプトを実行するには、スクリプトの1行目として#!/<path_to_program>を使用します。
  • Windowsインスタンスでは、スクリプトはデフォルトでバッチ・シェルで実行されます。PowerShellでスクリプトを実行するには、スクリプトの1行目として#ps1を使用します。

    PowerShellスクリプトの例を参照してください

    次の例では、PowerShellを使用してインスタンス・メタデータ・サービスを問い合せ、インスタンスOCIDを出力します:

    #ps1
    $instance = Invoke-RestMethod -Headers @{'Authorization' = 'Bearer Oracle'} -Uri http://169.254.169.254/opc/v2/instance/
    Write-Host ('Instance OCID is ' + $($instance.id))
  • プレーン・テキストでインスタンスに直接アップロードするスクリプト・ファイルの最大サイズは4KBです。より大きなファイルを指定するには、ファイルをオブジェクト・ストレージの場所に保存します。
  • プレーン・テキストとして返されるスクリプトの出力は、最後の1KBに制限されます。より大きなレスポンスを保存するには、出力をオブジェクト・ストレージの場所に保存します。
  • オブジェクト・ストレージの場所を使用してスクリプト・ファイルまたはレスポンスを保存する場合、インスタンスにNetwork Access Translation (NAT)ゲートウェイサービス・ゲートウェイインターネット・ゲートウェイなどのアウトバウンド接続が必要です。インスタンスでは、Oracle Cloud Agentソフトウェア、オブジェクト・ストレージおよびIAMのポート443でのエグレス・トラフィックも許可する必要があります。
  • デフォルトでは、一度に2つのスクリプトを実行できます。デフォルトを変更するには、コマンド実行の構成ファイルを更新します:

    cat /etc/oracle-cloud-agent/plugins/runcommand/config.yml

    次のパラメータを設定します:

    logDir: /var/log/oracle-cloud-agent/plugins/runcommand
    commandExecutionMaxWorkers: <number-of-parallel-scripts>
  • 一度に実行できるスクリプトは最大5つです。スクリプトは、コンピュート・インスタンスのコマンド実行プラグインによって受信されたが、まだキューから削除されていない場合、実行中とみなされます。
  • 長時間実行タスクを実行するには、コマンド実行機能を使用して、インスタンスでcronジョブをスケジュールします。コマンドのオーケストレーションはサポートされていません。
  • 各スクリプトは1回実行されます。スクリプトを複数回実行する場合は、cronを使用してスクリプトのスケジュールを構成します。
  • 情報の入力を求めるスクリプトは、サポートされていません。ただし、インスタンス・メタデータ・サービス(IMDS)を使用して、スクリプトが実行されるインスタンスに関する情報をプログラム的に取得できます。
  • コンピュート・インスタンス実行コマンド・プラグインの権限がすでに構成されているカスタム・イメージからインスタンスを作成する場合は、構成ファイルで101-oracle-cloud-agent-run-command100-oracle-cloud-agent-run-commandに置き換えます。
  • 返される終了コードは、標準のLinuxエラー・コードです。終了コード0は成功を示します。
  • スクリプトにオプションのタイムアウトを適用した場合、デフォルトは1時間です。最大値は24時間です。
  • スクリプトを実行できる最大時間は1日です。
  • スクリプトが消費するリソース(CPU使用率など)をモニターするには、メトリックを使用します。
  • スクリプトの取消しは、ベストエフォート試行です。コマンドの実行が終了した後、またはコマンドの有効期限が切れた場合は、コマンドを取り消すことはできません。
  • プレーン・テキストで保存されたスクリプト・ファイルおよびレスポンスは、7日間保持されます。オブジェクト・ストレージの場所に保存されたスクリプト・ファイルおよびレスポンスは、削除するまで保持されます。
  • Oracle Cloud Agentソフトウェアまたはコンピュート・インスタンスのコマンド実行プラグインを停止させるスクリプトを実行しないでください。

管理者権限でのコマンドの実行

コマンドにsudo権限が必要な場合、コマンドを実行できるように、コンピュート・インスタンスのコマンド実行プラグインにsudo権限を付与する必要があります。プラグインは、ocarunユーザーとして実行されます。

cloud-initを使用して、インスタンスの起動時に権限を構成することも、インスタンスの起動後にインスタンスに接続し、権限を手動で構成することもできます。次を行います:

  1. インスタンスで、コンピュート・インスタンスのコマンド実行プラグインのsudoers構成ファイルを作成します:

    vi ./101-oracle-cloud-agent-run-command
  2. 構成ファイルに次の行を追加して、ocarunユーザーがすべてのコマンドをsudoとして実行できるようにします:

    ocarun ALL=(ALL) NOPASSWD:ALL

    必要に応じて、特定のコマンドをリストできます。詳細は、sudoersに関するLinux manページを参照してください。

  3. 構成ファイルの構文が正しいことを確認します:

    visudo -cf ./101-oracle-cloud-agent-run-command

    構文が正しい場合は、次のメッセージが返されます:

    ./101-oracle-cloud-agent-run-command: parsed OK
  4. 構成ファイルを/etc/sudoers.dに追加します:

    sudo cp ./101-oracle-cloud-agent-run-command /etc/sudoers.d/

必要なIAMポリシー

Oracle Cloud Infrastructureを使用するには、管理者によってポリシーでセキュリティ・アクセス権が付与されている必要があります。このアクセス権は、コンソール、あるいはSDK、CLIまたはその他のツールを使用したREST APIのいずれを使用している場合でも必要です。権限がない、または認可されていないというメッセージが表示される場合は、管理者に連絡して、どのタイプのアクセス権があり、どのコンパートメントで作業するかを確認してください。

管理者向け: コマンド実行機能のポリシーを記述するには、次を実行します:

  1. コマンドの発行、コマンドの取消し、およびコンパートメント内のインスタンスのコマンド出力の表示を許可するユーザーを含むグループを作成します。次に、次のポリシーを記述して、グループにアクセス権を付与します:

    Allow group RunCommandUsers to manage instance-agent-command-family in compartment ABC
  2. コマンドの実行を許可するインスタンスを含む動的グループを作成します。たとえば、動的グループ内のルールでは次のように記述できます:

    any { instance.id = 'ocid1.instance.oc1.phx.<unique_ID_1>', 'ocid1.instance.oc1.phx.<unique_ID_2>' }
  3. 次のポリシーを記述して、動的グループにアクセス権を付与します:
    ノート

    インスタンスを作成してから動的グループに追加する場合、インスタンスがコマンドのポーリングを開始するまでに最大30分かかります。最初に動的グループを作成してからインスタンスを作成する場合、インスタンスの作成直後にコマンドのポーリングが開始されます。
    Allow dynamic-group RunCommandDynamicGroup to use instance-agent-command-execution-family in compartment ABC where request.instance.id=target.instance.id
  4. 動的グループがオブジェクト・ストレージ・バケットからスクリプト・ファイルにアクセスし、レスポンスをオブジェクト・ストレージ・バケットに保存できるようにするには、次のポリシーを記述します:

    Allow dynamic-group RunCommandDynamicGroup to read objects in compartment ABC where all {target.bucket.name = '<bucket_with_script_file>'}
    Allow dynamic-group RunCommandDynamicGroup to manage objects in compartment ABC where all {target.bucket.name = '<bucket_for_command_output>'}

ポリシーを初めて使用する場合は、ポリシーの開始共通ポリシーを参照してください。インスタンス、クラウド・ネットワーク、または他のCore Services APIリソースのポリシーを作成するための参照資料については、コア・サービスの詳細を参照してください。

前提条件

  • コンピュート・インスタンスのコマンド実行プラグインをインスタンスで有効にし、プラグインを実行する必要があります。プラグインを有効にして実行する方法の詳細は、Oracle Cloud Agentを使用したプラグインの管理を参照してください。
  • 実行するスクリプトの準備が完了しました。コマンドは、本番ワークフローを実行するインスタンスにデプロイする前に、本番以外の環境でテストすることをお薦めします。
  • オブジェクト・ストレージの場所からスクリプト・ファイルを提供するには、ターゲット・インスタンスと同じリージョンのオブジェクト・ストレージ・バケットにファイルをアップロードします。バケットとファイル名、またはファイルのオブジェクト・ストレージURLを書き留めます。テナンシ間で同じコマンドを使用するには、ファイルを指す事前認証済リクエストを作成します。
  • コマンド出力をオブジェクト・ストレージの場所に保存するには、ターゲット・インスタンスと同じリージョンに、保存先のバケットを作成します。バケット名またはバケットのオブジェクト・ストレージURLを書き留めます。オプションで、オブジェクト・ストレージの場所を指す事前認証済リクエストを使用して、コマンド出力を保存できます。
  • 2020年10月より前にリリースされたプラットフォーム・イメージの場合、コンピュート・インスタンスのコマンド実行プラグイン(バージョン1.5.1以降)をサポートするバージョンに、Oracle Cloud Agentソフトウェアを更新する必要があります

コンソールの使用

インスタンスで実行するコマンドを作成するには
  1. ナビゲーション・メニューを開き、「コンピュート」をクリックします。「コンピュート」で、「インスタンス」をクリックします。
  2. 関心のあるインスタンスをクリックします。
  3. 「リソース」で、「コマンドの実行」をクリックします。
  4. 「コマンドの作成」をクリックします。
  5. コマンドの名前を入力します。機密情報の入力は避けてください。
  6. 「タイムアウト(秒)」ボックスに、コンピュート・インスタンスのコマンド実行プラグインがタイムアウトするまでにインスタンスでコマンドを実行する時間を入力します。タイマーは、プラグインがコマンドを開始すると開始されます。タイムアウトなしの場合は、0を入力します。
  7. 「スクリプトの追加」セクションで、コンピュート・インスタンスのコマンド実行プラグインをインスタンスで実行するスクリプトをアップロードします。次のいずれかのオプションを選択します:

    • スクリプトの貼付け: ボックスにコマンドを貼り付けます。
    • ファイルの選択: スクリプトをテキスト(.txt)ファイルとしてアップロードします。アップロードするファイルを参照するか、ボックスにファイルをドラッグ・アンド・ドロップします。
    • オブジェクト・ストレージ・バケットからインポート: スクリプト・ファイルを含むバケットを選択します。「オブジェクト名」ボックスに、ファイル名を入力します。
    • オブジェクト・ストレージURLからインポート: スクリプト・ファイルのオブジェクト・ストレージURLを入力します。
  8. 「出力タイプ」セクションで、コマンドの出力を保存する場所を選択します:

    • テキストとして出力: 出力はプレーン・テキストとして保存されます。「インスタンスの詳細」ページで出力を確認できます。
    • オブジェクト・ストレージ・バケットに出力: 出力はオブジェクト・ストレージ・バケットに保存されます。バケットを選択します。「オブジェクト名」ボックスに、出力ファイルの名前を入力します。機密情報の入力は避けてください。
    • オブジェクト・ストレージURLに出力: 出力はオブジェクト・ストレージURLに保存されます。URLを入力します。
  9. 「コマンドの作成」をクリックします。
コマンドの出力を表示するには

コマンド出力がオブジェクト・ストレージの場所に保存された場合は、保存されたバケットからレスポンス・オブジェクトをダウンロードするか、オブジェクト・ストレージの事前認証済リクエストURLに移動します。

コマンド出力がプレーン・テキスト・ファイルとして保存された場合は、次を実行します:

  1. ナビゲーション・メニューを開き、「コンピュート」をクリックします。「コンピュート」で、「インスタンス」をクリックします。
  2. 関心のあるインスタンスをクリックします。
  3. 「リソース」で、「コマンドの実行」をクリックします。
  4. リストでコマンドを見つけて、「アクション」メニューをクリックし、「コマンドの詳細の表示」をクリックします。
コマンドを取り消すには
  1. ナビゲーション・メニューを開き、「コンピュート」をクリックします。「コンピュート」で、「インスタンス」をクリックします。
  2. 関心のあるインスタンスをクリックします。
  3. 「リソース」で、「コマンドの実行」をクリックします。
  4. リストでコマンドを見つけて、「アクション」メニューをクリックし、「コマンドの取消し」をクリックします。プロンプトが表示されたら確認します。

APIの使用

APIの使用およびリクエストの署名の詳細は、REST APIおよびセキュリティ資格証明を参照してください。SDKの詳細は、ソフトウェア開発キットとコマンドライン・インタフェースを参照してください。

次のAPI操作を使用して、コマンド実行機能を使用します:

コンピュート・インスタンスのコマンド実行プラグインのトラブルシューティング

コンピュート・インスタンスのコマンド実行プラグインのトラブルシューティングを行うには、プラグインが生成するログを表示します。インスタンスに接続し、次を使用します:

tail -f /var/log/oracle-cloud-agent/plugins/runcommand/runcommand.log

インスタンスに接続せずにプラグインの操作を簡単に表示できるように、Oracle Cloud Infrastructure Loggingサービスを使用してカスタム・ログを作成できます。

ログ・エラー

この項では、ログ・ファイルに表示されるエラーの解決方法について説明します。

ポーリングの失敗

コンピュート・インスタンスのコマンド実行プラグインがコマンドのポーリングに失敗した場合、ログ・ファイルに次のエラーが表示されることがあります:

poll command err: circuitbreaker:[pollCommand] is open, last err:Service error:NotAuthorizedOrNotFound. Authorization failed or requested resource not found. http status code: 404.

このエラーは、コマンド実行機能の動的グループ・ポリシーが有効になっていない場合、またはインスタンスが動的グループに最近追加された場合に発生することがあります。デフォルトでは、インスタンスはテナンシ管理者グループに属していないため、インスタンスの動的グループ権限を明示的に設定する必要があります。動的グループ・ポリシーを有効にする方法の詳細は、必要なIAMポリシーを参照してください。

インスタンスを作成してから動的グループに追加する場合、インスタンスがコマンドのポーリングを開始するまでに最大30分かかります。最初に動的グループを作成してからインスタンスを作成する場合、インスタンスの作成直後にコマンドのポーリングが開始されます。

インスタンスを動的グループに追加した直後に動的グループ・ポリシーをテストするには、次のいずれかのコマンドを使用して、サービスを手動で再起動します:

Oracle Linux 6.x

sudo initctl restart oracle-cloud-agent

Oracle Linux 7.xおよびOracle Linux 8.x

sudo systemctl restart oracle-cloud-agent

Windows Server

net restart ocarun