使用方法

容器管理

创建容器

描述

isula create 命令用于创建一个新的容器。容器引擎会使用指定的容器镜像创建容器读写层，或者使用指定的本地 rootfs 作为容器的运行环境。创建完成后，会将容器的ID输出到标准输出，后续可以使用 isula start 命令启动该容器。新创建的容器状态为 inited 状态

用法

isula create [OPTIONS] IMAGE [COMMAND] [ARG...]

参数

create 命令支持参数参考下表 表 1。

表 1 create 命令参数列表

约束限制

• 使用 --user 或 --group-add 参数，在容器启动阶段校验 user 或 group 时，容器如果使用的是 OCI 镜像，是从镜像的真实 rootfs 的 etc/passwd 和 etc/group 文件中校验，如果使用的是 rootfs 文件夹或块设备作为容器的 rootfs，则校验的是 host 中的 etc/passwd 和 etc/group 文件；查找时使用的 rootfs 会忽略 -v 和 --mount 等挂载参数，意味着使用这些参数尝试覆盖 etc/passwd 和 etc/group 两个文件时，在查找阶段不生效，只在容器真正启动时生效。生成的配置保存在 ”iSulad根目录/engine/容器ID/start_generate_config.json”，文件格式如下：

  {
      "uid": 0,
      "gid": 8,
      "additionalGids": [
          1234,
          8
      ]
  }
  

示例

创建一个新容器

$ isula create busybox  
fd7376591a9c3d8ee9a14f5d2c2e5255b02cc44cddaabca82170efd4497510e1  
$ isula ps -a  
STATUS PID IMAGE   COMMAND EXIT_CODE RESTART_COUNT STARTAT FINISHAT RUNTIME ID 
NAMES  inited -   busybox "sh"    0         0             -       -        lcr     fd7376591a9c fd7376591a9c4521...

启动容器

描述

isula start 命令用于启动一个或多个容器。

用法

isula start [OPTIONS] CONTAINER [CONTAINER...]

参数

start 命令支持参数参考下表 表 2。

表 2 start 命令参数列表

示例

启动一个新容器

$ isula start fd7376591a9c3d8ee9a14f5d2c2e5255b02cc44cddaabca82170efd4497510e1

运行容器

描述

isula run 命令命令用于创建一个新的容器。会使用指定的容器镜像创建容器读写层，并且为运行指定的命令做好准备。创建完成后，使用指定的命令启动该容器。run 命令相当于 create 然后 start 容器。

用法

isula run [OPTIONS] ROOTFS|IMAGE [COMMAND] [ARG...]

参数

run 命令支持参数参考下表 表 3。

表 3 run 命令参数列表

约束限制

• 容器父进程进程退出时，则对应的容器也自动退出。

• 创建普通容器时父进程不能为 init，因为普通容器的权限不够，导致容器可以创建成功，但是 attach进去的时候会卡住。

• 运行容器时，不指定 --net，默认 hostname 为 localhost。

• 使用 --files-limit 参数传入一个很小的值，如 1 时，启动容器时，iSulad 创建 cgroup 子组后先设置 files.limit 值，再将容器进程的 PID 写入该子组的 cgroup.procs 文件，此时容器进程已经打开超过 1 个句柄，因而写入报错导致启动失败启动容器会失败。

• --mount 参数和 --volume 参数同时存在时，如果目的路径有冲突，则 --mount 会在 --volume 之后挂载(即将 --volume 中的挂载点覆盖掉)。

  备注：轻量级容器的参数中 type 支持 bind 或 squashfs，当 type=squashfs 时，src 是镜像的路径；原生 docker 的参数 type 支持 bind、volume、tmpfs。

• restart 重启策略不支持 unless-stopped。

• 以下三种情况与 docker 返回值不一致，docker 返回 127，轻量级容器返回125

  --device 参数指定主机设备为不存在的设备

  --hook-spec 参数指定不存在的hook json文件

  --entrypoint 参数指定不存在的入口参数

• 使用 --volume 参数时，由于容器启动时会对 /dev/ptmx 设备进行删除重建，因此请勿将 /dev 目录挂载至容器 /dev 目录，应使用 --device 对 /dev 下的设备在容器中进行挂载。

• 禁止使用 echo 的方式向 run 命令的 stdin 输入数据，会导致客户端卡死。应该直接将 echo 的值作为命令行参数传给容器。

  [root@localhost ~]# echo ls | isula run -i busybox /bin/sh   
  ^C
  [root@localhost ~]#
  

  上述命令出现客户端卡死现象，这是由于上述命令相当于往 stdin 输入 ls，随后 EOF 被读取，客户端不再发送数据，等待服务端退出，但是服务端无法区分客户端是否需要继续发送数据，因而服务端卡在 read 数据上，最终导致双方均卡死。
  正确的执行方式为：

  [root@localhost ~]# isula run -i busybox ls
  bin
  dev
  etc
  home
  proc
  root
  sys
  tmp
  usr
  var
  [root@localhost ~]#
  

• 试试 host 的根目录（/）作为容器的文件系统，那么在挂载路径时，如果有如下情况

  表 4 挂载情况

须知： 第一种情况，先挂载 /home/test1，然后挂载 /home/test2，这种情况会导致
/home/test1 的内容覆盖掉原来 /mnt 下面的内容，这样可能导致 /mnt 下面不存在 abc 目录，这样会导致挂载 /home/test2 到 /mnt/abc 失败。

第二种情况，先挂载 /home/test2，然后挂载 /home/test1。这种情况，第二次的挂载会把 /mnt 的内容替换为 /home/test1 的内容，这样第一次挂载的 /home/test2 到 /mnt/abc 的内容就看不到了。

因此，不支持第一种使用方式；第二种使用用户需要了解这种数据无法访问的风险。

须知：

• 高并发场景（并发启动 200 容器）下，glibc 的内存管理机制会导致内存空洞以及虚拟 > 内存较大（例如 10 GB）的问题。该问题是高并发场景下 glibc 内存管理机制的限制， 而不是内存泄露，不会导致内存消耗无限增大。可以通过设置 MALLOC_ARENA_MAX 环境变 量来减少虚拟内存的问题，而且可以增大减少物理内存的概率。但是这个环境变量会导致 iSulad 的并发性能下降，需要用户根据实际情况做配置。

 参考实践情况，平衡性能和内存，可以设置 MALLOC_ARENA_MAX 为 4。（在 arm64 服务器上面对 iSulad 的性能影响在 10% 以内）  
 配置方法：  
   1. 手动启动 iSulad 的场景，可以直接 export MALLOC_ARENA_MAX=4，然后再启动 iSulad 即可。  
   2. systemd 管理 iSulad 的场景，可以修改 /etc/sysconfig/iSulad，增加一条 MALLOC_ARENA_MAX=4 即可。

示例

运行一个新容器

$ isula run -itd busybox
9c2c13b6c35f132f49fb7ffad24f9e673a07b7fe9918f97c0591f0d7014c713b

停止容器

描述

isula stop 命令用于停止一个或多个运行中的容器。首先向容器中的首进程会发送 SIGTERM 信号，在指定时间（默认为 10 s）内容器未停止时，会发送 SIGKILL。

用法

isula stop [OPTIONS] CONTAINER [CONTAINER...]

参数

stop 命令支持参数参考下表 表 5。

表 5 stop 命令参数列表

约束限制

• 指定 t 参数且 t<0 时，请确保自己容器的应用会处理 stop 信号。

  Stop 的原理：Stop 会首先给容器发送 Stop 信号（SIGTERM），然后等待一定的时间（这个时间就是用户输入的 t），过了指定时间如果容器还仍处于运行状态，那么就发送 kill 信号（SIGKILL）强杀。

• 输入参数t的含义：

  t<0 : 表示一直等待，不管多久都等待程序优雅退出，既然用户这么输入了，表示对自己的应用比较放心，认为自己的程序有 合理的 stop 信号的处理机制。

  t=0 ： 表示不等，立即发送 kill -9 到容器。

  t>0 ： 表示等一定的时间，如果容器还未退出，就发送 kill -9 到容器。

  所以如果用户使用 t<0 （比如t=-1），请确保自己容器的应用会正确处理 SIGTERM。 如果容器忽略了该信号，会导致 isula stop 一直卡住。

示例

停止一个容器

$ isula stop fd7376591a9c3d8ee9a14f5d2c2e5255b02cc44cddaabca82170efd4497510e1
fd7376591a9c3d8ee9a14f5d2c2e5255b02cc44cddaabca82170efd4497510e1

强制停止容器

描述

isula kill命令用于强制停止一个或多个运行中的容器。

用法

isula kill [OPTIONS] CONTAINER [CONTAINER...]

参数

kill 命令支持参数参考下表 表 6。

表 6 kill 命令参数列表

示例

杀掉一个容器

$ isula kill fd7376591a9c3d8ee9a14f5d2c2e5255b02cc44cddaabca82170efd4497510e1
fd7376591a9c3d8ee9a14f5d2c2e5255b02cc44cddaabca82170efd4497510e1

删除容器

描述

isula rm 命令用于删除一个或多个容器。

用法

isula rm [OPTIONS] CONTAINER [CONTAINER...]

参数

rm 命令支持参数参考下表 表 7。

表 7 rm 命令参数列表

约束限制

• 在 IO 正常情况，空环境（只有 1 个容器）删除一个 running 容器的时间为 T1，200 个容器的环境（容器无大量 IO 操作，host IO 正常）删除一个 running 容器所需时间为 T2。T2 的规格为：T2 = max { T1 * 3, 5 } 秒钟。

示例

删除一个停止状态的容器

$ isula rm fd7376591a9c3d8ee9a14f5d2c2e5255b02cc44cddaabca82170efd4497510e1
fd7376591a9c3d8ee9a14f5d2c2e5255b02cc44cddaabca82170efd4497510e1

接入容器

描述

isula attach 命令用于将当前终端的标准输入、标准输出和标准错误连接到正在运行的容器。

用法

isula attach [OPTIONS] CONTAINER

参数

attach 命令支持参数参考下表 表 8。

表 8 attach 命令参数列表

约束限制

• 原生 docker attach 容器会直接进入容器，而 isulad attach 容器后需要敲一个回车才进入。

示例

接入一个运行状态的容器

$ isula attach fd7376591a9c3d8ee9a14f5d2c2e5255b02cc44cddaabca82170efd4497510e1
/ #
/ #

重命名容器

描述

isula rename 命令用于重命名容器。

用法

isula rename [OPTIONS] OLD_NAME NEW_NAME

参数

rename 命令支持参数参考下表 表 9。

表 9 rename 命令参数列表

示例

重命名一个容器

$ isula rename my_container my_new_container

在容器中执行新命令

描述

isula exec 命令用于正在运行的容器中运行一个新命令。新执行的命令将在容器的默认目录中运行。如果基础镜像指定了自定义目录，则将使用该目录。

