<Deploy>

The Deploy operation allows the user to upload a docker image (either “tar” or “tar.gz” format) to the switch and register to the switch’s repository.

The deploy RPC is documented here:

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

The purpose of the deploy RPC is to load an image archive into the docker image registry. The deploy RPC provides equivalent functionality to the “"docker load” command line. The image archive file is expected to be a GZIP or TAR file and contain a valid docker image.

Guidelines and Limitations for <Deploy>

Following are guidelines and limitations for deploy operation.

• The file being deployed must be a valid Docker image in a Gzip or TAR format

• Plugins are not supported

• Only non-interactive remote copy can be done, meaning for SCP/SFTP the administrator must have setup passwordless SSH before the RPC is executed.

• For remote download case, the switch will not send an ImageTransferReady and it is assumed the client will not send a ImageTransferEnd.

RPC Options

The following protobuf messages are exchanged during the RPC execution (refer to RPC proto definition for complete details). These messages are sent by the client to the switch.

The ImageTransfer message is the first message sent from the client to the switch to initiate the deploy operation.

Table showing RemoteDownload message

Bytes Message

ImageTransferEnd Message

The following protobuf messages are sent from the switch to the client.in the form of a DeployResponse message.

• ImageTransferReady -- switch is ready to receive data

• ImageTransferProgress – indicates to client the number of bytes received so far

• ImageTransferSuccess -- indicates to client the transfer was successful

• Google.rpc.Status -- RPC status code

ImageTransferReady Message

ImageTransferProgress Message

ImageTransferSuccess Message

Example Client RPC Interaction

The below examples illustrate the usage of the deploy RPC using one particular client. Other clients will differ in the details but this illustrates the basic interaction.

Example – Direct upload

./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

Example – Remote Deploy

(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>

The ListImage operation would return the list of images in the switch’s local repository. Each image would include the information such as image id, name, and tag.

The ListImage operation supports the following options.

The following example illustrates the usage of ListImage operation.

> 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>

The RemoveImage operation would remove a docker container identified by the name.

By default, the operation would fail if the image is used by some containers. The “force” option may be used to force to stop and remove the image. However, in this case, docker only untags the image.

The RemoveImage operation supports the following options.

following example illustrates the usage of RemoveImage operation

> 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"

Following example illustrates force removal (untag only).

> 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"

Following example illustrates Force removal again after the container is stopped.

> 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>

The StartContainer operation could be used to either start a new container or restart a previously stopped container. The decision is based on the following conditions.

• If the the container does not exist, then start a new container

• Otherwise

  • If the container is already running, then return an error.

  • If the container is stopped but the request includes more fields than just the instance name, then return an error.

  • If the container is stopped and the request contains only the instance name, then start the container.

The StartContainer supports the following options

Guidelines and Limitations

• The StartContainer operation is achieved via “docker run” CLI. The maximum supported length for this CLI is 2500 bytes.

• In the case of RunAs, current docker only supports UID and GID. Container starts with any value of UID and GID and fails when username and group names are provided.

• In case of any warning while starting the container, NXOS would start the container without sending the warning back.

The following example illustrates the usage of StartContainer operation

Example – Start a new container

> 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"
}

Example – Start a new container

> 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"
}

Example – Start an existing and running container

> 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"
}

Example – Start an existing but stopped container

> 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>

The RemoveContainer operation would remove a docker container identified by the name.

By default, the operation would fail if the container is still running. The force option can be used to force to stop and remove the container.

The RemoveContainer operation supports the following options.

It is important to know that containers may continue to exist even if the underlying image has been removed, as there is a certain degree of independence before the docker images and containers. The user should remove the images and containers with caution.

Example

> 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"

Example – Force removal

> 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>

The ListContainer operation would return the list of containers in the switch’s local repository.

Each container would include the information such as the image name, container id, name, running status, metadata which includes the labels and image hash computed by the container runtime.

The ListContainer operation supports the following options

Example

> 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"
 }

Example – All containers

> 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>

The StopContainer operation would stop a docker container identified by the name, and is achieved via the “docker container stop” command. When the “restart” option is specified, It would also restart the docker container using “docker container restart” command.

StopContainer operation supports the following options

Limitations and Caveats

• When the running container is stopped using StopContainer operation, it would take 10s to stop the container without returning error.

• When the running container is stopped with the “force” option, the container will stop after 5s.

The following example illustrates the usage of StopContainer operation.

Example

> 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>

The UpdateContainer operation would update a container instance with a new image and arguments. If the update fails, it shall restore the container back to its previous status.

Note that currently the native docker does not support this operation, and thus NX-OS would achieve this functionality via a sequence docker operation

1. Stop the given container if it is currently running

2. Rename the container to a temporary name as the backup

3. Start a new container with the same container name, using the given new image and arguments

4. If the new container succeeds to run, then remove the backup container

5. If the new container fails to run, then try to restore

   • Stop and remove the new container

   • Rember the backup back to its original container name

   • Start the container if it was running

The UpdateContainer operation supports the following option

Example

> 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>

The Log operation allows to client to fetch the container logs, similar to the “docker container logs” command. The operation can choose whether to “follow” the log.

• If follow=False, the switch would fetch and return the current logs

• If follow=True, the switch would return the current logs, and stream the new logs until the RPC is canceled by the client, or when the container stops.

The Log operation supports the following option

Example

> 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

Example – Follow the logs

> 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>

The CreateVolume operation would create a docker volume identified by the name.

The user can mount this volume into multiple containers.

The CreateVolume operation supports the following options

Guideines and Limitations

• NXOS only supports “LOCAL” driver ro create volume.

• NXOS does not support “Local mount options”.

Example

> 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>

The RemoveVolume operation would remove a docker volume identified by the name.

The RemoveVolume operation supports the following options

Guidelines and Limitations

• The “force” option is not supported by docker, and thus please make sure to detach the volume from all containers to allow the volume to remove successfully

Example

> 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>

The ListVolume operation would return the list of docker volumes.

It includes the volume name, created timestamp, driver, and volume options and labels if applicable.

The ListVolume operation supports the following options

Example

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

[REQ]

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