安装与配置
本章介绍iSulad的安装、安装后配置，以及升级和卸载的方法。
说明
iSulad的安装、升级、卸载均需要使用root权限。
安装方法
iSulad可以通过yum或rpm命令两种方式安装，由于yum会自动安装依赖，而rpm命令需要手动安装所有依赖，所以推荐使用yum安装。
这里给出两种安装方式的操作方法。
（推荐）使用yum安装iSulad，参考命令如下：
bash# sudo yum install -y iSulad使用rpm安装iSulad，需要下载iSulad及其所有依赖的RPM包，然后手动安装。安装单个iSulad的RPM包（依赖包安装方式相同），参考命令如下：
bash# sudo rpm -ihv iSulad-xx.xx.xx-xx.xxx.aarch64.rpm
配置方法
iSulad 安装完成后，可以根据需要进行相关配置。
配置方式
轻量级容器引擎（iSulad）服务端daemon为isulad，isulad可以通过配置文件进行配置，也可以通过命令行的方式进行配置，例如：isulad --xxx，优先级从高到低是：命令行方式>配置文件>代码中默认配置。
说明
如果采用systemd管理iSulad进程，修改/etc/sysconfig/iSulad文件中的OPTIONS字段，等同于命令行方式进行配置。
命令行方式
在启动服务的时候，直接通过命令行进行配置。其配置选项可通过以下命令查阅：
bash# isulad --help isulad lightweight container runtime daemon Usage: isulad [global options] GLOBAL OPTIONS: --authorization-plugin Use authorization plugin --cgroup-parent Set parent cgroup for all containers --cni-bin-dir The full path of the directory in which to search for CNI plugin binaries. Default: /opt/cni/bin --cni-conf-dir The full path of the directory in which to search for CNI config files. Default: /etc/cni/net.d --container-log-driver Set default container log driver, such as: json-file --container-log-opts Set default container log driver options, such as: max-file=7 to set max number of container log files --default-ulimit Default ulimits for containers (default []) -e, --engine Select backend engine -g, --graph Root directory of the iSulad runtime -G, --group Group for the unix socket(default is isulad) --help Show help --hook-spec Default hook spec file applied to all containers -H, --host The socket name used to create gRPC server --image-layer-check Check layer integrity when needed --insecure-registry Disable TLS verification for the given registry --insecure-skip-verify-enforce Force to skip the insecure verify(default false) --log-driver Set daemon log driver, such as: file -l, --log-level Set log level, the levels can be: FATAL ALERT CRIT ERROR WARN NOTICE INFO DEBUG TRACE --log-opt Set daemon log driver options, such as: log-path=/tmp/logs/ to set directory where to store daemon logs --native.umask Default file mode creation mask (umask) for containers --network-plugin Set network plugin, default is null, support null and cni -p, --pidfile Save pid into this file --pod-sandbox-image The image whose network/ipc namespaces containers in each pod will use. (default "pause-${machine}:3.0") --registry-mirrors Registry to be prepended when pulling unqualified images, can be specified multiple times --selinux-enabled Enable selinux support --start-timeout timeout duration for waiting on a container to start before it is killed -S, --state Root directory for execution state files --storage-driver Storage driver to use(default overlay2) -s, --storage-opt Storage driver options --tls Use TLS; implied by --tlsverify --tlscacert Trust certs signed only by this CA (default "/root/.iSulad/ca.pem") --tlscert Path to TLS certificate file (default "/root/.iSulad/cert.pem") --tlskey Path to TLS key file (default "/root/.iSulad/key.pem") --tlsverify Use TLS and verify the remote --use-decrypted-key Use decrypted private key by default(default true) --userns-remap User/Group setting for user namespaces -V, --version Print the version --websocket-server-listening-port CRI websocket streaming service listening port (default 10350)示例： 启动isulad，并将日志级别调整成DEBUG
bash# isulad -l DEBUG配置文件方式
isulad配置文件为/etc/isulad/daemon.json和/etc/isulad/daemon_constants.json，各配置字段说明如下：
配置文件/etc/isulad/daemon.json
配置文件/etc/isulad/daemon_constants.json
"docker.io": "registry-1.docker.io",
示例：
bash# cat /etc/isulad/daemon.json { "group": "isulad", "default-runtime": "lcr", "graph": "/var/lib/isulad", "state": "/var/run/isulad", "engine": "lcr", "log-level": "ERROR", "pidfile": "/var/run/isulad.pid", "log-opts": { "log-file-mode": "0600", "log-path": "/var/lib/isulad", "max-file": "1", "max-size": "30KB" }, "log-driver": "stdout", "hook-spec": "/etc/default/isulad/hooks/default.json", "start-timeout": "2m", "storage-driver": "overlay2", "storage-opts": [ "overlay2.override_kernel_check=true" ], "registry-mirrors": [ "docker.io" ], "insecure-registries": [ "rnd-dockerhub.huawei.com" ], "pod-sandbox-image": "", "native.umask": "secure", "network-plugin": "", "cni-bin-dir": "", "cni-conf-dir": "", "image-layer-check": false, "use-decrypted-key": true, "insecure-skip-verify-enforce": false, "cri-runtime": { "kata": "io.containerd.kata.v2" } } # cat /etc/isulad/daemon.json { "default-host": "docker.io", "registry-transformation":{ "docker.io": "registry-1.docker.io", "index.docker.io": "registry-1.docker.io" } }须知
默认配置文件/etc/isulad/daemon.json仅供参考，请根据实际需要进行配置。
存储说明
存放isulad的OCI配置文件和钩子模板文件，文件夹下的配置文件权限设置为0640，sysmonitor检查脚本权限为0550 | ||
isulad运行的根目录，存放创建的容器配置、日志的默认路径、数据库文件、mount点等 |
约束限制
高并发场景（并发启动200容器）下，glibc的内存管理机制会导致内存空洞以及虚拟内存较大（例如10GB）的问题。该问题是高并发场景下glibc内存管理机制的限制，而不是内存泄露，不会导致内存消耗无限增大。可以通过设置MALLOC_ARENA_MAX环境变量来减少虚拟内存的问题，而且可以增大减少物理内存的概率。但是这个环境变量会导致iSulad的并发性能下降，需要用户根据实际情况做配置。
参考实践情况，平衡性能和内存，可以设置MALLOC_ARENA_MAX为4。（在arm64服务器上面对iSulad的性能影响在10%以内）
配置方法：
- 手动启动iSulad的场景，可以直接export MALLOC_ARENA_MAX=4，然后再启动iSulad即可。
- systemd管理iSulad的场景，可以修改/etc/sysconfig/iSulad，增加一条MALLOC_ARENA_MAX=4即可。
为daemon指定各种运行目录时的注意事项
以--root为例，当使用/new/path/作为daemon新的Root Dir时，如果/new/path/下已经存在文件，且目录或文件名与isulad需要使用的目录或文件名冲突（例如：engines、mnt等目录）时，isulad可能会更新原有目录或文件的属性，包括属主、权限等为自己的属主和权限。
所以，用户需要明白重新指定各种运行目录和文件，会对冲突目录、文件属性的影响。建议用户指定的新目录或文件为isulad专用，避免冲突导致的文件属性变化以及带来的安全问题。
日志文件管理：
须知
日志功能对接： iSulad由systemd管理，日志也由systemd管理，然后传输给rsyslogd。rsyslog默认会对写日志速度有限制，可以通过修改/etc/rsyslog.conf文件，增加"$imjournalRatelimitInterval 0"配置项，然后重启rsyslogd的服务即可。
命令行参数解析限制
使用iSulad命令行接口时，其参数解析方式与docker略有不同，对于命令行中带参数的flag，不管使用长flag还是短flag，只会将该flag后第一个空格或与flag直接相连接的'='后的字符串作为flag的参数，具体如下：
使用短flag时，与“-”连接的字符串中的每个字符都被当作短flag（当有=号时，=号后的字符串当成=号前的短flag的参数）。
isula run -du=root busybox 等价于 isula run -du root busybox 或 isula run -d -u=root busybox 或 isula run -d -u root busybox ，当使用isula run -du:root时，由于-:不是有效的短flag，因此会报错。前述的命令行也等价于isula run -ud root busybox，但不推荐这种使用方式，可能带来语义困扰。
使用长flag时，与“--”连接的字符串作为一个整体当成长flag，若包含=号，则=号前的字符串为长flag，=号后的为参数。
bashisula run --user=root busybox等价于
bashisula run --user root busybox
启动一个isulad容器，不能够以非root用户进行isula run -i/-t/-ti以及isula attach/exec操作。
isulad的临时文件存放路径默认为/var/lib/isulad/isulad_tmpdir，如果更换了isulad的根目录，则路径为
$isulad_root/isulad_tmpdir。如果需要修改isulad存放临时文件的目录，可以通过在启动isulad前配置ISULAD_TMPDIR环境变量来实现，isulad启动时会进行检查，如果发现配置了ISULAD_TMPDIR环境变量，则会将$ISULAD_TMPDIR/isulad_tmpdir目录作为临时文件存放的路径，注意$ISULAD_TMPDIR下面的不要存放名称为isulad_tmpdir的文件/文件夹等，因为isulad启动时会递归删除$ISULAD_TMPDIR/isulad_tmpdir目录来防止数据残留。同时请确保$ISULAD_TMPDIR路径只有root用户可以访问，防止其他用户操作导致的安全问题。
DAEMON多端口的绑定
描述
daemon端可以绑定多个unix socket或者tcp端口，并在这些端口上侦听，客户端可以通过这些端口和daemon端进行交互。
接口
用户可以在/etc/isulad/daemon.json文件的hosts字段配置一个或者多个端口。当然用户也可以不指定hosts。
{
"hosts": [
"unix:///var/run/isulad.sock",
"tcp://localhost:5678",
"tcp://127.0.0.1:6789"
]
}用户也可以在/etc/sysconfig/iSulad中通过-H或者--host配置端口。用户同样可以不指定hosts。
OPTIONS='-H unix:///var/run/isulad.sock --host tcp://127.0.0.1:6789'如果用户在daemon.json文件及iSulad中均未指定hosts，则daemon在启动之后将默认侦听unix:///var/run/isulad.sock。
限制
用户不可以在/etc/isulad/daemon.json和/etc/sysconfig/iSulad两个文件中同时指定hosts，如果这样做将会出现错误，isulad无法正常启动；
textunable to configure the isulad with file /etc/isulad/daemon.json: the following directives are specified both as a flag and in the configuration file: hosts: (from flag: [unix:///var/run/isulad.sock tcp://127.0.0.1:6789], from file: [unix:///var/run/isulad.sock tcp://localhost:5678 tcp://127.0.0.1:6789])若指定的host是unix socket，则必须是合法的unix socket，需要以"unix://"开头，后跟合法的socket绝对路径；
若指定的host是tcp端口，则必须是合法的tcp端口，需要以"tcp://"开头，后跟合法的IP地址和端口，IP地址可以为localhost；
可以指定至多10个有效的端口，超过10个则会出现错误，isulad无法正常启动。
配置TLS认证与开启远程访问
描述
iSulad采用C/S模式进行设计，在默认情况，iSulad守护进程isulad只侦听本地/var/run/isulad.sock，因此只能在本地通过客户端isula执行相关命令操作容器。为了能使isula可以远程访问容器，isulad守护进程需要通过tcp:ip的方式侦听远程访问的端口。然而，仅通过简单配置tcp ip:port进行侦听，这样会导致所有的ip都可以通过调用isula -H tcp://<remote ip="" server="">:port与isulad通信，容易导致安全问题，因此推荐使用较安全版本的TLS(Transport Layer Security - 安全传输层协议）方式进行远程访问。
生成TLS证书
明文私钥和证书生成方法示例
bash#!/bin/bash set -e echo -n "Enter pass phrase:" read password echo -n "Enter public network ip:" read publicip echo -n "Enter host:" read HOST echo " => Using hostname: $publicip, You MUST connect to iSulad using this host!" mkdir -p $HOME/.iSulad cd $HOME/.iSulad rm -rf $HOME/.iSulad/* echo " => Generating CA key" openssl genrsa -passout pass:$password -aes256 -out ca-key.pem 4096 echo " => Generating CA certificate" openssl req -passin pass:$password -new -x509 -days 365 -key ca-key.pem -sha256 -out ca.pem -subj "/C=CN/ST=zhejiang/L=hangzhou/O=Huawei/OU=iSulad/CN=iSulad@huawei.com" echo " => Generating server key" openssl genrsa -passout pass:$password -out server-key.pem 4096 echo " => Generating server CSR" openssl req -passin pass:$password -subj /CN=$HOST -sha256 -new -key server-key.pem -out server.csr echo subjectAltName = DNS:$HOST,IP:$publicip,IP:127.0.0.1 >> extfile.cnf echo extendedKeyUsage = serverAuth >> extfile.cnf echo " => Signing server CSR with CA" openssl x509 -req -passin pass:$password -days 365 -sha256 -in server.csr -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out server-cert.pem -extfile extfile.cnf echo " => Generating client key" openssl genrsa -passout pass:$password -out key.pem 4096 echo " => Generating client CSR" openssl req -passin pass:$password -subj '/CN=client' -new -key key.pem -out client.csr echo " => Creating extended key usage" echo extendedKeyUsage = clientAuth > extfile-client.cnf echo " => Signing client CSR with CA" openssl x509 -req -passin pass:$password -days 365 -sha256 -in client.csr -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out cert.pem -extfile extfile-client.cnf rm -v client.csr server.csr extfile.cnf extfile-client.cnf chmod -v 0400 ca-key.pem key.pem server-key.pem chmod -v 0444 ca.pem server-cert.pem cert.pem加密私钥和证书请求文件生成方法示例
bash#!/bin/bash echo -n "Enter public network ip:" read publicip echo -n "Enter pass phrase:" read password # remove certificates from previous execution. rm -f *.pem *.srl *.csr *.cnf # generate CA private and public keys echo 01 > ca.srl openssl genrsa -aes256 -out ca-key.pem -passout pass:$password 2048 openssl req -subj '/C=CN/ST=zhejiang/L=hangzhou/O=Huawei/OU=iSulad/CN=iSulad@huawei.com' -new -x509 -days $DAYS -passin pass:$password -key ca-key.pem -out ca.pem # create a server key and certificate signing request (CSR) openssl genrsa -aes256 -out server-key.pem -passout pass:$PASS 2048 openssl req -new -key server-key.pem -out server.csr -passin pass:$password -subj '/CN=iSulad' echo subjectAltName = DNS:iSulad,IP:${publicip},IP:127.0.0.1 > extfile.cnf echo extendedKeyUsage = serverAuth >> extfile.cnf # sign the server key with our CA openssl x509 -req -days $DAYS -passin pass:$password -in server.csr -CA ca.pem -CAkey ca-key.pem -out server-cert.pem -extfile extfile.cnf # create a client key and certificate signing request (CSR) openssl genrsa -aes256 -out key.pem -passout pass:$password 2048 openssl req -subj '/CN=client' -new -key key.pem -out client.csr -passin pass:$password # create an extensions config file and sign echo extendedKeyUsage = clientAuth > extfile.cnf openssl x509 -req -days 365 -passin pass:$password -in client.csr -CA ca.pem -CAkey ca-key.pem -out cert.pem -extfile extfile.cnf # remove the passphrase from the client and server key openssl rsa -in server-key.pem -out server-key.pem -passin pass:$password openssl rsa -in key.pem -out key.pem -passin pass:$password # remove generated files that are no longer required rm -f ca-key.pem ca.srl client.csr extfile.cnf server.csr
接口
{
"tls": true,
"tls-verify": true,
"tls-config": {
"CAFile": "/root/.iSulad/ca.pem",
"CertFile": "/root/.iSulad/server-cert.pem",
"KeyFile":"/root/.iSulad/server-key.pem"
}
}限制
服务端支持的模式如下：
- 模式1（验证客户端）：tlsverify, tlscacert, tlscert, tlskey。
- 模式2（不验证客户端）：tls, tlscert, tlskey。
客户端支持的模式如下:
- 模式1(使用客户端证书进行身份验证，并根据给定的CA验证服务器)：tlsverify, tlscacert, tlscert, tlskey。
- 模式2(验证服务器)：tlsverify, tlscacert。
如果需要采用双向认证方式进行通讯，则服务端采用模式1，客户端采用模式1；
如果需要采用单向认证方式进行通讯，则服务端采用模式2，客户端采用模式2。
须知
- 采用RPM安装方式时，服务端配置可通过/etc/isulad/daemon.json以及/etc/sysconfig/iSulad配置修改。
- 相比非认证或者单向认证方式，双向认证具备更高的安全性，推荐使用双向认证的方式进行通讯。
- GRPC开源组件日志不由iSulad进行接管，如果需要查看GRPC相关日志，请按需设置GRPC_VERBOSITY和GRPC_TRACE环境变量。
示例
服务端：
isulad -H=tcp://0.0.0.0:2376 --tlsverify --tlscacert ~/.iSulad/ca.pem --tlscert ~/.iSulad/server-cert.pem --tlskey ~/.iSulad/server-key.pem客户端：
isula version -H=tcp://$HOSTIP:2376 --tlsverify --tlscacert ~/.iSulad/ca.pem --tlscert ~/.iSulad/cert.pem --tlskey ~/.iSulad/key.pem配置devicemapper存储驱动
使用devicemapper存储驱动需要先配置一个thinpool设备，而配置thinpool需要一个独立的块设备，且该设备需要有足够的空闲空间用于创建thinpool，请用户根据实际需求确定。这里假设独立块设备为/dev/xvdf，具体的配置方法如下：
一、配置thinpool
停止isulad服务。
bash# systemctl stop isulad基于块设备创建一个lvm卷。
bash# pvcreate /dev/xvdf使用刚才创建的物理卷创建一个卷组。
bash# vgcreate isula /dev/xvdf Volume group "isula" successfully created：创建名为thinpool和thinpoolmeta的两个逻辑卷。
bash# lvcreate --wipesignatures y -n thinpool isula -l 95%VG Logical volume "thinpool" created.bash# lvcreate --wipesignatures y -n thinpoolmeta isula -l 1%VG Logical volume "thinpoolmeta" created.将新创建的两个逻辑卷转换成thinpool以及thinpool所使用的metadata，这样就完成了thinpool配置。
bash# lvconvert -y --zero n -c 512K --thinpool isula/thinpool --poolmetadata isula/thinpoolmeta WARNING: Converting logical volume isula/thinpool and isula/thinpoolmeta to thin pool's data and metadata volumes with metadata wiping. THIS WILL DESTROY CONTENT OF LOGICAL VOLUME (filesystem etc.) Converted isula/thinpool to thin pool.
二、修改isulad配置文件
如果环境之前运行过isulad，请先备份之前的数据。
bash# mkdir /var/lib/isulad.bk # mv /var/lib/isulad/* /var/lib/isulad.bk修改配置文件
这里提供了两种配置方式，用户可根据实际情况的选择合适的方式。
编辑/etc/isulad/daemon.json，配置storage-driver字段值为devicemapper，并配置storage-opts字段的相关参数，支持参数请参见参数说明。配置参考如下所示：
conf{ "storage-driver": "devicemapper" "storage-opts": [ "dm.thinpooldev=/dev/mapper/isula-thinpool", "dm.fs=ext4", "dm.min_free_space=10%" ] }或者也可以通过编辑/etc/sysconfig/iSulad，在isulad启动参数里显式指定，支持参数请参见参数说明。配置参考如下所示：
confOPTIONS="--storage-driver=devicemapper --storage-opt dm.thinpooldev=/dev/mapper/isula-thinpool --storage-opt dm.fs=ext4 --storage-opt dm.min_free_space=10%"
启动isulad，使配置生效。
bash# systemctl start isulad
参数说明
storage-opts 支持的参数请参见表1。
表 1 storage-opts字段参数说明
用于指定单个容器的最大存储空间大小，单位为k/m/g/t/p，也可以使用大写字母，例如dm.basesize=50G。该参数只在首次初始化时有效。 | ||
用于指定最小的预留空间，用百分比表示。例如dm.min_free_space=10%，表示当剩余存储空间只剩10%左右时，创建容器等和存储相关操作就会失败。 |
注意事项
配置devicemapper时，如果系统上没有足够的空间给thinpool做自动扩容，请禁止自动扩容功能。
禁止自动扩容的方法是把/etc/lvm/profile/isula-thinpool.profile中thin_pool_autoextend_threshold和thin_pool_autoextend_percent两个值都改成100，如下所示：
confactivation { thin_pool_autoextend_threshold=100 thin_pool_autoextend_percent=100 }使用devicemapper时，容器文件系统必须配置为ext4，需要在isulad的配置参数中加上--storage-opt dm.fs=ext4。
当graphdriver为devicemapper时，如果metadata文件损坏且不可恢复，需要人工介入恢复。禁止直接操作或篡改daemon存储devicemapper的元数据。
使用devicemapper lvm时，异常掉电导致的devicemapper thinpool损坏，无法保证thinpool损坏后可以修复，也不能保证数据的完整性，需重建thinpool。
iSula开启了user namespace特性，切换devicemapper存储池时的注意事项
- 一般启动容器时，deviceset-metadata文件为：/var/lib/isulad/devicemapper/metadata/deviceset-metadata。
- 使用了user namespace场景下，deviceset-metadata文件使用的是：/var/lib/isulad/{userNSUID.GID}/devicemapper/metadata/deviceset-metadata。
- 使用devicemapper存储驱动，容器在user namespace场景和普通场景之间切换时，需要将对应deviceset-metadata文件中的BaseDeviceUUID内容清空；针对thinpool扩容或者重建的场景下，也同样的需要将对应deviceset-metadata文件中的BaseDeviceUUID内容清空，否则isulad服务会重启失败。