用法

isula exec [OPTIONS] CONTAINER COMMAND [ARG...]

参数

exec 命令支持参数参考下表 表 10。

表 10 exec 命令参数列表

约束限制

• isula exec 不指定任何参数时，会默认使用-it参数， 表示分配一个伪终端，以交互式的方式进入容器

• 当使用 isula exec 执行脚本，在脚本中执行后台进程时，需使用 nohup 标志忽略 SIGHUP 信号。

  使用 isula exec 运行脚本,在脚本中运行后台进程需使用 nohup 标志。否则内核会在 exec 执行的进程（session 首进程）退出时，向后台执行的进程发送 SIGHUP 信号，导致后台进程退出，出现僵尸进程。

• isula exec 进入容器进程后，不能执行后台程序，否则会出现卡死现象。

  isula exec 执行后台进程的方式如下：

  1. 使用 isula exec 进入容器终端，isula exec container_name bash

  2. 进入容器后，执行 script &

  3. 执行exit，导致终端卡死

     isula exec 进入容器后，执行后台程序卡住的原因为 isula exec 进入容器运行后台 while1 程序，当 bash 退出时，while1 程序并不会退出，变为孤儿进程由 1 号
     进程接管，while1 程序是由容器的初始 bash 进程 fork &exec 执行的，while1 进程复制了 bash 进程的文件句柄，导致 bash 退出时，句柄并未完全关闭，导致 
     console 进程收不到句柄关闭事件，epoll_wait 卡住，进程不退出。
     

• isula exec 不能用后台方式执行，否则可能会出现卡死现象。

  isula exec 后台执行的方式如下：

  使用 isula exec 脚本 & 的方式后台执行 exec，如：isula exec container_name script & ，isula exec 后台执行，执行的脚本中不断 cat 某一文件，正常时在当前终端有输出，如果在当前终端执行回车操作，客户端会因读 IO 失败而退出读 stdout 的动作，使终端不再输出，服务端由于进程仍然在 cat 文件，会继续往 fifo 的 buffer 里写入数据，当缓存写满时，容器内进程会卡死在 write 动作上。

• 轻量级容器使用 exec 执行带有管道操作的命令时，建议使用 /bin/bash -c 方式执行该命令。

  典型应用场景：

使用 isula exec container_name -it ls /test | grep “xx” | wc -l，用于统计 test 目录下 xx 的文件个数，因 exec 执行的为 ls /test，其输出通过管道进行 grep、wc 处理。exec 执行的为 ls /test 的输出会换行，再针对该输出进行处理时，结果有误。

原因：使用 exec 执行 ls /test，输出带有换行，针对该输出进行 | grep “xx” | wc -l，处理结果为2（两行）

  [root@localhost ~]# isula exec  -it container ls /test
  xx    xx10  xx12  xx14  xx3   xx5   xx7   xx9
  xx1   xx11  xx13  xx2   xx4   xx6   xx8
  [root@localhost ~]#

建议处理方式：使用 run/exec 执行带有管道操作的命令时，使用 /bin/bash -c 执行命令，在容器中执行管道操作。

  [root@localhost ~]# isula exec  -it container  /bin/sh -c "ls /test | grep "xx" | wc -l"
  15
  [root@localhost ~]#

• 禁止使用 echo 的方式向 exec 命令的 stdin 输入数据，会导致客户端卡死。应该直接将 echo 的值作为命令行参数传给容器

  [root@localhost ~]# echo ls | isula exec 38 /bin/sh
  ^C
  [root@localhost ~]#
  

上述命令可能出现客户端卡死现象，这是由于上述命令相当于往 stdin 输入 ls，随后 EOF 被读取，客户端不再发送数据，等待服务端退出，但是服务端无法区分客户端是否需要继续发送数据，因而服务端卡在 read 数据上，最终导致双方均卡死。

正确的执行方式为：

  [root@localhost ~]# isula exec 38 ls
  bin   dev   etc   home  proc  root  sys   tmp   usr   var

示例

在运行中的容器中，执行 echo 命令

$ isula exec c75284634bee echo "hello,world"
hello,world

查询单个容器信息

描述

isula inspect 提供了容器的详细信息。

用法

isula inspect [OPTIONS] CONTAINER|IMAGE [CONTAINER|IMAGE...]

参数

inspect 命令支持参数参考下表 表 11。

表 11 inspect 命令参数列表

约束限制

• 轻量级容器不支持 format 为 “{{.State}}” 的格式化输出，支持 “{{json.State}}” 的 json 格式化输出。当 inspect 镜像时，不支持 -f 参数。

示例

查询容器信息

$ isula inspect c75284634bee
[
    {
        "Id": "c75284634beeede3ab86c828790b439d16b6ed8a537550456b1f94eb852c1c0a",
        "Created": "2019-08-01T22:48:13.993304927-04:00",
        "Path": "sh",
        "Args": [],
        "State": {
            "Status": "running",
            "Running": true,
            "Paused": false,
            "Restarting": false,
            "Pid": 21164,
            "ExitCode": 0,
            "Error": "",
            "StartedAt": "2019-08-02T06:09:25.535049168-04:00",
            "FinishedAt": "2019-08-02T04:28:09.479766839-04:00",
            "Health": {
                "Status": "",
                "FailingStreak": 0,
                "Log": []
            }
        },
        "Image": "busybox",
        "ResolvConfPath": "",
        "HostnamePath": "",
        "HostsPath": "",
        "LogPath": "none",
        "Name": "c75284634beeede3ab86c828790b439d16b6ed8a537550456b1f94eb852c1c0a",
        "RestartCount": 0,
        "HostConfig": {
            "Binds": [],
            "NetworkMode": "",
            "GroupAdd": [],
            "IpcMode": "",
            "PidMode": "",
            "Privileged": false,
            "SystemContainer": false,
            "NsChangeFiles": [],
            "UserRemap": "",
            "ShmSize": 67108864,
            "AutoRemove": false,
            "AutoRemoveBak": false,
            "ReadonlyRootfs": false,
            "UTSMode": "",
            "UsernsMode": "",
            "Sysctls": {},
            "Runtime": "lcr",
            "RestartPolicy": {
                "Name": "no",
                "MaximumRetryCount": 0
            },
            "CapAdd": [],
            "CapDrop": [],
            "Dns": [],
            "DnsOptions": [],
            "DnsSearch": [],
            "ExtraHosts": [],
            "HookSpec": "",
            "CPUShares": 0,
            "Memory": 0,
            "OomScoreAdj": 0,
            "BlkioWeight": 0,
            "BlkioWeightDevice": [],
            "CPUPeriod": 0,
            "CPUQuota": 0,
            "CPURealtimePeriod": 0,
            "CPURealtimeRuntime": 0,
            "CpusetCpus": "",
            "CpusetMems": "",
            "SecurityOpt": [],
            "StorageOpt": {},
            "KernelMemory": 0,
            "MemoryReservation": 0,
            "MemorySwap": 0,
            "OomKillDisable": false,
            "PidsLimit": 0,
            "FilesLimit": 0,
            "Ulimits": [],
            "Hugetlbs": [],
            "HostChannel": {
                "PathOnHost": "",
                "PathInContainer": "",
                "Permissions": "",
                "Size": 0
            },
            "EnvTargetFile": "",
            "ExternalRootfs": ""
        },
        "Mounts": [],
        "Config": {
            "Hostname": "localhost",
            "User": "",
            "Env": [
                "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
                "TERM=xterm",
                "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
            ],
            "Tty": true,
            "Cmd": [
                "sh"
            ],
            "Entrypoint": [],
            "Labels": {},
            "Annotations": {
                "log.console.file": "none",
                "log.console.filerotate": "7",
                "log.console.filesize": "1MB",
                "rootfs.mount": "/var/lib/isulad/mnt/rootfs",
                "native.umask": "secure"
            },
            "HealthCheck": {
                "Test": [],
                "Interval": 0,
                "Timeout": 0,
                "StartPeriod": 0,
                "Retries": 0,
                "ExitOnUnhealthy": false
            }
        },
        "NetworkSettings": {
            "IPAddress": ""
        }
    }
]

查询所有容器信息

描述

isula ps 用于查询所有容器的信息。

用法

isula ps [OPTIONS]

参数

ps 命令支持参数参考下表 表 12。

表 12 ps 命令参数列表

示例

查询所有容器信息

$ isula ps -a
ID           IMAGE                                     STATUS  PID    COMMAND EXIT_CODE RESTART_COUNT STARTAT        FINISHAT    RUNTIME NAMES
e84660aa059c rnd-dockerhub.huawei.com/official/busybox running 304765 "sh"    0         0             13 minutes ago -           lcr     e84660aa059cafb0a77a4002e65cc9186949132b8e57b7f4d76aa22f28fde016
$ isula ps -a --format "table {{.ID}} {{.Image}}" --no-trunc
ID                                                               IMAGE
e84660aa059cafb0a77a4002e65cc9186949132b8e57b7f4d76aa22f28fde016 rnd-dockerhub.huawei.com/official/busybox

重启容器

描述

isula restart 用于重启一个或者多个容器。

用法

isula restart [OPTIONS] CONTAINER [CONTAINER...]

参数

restart 命令支持参数参考下表 表 13。

表 13 restart 命令参数列表

约束限制

• 指定t参数且 t<0 时，请确保自己容器的应用会处理 stop 信号。

  restart 会首先调用 stop 停止容器。stop 会首先给容器发送 stop 信号（SIGTERM），然后等待一定的时间（这个时间就是用户输入的 t），过了一定时间如果容器仍处于运行状态，那么就发送 kill信号（SIGKILL）强杀。

• 输入参数 t 的含义：

  t<0 : 表示一直等待，不管多久都等待程序优雅退出，既然用户这么输入了，表示对自己的应用比较放心，认为自己的程序有合理的 stop 信号的处理机制。

  t=0 ： 表示不等，立即发送 kill -9 到容器。

  t>0 ： 表示等一定的时间，如果容器还未退出，就发送 kill -9 到容器。

  所以如果用户使用 t<0（比如t=-1），请确保自己容器的应用会正确处理 SIGTERM。 如果容器忽略了该信号，会导致 isula restart 一直卡住。

示例

重启单个容器

$ isula restart c75284634beeede3ab86c828790b439d16b6ed8a537550456b1f94eb852c1c0a
 c75284634beeede3ab86c828790b439d16b6ed8a537550456b1f94eb852c1c0a

等待容器退出

描述

isula wait 用于等待一个或者多个容器退出。

用法

isula wait [OPTIONS] CONTAINER [CONTAINER...]

参数

wait 命令支持参数参考下表 表 14。

表 14 wait 命令参数列表

示例

等待单个容器退出

$ isula wait c75284634beeede3ab86c828790b439d16b6ed8a537550456b1f94eb852c1c0a
 137

