CRI

• CRI
  • Description
  • APIs
    • Runtime Service
      • RunPodSandbox
      • StopPodSandbox
      • RemovePodSandbox
      • PodSandboxStatus
      • ListPodSandbox
      • CreateContainer
      • StartContainer
      • StopContainer
      • RemoveContainer
      • ListContainers
      • ContainerStatus
      • UpdateContainerResources
      • ExecSync
      • Exec
      • Attach
      • ContainerStats
      • ListContainerStats
      • UpdateRuntimeConfig
      • Status
    • Image Service
      • ListImages
      • ImageStatus
      • PullImage
      • RemoveImage
      • ImageFsInfo
  • Constraints

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:

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

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.

  Parameter	Description
  repeated string servers	DNS server list of a cluster.
  repeated string searches	DNS search domain list of a cluster.
  repeated string options	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.

  Parameter	Description
  TCP = 0↵	Transmission Control Protocol (TCP).
  UDP = 1	User Datagram Protocol (UDP).

• PortMapping

  This API is used to configure the port mapping for a sandbox.

  Parameter	Description
  Protocol protocol	Protocol used for port mapping.
  int32 container_port	Port number in the container.
  int32 host_port	Port number on the host.
  string host_ip	Host IP address.

• MountPropagation

  This API is used to specify enums of mount propagation attributes.

  Parameter	Description
  PROPAGATION_PRIVATE = 0	No mount propagation attributes, that is, private in Linux.
  PROPAGATION_HOST_TO_CONTAINER = 1	Mount attribute that can be propagated from the host to the container, that is, rslave in Linux.
  PROPAGATION_BIDIRECTIONAL = 2	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.)

  Parameter	Description
  string container_path	Path in the container.
  string host_path	Path on the host.
  bool readonly	Whether the configuration is read-only in the container. Default value: false
  bool selinux_relabel	Whether to set the SELinux label. This parameter does not take effect now.
  MountPropagation propagation	Mount propagation attribute. The value can be 0, 1, or 2, corresponding to the private, rslave, and rshared propagation attributes respectively. Default value: 0

• NamespaceOption

  Parameter	Description
  bool host_network	Whether to use host network namespaces.
  bool host_pid	Whether to use host PID namespaces.
  bool host_ipc	Whether to use host IPC namespaces.

• Capability

  This API is used to specify the capabilities to be added and deleted.

  Parameter	Description
  repeated string add_capabilities	Capabilities to be added.
  repeated string drop_capabilities	Capabilities to be deleted.

• Int64Value

  This API is used to encapsulate data of the signed 64-bit integer type.

  Parameter	Description
  int64 value	Actual value of the signed 64-bit integer type.

• UInt64Value

  This API is used to encapsulate data of the unsigned 64-bit integer type.

  Parameter	Description
  uint64 value	Actual value 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.

  Parameter	Description
  NamespaceOption namespace_options	Sandbox namespace options.
  SELinuxOption selinux_options	SELinux options. This parameter does not take effect now.
  Int64Value run_as_user	Process UID in the sandbox.
  bool readonly_rootfs	Whether the root file system of the sandbox is read-only.
  repeated int64 supplemental_groups	Information of the user group of the init process in the sandbox (except the primary GID).
  bool privileged	Whether the sandbox is a privileged container.
  string seccomp_profile_path	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. // unconfined is the default value.

• LinuxPodSandboxConfig

  This API is used to configure information related to the Linux host and containers.

  Parameter	Description
  string cgroup_parent	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	Security attribute of the sandbox.
  map<string, string> sysctls	Linux sysctls configuration of the sandbox.

• 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.

  Parameter	Description
  string name	Sandbox name.
  string uid	Sandbox UID.
  string namespace	Sandbox namespace.
  uint32 attempt	Number of attempts to create a sandbox. Default value: 0

