<Deploy>

展開操作により、ユーザーはDockerイメージ(「tar」または「tar.gz」形式)をスイッチにアップロードし、スイッチのリポジトリに登録できます。

展開 RPC については、次の場所に記載されています：

https://github.com/openconfig/gnoi/blob/main/containerz/containerz.proto#L54

展開 RPC の目的は、イメージアーカイブを Docker イメージレジストリにロードすることです。展開 RPC は、「docker load」コマンドラインと同等の機能を提供します。イメージアーカイブファイルは、GZIP または TAR ファイルで、有効な Docker イメージが含まれている必要があります。

遅延展開に関するガイドラインおよび制限事項

展開操作に関するガイドラインと制限事項は次のとおりです。

• 展開するファイルは、Gzip または TAR 形式の有効な Docker イメージである必要があります。

• プラグインは、サポートされません。

• 非インタラクティブなリモートコピーのみを実行できます。つまり、 SCP/SFTP の場合、管理者は RPC を実行する前にパスワードレス SSH をセットアップ必要があります。

• リモート ダウンロードの場合、スイッチは ImageTransferReady を送信せず、クライアントは ImageTransferEnd を送信しないと見なされます。

RPC オプション

RPC の実行中に次の protobuf メッセージが交換されます（詳細については、RPC プロトコルの定義を参照してください）。これらのメッセージは、クライアントによってスイッチに送信されます。

ImageTransfer メッセージは、展開操作を開始するためにクライアントからスイッチに送信される最初のメッセージです。

RemoteDownload メッセージを示す表

バイトメッセージ

ImageTransferEnd メッセージ

次の protobuf メッセージは、DeployResponse メッセージの形式でスイッチからクライアントに送信されます。

• ImageTransferReady：スイッチはデータを受信する準備が整っています。

• ImageTransferProgress：これまでに受信したバイト数をクライアントに示します。

• ImageTransferSuccess -- クライアントへの転送が成功したことを示します

• Google.rpc.Status：RPC ステータス コード

ImageTransferReady メッセージ

ImageTransferProgress メッセージ

ImageTransferSuccess メッセージ

クライアント RPC インタラクションの例

次の例は、特定のクライアントを使用した展開 RPC の使用方法を示しています。詳細は他のクライアントによって異なりますが、これは基本的な相互作用を示しています。

例：直接アップロード

./gnxi-console --host 172.22.244.142 --port 50051 --cafile /tmp/grpc.pem --hostnameoverride ems.cisco.com -u admin -p <passwd>
--operation gnoi.containerz.deploy --arg image_transfer.name=alpine_dev,image_transfer.tag="DEV-1.0.1",image_transfer.image_size=3309581,
image_transfer.is_plugin=false,local_file=/auto/mtx-dev/sanity/docker/docker_alpine_latest.tar.gz
 
 
### [gnoi.containerz.deploy]-------------------------------
Transfer>>
image_transfer {
  name: "alpine_dev"
  tag: "DEV-1.0.1"
  image_size: 3309581
}
 
[RESP] : 0
 image_transfer_ready {
  chunk_size: 64000
}
 
Sent 52 chunks
End>>
image_transfer_end {
}
 
[RESP] : 0
 image_transfer_progress {
  bytes_received: 2112000
}
 
[RESP] : 0
 image_transfer_success {
  name: "alpine_dev"
  tag: "DEV-1.0.1"
  image_size: 3309581
}
 
The state of docker on n9k:
 
bash-5.1# docker image ls
REPOSITORY                                TAG         IMAGE ID       CREATED         SIZE
busybox                                   latest      af4709625109   5 months ago    4.27MB
alpine_dev                                DEV-1.0.1   2c64cf60f6f0   6 months ago    7.35MB

例：リモート展開

(pyats) [sjc-ads-7111]$ ./gnxi-console --host <ip> --port 50051 --cafile /tmp/grpc.pem --hostnameoverride ems.cisco.com -u admin -p <passwd> --operation gnoi.containerz.deploy --arg image_transfer.name=alpine,image_transfer.tag=new_image,image_transfer.image_size=7349436,image_transfer.remote_download.path=10.0.0.1:/auto/mtx-dev/sanity/docker/docker_alpine_latest.tar.gz,image_transfer.remote_download.protocol=4,image_transfer.remote_download.source_vrf=management,image_transfer.remote_download.credentials.username=<userid>