查看容器中进程信息

描述

isula top 用于查看容器中的进程信息。

用法

isula top [OPTIONS] container [ps options]

参数

top 命令支持参数参考下表 表 15。

表 15 top 命令参数列表

示例

查询容器中进程信息

$ isula top 21fac8bb9ea8e0be4313c8acea765c8b4798b7d06e043bbab99fc20efa72629c
UID        PID  PPID  C STIME TTY          TIME CMD
root     22166 22163  0 23:04 pts/1    00:00:00 sh

查看容器使用的资源

描述

isula stats 用于实时显示资源使用的统计信息。

用法

isula stats [OPTIONS] [CONTAINER...]

参数

stats 命令支持参数参考下表 表 16。

表 16 stats 命令参数列表

示例

显示资源使用的统计信息

$ isula stats --no-stream 21fac8bb9ea8e0be4313c8acea765c8b4798b7d06e043bbab99fc20efa72629c                                                                                 CONTAINER        CPU %      MEM USAGE / LIMIT          MEM %      BLOCK I / O                PIDS      
21fac8bb9ea8     0.00       56.00 KiB / 7.45 GiB       0.00       0.00 B / 0.00 B            1

获取容器日志

描述

isula logs 用于获取容器的日志。

用法

isula logs [OPTIONS] [CONTAINER...]

参数

logs 命令支持参数参考下表 表 17。

表 17 logs 命令参数列表

约束限制

• 容器串口 logs 日志记录功能，默认为开启状态，需要关闭可以通过 isula create --log-opt disable-log=true 或 isula run --log-opt disable-log=true 关闭。

示例

获取容器日志

$ isula logs 6a144695f5dae81e22700a8a78fac28b19f8bf40e8827568b3329c7d4f742406
hello, world
hello, world
hello, world

容器与主机之间数据拷贝

描述

isula cp 用于容器与主机之间的数据拷贝。

用法

isula cp [OPTIONS] CONTAINER:SRC_PATH DEST_PATH
isula cp [OPTIONS] SRC_PATH CONTAINER:DEST_PATH

参数

cp 命令支持参数参考下表 表 18。

表 18 cp 命令参数列表

约束限制

• iSulad 在执行拷贝时，不会挂载 /etc/hostname， /etc/resolv.conf，/etc/hosts三个文件，也不会对 --volume 和 --mount 参数传入的参数挂载到 host，所以对这些文件的拷贝使用的是镜像中的原始文件，而不是真实容器中的文件。

  [root@localhost tmp]# isula cp b330e9be717a:/etc/hostname /tmp/hostname
  [root@localhost tmp]# cat /tmp/hostname
  [root@localhost tmp]#
  

• iSulad 在解压文件时，不会对文件系统中即将被覆盖的文件或文件夹做类型判断，而是直接覆盖，所以在拷贝时，如果源为文件夹，同名的文件会被强制覆盖为文件夹；如果源为文件，同名的文件夹会被强制覆盖为文件。

  [root@localhost tmp]# rm -rf /tmp/test_file_to_dir && mkdir /tmp/test_file_to_dir
  [root@localhost tmp]# isula exec b330e9be717a /bin/sh -c "rm -rf /tmp/test_file_to_dir && touch /tmp/test_file_to_dir"
  [root@localhost tmp]# isula cp b330e9be717a:/tmp/test_file_to_dir /tmp
  [root@localhost tmp]# ls -al /tmp | grep test_file_to_dir
  -rw-r-----    1 root     root             0 Apr 26 09:59 test_file_to_dir
  

• iSulad 在 cp 拷贝过程中，会将容器 freeze 住，在拷贝完成后，恢复容器运行。

示例

将主机 /test/host 目录拷贝到容器 21fac8bb9ea8 的 /test 目录下。

isula cp /test/host 21fac8bb9ea8:/test

将容器 21fac8bb9ea8 的 /www 目录拷贝到主机的 /tmp 目录中。

isula cp 21fac8bb9ea8:/www /tmp/

支持CNI网络

描述

实现 CRI 接口对接 CNI 网络的能力，包括 CNI 网络配置文件的解析、 CNI 网络的加入和退出。Pod 需要支持网络时，例如通过 canal 等容器网络插件提供网络能力，那么需要 CRI 接口能够和 canal 实现对接，并且调用 canal 的接口，为 Pod 提供网络能力。

接口

CNI 对用户可见的接口，主要涉及 CNI 网络配置和 Pod 配置中 CNI 网络相关的项。

• CNI 网络配置相关的接口，主要是 isulad 指定 CNI 网络配置文件所在路径、CNI 网络插件二进制文件所在的路径以及使用的网络模式；表19 CNI网络配置接口。
• Pod 配置中 CNI 网络相关的项，主要是设置 Pod 加入的附加 CNI 网络列表，默认情况 Pod 只会加入到 default CNI 网络平面中，可以通过该配置把 Pod 加入到多个 CNI 网络平面中。

表 19 CNI 网络配置接口

附加 CNI 网络配置方式：

在 Pod 的配置文件的 ”annotations” 中，增加一项 ”network.alpha.kubernetes.io/network” ： “网络平面配置”；

网络平面配置为 json 格式，包含两项：

• name：指定 CNI 网络平面的名字
• interface：指定网络接口的名字

附件 CNI 网络配置方式示例如下：

"annotations" : {
        "network.alpha.kubernetes.io/network": "{\"name\": \"mynet\", \"interface\": \"eth1\"}"
 }

CNI 网络配置说明

CNI 网络配置包含两种类型，文件格式都为 json：

• 单网络平面配置，以 .conf 和 .json 为后缀的文件：具体的配置项请参见”附录 > CNI 配置参数” 章节的 “表 CNI 单网络配置参数”。
• 多网络平面配置，以 .conflist 为后缀的文件：具体的配置项请参见”附录 > CNI 配置参数” 章节的 “表3 CNI 多网络配置参数”。

加入 CNI 网络列表

如果 iSulad 配置了 --network-plugin=cni，而且设置了 default 网络平面配置，那么在启动 Pod 的时候，会自动把 Pod 加入到 default 网络平面。如果在 Pod 的配置中配置了附加网络配置，那么启动 Pod 的时候也会把 Pod 加入到这些附加网络平面中。

Pod 配置中和网络相关的还有 port_mappings 项，用于设置 Pod 的端口映射关系。配置方式如下：

"port_mappings":[
     { 
         "protocol": 1,
         "container_port": 80,
         "host_port": 8080
      }
]

• protocal：表示映射使用的协议，支持 tcp（用0标识）、udp（用1标识）；
• container_port：表示容器映射出去的 port；
• host_port：表示映射到主机的 port。

退出 CNI 网络列表

StopPodSandbox 的时候，会调用退出 CNI 网络的接口，清理网络相关的资源。

警告：

1. 在调用 RemovePodSandbox 接口之前，至少要调用一次 StopPodSandbox 接口。
2. StopPodSandbox 调用 CNI 接口失败，导致的网络资源残留，由 canal 组件负责清理。

使用限制

• cniVersion 的版本，当前只支持 0.3.0 和 0.3.1。由于后期可能需要支持 0.1.0 和 0.2.0，错误日志打印时，保留了 0.1.0 和 0.2.0 的提示信息。
• name：必须是小写字符、数字、’-‘ 以及 ’.‘ 组成； ‘.‘ 和 ’-‘ 不能作为首字符和尾字符； 而且长度不超过 200 个字符。
• 配置文件个数不超过 200 个，单个配置文件大小不超过 1 MB。
• 扩展之后的参数，需要根据实际网络需求来配置，不需要使用的可选参数可以不写入到 netconf.json 文件中。

容器资源管理

资源的共享

描述

容器间或者容器与 host 之间可以共享 namespace 信息，包括 pid，net，ipc，uts。

用法

isula create/run 时使用 namespace 相关的参数共享资源，具体参数见下方参数列表。

参数

create/run 时可以指定下列参数。

示例

如果两个容器需要共享同一个 pid namespace，在运行容器时，直接加上 --pid container。 即可，如：

isula run -tid --name test_pid busybox sh
isula run -tid --name test --pid container:test_pid busybox sh

限制运行时的 CPU 资源

描述

可以通过参数限制容器的各项 cpu 资源值。

用法

isula create/run 时使用 cpu 相关的参数限制容器的各项 cpu 资源值，具体参数及取值见下方参数列表。

参数

create/run 时可以指定下列参数。

示例

如果需要限制容器只是用特定的 cpu，在运行容器时，直接加上 --cpuset-cpus number 即可，如：

isula run -tid --cpuset-cpus 0,2-3 busybox sh

说明：

是否设置成功，请参见“查询单个容器信息”章节。

限制运行时的内存

描述

可以通过参数限制容器的各项内存值上限。

用法

isula create/run 时使用内存相关的参数限制容器的各项内存使用上限，具体参数及取值见下方参数列表。

参数

create/run 时可以指定下列参数。

示例

如果需要限制容器内内存的上限，在运行容器时，直接加上 --memory [] 即可，如：

isula run -tid --memory 1G busybox sh

限制运行时的 IO 资源

描述

可以通过参数限制容器中设备读写速度。

用法

isula create/run 时使用 --device-read-bps/–device-write-bps :[] 来限制容器中设备的读写速度。

参数

create/run时指定 --device-read/write-bps参数。

示例

如果需要限制容器内设备的读写速度，在运行容器时，直接加上 --device-write-bps/--device-read-bps :[] 即可，例如，限制容器 busybox 内设备 /dev/sda 的读速度为 1 MB 每秒，则命令如下：

isula run -tid --device-write /dev/sda:1mb busybox sh

限制写速度的命令如下：

isula run -tid read-bps /dev/sda:1mb busybox sh

限制容器 rootfs 存储空间

描述

在 ext4 上使用 overlay2 时，可以设置单个容器的文件系统限额，比如设置 A 容器的限额为 5 G，B 容器为 10 G。

该特性通过 ext4 文件系统的 project quota 功能来实现，在内核支持的前提下，通过系统调用 SYS_IOCTL 设置某个目录的 project ID，再通过系统调用 SYS_QUOTACTL 设置相应的 project ID 的 hard limit 和 solft limit 值达到限额的目的。

用法

1. 环境准备

   文件系统支持 Project ID 和 Project Quota 属性，4.19 版本内核已经支持，外围包 e2fsprogs 版本不低于 1.43.4-2。

2. 在容器挂载 overlayfs 之前，需要对不同容器的 upper 目录和 work 目录设置不同的 project id，同时设置继承选项，在容器挂载 overlayfs 之后不允许再修改 project id 和继承属性。

3. 配额的设置需要在容器外以特权用户进行。

4. daemon 中增加如下配置

   -s overlay2 --storage-opt overlay2.override_kernel_check=true
   