• PodSandboxConfig

  This API is used to specify all mandatory and optional configurations for creating a sandbox.

  Parameter	Description
  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.
  string hostname	Host name of the sandbox.
  string log_directory	Folder for storing container log files in the sandbox.
  DNSConfig dns_config	Sandbox DNS configuration.
  repeated PortMapping port_mappings	Sandbox port mapping.
  map<string, string> labels	Key-value pair that can be used to identify a sandbox or a series of sandboxes.
  map<string, string> annotations	Key-value pair that stores any information, whose values cannot be changed and can be queried by using the PodSandboxStatus API.
  LinuxPodSandboxConfig linux	Options related to the Linux host.

• PodSandboxNetworkStatus

  This API is used to describe the network status of a sandbox.

  Parameter	Description
  string ip	IP address of the sandbox.
  string name	Network interface name in the sandbox.
  string network	Name of the additional network.

• Namespace

  This API is used to set namespace options.

  Parameter	Description
  NamespaceOption options	Linux namespace options.

• LinuxPodSandboxStatus

  This API is used to describe the status of a Linux sandbox.

  Parameter	Description
  Namespace namespaces	Sandbox namespace.

• PodSandboxState

  This API is used to specify enum data of the sandbox status values.

  Parameter	Description
  SANDBOX_READY = 0	The sandbox is ready.
  SANDBOX_NOTREADY = 1	The sandbox is not ready.

• PodSandboxStatus

  This API is used to describe the PodSandbox status.

  Parameter	Description
  string id	Sandbox ID.
  PodSandboxMetadata metadata	Sandbox metadata.
  PodSandboxState state	Sandbox status value.
  int64 created_at	Sandbox creation timestamp (unit: ns).
  repeated PodSandboxNetworkStatus networks	Multi-plane network status of the sandbox.
  LinuxPodSandboxStatus linux	Sandbox status complying with the Linux specifications.
  map<string, string> labels	Key-value pair that can be used to identify a sandbox or a series of sandboxes.
  map<string, string> annotations	Key-value pair that stores any information, whose values cannot be changed by the runtime.

• PodSandboxStateValue

  This API is used to encapsulate PodSandboxState.

  Parameter	Description
  PodSandboxState state	Sandbox status value.

• PodSandboxFilter

  This API is used to add filter criteria for the sandbox list. The intersection of multiple filter criteria is displayed.

  Parameter	Description
  string id	Sandbox ID.
  PodSandboxStateValue state	Sandbox status.
  map<string, string> label_selector	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.

  Parameter	Description
  string id	Sandbox ID.
  PodSandboxMetadata metadata	Sandbox metadata.
  PodSandboxState state	Sandbox status value.
  int64 created_at	Sandbox creation timestamp (unit: ns).
  map<string, string> labels	Key-value pair that can be used to identify a sandbox or a series of sandboxes.
  map<string, string> annotations	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.

  Parameter	Description
  string key	Key
  string value	Value

• SELinuxOption

  This API is used to specify the SELinux label of a container.

  Parameter	Description
  string user	User
  string role	Role
  string type	Type
  string level	Level

• 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.

  Parameter	Description
  string name	Container name.
  uint32 attempt	Number of attempts to create a container. Default value: 0

• ContainerState

  This API is used to specify enums of container status values.

  Parameter	Description
  CONTAINER_CREATED = 0	The container is created.
  CONTAINER_RUNNING = 1	The container is running.
  CONTAINER_EXITED = 2	The container exits.
  CONTAINER_UNKNOWN = 3	Unknown container status.

• ContainerStateValue

  This API is used to encapsulate the data structure of ContainerState.

  Parameter	Description
  ContainerState state	Container status value.

• ContainerFilter

  This API is used to add filter criteria for the container list. The intersection of multiple filter criteria is displayed.

  Parameter	Description
  string id	Container ID.
  PodSandboxStateValue state	Container status.
  string pod_sandbox_id	Sandbox ID.
  map<string, string> label_selector	Container label, which does not support regular expressions and must be fully matched.

