CRI
Description
The Container Runtime Interface (CRI) provided by Kubernetes defines container and image service APIs. iSulad uses the CRI to interconnect with Kubernetes.
Since the container runtime is isolated from the image lifecycle, two services need to be defined. This API is defined by using Protocol Buffer based on gRPC.
The current CRI version is v1alpha1. For official API description, access the following link:
iSulad uses the API description file of version 1.14 used by Pass, which is slightly different from the official API description file. API description in this document prevails.
NOTE:
The listening IP address of the CRI WebSocket streaming service is 127.0.0.1 and the port number is 10350. The port number can be configured in the --websocket-server-listening-port command or in the daemon.json configuration file.
APIs
The following tables list the parameters that may be used in each API. Some parameters do not take effect now, which have been noted in the corresponding parameter description.
API Parameters
DNSConfig
This API is used to configure DNS servers and search domains of a sandbox.
DNS option list. For details, see https://linux.die.net/man/5/resolv.conf.
Protocol
This API is used to specify enum values of protocols.
PortMapping
This API is used to configure the port mapping for a sandbox.
Protocol protocol
MountPropagation
This API is used to specify enums of mount propagation attributes.
Mount attribute that can be propagated from the host to the container, that is, rslave in Linux.
Mount attribute that can be propagated between a host and a container, that is, rshared in Linux.
Mount
This API is used to mount a volume on the host to a container. (Only files and folders are supported.)
Whether to set the SELinux label. This parameter does not take effect now.
MountPropagation propagation
The value can be 0, 1, or 2, corresponding to the private, rslave, and rshared propagation attributes respectively.
NamespaceOption
Capability
This API is used to specify the capabilities to be added and deleted.
Int64Value
This API is used to encapsulate data of the signed 64-bit integer type.
UInt64Value
This API is used to encapsulate data of the unsigned 64-bit integer type.
LinuxSandboxSecurityContext
This API is used to configure the Linux security options of a sandbox.
Note that these security options are not applied to containers in the sandbox, and may not be applied to the sandbox without any running process.
NamespaceOption namespace_options
SELinuxOption selinux_options
Int64Value run_as_user
Information of the user group of the init process in the sandbox (except the primary GID).
Path of the seccomp configuration file. Valid values are as follows:
// unconfined: Seccomp is not configured.
// localhost/ Full path of the configuration file: configuration file path installed in the system.
// Full path of the configuration file: full path of the configuration file.
LinuxPodSandboxConfig
This API is used to configure information related to the Linux host and containers.
Parent path of the cgroup of the sandbox. The runtime can use the cgroupfs or systemd syntax based on site requirements. This parameter does not take effect now.
LinuxSandboxSecurityContext security_context
PodSandboxMetadata
Sandbox metadata contains all information that constructs a sandbox name. It is recommended that the metadata be displayed on the user interface during container running to improve user experience. For example, a unique sandbox name can be generated based on the metadata during running.
PodSandboxConfig
This API is used to specify all mandatory and optional configurations for creating a sandbox.
PodSandboxMetadata metadata
Sandbox metadata, which uniquely identifies a sandbox. The runtime must use the information to ensure that operations are correctly performed, and to improve user experience, for example, construct a readable sandbox name.
DNSConfig dns_config
repeated PortMapping port_mappings
Key-value pair that can be used to identify a sandbox or a series of sandboxes.
Key-value pair that stores any information, whose values cannot be changed and can be queried by using the PodSandboxStatus API.
LinuxPodSandboxConfig linux
PodSandboxNetworkStatus
This API is used to describe the network status of a sandbox.
Namespace
This API is used to set namespace options.
NamespaceOption options
LinuxPodSandboxStatus
This API is used to describe the status of a Linux sandbox.
Namespace namespaces
PodSandboxState
This API is used to specify enum data of the sandbox status values.
PodSandboxStatus
This API is used to describe the PodSandbox status.
PodSandboxMetadata metadata
PodSandboxState state
repeated PodSandboxNetworkStatus networks
LinuxPodSandboxStatus linux
Key-value pair that can be used to identify a sandbox or a series of sandboxes.
Key-value pair that stores any information, whose values cannot be changed by the runtime.
PodSandboxStateValue
This API is used to encapsulate PodSandboxState.
PodSandboxState state
PodSandboxFilter
This API is used to add filter criteria for the sandbox list. The intersection of multiple filter criteria is displayed.
PodSandboxStateValue state
Sandbox label, which does not support regular expressions and must be fully matched.
PodSandbox
This API is used to provide a minimum description of a sandbox.
PodSandboxMetadata metadata
PodSandboxState state
Key-value pair that can be used to identify a sandbox or a series of sandboxes.
Key-value pair that stores any information, whose values cannot be changed by the runtime.
KeyValue
This API is used to encapsulate key-value pairs.
SELinuxOption
This API is used to specify the SELinux label of a container.
ContainerMetadata
Container metadata contains all information that constructs a container name. It is recommended that the metadata be displayed on the user interface during container running to improve user experience. For example, a unique container name can be generated based on the metadata during running.
ContainerState
This API is used to specify enums of container status values.
ContainerStateValue
This API is used to encapsulate the data structure of ContainerState.
ContainerState state
ContainerFilter
This API is used to add filter criteria for the container list. The intersection of multiple filter criteria is displayed.
PodSandboxStateValue state
Container label, which does not support regular expressions and must be fully matched.
LinuxContainerSecurityContext
This API is used to specify container security configurations.
Capability capabilities
Whether the container is in privileged mode. Default value: false
NamespaceOption namespace_options
SELinuxOption selinux_options
SELinux context, which is optional. This parameter does not take effect now.
Int64Value run_as_user
UID for running container processes. Only run_as_user or run_as_username can be specified at a time. run_as_username takes effect preferentially.
Username for running container processes. If specified, the user must exist in /etc/passwd in the container image and be parsed by the runtime. Otherwise, an error must occur during running.
Whether the root file system in a container is read-only. The default value is configured in config.json.
List of user groups of the init process running in the container (except the primary GID).
AppArmor configuration file of the container. This parameter does not take effect now.
LinuxContainerResources
This API is used to specify configurations of Linux container resources.
OOMScoreAdj that is used to adjust the OOM killer. Default value: 0
Image
This API is used to describe the basic information about an image.
Int64Value uid
ImageSpec
This API is used to represent the internal data structure of an image. Currently, ImageSpec encapsulates only the container image name.
StorageIdentifier
This API is used to specify the unique identifier for defining the storage.
FilesystemUsage
StorageIdentifier storage_id
UInt64Value used_bytes
UInt64Value inodes_used
AuthConfig
Container
This API is used to describe container information, such as the ID and status.
ContainerMetadata metadata
ImageSpec image
Image used by the container. This parameter is an image ID for most runtime.
ContainerState state
Key-value pair that can be used to identify a container or a series of containers.
Key-value pair that stores any information, whose values cannot be changed by the runtime.
ContainerStatus
This API is used to describe the container status information.
ContainerMetadata metadata
ContainerState state
ImageSpec image
Image used by the container. This parameter is an image ID for most runtime.
Brief description of the reason why the container is in the current status.
Information that is easy to read and indicates the reason why the container is in the current status.
Key-value pair that can be used to identify a container or a series of containers.
Key-value pair that stores any information, whose values cannot be changed by the runtime.
repeated Mount mounts
Path of the container log file that is in the log_directory folder configured in PodSandboxConfig.
ContainerStatsFilter
This API is used to add filter criteria for the container stats list. The intersection of multiple filter criteria is displayed.
Container label, which does not support regular expressions and must be fully matched.
ContainerStats
This API is used to add filter criteria for the container stats list. The intersection of multiple filter criteria is displayed.
ContainerAttributes attributes
CpuUsage cpu
MemoryUsage memory
FilesystemUsage writable_layer
ContainerAttributes
This API is used to list basic container information.
ContainerMetadata metadata
Key-value pair that can be used to identify a container or a series of containers.
Key-value pair that stores any information, whose values cannot be changed by the runtime.
CpuUsage
This API is used to list the CPU usage information of a container.
MemoryUsage
This API is used to list the memory usage information of a container.
FilesystemUsage
This API is used to list the read/write layer information of a container.
Device
This API is used to specify the host volume to be mounted to a container.
LinuxContainerConfig
This API is used to specify Linux configurations.
LinuxContainerResources resources
LinuxContainerSecurityContext security_context
ContainerConfig
This API is used to specify all mandatory and optional fields for creating a container.
ContainerMetadata metadata
Container metadata. The information will uniquely identify a container and should be used at runtime to ensure correct operations. The information can also be used at runtime to optimize the user experience (UX) design, for example, construct a readable name. This parameter is mandatory.
ImageSpec image
repeated KeyValue envs
repeated Mount mounts
Information about the mount point to be mounted in the container.
repeated Device devices
Key-value pair that can be used to index and select a resource.
Unstructured key-value mappings that can be used to store and retrieve any metadata.
Relative path to PodSandboxConfig.LogDirectory, which is used to store logs (STDOUT and STDERR) on the container host.
Whether to immediately disconnect other data flows connected with stdin when a data flow connected with stdin is disconnected. This parameter does not take effect now.
Whether to use a pseudo terminal to connect to stdio of the container.
LinuxContainerConfig linux
NetworkConfig
This API is used to specify runtime network configurations.
RuntimeConfig
This API is used to specify runtime network configurations.
NetworkConfig network_config
RuntimeCondition
This API is used to describe runtime status information.
Brief description of the reason for the runtime status change.
Message with high readability, which indicates the reason for the runtime status change.
RuntimeStatus
This API is used to describe runtime status.
Runtime Service
The runtime service provides APIs for operating pods and containers, and APIs for querying the configuration and status information of the runtime service.
RunPodSandbox
Prototype
rpc RunPodSandbox(RunPodSandboxRequest) returns (RunPodSandboxResponse) {}
Description
This API is used to create and start a PodSandbox. If the PodSandbox is successfully run, the sandbox is in the ready state.
Precautions
- The default image for starting a sandbox is rnd-dockerhub.huawei.com/library/pause-${machine}:3.0 where ${machine} indicates the architecture. On x86_64, the value of machine is amd64. On ARM64, the value of machine is aarch64. Currently, only the amd64 or aarch64 image can be downloaded from the rnd-dockerhub registry. If the image does not exist on the host, ensure that the host can download the image from the rnd-dockerhub registry. If you want to use another image, refer to pod-sandbox-image in the iSulad Deployment Configuration.
- The container name is obtained from fields in PodSandboxMetadata and separated by underscores (_). Therefore, the metadata cannot contain underscores (_). Otherwise, the ListPodSandbox API cannot be used for query even when the sandbox is running successfully.
Parameters
PodSandboxConfig config | |
Runtime for the created sandbox. Currently, lcr and kata-runtime are supported. |
Return Values
StopPodSandbox
Prototype
rpc StopPodSandbox(StopPodSandboxRequest) returns (StopPodSandboxResponse) {}
Description
This API is used to stop PodSandboxes and sandbox containers, and reclaim the network resources (such as IP addresses) allocated to a sandbox. If any running container belongs to the sandbox, the container must be forcibly stopped.
Parameters
Return Values
RemovePodSandbox
Prototype
rpc RemovePodSandbox(RemovePodSandboxRequest) returns (RemovePodSandboxResponse) {}
Description
This API is used to delete a sandbox. If any running container belongs to the sandbox, the container must be forcibly stopped and deleted. If the sandbox has been deleted, no errors will be returned.
Precautions
- When a sandbox is deleted, network resources of the sandbox are not deleted. Before deleting a pod, you must call StopPodSandbox to clear network resources. Ensure that StopPodSandbox is called at least once before deleting the sandbox.
- If the container in a sandbox fails to be deleted when the sandbox is deleted, the sandbox is deleted but the container remains. In this case, you need to manually delete the residual container.
Parameters
Return Values
PodSandboxStatus
Prototype
rpc PodSandboxStatus(PodSandboxStatusRequest) returns (PodSandboxStatusResponse) {}
Description
This API is used to query the sandbox status. If the sandbox does not exist, an error is returned.
Parameters
Whether to display additional information about the sandbox. This parameter does not take effect now. |
Return Values
PodSandboxStatus status | |
Additional information about the sandbox. The key can be any string, and the value is a JSON character string. The information can be any debugging content. When verbose is set to true, info cannot be empty. This parameter does not take effect now. |
ListPodSandbox
Prototype
rpc ListPodSandbox(ListPodSandboxRequest) returns (ListPodSandboxResponse) {}
Description
This API is used to return the sandbox information list. Filtering based on criteria is supported.
Parameters
PodSandboxFilter filter |
Return Values
repeated PodSandbox items |
CreateContainer
rpc CreateContainer(CreateContainerRequest) returns (CreateContainerResponse) {}
Description
This API is used to create a container in the PodSandbox.
Precautions
- sandbox_config in** CreateContainerRequest** is the same as the configuration transferred to RunPodSandboxRequest to create a PodSandbox. It is transferred again for reference only. PodSandboxConfig must remain unchanged throughout the lifecycle of a pod.
- The container name is obtained from fields in ContainerMetadata and separated by underscores (_). Therefore, the metadata cannot contain underscores (_). Otherwise, the ListContainers API cannot be used for query even when the sandbox is running successfully.
- CreateContainerRequest does not contain the runtime_handler field. The runtime type of the container is the same as that of the corresponding sandbox.
Parameters
ContainerConfig config | |
PodSandboxConfig sandbox_config |
Supplement
Unstructured key-value mappings that can be used to store and retrieve any metadata. The field can be used to transfer parameters for the fields for which the CRI does not provide specific parameters.
Customize the field:
Used to limit the number of processes or threads in a container. (Set the parameter to -1 for unlimited number.)
Return Values
StartContainer
Prototype
rpc StartContainer(StartContainerRequest) returns (StartContainerResponse) {}
Description
This API is used to start a container.
Parameters
Return Values
StopContainer
Prototype
rpc StopContainer(StopContainerRequest) returns (StopContainerResponse) {}
Description
This API is used to stop a running container. You can set a graceful timeout time. If the container has been stopped, no errors will be returned.
Parameters
Waiting time before a container is forcibly stopped. The default value is 0, indicating forcible stop. |
Return Values
None
RemoveContainer
Prototype
rpc RemoveContainer(RemoveContainerRequest) returns (RemoveContainerResponse) {}
Description
This API is used to delete a container. If the container is running, it must be forcibly stopped. If the container has been deleted, no errors will be returned.
Parameters
Return Values
None
ListContainers
Prototype
rpc ListContainers(ListContainersRequest) returns (ListContainersResponse) {}
Description
This API is used to return the container information list. Filtering based on criteria is supported.
Parameters
ContainerFilter filter |
Return Values
repeated Container containers |
ContainerStatus
Prototype
rpc ContainerStatus(ContainerStatusRequest) returns (ContainerStatusResponse) {}
Description
This API is used to return the container status information. If the container does not exist, an error will be returned.
Parameters
Whether to display additional information about the sandbox. This parameter does not take effect now. |
Return Values
ContainerStatus status | |
Additional information about the sandbox. The key can be any string, and the value is a JSON character string. The information can be any debugging content. When verbose is set to true, info cannot be empty. This parameter does not take effect now. |
UpdateContainerResources
Prototype
rpc UpdateContainerResources(UpdateContainerResourcesRequest) returns (UpdateContainerResourcesResponse) {}
Description
This API is used to update container resource configurations.
Precautions
- This API cannot be used to update the pod resource configurations.
- The value of oom_score_adj of any container cannot be updated.
Parameters
LinuxContainerResources linux |
Return Values
None
ExecSync
Prototype
rpc ExecSync(ExecSyncRequest) returns (ExecSyncResponse) {}
Description
This API is used to run a command in containers in synchronization mode through the gRPC communication method.
Precautions
The interaction between the terminal and the containers must be disabled when a single command is executed.
Parameters
Timeout period for stopping the command (unit: second). The default value is 0, indicating that there is no timeout limit. This parameter does not take effect now. |
Return Values
Exit code, which represents the completion of command execution. The default value is 0, indicating that the command is executed successfully. |
Exec
Prototype
rpc Exec(ExecRequest) returns (ExecResponse) {}
Description
This API is used to run commands in a container through the gRPC communication method, that is, obtain URLs from the CRI server, and then use the obtained URLs to establish a long connection to the WebSocket server, implementing the interaction with the container.
Precautions
The interaction between the terminal and the container can be enabled when a single command is executed. One of stdin, stdout, and stderr must be true. If tty is true, stderr must be false. Multiplexing is not supported. In this case, the output of stdout and stderr will be combined to a stream.
Parameters
Return Values
Attach
Prototype
rpc Attach(AttachRequest) returns (AttachResponse) {}
Description
This API is used to take over the init process of a container through the gRPC communication method, that is, obtain URLs from the CRI server, and then use the obtained URLs to establish a long connection to the WebSocket server, implementing the interaction with the container.
Parameters
Return Values
ContainerStats
Prototype
rpc ContainerStats(ContainerStatsRequest) returns (ContainerStatsResponse) {}
Description
This API is used to return information about resources occupied by a container. Only containers whose runtime is of the LCR type are supported.
Parameters
Return Values
ContainerStats stats | Container information. Note: Disks and inodes support only the query of containers started by OCI images. |
ListContainerStats
Prototype
rpc ListContainerStats(ListContainerStatsRequest) returns (ListContainerStatsResponse) {}
Description
This API is used to return the information about resources occupied by multiple containers. Filtering based on criteria is supported.
Parameters
ContainerStatsFilter filter |
Return Values
repeated ContainerStats stats | Container information list. Note: Disks and inodes support only the query of containers started by OCI images. |
UpdateRuntimeConfig
Prototype
rpc UpdateRuntimeConfig(UpdateRuntimeConfigRequest) returns (UpdateRuntimeConfigResponse);
Description
This API is used as a standard CRI to update the pod CIDR of the network plug-in. Currently, the CNI network plug-in does not need to update the pod CIDR. Therefore, this API records only access logs.
Precautions
API operations will not modify the system management information, but only record a log.
Parameters
RuntimeConfig runtime_config |
Return Values
None
Status
Prototype
rpc Status(StatusRequest) returns (StatusResponse) {};
Description
This API is used to obtain the network status of the runtime and pod. Obtaining the network status will trigger the update of network configuration.
Precautions
If the network configuration fails to be updated, the original configuration is not affected. The original configuration is overwritten only when the update is successful.
Parameters
Whether to display additional runtime information. This parameter does not take effect now. |
Return Values
RuntimeStatus status | |
Additional information about the runtime. The key of info can be any value. The value must be in JSON format and can contain any debugging information. When verbose is set to true, info cannot be empty. |
Image Service
The service provides the gRPC API for pulling, viewing, and removing images from the registry.
ListImages
Prototype
rpc ListImages(ListImagesRequest) returns (ListImagesResponse) {}
Description
This API is used to list existing image information.
Precautions
This is a unified API. You can run the cri images command to query embedded images. However, embedded images are not standard OCI images. Therefore, query results have the following restrictions:
- An embedded image does not have an image ID. Therefore, the value of image ID is the config digest of the image.
- An embedded image has only config digest, and it does not comply with the OCI image specifications. Therefore, the value of digest cannot be displayed.
Parameters
ImageSpec filter |
Return Values
repeated Image images |
ImageStatus
Prototype
rpc ImageStatus(ImageStatusRequest) returns (ImageStatusResponse) {}
Description
This API is used to query the information about a specified image.
Precautions
- If the image to be queried does not exist, ImageStatusResponse is returned and Image is set to nil in the return value.
- This is a unified API. Since embedded images do not comply with the OCI image specifications and do not contain required fields, the images cannot be queried by using this API.
Parameters
ImageSpec image | |
Whether to query additional information. This parameter does not take effect now. No additional information is returned. |
Return Values
Image image | |
Additional image information. This parameter does not take effect now. No additional information is returned. |
PullImage
Prototype
rpc PullImage(PullImageRequest) returns (PullImageResponse) {}
Description
This API is used to download images.
Precautions
Currently, you can download public images, and use the username, password, and auth information to download private images. The server_address, identity_token, and registry_token fields in authconfig cannot be configured.
Parameters
ImageSpec image | |
AuthConfig auth | |
PodSandboxConfig sandbox_config | Whether to download an image in the pod context. This parameter does not take effect now. |
Return Values
RemoveImage
Prototype
rpc RemoveImage(RemoveImageRequest) returns (RemoveImageResponse) {}
Description
This API is used to delete specified images.
Precautions
This is a unified API. Since embedded images do not comply with the OCI image specifications and do not contain required fields, you cannot delete embedded images by using this API and the image ID.
Parameters
ImageSpec image |
Return Values
None
ImageFsInfo
Prototype
rpc ImageFsInfo(ImageFsInfoRequest) returns (ImageFsInfoResponse) {}
Description
This API is used to query the information about the file system that stores images.
Precautions
Queried results are the file system information in the image metadata.
Parameters
None
Return Values
repeated FilesystemUsage image_filesystems |
Constraints
If log_directory is configured in the PodSandboxConfig parameter when a sandbox is created, log_path must be specified in ContainerConfig when all containers that belong to the sandbox are created. Otherwise, the containers may not be started or deleted by using the CRI.
The actual value of LOGPATH of containers is log_directory/log_path. If log_path is not set, the final value of LOGPATH is changed to log_directory.
If the path does not exist, iSulad will create a soft link pointing to the actual path of container logs when starting a container. Then log_directory becomes a soft link. There are two cases:
- In the first case, if log_path is not configured for other containers in the sandbox, log_directory will be deleted and point to log_path of the newly started container. As a result, logs of the first started container point to logs of the later started container.
- In the second case, if log_path is configured for other containers in the sandbox, the value of LOGPATH of the container is log_directory/log_path. Because log_directory is a soft link, the creation fails when log_directory/log_path is used as the soft link to point to the actual path of container logs.
If the path exists, iSulad will attempt to delete the path (non-recursive) when starting a container. If the path is a folder path containing content, the deletion fails. As a result, the soft link fails to be created, the container fails to be started, and the same error occurs when the container is going to be deleted.
If log_directory is configured in the PodSandboxConfig parameter when a sandbox is created, and log_path is specified in ContainerConfig when a container is created, the final value of LOGPATH is log_directory/log_path. iSulad does not recursively create LOGPATH, therefore, you must ensure that dirname(LOGPATH) exists, that is, the upper-level path of the final log file path exists.
If log_directory is configured in the PodSandboxConfig parameter when a sandbox is created, and the same log_path is specified in ContainerConfig when multiple containers are created, or if containers in different sandboxes point to the same LOGPATH, the latest container log path will overwrite the previous path after the containers are started successfully.
If the image content in the remote registry changes and the original image is stored in the local host, the name and tag of the original image are changed to none when you call the CRI Pull image API to download the image again.
An example is as follows:
Locally stored images:
IMAGE TAG IMAGE ID SIZE rnd-dockerhub.huawei.com/pproxyisulad/test latest 99e59f495ffaa 753kB
After the rnd-dockerhub.huawei.com/pproxyisulad/test:latest image in the remote registry is updated and downloaded again:
IMAGE TAG IMAGE ID SIZE <none> <none> 99e59f495ffaa 753kB rnd-dockerhub.huawei.com/pproxyisulad/test latest d8233ab899d41 1.42MB
Run the isula images command. The value of REF is displayed as -.
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
The iSulad CRI API exec/attach is implemented using the WebSocket protocol. Clients interact with the iSulad using the same protocol. When using the exec/attach API, do not transfer a large amount of data or files over the serial port. The exec/attach API is used only for basic command interaction. If the user does not process the data or files in a timely manner, data may be lost. In addition, do not use the exec/attach API to transfer binary data or files.
The iSulad CRI API exec/attach depends on libwebsockets (LWS). It is recommended that the streaming API be used only for persistent connection interaction but not in high-concurrency scenarios, because the connection may fail due to insufficient host resources. It is recommended that the number of concurrent connections be less than or equal to 100.