5. daemon 支持以下选项，用于为容器设置默认的限制，

   --storage-opt overlay2.basesize=128M 指定默认限制的大小，若 isula run 时也指定 了 --storeage-opt size 选项，则以 run 时指定来生效，若 daemon 跟 isula run 时都不指定大小，则表示不限制。

6. 需要开启文件系统 Project ID 和 Project Quota 属性。

   • 新格式化文件系统并 mount

     # mkfs.ext4 -O quota,project /dev/sdb
     # mount -o prjquota /dev/sdb /var/lib/isulad
     

参数

create/run 时指定 --storage-opt 参数。

示例

在 isula run/create 命令行上通过已有参数 “--storage-opt size=” 来设置限额。其中 value 是一个正数，单位可以是 [kKmMgGtTpP]?[iI]?[bB]?，在不带单位的时候默认单位是字节。

$ [root@localhost ~]# isula run -ti --storage-opt size=10M busybox
/ # df -h
Filesystem                Size      Used Available Use% Mounted on
overlay                  10.0M     48.0K     10.0M   0% /
none                     64.0M         0     64.0M   0% /dev
none                     10.0M         0     10.0M   0% /sys/fs/cgroup
tmpfs                    64.0M         0     64.0M   0% /dev
shm                      64.0M         0     64.0M   0% /dev/shm
/dev/mapper/vg--data-ext41
                          9.8G     51.5M      9.2G   1% /etc/hostname
/dev/mapper/vg--data-ext41
                          9.8G     51.5M      9.2G   1% /etc/resolv.conf
/dev/mapper/vg--data-ext41
                          9.8G     51.5M      9.2G   1% /etc/hosts
tmpfs                     3.9G         0      3.9G   0% /proc/acpi
tmpfs                    64.0M         0     64.0M   0% /proc/kcore
tmpfs                    64.0M         0     64.0M   0% /proc/keys
tmpfs                    64.0M         0     64.0M   0% /proc/timer_list
tmpfs                    64.0M         0     64.0M   0% /proc/sched_debug
tmpfs                     3.9G         0      3.9G   0% /proc/scsi
tmpfs                    64.0M         0     64.0M   0% /proc/fdthreshold
tmpfs                    64.0M         0     64.0M   0% /proc/fdenable
tmpfs                     3.9G         0      3.9G   0% /sys/firmware
/ # 
/ # dd if=/dev/zero of=/home/img bs=1M count=12 && sync
dm-4: write failed, project block limit reached.
10+0 records in
9+0 records out
10432512 bytes (9.9MB) copied, 0.011782 seconds, 844.4MB/s
/ # df -h | grep overlay
overlay                  10.0M     10.0M         0 100% /
/ #

约束

1. 限额只针对 rw 层。

   overlay2 的限额是针对容器的 rw 层的，镜像的大小不计算在内。

2. 内核支持并使能。

   内核必须支持 ext4 的 project quota 功能，并在 mkfs 的时候要加上 -O quota,project，挂载的时候要加上 -o prjquota。任何一个不满足，在使用 --storage-opt size= 时都将报错。

   $ [root@localhost ~]# isula run -it --storage-opt size=10Mb busybox df -h
   Error response from daemon: Failed to prepare rootfs with error: time="2019-04-09T05:13:52-04:00" level=fatal msg="error creating read-
   write layer with ID "a4c0e55e82c55e4ee4b0f4ee07f80cc2261cf31b2c2dfd628fa1fb00db97270f": --storage-opt is supported only for overlay over
   xfs or ext4 with 'pquota' mount option"
   

3. 限制额度的说明。

   1. 限制的额度大于 isulad 的 root 所在分区的 size 时，在容器内用 df 看到的文件系统的额度是 isulad 的 root 所在分区的 size，而不是设置的限额。
   2. --storage-opt size=0 代表不限制，且设置值不能小于 4096。size 的精度为 1 个字节，如果指定精度含小数个字节，小数部分被忽略，如指定 size=0.1 实际等同于 size=0 不限制。（受计算机存储浮点数精度的限制，即 0.999999999999999999999999999 与 1 是等价的，具体的 9的个数不同计算机可能存在差异，故设置 4095.999999999999999999999999999 与 4096 等价，其它情况类似），注意 isula inspect 显示原始命令行指定形式，如果含小数字节，需自行忽略小数部分。
   3. 限制的额度过小时，比如 --storage-opt size=4k，可能会导致容器无法启动，因为启动容器本身需要创建一些文件。
   4. 上一次启动 isulad 时，isulad 的 root 所在分区挂载时加了 -o prjquota选项，这次启动时不加，那么上一次启动中创建的带 quota 的容器的设置值不生效。
   5. daemon端配额 --storage-opt overlay2.basesize，其取值范围与 --storage-opt size 相同。

4. 指定 storage-opt 为 4k 时，轻量级容器启动与 docker 有差异

   使用选项 --storage-opt size=4k 和镜像 rnd-dockerhub.huawei.com/official/ubuntu-arm64:latest 运行容器。

   docker 启动失败。

   [root@localhost ~]# docker run -itd --storage-opt size=4k rnd-dockerhub.huawei.com/official/ubuntu-arm64:latest
   docker: Error response from daemon: symlink /proc/mounts /var/lib/docker/overlay2/e6e12701db1a488636c881b44109a807e187b8db51a50015db34a131294fcf70-init/merged/etc/mtab: disk quota exceeded.
   See 'docker run --help'.
   

   轻量级容器不报错，正常启动

   [root@localhost ~]# isula run -itd --storage-opt size=4k rnd-dockerhub.huawei.com/official/ubuntu-arm64:latest
   636480b1fc2cf8ac895f46e77d86439fe2b359a1ff78486ae81c18d089bbd728
   [root@localhost ~]# isula ps
   STATUS  PID   IMAGE                                                 COMMAND   EXIT_CODE RESTART_COUNT STARTAT       FINISHAT RUNTIME ID           NAMES                                                            
   running 17609 rnd-dockerhub.huawei.com/official/ubuntu-arm64:latest /bin/bash 0         0             2 seconds ago -        lcr     636480b1fc2c 636480b1fc2cf8ac895f46e77d86439fe2b359a1ff78486ae81c18d089bbd728
   

   在启动容器的过程中，如果需要在容器的 rootfs 路径下创建文件，若镜像本身占用的大小超过 4k，且此时的 quota 设置为4 k，则创建文件必定失败。

   docker 在启动容器的过程中，会比 isulad 创建更多的挂载点，用于挂载 host 上的某些路径到容器中，如 /proc/mounts，/dev/shm等，如果镜像内本身不存在这些文件，则会创建，根据上述原因该操作会导致文件创建失败，因而容器启动失败。

   轻量级容器在启动容器过程中，使用默认配置时，挂载点较少，如 /proc，或 /sys等路径不存在时，才会创建。用例中的镜像 rnd-dockerhub.huawei.com/official/ubuntu-arm64:latest 本身含有/proc， /sys等，因此整个启动容器的过程中，都不会有新文件或路径生成，故轻量级容器启动过程不会报错。为验证这一过程，当把镜像替换为 rnd-dockerhub.huawei.com/official/busybox-aarch64:lates t时，由于该镜像内无 /proc 存在，轻量级容器启动一样会报错。

   [root@localhost ~]# isula run -itd --storage-opt size=4k rnd-dockerhub.huawei.com/official/busybox-aarch64:latest
   8e893ab483310350b8caa3b29eca7cd3c94eae55b48bfc82b350b30b17a0aaf4
   Error response from daemon: Start container error: runtime error: 8e893ab483310350b8caa3b29eca7cd3c94eae55b48bfc82b350b30b17a0aaf4:tools/lxc_start.c:main:404 starting container process caused "Failed to setup lxc,
   please check the config file."
   

5. 其他说明。

   使用限额功能的 isulad 切换数据盘时，需要保证被切换的数据盘使用prjquota选项挂载，且 /var/lib/isulad/storage/overlay2 目录的挂载方式与/var/lib/isulad 相同。

   说明：

   切换数据盘时需要保证/var/lib/isulad/storage/overlay2的挂载点被卸载。

限制容器内文件句柄数

描述

可以通过参数限制容器中可以打开的文件句柄数。

用法

isula create/run 时使用 --files-limit 来限制容器中可以打开的文件句柄数。

参数

create/run 时指定 --files-limit 参数。

示例

在运行容器时，直接加上 --files-limit n 即可，如：

isula run -ti --files-limit 1024 busybox bash

约束

1. 使用 --files-limit 参数传入一个很小的值，如 1，可能导致容器启动失败。

   [root@localhost ~]# isula run -itd --files-limit 1 rnd-dockerhub.huawei.com/official/busybox-aarch64
   004858d9f9ef429b624f3d20f8ba12acfbc8a15bb121c4036de4e5745932eff4
   Error response from daemon: Start container error: Container is not running:004858d9f9ef429b624f3d20f8ba12acfbc8a15bb121c4036de4e5745932eff4
   

   而 docker 会启动成功，其 files.limit cgroup 值为 max。

   [root@localhost ~]# docker run -itd --files-limit 1 rnd-dockerhub.huawei.com/official/busybox-aarch64
   ef9694bf4d8e803a1c7de5c17f5d829db409e41a530a245edc2e5367708dbbab
   [root@localhost ~]# docker exec -it ef96 cat /sys/fs/cgroup/files/files.limit
   max
   

   根因是 lxc 和 runc 启动过程的原理不一样，lxc 创建 cgroup 子组后先设置 files.limit 值，再将容器进程的 PID 写入该子组的 cgroup.procs 文件，此时该进程已经打开超过 1 个句柄，因而写入报错导致启动失败。runc 创建 cgroup 子组后先将容器进程的 PID 写入该子组的 cgroup.procs 文件，再设置 files.limit 值，此时由于该子组内的进程已经打开超过 1 个句柄，因而写入 files.limit 不会生效，内核也不会报错，容器启动成功。

限制容器内可以创建的进程/线程数

描述

可以通过参数限制容器中能够创建的进程/线程数。

用法

在容器 create/run 时，使用参数 --pids-limit 来限制容器中可以创建的进程/线程数。

参数

create/run时指定 --pids-limit 参数。

示例

在运行容器时，直接加上--pids-limit n 即可，如：

isula run -ti --pids-limit 1024 busybox bash

约束

由于创建容器的过程中会临时创建一些进程，所以此值不能设置的太小，不然容器可能起不来，建议大于 10。

配置容器内的 ulimit 值

描述

可以通过参数控制执行程序的资源。

用法

在容器 create/run 时配置--ulimit参数，或通过 daemon 端配置，控制容器中执行程序的资源。

参数

通过两种方法配置 ulimit

1. isula create/run 时使用--ulimit =[:]来控制shell执行程序的资源。

1. 通过 daemon 端参数或配置文件

