长期支持版本

    社区创新版本

      CRI V1alpha2 接口

      描述

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

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

      当前iSulad使用默认CRI版本为v1alpha2版本,官方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备份