Long-Term Supported Versions

    Innovation Versions

      Dynamically Managing Container Resources (syscontainer-tools)

      Resources in common containers cannot be managed. For example, a block device cannot be added to a common container, and a physical or virtual NIC cannot be inserted to a common container. In the system container scenario, the syscontainer-tools can be used to dynamically mount or unmount block devices, network devices, routes, and volumes for containers.

      To use this function, you need to install the syscontainer-tools first.

      [root@localhost ~]# yum install syscontainer-tools
      

      Device Management

      Function Description

      isulad-tools allows you to add block devices (such as disks and logical volume managers) or character devices (such as GPUs, binners, and FUSEs) on the host to a container. The devices can be used in the container. For example, you can run the fdisk command to format the disk and write data to the file system. If the devices are not required, isulad-tools allows you to delete them from the container and return them to the host.

      Command Format

      isulad-tools [COMMAND][OPTIONS] <container_id> [ARG...]
      

      In the preceding format:

      COMMAND: command related to device management.

      OPTIONS: option supported by the device management command.

      container_id: container ID.

      ARG: parameter corresponding to the command.

      Parameter Description

      Command

      Function Description

      Option Description

      Parameter Description

      add-device

      Adds block devices or character devices on the host to a container.

      Supported options are as follows:

      • --blkio-weight-device: sets the I/O weight (relative weight, ranging from 10 to 100) of a block device.
      • --device-read-bps: sets the read rate limit for the block device (byte/s).
      • --device-read-iops: sets the read rate limit for the block device (I/O/s).
      • --device-write-bps: sets the write rate limit for the block device (byte/s).
      • --device-write-iops: sets the write rate limit for the block device (I/O/s).
      • --follow-partition: If a block device is a basic block device (primary SCSI block disk), set this parameter to add all partitions of the primary disk.
      • --force: If any block device or character device already exists in the container, use this parameter to overwrite the old block device or character device files.
      • --update-config-only: updates configuration files only and does not add disks.

      Parameter format: hostdevice[:containerdevice][:permission] [hostdevice[:containerdevice][:permission]]

      In the preceding format:

      hostdevice: path on the host for storing a device.

      containerdevice: path on the container for storing a device.

      permission: operation permission on a device within the container.

      remove-device

      Deletes block devices or character devices from a container and restores them to the host.

      Supported options are as follows:

      --follow-partition: If a block device is a basic block device (primary SCSI block disk), set this parameter to delete all partitions of the primary disk in the container, and restore them to the host.

      Parameter format: hostdevice[:containerdevice] [hostdevice[:containerdevice]]

      In the preceding format:

      hostdevice: path on the host for storing a device.

      containerdevice: path on the container for storing a device.

      list-device

      Lists all block devices or character devices in a container.

      Supported options are as follows:

      • --pretty: outputs data in JSON format.
      • --sub-partition: For a primary disk, add this flag to display the primary disk and its sub-partitions.

      None

      update-device

      Updates the disk QoS.

      Supported options are as follows:

      • --device-read-bps: sets the read rate limit for the block device (byte/s). You are advised to set this parameter to a value greater than or equal to 1024.
      • --device-read-iops: sets the read rate limit for the block device (I/O/s).
      • --device-write-bps: sets the write rate limit for the block device (byte/s). You are advised to set this parameter to a value greater than or equal to 1024.
      • --device-write-iops: sets the write rate limit for the block device (I/O/s).

      None

      Constraints

      • You can add or delete devices when container instances are not running. After the operation is complete, you can start the container to view the device status. You can also dynamically add a device when the container is running.
      • Do not concurrently run the fdisk command to format disks in a container and on the host. Otherwise, the container disk usage will be affected.
      • When you run the add-device command to add a disk to a specific directory of a container, if the parent directory in the container is a multi-level directory (for example, /dev/a/b/c/d/e) and the directory level does not exist, isulad-tools will automatically create the corresponding directory in the container. When the disk is deleted, the created parent directory is not deleted. If you run the add-device command to add a device to this parent directory again, a message is displayed, indicating that a device already exists and cannot be added.
      • When you run the** add-device** command to add a disk or update disk parameters, you need to configure the disk QoS. Do not set the write or read rate limit for the block device (I/O/s or byte/s) to a small value. If the value is too small, the disk may be unreadable (the actual reason is the speed is too slow), affecting service functions.
      • When you run the --blkio-weight-device command to limit the weight of a specified block device, if the block device supports only the BFQ mode, an error may be reported, prompting you to check whether the current OS environment supports setting the weight of the BFQ block device.

      Example

      • Start a system container, and set hook spec to the isulad hook execution script.

        [root@localhost ~]# isula run -tid --hook-spec /etc/isulad-tools/hookspec.json --system-container --external-rootfs /root/root-fs none init
        eed1096c8c7a0eca6d92b1b3bc3dd59a2a2adf4ce44f18f5372408ced88f8350
        
      • Add a block device to a container.

        [root@localhost ~]# isulad-tools add-device ee /dev/sdb:/dev/sdb123
        Add device (/dev/sdb) to container(ee,/dev/sdb123) done.
        [root@localhost ~]# isula exec ee fdisk -l /dev/sdb123
        Disk /dev/sdb123: 50 GiB, 53687091200 bytes, 104857600 sectors
        Units: sectors of 1 * 512 = 512 bytes
        Sector size (logical/physical): 512 bytes / 512 bytes
        I/O size (minimum/optimal): 512 bytes / 512 bytes
        Disklabel type: dos
        Disk identifier: 0xda58a448
        
        Device        Boot Start       End   Sectors Size Id Type
        /dev/sdb123p1       2048 104857599 104855552  50G  5 Extended
        /dev/sdb123p5       4096 104857599 104853504  50G 83 Linux
        
      • Update the device information.

        [root@localhost ~]# isulad-tools update-device --device-read-bps /dev/sdb:10m ee
        Update read bps for device (/dev/sdb,10485760) done.
        
      • Delete a device.

        [root@localhost ~]# isulad-tools remove-device ee /dev/sdb:/dev/sdb123
        Remove device (/dev/sdb) from container(ee,/dev/sdb123) done.
        Remove read bps for device (/dev/sdb) done.
        

      NIC Management

      Function Description

      isulad-tools allows you to insert physical or virtual NICs on the host to a container. If the NICs are not required, isulad-tools allows you to delete them from the container and return them to the host. In addition, the NIC configurations can be dynamically modified. To insert a physical NIC, add the NIC on the host to the container. To insert a virtual NIC, create a veth pair and insert its one end to the container.

      Command Format

      isulad-tools [COMMAND][OPTIONS] <container_id>
      

      In the preceding format:

      COMMAND: command related to NIC management.

      OPTIONS: option supported by the NIC management command.

      container_id: container ID.

      Parameter Description

      Command

      Function Description

      Option Description

      add-nic

      Creates an NIC for a container.

      Supported options are as follows:

      • --type: specifies the NIC type. Only eth and veth are supported.
      • --name: specifies the NIC name. The format is [host:]container. If host is not specified, a random value is used.
      • --ip: specifies the NIC IP address.
      • --mac: specifies the NIC MAC address.
      • --bridge: specifies the network bridge bound to the NIC.
      • --mtu: specifies the MTU value of the NIC. The default value is 1500.
      • --update-config-only: If this flag is set, only configuration files are updated and NICs are not added.
      • --qlen: specifies the value of QLEN. The default value is 1000.

      remove-nic

      Deletes NICs from a container and restores them to the host.

      Supported options are as follows:

      • --type: specifies the NIC type.
      • --name: specifies the name of the NIC. The format is [host:]container.

      list-nic

      Lists all NICs in a container.

      Supported options are as follows:

      • --pretty: outputs data in JSON format.
      • --filter: outputs filtered data in the specific format, for example, --filter' {"ip":"192.168.3.4/24", "Mtu":1500}'.

      update-nic

      Modifies configuration parameters of a specified NIC in a container.

      Supported options are as follows:

      • --name: specifies the name of the NIC in the container. This parameter is mandatory.
      • --ip: specifies the NIC IP address.
      • --mac: specifies the NIC MAC address.
      • --bridge: specifies the network bridge bound to the NIC.
      • --mtu: specifies the MTU value of the NIC.
      • --update-config-only: If this flag is set, configuration files are updated and NICs are not updated.
      • --qlen: specifies the value of QLEN.

      Constraints

      • Physical NICs (eth) and virtual NICs (veth) can be added.
      • When adding a NIC, you can also configure the NIC. The configuration parameters include --ip, --mac, --bridge, --mtu, --qlen.
      • A maximum of eight physical NICs can be added to a container.
      • If you run the isulad-tools add-nic command to add an eth NIC to a container and do not add a hook, you must manually delete the NIC before the container exits. Otherwise, the name of the eth NIC on the host will be changed to the name of that in the container.
      • For a physical NIC (except 1822 VF NIC), use the original MAC address when running the add-nic command. Do not change the MAC address in the container, or when running the update-nic command.
      • When using the isulad-tools add-nic command, set the MTU value. The value range depends on the NIC model.
      • When using isulad-tools to add NICs and routes to containers, you are advised to run the add-nic command to add NICs and then run the add-route command to add routes. When using isulad-tools to delete NICs and routes from a container, you are advised to run the remove-route command to delete routes and then run the remove-nic command to delete NICs.
      • When using isulad-tools to add NICs, add a NIC to only one container.

      Example

      • Start a system container, and set hook spec to the isulad hook execution script.

        [root@localhost ~]# isula run -tid --hook-spec /etc/isulad-tools/hookspec.json --system-container --external-rootfs /root/root-fs none init
        2aaca5c1af7c872798dac1a468528a2ccbaf20b39b73fc0201636936a3c32aa8
        
      • Add a virtual NIC to a container.

        [root@localhost ~]# isulad-tools add-nic --type "veth" --name abc2:bcd2 --ip 172.17.28.5/24 --mac 00:ff:48:13:xx:xx --bridge docker0 2aaca5c1af7c
        Add network interface to container 2aaca5c1af7c (bcd2,abc2) done  
        
      • Add a physical NIC to a container.

        [root@localhost ~]# isulad-tools add-nic --type "eth" --name eth3:eth1 --ip 172.17.28.6/24  --mtu 1300  --qlen 2100 2aaca5c1af7c
        Add network interface to container 2aaca5c1af7c (eth3,eth1) done
        

        NOTE:
        When adding a virtual or physical NIC, ensure that the NIC is in the idle state. Adding a NIC in use will disconnect the system network.

      Route Management

      Function Description

      isulad-tools can be used to dynamically add or delete routing tables for system containers.

      Command Format

      isulad-tools [COMMAND][OPTIONS] <container_id> [ARG...]
      

      In the preceding format:

      COMMAND: command related to route management.

      OPTIONS: option supported by the route management command.

      container_id: container ID.

      ARG: parameter corresponding to the command.

      API Description

      Command

      Function Description

      Option Description

      Parameter Description

      add-route

      Adds the network routing rules to a container.

      Supported options are as follows:

      --update-config-only: If this parameter is configured, configuration files are updated and routing tables are not updated.

      Parameter format: [{rule1},{rule2}]

      Example of rule:

      '[{"dest":"default", "gw":"192.168.10.1"},{"dest":"192.168.0.0/16","dev":"eth0","src":"192.168.1.2"}]'

      • dest: target network. If this parameter is left blank, the default gateway is used.
      • src: source IP address of a route.
      • gw: route gateway.
      • dev: network device.

      remove-route

      Deletes a route from a container.

      Supported options are as follows:

      --update-config-only: If this parameter is configured, only configuration files are updated and routes are not deleted from the container.

      Parameter format: [{rule1},{rule2}]

      Example of rule:

      '[{"dest":"default", "gw":"192.168.10.1"},{"dest":"192.168.0.0/16","dev":"eth0","src":"192.168.1.2"}]'

      • dest: target network. If this parameter is left blank, the default gateway is used.
      • src: source IP address of a route.
      • gw: route gateway.
      • dev: network device.

      list-route

      Lists all routing rules in a container.

      Supported options are as follows:

      • --pretty: outputs data in JSON format.
      • --filter: outputs filtered data in the specific format, for example, --filter' {"ip":"192.168.3.4/24", "Mtu":1500}'.

      None

      Constraints

      • When using isulad-tools to add NICs and routes to containers, you are advised to run the add-nic command to add NICs and then run the add-route command to add routes. When using isulad-tools to delete NICs and routes from a container, you are advised to run the remove-route command to delete routes and then run the remove-nic command to delete NICs.
      • When adding a routing rule to a container, ensure that the added routing rule does not conflict with existing routing rules in the container.

      Example

      • Start a system container, and set hook spec to the isulad hook execution script.

        [root@localhost ~]# isula run -tid --hook-spec /etc/isulad-tools/hookspec.json --system-container --external-rootfs /root/root-fs none init
        0d2d68b45aa0c1b8eaf890c06ab2d008eb8c5d91e78b1f8fe4d37b86fd2c190b
        
      • Use isulad-tools to add a physical NIC to the system container.

        [root@localhost ~]# isulad-tools add-nic --type "eth" --name enp4s0:eth123 --ip 172.17.28.6/24  --mtu 1300  --qlen 2100 0d2d68b45aa0
        Add network interface (enp4s0) to container (0d2d68b45aa0,eth123) done
        
      • isulad-tools adds a routing rule to the system container. Format example: [{"dest":"default", "gw":"192.168.10.1"},{"dest":"192.168.0.0/16","dev":"eth0","src":"192.168.1.2"}]. If dest is left blank, its value will be default.

        [root@localhost ~]# isulad-tools add-route 0d2d68b45aa0 '[{"dest":"172.17.28.0/32", "gw":"172.17.28.5","dev":"eth123"}]'
        Add route to container 0d2d68b45aa0, route: {dest:172.17.28.0/32,src:,gw:172.17.28.5,dev:eth123} done
        
      • Check whether a routing rule is added in the container.

        [root@localhost ~]# isula exec -it 0d2d68b45aa0 route
        Kernel IP routing table
        Destination     Gateway         Genmask         Flags Metric Ref    Use Iface
        172.17.28.0     172.17.28.5     255.255.255.255 UGH   0      0        0 eth123
        172.17.28.0     0.0.0.0         255.255.255.0   U     0      0        0 eth123
        

      Volume Mounting Management

      Function Description

      In a common container, you can set the --volume parameter during container creation to mount directories or volumes of the host to the container for resource sharing. However, during container running, you cannot unmount directories or volumes that are mounted to the container, or mount directories or volumes of the host to the container. Only the system container can use the isulad-tools tool to dynamically mount directories or volumes of the host to the container and unmount directories or volumes from the container.

      Command Format

      isulad-tools [COMMAND][OPTIONS] <container_id> [ARG...]
      

      In the preceding format:

      COMMAND: command related to route management.

      OPTIONS: option supported by the route management command.

      container_id: container ID.

      ARG: parameter corresponding to the command.

      API Description

      Table 1   

      Command

      Function Description

      Option Description

      Parameter Description

      add-path

      Adds files or directories on the host to a container.

      None

      The parameter format is as follows:

      hostpath:containerpath:permission [hostpath:containerpath:permission ...]

      In the preceding format:

      hostpath: path on the host for storing a volume.

      containerpath: path on the container for storing a volume.

      permission: operation permission on a mount path within the container.

      remove-path

      Deletes directories or files from the container and restores them to the host.

      None

      Parameter format: hostpath:containerpath[hostpath:containerpath ]

      In the preceding format:

      hostpath: path on the host for storing a volume.

      containerpath: path on the container for storing a volume.

      list-path

      Lists all path directories in a container.

      Supported options are as follows:

      --pretty: outputs data in JSON format.

      None

      Constraints

      • When running the add-path command, specify an absolute path as the mount path.
      • The mount point /.sharedpath is generated on the host after the mount path is specified by running the add-path command.
      • A maximum of 128 volumes can be added to a container.
      • Do not overwrite the root directory (/) in a container with the host directory by running the add-path command. Otherwise, the function is affected.

      Example

      • Start a system container, and set hook spec to the isulad hook execution script.

        [root@localhost ~]# isula run -tid --hook-spec /etc/isulad-tools/hookspec.json --system-container --external-rootfs /root/root-fs none init
        e45970a522d1ea0e9cfe382c2b868d92e7b6a55be1dd239947dda1ee55f3c7f7
        
      • Use isulad-tools to mount a directory on the host to a container, implementing resource sharing.

        [root@localhost ~]# isulad-tools add-path e45970a522d1 /home/test123:/home/test123
        Add path (/home/test123) to container(e45970a522d1,/home/test123) done.
        
      • Create a file in the /home/test123 directory on the host and check whether the file can be accessed in the container.

        [root@localhost ~]# echo "hello world" > /home/test123/helloworld
        [root@localhost ~]# isula exec e45970a522d1 bash
        [root@localhost /]# cat /home/test123/helloworld
        hello world
        
      • Use isulad-tools to delete the mount directory from the container.

        [root@localhost ~]# isulad-tools remove-path e45970a522d1 /home/test123:/home/test123
        Remove path (/home/test123) from container(e45970a522d1,/home/test123) done
        [root@localhost ~]# isula exec e45970a522d1 bash
        [root@localhost /]# ls /home/test123/helloworld
        ls: cannot access '/home/test123/helloworld': No such file or directory
        

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