详见”(命令行参数说明”与”部署方式”的 --default-ulimits 相关选项。

--ulimit可以对以下类型的资源进行限制。

示例

在容器的创建或者运行时，加上 --ulimit =[:]即可，如：

isula create/run -tid --ulimit nofile=1024:2048 busybox sh

约束

不能在 daemon.json 和 /etc/sysconfig/iSulad 文件（或 isulad 命令行）中同时配置 ulimit 限制，否则 isulad 启动会报错。

特权容器

场景说明

iSulad 默认启动的是普通容器，普通容器适合启动普通进程，其权限非常受限，仅具备 /etc/default/isulad/config.json 中 capabilities 所定义的默认权限。当需要特权操作时（比如操作 /sys 下的设备），需要特权容器完成这些操作，使用该特性，容器内的 root 将拥有宿主机的 root 权限， 否则，容器内的 root 在只是宿主机的普通用户权限。

使用限制

特权容器为容器提供了所有功能，还解除了设备 cgroup 控制器强制执行的所有限制，具备以下特性：

• Secomp 不 block 任何系统调用
• /sys、/proc 路径可写
• 容器内能访问主机上所有设备
• 系统的权能将全部打开

普通容器默认权能为：

当容器为特权模式时，将添加以下权能

使用指导

iSulad 使用 --privileged 给容器添加特权模式，在非必要情况下，不要给容器添加特权，遵循最小特权原则，减少存在的安全风险。

isula run --rm -it --privileged busybox

CRI 接口

描述

CRI API 接口是由 kubernetes 推出的容器运行时接口，CRI 定义了容器和镜像的服务接口。ISulad 使用 CRI 接口，实现和 kubernetes 的对接。

因为容器运行时与镜像的生命周期是彼此隔离的，因此需要定义两个服务。该接口使用Protocol Buffer定义，基于gRPC。

当前实现 CRI 版本为 v1alpha1 版本，官方 API 描述文件如下：

https://github.com/kubernetes/kubernetes/blob/release-1.14/pkg/kubelet/apis/cri/runtime/v1alpha2/api.proto，

ISulad 使用的为 pass 使用的 1.14 版本 API 描述文件，与官方 API 略有出入，以本文档描述的接口为准。

说明：

CRI 接口 websocket 流式服务，服务端监听地址为 127.0.0.1，端口为 10350，端口可通过命令行 --websocket-server-listening-port 参数接口或者 daemon.json 配置文件进行配置。

接口

各接口中可能用到的参数清单如下，部分参数暂不支持配置，已在配置中标出。

接口参数列表

• DNSConfig

  配置 sandbox 的 DNS 服务器和搜索域

• Protocol

  协议的 enum 值列表

• PortMapping

  指定 sandbox 的端口映射配置

• MountPropagation

  挂载传播属性的 enum 列表

• Mount

  Mount 指定 host 上的一个挂载卷挂载到容器中（只支持文件和文件夹)

• NamespaceOption

  NamespaceOption 参数成员如下

• Capability

  包含待添加与待删除的权能信息

• Int64Value

  int64 类型的封装

• UInt64Value

  uint64 类型的封装

• LinuxSandboxSecurityContext

  配置 sandbox 的 linux 安全选项。

  注意，这些安全选项不会应用到 sandbox 中的容器中，也可能不适用于没有任何 running 进程的 sandbox

• LinuxPodSandboxConfig

  设定和 Linux 主机及容器相关的一些配置

• PodSandboxMetadata

  Sandbox 元数据包含构建 sandbox 名称的所有信息，鼓励容器运行时在用户界面中公开这些元数据以获得更好的用户体验，例如，运行时可以根据元数据生成 sandbox 的唯一命名。

• PodSandboxConfig

  包含创建 sandbox 的所有必选和可选配置信息

• PodSandboxNetworkStatus

  描述 sandbox 的网络状态

• Namespace

  命名空间选项

• LinuxPodSandboxStatus

  描述 Linux sandbox 的状态

• PodSandboxState

  sandbox 状态值的 enum 数据

• PodSandboxStatus

  描述 Podsandbox 的状态信息

• PodSandboxStateValue

  对 PodSandboxState 的封装

• PodSandboxFilter

  用于列出 sandbox 时添加过滤条件，多个条件取交集显示

• PodSandbox

  包含最小化描述一个 sandbox 的数据

• KeyValue

  键值对的封装

• SELinuxOption

  应用于容器的 SELinux 标签

• ContainerMetadata

  Container 元数据包含构建 container 名称的所有信息，鼓励容器运行时在用户界面中公开这些元数据以获得更好的用户体验，例如，运行时可以根据元数据生成 container 的唯一命名。

• ContainerState

  容器状态值的 enum 列表

• ContainerStateValue

  封装 ContainerState 的数据结构

• ContainerFilter

  用于列出 container 时添加过滤条件，多个条件取交集显示

• LinuxContainerSecurityContext

  指定应用于容器的安全配置

• LinuxContainerResources

  指定 Linux 容器资源的特定配置

• Image

  Image 信息描述一个镜像的基本数据。

• ImageSpec

  表示镜像的内部数据结构，当前，ImageSpec 只封装容器镜像名称

• StorageIdentifier

  唯一定义storage的标识

• FilesystemUsage

• AuthConfig

• Container

  用于描述容器信息，例如 ID, 状态等。

• ContainerStatus

  用于描述容器状态信息

• ContainerStatsFilter

  用于列出 container stats 时添加过滤条件，多个条件取交集显示

• ContainerStats

  用于列出 container stats 时添加过滤条件，多个条件取交集显示

• ContainerAttributes

  列出 container 的基本信息

• CpuUsage

  列出 container 的 CPU 使用信息

• MemoryUsage

  列出 container 的内存使用信息

• FilesystemUsage

  列出container的读写层信息

• Device

  指定待挂载至容器的主机卷

• LinuxContainerConfig

  包含特定于 Linux 平台的配置

• ContainerConfig

  包含用于创建容器的所有必需和可选字段

• NetworkConfig

  Runtime 的网络配置

• RuntimeConfig

  Runtime 的网络配置

• RuntimeCondition

  描述 runtime 的状态信息

• RuntimeStatus

  Runtime 的状态

• Runtime服务
• Image服务

Runtime服务

Runtime 服务中包含操作 pod 和容器的接口，以及查询 runtime 自身配置和状态信息的接口。

RunPodSandbox

接口原型

rpc RunPodSandbox(RunPodSandboxRequest) returns (RunPodSandboxResponse) {}

接口描述

创建和启动一个 pod sandbox，若运行成功，sandbox 处于 ready 状态。

注意事项

1. 启动 sandbox 的默认镜像为 rnd-dockerhub.huawei.com/library/pause-${machine}:3.0， 其中 ${machine} 为架构，在 x86_64 上，machine 的值为 amd64，在 arm64 上，machine 的值为 aarch64，当前 rnd-dockerhub 仓库上只有 amd64 和 aarch64 镜像可供下载，若机器上无此镜像，请确保机器能从 rnd-dockerhub 下载，若要使用其它镜像，请参考 iSulad部署配置 中的pod-sandbox-image指定镜像。
2. 由于容器命名以 PodSandboxMetadata 中的字段为来源，且以下划线 ”_“ 为分割字符，因此限制 metadata 中的数据不能包含下划线，否则会出现 sandbox 运行成功，但无法使用 ListPodSandbox 接口查询的现象。

参数：RunPodSandboxRequest

返回值：RunPodSandboxResponse

StopPodSandbox

接口原型

rpc StopPodSandbox(StopPodSandboxRequest) returns (StopPodSandboxResponse) {}

接口描述

停止 pod sandbox，停止 sandbox 容器，回收分配给 sandbox 的网络资源（比如 IP 地址）。如果有任何 running 的容器属于该 sandbox，则必须被强制停止。

注意事项

参数: StopPodSandboxRequest

返回值: StopPodSandboxResponse

RemovePodSandbox

接口原型

rpc RemovePodSandbox(RemovePodSandboxRequest) returns (RemovePodSandboxResponse) {}

接口描述

删除 sandbox，如果有任何 running 的容器属于该 sandbox，则必须被强制停止和删除，如果 sandbox 已经被删除，不能返回错误。

注意事项

1. 删除 sandbox 时，不会删除 sandbox 的网络资源，在删除 pod 前必须先调用 StopPodSandbox 才能清理网络资源，调用者应当保证在删除 sandbox 之前至少调用一次 StopPodSandbox。

参数: RemovePodSandboxRequest

返回值: RemovePodSandboxResponse

PodSandboxStatus

接口原型

rpc PodSandboxStatus(PodSandboxStatusRequest) returns (PodSandboxStatusResponse) {}

接口描述

查询 sandbox 的状态，如果 sandbox 不存在，返回错误。

注意事项

参数: PodSandboxStatusRequest

返回值: PodSandboxStatusResponse

ListPodSandbox

接口原型

rpc ListPodSandbox(ListPodSandboxRequest) returns (ListPodSandboxResponse) {}

接口描述

返回 sandbox 信息的列表，支持条件过滤。

注意事项

参数: ListPodSandboxRequest

返回值: ListPodSandboxResponse

CreateContainer

grpc::Status CreateContainer(grpc::ServerContext *context, const runtime::CreateContainerRequest *request, runtime::CreateContainerResponse *reply) {}

接口描述

在 PodSandbox 内创建一个容器

注意事项

1. 请求 CreateContainerRequest 中的 sandbox_config 与传递给 RunPodSandboxRequest 以创建 PodSandbox 的配置相同。 它再次传递，只是为了方便参考。 PodSandboxConfig 是不可变的，在 pod 的整个生命周期内保持不变。
2. 由于容器命名以ContainerMetadata中的字段为来源，且以下划线 ”_“ 为分割字符，因此限制metadata中的数据不能包含下划线，否则会出现sandbox运行成功，但无法使用ListContainers接口查询的现象。

参数： CreateContainerRequest

补充 ：annotations

可用于存储和检索任意元数据的非结构化键值映射。有一些字段由于 cri 接口没有提供特定的参数，可通过该字段将参数传入

• 自定义

返回值 ：CreateContainerResponse

StartContainer

接口原型

rpc StartContainer(StartContainerRequest) returns (StartContainerResponse) {}

接口描述

启动一个容器。

注意事项

参数： StartContainerRequest

返回值： StartContainerResponse

StopContainer

接口原型

rpc StopContainer(StopContainerRequest) returns (StopContainerResponse) {}

接口描述

停止一个 running 的容器，支持配置优雅停止时间 timeout，如果容器已经停止，不能返回错误。

注意事项

参数： StopContainerRequest

返回值: StopContainerResponse

RemoveContainer

接口原型

rpc RemoveContainer(RemoveContainerRequest) returns (RemoveContainerResponse) {}

接口描述

删除一个容器，如果容器正在运行，必须强制停止，如果容器已经被删除，不能返回错误。

注意事项

参数: RemoveContainerRequest