• LinuxContainerSecurityContext

  This API is used to specify container security configurations.

  Parameter	Description
  Capability capabilities	Added or removed capabilities.
  bool privileged	Whether the container is in privileged mode. Default value: false
  NamespaceOption namespace_options	Container 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.
  string run_as_username	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.
  bool readonly_rootfs	Whether the root file system in a container is read-only. The default value is configured in config.json.
  repeated int64 supplemental_groups	List of user groups of the init process running in the container (except the primary GID).
  string apparmor_profile	AppArmor configuration file of the container. This parameter does not take effect now.
  string seccomp_profile_path	Path of the seccomp configuration file of the container.
  bool no_new_privs	Whether to set the no_new_privs flag in the container.

• LinuxContainerResources

  This API is used to specify configurations of Linux container resources.

  Parameter	Description
  int64 cpu_period	CPU CFS period. Default value: 0
  int64 cpu_quota	CPU CFS quota. Default value: 0
  int64 cpu_shares	CPU share (relative weight). Default value: 0
  int64 memory_limit_in_bytes	Memory limit (unit: byte). Default value: 0
  int64 oom_score_adj	OOMScoreAdj that is used to adjust the OOM killer. Default value: 0
  string cpuset_cpus	CPU core used by the container. Default value: null
  string cpuset_mems	Memory nodes used by the container. Default value: null

• Image

  This API is used to describe the basic information about an image.

  Parameter	Description
  string id	Image ID.
  repeated string repo_tags	Image tag name repo_tags.
  repeated string repo_digests	Image digest information.
  uint64 size	Image size.
  Int64Value uid	Default image UID.
  string username	Default image username.

• ImageSpec

  This API is used to represent the internal data structure of an image. Currently, ImageSpec encapsulates only the container image name.

  Parameter	Description
  string image	Container image name.

• StorageIdentifier

  This API is used to specify the unique identifier for defining the storage.

  Parameter	Description
  string uuid	Device UUID.

• FilesystemUsage

  Parameter	Description
  int64 timestamp	Timestamp when file system information is collected.
  StorageIdentifier storage_id	UUID of the file system that stores images.
  UInt64Value used_bytes	Size of the metadata that stores images.
  UInt64Value inodes_used	Number of inodes of the metadata that stores images.

• AuthConfig

  Parameter	Description
  string username	Username used for downloading images.
  string password	Password used for downloading images.
  string auth	Authentication information used for downloading images. The value is encoded by using Base64.
  string server_address	IP address of the server where images are downloaded. This parameter does not take effect now.
  string identity_token	Information about the token used for the registry authentication. This parameter does not take effect now.
  string registry_token	Information about the token used for the interaction with the registry. This parameter does not take effect now.

• Container

  This API is used to describe container information, such as the ID and status.

  Parameter	Description
  string id	Container ID.
  string pod_sandbox_id	ID of the sandbox to which the container belongs.
  ContainerMetadata metadata	Container metadata.
  ImageSpec image	Image specifications.
  string image_ref	Image used by the container. This parameter is an image ID for most runtime.
  ContainerState state	Container status.
  int64 created_at	Container creation timestamp (unit: ns).
  map<string, string> labels	Key-value pair that can be used to identify a container or a series of containers.
  map<string, string> annotations	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.

  Parameter	Description
  string id	Container ID.
  ContainerMetadata metadata	Container metadata.
  ContainerState state	Container status.
  int64 created_at	Container creation timestamp (unit: ns).
  int64 started_at	Container start timestamp (unit: ns).
  int64 finished_at	Container exit timestamp (unit: ns).
  int32 exit_code	Container exit code.
  ImageSpec image	Image specifications.
  string image_ref	Image used by the container. This parameter is an image ID for most runtime.
  string reason	Brief description of the reason why the container is in the current status.
  string message	Information that is easy to read and indicates the reason why the container is in the current status.
  map<string, string> labels	Key-value pair that can be used to identify a container or a series of containers.
  map<string, string> annotations	Key-value pair that stores any information, whose values cannot be changed by the runtime.
  repeated Mount mounts	Information about the container mount point.
  string log_path	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.

  Parameter	Description
  string id	Container ID.
  string pod_sandbox_id	Sandbox ID.
  map<string, string> label_selector	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.

  Parameter	Description
  ContainerAttributes attributes	Container information.
  CpuUsage cpu	CPU usage information.
  MemoryUsage memory	Memory usage information.
  FilesystemUsage writable_layer	Information about the writable layer usage.

