OCI CLIを利用してコマンドラインからOCIを操作するTips を紹介
CLI(コマンドライン・インタフェース)は、コマンドラインでOracle Cloud Infrastructureのオブジェクトとサービスを操作するためのツールです。
はじめに
Oracle Cloud Infrastructure（OCI）を使用したことがある方であれば、利用された経験がある方が多いかと思います。
今回は OCI CLI（コマンドライン・インタフェース）について、知っておくと便利かと思われる内容をまとめてみました。
インストール方法や基本的な使用方法については割愛させて頂きますので、初めて利用される方は以下のリファレンスをご確認ください。
1.デバッグオプション
コマンド実行しても、中々レスポンスが返ってこないぞってケースでは、コマンドを一旦中断して、–debugオプションを付与して確認してみましょう。
大体は、以下のようにエンドポイントに接続できずにリトライしている様子が出力されるはずです。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
$ oci compute instance list --compartment-id {コンパートメントID} --debug DEBUG:oci_cli.cli_metrics: 2023-09-13 06:05:23.765142: Metrics is not enabled Linux-5.10.102.1-microsoft-standard-WSL2-x86_64-with-glibc2.29 System name: Linux System release : 5.10.102.1-microsoft-standard-WSL2 System version: #1 SMP Wed Mar 2 00:30:59 UTC 2022 env OCI_PYTHON_SDK_NO_SERVICE_IMPORTS is set DEBUG:oci_cli.cli_util:Config File: dict_keys(['log_requests', 'additional_user_agent', 'pass_phrase', 'user', 'fingerprint', 'key_file', 'tenancy', 'region']) DEBUG:oci_cli.cli_util:region: Environment Variable or Parameter DEBUG:oci.base_client.140509712882848:No circuit breaker strategy enabled! DEBUG:oci.base_client.140509712882848:Endpoint: https://iaas.ap-tokyo-1.oraclecloud.com/20160918 INFO:oci.base_client.140509712882848: 2023-09-01 06:05:23.800801: Request: GET https://iaas.ap-tokyo-1.oraclecloud.com/20160918/instances INFO:oci.base_client.140509712882848: 2023-09-01 06:05:35.129771: Request: GET https://iaas.ap-tokyo-1.oraclecloud.com/20160918/instances INFO:oci.base_client.140509712882848: 2023-09-01 06:05:48.047316: Request: GET https://iaas.ap-tokyo-1.oraclecloud.com/20160918/instances ・・・省略) |
この出力を見れば、どこへリクエストを投げているかが分かるので、エンドポイントと正常に疎通ができるように対応すればよいことが分かります。
デフォルトだと、エンドポイントへ接続できない場合は、コマンドが返ってくるまでに時間を要する為、接続できるか、できないかだけを確認したい場合は、–connection-timeoutでデフォルトの10秒から更に短い値で指定し、–no-retryオプションを指定して、リトライしないようにしておくと、コマンドのレスポンスを待つのに長時間待つ必要がなくなります。
2.プロファイルの切替
OCI CLIをインストールすると、資格証明情報を定義したプロファイルが作成されます。
プロファイルはデフォルトでは、 ~/.oci/config に作成されます。
|
1 2 3 4 5 6 7 |
$ cat ~/.oci/config [DEFAULT] user=ocid1.user.oc1..aaaaaaaaqzn5nbdueaw（省略） fingerprint=2e:bb:46:34:4a:95:58:47:ef:27:3e:69:84:（省略） key_file=/path/to/.oci/oci_api_key.pem tenancy=ocid1.tenancy.oc1..aaaaaaaax2k5wjt6nmb4（省略） region=ap-tokyo-1 |
例えば、複数のテナンシーに対して、CLIを実行したいとなった場合、どのようにすればよいでしょうか？
CLIを実行するOSユーザを分ければ、ユーザをスイッチするだけで、異なるデフォルトプロファイルを参照することができますが、同一のOSユーザを使用する場合は、2通りの方法が挙げられます。
既存のプロファイルとは別にプロファイルを作成
1つ目は、プロファイルを既存のファイルパスとは別に作成し、コマンド実行時に --config-file オプションで、そのファイルを指定するようにします。
（プロファイルのファイルパスは、oci setup config 実行時の対話形式の入力の中で、設定可能です。）
|
1 |
$ oci compute instance list --compartment-id {コンパートメントID} --config-file /path/to/config |
また、環境変数 OCI_CLI_CONFIG_FILE でプロファイルのファイルパスを指定することも可能です。
|
1 2 |
$ export OCI_CLI_CONFIG_FILE='/path/to/config' $ oci compute instance list --compartment-id {コンパートメントID} |
既存のプロファイルに、別のセクションで定義する
2つ目は、既存のプロファイルに別のセクションで定義する方法です。
以下は、デフォルトで東京リージョンを参照する設定の下に、リージョンを大阪に変更しただけのセクション Osaka を追加しました。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
$ cat ~/.oci/config [DEFAULT] user=ocid1.user.oc1..aaaaaaaaqzn5nbdueaw（省略） fingerprint=2e:bb:46:34:4a:95:58:47:ef:27:3e:69:84:（省略） key_file=/path/to/.oci/oci_api_key.pem tenancy=ocid1.tenancy.oc1..aaaaaaaax2k5wjt6nmb4（省略） region=ap-tokyo-1 [Osaka] user=ocid1.user.oc1..aaaaaaaaqzn5nbdueaw（省略） fingerprint=2e:bb:46:34:4a:95:58:47:ef:27:3e:69:84:（省略） key_file=/path/to/.oci/oci_api_key.pem tenancy=ocid1.tenancy.oc1..aaaaaaaax2k5wjt6nmb4（省略） region=ap-osaka-1 |
この状態で、コマンドオプションに --profile でセクション名を指定すれば、指定したセクションの情報を使用してコマンド実行します。
|
1 |
$ oci compute instance list --compartment-id {コンパートメントID} --profile Osaka |
こちらも、環境変数 OCI_CLI_PROFILE で読み込むセクションを定義しておくことが可能です。
|
1 2 |
$ export OCI_CLI_PROFILE='Osaka' $ oci compute instance list --compartment-id {コンパートメントID} |
3.oci_cli_rcファイルの使用
OCI CLI には、資格証明情報を定義したプロファイルとは別に、追加設定を行えるファイルがあります。
このファイルでは、デフォルトのオプションパラメータや、コマンドやパラメータのエイリアスを定義することができ、設定ファイルの作成には、 oci setup oci-cli-rc コマンドを実行することで、 ~/.oci/oci_cli_rc にファイルが作成されます。
デフォルトオプションパラメータの定義
デフォルトオプションパラメータが便利に働くケースとしては、頻繁に実行する対象のコンパートメントがあれば、そのコンパートメントID（–compartment-id/-c）があれば、それを定義しておきましょう。
|
1 2 |
[DEFAULT] compartment-id=<コンパートメントのOCID> |
コマンド実行時にコンパートメントIDをパラメータで指定しなかった場合は、ここで定義されたコンパートメントIDが適用されますが、コマンド実行時にパラメータを指定した場合は、そちらが優先されるので、よく実行するコンパートメントIDがあるなら定義しておくとよいでしょう。
コマンドエイリアス
oci setup oci-cli-rc コマンドを実行してCLI構成ファイルを作成した場合は、以下のように2つのコマンドエイリアスが [OCI_CLI_COMMAND_ALIASES] セクションで定義されています。
|
1 2 3 4 5 6 7 8 9 10 |
[OCI_CLI_COMMAND_ALIASES] # This lets you use "ls" instead of "list" for any list command in the CLI ls = list # This lets you do "oci os object rm" rather than "oci os object delete". This is an example of a "command sequence alias", where the alias on the left # hand side only applies when the command sequence on the right hand side is invoked. You can think of these as being of the form: # <alias> = <dot-separated sequence of groups and sub-groups>.<command or group to alias> # # So in our example, <alias> = rm, <sequence of groups and sub-groups> = os object, <command or group to alias> = delete rm = os.object.delete |
1つ目の定義で、CLIコマンドにおける list は全て ls に置き換えることができます。
|
1 2 3 4 |
$ oci compute instance ls --query 'data[0].{name:"display-name"}' { "name": "privins01" } |
2つ目の定義で、オブジェクトストレージからオブジェクトを削除する際の oci os object delete は oci os object rm に置き換えることができます。
|
1 2 3 4 |
$ oci os object rm Usage: oci os object rm [OPTIONS] Error: Missing option(s) --bucket-name, --object-name. |
エラーとなっていますが、バケット名とオブジェクト名を指定する必要がある点から正常にエイリアスが認識されているようです。
また、定義内容から、 oci rm で削除できるのかと推測される方もおられるかもしれませんが、そうゆう訳ではありませんので、ご注意下さい。
パラメータエイリアス
oci setup oci-cli-rc コマンドを実行してCLI構成ファイルを作成した場合は、以下のように4つのパラメータエイリアスが [OCI_CLI_PARAM_ALIASES] セクションで定義されています。
|
1 2 3 4 5 6 |
[OCI_CLI_PARAM_ALIASES] # Parameter aliases either need to start with a double dash (--) or be a single dash (-) followed by a single letter. For example: --foo, -f --ad = --availability-domain --dn = --display-name --egress-rules = --egress-security-rules --ingress-rules = --ingress-security-rules |
こちらは見ての通り、--availability-domain、--display-name、--egress-rules、 --ingress-rules に対するエイリアスが用意されおりますので、コマンドエイリアスと合わせてお好みを定義しておくとよいでしょう。
名前付き問い合わせ
oci setup oci-cli-rc コマンドを実行してCLI構成ファイルを作成した場合は、以下のように [OCI_CLI_CANNED_QUERIES] セクションで名前付き問い合わせが定義されています。
名前付き問い合わせは、 --queryパラメータを使用して出力をフィルタリングまたは操作する際の定義を、名前をキーにして問い合わせ内容を定義します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 |
[OCI_CLI_CANNED_QUERIES] # For list results, this gets the ID and display-name of each item in the list. Note that when the names of attirbutes have # dashes in them they need to be surrounded with double quotes. This query knows to look for a list because of the # [*] syntax get_id_and_display_name_from_list=data[*].{id: id, "display-name": "display-name"} get_id_and_display_name_from_single_result=data.{id: id, "display-name": "display-name"} # Retrieves a comma separated string, for example: # ocid1.instance.oc1.phx.xyz....,cli_test_instance_675195,RUNNING get_id_display_name_and_lifecycle_state_from_single_result_as_csv=data.[id, "display-name", "lifecycle-state"] | join(<code>,</code>, @) # Retrieves comma separated strings from a list of results get_id_display_name_and_lifecycle_state_from_list_as_csv=data[*].[join(<code>,</code>, [id, "display-name", "lifecycle-state"])][] # Filters where the display name contains some text filter_by_display_name_contains_text=data[?contains("display-name", <code>your_text_here</code>)] # Filters where the display name contains some text and pull out certain attributes(id and time-created) filter_by_display_name_contains_text_and_get_attributes=data[?contains("display-name", <code>your_text_here</code>)].{id: id, timeCreated: "time-created"} # Get the top 5 results from a list operation get_top_5_results=data[:5] # Get the last 2 results from a list operation get_last_2_results=data[-2:] # List instance public IPs from list vnics response # Example: oci compute instance list-vnics --instance-id $I --query query://list_public_ips list_public_ips=data[?"public-ip" != null]."public-ip" # Get first public IP from list vnics response # Example: oci compute instance list-vnics --instance-id $I --query query://get_public_ip get_public_ip=data[?"public-ip" != null]."public-ip" | [0] |
例えば、一番上で定義されている get_id_and_display_name_from_list では、リストを取得した際の id と display-name だけを表示するものとして定義されており、以下のように指定することで適用することが可能です。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
$ oci compute instance list --query query://get_id_and_display_name_from_list [ { "display-name": "privins01", "id": "ocid1.instance.oc1.ap-tokyo-1.anxhiljrzif6lvycmb5l26w75lh3rnghq4kjdko7bgkcltvkpi7bgdpciy2a" }, { "display-name": "privins02", "id": "ocid1.instance.oc1.ap-tokyo-1.anxhiljrzif6lvycdu4cphnvpj6n7owczdhgukfqbg7p27a5nllo4zhmmmea" }, { "display-name": "privins03", "id": "ocid1.instance.oc1.ap-tokyo-1.anxhiljrzif6lvycbygxdnripliwcs7pcj35oetbw3sadbtrj4blxl7bgidq" } ] |
こちらも、よく使用される問い合わせ方法があれば、登録しておくとよいと思います。
4.非同期処理の終了を待つ
各サービスのインスタンスの作成や、起動、停止等をCLIで行った際には、リクエスト発行後、処理の完了を待たずにレスポンスが返されます。
複数のリソースに対して処理を行う際に、処理したリソースの状態を確認した上で次の処理を行いたい場合、例えば Compute インスタンスを起動して、起動完了を待ってから次の処理を行いたい場合等では、Terraformを使用するのが最善の手段かと思いますが、CLIでも実現することは可能です。
そのようなコマンドには、 --wait-for-state が活用できます。
例えば、以下のように Compute インスタンスを起動させ、起動状態になるまでコマンドが返ってこなくなるようにするには、以下のようにします。
|
1 2 3 4 5 6 7 8 9 |
$ oci compute instance action --action START --instance-id {インスタンスID} --wait-for-state RUNNING --wait-interval-seconds 10 Action completed. Waiting until the resource has entered state: ('RUNNING',) { "data": { （省略） "lifecycle-state": "RUNNING", "metadata": { （省略） } |
–wait-for-state に指定できる値はコマンドごとに異なる可能性があるので、各コマンドのリファレンスをご参照下さい。
上記例の compute instance action については、こちら になります。
–wait-interval-seconds については、状態を確認しにいく間隔となります。
これも、コマンドによって異なる可能性がありますが、デフォルトの 30秒 を 10秒 に変更しています。
また、--wait-for-state を指定した場合、その状態になるまでの最大待機時間は 20分（1,200秒）となりますので、それ以上に時間を要する処理の待機が見込まれる場合、–max-wait-secondsで最大待機時間を増やしておくことをお勧めします。
5.対話型モード
OCI CLI には対話型モードというものが存在します。
対話型モードを使用するには、OCI CLIのバージョン3.9.1以上である必要がありますが、入力内容に沿って補完候補が表示され、パラメータの情報も表示される為、一度実行したことのあるコマンドであれば、ある程度リファレンスを見なくても実行できるという利点があります。
対話型モードを使用するには、 oci -i を実行します。
実行すると、以下のように表示されます。
例えば、oci compute コマンドの実行をしたい場合は、最初に c を入力するとcから始まるコマンドがリストされます。
キーボードの↑↓で実行したいコマンドを選択し、Enterキーを押下します。
その後、スペースを入力すると、次の補完候補が表示されます。
そのまま、補完していき、パラメータ入力部分で補完候補を表示すると、以下のように必須パラメータは赤色で(*) 表示されます。
対話型モードを使用すれば、リファレンスを見なくても、コマンド実行できる機会が増えるのではないでしょうか。
まとめ
コンソール画面での操作が手間だと感じる事もあり、よく使用するインスタンスの起動、停止等の簡単な操作には、OCI CLI を用いられている方も多いのではないでしょうか。
今後も便利な新機能等があれば、本ブログで発信していきたいと思います。