返回值: RemoveContainerResponse

ListContainers

接口原型

rpc ListContainers(ListContainersRequest) returns (ListContainersResponse) {}

接口描述

返回 container 信息的列表，支持条件过滤。

注意事项

参数： ListContainersRequest

返回值： ListContainersResponse

ContainerStatus

接口原型

rpc ContainerStatus(ContainerStatusRequest) returns (ContainerStatusResponse) {}

接口描述

返回容器状态信息，如果容器不存在，则返回错误。

注意事项

参数: ContainerStatusRequest

返回值: ContainerStatusResponse

UpdateContainerResources

接口原型

rpc UpdateContainerResources(UpdateContainerResourcesRequest) returns (UpdateContainerResourcesResponse) {}

接口描述

该接口用于更新容器资源配置。

注意事项

1. 该接口仅用于更新容器的资源配置，不能用于更新Pod的资源配置。
2. 当前不支持更新容器 oom_score_adj 配置

参数: UpdateContainerResourcesRequest

返回值: UpdateContainerResourcesResponse

ExecSync

接口原型

rpc ExecSync(ExecSyncRequest) returns (ExecSyncResponse) {}

接口描述

以同步的方式在容器中执行命令，采用的 gRPC 通讯方式。

注意事项

执行执行一条单独的命令，不能打开终端与容器交互。

参数：ExecSyncRequest

返回值: ExecSyncResponse

Exec

接口原型

rpc Exec(ExecRequest) returns (ExecResponse) {}

接口描述

在容器中执行命令，采用的 gRPC 通讯方式从 CRI 服务端获取 url，再通过获得的 url 与 websocket 服务端建立长连接，实现与容器的交互。

注意事项

执行执行一条单独的命令，也能打开终端与容器交互。 stdin/stdout/stderr 之一必须是真的。如果 tty 为真，stderr 必须是假的。 不支持多路复用, 在这种情况下, stdout 和 stderr 的输出将合并为单流。

参数: ExecRequest

返回值: ExecResponse

Attach

接口原型

rpc Attach(AttachRequest) returns (AttachResponse) {}

接口描述

接管容器的1号进程，采用的 gRPC 通讯方式从 CRI 服务端获取 url，再通过获得的 url 与 websocket 服务端建立长连接，实现与容器的交互。

参数: AttachRequest

返回值: ExecResponse

PortForward

暂不支持

ContainerStats

接口原型

rpc ContainerStats(ContainerStatsRequest) returns (ContainerStatsResponse) {}

接口描述

返回单个容器占用资源信息

参数： ContainerStatsRequest

返回值： ContainerStatsResponse

ListContainerStats

接口原型

rpc ListContainerStats(ListContainerStatsRequest) returns (ListContainerStatsResponse) {}

接口描述

返回多个容器占用资源信息，支持条件过滤

参数： ListContainerStatsRequest

返回值： ListContainerStatsResponse

UpdateRuntimeConfig

接口原型

rpc UpdateRuntimeConfig(UpdateRuntimeConfigRequest) returns (UpdateRuntimeConfigResponse);

接口描述

提供标准的 CRI 接口，目的为了更新网络插件的 Pod CIDR，当前 CNI 网络插件无需更新 Pod CIDR，因此该接口只会记录访问日志。

注意事项

接口操作不会对系统管理信息修改，只是记录一条日志。

参数： UpdateRuntimeConfigRequest

返回值： UpdateRuntimeConfigResponse

Status

接口原型

rpc Status(StatusRequest) returns (StatusResponse) {};

接口描述

获取runtime和pod的网络状态，在获取网络状态时，会触发网络配置的刷新。

注意事项

如果网络配置刷新失败，不会影响原有配置；只有刷新成功时，才会覆盖原有配置。

参数： StatusRequest

返回值： StatusResponse

Image服务

提供了从镜像仓库拉取、查看、和移除镜像的 gRPC API。

ListImages

接口原型

rpc ListImages(ListImagesRequest) returns (ListImagesResponse) {}

接口描述

列出当前已存在的镜像信息。

注意事项

为统一接口，对于 embedded 格式镜像，可以通过 cri images 查询到。但是因 embedded 镜像不是标准 OCI 镜像，因此查询得到的结果有以下限制：

1. 因 embedded 镜像无镜像 ID，显示的镜像 ID 为镜像的 config digest。
2. 因 embedded 镜像本身无 digest 仅有 config 的 digest，且格式不符合 OCI 镜像规范，因此无法显示 digest。

参数

返回值

ImageStatus

接口原型

rpc ImageStatus(ImageStatusRequest) returns (ImageStatusResponse) {}

接口描述

查询指定镜像信息。

注意事项

1. 查询指定镜像信息，若镜像不存在，则返回 ImageStatusResponse，其中 Image 设置为 nil。
2. 为统一接口，对于 embedded 格式镜像，因不符合 OCI 格式镜像，缺少字段，无法通过本接口进行查询。

参数

返回值

PullImage

接口原型

 rpc PullImage(PullImageRequest) returns (PullImageResponse) {}

接口描述

下载镜像。

注意事项

当前支持下载 public 镜像，使用用户名、密码、auth 信息下载私有镜像，不支持 authconfig 中的 server_address、identity_token、registry_token 字段。

参数

返回值

RemoveImage

接口原型

rpc RemoveImage(RemoveImageRequest) returns (RemoveImageResponse) {}

接口描述

删除指定镜像。

注意事项

为统一接口，对于 embedded 格式镜像，因不符合 OCI 格式镜像，缺少字段，无法通过本接口使用 image id 进行删除。

参数

返回值

ImageFsInfo

接口原型

rpc ImageFsInfo(ImageFsInfoRequest) returns (ImageFsInfoResponse) {}

接口描述

查询存储镜像的文件系统信息。

注意事项

查询到的为镜像元数据下的文件系统信息。

参数

返回值

约束

1. 如果创建 sandbox 时，PodSandboxConfig 参数中配置了 log_directory，则所有属于该 sandbox 的 container 在创建时必须在 ContainerConfig 中指定 log_path，否则可能导致容器无法使用 CRI 接口启动，甚至无法使用 CRI 接口删除。

   容器的真实 LOGPATH=log_directory/log_path ，如果 log_path 不配置，那么最终的 LOGPATH 会变为 LOGPATH=log_directory。

   • 如果该路径不存在，isulad 在启动容器时会创建一个软链接，指向最终的容器日志真实路径，此时 log_directory 变成一个软链接，此时有两种情况：
     1. 第一种情况，如果该 sandbox 里其它容器也没配置 log_path，在启动其它容器时， log_directory 会被删除，然后重新指向新启动容器的 log_path，导致之前启动的容器日志指向后面启动容器的日志。
     2. 第二种情况，如果该 sandbox 里其它容器配置了 log_path，则该容器的LOGPATH=log_directory/log_path，由于 log_directory 实际是个软链接，使用 log_directory/log_path 为软链接指向容器真实日志路径时，创建会失败。
   • 如果该路径存在，isulad 在启动容器时首先会尝试删除该路径（非递归），如果该路径是个文件夹，且里面有内容，删除会失败，从而导致创建软链接失败，容器启动失败，删除该容器时，也会出现同样的现象，导致删除失败。

2. 如果创建 sandbox 时，PodSandboxConfig 参数中配置了 log_directory，且 container 创建时在 ContainerConfig 中指定 log_path，那么最终的 LOGPATH=log_directory/log_path，isulad 不会递归的创建 LOGPATH，因而用户必须保证 dirname(LOGPATH) 存在，即最终的日志文件的上一级路径存在。

3. 如果创建 sandbox 时，PodSandboxConfig 参数中配置了 log_directory，如果有两个或多个container 创建时在 ContainerConfig 中指定了同一个 log_path，或者不同的 sandbox 内的容器最终指向的 LOGPATH 是同一路径，若容器启动成功，则后启动的容器日志路径会覆盖掉之前启动的容器日志路径。

4. 如果远程镜像仓库中镜像内容发生变化，调用 CRI Pull image 接口重新下载该镜像时，若本地原来存储有原镜像，则原镜像的镜像名称、TAG 会变更为 “none”

   举例如下：

   本地已存储镜像：

   IMAGE                                        TAG                 IMAGE ID            SIZE
   rnd-dockerhub.huawei.com/pproxyisulad/test   latest              99e59f495ffaa       753kB
   

   远程仓库中 rnd-dockerhub.huawei.com/pproxyisulad/test:latest 镜像更新后，重新下载后：

   IMAGE                                        TAG                 IMAGE ID            SIZE
   <none>                                       <none>              99e59f495ffaa       753kB
   rnd-dockerhub.huawei.com/pproxyisulad/test   latest              d8233ab899d41       1.42MB
   

   使用 isula images 命令行查询，REF 显示为”-“：

   REF                                               IMAGE ID               CREATED              SIZE       
   rnd-dockerhub.huawei.com/pproxyisulad/test:latest d8233ab899d41          2019-02-14 19:19:37  1.42MB     
   -                                                 99e59f495ffaa          2016-05-04 02:26:41  753kB
   

镜像管理

docker镜像管理

登录到镜像仓库

描述

isula login 命令用于登录到镜像仓库。登录成功后可以使用 isula pull 命令从该镜像仓库拉取镜像。如果镜像仓库不需要密码，则拉取镜像前不需要执行该命令。

用法

isula login [OPTIONS] SERVER

参数

login 命令支持参数请参见 “附录 > 命令行参数说明” 章节的 “表1 表1-20 login 命令参数列表” 。

示例

$ isula login -u abc my.csp-edge.com:5000

Login Succeeded

从镜像仓库退出登录

描述

isula logout 命令用于从镜像仓库退出登录。退出登录成功后再执行 isula pull 命令从该镜像仓库拉取镜像会因为未认证而拉取失败。

用法

isula logout SERVER

参数

logout 命令支持参数请参见”附录 > 命令行参数说明” 章节的 “表2 logout 命令参数列表”。

示例

$ isula logout my.csp-edge.com:5000
Logout Succeeded

从镜像仓库拉取镜像

描述

从镜像仓库拉取镜像到本地。

用法

isula pull [OPTIONS] NAME[:TAG|@DIGEST]

参数

login 命令支持参数请参见”附录 > 命令行参数说明” 章节的 “表3 pull 命令参数列表”。

示例

$ isula pull localhost:5000/official/busybox
Image "localhost:5000/official/busybox" pulling
Image "localhost:5000/official/busybox@sha256:bf510723d2cd2d4e3f5ce7e93bf1e52c8fd76831995ac3bd3f90ecc866643aff" pulled

删除镜像

描述

删除一个或多个镜像。

用法

isula rmi [OPTIONS] IMAGE [IMAGE...]

参数

rmi 命令支持参数请参见”附录 > 命令行参数说明” 章节的 “表4 rmi 命令参数列表”。