[gnoi.containerz.deploy]-------------------------------
Transfer>> image_transfer { 
     name: "alpine" 
     tag: "new_image" 
     image_size: 7349436 
     remote_download { 
         path: "10.0.0.1:/auto/mtx-dev/sanity/docker/docker_alpine_latest.tar.gz" 
        protocol: SCP 
        credentials { 
                   username: "<user>" 
           } 
     source_vrf: "management" } }
[RESP] : 0 image_transfer_success { 
       name: "alpine" 
       tag: "new_image" 
       image_size: 7349436 
  }
bash-5.1# docker image ls
REPOSITORY    TAG         IMAGE ID       CREATED        SIZE
busybox       latest      af4709625109   8 months ago   4.27MB
alpine        new_image   2c64cf60f6f0   9 months ago   7.35MB

<ListImage>

ListImage 操作は、スイッチのローカル リポジトリ内のイメージのリストを返します。各イメージには、イメージ ID、名前、タグなどの情報が含まれます。

ListImage 操作は、次のオプションのどれでもサポートします。

次の例は、ListImage 操作の使用方法を示しています。

> gnoi-client --host <ip> --port <port> -u admin -p <pass> containerz.listimage 
  --arg limit=2


[REQ]
 limit: 2

[RESP] : 1
 id: "f7a401783329"
 image_name: "ghcr.io/openconfig/gnmic"
 tag: "latest"

[RESP] : 2
 id: "2c64cf60f6f0"
 image_name: "alpine"
 tag: "latest"

<RemoveImage>

RemoveImage 操作は、名前で識別される Docker コンテナを削除します。

デフォルトでは、イメージが一部のコンテナによって使用されている場合、操作は失敗します。「force」オプションを使用すると、イメージを強制的に停止して削除できます。ただし、この場合、docker はイメージのタグを解除するだけです。

RemoveImage 操作は、次のオプションをサポートします。

次の例は、RemoveImage 操作の使用方法を示しています。

> gnoi-client --host <ip> --port <port> -u admin -p <pass> containerz.removeimage 
  --arg name=alpine

[REQ]
 name: "alpine"

[RESP]
 code: UNKNOWN
detail: "Error response from daemon: conflict: unable to remove repository reference \"alpine\" (must force) - container 21e718a3bf52 is using its referenced image 2c64cf60f6f0\n"

次の例は、強制削除（タグ解除のみ）を示しています。

> gnoi-client --host <ip> --port <port> -u admin -p <pass> containerz.removeimage 
  --arg name=alpine,force=True

[REQ]
 name: "alpine"
force: true

[RESP]
 code: SUCCESS
 detail: "Untagged: alpine:latest\n"

次の例は、コンテナが停止した後に再度強制削除することを示しています。

> gnoi-client --host <ip> --port <port> -u admin -p <pass> containerz.removeimage 
  --arg name= 2c64cf60f6f0,force=True

[REQ]
 name: "foo"
force: true

[RESP]
 code: UNKNOWN
detail: "Deleted: sha256:2c64cf60f6f05256c049f58403d0c3b33f2145a70830cb8e24efa826854c1a46\n"

<StartContainer>

StartContainer 操作は、新しいコンテナを開始するか、以前に停止したコンテナを再起動するために使用できます。判断は、次の条件に基づきます。

• コンテナが存在しない場合は、新しいコンテナを開始します

• otherwise

  • コンテナがすでに実行されている場合は、エラーを返します。

  • コンテナが停止しているが、リクエストにインスタンス名だけではない多くのフィールドが含まれている場合は、エラーを返します。

  • コンテナが停止し、リクエストにインスタンス名のみが含まれている場合は、コンテナを開始します。

StartContainer は次のオプションをサポートしています

ガイドラインと制約事項

• StartContainer 操作は、「docker run」 CLI を介して実現されます。この CLIでサポートされる最大長は 2500 バイトです。

• RunAs の場合、現在の Docker は UID と GID のみをサポートします。コンテナは UID と GID の任意の値で開始し、ユーザー名とグループ名が指定されると失敗します。

• コンテナの起動中に警告が発生した場合、NXOS は警告を返さずにコンテナを起動します。

次の例は、StartContainer 操作を示しています。

