LTS

    Innovation Version

      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:

      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

      Parameter

      Description

      PodSandboxConfig config

      Sandbox configuration.

      string runtime_handler

      Runtime for the created sandbox. Currently, lcr and kata-runtime are supported.

      Return Values

      Return Value

      Description

      string pod_sandbox_id

      If the operation is successful, the response is returned.

      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

      Parameter

      Description

      string pod_sandbox_id

      Sandbox ID.

      Return Values

      Return Value

      Description

      None

      None

      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

      Parameter

      Description

      string pod_sandbox_id

      Sandbox ID.

      Return Values

      Return Value

      Description

      None

      None

      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

      Parameter

      Description

      string pod_sandbox_id

      Sandbox ID

      bool verbose

      Whether to display additional information about the sandbox. This parameter does not take effect now.

      Return Values

      Return Value

      Description

      PodSandboxStatus status

      Status of the sandbox.

      map<string, string> info

      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

      Parameter

      Description

      PodSandboxFilter filter

      Filter criteria.

      Return Values

      Return Value

      Description

      repeated PodSandbox items

      Sandbox information list.

      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

      Parameter

      Description

      string pod_sandbox_id

      ID of the PodSandbox where a container is to be created.

      ContainerConfig config

      Container configuration information.

      PodSandboxConfig sandbox_config

      PodSandbox configuration information.

      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

      Return Value

      Description

      string container_id

      ID of the created container.

      StartContainer

      Prototype

      rpc StartContainer(StartContainerRequest) returns (StartContainerResponse) {}
      

      Description

      This API is used to start a container.

      Parameters

      Parameter

      Description

      string container_id

      Container ID.

      Return Values

      Return Value

      Description

      None

      None

      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

      Parameter

      Description

      string container_id

      Container ID.

      int64 timeout

      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

      Parameter

      Description

      string container_id

      Container ID.

      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

      Parameter

      Description

      ContainerFilter filter

      Filter criteria.

      Return Values

      Return Value

      Description

      repeated Container containers

      Container information list.

      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

      Parameter

      Description

      string container_id

      Container ID.

      bool verbose

      Whether to display additional information about the sandbox. This parameter does not take effect now.

      Return Values

      Return Value

      Description

      ContainerStatus status

      Container status information.

      map<string, string> info

      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

      Parameter

      Description

      string container_id

      Container ID.

      LinuxContainerResources linux

      Linux resource configuration information.

      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

      Parameter

      Description

      string container_id

      Container ID.

      repeated string cmd

      Command to be executed.

      int64 timeout

      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

      Return Value

      Description

      bytes stdout

      Standard output of the capture command.

      bytes stderr

      Standard error output of the capture command.

      int32 exit_code

      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

      Parameter

      Description

      string container_id

      Container ID.

      repeated string cmd

      Command to be executed.

      bool tty

      Whether to run the command in a TTY.

      bool stdin

      Whether to generate the standard input stream.

      bool stdout

      Whether to generate the standard output stream.

      bool stderr

      Whether to generate the standard error output stream.

      Return Values

      Return Value

      Description

      string url

      Fully qualified URL of the exec streaming server.

      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

      Parameter

      Description

      string container_id

      Container ID.

      bool tty

      Whether to run the command in a TTY.

      bool stdin

      Whether to generate the standard input stream.

      bool stdout

      Whether to generate the standard output stream.

      bool stderr

      Whether to generate the standard error output stream.

      Return Values

      Return Value

      Description

      string url

      Fully qualified URL of the attach streaming server.

      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

      Parameter

      Description

      string container_id

      Container ID.

      Return Values

      Return Value

      Description

      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

      Parameter

      Description

      ContainerStatsFilter filter

      Filter criteria.

      Return Values

      Return Value

      Description

      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

      Parameter

      Description

      RuntimeConfig runtime_config

      Information to be configured for the runtime.

      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

      Parameter

      Description

      bool verbose

      Whether to display additional runtime information. This parameter does not take effect now.

      Return Values

      Return Value

      Description

      RuntimeStatus status

      Runtime status.

      map<string, string> info

      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

      Parameter

      Description

      ImageSpec filter

      Name of the image to be filtered.

      Return Values

      Return Value

      Description

      repeated Image images

      Image information list.

      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

      Parameter

      Description

      ImageSpec image

      Image name.

      bool verbose

      Whether to query additional information. This parameter does not take effect now. No additional information is returned.

      Return Values

      Return Value

      Description

      Image image

      Image information.

      map<string, string> info

      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

      Parameter

      Description

      ImageSpec image

      Name of the image to be downloaded.

      AuthConfig auth

      Verification information for downloading a private image.

      PodSandboxConfig sandbox_config

      Whether to download an image in the pod context. This parameter does not take effect now.

      Return Values

      Return Value

      Description

      string image_ref

      Information about the downloaded image.

      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

      Parameter

      Description

      ImageSpec image

      Name or ID of the image to be deleted.

      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

      Return Value

      Description

      repeated FilesystemUsage image_filesystems

      Information about the file system that stores images.

      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.

      Bug Catching

      Buggy Content

      Bug Description

      Submit As Issue

      It's a little complicated....

      I'd like to ask someone.

      PR

      Just a small problem.

      I can fix it online!

      Bug Type
      Specifications and Common Mistakes

      ● Misspellings or punctuation mistakes;

      ● Incorrect links, empty cells, or wrong formats;

      ● Chinese characters in English context;

      ● Minor inconsistencies between the UI and descriptions;

      ● Low writing fluency that does not affect understanding;

      ● Incorrect version numbers, including software package names and version numbers on the UI.

      Usability

      ● Incorrect or missing key steps;

      ● Missing prerequisites or precautions;

      ● Ambiguous figures, tables, or texts;

      ● Unclear logic, such as missing classifications, items, and steps.

      Correctness

      ● Technical principles, function descriptions, or specifications inconsistent with those of the software;

      ● Incorrect schematic or architecture diagrams;

      ● Incorrect commands or command parameters;

      ● Incorrect code;

      ● Commands inconsistent with the functions;

      ● Wrong screenshots.

      Risk Warnings

      ● Lack of risk warnings for operations that may damage the system or important data.

      Content Compliance

      ● Contents that may violate applicable laws and regulations or geo-cultural context-sensitive words and expressions;

      ● Copyright infringement.

      How satisfied are you with this document

      Not satisfied at all
      Very satisfied
      Submit
      Click to create an issue. An issue template will be automatically generated based on your feedback.
      Bug Catching
      编组 3备份