• ContainerAttributes

  This API is used to list basic container information.

  Parameter	Description
  string id	Container ID.
  ContainerMetadata metadata	Container metadata.
  map<string,string> labels	Key-value pair that can be used to identify a container or a series of containers.
  map<string,string> annotations	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.

  Parameter	Description
  int64 timestamp	Timestamp.
  UInt64Value usage_core_nano_seconds	CPU usage (unit: ns).

• MemoryUsage

  This API is used to list the memory usage information of a container.

  Parameter	Description
  int64 timestamp	Timestamp.
  UInt64Value working_set_bytes	Memory usage.

• FilesystemUsage

  This API is used to list the read/write layer information of a container.

  Parameter	Description
  int64 timestamp	Timestamp.
  StorageIdentifier storage_id	Writable layer directory.
  UInt64Value used_bytes	Number of bytes occupied by images at the writable layer.
  UInt64Value inodes_used	Number of inodes occupied by images at the writable layer.

• Device

  This API is used to specify the host volume to be mounted to a container.

  Parameter	Description
  string container_path	Mounting path of a container.
  string host_path	Mounting path on the host.
  string permissions	Cgroup permission of a device. (r indicates that containers can be read from a specified device. w indicates that containers can be written to a specified device. m indicates that containers can create new device files.)

• LinuxContainerConfig

  This API is used to specify Linux configurations.

  Parameter	Description
  LinuxContainerResources resources	Container resource specifications.
  LinuxContainerSecurityContext security_context	Linux container security configuration.

• ContainerConfig

  This API is used to specify all mandatory and optional fields for creating a container.

  Parameter	Description
  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	Image used by the container. This parameter is mandatory.
  repeated string command	Command to be executed. Default value: /bin/sh
  repeated string args	Parameters of the command to be executed.
  string working_dir	Current working path of the command.
  repeated KeyValue envs	Environment variables configured in the container.
  repeated Mount mounts	Information about the mount point to be mounted in the container.
  repeated Device devices	Information about the device to be mapped in the container.
  map<string, string> labels	Key-value pair that can be used to index and select a resource.
  map<string, string> annotations	Unstructured key-value mappings that can be used to store and retrieve any metadata.
  string log_path	Relative path to PodSandboxConfig.LogDirectory, which is used to store logs (STDOUT and STDERR) on the container host.
  bool stdin	Whether to open stdin of the container.
  bool stdin_once	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.
  bool tty	Whether to use a pseudo terminal to connect to stdio of the container.
  LinuxContainerConfig linux	Container configuration information in the Linux system.

• NetworkConfig

  This API is used to specify runtime network configurations.

  Parameter	Description
  string pod_cidr	CIDR used by pod IP addresses.

• RuntimeConfig

  This API is used to specify runtime network configurations.

  Parameter	Description
  NetworkConfig network_config	Runtime network configurations.

• RuntimeCondition

  This API is used to describe runtime status information.

  Parameter	Description
  string type	Runtime status type.
  bool status	Runtime status.
  string reason	Brief description of the reason for the runtime status change.
  string message	Message with high readability, which indicates the reason for the runtime status change.

• RuntimeStatus

  This API is used to describe runtime status.

  Parameter	Description
  repeated RuntimeCondition conditions	List of current 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

1. 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.
2. 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

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

1. 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.
2. 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

Return Values

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

Return Values

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

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:

  Custom key:value	Description
  cgroup.pids.max:int64_t	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

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

Return Values

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

Return Values

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

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

Return Values

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

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

Return Values

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

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

Return Values

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

Return Values

ImageStatus

Prototype

rpc ImageStatus(ImageStatusRequest) returns (ImageStatusResponse) {}

Description

This API is used to query the information about a specified image.

Precautions

1. If the image to be queried does not exist, ImageStatusResponse is returned and Image is set to nil in the return value.
2. 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

Return Values

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

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

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

Constraints

1. 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:

     1. 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.
     2. 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.

2. 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.

3. 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.

4. 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
   

5. 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.

6. 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.