例：新しいコンテナの開始

> gnoi-client --host <ip> --port <port> -u admin -p <pass> containerz.startcontainer 
  --arg instance_name=foo,
        image_name=busybox,
        cmd="sh -c \"sleep 300\"",
        volume=my_volume:/docker

[REQ]
 image_name: "busybox"
 cmd: "sh -c \"sleep 300\""
 instance_name: "foo"
 volumes {
   name: "my_volume"
   mount_point: "/docker"
 }

[RESP]
 start_ok {
  instance_name: "foo"
}

例：新しいコンテナの開始

> gnoi-client --host <ip> --port <port> -u admin -p <pass> containerz.startcontainer --arg image_name=alpine,
                        cmd="sh -c \"while true; do $(echo date); sleep 1; done\"",
                        instance_name=foo,
                        volume=my_volume:/docker:True,
                        env=VAR1:value1,env=VAR2:value2,
                        cap.add=FOWNER,
                        cap.add=AUDIT_WRITE,
                        cap.remove=SETFCAP,
                        cap.remove=NET_RAW,
                        network=host,
                        restart.policy=3,restart.attempts=2,
                        run_as.user=1001,run_as.group=2003,
                        label=env:prod,label=team:neteng,
                        limits.max_cpu=1.5,
                        limits.soft_mem_bytes=7000000,
                        limits.hard_mem_bytes=90000000,
                        port=1001:2001
[REQ]
image_name: "alpine2"
cmd: "sh -c \"while true; do date; sleep 1; done\""
instance_name: "foo"
ports {
  internal: 2001
  external: 1001
}
environment {
  key: "VAR1"
  value: "value1"
}
environment {
  key: "VAR2"
  value: "value2"
}
volumes {
  name: "my_volume"
  mount_point: "/docker"
  read_only: true
}
network: "host"
cap {
  add: "FOWNER"
  add: "AUDIT_WRITE"
  remove: "SETFCAP"
  remove: "NET_RAW"
}
restart {
  policy: ON_FAILURE
  attempts: 2
}
run_as {
  user: "1001"
  group: "2003"
}
labels {
  key: "env"
  value: "prod"
}
labels {
  key: "team"
  value: "neteng"
}
limits {
  max_cpu: 1.5
  soft_mem_bytes: 7000000
  hard_mem_bytes: 90000000
}
 
[RESP]
start_ok {
  instance_name: "foo"
}

例：既存の実行中のコンテナの開始

> gnoi-client --host <ip> --port <port> -u admin -p <pass> containerz.startcontainer 
  --arg instance_name=foo,
        image_name=busybox

[REQ]
 image_name: "busybox"
 instance_name: "foo "

[RESP]
 start_error {
  error_code: UNKNOWN
  details: "container is already running"
}

例：既存の停止したコンテナの起動

> gnoi-client --host <ip> --port <port> -u admin -p <pass> containerz.startcontainer 
  --arg instance_name=foo

[REQ]
 instance_name: "foo "

[RESP]
 start_ok {
  instance_name: "foo "
}

<RemoveContainer>

RemoveContainer 操作は、名前で識別される Docker コンテナを削除します。

デフォルトでは、コンテナがまだ実行中の場合、操作は失敗します。force オプションを使用すると、コンテナを強制的に停止して削除できます。

RemoveContainer 操作では、次のオプションがサポートされています。

Docker イメージとコンテナの前には一定の独立性があるため、基礎となるイメージが削除された場合でも、コンテナは存在し続ける可能性があることを認識することが重要です。ユーザーはイメージとコンテナを慎重に削除する必要があります。

例

> gnoi-client --host <ip> --port <port> -u admin -p <pass> containerz.removecontainer 

[REQ]
 name: "foo"

[RESP]
 code: RUNNING
detail: "Error response from daemon: You cannot remove a running container 706723d4ae83e3fa7b5dcfe4edbb8edd570ea8af690c3eef2526f9c603bfba97. Stop the container before attempting removal or force remove\n"

例：強制削除

> gnoi-client --host <ip> --port <port> -u admin -p <pass> containerz.removecontainer 
  --arg force=True

[REQ]
 name: "foo"
force: true

[RESP]
 code: SUCCESS
detail: "Container removed successfully"

<ListContainer>