示例

$ isula rmi rnd-dockerhub.huawei.com/official/busybox
Image "rnd-dockerhub.huawei.com/official/busybox" removed

加载镜像

描述

从一个 tar 包加载镜像。该 tar 包必须是使用 docker save 命令导出的 tar 包或格式一致的 tar 包。

用法

isula load [OPTIONS]

参数

load 命令支持参数请参见”附录 > 命令行参数说明” 章节的 “表5 load 命令参数列表”。

示例

$ isula load -i busybox.tar
Load image from "/root/busybox.tar" success

列出镜像

描述

列出当前环境中所有镜像。

用法

isula images

参数

images 命令支持参数请参见”附录 > 命令行参数说明” 章节的 “表6 images 命令参数列表”。

示例

$ isula images
REF                                              IMAGE ID             CREATED              SIZE
rnd-dockerhub.huawei.com/official/busybox:latest e4db68de4ff2         2019-06-15 08:19:54  1.376 MB

检视镜像

描述

返回该镜像的配置信息。可以使用-f参数过滤出需要的信息。

用法

isula inspect [options] CONTAINER|IMAGE [CONTAINER|IMAGE...]

参数

inspect 命令支持参数请参见 ”附录 > 命令行参数说明” 章节的 “表7 inspect 命令参数列表”。

示例

$ isula inspect -f "" rnd-dockerhub.huawei.com/official/busybox
"e4db68de4ff27c2adfea0c54bbb73a61a42f5b667c326de4d7d5b19ab71c6a3b"

双向认证

描述

开启该功能后 isulad 和镜像仓库之间的通信采用 https 通信，isulad 和镜像仓库都会验证对方的合法性。

用法

要支持该功能，需要镜像仓库支持该功能，同时 isulad 也需要做相应的配置：

1. 修改 isulad 的配置（默认路径 /etc/isulad/daemon.json），将配置里的 use-decrypted-key 项配置为 false。
2. 需要将相关的证书放置到 /etc/isulad/certs.d 目录下对应的镜像仓库命名的文件夹下，证书具体的生成方法见 docker 的官方链接：
   • https://docs.docker.com/engine/security/certificates/
   • https://docs.docker.com/engine/security/https/
3. 执行 systemctl restart isulad 重启 isulad。

参数

可以在 /etc/isulad/daemon.json 中配置参数，也可以在启动 isulad 时携带参数：

isulad --use-decrypted-key=false

示例

配置 use-decrypted-key 参数为 false

$ cat /etc/isulad/daemon.json
{
    "group": "isulad",
    "graph": "/var/lib/isulad",
    "state": "/var/run/isulad",
    "engine": "lcr",
    "log-level": "ERROR",
    "pidfile": "/var/run/isulad.pid",
    "log-opts": {
        "log-file-mode": "0600",
        "log-path": "/var/lib/isulad",
        "max-file": "1",
        "max-size": "30KB"
    },
    "log-driver": "stdout",
    "hook-spec": "/etc/default/isulad/hooks/default.json",
    "start-timeout": "2m",
    "storage-driver": "overlay2",
    "storage-opts": [
        "overlay2.override_kernel_check=true"
    ],
    "registry-mirrors": [
        "docker.io"
    ],
    "insecure-registries": [
        "rnd-dockerhub.huawei.com"
    ],
    "pod-sandbox-image": "",
    "image-opt-timeout": "5m",
    "native.umask": "secure",
    "network-plugin": "",
    "cni-bin-dir": "",
    "cni-conf-dir": "",
    "image-layer-check": false,
    "use-decrypted-key": false,
    "insecure-skip-verify-enforce": false
}

将证书放到对应的目录下

$ pwd
/etc/isulad/certs.d/my.csp-edge.com:5000
$ ls
ca.crt  tls.cert  tls.key

重启 isulad

$ systemctl restart isulad

执行 pull 命令从仓库下载镜像

$ isula pull my.csp-edge.com:5000/ubuntu
Image "my.csp-edge.com:5000/ubuntu" pulling
Image "my.csp-edge.com:5000/ubuntu@sha256:f1bdc62115dbfe8f54e52e19795ee34b4473babdeb9bc4f83045d85c7b2ad5c0" pulled

embedded镜像管理

加载镜像

描述

根据 embedded 镜像的 manifest 加载镜像。注意 --type 的值必须填写 embedded。

用法

isula load [OPTIONS] --input=FILE --type=TYPE

参数

load 命令支持参数请参见”附录 > 命令行参数说明” 章节的 “表5 load 命令参数列表”。

示例

$ isula load -i test.manifest --type embedded
Load image from "/root/work/bugfix/tmp/ci_testcase_data/embedded/img/test.manifest" success

列出镜像

描述

列出当前环境中所有镜像。

用法

isula images [OPTIONS]

参数

images 命令支持参数请参见”附录 > 命令行参数说明” 章节的 “表6 images 命令参数列表”。

示例

$ isula images
REF                            IMAGE ID             CREATED              SIZE
test:v1                        9319da1f5233         2018-03-01 10:55:44  1.273 MB

检视镜像

描述

返回该镜像的配置信息。可以使用-f参数过滤出需要的信息。

用法

isula inspect [options] CONTAINER|IMAGE [CONTAINER|IMAGE...]

参数

inspect命令支持参数请参见”附录 > 命令行参数说明” 章节的 “表7 inspect命令参数列表”。

示例

$ isula inspect -f "" test:v1
"2018-03-01T15:55:44.322987811Z"

删除镜像

描述

删除一个或多个镜像。

用法

isula rmi [OPTIONS] IMAGE [IMAGE...]

参数

rmi 命令支持参数请参见”附录 > 命令行参数说明” 章节的 “表4 rmi 命令参数列表”。

示例

$ isula rmi test:v1
Image "test:v1" removed

容器健康状态检查

场景说明

在实际的生产环境中，开发者提供的应用程序或者平台提供的服务难免存在 bug，因此，一套管理系统对运行的应用程序进行周期性的健康检查和修复就是不可或缺的。容器健康检查机制便添加了用户定义的对容器进行健康检查的功能。在容器创建时配置 --health-cmd 选项，在容器内部周期性地执行命令，通过命令的返回值来监测容器的健康状态。

配置方法

在容器启动时的配置：

isula run -itd --health-cmd "echo iSulad >> /tmp/health_check_file || exit 1" --health-interval 5m --health-timeout 3s --health-exit-on-unhealthy  centos bash

可配置的选项：

• --health-cmd，必选，在容器内执行的命令。返回值为 0 表示成功，非 0 表示失败。
• --health-interval，默认 30s，最大为 int64 上限（纳秒），自定义配置最小值 1s，相邻两次命令执行的间隔时间（注：入参 0s 时视为 default）。
• --health-timeout，默认 30s，最大为 int64 上限（纳秒），自定义配置最小值1s，单次检查命令执行的时间上限，超时则任务命令执行失败（注：入参 0s 时视为 default）
• --health-start-period，默认 0s，最大为 int64 上限（纳秒），自定义配置最小值 1s，容器初始化时间。
• --health-retries，默认 3，最大为 int32 上限，健康检查失败最大的重试次数。
• --health-exit-on-unhealthy，默认 false，检测到容器非健康时是否杀死容器。

检查规则

1. 容器启动后，容器状态中显示 health:starting。

2. 经过 start-period 时间后开始，以 interval 为间隔周期性在容器中执行 CMD。即：当一次命令执行完毕后，经过 interval 时间，执行下一次命令。

3. 若 CMD 命令在 timeout 限制的时间内执行完毕，并且返回值为 0，则视为一次检查成功。否则视为一次检查失败。检查成功后，容器状态变为 health:healthy。

4. 若 CMD 命令连续 retries 次检查失败，则容器状态变为 health:unhealthy。失败后容器也会继续进行健康检查。

5. 容器状态为 health:unhealthy 时，任意一次检查成功会使得容器状态变为 health:healthy。

6. 设置--exit-on-unhealthy的情况下，如果容器因为非被杀死退出（退出返回值 137）后，健康检查只有容器在重新启动后才会继续生效。

7. CMD 执行完毕或超时时，docker daemon 会将这次检查的起始时间、返回值和标准输出记录到容器的配置文件中。最多记录 5 条。此外，容器的配置文件中还存储着健康检查的相关参数。

