长期支持版本

    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服务器和搜索域

      参数成员

      描述

      repeated string servers

      集群的DNS服务器列表

      repeated string searches

      集群的DNS搜索域列表

      repeated string options

      DNS可选项列表,参考https://linux.die.net/man/5/resolv.conf

    • Protocol

      协议的enum值列表

      参数成员

      描述

      TCP = 0

      TCP协议

      UDP = 1

      UDP协议

    • PortMapping

      指定sandbox的端口映射配置

      参数成员

      描述

      Protocol protocol

      端口映射使用的协议

      int32 container_port

      容器内的端口号

      int32 host_port

      主机上的端口号

      string host_ip

      主机IP地址

    • MountPropagation

      挂载传播属性的enum列表

      参数成员

      描述

      PROPAGATION_PRIVATE = 0

      无挂载传播属性,即linux中的private

      PROPAGATION_HOST_TO_CONTAINER = 1

      挂载属性能从host传播到容器中,即linux中的rslave

      PROPAGATION_BIDIRECTIONAL = 2

      挂载属性能在host和容器中双向传播,即linux中的rshared

    • Mount

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

      参数成员

      描述

      string container_path

      容器中的路径

      string host_path

      主机上的路径

      bool readonly

      是否配置在容器中是只读的, 默认值: false

      bool selinux_relabel

      是否设置SELinux标签(不支持配置)

      MountPropagation propagation

      挂载传播属性配置(取值0/1/2,分别对应private/rslave/rshared传播属性) 默认值:0

    • NamespaceOption

      参数成员

      描述

      bool host_network

      是否使用host的网络命名空间

      bool host_pid

      是否使用host的PID命名空间

      bool host_ipc

      是否使用host的IPC命名空间

    • Capability

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

      参数成员

      描述

      repeated string add_capabilities

      待新增的权能

      repeated string drop_capabilities

      待删除的权能

    • Int64Value

      int64类型的封装

      参数成员

      描述

      int64 value

      实际的int64值

    • UInt64Value

      uint64类型的封装

      参数成员

      描述

      uint64 value

      实际的uint64值

    • LinuxSandboxSecurityContext

      配置sandbox的linux安全选项。

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

      参数成员

      描述

      NamespaceOption namespace_options

      配置sandbox的命名空间选项

      SELinuxOption selinux_options

      配置SELinux选项(不支持)

      Int64Value run_as_user

      配置sandbox中进程的uid

      bool readonly_rootfs

      配置sandbox的根文件系统是否只读

      repeated int64 supplemental_groups

      配置除主GID之外的sandbox的1号进程用户组信息

      bool privileged

      配置sandbox是否为特权容器

      string seccomp_profile_path

      seccomp配置文件路径,有效值为:

      // unconfined: 不配置seccomp

      // localhost/<配置文件的全路径>: 安装在系统上的配置文件路径

      // <配置文件的全路径>: 配置文件全路径

      // 默认不配置,即unconfined。

    • LinuxPodSandboxConfig

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

      参数成员

      描述

      string cgroup_parent

      sandbox的cgroup父路径,runtime可根据实际情况使用cgroupfs或systemd的语法。(不支持配置)

      LinuxSandboxSecurityContext security_context

      sandbox的安全属性

      map<string, string> sysctls

      sandbox的linux sysctls配置

    • PodSandboxMetadata

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

      参数成员

      描述

      string name

      sandbox的名称

      string uid

      sandbox的UID

      string namespace

      sandbox的命名空间

      uint32 attempt

      尝试创建sandbox的次数,默认为0

    • PodSandboxConfig

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

      参数成员

      描述

      PodSandboxMetadata metadata

      sandbox的元数据,这项信息唯一标识一个sandbox,runtime必须利用此信息确保操作正确,runtime也可以根据此信息来改善用户体验,例如构建可读的sandbox名称。

      string hostname

      sandbox的hostname

      string log_directory

      配置sandbox内的容器的日志文件所存储的文件夹

      DNSConfig dns_config

      sandbox的DNS配置

      repeated PortMapping port_mappings

      sandbox的端口映射

      map<string, string> labels

      可用于标识单个或一系列sandbox的键值对

      map<string, string> annotations

      存储任意信息的键值对,这些值是不可更改的,且能够利用PodSandboxStatus接口查询

      LinuxPodSandboxConfig linux

      与linux主机相关的可选项

    • PodSandboxNetworkStatus

      描述sandbox的网络状态

      参数成员

      描述

      string ip

      sandbox的ip地址

      string name

      sandbox内的网络接口名

      string network

      附加网络的名称

    • Namespace

      命名空间选项

      参数成员

      描述

      NamespaceOption options

      Linux 命名空间选项

    • LinuxPodSandboxStatus

      描述Linux sandbox的状态

      参数成员

      描述

      Namespace namespaces

      sandbox命名空间

    • PodSandboxState

      sandbox状态值的enum数据

      参数成员

      描述

      SANDBOX_READY = 0

      sandbox处于ready状态

      SANDBOX_NOTREADY = 1

      sandbox处于非ready状态

    • PodSandboxStatus

      描述Podsandbox的状态信息

      参数成员

      描述

      string id

      sandbox的ID

      PodSandboxMetadata metadata

      sandbox的元数据

      PodSandboxState state

      sandbox的状态值

      int64 created_at

      sandbox的创建时间戳,单位纳秒

      repeated PodSandboxNetworkStatus networks

      sandbox的多平面网络状态

      LinuxPodSandboxStatus linux

      Linux规范的sandbox状态

      map<string, string> labels

      可用于标识单个或一系列sandbox的键值对

      map<string, string> annotations

      存储任意信息的键值对,这些值是不可被runtime更改的

    • PodSandboxStateValue

      对PodSandboxState的封装

      参数成员

      描述

      PodSandboxState state

      sandbox的状态值

    • PodSandboxFilter

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

      参数成员

      描述

      string id

      sandbox的ID

      PodSandboxStateValue state

      sandbox的状态

      map<string, string> label_selector

      sandbox的labels,label只支持完全匹配,不支持正则匹配

    • PodSandbox

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

      参数成员

      描述

      string id

      sandbox的ID

      PodSandboxMetadata metadata

      sandbox的元数据

      PodSandboxState state

      sandbox的状态值

      int64 created_at

      sandbox的创建时间戳,单位纳秒

      map<string, string> labels

      可用于标识单个或一系列sandbox的键值对

      map<string, string> annotations

      存储任意信息的键值对,这些值是不可被runtime更改的

    • KeyValue

      键值对的封装

      参数成员

      描述

      string key

      string value

    • SELinuxOption

      应用于容器的SELinux标签

      参数成员

      描述

      string user

      用户

      string role

      角色

      string type

      类型

      string level

      级别

    • ContainerMetadata

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

      参数成员

      描述

      string name

      container的名称

      uint32 attempt

      尝试创建container的次数,默认为0

    • ContainerState

      容器状态值的enum列表

      参数成员

      描述

      CONTAINER_CREATED = 0

      container创建完成

      CONTAINER_RUNNING = 1

      container处于运行状态

      CONTAINER_EXITED = 2

      container处于退出状态

      CONTAINER_UNKNOWN = 3

      未知的容器状态

    • ContainerStateValue

      封装ContainerState的数据结构

      参数成员

      描述

      ContainerState state

      容器状态值

    • ContainerFilter

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

      参数成员

      描述

      string id

      container的ID

      PodSandboxStateValue state

      container的状态

      string pod_sandbox_id

      sandbox的ID

      map<string, string> label_selector

      container的labels,label只支持完全匹配,不支持正则匹配

    • LinuxContainerSecurityContext

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

      参数成员

      描述

      Capability capabilities

      新增或去除的权能

      bool privileged

      指定容器是否未特权模式, 默认值:false

      NamespaceOption namespace_options

      指定容器的namespace选项

      SELinuxOption selinux_options

      SELinux context(可选配置项) 暂不支持

      Int64Value run_as_user

      运行容器进程的UID。 一次只能指定run_as_user与run_as_username其中之一,run_as_username优先生效

      string run_as_username

      运行容器进程的用户名。 如果指定,用户必须存在于容器映像中(即在映像内的/etc/passwd中),并由运行时在那里解析; 否则,运行时必须出错

      bool readonly_rootfs

      设置容器中根文件系统是否为只读 默认值由config.json配置

      repeated int64 supplemental_groups

      容器运行的除主GID外首进程组的列表

      string apparmor_profile

      容器的AppArmor配置文件 暂不支持

      string seccomp_profile_path

      容器的seccomp配置文件路径

      bool no_new_privs

      是否在容器上设置no_new_privs的标志

    • LinuxContainerResources

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

      参数成员

      描述

      int64 cpu_period

      CPU CFS(完全公平调度程序)周期。 默认值:0

      int64 cpu_quota

      CPU CFS(完全公平调度程序)配额。 默认值:0

      int64 cpu_shares

      所占CPU份额(相对于其他容器的相对权重)。 默认值:0

      int64 memory_limit_in_bytes

      内存限制(字节)。 默认值:0

      int64 oom_score_adj

      OOMScoreAdj用于调整oom-killer。 默认值:0

      string cpuset_cpus

      指定容器使用的CPU核心。 默认值:“”

      string cpuset_mems

      指定容器使用的内存节点。 默认值:“”

    • Image

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

      参数成员

      描述

      string id

      镜像ID

      repeated string repo_tags

      镜像tag 名称 repo_tags

      repeated string repo_digests

      镜像digest信息

      uint64 size

      镜像大小

      Int64Value uid

      镜像默认用户UID

      string username

      镜像默认用户名称

    • ImageSpec

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

      参数成员

      描述

      string image

      容器镜像名

    • StorageIdentifier

      唯一定义storage的标识

      参数成员

      描述

      string uuid

      设备的UUID

    • FilesystemUsage

      参数成员

      描述

      int64 timestamp

      收集文件系统信息时的时间戳

      StorageIdentifier storage_id

      存储镜像的文件系统UUID

      UInt64Value used_bytes

      存储镜像元数据的大小

      UInt64Value inodes_used

      存储镜像元数据的inodes个数

    • AuthConfig

      参数成员

      描述

      string username

      下载镜像使用的用户名

      string password

      下载镜像使用的密码

      string auth

      下载镜像时使用的认证信息,base64编码

      string server_address

      下载镜像的服务器地址,暂不支持

      string identity_token

      用于与镜像仓库鉴权的令牌信息,暂不支持

      string registry_token

      用于与镜像仓库交互的令牌信息,暂不支持

    • Container

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

      参数成员

      描述

      string id

      container的ID

      string pod_sandbox_id

      该容器所属的sandbox的ID

      ContainerMetadata metadata

      container的元数据

      ImageSpec image

      镜像规格

      string image_ref

      代表容器使用的镜像,对大多数runtime来产,这是一个image ID值

      ContainerState state

      container的状态

      int64 created_at

      container的创建时间戳,单位为纳秒

      map<string, string> labels

      可用于标识单个或一系列container的键值对

      map<string, string> annotations

      存储任意信息的键值对,这些值是不可被runtime更改的

    • ContainerStatus

      用于描述容器状态信息

      参数成员

      描述

      string id

      container的ID

      ContainerMetadata metadata

      container的元数据

      ContainerState state

      container的状态

      int64 created_at

      container的创建时间戳,单位为纳秒

      int64 started_at

      container启动时的时间戳,单位为纳秒

      int64 finished_at

      container退出时的时间戳,单位为纳秒

      int32 exit_code

      容器退出码

      ImageSpec image

      镜像规格

      string image_ref

      代表容器使用的镜像,对大多数runtime来产,这是一个image ID值

      string reason

      简要描述为什么容器处于当前状态

      string message

      易于人工阅读的信息,用于表述容器处于当前状态的原因

      map<string, string> labels

      可用于标识单个或一系列container的键值对

      map<string, string> annotations

      存储任意信息的键值对,这些值是不可被runtime更改的

      repeated Mount mounts

      容器的挂载点信息

      string log_path

      容器日志文件路径,该文件位于PodSandboxConfig中配置的log_directory文件夹下

    • ContainerStatsFilter

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

      参数成员

      描述

      string id

      container的ID

      string pod_sandbox_id

      sandbox的ID

      map<string, string> label_selector

      container的labels,label只支持完全匹配,不支持正则匹配

    • ContainerStats

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

      参数成员

      描述

      ContainerAttributes attributes

      容器的信息

      CpuUsage cpu

      CPU使用情况

      MemoryUsage memory

      内存使用情况

      FilesystemUsage writable_layer

      可写层使用情况

    • ContainerAttributes

      列出container的基本信息

      参数成员

      描述

      string id

      容器的ID

      ContainerMetadata metadata

      容器的metadata

      map<string,string> labels

      可用于标识单个或一系列container的键值对

      map<string,string> annotations

      存储任意信息的键值对,这些值是不可被runtime更改的

    • CpuUsage

      列出container的CPU使用信息

      参数成员

      描述

      int64 timestamp

      时间戳

      UInt64Value usage_core_nano_seconds

      CPU的使用值,单位/纳秒

    • MemoryUsage

      列出container的内存使用信息

      参数成员

      描述

      int64 timestamp

      时间戳

      UInt64Value working_set_bytes

      内存的使用值

    • FilesystemUsage

      列出container的读写层信息

      参数成员

      描述

      int64 timestamp

      时间戳

      StorageIdentifier storage_id

      可写层目录

      UInt64Value used_bytes

      镜像在可写层的占用字节

      UInt64Value inodes_used

      镜像在可写层的占用inode数

    • Device

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

      参数成员

      描述

      string container_path

      容器内的挂载路径

      string host_path

      主机上的挂载路径

      string permissions

      设备的Cgroup权限(r允许容器从指定的设备读取; w允许容器从指定的设备写入; m允许容器创建尚不存在的设备文件)

    • LinuxContainerConfig

      包含特定于Linux平台的配置

      参数成员

      描述

      LinuxContainerResources resources

      容器的资源规范

      LinuxContainerSecurityContext security_context

      容器的Linux容器安全配置

    • ContainerConfig

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

      参数成员

      描述

      ContainerMetadata metadata

      容器的元数据。 此信息将唯一标识容器,运行时应利用此信息来确保正确操作。 运行时也可以使用此信息来提升UX(用户体检设计),例如通过构造可读名称。(必选)

      ImageSpec image

      容器使用的镜像 (必选)

      repeated string command

      待执行的命令 默认值: "/bin/sh"

      repeated string args

      待执行命令的参数

      string working_dir

      命令执行的当前工作路径

      repeated KeyValue envs

      在容器中配置的环境变量

      repeated Mount mounts

      待在容器中挂载的挂载点信息

      repeated Device devices

      待在容器中映射的设备信息

      map<string, string> labels

      可用于索引和选择单个资源的键值对。

      map<string, string> annotations

      可用于存储和检索任意元数据的非结构化键值映射。

      string log_path

      相对于PodSandboxConfig.LogDirectory的路径,用于存储容器主机上的日志(STDOUT和STDERR)。

      bool stdin

      是否打开容器的stdin

      bool stdin_once

      当某次连接stdin的数据流断开时,是否立即断开其他与stdin连接的数据流(暂不支持

      bool tty

      是否使用伪终端连接容器的stdio

      LinuxContainerConfig linux

      linux系统上容器的特定配置信息

    • NetworkConfig

      Runtime的网络配置

      参数成员

      描述

      string pod_cidr

      Pod IP 地址使用的CIDR

    • RuntimeConfig

      Runtime的网络配置

      参数成员

      描述

      NetworkConfig network_config

      Runtime的网络配置

    • RuntimeCondition

      描述runtime的状态信息

      参数成员

      描述

      string type

      Runtime状态的类型

      bool status

      Runtime状态

      string reason

      简要描述runtime状态变化的原因

      string message

      具备可阅读性的信息表明runtime状态变化的原因

    • RuntimeStatus

      Runtime的状态

      参数成员

      描述

      repeated RuntimeCondition conditions

      描述当前runtime状态的列表

    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接口查询的现象。

    参数

    参数成员

    描述

    PodSandboxConfig config

    sandbox的配置

    string runtime_handler

    指定创建sandbox的runtime运行时,当前支持lcr、kata-runtime运行时类型。

    返回值

    返回值

    描述

    string pod_sandbox_id

    成功,返回response数据

    StopPodSandbox

    接口原型

    rpc StopPodSandbox(StopPodSandboxRequest) returns (StopPodSandboxResponse) {}
    

    接口描述

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

    参数

    参数成员

    描述

    string pod_sandbox_id

    sandbox的id

    返回值

    返回值

    描述

    RemovePodSandbox

    接口原型

    rpc RemovePodSandbox(RemovePodSandboxRequest) returns (RemovePodSandboxResponse) {}
    

    接口描述

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

    注意事项

    1. 删除sandbox时,不会删除sandbox的网络资源,在删除pod前必须先调用StopPodSandbox才能清理网络资源,调用者应当保证在删除sandbox之前至少调用一次StopPodSandbox。
    2. 删除sandbox时,如果sandbox中的容器删除失败,则会出现sanbox被删除但容器还残留的情况,此时需要手动删除残留的容器进行清理。

    参数

    参数成员

    描述

    string pod_sandbox_id

    sandbox的id

    返回值

    返回值

    描述

    PodSandboxStatus

    接口原型

    rpc PodSandboxStatus(PodSandboxStatusRequest) returns (PodSandboxStatusResponse) {}
    

    接口描述

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

    参数

    参数成员

    描述

    string pod_sandbox_id

    sandbox的id

    bool verbose

    标识是否显示sandbox的一些额外信息。(暂不支持配置)

    返回值

    返回值

    描述

    PodSandboxStatus status

    sandbox的状态信息

    map<string, string> info

    sandbox的额外信息,key是任意string,value是json格式的字符串,这些信息可以是任意调试内容。当verbose为true时info不能为空。(暂不支持配置)

    ListPodSandbox

    接口原型

    rpc ListPodSandbox(ListPodSandboxRequest) returns (ListPodSandboxResponse) {}
    

    接口描述

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

    参数

    参数成员

    描述

    PodSandboxFilter filter

    条件过滤参数

    返回值

    返回值

    描述

    repeated PodSandbox items

    sandbox信息的列表

    CreateContainer

    接口原型

    rpc CreateContainer(CreateContainerRequest) returns (CreateContainerResponse) {}
    

    接口描述

    在PodSandbox内创建一个容器。

    注意事项

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

    参数

    参数成员

    描述

    string pod_sandbox_id

    待在其中创建容器的PodSandbox的ID。

    ContainerConfig config

    容器的配置信息

    PodSandboxConfig sandbox_config

    PodSandbox的配置信息

    补充

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

    • 自定义

      自定义 key:value

      描述

      cgroup.pids.max:int64_t

      用于限制容器内的进/线程数(set -1 for unlimited)

    返回值

    返回值

    描述

    string container_id

    创建完成的容器ID

    StartContainer

    接口原型

    rpc StartContainer(StartContainerRequest) returns (StartContainerResponse) {}
    

    接口描述

    启动一个容器。

    参数

    参数成员

    描述

    string container_id

    容器id

    返回值

    返回值

    描述

    StopContainer

    接口原型

    rpc StopContainer(StopContainerRequest) returns (StopContainerResponse) {}
    

    接口描述

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

    参数

    参数成员

    描述

    string container_id

    容器id

    int64 timeout

    强制停止容器前的等待时间,默认值为0,即强制停止容器。

    返回值

    RemoveContainer

    接口原型

    rpc RemoveContainer(RemoveContainerRequest) returns (RemoveContainerResponse) {}
    

    接口描述

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

    参数

    参数成员

    描述

    string container_id

    容器id

    返回值

    ListContainers

    接口原型

    rpc ListContainers(ListContainersRequest) returns (ListContainersResponse) {}
    

    接口描述

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

    参数

    参数成员

    描述

    ContainerFilter filter

    条件过滤参数

    返回值

    返回值

    描述

    repeated Container containers

    容器信息的列表

    ContainerStatus

    接口原型

    rpc ContainerStatus(ContainerStatusRequest) returns (ContainerStatusResponse) {}
    

    接口描述

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

    参数

    参数成员

    描述

    string container_id

    容器id

    bool verbose

    标识是否显示sandbox的一些额外信息。(暂不支持配置)

    返回值

    返回值

    描述

    ContainerStatus status

    容器的状态信息

    map<string, string> info

    sandbox的额外信息,key是任意string,value是json格式的字符串,这些信息可以是任意调试内容。当verbose为true时info不能为空。(暂不支持配置)

    UpdateContainerResources

    接口原型

    rpc UpdateContainerResources(UpdateContainerResourcesRequest) returns (UpdateContainerResourcesResponse) {}
    

    接口描述

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

    注意事项

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

    参数

    参数成员

    描述

    string container_id

    容器id

    LinuxContainerResources linux

    linux资源配置信息

    返回值

    ExecSync

    接口原型

    rpc ExecSync(ExecSyncRequest) returns (ExecSyncResponse) {}
    

    接口描述

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

    注意事项

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

    参数

    参数成员

    描述

    string container_id

    容器ID

    repeated string cmd

    待执行命令

    int64 timeout

    停止命令的超时时间(秒)。 默认值:0(无超时限制)。 暂不支持

    返回值

    返回值

    描述

    bytes stdout

    捕获命令标准输出

    bytes stderr

    捕获命令标准错误输出

    int32 exit_code

    退出代码命令完成。 默认值:0(成功)。

    Exec

    接口原型

    rpc Exec(ExecRequest) returns (ExecResponse) {}
    

    接口描述

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

    注意事项

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

    参数

    参数成员

    描述

    string container_id

    容器ID

    repeated string cmd

    待执行的命令

    bool tty

    是否在TTY中执行命令

    bool stdin

    是否流式标准输入

    bool stdout

    是否流式标准输出

    bool stderr

    是否流式输出标准错误

    返回值

    返回值

    描述

    string url

    exec流服务器的完全限定URL

    Attach

    接口原型

    rpc Attach(AttachRequest) returns (AttachResponse) {}
    

    接口描述

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

    参数

    参数成员

    描述

    string container_id

    容器id

    bool tty

    是否在TTY中执行命令

    bool stdin

    是否流式标准输入

    bool stdout

    是否流式标准输出

    bool stderr

    是否流式标准错误

    返回值

    返回值

    描述

    string url

    attach流服务器的完全限定URL

    ContainerStats

    接口原型

    rpc ContainerStats(ContainerStatsRequest) returns (ContainerStatsResponse) {}
    

    接口描述

    返回单个容器占用资源信息,仅支持runtime类型为lcr的容器。

    参数

    参数成员

    描述

    string container_id

    容器id

    返回值

    返回值

    描述

    ContainerStats stats

    容器信息。注:disk和inodes只支持oci格式镜像起的容器查询

    ListContainerStats

    接口原型

    rpc ListContainerStats(ListContainerStatsRequest) returns (ListContainerStatsResponse) {}
    

    接口描述

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

    参数

    参数成员

    描述

    ContainerStatsFilter filter

    条件过滤参数

    返回值

    返回值

    描述

    repeated ContainerStats stats

    容器信息的列表。注:disk和inodes只支持oci格式镜像启动的容器查询

    UpdateRuntimeConfig

    接口原型

    rpc UpdateRuntimeConfig(UpdateRuntimeConfigRequest) returns (UpdateRuntimeConfigResponse);
    

    接口描述

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

    注意事项

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

    参数

    参数成员

    描述

    RuntimeConfig runtime_config

    包含Runtime要配置的信息

    返回值

    Status

    接口原型

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

    接口描述

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

    注意事项

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

    参数

    参数成员

    描述

    bool verbose

    是否显示关于Runtime额外的信息(暂不支持)

    返回值

    返回值

    描述

    RuntimeStatus status

    Runtime的状态

    map<string, string> info

    Runtime额外的信息,info的key为任意值,value为json格式,可包含任何debug信息;只有Verbose为true是才应该被赋值

    Image服务

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

    ListImages

    接口原型

    rpc ListImages(ListImagesRequest) returns (ListImagesResponse) {}
    

    接口描述

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

    注意事项

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

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

    参数

    参数成员

    描述

    ImageSpec filter

    筛选的镜像名称

    返回值

    返回值

    描述

    repeated Image images

    镜像信息列表

    ImageStatus

    接口原型

    rpc ImageStatus(ImageStatusRequest) returns (ImageStatusResponse) {}
    

    接口描述

    查询指定镜像信息。

    注意事项

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

    参数

    参数成员

    描述

    ImageSpec image

    镜像名称

    bool verbose

    查询额外信息,暂不支持,无额外信息返回

    返回值

    返回值

    描述

    Image image

    镜像信息

    map<string, string> info

    镜像额外信息,暂不支持,无额外信息返回

    PullImage

    接口原型

     rpc PullImage(PullImageRequest) returns (PullImageResponse) {}
    

    接口描述

    下载镜像。

    注意事项

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

    参数

    参数成员

    描述

    ImageSpec image

    要下载的镜像名称

    AuthConfig auth

    下载私有镜像时的验证信息

    PodSandboxConfig sandbox_config

    在Pod上下文中下载镜像(暂不支持)

    返回值

    返回值

    描述

    string image_ref

    返回已下载镜像信息

    RemoveImage

    接口原型

    rpc RemoveImage(RemoveImageRequest) returns (RemoveImageResponse) {}
    

    接口描述

    删除指定镜像。

    注意事项

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

    参数

    参数成员

    描述

    ImageSpec image

    要删除的镜像名称或者ID

    返回值

    ImageFsInfo

    接口原型

    rpc ImageFsInfo(ImageFsInfoRequest) returns (ImageFsInfoResponse) {}
    

    接口描述

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

    注意事项

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

    参数

    返回值

    返回值

    描述

    repeated FilesystemUsage image_filesystems

    镜像存储文件系统信息

    约束

    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
      
    5. iSulad CRI exec/attach接口采用websocket协议实现,需要采用同样协议的客户端与iSulad进行交互;使用exec/attach接口时,请避免进行串口大量数据及文件的传输,仅用于基本命令交互,若用户侧处理不及时将存在数据丢失的风险;同时请勿使用cri exec/attach接口进行二进制数据及文件传输。

    6. iSulad CRI exec/attach流式接口依赖libwebsockets实现,流式接口建议仅用于长连接交互使用,不建议在大并发场景下使用,可能会因为宿主机资源不足导致连接失败,建议并发量不超过100。

    文档捉虫

    “有虫”文档片段

    问题描述

    提交类型 issue

    有点复杂...

    找人问问吧。

    PR

    小问题,全程线上修改...

    一键搞定!

    问题类型
    规范和低错类

    ● 错别字或拼写错误;标点符号使用错误;

    ● 链接错误、空单元格、格式错误;

    ● 英文中包含中文字符;

    ● 界面和描述不一致,但不影响操作;

    ● 表述不通顺,但不影响理解;

    ● 版本号不匹配:如软件包名称、界面版本号;

    易用性

    ● 关键步骤错误或缺失,无法指导用户完成任务;

    ● 缺少必要的前提条件、注意事项等;

    ● 图形、表格、文字等晦涩难懂;

    ● 逻辑不清晰,该分类、分项、分步骤的没有给出;

    正确性

    ● 技术原理、功能、规格等描述和软件不一致,存在错误;

    ● 原理图、架构图等存在错误;

    ● 命令、命令参数等错误;

    ● 代码片段错误;

    ● 命令无法完成对应功能;

    ● 界面错误,无法指导操作;

    风险提示

    ● 对重要数据或系统存在风险的操作,缺少安全提示;

    内容合规

    ● 违反法律法规,涉及政治、领土主权等敏感词;

    ● 内容侵权;

    您对文档的总体满意度

    非常不满意
    非常满意
    提交
    根据您的反馈,会自动生成issue模板。您只需点击按钮,创建issue即可。
    文档捉虫
    编组 3备份