ListContainer 操作は、スイッチのローカル リポジトリ内のコンテナのリストを返します。

各コンテナには、イメージ名、コンテナ ID、名前、実行ステータス、コンテナランタイムによって計算されたラベルとイメージハッシュを含むメタデータなどの情報が含まれます。

ListContainer 操作では、次のオプションがサポートされます

例

> gnoi-client --host <ip> --port <port> -u admin -p <pass> containerz.listcontainer 
  --arg name=my_volume

[REQ]

[RESP] : 1
 id: "706723d4ae83e3fa7b5dcfe4edbb8edd570ea8af690c3eef2526f9c603bfba97"
 name: "my_volume"
 image_name: "alpine"
 status: RUNNING
 hash {
   method: SHA256
   hash: "sha256:2c64cf60f6f05256c049f58403d0c3b33f2145a70830cb8e24efa826854c1a46"
 }

例：すべてのコンテナ

> gnoi-client --host <ip> --port <port> -u admin -p <pass> containerz.listcontainer 
  --arg all=True 

[REQ]
 all: true

[RESP] : 1
 id: "706723d4ae83e3fa7b5dcfe4edbb8edd570ea8af690c3eef2526f9c603bfba97"
 name: "foo"
 image_name: "alpine"
 status: RUNNING
 hash {
   method: SHA256
   hash: "sha256:2c64cf60f6f05256c049f58403d0c3b33f2145a70830cb8e24efa826854c1a46"
 }

[RESP] : 2
 id: "21e718a3bf525635b606b6a121bf8a79c323da4edc044f2e6c3811cd3219de94"
 name: "test"
 image_name: "alpine"
 status: STOPPED
 hash {
   method: SHA256
   hash: "sha256:2c64cf60f6f05256c049f58403d0c3b33f2145a70830cb8e24efa826854c1a46"
 }

<StopContainer>

StopContainer 操作は、名前で識別される Docker コンテナを停止します。これは、「docker container stop」コマンドを介して実行されます。「restart」オプションを指定した場合、「docker chain restart」コマンドを使用して docker コンテナも再起動します。

StopContainer 操作は次のオプションをサポートしています

制限と不具合

• 実行中のコンテナが StopContainer 操作を使用して停止されると、エラーを返さずにコンテナを停止するのに 10 秒かかります。

• 実行中のコンテナを「force」オプションで停止すると、コンテナは 5 秒後に停止します。

次の例は、StopContainer 操作を示しています。

例

> gnoi-client --host <ip> --port <port> -u admin -p <pass> containerz.stopcontainer 
  --arg instance_name=foo 


[REQ]
 Instance_name: "foo"

[RESP]
 code: SUCCESS
details: "Container stopped/re-started successfully"

<UpdateContainer>

UpdateContainer 操作は、新しいイメージと引数でコンテナ インスタンスを更新します。更新が失敗すると、コンテナは以前の状態に復元されます。

現在、ネイティブのDocker はこの操作をサポートしていないため、NX- OS はシーケンス Docker 操作を介してこの機能を実現することに注意してください。

1. 現在実行中の場合は、指定されたコンテナを停止する

2. コンテナの名前をバックアップとしての一時的な名前に変更します

3. 指定された新しいイメージと引数を使用して、同じコンテナ名で新しいコンテナを開始します。

4. 新しいコンテナの実行に成功した場合は、バックアップ コンテナを削除します。

5. 新しいコンテナの実行に失敗した場合は、復元を試みます

   • 新しいコンテナを停止して削除します。

   • バックアップを元のコンテナ名に戻します

   • 実行していた場合、コンテナを開始します。

UpdateContainer 操作では、次のオプションがサポートされています。

例

> gnoi-client --host <ip> --port <port> -u admin -p <pass> containerz.updatecontainer 
  --arg instance_name=foo,image_name=alpine,params=<same as StartContainer>

[REQ]
 instance_name: "foo"
 image_name: ”alpine”
 params {
  instance_name: "foo"
  cap {
  }
  ...
 }

[RESP]
 updateOk: {
  instanceName: “foo”
 }

<Log>

ログ操作により、「docker container logs」コマンドと同様に、クライアントはコンテナ ログを取得できます。操作で、ログを「フォローする」かどうかを選択できます。

• Follow=False の場合、スイッチは現在のログをフェッチして返します。

