LTS

    Innovation Version

      Container Management

      Creating a Container

      Description

      To create a container, run the isula create command. The container engine will use the specified container image to create a read/write layer, or use the specified local rootfs as the running environment of the container. After the creation is complete, the container ID is output as standard output. You can run the isula start command to start the container. The new container is in the inited state.

      Usage

      isula create [OPTIONS] IMAGE [COMMAND] [ARG...]
      

      Parameters

      The following table lists the parameters supported by the create command.

      Table 1 Parameter description

      Command

      Parameter

      Description

      create

        

      --add-host

      Adds the mapping between the custom host and the IP address (host:ip).

      --annotation

      Sets annotations for the container. For example, set the native.umask parameter.

      --annotation native.umask=normal #The umask value of the started container is 0022.
      --annotation native.umask=secure #The umask value of the started container is 0027.

      If this parameter is not set, the umask configuration in iSulad is used.

      --blkio-weight

      Specifies the block I/O (relative weight). The value ranges from 10 to 1000. The default value is 0, indicating that this function is disabled.

      --blkio-weight-device

      Specifies the block I/O weight (relative device weight). The format is DEVICE_NAME: weight. The weight value ranges from 10 to 1000. The default value is 0, indicating that this function is disabled.

      --cap-add

      Adds the Linux permission function.

      --cap-drop

      Deletes Linux permissions.

      --cgroup-parent

      Specifies the cgroup parent path of the container.

      --cpu-period

      Limits the period of CPU CFS.

      --cpu-quota

      Limits the CPU CFS quota.

      --cpu-rt-period

      Limits the real-time CPU period (in microseconds).

      --cpu-rt-runtime

      Limits the real-time running time of the CPU (in microseconds).

      --cpu-shares

      CPU share (relative weight).

      --cpus

      Specifies the number of CPUs.

      --cpuset-cpus

      Specifies the CPU that can be executed. Example values: 0-3, 0, 1.

      --cpuset-mems

      Specifies memory that can be executed. Example values: 0-3, 0, 1.

      --device

      Adds a device to the container.

      --device-cgroup-rule

      Adds a rule to the list of devices allowed by the cgroup.

      --device-read-bps

      Limits the read rate (bytes per second) of the device.

      --device-read-iops

      Limits the read rate (I/Os per second) of the device.

      --device-write-bps

      Limits the write rate (bytes per second) of the device.

      --device-write-iops

      Limits the write rate (I/Os per second) of the device.

      --dns

      Adds a DNS server.

      --dns-opt

      Adds DNS options.

      --dns-search

      Sets the search domain of a container.

      --entrypoint

      Specifies the entry point to be run when a container is started.

      -e, --env

      Sets environment variables.

      --env-file

      Configures environment variables using a file.

      --env-target-file

      Specifies the target file path in rootfs to which environment variables are exported.

      --external-rootfs=PATH

      Specifies a rootfs (a folder or block device) that is not managed by iSulad for the container.

      --files-limit

      Limits the number of file handles that can be opened in a container. The value -1 indicates no limit.

      --group-add=[]

      Adds additional user groups to the container.

      --help

      Prints help information.

      --health-cmd

      Command executed in a container.

      --health-exit-on-unhealthy

      Determines whether to kill a container when the container is detected unhealthy.

      --health-interval

      Interval between two consecutive command executions.

      --health-retries

      Maximum number of health check retries.

      --health-start-period

      Container initialization interval.

      --health-timeout

      Maximum time for executing a single check command.

      --hook-spec

      Hook configuration file.

      -H, --host

      Specifies the iSulad socket file path to be accessed.

      --host-channel

      Creates the shared memory between the host and the container.

      -h, --hostname

      Container host name.

      --hugetlb-limit=[]

      Limits the huge page file. For example, --hugetlb-limit 2MB:32MB.

      -i, --interactive

      Enables the standard input of the container even if it is not connected to the standard input of the container.

      --ipc

      Specifies the IPC namespace.

      --kernel-memory

      Limits the kernel memory.

      -l,--label

      Sets a label for a container.

      --lablel-file

      Sets container labels using files.

      --log-driver

      Records the container driver.

      --log-opt=[]

      Log driver option. By default, the function of recording container serial port logs is disabled. You can enable it by setting --log-opt disable-log=false.

      -m, --memory

      Memory limit.

      --memory-reservation

      Sets the container memory limit. The default value is the same as that of --memory. --memory is a hard limit, and --memory-reservation is a soft limit. When the memory usage exceeds the preset value, the memory usage is dynamically adjusted (the system attempts to reduce the memory usage to a value less than the preset value when reclaiming the memory). However, the memory usage may exceed the preset value. Generally, this parameter can be used together with --memory. The value must be less than the preset value of --memory. The minimum value is 4 MB.

      --memory-swap

      Memory swap space, which should be a positive integer. The value -1 indicates no limit.

      --memory-swappiness

      The value of swappiness is a positive integer ranging from 0 to 100. The smaller the value is, the less the swap partition is used and the more the memory is used in the Linux system. The larger the value is, the more the swap space is used by the kernel. The default value is -1, indicating that the default system value is used.

      --mount

      Mounts the host directory, volume, or file system to the container.

      --name=NAME

      Container name.

      --net=none

      Connects the container to the network.

      --no-healthcheck

      Disables the health check configuration.

      --ns-change-opt

      Namespace kernel parameter option of the system container.

      --oom-kill-disable

      Disables OOM.

      --oom-score-adj

      Adjusts the OOM preference of the host (from -1000 to 1000).

      --pid

      Specifies the PID namespace to be used.

      --pids-limit

      Limits the number of processes that can be executed in the container. The value -1 indicates no limit.

      --privileged

      Grants container extension privileges.

      --pull

      Pulls the image before running.

      -R, --runtime

      Container runtime. The parameter value can be runc or lcr, which is case insensitive. Therefore, LCR and lcr are equivalent.

      --read-only

      Sets the rootfs of a container to read-only.

      --restart

      Restart policy upon container exit.

      For a system container, --restart on-reboot is supported.

      --security-opt

      Security option.

      --shm-size

      Size of /dev/shm. The default value is 64MB.

      --stop-signal

      Stop signal for a container. The default value is SIGTERM.

      --storage-opt

      Configures the storage driver option for a container.

      --sysctl

      Sets the sysctl option.

      --system-container

      Starts the system container.

      --tmpfs

      Mounts the tmpfs directory.

      -t, --tty

      Allocates a pseudo terminal.

      --ulimit

      Sets the ulimit for a container.

      -u, --user

      User name or UID, in the format of [<name|uid>][:<group|gid>].

      --user-remap

      Maps users to the system container.

      --userns

      Sets the user command space for a container when the user-remap option is enabled.

      --uts

      Sets the PID namespace.

      -v, --volume=[]

      Mounts a volume.

      --volumes-from=[]

      Uses the mounting configuration of the specified container.

      --workdir

      Sets the working directory in the container.

      Constraints

      • When the --user or --group-add parameter is used to verify the user or group during container startup, if the container uses an OCI image, the verification is performed in the etc/passwd and etc/group files of the actual rootfs of the image. If a folder or block device is used as the rootfs of the container, the etc/passwd and etc/group files in the host are verified. The rootfs ignores mounting parameters such as -v and --mount. That is, when these parameters are used to attempt to overwrite the etc/passwd and etc/group files, the parameters do not take effect during the search and take effect only when the container is started. The generated configuration is saved in the iSulad root directory/engine/container ID/start_generate_config.json file. The file format is as follows:

        {
            "uid": 0,
            "gid": 8,
            "additionalGids": [
                1234,
                8
            ]
        }
        

      Example

      Create a container.

      # isula create busybox
      fd7376591a9c3d8ee9a14f5d2c2e5255b02cc44cddaabca82170efd4497510e1
      # isula ps -a
      STATUS PID IMAGE   COMMAND EXIT_CODE RESTART_COUNT STARTAT FINISHAT RUNTIME ID           NAMES                
      inited -   busybox "sh"    0         0             -       -        runc     fd7376591a9c fd7376591a9c4521...
      

      Starting a Container

      Description

      To start one or more containers, run the isula start command.

      Usage

      isula start [OPTIONS] CONTAINER [CONTAINER...]
      

      Parameters

      The following table lists the parameters supported by the start command.

      Table 1 Parameter description

      Command

      Parameter

      Description

      start

      -H, --host

      Specifies the iSulad socket file path to be accessed.

      -a, --attach

      Connects to STDOUT and STDERR of the container.

      -D, --debug

      Enables the debug mode.

      --help

      Prints help information.

      Example

      Start a new container.

      isula start fd7376591a9c3d8ee9a14f5d2c2e5255b02cc44cddaabca82170efd4497510e1
      

      Running a Container

      Description

      To create and start a container, run the isula run command. You can use a specified container image to create a container read/write layer and prepare for running the specified command. After the container is created, run the specified command to start the container. The run command is equivalent to creating and starting a container.

      Usage

      isula run [OPTIONS] ROOTFS|IMAGE [COMMAND] [ARG...]
      

      Parameters

      The following table lists the parameters supported by the run command.

      Table 1 Parameter description

      Command

      Parameter

      Description

      run

      --annotation

      Sets annotations for the container. For example, set the native.umask option.

      --annotation native.umask=normal #The umask value of the started container is 0022.
      --annotation native.umask=secure #The umask value of the started container is 0027.

      If this parameter is not set, the umask configuration in iSulad is used.

      --add-host

      Adds the mapping between the custom host and the IP address (host:ip).

      --blkio-weight

      Specifies the block I/O (relative weight). The value ranges from 10 to 1000. The default value is 0, indicating that this function is disabled.

      --blkio-weight-device

      Specifies the block I/O weight (relative device weight). The format is DEVICE_NAME: weight. The weight value ranges from 10 to 1000. The default value is 0, indicating that this function is disabled.

      --cap-add

      Adds Linux functions.

      --cap-drop

      Deletes Linux functions.

      --cgroup-parent

      Specifies the cgroup parent path of the container.

      --cpu-period

      Limits the period of CPU CFS.

      --cpu-quota

      Limits the CPU CFS quota.

      --cpu-rt-period

      Limits the real-time CPU period (in microseconds).

      --cpu-rt-runtime

      Limits the real-time running time of the CPU (in microseconds).

      --cpu-shares

      CPU share (relative weight).

      --cpus

      Specifies the number of CPUs.

      --cpuset-cpus

      Specifies the CPU that can be executed. Example values: 0-3, 0, 1.

      --cpuset-mems

      Specifies memory that can be executed. Example values: 0-3, 0, 1.

      -d, --detach

      Runs the container in the background and displays the container ID.

      --device=[]

      Adds a device to the container.

      --device-cgroup-rule

      Adds a rule to the list of devices allowed by the cgroup.

      --device-read-bps

      Limits the read rate (bytes per second) of the device.

      --device-read-iops

      Limits the read rate (I/Os per second) of the device.

      --device-write-bps

      Limits the write rate (bytes per second) of the device.

      --device-write-iops

      Limits the write rate (I/Os per second) of the device.

      --dns

      Adds a DNS server.

      --dns-opt

      Adds DNS options.

      --dns-search

      Sets the search domain of a container.

      --entrypoint

      Specifies the entry point to be run when a container is started.

      -e, --env

      Sets environment variables.

      --env-file

      Configures environment variables using a file.

      --env-target-file

      Specifies the target file path in rootfs to which environment variables are exported.

      --external-rootfs=PATH

      Specifies a rootfs (a folder or block device) that is not managed by iSulad for the container.

      --files-limit

      Limits the number of file handles that can be opened in the container. The value -1 indicates no limit.

      --group-add=[]

      Adds additional user groups to the container.

      --help

      Prints help information.

      --health-cmd

      Command executed in a container.

      --health-exit-on-unhealthy

      Determines whether to kill a container when the container is detected unhealthy.

      --health-interval

      Interval between two consecutive command executions.

      --health-retries

      Maximum number of health check retries.

      --health-start-period

      Container initialization interval.

      --health-timeout

      Maximum time for executing a single check command.

      --hook-spec

      Hook configuration file.

      -H, --host

      Specifies the iSulad socket file path to be accessed.

      --host-channel

      Creates the shared memory between the host and the container.

      -h, --hostname

      Container host name.

      --hugetlb-limit=[]

      Limits the size of huge-page files, for example, --hugetlb-limit 2MB:32MB.

      -i, --interactive

      Enables the standard input of the container even if it is not connected to the standard input of the container.

      --ipc

      Specifies the IPC namespace.

      --kernel-memory

      Limits the kernel memory.

      -l, --label

      Sets a label for a container.

      --lablel-file

      Sets the container label through a file.

      --log-driver

      Sets the log driver. syslog and json-file are supported.

      --log-opt=[]

      Log driver option. By default, the container serial port log function is disabled. You can run the --log-opt disable-log=false command to enable it.

      -m, --memory

      Memory limit.

      --memory-reservation

      Sets the container memory limit. The default value is the same as that of --memory. --memory is a hard limit, and --memory-reservation is a soft limit. When the memory usage exceeds the preset value, the memory usage is dynamically adjusted (the system attempts to reduce the memory usage to a value less than the preset value when reclaiming the memory). However, the memory usage may exceed the preset value. Generally, this parameter can be used together with --memory. The value must be less than the preset value of --memory. The minimum value is 4 MB.

      --memory-swap

      Memory swap space, which should be a positive integer. The value -1 indicates no limit.

      --memory-swappiness

      The value of swappiness is a positive integer ranging from 0 to 100. The smaller the value is, the less the swap partition is used and the more the memory is used in the Linux system. The larger the value is, the more the swap space is used by the kernel. The default value is -1, indicating that the default system value is used.

      --mount

      Mounts a host directory to a container.

      --name=NAME

      Container name

      --net=none

      Connects a container to the network.

      --no-healthcheck

      Disables the health check configuration.

      --ns-change-opt

      Namespace kernel parameter option of the system container.

      --oom-kill-disable

      Disables OOM.

      --oom-score-adj

      Adjusts the OOM preference of the host (from -1000 to 1000).

      --pid

      Specifies the PID namespace to be used.

      --pids-limit

      Limits the number of processes that can be executed in the container. The value -1 indicates no limit.

      --privileged

      Grants container extension privileges.

      --pull

      Pulls the image before running.

      -R, --runtime

      Container runtime. The parameter value can be runc or lcr, which is case insensitive. Therefore, LCR and lcr are equivalent.

      --read-only

      Sets the rootfs of a container to read-only.

      --restart

      Restart policy upon container exit.

      For a system container, --restart on-reboot is supported.

      --rm

      Automatically clears a container upon exit.

      --security-opt

      Security option.

      --shm-size

      Size of /dev/shm. The default value is 64MB.

      --stop-signal

      Stop signal for a container. The default value is SIGTERM.

      --storage-opt

      Configures the storage driver option of a container.

      --sysctl

      Sets the sysctl option.

      --system-container

      Starts the system container.

      --tmpfs

      Mounts the tmpfs directory.

      -t, --tty

      Allocates a pseudo terminal.

      --ulimit

      Sets the ulimit for a container.

      -u, --user

      User name or UID, in the format of [<name|uid>][:<group|gid>].

      --user-remap

      Maps users to the system container.

      --userns

      Sets the user command space for a container when the user-remap option is enabled.

      --uts

      Sets the PID namespace.

      -v, --volume=[]

      Mounts a volume.

      --volumes-from=[]

      Uses the mounting configuration of the specified container.

      --workdir

      Sets the working directory in the container.

      Constraints

      • When the parent process of a container exits, the corresponding container automatically exits.

      • When a common container is created, the parent process cannot be initiated because the permission of common containers is insufficient. As a result, the container does not respond when you run the attach command though it is created successfully.

      • If --net is not specified when the container is running, the default host name is localhost.

      • If the --files-limit parameter is to transfer a small value, for example, 1, when the container is started, iSulad creates a cgroup, sets the files.limit value, and writes the PID of the container process to the cgroup.procs file of the cgroup. At this time, the container process has opened more than one handle. As a result, a write error is reported, and the container fails to be started.

      • If both**--mount** and --volume exist and their destination paths conflict, --mount will be run after --volume (that is, the mount point in --volume will be overwritten).

        Note: The value of the type parameter of lightweight containers can be bind or squashfs. When type is set to squashfs, src is the image path. The value of the type parameter of the native Docker can be bind, volume, and tmpfs.

      • The restart policy does not support unless-stopped.

      • The values returned for Docker and lightweight containers are 127 and 125 respectively in the following three scenarios:

        The host device specified by --device does not exist.

        The hook JSON file specified by --hook-spec does not exist.

        The entry point specified by --entrypoint does not exist.

      • When the --volume parameter is used, /dev/ptmx will be deleted and recreated during container startup. Therefore, do not mount the /dev directory to that of the container. Use --device to mount the devices in /dev of the container.

      • When the -it parameter is used, the /dev/ptmx device will be deleted and rebuilt when the container is started. Therefore, do not mount the /dev directory to the /dev directory of the container. Instead, use --device to mount the devices in the /dev directory to the container.

      • Do not use the echo option to input data to the standard input of the run command. Otherwise, the client will be suspended. The echo value should be directly transferred to the container as a command line parameter.

        # echo ls | isula run -i busybox /bin/sh
        
        
        ^C
        #
        

        The client is suspended when the preceding command is executed because the preceding command is equivalent to input ls to stdin. Then EOF is read and the client does not send data and waits for the server to exit. However, the server cannot determine whether the client needs to continue sending data. As a result, the server is suspended in reading data, and both parties are suspended.

        The correct execution method is as follows:

        # isula run -i busybox ls
        bin
        dev
        etc
        home
        proc
        root
        sys
        tmp
        usr
        var
        #
        
      • If the root directory (/) of the host is used as the file system of the container, the following situations may occur during the mounting:

        Table 2 Mounting scenarios

        Host Path (Source)

        Container Path (Destination)

        /home/test1

        /mnt/

        /home/test2

        /mnt/abc

        NOTICE: Scenario 1: Mount /home/test1 and then /home/test2. In this case, the content in /home/test1 overwrites the content in /mnt. As a result, the abc directory does not exist in /mnt, and mounting**/home/test2** to /mnt/abc fails. Scenario 2: Mount /home/test2 and then /home/test1. In this case, the content of /mnt is replaced with the content of /home/test1 during the second mounting. In this way, the content mounted during the first mounting from /home/test2 to /mnt/abc is overwritten. The first scenario is not supported. For the second scenario, users need to understand the risk of data access failures.

      • Exercise caution when configuring the /sys and /proc directories to be writable.

        The /sys and /proc directories contain the APIs for maintaining Linux kernel parameters and managing devices. If the directories are writable in a container, container escape may occur.

      • Exercise caution when configuring containers to share namespaces with hosts.

        For example, if you use --pid, --ipc, --uts, or --net to configure namespace sharing between the container and the host, the namespace isolation between the container and the host is lost, and the host can be attacked from the container. For example, if you use --pid to configure PID namespace sharing between the container and the host, the PID of the process on the host can be viewed in the container and the process can be killed in the container.

      • Exercise caution when configuring parameters that can be used to mount host resources, such as --device and -v. Do not map sensitive directories or devices of the host to containers to prevent leakage of sensitive information.

      • Exercise caution when using the --privileged option to start a container. If the --privileged option is used, the container will have excessive permissions, affecting the host configuration.

        NOTICE:

        • In high concurrency scenarios (200 containers are concurrently started), the memory management mechanism of Glibc may cause memory holes and large virtual memory (for example, 10 GB). This problem is caused by the restriction of the Glibc memory management mechanism in the high concurrency scenario, but not by memory leakage. Therefore, the memory consumption does not increase infinitely. You can set the MALLOC_ARENA_MAX environment variable to reduce the virtual memory and increase the probability of reducing the physical memory. However, this environment variable will cause the iSulad concurrency performance to deteriorate. Set this environment variable based on the site requirements.

          To balance performance and memory usage, set MALLOC_ARENA_MAX to 4. (The iSulad performance deterioration on the ARM64 server is controlled by less than 10%.)
          Configuration method:
          1. To manually start iSulad, run the export MALLOC_ARENA_MAX=4 command and then start the iSulad.
          2. If systemd manages iSulad, you can modify the /etc/sysconfig/iSulad file by adding MALLOC_ARENA_MAX=4.
          

      Example

      Run a new container.

      # isula run -itd busybox
      9c2c13b6c35f132f49fb7ffad24f9e673a07b7fe9918f97c0591f0d7014c713b
      

      Stopping a Container

      Description

      To stop a container, run the isula stop command. The SIGTERM signal is sent to the first process in the container. If the container is not stopped within the specified time (10s by default), the SIGKILL signal is sent.

      Usage

      isula stop [OPTIONS] CONTAINER [CONTAINER...]
      

      Parameters

      The following table lists the parameters supported by the stop command.

      Table 1 Parameter description

      Command

      Parameter

      Description

      stop

      -f, --force

      Forcibly stops a running container.

      -H, --host

      Specifies the iSulad socket file path to be accessed.

      -D, --debug

      Enables the debug mode.

      --help

      Prints help information.

      -t, --time

      Time for graceful stop. If the time exceeds the value of this parameter, the container is forcibly stopped.

      Constraints

      • If the t parameter is specified and the value of t is less than 0, ensure that the application in the container can process the stop signal.

        Principle of the Stop command: Send the SIGTERM signal to the container, and then wait for a period of time (t entered by the user). If the container is still running after the period of time, the SIGKILL signal is sent to forcibly kill the container.

      • The meaning of the input parameter t is as follows:

        t < 0: Wait for graceful stop. This setting is preferred when users are assured that their applications have a proper stop signal processing mechanism.

        t = 0: Do not wait and send kill -9 to the container immediately.

        t > 0: Wait for a specified period and send kill -9 to the container if the container does not stop within the specified period.

        Therefore, if t is set to a value less than 0 (for example, t = -1), ensure that the container application correctly processes the SIGTERM signal. If the container ignores this signal, the container will be suspended when the isula stop command is run.

      Example

      Stop a container.

      # isula stop fd7376591a9c3d8ee9a14f5d2c2e5255b02cc44cddaabca82170efd4497510e1
      fd7376591a9c3d8ee9a14f5d2c2e5255b02cc44cddaabca82170efd4497510e1
      

      Forcibly Stopping a Container

      Description

      To forcibly stop one or more running containers, run the isula kill command.

      Usage

      isula kill [OPTIONS] CONTAINER [CONTAINER...]
      

      Parameters

      The following table lists the parameters supported by the kill command.

      Table 1 Parameter description

      Command

      Parameter

      Description

      kill

      -H, --host

      Specifies the iSulad socket file path to be accessed.

      -D, --debug

      Enables the debug mode.

      --help

      Prints help information.

      -s, --signal

      Signal sent to the container.

      Example

      Kill a container.

      # isula kill fd7376591a9c3d8ee9a14f5d2c2e5255b02cc44cddaabca82170efd4497510e1
      fd7376591a9c3d8ee9a14f5d2c2e5255b02cc44cddaabca82170efd4497510e1
      

      Removing a Container

      Description

      To remove a container, run the isula rm command.

      Usage

      isula rm [OPTIONS] CONTAINER [CONTAINER...]
      

      Parameters

      The following table lists the parameters supported by the rm command.

      Table 1 Parameter description

      Command

      Parameter

      Description

      rm

      -f, --force

      Forcibly removes a running container.

      -D, --debug

      Enables the debug mode.

      --help

      Prints help information.

      -H, --host

      Specifies the iSulad socket file path to be accessed.

      -v, --volume

      Removes a volume mounted to a container. (Note: Currently, iSulad does not use this function.)

      Constraints

      • In normal I/O scenarios, it takes T1 to delete a running container in an empty environment (with only one container). In an environment with 200 containers (without a large number of I/O operations and with normal host I/O), it takes T2 to delete a running container. The specification of T2 is as follows: T2 = max {T1 x 3, 5}s.

      Example

      Delete a stopped container.

      # isula rm fd7376591a9c3d8ee9a14f5d2c2e5255b02cc44cddaabca82170efd4497510e1
      fd7376591a9c3d8ee9a14f5d2c2e5255b02cc44cddaabca82170efd4497510e1
      

      Attaching to a Container

      Description

      To attach standard input, standard output, and standard error of the current terminal to a running container, run the isula attach command.

      Usage

      isula attach [OPTIONS] CONTAINER
      

      Parameters

      The following table lists the parameters supported by the attach command.

      Table 1 Parameter description

      Command

      Parameter

      Description

      attach

      --help

      Prints help information.

      -H, --host

      Specifies the iSulad socket file path to be accessed.

      -D, --debug

      Enables the debug mode.

      Constraints

      • For the native Docker, running the attach command will directly enter the container. For the iSulad container, you have to run the attach command and press Enter to enter the container.

      Example

      Attach to a running container.

      # isula attach fd7376591a9c3d8ee9a14f5d2c2e5255b02cc44cddaabca82170efd4497510e1
      / #
      / #
      

      Renaming a Container

      Description

      To rename a container, run the isula rename command.

      Usage

      isula rename [OPTIONS] OLD_NAME NEW_NAME
      

      Parameters

      The following table lists the parameters supported by the rename command.

      Table 1 Parameter description

      Command

      Parameter

      Description

      rename

      --help

      Prints help information.

      -H, --host

      Specifies the path of the iSulad socket file to be connected.

      -D, --debug

      Enables the debug mode.

      Example

      Rename a container.

      isula rename my_container my_new_container
      

      Executing a Command in a Running Container

      Description

      To execute a command in a running container, run the isula exec command. This command is executed in the default directory of the container. If a user-defined directory is specified for the basic image, the user-defined directory is used.

      Usage

      isula exec [OPTIONS] CONTAINER COMMAND [ARG...]
      

      Parameters

      The following table lists the parameters supported by the exec command.

      Table 1 Parameter description

      Command

      Parameter

      Description

      exec

        

      -d, --detach

      Runs a command in the background.

      -D, --debug

      Enables the debug mode.

      -e, --env

      Sets environment variables. (Note: Currently, iSulad does not use this function.)

      --help

      Prints help information.

      -H, --host

      Specifies the iSulad socket file path to be accessed.

      -i, --interactive

      Enables the standard input though no connection is set up. (Note: Currently, iSulad does not use this function.)

      -t, --tty

      Allocates a pseudo terminal. (Note: Currently, iSulad does not use this function.)

      -u, --user

      Logs in to the container as a specified user.

      --workdir

      Specifies the working directory for running the command. This function is supported only when runtime is set to lcr.

      Constraints

      • If no parameter is specified in the isula exec command, the -it parameter is used by default, indicating that a pseudo terminal is allocated and the container is accessed in interactive mode.

      • When you run the isula exec command to execute a script and run a background process in the script, you need to use the nohup flag to ignore the SIGHUP signal.

        When you run the isula exec command to execute a script and run a background process in the script, you need to use the nohup flag. Otherwise, the kernel sends the SIGHUP signal to the process executed in the background when the process (first process of the session) exits. As a result, the background process exits and zombie processes occur.

      • After running the isula exec command to access the container process, do not run background programs. Otherwise, the system will be suspended.

        To run the isula exec command to execute a background process, perform the following steps:

        1. Run the isula exec container_name bash command to access the container.
        2. After entering the container, run the script & command.
        3. Run the exit command. The terminal stops responding.

        After the isula exec command is executed to enter the container, the background program stops responding because the isula exec command is executed to enter the container and run the background while1 program. When the bash command is run to exit the process, the while1 program does not exit and becomes an orphan process, which is taken over by process 1. The while1 process is executed by the initial bash process fork &exec of the container. The while1 process copies the file handle of the bash process. As a result, the handle is not completely closed when the bash process exits. The console process cannot receive the handle closing event, epoll_wait stops responding, and the process does not exit.

      • Do not run the isula exec command in the background. Otherwise, the system may be suspended.

        Run the isula exec command in the background as follows:

        Run the isula exec script & command in the background, for example, isula exec container_name script &,isula exec. The command is executed in the background. The script continuously displays a file by running the cat command. Normally, there is output on the current terminal. If you press Enter on the current terminal, the client exits the stdout read operation due to the I/O read failure. As a result, the terminal does not output data. The server continues to write data to the buffer of the FIFO because the process is still displaying files by running the cat command. When the buffer is full, the process in the container is suspended in the write operation.

      • When a lightweight container uses the exec command to execute commands with pipe operations, you are advised to run the /bin/bash -c command.

        Typical application scenarios:

        Run the isula exec container_name -it ls /test | grep "xx" | wc -l command to count the number of xx files in the test directory. The output is processed by grep and wc through the pipe because ls /test is executed with exec. The output of ls /test executed by exec contains line breaks. When the output is processed, the result is incorrect.

        Cause: Run the ls /test command using exec. The command output contains a line feed character. Run the**| grep "xx" | wc -l** command for the output. The processing result is 2 (two lines).

        # isula exec  -it container ls /test
        xx    xx10  xx12  xx14  xx3   xx5   xx7   xx9
        xx1   xx11  xx13  xx2   xx4   xx6   xx8
        #
        

        Suggestion: When running the run/exec command to perform pipe operations, run the /bin/bash -c command to perform pipe operations in the container.

        # isula exec  -it container  /bin/sh -c "ls /test | grep "xx" | wc -l"
        15
        #
        
      • Do not use the echo option to input data to the standard input of the exec command. Otherwise, the client will be suspended. The echo value should be directly transferred to the container as a command line parameter.

        # echo ls | isula exec 38 /bin/sh
        
        
        ^C
        #
        

        The client is suspended when the preceding command is executed because the preceding command is equivalent to input ls to stdin. Then EOF is read and the client does not send data and waits for the server to exit. However, the server cannot determine whether the client needs to continue sending data. As a result, the server is suspended in reading data, and both parties are suspended.

        The correct execution method is as follows:

        # isula exec 38 ls
        bin   dev   etc   home  proc  root  sys   tmp   usr   var
        

      Example

      Run the echo command in a running container.

      # isula exec c75284634bee echo "hello,world"
      hello,world
      

      Querying Information About a Single Container

      Description

      To query information about a single container, run the isula inspect command.

      Usage

      isula inspect [OPTIONS] CONTAINER|IMAGE [CONTAINER|IMAGE...]
      

      Parameters

      The following table lists the parameters supported by the inspect command.

      Table 1 Parameter description

      Command

      Parameter

      Description

      inspect

        

      -H, --host

      Specifies the iSulad socket file path to be accessed.

      -D, --debug

      Enables the debug mode.

      --help

      Prints help information.

      -f, --format

      Output format.

      -t, --time

      Timeout interval, in seconds. If the inspect command fails to query container information within the specified period, the system stops waiting and reports an error immediately. The default value is 120s. If the value is less than or equal to 0, the inspect command keeps waiting until the container information is obtained successfully.

      Example

      Query information about a container.

      # isula inspect -f '{{.State.Status} {{.State.Running}}' c75284634bee
      running
      true
      
      
      # isula inspect c75284634bee
      [
          {
              "Id": "c75284634beeede3ab86c828790b439d16b6ed8a537550456b1f94eb852c1c0a",
              "Created": "2019-08-01T22:48:13.993304927-04:00",
              "Path": "sh",
              "Args": [],
              "State": {
                  "Status": "running",
                  "Running": true,
                  "Paused": false,
                  "Restarting": false,
                  "Pid": 21164,
                  "ExitCode": 0,
                  "Error": "",
                  "StartedAt": "2019-08-02T06:09:25.535049168-04:00",
                  "FinishedAt": "2019-08-02T04:28:09.479766839-04:00",
                  "Health": {
                      "Status": "",
                      "FailingStreak": 0,
                      "Log": []
                  }
              },
              "Image": "busybox",
              "ResolvConfPath": "",
              "HostnamePath": "",
              "HostsPath": "",
              "LogPath": "none",
              "Name": "c75284634beeede3ab86c828790b439d16b6ed8a537550456b1f94eb852c1c0a",
              "RestartCount": 0,
              "HostConfig": {
                  "Binds": [],
                  "NetworkMode": "",
                  "GroupAdd": [],
                  "IpcMode": "",
                  "PidMode": "",
                  "Privileged": false,
                  "SystemContainer": false,
                  "NsChangeFiles": [],
                  "UserRemap": "",
                  "ShmSize": 67108864,
                  "AutoRemove": false,
                  "AutoRemoveBak": false,
                  "ReadonlyRootfs": false,
                  "UTSMode": "",
                  "UsernsMode": "",
                  "Sysctls": {},
                  "Runtime": "runc",
                  "RestartPolicy": {
                      "Name": "no",
                      "MaximumRetryCount": 0
                  },
                  "CapAdd": [],
                  "CapDrop": [],
                  "Dns": [],
                  "DnsOptions": [],
                  "DnsSearch": [],
                  "ExtraHosts": [],
                  "HookSpec": "",
                  "CPUShares": 0,
                  "Memory": 0,
                  "OomScoreAdj": 0,
                  "BlkioWeight": 0,
                  "BlkioWeightDevice": [],
                  "CPUPeriod": 0,
                  "CPUQuota": 0,
                  "CPURealtimePeriod": 0,
                  "CPURealtimeRuntime": 0,
                  "CpusetCpus": "",
                  "CpusetMems": "",
                  "SecurityOpt": [],
                  "StorageOpt": {},
                  "KernelMemory": 0,
                  "MemoryReservation": 0,
                  "MemorySwap": 0,
                  "OomKillDisable": false,
                  "PidsLimit": 0,
                  "FilesLimit": 0,
                  "Ulimits": [],
                  "Hugetlbs": [],
                  "HostChannel": {
                      "PathOnHost": "",
                      "PathInContainer": "",
                      "Permissions": "",
                      "Size": 0
                  },
                  "EnvTargetFile": "",
                  "ExternalRootfs": ""
              },
              "Mounts": [],
              "Config": {
                  "Hostname": "localhost",
                  "User": "",
                  "Env": [
                      "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
                      "TERM=xterm",
                      "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
                  ],
                  "Tty": true,
                  "Cmd": [
                      "sh"
                  ],
                  "Entrypoint": [],
                  "Labels": {},
                  "Annotations": {
                      "log.console.file": "none",
                      "log.console.filerotate": "7",
                      "log.console.filesize": "1MB",
                      "rootfs.mount": "/var/lib/isulad/mnt/rootfs",
                      "native.umask": "secure"
                  },
                  "HealthCheck": {
                      "Test": [],
                      "Interval": 0,
                      "Timeout": 0,
                      "StartPeriod": 0,
                      "Retries": 0,
                      "ExitOnUnhealthy": false
                  }
              },
              "NetworkSettings": {
                  "IPAddress": ""
              }
          }
      ]
      

      Querying Information About All Containers

      Description

      To query information about all containers, run the isula ps command.

      Usage

      isula ps [OPTIONS]
      

      Parameters

      The following table lists the parameters supported by the ps command.

      Table 1 Parameter description

      Command

      Parameter

      Description

      ps

        

        

        

        

      -a, --all

      Displays all containers.

      -D, --debug

      Enables the debug mode.

      --help

      Prints help information.

      -H, --host

      Specifies the iSulad socket file path to be accessed.

      -q, --quiet

      Displays only the container name.

      -f, --filter

      Adds filter criteria.

      --format

      Output format.

      --no-trunc

      Do not truncate the container ID.

      Example

      Query information about all containers.

      # isula ps -a
      
      ID           IMAGE                                     STATUS  PID    COMMAND EXIT_CODE RESTART_COUNT STARTAT        FINISHAT    RUNTIME NAMES
      e84660aa059c rnd-dockerhub.huawei.com/official/busybox running 304765 "sh"    0         0             13 minutes ago -           runc     e84660aa059cafb0a77a4002e65cc9186949132b8e57b7f4d76aa22f28fde016
      # isula ps -a --format "table {{.ID}} {{.Image}}" --no-trunc
      ID                                                               IMAGE
      e84660aa059cafb0a77a4002e65cc9186949132b8e57b7f4d76aa22f28fde016 rnd-dockerhub.huawei.com/official/busybox
      

      Restarting a Container

      Description

      To restart one or more containers, run the isula restart command.

      Usage

      isula restart [OPTIONS] CONTAINER [CONTAINER...]
      

      Parameters

      The following table lists the parameters supported by the restart command.

      Table 1 Parameter description

      Command

      Parameter

      Description

      restart

      -H, --host

      Specifies the iSulad socket file path to be accessed.

      -D, --debug

      Enables the debug mode.

      --help

      Prints help information.

      -t, --time

      Time for graceful stop. If the time exceeds the value of this parameter, the container is forcibly stopped.

      Constraints

      • If the t parameter is specified and the value of t is less than 0, ensure that the application in the container can process the stop signal.

        The restart command first calls the stop command to stop the container. Send the SIGTERM signal to the container, and then wait for a period of time (t entered by the user). If the container is still running after the period of time, the SIGKILL signal is sent to forcibly kill the container.

      • The meaning of the input parameter t is as follows:

        t < 0: Wait for graceful stop. This setting is preferred when users are assured that their applications have a proper stop signal processing mechanism.

        t = 0: Do not wait and send kill -9 to the container immediately.

        t > 0: Wait for a specified period and send kill -9 to the container if the container does not stop within the specified period.

        Therefore, if t is set to a value less than 0 (for example, t = -1), ensure that the container application correctly processes the SIGTERM signal. If the container ignores this signal, the container will be suspended when the isula stop command is run.

      Example

      Restart a container.

      # isula restart c75284634beeede3ab86c828790b439d16b6ed8a537550456b1f94eb852c1c0a
       c75284634beeede3ab86c828790b439d16b6ed8a537550456b1f94eb852c1c0a
      

      Waiting for a Container to Exit

      Description

      To wait for one or more containers to exit, run the isula wait command. Only containers whose runtime is of the LCR type are supported.

      Usage

      isula wait [OPTIONS] CONTAINER [CONTAINER...]
      

      Parameters

      The following table lists the parameters supported by the wait command.

      Table 1 Parameter description

      Command

      Parameter

      Description

      wait

      -H, --host

      Specifies the iSulad socket file path to be accessed.

      -D, --debug

      Enables the debug mode.

      --help

      Prints help information.

      Example

      Wait for a single container to exit.

      $ isula wait c75284634beeede3ab86c828790b439d16b6ed8a537550456b1f94eb852c1c0a
       137
      

      Viewing Process Information in a Container

      Description

      To view process information in a container, run the isula top command. Only containers whose runtime is of the LCR type are supported.

      Usage

      isula top [OPTIONS] container [ps options]
      

      Parameters

      The following table lists the parameters supported by the top command.

      Table 1 Parameter description

      Command

      Parameter

      Description

      top

        

      -H, --host

      Specifies the iSulad socket file path to be accessed.

      -D, --debug

      Enables the debug mode.

      --help

      Prints help information.

      Example

      Query process information in a container.

      # isula top 21fac8bb9ea8e0be4313c8acea765c8b4798b7d06e043bbab99fc20efa72629c
      UID        PID  PPID  C STIME TTY          TIME CMD
      root     22166 22163  0 23:04 pts/1    00:00:00 sh
      

      Displaying Resource Usage Statistics of a Container

      Description

      To display resource usage statistics in real time, run the isula stats command. Only containers whose runtime is of the LCR type are supported.

      Usage

      isula stats [OPTIONS] [CONTAINER...]
      

      Parameters

      The following table lists the parameters supported by the stats command.

      Table 1 Parameter description

      Command

      Parameter

      Description

      stats

        

        

      -H, --host

      Specifies the iSulad socket file path to be accessed.

      -D, --debug

      Enables the debug mode.

      --help

      Prints help information.

      -a, --all

      Displays all containers. (By default, only running containers are displayed.)

      --no-stream

      Display the first result only. Only statistics in non-stream mode are displayed.

      --original

      Displays the original data of the container without statistics calculation.

      Example

      Display resource usage statistics.

      # isula stats --no-stream 21fac8bb9ea8e0be4313c8acea765c8b4798b7d06e043bbab99fc20efa72629c                                                                                 CONTAINER        CPU %      MEM USAGE / LIMIT          MEM %      BLOCK I / O                PIDS
      21fac8bb9ea8     0.00       56.00 KiB / 7.45 GiB       0.00       0.00 B / 0.00 B            1
      

      Obtaining Container Logs

      Description

      To obtain container logs, run the isula logs command.

      Usage

      isula logs [OPTIONS] [CONTAINER...]
      

      Parameters

      The following table lists the parameters supported by the logs command.

      Table 1 Parameter description

      Command

      Parameter

      Description

      logs

        

      -H, --host

      Specifies the iSulad socket file path to be accessed.

      -D, --debug

      Enables the debug mode.

      --help

      Prints help information.

      -f, --follow

      Traces log output.

      --tail

      Displays the number of log records.

      -t, --timestamps

      Displays the timestamp.

      Constraints

      • By default, the container log function is enabled. To disable this function, run the isula create --log-opt disable-log=true or isula run --log-opt disable-log=true command.

      Example

      Obtain container logs.

      # isula logs 6a144695f5dae81e22700a8a78fac28b19f8bf40e8827568b3329c7d4f742406
      hello, world
      hello, world
      hello, world
      

      Copying Data Between a Container and a Host

      Description

      To copy data between a host and a container, run the isula cp command. Only containers whose runtime is of the LCR type are supported.

      Usage

      isula cp [OPTIONS] CONTAINER:SRC_PATH DEST_PATH
      isula cp [OPTIONS] SRC_PATH CONTAINER:DEST_PATH
      

      Parameters

      The following table lists the parameters supported by the cp command.

      Table 1 Parameter description

      Command

      Parameter

      Description

      cp

      -H, --host

      Specifies the iSulad socket file path to be accessed.

      -D, --debug

      Enables the debug mode.

      --help

      Prints help information.

      Constraints

      • When iSulad copies files, note that the /etc/hostname, /etc/resolv.conf, and /etc/hosts files are not mounted to the host, neither the --volume and --mount parameters. Therefore, the original files in the image instead of the files in the real container are copied.

        # isula cp b330e9be717a:/etc/hostname /tmp/hostname
        # cat /tmp/hostname
        #
        
      • When decompressing a file, iSulad does not check the type of the file or folder to be overwritten in the file system. Instead, iSulad directly overwrites the file or folder. Therefore, if the source is a folder, the file with the same name is forcibly overwritten as a folder. If the source file is a file, the folder with the same name will be forcibly overwritten as a file.

        # rm -rf /tmp/test_file_to_dir && mkdir /tmp/test_file_to_dir
        # isula exec b330e9be717a /bin/sh -c "rm -rf /tmp/test_file_to_dir && touch /tmp/test_file_to_dir"
        # isula cp b330e9be717a:/tmp/test_file_to_dir /tmp
        # ls -al /tmp | grep test_file_to_dir
        -rw-r-----    1 root     root             0 Apr 26 09:59 test_file_to_dir
        
      • The cp command is used only for maintenance and fault locating. Do not use the cp command in the production environment.

      Example

      Copy the /test/host directory on the host to the /test directory on container 21fac8bb9ea8.

      isula cp /test/host 21fac8bb9ea8:/test
      

      Copy the /www directory on container 21fac8bb9ea8 to the /tmp directory on the host.

      isula cp 21fac8bb9ea8:/www /tmp/
      

      Pausing All Processes in a Container

      Description

      The isula pause command is used to pause all processes in one or more containers.

      Usage

      isula pause [OPTIONS] CONTAINER [CONTAINER...]
      

      Parameters

      Command

      Parameter

      Description

      pause

      -H, --host

      Specifies the iSulad socket file path to be accessed.

      -D, --debug

      Enables the debug mode.

      --help

      Prints help information.

      Constraints

      • Only containers in the running state can be paused.
      • After a container is paused, other lifecycle management operations (such as restart, exec, attach, kill, stop, and rm) cannot be performed.
      • After a container with health check configurations is paused, the container status changes to unhealthy.

      Example

      Pause a running container.

      # isula pause 8fe25506fb5883b74c2457f453a960d1ae27a24ee45cdd78fb7426d2022a8bac
       8fe25506fb5883b74c2457f453a960d1ae27a24ee45cdd78fb7426d2022a8bac
      

      Resuming All Processes in a Container

      Description

      The isula unpause command is used to resume all processes in one or more containers. It is a reversible process of isula pause.

      Usage

      isula unpause [OPTIONS] CONTAINER [CONTAINER...]
      

      Parameters

      Command

      Parameter

      Description

      pause

      -H, --host

      Specifies the iSulad socket file path to be accessed.

      -D, --debug

      Enables the debug mode.

      --help

      Prints help information.

      Constraints

      • Only containers in the paused state can be unpaused.

      Example

      Resume a paused container.

      # isula unpause 8fe25506fb5883b74c2457f453a960d1ae27a24ee45cdd78fb7426d2022a8bac
       8fe25506fb5883b74c2457f453a960d1ae27a24ee45cdd78fb7426d2022a8bac
      

      Obtaining Event Messages from the Server in Real Time

      Description

      The isula events command is used to obtain real-time events from the server.

      Usage

      isula events [OPTIONS]
      

      Parameter

      Command

      Parameter

      Description

      events

      -H, --host

      Specifies the iSulad socket file path to be accessed.

      -D, --debug

      Enables the debug mode.

      --help

      Prints help information.

      -n, --name

      Obtains event messages of a specified container.

      -S, --since

      Obtains event messages generated since a specified time.

      -U, --until

      Obtains the event at the specified time point.

      Constraints

      • Support container-related events: create, start, restart, stop, exec_create, exec_die, attach, kill, top, rename, archive-path, extract-to-dir, update, pause, unpause, export, and resize.
      • Supported image-related events: load, remove, pull, login, and logout.

      Example

      Run the following command to obtain event messages from the server in real time:

      # isula events
      

      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备份