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

    The 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

    The API is used to specify enum values of protocols.

    Parameter

    Description

    TCP = 0↵

    Transmission Control Protocol (TCP).

    UDP = 1

    User Datagram Protocol (UDP).

  • PortMapping

    The 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

    The 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

    The 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

    The 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

    The 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

    The 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

    The 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

    The 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

    The API is used to set namespace options.

    Parameter

    Description

    NamespaceOption options

    Linux namespace options.

  • LinuxPodSandboxStatus

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

    Parameter

    Description

    Namespace namespaces

    Sandbox namespace.

  • PodSandboxState

    The 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

    The 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

    The API is used to encapsulate PodSandboxState.

    Parameter

    Description

    PodSandboxState state

    Sandbox status value.

  • PodSandboxFilter

    The 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

    The API is used to encapsulate key-value pairs.

    Parameter

    Description

    string key

    Key

    string value

    Value

  • SELinuxOption

    The 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

    The 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

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

    Parameter

    Description

    ContainerState state

    Container status value.

  • ContainerFilter

    The 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

    The 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

    The 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

    The 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

    The 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

    The 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

    The 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

    The 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

    The 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

    The 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

    The 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

    The 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

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

    Parameter

    Description

    int64 timestamp

    Timestamp.

    UInt64Value working_set_bytes

    Memory usage.

  • FilesystemUsage

    The 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

    The 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

    The API is used to specify Linux configurations.

    Parameter

    Description

    LinuxContainerResources resources

    Container resource specifications.

    LinuxContainerSecurityContext security_context

    Linux container security configuration.

  • ContainerConfig

    The 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

    The 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

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

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

grpc::Status CreateContainer(grpc::ServerContext *context, const runtime::CreateContainerRequest *request, runtime::CreateContainerResponse *reply) {}

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

The 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. Only containers whose runtime is of the LCR type are supported.

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. Only containers whose runtime is of the LCR type are supported.

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

The 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
    
Rating

search results about are found