• Follow=True の場合、スイッチは現在のログを返し、RPC がクライアントによってキャンセルされるか、コンテナが停止するまで、新しいログをストリーミングします。

ログ操作は、次のオプションのどれでもサポートします

例

> gnoi-client --host <ip> --port <port> -u admin -p <pass> containerz.log 
  --arg instance_name=test

[REQ]
 instance_name: "test"

[RESP] : 1
 msg: "Wed Jun 11 20:21:05 UTC 2025\nWed Jun 11 20:21:06 UTC 2025\nWed Jun 11 20:21:07 UTC 2025\nWed Jun 11 20:21:08 UTC 2025\nWed Jun 11 20:21:09 UTC 2025\nWed Jun 11 20:21:10 UTC 2025\nWed Jun 11 20:21:11 UTC 2025\nWed Jun 11 20:21:12 UTC 2025\n
Wed Jun 11 20:21:13 UTC 2025\nWed Jun 11 20:21:14 UTC 2025\nWed Jun 11 20:21:15 UTC 2025\nWed Jun 11 20:21:16 UTC 2025\nWed Jun 11 20:21:17 UTC 2025\nWed Jun 11 20:21:18 UTC 2025\nWed Jun 11 20:21:19 UTC 2025\nWed Jun 11 20:21:20 UTC 2025\nWed Jun 11 20:21:21 UTC 2025\nWed Jun 11 20:21:22 UTC 2025\nWed Jun 11 20:21:23 UTC 2025\nWed Jun 11 20:21:24 UTC 2025\n"

[RESP] : 2
 msg: "Wed Jun 11 20:21:25 UTC 2025\n

例：ログをたどる

> gnoi-client --host <ip> --port <port> -u admin -p <pass> containerz.log 
  --arg instance_name=test,follow=True

[REQ]
 instance_name: "test"

…

[RESP] : 16
 msg: "Wed Jun 11 20:26:06 UTC 2025\nWed Jun 11 20:26:07 UTC 2025\nWed Jun 11 20:26:08 UTC 2025\nWed Jun 11 20:26:09 UTC 2025\nWed Jun 11 20:26:10 UTC 2025\nWed Jun 11 20:26:11 UTC 2025\nWed Jun 11 20:26:12 UTC 2025\nWed Jun 11 20:26:13 UTC 2025\n"

[RESP] : 17
 msg: "Wed Jun 11 20:26:14 UTC 2025\n"

[RESP] : 18
 msg: "Wed Jun 11 20:26:15 UTC 2025\n"

…

<CreateVolume>

CreateVolume 操作では、名前で識別される Docker ボリュームが作成されます。

ユーザーは、このボリュームを複数のコンテナにマウントできます。

CreateVolume 操作は、次のオプションのどれでもサポートします

注意事項と制限事項

• NXOS は、「LOCAL」のドライバ ro create ボリュームのみをサポートします。

• NXOS は「ローカル マウント オプション」をサポートしていません。

例

> gnoi-client --host <ip> --port <port> -u admin -p <pass> containerz.createvolume 
  --arg name=my_volume

[REQ]
 name: "my_volume"

[RESP] : 1
 name: “my_volume”

<RemoveVolume>

RemoveVolume 操作は、名前で識別される Docker ボリュームを削除します。

RemoveVolume 操作は次のオプションをサポートしています

ガイドラインと制約事項

• 「force」オプションは docker ではサポートされていないため、ボリュームを正常に削除できるように、すべてのコンテナからボリュームを切り離してください

例

> gnoi-client --host <ip> --port <port> -u admin -p <pass> containerz.removevolume 
  --arg name=my_volume

[REQ]
 name: "my_volume"

[RESP] : 1
 name: “my_volume”

<ListVolume>

ListVolume 操作は Docker ボリュームのリストを返します。

これには、ボリューム名、作成されたタイムスタンプ、ドライバ、およびボリュームのオプションと該当する場合、ラベルが含まれます。

ListVolume 操作は次のオプションをサポートします

例

> gnoi-client --host <ip> --port <port> -u admin -p <pass> containerz.listvolume

[REQ]

[RESP] : 1
 name: "92945dc4e9ffdf571c85994738562b1d1f54158f784cac3eadc080c558e034ee"
 created {
   seconds: 1748490463
 }
 driver: "local"