CRI V1alpha2 接口
描述
CRI API 接口是由kubernetes 推出的容器运行时接口,CRI定义了容器和镜像的服务接口。ISulad使用CRI接口,实现和kubernetes 的对接。
因为容器运行时与镜像的生命周期是彼此隔离的,因此需要定义两个服务。该接口使用Protocol Buffer定义,基于gRPC。
当前iSulad使用默认CRI版本为v1alpha2版本,官方API描述文件如下:
ISulad使用的为pass使用的1.14版本API描述文件,与官方API略有出入,以本文档描述的接口为准。
说明: CRI接口websocket流式服务,服务端侦听地址为127.0.0.1,端口为10350,端口可通过命令行--websocket-server-listening-port参数接口或者daemon.json配置文件进行配置。
接口
各接口中可能用到的参数清单如下,部分参数暂不支持配置,已在配置中标出。
接口参数列表
配置sandbox的DNS服务器和搜索域
DNS可选项列表,参考https://linux.die.net/man/5/resolv.conf
协议的enum值列表
指定sandbox的端口映射配置
挂载传播属性的enum列表
Mount指定host上的一个挂载卷挂载到容器中(只支持文件和文件夹)
包含待添加与待删除的权能信息
int64类型的封装
uint64类型的封装
配置sandbox的linux安全选项。
注意,这些安全选项不会应用到sandbox中的容器中,也可能不适用于没有任何running进程的sandbox
设定和Linux主机及容器相关的一些配置
sandbox的cgroup父路径,runtime可根据实际情况使用cgroupfs或systemd的语法。(不支持配置)
Sandbox元数据包含构建sandbox名称的所有信息,鼓励容器运行时在用户界面中公开这些元数据以获得更好的用户体验,例如,运行时可以根据元数据生成sandbox的唯一命名。
包含创建sandbox的所有必选和可选配置信息
sandbox的元数据,这项信息唯一标识一个sandbox,runtime必须利用此信息确保操作正确,runtime也可以根据此信息来改善用户体验,例如构建可读的sandbox名称。
描述sandbox的网络状态
命名空间选项
描述Linux sandbox的状态
sandbox状态值的enum数据
描述Podsandbox的状态信息
对PodSandboxState的封装
PodSandboxFilter
用于列出sandbox时添加过滤条件,多个条件取交集显示
PodSandbox
包含最小化描述一个sandbox的数据
键值对的封装
应用于容器的SELinux标签
Container元数据包含构建container名称的所有信息,鼓励容器运行时在用户界面中公开这些元数据以获得更好的用户体验,例如,运行时可以根据元数据生成container的唯一命名。
容器状态值的enum列表
ContainerStateValue
封装ContainerState的数据结构
ContainerFilter
用于列出container时添加过滤条件,多个条件取交集显示
指定应用于容器的安全配置
运行容器进程的UID。 一次只能指定run_as_user与run_as_username其中之一,run_as_username优先生效
运行容器进程的用户名。 如果指定,用户必须存在于容器映像中(即在映像内的/etc/passwd中),并由运行时在那里解析; 否则,运行时必须出错
指定Linux容器资源的特定配置
Image信息描述一个镜像的基本数据。
ImageSpec
表示镜像的内部数据结构,当前,ImageSpec只封装容器镜像名称
唯一定义storage的标识
FilesystemUsage
AuthConfig
Container
用于描述容器信息,例如ID, 状态等。
ContainerStatus
用于描述容器状态信息
ContainerStatsFilter
用于列出container stats时添加过滤条件,多个条件取交集显示
ContainerStats
用于列出container stats时添加过滤条件,多个条件取交集显示
列出container的基本信息
列出container的CPU使用信息
列出container的内存使用信息
列出container的读写层信息
指定待挂载至容器的主机卷
设备的Cgroup权限,(r允许容器从指定的设备读取; w允许容器从指定的设备写入; m允许容器创建尚不存在的设备文件)
包含特定于Linux平台的配置
ContainerConfig
包含用于创建容器的所有必需和可选字段
容器的元数据。 此信息将唯一标识容器,运行时应利用此信息来确保正确操作。 运行时也可以使用此信息来提升UX(用户体检设计),例如通过构造可读名称。(必选)
相对于PodSandboxConfig.LogDirectory的路径,用于存储容器主机上的日志(STDOUT和STDERR)。
Runtime的网络配置
RuntimeConfig
Runtime的网络配置
RuntimeCondition
描述runtime的状态信息
RuntimeStatus
Runtime的状态
Runtime服务
Runtime服务中包含操作pod和容器的接口,以及查询runtime自身配置和状态信息的接口。
RunPodSandbox
接口原型
rpc RunPodSandbox(RunPodSandboxRequest) returns (RunPodSandboxResponse) {}
接口描述
创建和启动一个pod sandbox,若运行成功,sandbox处于ready状态。
注意事项
- 启动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指定镜像。
- 由于容器命名以PodSandboxMetadata中的字段为来源,且以下划线"_"为分割字符,因此限制metadata中的数据不能包含下划线,否则会出现sandbox运行成功,但无法使用ListPodSandbox接口查询的现象。
参数
返回值
StopPodSandbox
接口原型
rpc StopPodSandbox(StopPodSandboxRequest) returns (StopPodSandboxResponse) {}
接口描述
停止pod sandbox,停止sandbox容器,回收分配给sandbox的网络资源(比如IP地址)。如果有任何running的容器属于该sandbox,则必须被强制停止。
参数
返回值
RemovePodSandbox
接口原型
rpc RemovePodSandbox(RemovePodSandboxRequest) returns (RemovePodSandboxResponse) {}
接口描述
删除sandbox,如果有任何running的容器属于该sandbox,则必须被强制停止和删除,如果sandbox已经被删除,不能返回错误。
注意事项
- 删除sandbox时,不会删除sandbox的网络资源,在删除pod前必须先调用StopPodSandbox才能清理网络资源,调用者应当保证在删除sandbox之前至少调用一次StopPodSandbox。
- 删除sandbox时,如果sandbox中的容器删除失败,则会出现sanbox被删除但容器还残留的情况,此时需要手动删除残留的容器进行清理。
参数
返回值
PodSandboxStatus
接口原型
rpc PodSandboxStatus(PodSandboxStatusRequest) returns (PodSandboxStatusResponse) {}
接口描述
查询sandbox的状态,如果sandbox不存在,返回错误。
参数
返回值
sandbox的额外信息,key是任意string,value是json格式的字符串,这些信息可以是任意调试内容。当verbose为true时info不能为空。(暂不支持配置) |
ListPodSandbox
接口原型
rpc ListPodSandbox(ListPodSandboxRequest) returns (ListPodSandboxResponse) {}
接口描述
返回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相同。
参数
补充
可用于存储和检索任意元数据的非结构化键值映射。有一些字段由于cri接口没有提供特定的参数,可通过该字段将参数传入
返回值
StartContainer
接口原型
rpc StartContainer(StartContainerRequest) returns (StartContainerResponse) {}
接口描述
启动一个容器。
参数
返回值
StopContainer
接口原型
rpc StopContainer(StopContainerRequest) returns (StopContainerResponse) {}
接口描述
停止一个running的容器,支持配置优雅停止时间timeout,如果容器已经停止,不能返回错误。
参数
返回值
无
RemoveContainer
接口原型
rpc RemoveContainer(RemoveContainerRequest) returns (RemoveContainerResponse) {}
接口描述
删除一个容器,如果容器正在运行,必须强制停止,如果容器已经被删除,不能返回错误。
参数
返回值
无
ListContainers
接口原型
rpc ListContainers(ListContainersRequest) returns (ListContainersResponse) {}
接口描述
返回container信息的列表,支持条件过滤。
参数
返回值
ContainerStatus
接口原型
rpc ContainerStatus(ContainerStatusRequest) returns (ContainerStatusResponse) {}
接口描述
返回容器状态信息,如果容器不存在,则返回错误。
参数
返回值
sandbox的额外信息,key是任意string,value是json格式的字符串,这些信息可以是任意调试内容。当verbose为true时info不能为空。(暂不支持配置) |
UpdateContainerResources
接口原型
rpc UpdateContainerResources(UpdateContainerResourcesRequest) returns (UpdateContainerResourcesResponse) {}
接口描述
该接口用于更新容器资源配置。
注意事项
- 该接口仅用于更新容器的资源配置,不能用于更新Pod的资源配置。
- 当前不支持更新容器oom_score_adj配置。
参数
返回值
无
ExecSync
接口原型
rpc ExecSync(ExecSyncRequest) returns (ExecSyncResponse) {}
接口描述
以同步的方式在容器中执行命令,采用的gRPC通讯方式。
注意事项
执行一条单独的命令,不能打开终端与容器交互。
参数
返回值
Exec
接口原型
rpc Exec(ExecRequest) returns (ExecResponse) {}
接口描述
在容器中执行命令,采用的gRPC通讯方式从CRI服务端获取url,再通过获得的url与websocket服务端建立长连接,实现与容器的交互。
注意事项
执行一条单独的命令,也能打开终端与容器交互。stdin/stdout/stderr之一必须是真的。如果tty为真,stderr必须是假的。 不支持多路复用, 在这种情况下, stdout和stderr的输出将合并为单流。
参数
返回值
Attach
接口原型
rpc Attach(AttachRequest) returns (AttachResponse) {}
接口描述
接管容器的1号进程,采用gRPC通讯方式从CRI服务端获取url,再通过获取的url与websocket服务端建立长连接,实现与容器的交互。
参数
返回值
ContainerStats
接口原型
rpc ContainerStats(ContainerStatsRequest) returns (ContainerStatsResponse) {}
接口描述
返回单个容器占用资源信息,仅支持runtime类型为lcr的容器。
参数
返回值
ListContainerStats
接口原型
rpc ListContainerStats(ListContainerStatsRequest) returns (ListContainerStatsResponse) {}
接口描述
返回多个容器占用资源信息,支持条件过滤
参数
返回值
UpdateRuntimeConfig
接口原型
rpc UpdateRuntimeConfig(UpdateRuntimeConfigRequest) returns (UpdateRuntimeConfigResponse);
接口描述
提供标准的CRI接口,目的为了更新网络插件的Pod CIDR,当前CNI网络插件无需更新Pod CIDR,因此该接口只会记录访问日志。
注意事项
接口操作不会对系统管理信息修改,只是记录一条日志。
参数
返回值
无
Status
接口原型
rpc Status(StatusRequest) returns (StatusResponse) {};
接口描述
获取runtime和pod的网络状态,在获取网络状态时,会触发网络配置的刷新。
注意事项
如果网络配置刷新失败,不会影响原有配置;只有刷新成功时,才会覆盖原有配置。
参数
返回值
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。
参数
返回值
ImageStatus
接口原型
rpc ImageStatus(ImageStatusRequest) returns (ImageStatusResponse) {}
接口描述
查询指定镜像信息。
注意事项
- 查询指定镜像信息,若镜像不存在,则返回ImageStatusResponse,其中Image设置为nil。
- 为统一接口,对于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) {}
接口描述
查询存储镜像的文件系统信息。
注意事项
查询到的为镜像元数据下的文件系统信息。
参数
无
返回值
约束
如果创建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变成一个软链接,此时有两种情况:
- 第一种情况,如果该sandbox里其他容器也没配置log_path,在启动其他容器时,log_directory会被删除,然后重新指向新启动容器的log_path,导致之前启动的容器日志指向后面启动容器的日志。
- 第二种情况,如果该sandbox里其他容器配置了log_path,则该容器的LOGPATH=log_directory/log_path,由于log_directory实际是个软链接,使用log_directory/log_path为软链接指向容器真实日志路径时,创建会失败。
如果该路径存在,isulad在启动容器时首先会尝试删除该路径(非递归),如果该路径是个文件夹,且里面有内容,删除会失败,从而导致创建软链接失败,容器启动失败,删除该容器时,也会出现同样的现象,导致删除失败。
如果创建sandbox时,PodSandboxConfig参数中配置了log_directory,且container创建时在ContainerConfig中指定log_path,那么最终的LOGPATH=log_directory/log_path,isulad不会递归的创建LOGPATH,因而用户必须保证dirname(LOGPATH)存在,即最终的日志文件的上一级路径存在。
如果创建sandbox时,PodSandboxConfig参数中配置了log_directory,如果有两个或多个container创建时在ContainerConfig中指定了同一个log_path,或者不同的sandbox内的容器最终指向的LOGPATH是同一路径,若容器启动成功,则后启动的容器日志路径会覆盖掉之前启动的容器日志路径。
如果远程镜像仓库中镜像内容发生变化,调用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
iSulad CRI exec/attach接口采用websocket协议实现,需要采用同样协议的客户端与iSulad进行交互;使用exec/attach接口时,请避免进行串口大量数据及文件的传输,仅用于基本命令交互,若用户侧处理不及时将存在数据丢失的风险;同时请勿使用cri exec/attach接口进行二进制数据及文件传输。
iSulad CRI exec/attach流式接口依赖libwebsockets实现,流式接口建议仅用于长连接交互使用,不建议在大并发场景下使用,可能会因为宿主机资源不足导致连接失败,建议并发量不超过100。