8. 运行中的容器的健康检查状态也会被写入容器配置中。通过 isula inspect 可以看到。

   "Health": {
   "Status": "healthy",
   "FailingStreak": 0,
   "Log": [
       {
           "Start": "2018-03-07T07:44:15.481414707-05:00",
           "End": "2018-03-07T07:44:15.556908311-05:00",
           "ExitCode": 0,
           "Output": ""
       },
       {
           "Start": "2018-03-07T07:44:18.557297462-05:00",
           "End": "2018-03-07T07:44:18.63035891-05:00",
           "ExitCode": 0,
           "Output": ""
       },
       ......
   }
   

使用限制

• 容器内健康检查的状态信息最多保存 5 条。会保存最后得到的 5 条记录。
• 容器启动时若健康检查相关参数配置为 0，则按照默认值处理。
• 带有健康检查配置的容器启动后，若 iSulad daemon 退出，则健康检查不会执行。iSulad daemon 再次启动后，正在运行且带有健康检查配置的容器其健康状态会变为 starting。之后检查规则同上。
• 如果健康检查从第一次开始便一直失败，其状态保持与之前一致（starting），直到达到指定失败次数（--health-retries）后变为 unhealthy，或者检查成功后变为 healthy。

查询信息

查询服务版本信息

描述

isula version 命令用于查询 iSulad 服务的版本信息。

用法

isula version

实例

查询版本信息

isula version

如果 isulad 服务正常运行，则可以查看到客户端、服务端以及 OCI config 的版本等信息。

Client:
  Version:      1.0.31
  Git commit:   fa7f9902738e8b3d7f2eb22768b9a1372ddd1199
  Built:        2019-07-30T04:21:48.521198248-04:00

Server:
  Version:      1.0.31
  Git commit:   fa7f9902738e8b3d7f2eb22768b9a1372ddd1199
  Built:        2019-07-30T04:21:48.521198248-04:00

OCI config:
  Version:      1.0.0-rc5-dev
  Default file: /etc/default/isulad/config.json

若 isulad 服务未运行，则仅仅查询到客户端的信息，并提示无法连接到服务端。

Client:
  Version:      1.0.31
  Git commit:   fa7f9902738e8b3d7f2eb22768b9a1372ddd1199
  Built:        2019-07-30T04:21:48.521198248-04:00

Can not connect with server.Is the iSulad daemon running on the host?

因此，isula version 命令也常常用来检验 isulad 是否正常运行。

查询系统级信息

描述

isula info 命令用于对系统级信息，以及容器和镜像数目等信息的查询。

用法

isula info

示例

查询系统级信息，可以展示容器数目，镜像数目，内核版本、操作系统等信息

$ isula info
Containers: 2
 Running: 0
 Paused: 0
 Stopped: 2
Images: 8
Server Version: 1.0.31
Logging Driver: json-file
Cgroup Driverr: cgroupfs
Hugetlb Pagesize: 2MB
Kernel Version: 4.19
Operating System: Fedora 29 (Twenty Nine)
OSType: Linux
Architecture: x86_64
CPUs: 8
Total Memory: 7 GB
Name: localhost.localdomain
iSulad Root Dir: /var/lib/isulad

安全特性

seccomp安全配置场景

场景说明

seccomp（secure computing mode）是 linux kernel 从 2.6.23 版本开始引入的一种简洁的 sandboxing 机制。在一些特定场景下，用户需要在容器中执行一些“特权”操作，但又不想启动特权容器，用户经常会在 run 时添加 --cap-add 来获得一些“小范围”的权限。对于安全要求比较严格的容器实例，上述的 CAP 粒度不一定能够满足安全需要，可使用一些办法精细化控制权限范围。

• 举例

  普通容器场景中，用户使用 -v 将宿主机某目录（包含某普通用户无法执行的二进制），映射到容器中。

  在容器中，可以将二进制修改权限 chmod 4777 加入 S 标志位。这样在宿主机上，原先不能运行二进制的普通用户（或者运行此二进制受限），可以在 S 标志位的添加动作后，在运行此二进制的时候，获取到二进制自身的权限（比如 root），从而提权运行或者访问其他文件。

  这个场景，如果在严格安全要求下，需要使用 seccomp 裁剪 chmod、fchmod、fchmodat 系统调用。

使用限制

• seccomp 可能会影响性能，设置 seccomp 之前需要对场景进行评估，确定必要时加入 seccomp 配置。

使用指导

通过 --security-opt 将配置文件传给要过滤系统调用的容器。

isula run -itd --security-opt seccomp=/path/to/seccomp/profile.json rnd-dockerhub.huawei.com/official/busybox

说明：

1. 创建容器时通过 --security-opt 将配置文件传给容器时，采用默认配置文件（/etc/isulad/seccomp_default.json）。
2. 创建容器时 --security-opt 设置为 unconfined 时，对容器不过滤系统调用。
3. “/path/to/seccomp/profile.json” 需要是绝对路径。

获取普通容器的默认 seccomp 配置

• 启动一个普通容器（或者是带 --cap-add 的容器），并查看默认权限配置：

  cat /etc/isulad/seccomp_default.json | python -m json.tool > profile.json
  

  可以看到 ”seccomp” 字段中，有很多的 ”syscalls”，在此基础上，仅提取 syscalls 的部分，参考定制 seccomp 配置文件，进行定制化操作。

  "defaultAction": "SCMP_ACT_ERRNO",
  "syscalls": [
  {
  "action": "SCMP_ACT_ALLOW",
  "name": "accept"
  },
  {
  "action": "SCMP_ACT_ALLOW",
  "name": "accept4"
  },
  {
  "action": "SCMP_ACT_ALLOW",
  "name": "access"
  },
  {
  "action": "SCMP_ACT_ALLOW",
  "name": "alarm"
  },
  {
  "action": "SCMP_ACT_ALLOW",
  "name": "bind"
  },
  ]...
  

• 查看转换为 lxc 可识别的 seccomp 配置

  cat /var/lib/isulad/engines/lcr/74353e38021c29314188e29ba8c1830a4677ffe5c4decda77a1e0853ec8197cd/seccomp
  

  ...
  waitpid allow
  write allow
  writev allow
  ptrace allow
  personality allow [0,0,SCMP_CMP_EQ,0]
  personality allow [0,8,SCMP_CMP_EQ,0]
  personality allow [0,131072,SCMP_CMP_EQ,0]
  personality allow [0,131080,SCMP_CMP_EQ,0]
  personality allow [0,4294967295,SCMP_CMP_EQ,0]
  ...
  

定制seccomp配置文件

在启动容器的时候使用 --security-opt 引入 seccomp 配置文件，容器实例会按照配置文件规则进行限制系统 API 的运行。首先获取普通容器的默认 seccomp，得到完整模板，然后按照本节定制配置文件，启动容器：

isula run --rm -it --security-opt seccomp:/path/to/seccomp/profile.json rnd-dockerhub.huawei.com/official/busybox

配置文件模板：

{
"defaultAction": "SCMP_ACT_ALLOW",
"syscalls": [
{
"name": "syscall-name",
"action": "SCMP_ACT_ERRNO",
"args": null
}
]
}

须知：

- defaultAction、syscalls：对应的 action 的类型是一样的，但其值是不能一样的，目的就是让所有的 syscal 都有一个默认的 action，并且如果 syscalls 数组中有明确的定义，就以 syscalls 中的为准，由于 defaultAction、action 的值不一样，就能保证 action 不会有冲突。当前支持的 action 有： “SCMP_ACT_ERRNO”：禁止，并打印错误信息。 “SCMP_ACT_ALLOW”：允许。

- syscalls： 数组，可以只有一个 syscall，也可以有多个，可以带 args，也可以不带。

- name：要过滤的 syscall。

- args：数组，里面的每个 object的定义如下：

type Arg struct {  
Index    uint     `json:"index"`     //参数的序号，如open(fd, buf, len),fd 对应的就是0，buf为1  
Value    uint64   `json:"value"`     //跟参数进行比较的值  
ValueTwo uint64   `json:"value_two"` //仅当Op=MaskEqualTo时起作用，用户传入值跟Value按位与操作后，跟ValueTwo进行比较，若相等则执行action。  
Op       Operator `json:"op"`  
}

args中的Op，其取值可以下页面的任意一种： “SCMP_CMP_NE”: NotEqualTo “SCMP_CMP_LT”: LessThan “SCMP_CMP_LE”: LessThanOrEqualTo “SCMP_CMP_EQ”: EqualTo “SCMP_CMP_GE”: GreaterThanOrEqualTo “SCMP_CMP_GT”: GreaterThan “SCMP_CMP_MASKED_EQ”: MaskEqualTo

capabilities安全配置场景

场景说明

capabilities 机制是 linux kernel 2.2 之后引入的安全特性，用更小的粒度控制超级管理员权限,可以避免使用 root 权限，将 root 用户的权限细分为不同的领域，可以分别启用或禁用。capabilities 详细信息可通过 Linux Programmer’s Manual 进行查看（capabilities(7) - Linux man page）：

man capabilities

使用限制

• isulad 默认 Capabilities（白名单）配置如下，普通容器进程将默认携带：

  "CAP_CHOWN",
  "CAP_DAC_OVERRIDE",
  "CAP_FSETID",
  "CAP_FOWNER",
  "CAP_MKNOD",
  "CAP_NET_RAW",
  "CAP_SETGID",
  "CAP_SETUID",
  "CAP_SETFCAP",
  "CAP_SETPCAP",
  "CAP_NET_BIND_SERVICE",
  "CAP_SYS_CHROOT",
  "CAP_KILL",
  "CAP_AUDIT_WRITE"
  

• 默认的权能配置，包含了 CAP_SETUID 和 CAP_FSETID，如 host 和容器共享目录，容器可对共享目录的二进制文件进行文件权限设置，host 上的普通用户可能使用该特性进行提权攻击。CAP_AUDIT_WRITE，容器可以对 host 写入，存在一定的风险，如果使用场景不需要，推荐在启动容器的时候使用 --cap-drop将其删除。

• 增加 Capabilities 意味着容器进程具备更大的能力，同时也会开放更多的系统调用接口。

使用指导

iSulad 使用 --cap-add/--cap-drop 给容器增加/删去特定的权限，在非必要情况下，不要给容器增加额外的权限，推荐将容器默认但非必要的权限也去掉。

isula run --rm -it --cap-add all --cap-drop SYS_ADMIN rnd-dockerhub.huawei.com/official/busybox

支持OCI hooks

描述

支持在容器的生命周期中，运行 OCI 标准 hooks。包括三种类型的 hooks：

• prestart hook：在执行 isula start 命令之后，而在容器的 1 号进程启动之前，被执行。
• poststart hook：在容器 1 号进程启动之后，而在 isula start 命令返回之前，被执行。
• poststop hook：在容器被停止之后，但是在停止命令返回之前，被执行。

OCI hooks 的配置格式规范如下：

• path：格式是字符串，必须项，必须为绝对路径，指定的文件必须有可执行权限。
• args：格式是字符串数组，可选项，语义和 execv 的 args 一致。
• env：格式是字符串数组，可选项，语义和环境变量一致，内容为键值对，如：”PATH=/usr/bin”。
• timeout：格式是整数，可选项，必须大于 0，表示钩子执行的超时时间。如果钩子进程运行时间超过配置的时间，那么钩子进程会被杀死。

hook 的配置为 json 格式，一般存放在 json 结尾的文件中，示例如下：

{
        "prestart": [
            {
                "path": "/usr/bin/echo",
                "args": ["arg1", "arg2"],
                "env":  [ "key1=value1"],
                "timeout": 30
            },
            {
                "path": "/usr/bin/ls",
                "args": ["/tmp"]
            }
        ],
        "poststart": [
            {
                "path": "/usr/bin/ls",
                "args": ["/tmp"],
                "timeout": 5
            }
        ],
        "poststop": [
            {
                "path": "/tmp/cleanup.sh",
                "args": ["cleanup.sh", "-f"]
            }
        ]
}

接口

isulad 和 isula 都提供了 hook 的接口，isulad 提供了默认的 hook 配置，会作用于所有容器；而 isula 提供的 hook 接口，只会作用于当前创建的容器。

isulad 提供的默认 OCI hooks 配置：

• 通过 /etc/isulad/daemon.json 配置文件的 hook-spec 配置项设置 hook 配置的文件路径：”hook-spec”: “/etc/default/isulad/hooks/default.json”。
• 通过 isulad –hook-spec 参数设置 hook 配置的文件路径。

isula 提供的 OCI hooks 配置：

• isula create --hook-spec：指定 hook 配置的 json 文件的路径。
• isula run --hook-spec：指定 hook 配置的 json 文件的路径。

run 的配置其实也是在 create 阶段生效了。

使用限制

• hook-spec 指定的路径必须是绝对路径。

• hook-spec 指定的文件必须存在。

• hook-spec 指定的路径对应的必须是普通文本文件，格式为 json。

• hook-spec 指定的文件大小不能超过 10MB。

• hooks 配置的 path 字段必须为绝对路径。

• hooks 配置的 path 字段指定文件必须存在。

• hooks 配置的 path 字段指定文件必须有可执行权限。

• hooks 配置的 path 字段指定文件的 owner 必须是 root。

• hooks 配置的 path 字段指定文件必须只有 root 有写权限。

• hooks 配置的 timeout 必须大于 0。