From 1c36351f8eb4fbef6e3323bba0734c69f37fc844 Mon Sep 17 00:00:00 2001 From: Lu Jingxiao Date: Fri, 11 Sep 2020 10:35:29 +0800 Subject: [PATCH] isula-build: update usage guides for isula-build Update usage guides for isula-build Signed-off-by: Lu Jingxiao --- .../Container/figures/isula-build_arch.png | Bin 0 -> 3418 bytes content/en/docs/Container/isula-build.md | 833 +++++++++ content/en/menu/index.md | 4 +- .../Container/figures/isula-build_arch.png | Bin 0 -> 3418 bytes ...04\345\273\272\345\267\245\345\205\267.md" | 1627 +++++++++-------- content/zh/menu/index.md | 2 +- 6 files changed, 1666 insertions(+), 800 deletions(-) create mode 100644 content/en/docs/Container/figures/isula-build_arch.png create mode 100755 content/en/docs/Container/isula-build.md create mode 100644 content/zh/docs/Container/figures/isula-build_arch.png diff --git a/content/en/docs/Container/figures/isula-build_arch.png b/content/en/docs/Container/figures/isula-build_arch.png new file mode 100644 index 0000000000000000000000000000000000000000..911a9ae6f46988586ab49f15de282948f5470c37 GIT binary patch literal 3418 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 F{vW4ByAS{X literal 0 HcmV?d00001 diff --git a/content/en/docs/Container/isula-build.md b/content/en/docs/Container/isula-build.md new file mode 100755 index 000000000..bbfe58432 --- /dev/null +++ b/content/en/docs/Container/isula-build.md @@ -0,0 +1,833 @@ + + + +* [Installation](#installation) + * [Preparations](#preparations) + * [Installing isula-build](#installing-isula-build) +* [Configuring and Managing the isula-build Service](#configuring-and-managing-the-isula-build-service) + * [Configuring the isula-build Service](#configuring-the-isula-build-service) + * [Managing the isula-build Service](#managing-the-isula-build-service) + * [(Recommended) Using systemd for Management](#recommended-using-systemd-for-management) + * [Directly Running isula-builder](#directly-running-isula-builder) +* [Usage Guidelines](#usage-guidelines) + * [Prerequisites](#prerequisites) + * [Overview](#overview) + * [ctr-img: Container Image Management](#ctr-img-container-image-management) + * [build: Container Image Build](#build-container-image-build) + * [image: Viewing Local Persistent Build Images](#image-viewing-local-persistent-build-images) + * [import: Importing a Basic Container Image](#import-importing-a-basic-container-image) + * [load: Importing Cascade Images](#load-importing-cascade-images) + * [rm: Deleting a Local Persistent Image](#rm-deleting-a-local-persistent-image) + * [save: Exporting Cascade Images](#save-exporting-cascade-images) + * [tag: Tagging Local Persistent Images](#tag-tagging-local-persistent-images) + * [info: Viewing the Operating Environment and System Information](#info-viewing-the-operating-environment-and-system-information) + * [login: Logging In to the Remote Image Repository](#login-logging-in-to-the-remote-image-repository) + * [logout: Logging Out of the Remote Image Repository](#logout-logging-out-of-the-remote-image-repository) + * [version: Querying the isula-build Version](#version-querying-the-isula-build-version) +* [Directly Integrating a Container Engine](#directly-integrating-a-container-engine) + * [Integration with iSulad](#integration-with-isulad) + * [Integration with Docker](#integration-with-docker) +* [Appendix](#span-idappendixappendix) + * [Command Line Parameters](#command-line-parameters) + * [Communication Matrix](#communication-matrix) + * [File and Permission](#file-and-permission) + + + + + +isula-build is a container image build tool developed by the iSula container team. It allows you to quickly build container images using Dockerfiles. + +The isula-build uses the server/client mode. The isula-build functions as a client and provides a group of command line tools for image build and management. The isula-builder functions as the server, processes client management requests, and functions as the daemon process in the background. + +![isula-build architecure](./figures/isula-build_arch.png) + +Note: + +- Currently, isula-build supports only Docker images. + +# Installation + +## Preparations + +To ensure that isula-build can be successfully installed, the following software and hardware requirements must be met: + +- Supported architectures: x86_64 and AArch64 +- Supported OS: openEuler +- You have the permissions of the root user. + +### Installing isula-build + +Before using isula-build to build a container image, you need to install the following software packages: + + + +**(Recommended) Method 1: Using YUM** + +1. Configure the openEuler yum source. + +2. Log in to the target server as the root user and install isula-build. + + ``` + sudo yum install -y isula-build + ``` + + + +**Method 2: Using the RPM Package** + +1. Obtain the isula-build-*.rpm installation package from the openEuler yum source, for example, isula-build-0.9.3-1.oe1.x86_64.rpm. + +2. Upload the obtained RPM software package to any directory on the target server, for example, /home/. + +3. Log in to the target server as the root user and run the following command to install isula-build: + + ``` + sudo rpm -ivh /home/isula-build-*.rpm + ``` + +> **Note:** +After the installation is complete, you need to manually start the isula-build service. For details about how to start the service, see "Managing the isula-build Service." + +# Configuring and Managing the isula-build Service + +## Configuring the isula-build Service + +After the isula-build software package is installed, the systemd starts the isula-build service based on the default configuration contained in the isula-build software package on the isula-build server. If the default configuration file on the isula-build server cannot meet your requirements, perform the following operations to customize the configuration file: After the default configuration is modified, restart the isula-build server for the new configuration to take effect. For details, see "Managing the isula-build Service." + +Currently, the isula-build server contains the following configuration file: + +- /etc/isula-build/configuration.toml: general isula-builder configuration file, which is used to set the isula-builder log level, persistency directory, runtime directory, and OCI runtime. Parameters in the configuration file are described as follows: + +| Configuration Item | Mandatory or Optional | Description | Value | +| --------- | -------- | --------------------------------- | ----------------------------------------------- | +| debug | Optional | Indicates whether to enable the debug log function. | true: Enable the debug log function. false: Disable the debug log function. | +| loglevel | Optional | Sets the log level. | debug
info
warn
error | +| run_root | Mandatory | Sets the root directory of runtime data. | For example, /var/run/isula-build/ | +| data_root | Mandatory | Sets the local persistency directory. | For example, /var/lib/isula-build/ | +| runtime | Optional | Sets the runtime type. Currently, only runc is supported. | runc | + + +- /etc/isula-build/storage.toml: configuration file for local persistent storage, including the configuration of the storage driver in use. + +| Configuration Item | Mandatory or Optional | Description | +| ------ | -------- | ------------------------------ | +| driver | Optional | Storage driver type. Currently, overlay2 is supported. | + + For more settings, see [containers-storage.conf.5.md](https://github.com/containers/storage/blob/master/docs/containers-storage.conf.5.md). + + +- /etc/isula-build/registries.toml: configuration file for each image repository. + +| Configuration Item | Mandatory or Optional | Description | +| ------------------- | -------- | ------------------------------------------------------------ | +| registries.search | Optional | Search domain of the image repository. Only listed image repositories can be found. | +| registries.insecure | Optional | Accessible insecure image repositories. Listed image repositories cannot pass the authentication and are not recommended. | + + For more settings, see [containers-registries.conf.5.md](https://github.com/containers/image/blob/master/docs/containers-registries.conf.5.md). + +- /etc/isula-build/policy.json: image pull/push policy file. Note: Currently, this parameter cannot be configured. + +>![](public_sys-resources/icon-note.gif) **Note:** +> +> - isula-build supports the preceding configuration file with the maximum size of 1 MiB. +> - The persistent working directory dataroot cannot be configured on the memory disk, for example, tmpfs. +> - Currently, only overlay2 can be used as the underlying graphdriver. + + + +## Managing the isula-build Service + +Currently, openEuler uses systemd to manage the isula-build service. The isula-build software package contains the systemd service file. After installing the isula-build software package, you can use the systemd tool to start or stop the isula-build service. You can also manually start the isula-builder software. Note that only one isula-builder process can be started on a node at a time. + +>![](public_sys-resources/icon-note.gif) **Note:** +> Only one isula-builder process can be started on a node at a time. + +### (Recommended) Using systemd for Management + +You can run the following systemd commands to start, stop, and restart the isula-build service: + +- Run the following command to start the isula-build service: + + ```sh + sudo systemctl start isula-build.service + ``` + +- Run the following command to stop the isula-build service: + + ```sh + sudo systemctl stop isula-build.service + ``` + +- Run the following command to restart the isula-builder service: + + ```sh + sudo systemctl restart isula-build.service + ``` + +The systemd service file of the isula-build software installation package is stored in the `/usr/lib/systemd/system/isula-build.service` directory. If you need to modify the systemd configuration of the isula-build service, modify the file and run the following command to make the modification take effect. Then restart the isula-build service based on the systemd management command. + +```sh +sudo systemctl daemon-reload +``` + +### Directly Running isula-builder + +You can also run the isula-builder command on the server to start the service. The isula-builder command can contain flags for service startup. The following flags are supported: + +- -D, --debug: whether to enable the debugging mode. +- --log-level: log level. The options are debug, info, warn, and error. The default value is info. +- --dataroot: local persistency directory. The default value is /var/lib/isula-build/. +- --runroot: runtime directory. The default value is /var/run/isula-build/. +- --storage-driver: underlying storage driver type. +- --storage-opt: underlying storage driver configuration. + +>![](public_sys-resources/icon-note.gif) **Note:** +> If the command line startup parameters contain the same configuration options as those in the configuration file, the command line parameters are preferentially used for startup. + +Start the isula-build service. For example, to specify the local persistency directory /var/lib/isula-build and disable debugging, run the following command: + +```sh +sudo isula-builder --dataroot "/var/lib/isula-build" --debug=false +``` + +# Usage Guidelines + +## Prerequisites + +isula-build depends on the executable file runc to build the RUN command in the Dockerfile. Therefore, the runc must be pre-installed in the running environment of isula-build. The installation method depends on the application scenario. If you do not need to use the complete docker-engine tool chain, you can install only the docker-runc RPM package. + +```sh +sudo yum install -y docker-runc +``` + +If you need to use a complete docker-engine tool chain, install the docker-engine RPM package, which contains the executable file runc by default. + +```sh +sudo yum install -y docker-engine +``` + +>![](public_sys-resources/icon-note.gif) **Note:** +>Users must ensure the security of OCI runtime (runc) executable files to prevent malicious replacement. + + + +## Overview + +The isula-build client provides a series of commands for building and managing container images. Currently, the isula-build client provides the following command lines: + +- ctr-img: manages container images. The ctr-img command contains the following subcommands: + - build: builds a container image based on the specified Dockerfile. + - images: lists local container images. + - import: imports a basic container image. + - load: imports a cascade image. + - rm: deletes a local container image. + - save: exports a cascade image to a local disk. + - tag: adds a tag to a local container image. +- info: displays the running environment and system information of isula-build. +- login: logs in to the remote container image repository. +- logout: logs out of the remote container image repository. +- version: displays the versions of isula-build and isula-builder. + +>![](public_sys-resources/icon-note.gif) **Note:** +The isula-build completion and isula-builder completion commands are used to generate the bash command completion script. This command is implicitly provided by the command line framework and is not displayed in the help information. + + + +The following describes how to use these commands in detail. + + + + +## ctr-img: Container Image Management + +The isula-build command groups all container image management commands into the `ctr-img` command. The command is as follows: + +``` +isula-build ctr-img [command] +``` + +### build: Container Image Build + +The subcommand build of the ctr-img command is used to build container images. The command is as follows: + +``` +isula-build ctr-img build [flags] +``` + +The build command contains the following flags: + +- --build-arg: string list, which contains variables required during the build process. +- --build-static: key value, which is used to build binary equivalence. Currently, the following key values are included: + - build-time: string, which indicates that a fixed timestamp is used to build a container image. The timestamp format is YYYY-MM-DD HH-MM-SS. +- -f, --filename: string, which indicates the path of the Dockerfiles. If this parameter is not specified, the current path is used. +- --iidfile: string, which indicates the ID of the image output to a local file. +- -o, --output: string, which indicates the image export mode and path. +- --proxy: Boolean, which inherits the proxy environment variable on the host. The default value is true. +- --tag: string, which indicates the tag value of the image that is successfully built. +- --cap-add: string list, which contains permissions required by the RUN command during the build process. + +** The following describes the flags in detail. ** + +**\--build-arg** + +Parameters in the Dockerfile are inherited from the command lines. The usage is as follows: + +```sh +$ echo "This is bar file" > bar.txt +$ cat Dockerfile_arg +FROM busybox +ARG foo +ADD ${foo}.txt . +RUN cat ${foo}.txt +$ sudo isula-build ctr-img build --build-arg foo=bar -f Dockerfile_arg +STEP 1: FROM busybox +Getting image source signatures +Copying blob sha256:8f52abd3da461b2c0c11fda7a1b53413f1a92320eb96525ddf92c0b5cde781ad +Copying config sha256:e4db68de4ff27c2adfea0c54bbb73a61a42f5b667c326de4d7d5b19ab71c6a3b +Writing manifest to image destinationStoring signatures +STEP 2: ARG foo +STEP 3: ADD ${foo}.txt . +STEP 4: RUN cat ${foo}.txt +This is bar file +Getting image source signatures +Copying blob sha256:6194458b07fcf01f1483d96cd6c34302ffff7f382bb151a6d023c4e80ba3050a +Copying blob sha256:6bb56e4a46f563b20542171b998cb4556af4745efc9516820eabee7a08b7b869 +Copying config sha256:39b62a3342eed40b41a1bcd9cd455d77466550dfa0f0109af7a708c3e895f9a2 +Writing manifest to image destination +Storing signatures +Build success with image id: 39b62a3342eed40b41a1bcd9cd455d77466550dfa0f0109af7a708c3e895f9a2 +``` + +**\--build-static** + +Specifies a static build. That is, when isula-build is used to build a container image, differences between all timestamps and other build factors (such as the container ID and hostname) are eliminated. Finally, a container image that meets the static requirements is built. + +When isula-build is used to build a container image, assume that a fixed timestamp is given to the build subcommand and the following conditions are met: + +- The build environment is consistent before and after the upgrade. +- The Dockerfile is consistent before and after the build. +- The intermediate data generated before and after the build is consistent. +- The build commands are the same. +- The versions of the third-party libraries are the same. + +For container image build, isula-build supports the same Dockerfile. If the build environments are the same, the image content and image ID generated in multiple builds are the same. + +–build-static supports the key-value pair option in the k=v format. Currently, the following options are supported: + +- build-time: string, which indicates the fixed timestamp for creating a static image. The value is in the format of YYYY-MM-DD HH-MM-SS. The timestamp affects the attribute of the file for creating and modifying the time at the diff layer. + + Example: + + ```sh + $ sudo isula-build ctr-img build -f Dockerfile --build-static='build-time=2020-05-23 10:55:33' . + ``` + + In this way, the container images and image IDs built in the same environment for multiple times are the same. + +**\--iidfile** + +Run the following command to output the ID of the built image to a file: + +``` +isula-build ctr-img build --iidfile filename +``` + +For example, to export the container image ID to the testfile file, run the following command: + + ```sh +$ sudo isula-build ctr-img build -f Dockerfile_arg --iidfile testfile + ``` + + Check the container image ID in the testfile file. + + ```sh +$ cat testfile +76cbeed38a8e716e22b68988a76410eaf83327963c3b29ff648296d5cd15ce7b + ``` + + + +**\-o, --output** + +Currently, -o and –output support the following formats: + +- `isulad:image:tag`: directly pushes the image that is successfully built to iSulad, for example, `-o isulad:busybox:latest`. Pay attention to the following restrictions: + + - isula-build and iSulad must be on the same node. + - The tag must be configured. + - On the isula-build client, you need to temporarily save the successfully built image as `/var/tmp/isula-build-tmp-%v.tar` and then import it to iSulad. Ensure that the `/var/tmp/` directory has sufficient disk space. + +- `docker-daemon:image:tag`: directly pushes the successfully built image to Docker daemon, for example, `-o docker-daemon:busybox:latest`. Pay attention to the following restrictions: +- isula-build and Docker must be on the same node. + - The tag must be configured. + +- `docker://registry.example.com/repository:tag`: directly pushes the successfully built image to the remote image repository, for example, `-o docker://localhost:5000/library/busybox:latest`. + +- `docker-archive:/:image:tag`: saves the successfully built image to the local host in Docker image format, for example, `-o docker-archive:/root/image.tar:busybox:latest`. + +In addition to flags, the build subcommand also supports an argument whose type is string and meaning is context, that is, the context of the Dockerfile build environment. The default value of this parameter is the current path where isula-build is executed. This path affects the path retrieved by the ADD and COPY commands of .dockerignore and Dockerfile. + +**\--proxy** + +Specifies whether the container started by the RUN command inherits the proxy-related environment variables http_proxy, https_proxy, ftp_proxy, no_proxy, HTTP_PROXY, HTTPS_PROXY, and FTP_PROXY. The default value of NO_PROXY is true. + +When a user configures proxy-related ARG or ENV in the Dockerfile, the inherited environment variables will be overwritten. + +Note: If the client and daemon are not running on the same terminal, the environment variables that can be inherited are the environment variables of the terminal where the daemon is located. + +**\--tag** + +Specifies the tag of the image stored on the local disk after the image is successfully built. + +**\--cap-add** + +Run the following command to add the permission required by the RUN command during the build process: + +``` +isula-build ctr-img build --cap-add ${CAP} +``` + +Example: + +```sh +$ sudo isula-build ctr-img build --cap-add CAP_SYS_ADMIN --cap-add CAP_SYS_PTRACE -f Dockerfile +``` + +> **Note:** +> +> - A maximum of 100 container images can be concurrently built. +> - isula-build supports Dockerfiles with a maximum size of 1 MiB. +> - isula-build supports the .dockerignore file with a maximum size of 1 MiB. +> - Ensure that only the current user has the read and write permissions on the Dockerfiles to prevent other users from tampering with the files. +> - During the build, the RUN command starts the container to build in the container. Currently, isula-build supports the host network only. +> - isula-build only supports the tar.gz compression format. +> - isula-build commits once after each image build stage is complete, instead of each time a Dockerfile line is executed. +> - isula-build does not support cache build. +> - isula-build starts the build container only when the RUN command is built. +> - Currently, the history function of Docker images is not supported. +> - The stage name can start with a digit. +> - The stage name can contain a maximum of 64 characters. +> - isula-build does not support resource restriction on a single Dockerfile build. If resource restriction is required, you can configure a resource limit on the isula-builder. +> - Currently, isula-build does not support a remote URL as the data source of the ADD command in the Dockerfile. + + + +### image: Viewing Local Persistent Build Images + +You can run the images command to view the images in the local persistent storage. + +```sh +$ sudo isula-build ctr-img images +---------------------------------------------- ----------- ----------------- -------------------------- ------------ +REPOSITORY TAG IMAGE ID CREATED SIZE +---------------------------------------------- ----------- ----------------- -------------------------- ------------ +localhost:5000/library/alpine latest a24bb4013296 2020-20-19 19:59:197 5.85 MB + 39b62a3342ee 2020-20-38 38:66:387 1.45 MB +---------------------------------------------- ----------- ----------------- -------------------------- ------------ +``` + +**Note**: The image size displayed by running the `isula-build ctr-img images` command may be different from that displayed by running the `docker images` command. When calculating the image size, isula-build directly calculates the total size of .tar packages at each layer, while Docker calculates the total size of files by decompressing the .tar package and traversing the diff directory. Therefore, the statistics are different. + + + +### import: Importing a Basic Container Image + +openEuler releases a basic container image, for example, openEuler-docker.x86_64.tar.xz, with the version. You can run the `ctr-img import` command to import the image to isula-build. + +The command is as follows: + +``` +isula-build ctr-img import [flags] +``` + +Example: + +```sh +$ sudo isula-build ctr-img import ./openEuler-docker.x86_64.tar.xz openeuler:20.03 +Import success with image id: 7317851cd2ab33263eb293f68efee9d724780251e4e92c0fb76bf5d3c5585e37 +$ sudo isula-build ctr-img images +---------------------------------------------- -------------------- ----------------- ------------------------ ------------ +REPOSITORY TAG IMAGE ID CREATED SIZE +---------------------------------------------- -------------------- ----------------- ------------------------ ------------ +openeuler 20.03 7317851cd2ab 2020-08-01 06:25:34 500 MB +---------------------------------------------- -------------------- ----------------- ------------------------ ------------ +``` + +>![](public_sys-resources/icon-note.gif) **Note** +>isula-build supports the import of container basic images with a maximum size of 1 GiB. + + + +### load: Importing Cascade Images + +Cascade images are images that are saved to the local computer by running the docker save or isula-build ctr-img save command. The compressed image package contains a layer-by-layer image package named layer.tar. You can run the ctr-img load command to import the image to isula-build. + +The command is as follows: + +``` +isula-build ctr-img load [flags] +``` + +Currently, the following flags are supported: + +- -i, --input: path of the local .tar package. + +Example: + +```sh +$ sudo isula-build ctr-img load -i ubuntu.tarGetting image source signatures +Copying blob sha256:cf612f747e0fbcc1674f88712b7bc1cd8b91cf0be8f9e9771235169f139d507c +Copying blob sha256:f934e33a54a60630267df295a5c232ceb15b2938ebb0476364192b1537449093 +Copying blob sha256:943edb549a8300092a714190dfe633341c0ffb483784c4fdfe884b9019f6a0b4 +Copying blob sha256:e7ebc6e16708285bee3917ae12bf8d172ee0d7684a7830751ab9a1c070e7a125 +Copying blob sha256:bf6751561805be7d07d66f6acb2a33e99cf0cc0a20f5fd5d94a3c7f8ae55c2a1 +Copying blob sha256:c1bd37d01c89de343d68867518b1155cb297d8e03942066ecb44ae8f46b608a3 +Copying blob sha256:a84e57b779297b72428fc7308e63d13b4df99140f78565be92fc9dbe03fc6e69 +Copying blob sha256:14dd68f4c7e23d6a2363c2320747ab88986dfd43ba0489d139eeac3ac75323b2 +Copying blob sha256:a2092d776649ea2301f60265f378a02405539a2a68093b2612792cc65d00d161 +Copying blob sha256:879119e879f682c04d0784c9ae7bc6f421e206b95d20b32ce1cb8a49bfdef202 +Copying blob sha256:e615448af51b848ecec00caeaffd1e30e8bf5cffd464747d159f80e346b7a150 +Copying blob sha256:f610bd1e9ac6aa9326d61713d552eeefef47d2bd49fc16140aa9bf3db38c30a4 +Copying blob sha256:bfe0a1336d031bf5ff3ce381e354be7b2bf310574cc0cd1949ad94dda020cd27 +Copying blob sha256:f0f15db85788c1260c6aa8ad225823f45c89700781c4c793361ac5fa58d204c7 +Copying config sha256:c07ddb44daa97e9e8d2d68316b296cc9343ab5f3d2babc5e6e03b80cd580478e +Writing manifest to image destination +Storing signatures +Loaded image as c07ddb44daa97e9e8d2d68316b296cc9343ab5f3d2babc5e6e03b80cd580478e +``` + +>![](public_sys-resources/icon-note.gif) **Note:** +> +>The - isula-build load command can only be used to import a compressed image file that contains a single cascade image. +> +>- isula-build allows you to import a container image with a maximum size of 50 GB. + + + +### rm: Deleting a Local Persistent Image + +You can run the rm command to delete an image from the local persistent storage. The command is as follows: + +``` +isula-build ctr-img rm IMAGE [IMAGE...] [FLAGS] +``` + +Currently, the following flags are supported: + +- -a, –all: deletes all images stored locally. +- -p, –prune: deletes all images that are stored locally and do not have tags. + +Example: + +```sh +$ sudo isula-build ctr-img rm -p +Deleted: sha256:78731c1dde25361f539555edaf8f0b24132085b7cab6ecb90de63d72fa00c01d +Deleted: sha256:eeba1bfe9fca569a894d525ed291bdaef389d28a88c288914c1a9db7261ad12c +``` + + + +### save: Exporting Cascade Images + +You can run the save command to export the cascade images to the local disk. The command is as follows: + +``` +isula-build ctr-img save [REPOSITORY:TAG]|imageID -o xx.tar +``` + +The following example shows how to export an image in `image/tag` format: + +```sh +$ sudo isula-build ctr-img save busybox:latest -o busybox.tar +Getting image source signatures +Copying blob sha256:50644c29ef5a27c9a40c393a73ece2479de78325cae7d762ef3cdc19bf42dd0a +Copying blob sha256:824082a6864774d5527bda0d3c7ebd5ddc349daadf2aa8f5f305b7a2e439806f +Copying blob sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef +Copying config sha256:21c3e96ac411242a0e876af269c0cbe9d071626bdfb7cc79bfa2ddb9f7a82db6 +Writing manifest to image destination +Storing signatures +Save success with image: busybox:latest +``` + +The following example shows how to export an image in `ImageID` format: + +```sh +$ sudo isula-build ctr-img save 21c3e96ac411 -o busybox.tar +Getting image source signatures +Copying blob sha256:50644c29ef5a27c9a40c393a73ece2479de78325cae7d762ef3cdc19bf42dd0a +Copying blob sha256:824082a6864774d5527bda0d3c7ebd5ddc349daadf2aa8f5f305b7a2e439806f +Copying blob sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef +Copying config sha256:21c3e96ac411242a0e876af269c0cbe9d071626bdfb7cc79bfa2ddb9f7a82db6 +Writing manifest to image destination +Storing signatures +Save success with image: 21c3e96ac411 +``` + + + +### tag: Tagging Local Persistent Images + +You can run the tag command to add a tag to a local persistent container image. The command is as follows: + +``` +isula-build ctr-img tag / busybox:latest +``` + +Example: + +```sh +$ sudo isula-build ctr-img images +---------------------------------------------- ----------- ----------------- -------------------------- ------------ +REPOSITORY TAG IMAGE ID CREATED SIZE +---------------------------------------------- ----------- ----------------- -------------------------- ------------ +alpine latest a24bb4013296 2020-05-29 21:19:46 5.85 MB +---------------------------------------------- ----------- ----------------- -------------------------- ------------ +$ sudo isula-build ctr-img tag a24bb4013296 alpine:v1 +$ sudo isula-build ctr-img images +---------------------------------------------- ----------- ----------------- -------------------------- ------------ +REPOSITORY TAG IMAGE ID CREATED SIZE +---------------------------------------------- ----------- ----------------- -------------------------- ------------ +alpine latest a24bb4013296 2020-05-29 21:19:46 5.85 MB +alpine v1 a24bb4013296 2020-05-29 21:19:46 5.85 MB +---------------------------------------------- ----------- ----------------- -------------------------- ------------ +``` + + + +## info: Viewing the Operating Environment and System Information + +You can run the isula-build info command to view the running environment and system information of isula-build. The command is as follows: + +``` + isula-build info [flags] +``` + +The following flags are supported: + +- -H, –human-readable: Boolean. The memory information is printed in the common memory format. The value is 1000 power. + +Example: + +```sh +$ sudo isula-build info -H + General: + MemTotal: 7.63 GB + MemFree: 757 MB + SwapTotal: 8.3 GB + SwapFree: 8.25 GB + OCI Runtime: runc + DataRoot: /var/lib/isula-build/ + RunRoot: /var/run/isula-build/ + Builders: 0 + Goroutines: 12 + Store: + Storage Driver: overlay + Backing Filesystem: extfs + Registry: + Search Registries: + oepkgs.net + Insecure Registries: + localhost:5000 + oepkgs.net +``` + +## login: Logging In to the Remote Image Repository + +You can run the login command to log in to the remote image repository. The command is as follows: + +``` + isula-build login SERVER [FLAGS] +``` + +Currently, the following flags are supported: + +``` + Flags: + -p, --password-stdin Read password from stdin + -u, --username string Username to access registry +``` + +Enter the password through stdin. In the following example, the password in creds.txt is transferred to the stdin of isula-build through a pipe for input. + +```sh + $ cat creds.txt | sudo isula-build login -u cooper -p mydockerhub.io + Login Succeeded +``` + +Enter the password in interactive mode. + +```sh + $ sudo isula-build login mydockerhub.io -u cooper + Password: + Login Succeeded +``` + +## logout: Logging Out of the Remote Image Repository + +You can run the logout command to log out of the remote image repository. The command is as follows: + +``` + isula-build logout [SERVER] [FLAGS] +``` + +Currently, the following flags are supported: + +``` + Flags: + -a, --all Logout all registries +``` + +Example: + +```sh + $ sudo isula-build logout -a + Removed authentications +``` + +## version: Querying the isula-build Version + +You can run the version command to view the current version information. + +```sh + $ sudo isula-build version + Client: + Version: 0.9.2 + Go Version: go1.13.3 + Git Commit: ccb2a13 + Built: Sat Aug 22 08:06:47 2020 + OS/Arch: linux/amd64 + + Server: + Version: 0.9.2 + Go Version: go1.13.3 + Git Commit: ccb2a13 + Built: Sat Aug 22 08:06:47 2020 + OS/Arch: linux/amd64 +``` + + +# Directly Integrating a Container Engine + +isula-build can be integrated with iSulad or Docker to import the built container image to the local storage of the container engine. + +## Integration with iSulad + +Images that are successfully built can be directly exported to the iSulad. + +Example: + +```sh +$ sudo isula-build ctr-img build -f Dockerfile -o isulad:busybox:2.0 +``` + +Specify iSulad in the -o parameter to export the built container image to iSulad. You can query the image using isula images. + +```sh +$ sudo isula images +isula images +REPOSITORY TAG IMAGE ID CREATED SIZE +busybox 2.0 2d414a5cad6d 2020-08-01 06:41:36 5.577 MB +``` + +>![](public_sys-resources/icon-note.gif) **Note:** +> - It is required that isula-build and iSulad be on the same node. +> - When an image is directly exported to the iSulad, the isula-build client needs to temporarily store the successfully built image as `/var/tmp/isula-build-tmp-%v.tar` and then import it to the iSulad. Ensure that the /var/tmp/ directory has sufficient disk space. If the isula-build client process is killed or Ctrl+C is pressed during the export, you need to manually clear the `/var/tmp/isula-build-tmp-%v.tar` file. + +## Integration with Docker + +Images that are successfully built can be directly exported to the Docker daemon. + +Example: + +```sh +$ sudo isula-build ctr-img build -f Dockerfile -o docker-daemon:busybox:2.0 +``` + +Specify docker-daemon in the -o parameter to export the built container image to Docker. You can run the docker images command to query the image. + +```sh +$ sudo docker images +REPOSITORY TAG IMAGE ID CREATED SIZE +busybox 2.0 2d414a5cad6d 2 months ago 5.22MB +``` + +>![](public_sys-resources/icon-note.gif) **Note:** +> +> - The isula-build and Docker must be on the same node. + +# Appendix + + +## Command Line Parameters + +**Table 1** Parameters in the ctr-img build command + +| **Command** | **Parameter** | **Description** | +| ------------- | -------------- | ------------------------------------------------------------ | +| ctr-img build | --build-arg | String list, which contains variables required during the build. | +| | --build-static | Key value, which is used to build binary equivalence. Currently, the following key values are included: - build-time: string, which indicates that a fixed timestamp is used to build a container image. The timestamp format is YYYY-MM-DD HH-MM-SS. | +| | -f, --filename | String, which indicates the path of the Dockerfiles. If this parameter is not specified, the current path is used. | +| | --iidfile | String, which indicates the ID of the image output to a local file. | +| | -o, --output | String, which indicates the image export mode and path.| +| | --proxy | Boolean, which inherits the proxy environment variable on the host. The default value is true. | +| | --tag | String, which indicates the tag value of the image that is successfully built. | +| | --cap-add | String list, which contains permissions required by the RUN command during the build process.| + +**Table 2** Parameters in the ctr-img load command + +| **Command** | **Parameter** | **Description** | +| ------------ | ----------- | --------------------------------- | +| ctr-img load | -i, --input | String, Path of the local .tar package to be imported| + +**Table 3** Parameters in the ctr-img rm command + +| **Command** | **Parameter** | **Description** | +| ---------- | ----------- | --------------------------------------------- | +| ctr-img rm | -a, --all | Boolean, which is used to delete all local persistent images. | +| | -p, --prune | Boolean, which is used to delete all images that are stored persistently on the local host and do not have tags. | + +**Table 4** Parameters in the ctr-img save command + +| **Command** | **Parameter** | **Description** | +| ------------ | ------------ | ---------------------------------- | +| ctr-img save | -o, --output | String, which indicates the local path for storing the exported images.| + +**Table 5** Parameters in the login command + +| **Command** | **Parameter** | **Description** | +| -------- | -------------------- | ------------------------------------------------------- | +| login | -p, --password-stdin | Boolean, which indicates whether to read the password through stdin. or enter the password in interactive mode. | +| | -u, --username | String, which indicates the username for logging in to the image repository.| + +**Table 6** Parameters in the logout command + +| **Command** | **Parameter** | **Description** | +| -------- | --------- | ------------------------------------ | +| logout | -a, --all | Boolean, which indicates whether to log out of all logged-in image repositories. | + +## Communication Matrix + +The isula-build component processes communicate with each other through the Unix socket file. No port is used for communication. + +## File and Permission + +- All isula-build operations must be performed by the root user. + +- The following table lists the file permissions involved in the running of isula-build. + +| **File Path** | **File/Folder Permission** | **Description** | +| ------------------------------------------- | ------------------- | ------------------------------------------------------------ | +| /usr/bin/isula-build | 550 | Binary file of the command line tool. | +| /usr/bin/isula-builder | 550 | Binary file of the isula-builder process on the server. | +| /usr/lib/systemd/system/isula-build.service | 640 | systemd configuration file, which is used to manage the isula-build service. | +| /etc/isula-build/configuration.toml | 600 | General isula-builder configuration file, which sets the isula-builder log level, persistency directory, runtime directory, and OCI runtime. | +| /etc/isula-build/policy.json | 600 | Syntax file of the signature verification policy file. | +| /etc/isula-build/registries.toml | 600 | Configuration file of each image repository, including the available image repository list and image repository blacklist. | +| /etc/isula-build/storage.toml | 600 | Configuration file for local persistent storage, including the configuration of the used storage driver. | +| /var/run/isula_build.sock | 600 | Local socket of isula-builder. | +| /var/lib/isula-build | 700 | Local persistency directory. | +| /var/run/isula-build | 700 | Local runtime directory. | +| /var/tmp/isula-build-tmp-*.tar | 600 | Local directory for temporarily storing the images when they are exported to the iSulad. | + + diff --git a/content/en/menu/index.md b/content/en/menu/index.md index 1f1ee4f0b..525ff930e 100644 --- a/content/en/menu/index.md +++ b/content/en/menu/index.md @@ -125,6 +125,8 @@ headless: true - [Image Management]({{< ref "./docs/Container/image-management-2.md" >}}) - [Statistics]({{< ref "./docs/Container/statistics.md" >}}) + - [Image Building]({{< relref "./docs/Container/isula-build.md" >}}) + - [A-Tune User Guide]({{< relref "./docs/A-Tune/A-Tune.md" >}}) - [Getting to Know A-Tune]({{< relref "./docs/A-Tune/getting-to-know-a-tune.md" >}}) @@ -146,4 +148,4 @@ headless: true - [openEuler Toolset User Guide]({{< relref "./docs/userguide/overview.md" >}}) - [patch-tracking]({{< relref "./docs/userguide/patch-tracking.md" >}}) - - [pkgship]({{< relref "./docs/userguide/pkgship.md" >}}) \ No newline at end of file + - [pkgship]({{< relref "./docs/userguide/pkgship.md" >}}) diff --git a/content/zh/docs/Container/figures/isula-build_arch.png b/content/zh/docs/Container/figures/isula-build_arch.png new file mode 100644 index 0000000000000000000000000000000000000000..911a9ae6f46988586ab49f15de282948f5470c37 GIT binary patch literal 3418 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 F{vW4ByAS{X literal 0 HcmV?d00001 diff --git "a/content/zh/docs/Container/isula-build\346\236\204\345\273\272\345\267\245\345\205\267.md" "b/content/zh/docs/Container/isula-build\346\236\204\345\273\272\345\267\245\345\205\267.md" index 174a2ed26..af20374fc 100644 --- "a/content/zh/docs/Container/isula-build\346\236\204\345\273\272\345\267\245\345\205\267.md" +++ "b/content/zh/docs/Container/isula-build\346\236\204\345\273\272\345\267\245\345\205\267.md" @@ -1,798 +1,829 @@ -# isula-build容器镜像构建 - -## 概述 - -### 简介 - -isula-build是iSula团队推出的容器镜像构建工具，安装部署过程简单，通过Dockerfile文件可以迅速构建出容器镜像。其中，isula-build提供命令行工具，isula-builder常驻后台，处理客户端请求。 - -- 该工具目前所支持功能： - 1. ctr-img，构建容器镜像。 - 1. build，根据给定dockerfile构建出容器镜像。 - 2. images，列出本地容器镜像。 - 3. import，导入容器基础镜像。 - 4. load，导入层叠镜像。 - 5. rm，删除本地镜像。 - 6. save，导出容器镜像至本地磁盘。 - 7. tag，给本地容器镜像打tag。 - 2. login，登陆容器镜像仓库。 - 3. logout，登出容器镜像仓库。 - 4. version，查看版本号。 -- isula-build包含主要特性： - 1. 兼容Dockerfile语法。 - 3. 支持文件系统扩展属性，如Selinux、IMA、EVM等。 - 4. 支持多种镜像导出格式，可以直接将构建镜像结果推送至iSulad或docker。 - -### 快速引导 - -#### 安装部署 - -- rpm包安装 - - ``` - sudo rpm -ivh isula-build-*.rpm && systemctl start isula-build - ``` - -- yum安装 - - 推荐该方式，只需要配置openEuler yum源即可。 - - ``` - sudo yum install -y isula-build && systemctl start isula-build - ``` - - 说明： - - isula-build 构建时依赖 runc，当你安装时需要再安装单独的docker-runc或完整的docker-engine。 - -#### 示例 - -- 新建buildDir目录，在该目录下创建一个dockerfile文件，内容如下： - - ``` - FROM busybox:latest - MAINTAINER "someone" - RUN ["touch", "bar"] - LABEL foo=bar - EXPOSE 8888/udp - EXPOSE 9999/tcp - ENV a=hello - ARG word - ADD ./* /home/ - COPY ./* /home/dir1/ - VOLUME ["var/log"] - STOPSIGNAL 15 - HEALTHCHECK --interval=5m --timeout=3s --retries=1 - CMD ["pwd"] - SHELL ["pwd"] - ``` - -- 在该目录下使用isula-build构建镜像，过程如下： - - ``` - $ sudo isula-build ctr-img build -f dockerfile . - STEP 1: FROM busybox:latest - STEP 2: MAINTAINER "someone" - STEP 3: RUN ["touch", "bar"] - STEP 4: LABEL foo=bar - STEP 5: EXPOSE 8888/udp - STEP 6: EXPOSE 9999/tcp - STEP 7: ENV a=hello - STEP 8: ARG word - STEP 9: ADD ./* /home/ - STEP 10: COPY ./* /home/dir1/ - STEP 11: VOLUME ["var/log"] - STEP 12: STOPSIGNAL 15 - STEP 13: HEALTHCHECK --interval=5m --timeout=3s --retries=1 CMD ["pwd"] - STEP 14: SHELL ["pwd"] - Getting image source signatures - Copying blob sha256:e9235582825a2691b1c91a96580e358c99acfd48082cbf1b92fd2ba4a791efc3 - Copying blob sha256:dc3bca97af8b81508c343b13a08493c7809b474dc25986fcbae90c6722201be3 - Copying config sha256:9ec92a8819f9da1b06ea9ff83307ff859af2959b70bfab101f6a325b1a211549 - Writing manifest to image destination - Storing signatures - Build success with image id: 9ec92a8819f9da1b06ea9ff83307ff859af2959b70bfab101f6a325b1a211549 - ``` - -- 列出所构建镜像。 - - ``` - $ sudo isula-build ctr-img images - ----------------- ----------- ---------------- ---------------------------------------------- - REPOSITORY TAG IMAGE ID CREATED - ------------------ ---------- ---------------- ---------------------------------------------- - foo latest 9ec92a8819f9 2020-06-11 07:45:39.265106109 +0000 UTC - ``` - -- 删除镜像。 - - ``` - $ sudo isula-build ctr-img rm 9ec92a8819f9 - Deleted: sha256:86567f7a01b04c662a9657aac436e8d63ecebb26da4252abb016d177721fa11b - ``` - -#### 重点特性 - -- isula-build兼容dockerfile语法。 -- isula-build可以将构建好的容器镜像直接导入到iSulad、dockerd、registry和本地tar包。 - - - -#### 集成 - -关于iSulad和docker的集成，详情见[与容器引擎集成](#与容器引擎集成)。 - -### 注意事项 - -关于相关约束限制以及与docker build的区别详情见[使用注意事项](#使用注意事项)。 - - - -## 使用指南 - -### 配置 - -isula-builder 包含如下配置文件： - -- /etc/isula-build/configuration.toml：isula-builder 总配置文件，包含设置 isula-builder 日志级别、持久化目录和运行时目录、OCI runtime等。 - 1. debug：设置是否打开debug日志，可选参数：true、false。 - 2. loglevel：设置日志级别，可选参数：“debug”、“info”、“warn”、“error”。 - 3. run_root：设置运行时数据根目录。 - 4. data_root：设置本地持久化目录。 - 5. runtime：设置runtime种类，目前支持runc。 -- /etc/isula-build/storage.toml: 本地持久化存储的配置文件，包含所使用的存储驱动的配置。 - 1. driver：存储驱动类型，目前支持overlay2。 - 2. runroot：临时存储目录。 - 3. graphroot：可读写的镜像存储目录。 - 4. 更多设置可参考 [containers-storage.conf.5.md](https://github.com/containers/storage/blob/master/docs/containers-storage.conf.5.md)。 -- /etc/isula-build/registries.toml : 针对各个镜像仓库的配置文件，含可用的镜像仓库列表、镜像仓库黑名单。 - 1. registries.search：镜像仓库搜索域，在此list的镜像仓库可以被感知，不在此列的不被感知。 - 2. registries.insecure：可访问的不安全镜像仓库地址，在此列表中的镜像仓库将不会通过鉴权，不推荐使用。 - 3. 更多设置可参考 [containers-registries.conf.5.md](https://github.com/containers/image/blob/master/docs/containers-registries.conf.5.md)。 -- /etc/isula-build/policy.json：镜像pull/push策略文件。注：当前不支持对其进行配置 - -在启动 isula-builder 服务之前，先对服务按需配置，在还未熟悉配置的情况下，也可以直接使用rpm包安装的默认配置直接启动服务。 - -说明： - -以上配置文件，isula-build 支持最大 1M 的配置文件。 - -### 启动服务 - -#### 通过systemd启动 - -1. 配置需在上述配置文件中进行修改。 - - - 启动 isula-build 服务： - - ``` - systemctl start isula-build.service - ``` - - - 停止 isula-build 服务： - - ``` - systemctl stop isula-build.service - ``` - - - 重启 isula-builder 服务： - - ``` - systemctl restart isula-build.service - ``` - - - 查看 isula-build 服务的运行日志： - - ``` - journalctl -u isula-build - ``` - -2. 修改完配置文件后，需使用如下命令使配置生效。 - - ``` - systemctl daemon-reload - ``` - -#### 直接运行二进制启动 - -部分配置可通过isula-builder的flag进行设置，例如： - -``` -isula-builder --dataroot "/var/lib/isula-build" --debug=false -``` - -#### isula-builder目前支持的flags - -``` - --dataroot string persistent dir (default "/var/lib/isula-build") - -D, --debug print debugging information (default true) - -h, --help help for isula-builder - --log-level string The log level to be used. Either "debug", "info", "warn" or "error". (default "info") - --runroot string runtime dir (default "/var/run/isula-build") - --storage-driver string storage-driver (default "overlay") - --storage-opt strings storage driver option (default [overlay.mountopt=nodev]) - --version version for isula-builder -``` - -- -d, --debug: 是否开启调测模式。 -- --log-level: 日志级别，支持 "debug", "info", "warn" or "error"，默认为 "info"。 -- --dataroot: 本地持久化路径，默认为"/var/lib/isula-build/"。 -- --runroot: 运行时路径，默认为"/var/run/isula-build/"。 -- --storage-driver：底层存储驱动类型。 -- --storage-opt: 底层存储驱动配置。 - -当命令行启动参数中传递了与配置文件相同的配置选项，优先使用命令行参数启动。 - -### 子命令使用 - -目前 isula-build提供了如下对于容器镜像（ctr-img）操作的功能： - -- build，根据给定dockerfile构建出容器镜像。 -- images，列出本地容器镜像。 -- import，导入容器基础镜像。 -- load，导入层叠镜像。 -- rm，删除本地容器镜像。 -- save, 导出层叠镜像至本地磁盘。 -- tag，给本地容器镜像打tag。 - -同时提供了如下通用指令： - -- info，查看isula-build的运行环境和系统信息。 -- login，登入远端容器镜像仓库。 -- logout，从远端容器镜像仓库登出。 -- version，查看isula-build和isula-builder的版本号。 -- completion（隐式提供），生成bash环境命令补全脚本。 - -#### 容器镜像构建 - -``` -isula-build ctr-img build -``` - -其中 build 包含如下 flags： - -1. --build-arg：string列表，构建过程中需要用到的变量。 -2. --build-static：KV值，构建二进制一致性。目前包含如下K值： - 1. build-time：string，使用固定时间戳来构建容器镜像；时间戳格式为“YYYY-MM-DD HH-MM-SS”。 -3. -f, --filename：string，Dockerfile的路径，不指定则是使用当前路径的Dockerfile文件。 -4. --iidfile：string，输出 image ID 到本地文件。 -5. -o, --output：string，镜像导出的方式和路径。 -6. --proxy：布尔值，继承主机侧环境的proxy环境变量（默认为true）。 -7. --tag：string，设置构建成功的镜像的tag值。 -8. --cap-add：string列表，构建过程中RUN指令所需要的权限。 - -以下为各个 flags 的详解。 - -- **--build-arg** - - 从命令行接受参数作为Dockerfile中的参数，用法： - - ``` - isula-build ctr-img build --build-arg foo=bar -f Dockerfile - ``` - - ``` - $ echo "This is bar file" > bar.txt - $ cat Dockerfile_arg - FROM busybox - ARG foo - ADD ${foo}.txt . - RUN cat ${foo}.txt - $ sudo isula-build ctr-img build --build-arg foo=bar -f Dockerfile_arg - STEP 1: FROM busybox - Getting image source signatures - Copying blob sha256:8f52abd3da461b2c0c11fda7a1b53413f1a92320eb96525ddf92c0b5cde781ad - Copying config sha256:e4db68de4ff27c2adfea0c54bbb73a61a42f5b667c326de4d7d5b19ab71c6a3b - Writing manifest to image destinationStoring signatures - STEP 2: ARG foo - STEP 3: ADD ${foo}.txt . - STEP 4: RUN cat ${foo}.txt - This is bar file - Getting image source signatures - Copying blob sha256:6194458b07fcf01f1483d96cd6c34302ffff7f382bb151a6d023c4e80ba3050a - Copying blob sha256:6bb56e4a46f563b20542171b998cb4556af4745efc9516820eabee7a08b7b869 - Copying config sha256:39b62a3342eed40b41a1bcd9cd455d77466550dfa0f0109af7a708c3e895f9a2 - Writing manifest to image destination - Storing signatures - Build success with image id: 39b62a3342eed40b41a1bcd9cd455d77466550dfa0f0109af7a708c3e895f9a2 - ``` - -- **--build-static** - - 指定为静态构建，则isula-build会消除所有时间戳差异，同时消除其他构建过程差异，包括：容器ID、hsotname等, 最终构建出能满足BEP要求的容器镜像。 - - 在使用isula-build进行容器镜像构建时，假如给 build 子命令一个固定的时间戳，并在限定如下条件的时候： - - - 构建环境前后保持一致。 - - 构建Dockerfile前后保持一致。 - - 构建产生的中间数据前后保持一致。 - - 构建命令相同。 - - 第三方库版本一致。 - - 对于容器镜像构建，isula-build支持相同的Dockerfile。如果构建环境相同，则多次构建生成的镜像内容和镜像ID相同。 - - --build-static接受k=v形式的键值对选项，当前支持的选项有： - - - build-time：字符串类型。构建静态镜像的固定时间戳，格式为“YYYY-MM-DD HH-MM-SS”。时间戳影响diff层创建修改时间的文件属性。 - - 使用方式如下： - - ``` - $ sudo isula-build ctr-img build -f Dockerfile --build-static='build-time=2020-05-23 10:55:33' . - ``` - - 以此方式，同一环境多次构建出来的容器镜像和镜像ID均会保持一致。 - -- **--iidfile** - - 将构建的镜像ID输出到文件，用法： - - ``` - isula-build ctr-img build --iidfile testfile - ``` - - ``` - $ sudo isula-build ctr-img build -f Dockerfile_arg --iidfile testfile - - $ cat testfile - 76cbeed38a8e716e22b68988a76410eaf83327963c3b29ff648296d5cd15ce7b - ``` - -- **-o, --output** - - 目前 -o, --output 支持如下形式： - - - `isulad:image:tag`：将构建成功的镜像直接推送到 iSulad。比如：`-o isulad:busybox:latest`。同时需要注意如下约束： - - isula-build 和 iSulad 必须在同一个节点上 - - tag必须配置 - - isula-build client端需要将构建成功的镜像暂存成 /var/tmp/isula-build-tmp-%v.tar 再导入至 iSulad，用户需要保证 /var/tmp/ 目录有足够磁盘空间 - - `docker-daemon:image:tag`：将构建成功的镜像直接推送到 Docker daemon。比如：`-o docker-daemon:busybox:latest`。同时需要注意如下约束： - - isula-build 和 docker 必须在同一个节点上 - - tag必须配置 - - `docker://registry.example.com/repository:tag`：将构建成功的镜像直接推送到远端镜像仓库。比如：`-o docker://localhost:5000/library/busybox:latest`。 - - `docker-archive:/:image:tag`：将构建成功的镜像以Docker image的格式保存至本地。比如：`-o docker-archive:/root/image.tar:busybox:latest`。 - - 除去各个flags之外，build子命令的命令行最后还会接收一个argument，该argument类型是string，意义为context，即该Dockerfile构建环境的上下文。该参数默认值为isula-build被执行的当前路径。该路径会影响 .dockerignore 和 Dockerfile的ADD/COPY指令 所检索的路径。 - -- **--proxy** - - 选择构建时RUN指令启动的容器是否从环境上继承proxy相关环境变量"http_proxy","https_proxy","ftp_proxy","no_proxy","HTTP_PROXY","HTTPS_PROXY","FTP_PROXY","NO_PROXY"，默认为true。 - - 当用户在Dockerfile配置proxy相关ARG或ENV，将覆盖所继承的环境变量。 - - 注意：若client与daemon不在同一个终端运行，所能继承的环境变量为daemon所在终端的环境变量。 - -- **--tag** - - 设置镜像构建成功之后，该镜像在本地磁盘存储时的tag。 - -- **--cap-add** - - 添加构建过程中RUN指令所需权限，用法： - - ``` - isula-build ctr-img build --cap-add CAP_SYS_ADMIN --cap-add CAP_SYS_PTRACE -f Dockerfile - ``` - -说明： - -isula-build最大支持并发构建100个容器镜像、支持Dockerfile最大1M、支持 .dockerignore 最大 1M - -#### 查看本地持久化构建镜像 - -可通过images命令查看当前本地持久化存储的镜像： - -``` -$ sudo isula-build ctr-img images ----------------------------------------------- ----------- ----------------- -------------------------- ------------ -REPOSITORY TAG IMAGE ID CREATED SIZE ----------------------------------------------- ----------- ----------------- -------------------------- ------------ -localhost:5000/library/alpine latest a24bb4013296 2020-20-19 19:59:197 5.85 MB - 39b62a3342ee 2020-20-38 38:66:387 1.45 MB ----------------------------------------------- ----------- ----------------- -------------------------- ------------ -``` - -#### 导入容器基础镜像 - -openEuler会随版本发布一个容器基础镜像，比如openEuler-docker.x86_64.tar.xz。可以通过ctr-img import指令将它导入。 - -命令原型如下： - -``` -isula-build ctr-img import [flags] -``` - -使用举例： - -``` -$ sudo isula-build ctr-img import ./openEuler-docker.x86_64.tar.xz openeuler:20.03 -Import success with image id: 7317851cd2ab33263eb293f68efee9d724780251e4e92c0fb76bf5d3c5585e37 -$ sudo isula-build ctr-img images ----------------------------------------------- -------------------- ----------------- ------------------------ ------------ -REPOSITORY TAG IMAGE ID CREATED SIZE ----------------------------------------------- -------------------- ----------------- ------------------------ ------------ -openeuler 20.03 7317851cd2ab 2020-08-01 06:25:34 500 MB ----------------------------------------------- -------------------- ----------------- ------------------------ ------------ -``` - -说明： - -isula-build 支持导入最大1G的容器基础镜像 - -#### 导入层叠镜像 - -层叠镜像指的是通过 docker save 或 isula-build ctr-img save 等指令，将一个构建完成的镜像保存至本地之后，镜像压缩包内是一层一层 layer.tar 的镜像包。可以通过 ctr-img load 指令将它导入至 isula-build。 - -命令原型如下： - -``` -isula-build ctr-img load [flags] -``` - -使用举例如下： - -``` -$ sudo isula-build ctr-img load -i ubuntu.tarGetting image source signatures -Copying blob sha256:cf612f747e0fbcc1674f88712b7bc1cd8b91cf0be8f9e9771235169f139d507c -Copying blob sha256:f934e33a54a60630267df295a5c232ceb15b2938ebb0476364192b1537449093 -Copying blob sha256:943edb549a8300092a714190dfe633341c0ffb483784c4fdfe884b9019f6a0b4 -Copying blob sha256:e7ebc6e16708285bee3917ae12bf8d172ee0d7684a7830751ab9a1c070e7a125 -Copying blob sha256:bf6751561805be7d07d66f6acb2a33e99cf0cc0a20f5fd5d94a3c7f8ae55c2a1 -Copying blob sha256:c1bd37d01c89de343d68867518b1155cb297d8e03942066ecb44ae8f46b608a3 -Copying blob sha256:a84e57b779297b72428fc7308e63d13b4df99140f78565be92fc9dbe03fc6e69 -Copying blob sha256:14dd68f4c7e23d6a2363c2320747ab88986dfd43ba0489d139eeac3ac75323b2 -Copying blob sha256:a2092d776649ea2301f60265f378a02405539a2a68093b2612792cc65d00d161 -Copying blob sha256:879119e879f682c04d0784c9ae7bc6f421e206b95d20b32ce1cb8a49bfdef202 -Copying blob sha256:e615448af51b848ecec00caeaffd1e30e8bf5cffd464747d159f80e346b7a150 -Copying blob sha256:f610bd1e9ac6aa9326d61713d552eeefef47d2bd49fc16140aa9bf3db38c30a4 -Copying blob sha256:bfe0a1336d031bf5ff3ce381e354be7b2bf310574cc0cd1949ad94dda020cd27 -Copying blob sha256:f0f15db85788c1260c6aa8ad225823f45c89700781c4c793361ac5fa58d204c7 -Copying config sha256:c07ddb44daa97e9e8d2d68316b296cc9343ab5f3d2babc5e6e03b80cd580478e -Writing manifest to image destination -Storing signatures -Loaded image as c07ddb44daa97e9e8d2d68316b296cc9343ab5f3d2babc5e6e03b80cd580478e -``` - -说明： - -- isula-build load命令仅支持导入包含单个层叠镜像的镜像压缩文件 -- isula-build 支持导入最大50G的容器层叠镜像 - -#### 删除本地持久化镜像 - -可通过rm命令删除当前本地持久化存储的镜像 - -目前支持的flags有： - -``` -Flags: - -a, --all remove all images - -h, --help help for rm - -p, --prune remove all untagged images -``` - -这些flags分别： - -- -a, --all：删除所有本地持久化存储的镜像。 - -- -p, --prune：删除所有没有tag的本地持久化存储的镜像。 - - 使用举例： - - ``` - isula-build ctr-img rm -p - ``` - - ``` - $ sudo isula-build ctr-img rm -p - Deleted: sha256:78731c1dde25361f539555edaf8f0b24132085b7cab6ecb90de63d72fa00c01d - Deleted: sha256:eeba1bfe9fca569a894d525ed291bdaef389d28a88c288914c1a9db7261ad12c - ``` - -#### 导出层叠镜像 - -可通过save命令导出层叠镜像到本地磁盘。命令原型如下： - -``` -isula-build ctr-img save [REPOSITORY:TAG]|imageID -o xx.tar -``` - -通过镜像名字/tag进行导出： - -``` -$ sudo isula-build ctr-img save busybox:latest -o busybox.tar -Getting image source signatures -Copying blob sha256:50644c29ef5a27c9a40c393a73ece2479de78325cae7d762ef3cdc19bf42dd0a -Copying blob sha256:824082a6864774d5527bda0d3c7ebd5ddc349daadf2aa8f5f305b7a2e439806f -Copying blob sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef -Copying config sha256:21c3e96ac411242a0e876af269c0cbe9d071626bdfb7cc79bfa2ddb9f7a82db6 -Writing manifest to image destination -Storing signatures -Save success with image: busybox:latest -``` - -通过ImageID进行导出： - -``` -$ sudo isula-build ctr-img save 21c3e96ac411 -o busybox.tar -Getting image source signatures -Copying blob sha256:50644c29ef5a27c9a40c393a73ece2479de78325cae7d762ef3cdc19bf42dd0a -Copying blob sha256:824082a6864774d5527bda0d3c7ebd5ddc349daadf2aa8f5f305b7a2e439806f -Copying blob sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef -Copying config sha256:21c3e96ac411242a0e876af269c0cbe9d071626bdfb7cc79bfa2ddb9f7a82db6 -Writing manifest to image destination -Storing signatures -Save success with image: 21c3e96ac411 -``` - -#### 查看运行环境与系统信息 - -可以通过“isula-build info”指令查看 - -命令原型如下： - -``` -isula-build info [flags] -``` - -支持如下Flags： - -- -H, --human-readable 布尔值，以常用内存表示格式打印内存信息，使用1000次幂 - - 使用举例： - - ``` - $ sudo - isula-build info -H - General: - MemTotal: 7.63 GB - MemFree: 757 MB - SwapTotal: 8.3 GB - SwapFree: 8.25 GB - OCI Runtime: runc - DataRoot: /var/lib/isula-build/ - RunRoot: /var/run/isula-build/ - Builders: 0 - Goroutines: 12 - Store: - Storage Driver: overlay - Backing Filesystem: extfs - Registry: - Search Registries: - oepkgs.net - Insecure Registries: - localhost:5000 - oepkgs.net - ``` - -#### 与远程镜像仓库认证 - -可以通过 login 或 logout 命令来与远程镜像仓库交互 - -- **Login 使用**： - - ``` - isula-build login mydockerhub.io - ``` - - 你可以运行 login 命令来登录远程镜像仓库 - - 目前支持的flag有： - - ``` - Flags: - -p, --password-stdin Read password from stdin - -u, --username string Username to access registry - ``` - - 通过stdin输入密码： - - ``` - $ cat creds.txt | sudo isula-build login -u cooper -p mydockerhub.io - Login Succeeded - ``` - - 通过交互式输入密码： - - ``` - $ sudo isula-build login mydockerhub.io -u cooper - Password: - Login Succeeded - ``` - -- **Logout 使用**： - - ``` - isula-build logout mydockerhub.io - ``` - - 你可以运行 logout 命令来登出远程镜像仓库。 - - 目前支持的flag有： - - ``` - Flags: - -a, --all Logout all registries - ``` - - Flags解释如下： - - -a, --all：登出所有的镜像仓库。 - - ``` - $ sudo isula-build logout -a - Removed authentications - ``` - -#### 版本查询 - -可通过version命令查看当前版本信息： - -``` -$ sudo isula-build version -Client: - Version: 0.9.2 - Go Version: go1.13.3 - Git Commit: ccb2a13 - Built: Sat Aug 22 08:06:47 2020 - OS/Arch: linux/amd64 - -Server: - Version: 0.9.2 - Go Version: go1.13.3 - Git Commit: ccb2a13 - Built: Sat Aug 22 08:06:47 2020 - OS/Arch: linux/amd64 -``` - -说明： - -isula-build completion 和 isula-builder completion 命令用于生成bash命令补全脚本。该命令为命令行框架隐式提供，不会显示在help信息中。 - - - -### 与容器引擎集成 - -isula-build可以与iSulad和docker集成，将构建好的容器镜像导入到容器引擎的本地存储中。 - -#### 与iSulad集成 - -支持将构建成功的镜像直接导出到iSulad。命令行举例： - -``` -$ sudo isula-build ctr-img build -f Dockerfile -o isulad:busybox:2.0 -``` - -通过在-o参数中指定iSulad，将构建好的容器镜像导出到iSulad，可以通过isula images查询。 - -说明： - -要求isula-build和iSulad在同一节点。 - -#### 与Docker集成 - -支持将构建成功的镜像直接导出到Docker daemon。命令行举例： - -``` -$ sudo isula-build ctr-img build -f Dockerfile -o docker-daemon:busybox:2.0 -``` - -通过在-o参数中指定docker-daemon，将构建好的容器镜像导出到docker, 可以通过docker images查询。 - -说明： - -要求isula-build和Docker在同一节点。 - - - -## 使用注意事项 - -本章节主要介绍在使用isula-build构建镜像时相关的约束和限制，以及与docker build的差异。 - -### 约束和限制 - -1. 直接导出镜像到iSulad或docker daemon时，必须指定tag。 -2. 直接导出镜像到iSulad时，isula-build client端需要将构建成功的镜像暂存成 `/var/tmp/isula-build-tmp-%v.tar` 再导入至 iSulad，用户需要保证 /var/tmp/ 目录有足够磁盘空间；同时如果在导出过程中 isula-build client进程被KILL或Ctrl+C终止，需要依赖用户手动清理 `/var/tmp/isula-build-tmp-%v.tar` 文件。 -3. 用户需保证OCI runtime(runc)可执行文件的安全性，避免被恶意替换。 -4. isula-build不支持将持久化工作目录dataroot配置在内存盘上，比如tmpfs。 -5. isula-build目前仅支持使用overlay2为底层graphdriver。 -6. isula-build当前仅支持Docker镜像。 -7. 用户需保证Dockerfile文件的权限为仅当前用户可读写，避免别的用户进行篡改。 -8. 目前仅支持使用主机网络。 -9. 导出的镜像压缩格式，目前仅支持tar.gz格式。 -10. stage name不能以数字开头、stage name的长度限制为64个字符 - -### 与docker差异 - -- isula-build兼容dockerfile语法，但与docker build相比，使用isula-build进行镜像构建和docker build的差异如下： - 1. 在每一个镜像构建stage完成后做一次提交，而不是按行提交。 - 2. isula-build暂不支持缓存。 - 3. 仅RUN指令在构建容器中执行。 - 4. 目前不支持history。 - 5. isula-build的stage name支持以数字开头。 - 6. isula-build的stage name最长可为64个字符。 - 7. ADD指令目前不支持远端URL形式。 - 8. 暂不支持对单次构建进行资源限额，可采取对isula-builder配置资源限额的方式进行限制。 -- isula-build与docker的其它差异如下： - 1. 统计镜像大小时，isula-build是直接计算每层tar包大小之和，而docker是通过解压tar遍历diff目录计算文件大小之和，因此通过`isula-build ctr-img images`查看的镜像大小与`docker images`的显示上有一定差异。 - -### 与Dockerfile语法上的差异 - -1. 暂不支持ADD指令提供的来源是远端url。 - - - -## 附录 - -### 命令行参数说明 - -**表1** ctr-img build 命令参数列表 - -| **命令** | **参数** | **说明** | -| ------------- | -------------- | ------------------------------------------------------------ | -| ctr-img build | --build-arg | string列表，构建过程中需要用到的变量 | -| | --build-static | KV值，构建二进制一致性。目前包含如下K值：- build-time：string，使用固定时间戳来构建容器镜像；时间戳格式为“YYYY-MM-DD HH-MM-SS” | -| | -f, --filename | string，Dockerfile的路径，不指定则是使用当前路径的Dockerfile文件 | -| | --iidfile | string，输出 image ID 到本地文件 | -| | -o, --output | string，镜像导出的方式和路径 | -| | --proxy | 布尔值，继承主机侧环境的proxy环境变量（默认为true） | -| | --tag | string，给构建的镜像添加tag | -| | --cap-add | string列表，构建过程中RUN指令所需要的权限 | - -**表2** ctr-img load 命令参数列表 - -| **命令** | **参数** | **说明** | -| ------------ | ----------- | --------------------------------- | -| ctr-img load | -i, --input | string，需要导入的本地tar包的路径 | - -**表3** ctr-img rm 命令参数列表 - -| **命令** | **参数** | **说明** | -| ---------- | ----------- | --------------------------------------------- | -| ctr-img rm | -a, --all | 布尔值，删除所有本地持久化存储的镜像 | -| | -p, --prune | 布尔值，删除所有没有tag的本地持久化存储的镜像 | - -**表4** ctr-img save 命令参数列表 - -| **命令** | **参数** | **说明** | -| ------------ | ------------ | ---------------------------------- | -| ctr-img save | -o, --output | string，镜像导出后在本地的存储路径 | - -**表5** login 命令参数列表 - -| **命令** | **参数** | **说明** | -| -------- | -------------------- | ------------------------------------------------------- | -| login | -p, --password-stdin | 布尔值，是否通过stdin读入密码；或采用交互式界面输入密码 | -| | -u, --username | string，登陆镜像仓库所使用的用户名 | - -**表6** logout 命令参数列表 - -| **命令** | **参数** | **说明** | -| -------- | --------- | ------------------------------------ | -| logout | -a, --all | 布尔值，是否登出所有已登陆的镜像仓库 | - -### 通信矩阵 - -isula-build两个组件进程之间通过unix socket套接字文件进行通信，无端口通信。 - -### 文件与权限 - -1. isula-build 所有的操作均需要使用 root 权限。 - -2. isula-build 运行涉及文件权限如下表所示： - - | **文件路径** | **文件/文件夹权限** | **说明** | - | ------------------------------------------- | ------------------- | ------------------------------------------------------------ | - | /usr/bin/isula-build | 550 | 命令行工具二进制文件。 | - | /usr/bin/isula-builder | 550 | 服务端isula-builder进程二进制文件。 | - | /usr/lib/systemd/system/isula-build.service | 640 | systemd配置文件，用于管理isula-build服务。 | - | /etc/isula-build/configuration.toml | 600 | isula-builder 总配置文件，包含设置 isula-builder 日志级别、持久化目录和运行时目录、OCI runtime等。 | - | /etc/isula-build/policy.json | 600 | 签名验证策略文件的语法文件。 | - | /etc/isula-build/registries.toml | 600 | 针对各个镜像仓库的配置文件，含可用的镜像仓库列表、镜像仓库黑名单。 | - | /etc/isula-build/storage.toml | 600 | 本地持久化存储的配置文件，包含所使用的存储驱动的配置。 | - | /var/run/isula_build.sock | 600 | 服务端isula-builder的本地套接字。 | - | /var/lib/isula-build | 700 | 本地持久化目录。 | - | /var/run/isula-build | 700 | 本地运行时目录。 | - | /var/tmp/isula-build-tmp-*.tar | 600 | 镜像导出至iSulad时的本地暂存目录。 | - - \ No newline at end of file + + +* [安装](#安装) + * [环境准备](#环境准备) + * [安装isula-build](#安装isula-build) +* [配置与管理服务](#配置与管理服务) + * [配置服务](#配置服务) + * [管理服务](#管理服务) + * [通过 systemd 管理（推荐方式）](#通过-systemd-管理推荐方式) + * [直接运行 isula-build 服务端](#直接运行-isula-build-服务端) +* [使用指南](#使用指南) + * [前提条件](#前提条件) + * [总体说明](#总体说明) + * [ctr-img: 容器镜像管理](#ctr-img-容器镜像管理) + * [build: 容器镜像构建](#build-容器镜像构建) + * [image: 查看本地持久化构建镜像](#image-查看本地持久化构建镜像) + * [import: 导入容器基础镜像](#import-导入容器基础镜像) + * [load: 导入层叠镜像](#load-导入层叠镜像) + * [rm: 删除本地持久化镜像](#rm-删除本地持久化镜像) + * [save: 导出层叠镜像](#save-导出层叠镜像) + * [tag: 给本地持久化镜像打标签](#tag-给本地持久化镜像打标签) + * [info: 查看运行环境与系统信息](#info-查看运行环境与系统信息) + * [login: 登录远端镜像仓库](#login-登录远端镜像仓库) + * [logout: 退出远端镜像仓库](#logout-退出远端镜像仓库) + * [version: 版本查询](#version-版本查询) +* [直接集成容器引擎](#直接集成容器引擎) + * [与iSulad集成](#与isulad集成) + * [与Docker集成](#与docker集成) +* [附录](#附录) + * [命令行参数说明](#命令行参数说明) + * [通信矩阵](#通信矩阵) + * [文件与权限](#文件与权限) + + + +isula-build是iSula容器团队推出的容器镜像构建工具，支持通过Dockerfile文件快速构建容器镜像。 + +isula-build采用服务端/客户端模式，其中，isula-build为客户端，提供了一组命令行工具，用于镜像构建及管理等；isula-builder为服务端，用于处理客户端管理请求，作为守护进程常驻后台。 + +![isula-build architecure](./figures/isula-build_arch.png) + +说明： + +- isula-build当前仅支持Docker镜像。 + +# 安装 + +## 环境准备 + +为了确保isula-build成功安装，需满足以下软件硬件要求。 + +- 支持的机器架构：x86_64 和 AArch64 +- 支持的操作系统：openEuler +- 用户具有root权限。 + +### 安装isula-build + +使用isula-build构建容器镜像，需要先安装以下软件包。 + + + +**（推荐）方法一：使用yum安装** + +1. 配置openEuler yum源。 + +2. 使用root权限，登录目标服务器，安装isula-build。 + + ``` + sudo yum install -y isula-build + ``` + + + +**方法二：使用rpm包安装** + +1. 从openEuler yum源中获取isula-build对应安装包isula-build-*.rpm。例如isula-build-0.9.3-1.oe1.x86_64.rpm。 + +2. 将获取的rpm软件包上传至目标服务器的任一目录，例如 /home/。 + +3. 使用root权限，登录目标服务器，参考如下命令安装isula-build。 + + ``` + sudo rpm -ivh /home/isula-build-*.rpm + ``` + +> **说明：** +> 安装完成后，需要手工启动isula-build服务。启动请参见"管理服务"。 + +# 配置与管理服务 + +## 配置服务 + +在安装完 isula-build 软件包之后，systemd 管理服务会以 isula-build 软件包自带的 isula-build 服务端默认配置启动 isula-build 服务。如果 isula-build 服务端的默认配置文件不能满足用户的需求，可以参考如下介绍进行定制化配置。需要注意的是，修改完默认配置之后，需要重启 isula-build 服务端使新配置生效，具体操作可参考下一章节。 + +目前 isula-build 服务端包含如下配置文件： + +- /etc/isula-build/configuration.toml：isula-builder 总体配置文件，用于设置 isula-builder 日志级别、持久化目录和运行时目录、OCI runtime等。其中各参数含义如下： + +| 配置项 | 是否可选 | 配置项含义 | 配置项取值 | +| --------- | -------- | --------------------------------- | ----------------------------------------------- | +| debug | 可选 | 设置是否打开debug日志 | true：打开debug日志
false：关闭debug日志 | +| loglevel | 可选 | 设置日志级别 | debug
info
warn
error | +| run_root | 必选 | 设置运行时数据根目录 | 运行时数据根目录路径，例如/var/run/isula-build/ | +| data_root | 必选 | 设置本地持久化目录 | 本地持久化目录路径，例如/var/lib/isula-build/ | +| runtime | 可选 | 设置runtime种类，目前仅支持runc。 | runc | + + +- /etc/isula-build/storage.toml: 本地持久化存储的配置文件，包含所使用的存储驱动的配置。 + +| 配置项 | 是否可选 | 配置项含义 | +| ------ | -------- | ------------------------------ | +| driver | 可选 | 存储驱动类型，目前支持overlay2 | + + 更多设置可参考 [containers-storage.conf.5.md](https://github.com/containers/storage/blob/master/docs/containers-storage.conf.5.md)。 + + +- /etc/isula-build/registries.toml : 针对各个镜像仓库的配置文件。 + +| 配置项 | 是否可选 | 配置项含义 | +| ------------------- | -------- | ------------------------------------------------------------ | +| registries.search | 可选 | 镜像仓库搜索域，在此list的镜像仓库可以被感知，不在此列的不被感知。 | +| registries.insecure | 可选 | 可访问的不安全镜像仓库地址，在此列表中的镜像仓库将不会通过鉴权，不推荐使用。 | + + 更多设置可参考 [containers-registries.conf.5.md](https://github.com/containers/image/blob/master/docs/containers-registries.conf.5.md)。 + +- /etc/isula-build/policy.json：镜像pull/push策略文件。注：当前不支持对其进行配置 + +> ![](./public_sys-resources/icon-note.gif) **说明：** +> +> - isula-build 支持最大 1MiB 的上述配置文件。 +> - isula-build 不支持将持久化工作目录 dataroot 配置在内存盘上，比如 tmpfs。 +> - isula-build 目前仅支持使用overlay2为底层 graphdriver。 + + + +## 管理服务 + +目前 openEuler 采用 systemd 管理软件服务，isula-build 软件包已经自带了 systemd 的服务文件，用户安装完 isula-build 软件包之后可以直接通过 systemd 工具对它进行服务启停等操作。用户同样可以手动启动 isula-build 服务端软件。需要注意的是，同一个节点上不可以同时启动多个 isula-build 服务端软件。 + +>![](./public_sys-resources/icon-note.gif) **说明：** +>同一个节点上不可以同时启动多个 isula-build 服务端软件。 + +### 通过 systemd 管理（推荐方式） + +用户可以通过如下 systemd 的标准指令控制 isula-build 服务的启动、停止、重启等动作： + +- 启动 isula-build 服务： + + ```sh + sudo systemctl start isula-build.service + ``` + +- 停止 isula-build 服务： + + ```sh + sudo systemctl stop isula-build.service + ``` + +- 重启 isula-builder 服务： + + ```sh + sudo systemctl restart isula-build.service + ``` + +isula-build 软件包安装的 systemd 服务文件保存在 `/usr/lib/systemd/system/isula-build.service`。如果用户需要修改 isula-build 服务的 systemd 配置，可以修改该文件，执行如下命令使配置生效，之后再根据上面提到的 systemd 管理指令重启 isula-build 服务 + +```sh +sudo systemctl daemon-reload +``` + +### 直接运行 isula-build 服务端 + +您也可以通过执行 isula-build 服务端命令（ isula-builder）的方式启动服务。其中，服务端启动配置，可通过isula-builder命令支持的 flags 设置。isula-build 服务端目前支持的 flags 如下： + +- -D, --debug: 是否开启调测模式。 +- --log-level: 日志级别，支持 “debug”, “info”, “warn” or “error”，默认为 “info”。 +- --dataroot: 本地持久化路径，默认为”/var/lib/isula-build/“。 +- --runroot: 运行时路径，默认为”/var/run/isula-build/“。 +- --storage-driver：底层存储驱动类型。 +- --storage-opt: 底层存储驱动配置。 + +>![](./public_sys-resources/icon-note.gif) **说明：** +>当命令行启动参数中传递了与配置文件相同的配置选项时，优先使用命令行参数启动。 + +启动 isula-build 服务。例如指定本地持久化路径/var/lib/isula-build，且不开启调试的参考命令如下： + +```sh +sudo isula-builder --dataroot "/var/lib/isula-build" --debug=false +``` + +# 使用指南 + +## 前提条件 + +isula-build 构建 Dockerfile 内的 RUN 指令时依赖可执行文件 runc ，需要 isula-build 的运行环境上预装好 runc。安装方式视用户使用场景而定，如果用户不需要使用完整的 docker-engine 工具链，则可以仅安装 docker-runc rpm包： + +```sh +sudo yum install -y docker-runc +``` + +如果用户需要使用完整的 docker-engine 工具链，则可以安装 docker-engine rpm包，默认包含可执行文件 runc ： + +```sh +sudo yum install -y docker-engine +``` + +>![](./public_sys-resources/icon-note.gif) **说明：** +>用户需保证OCI runtime(runc)可执行文件的安全性，避免被恶意替换。 + + + +## 总体说明 + +isula-build 客户端提供了一系列命令用于构建和管理容器镜像，当前 isula-build 包含的命令行指令如下： + +- ctr-img，容器镜像管理。ctr-img又包含如下子命令： + - build，根据给定dockerfile构建出容器镜像。 + - images，列出本地容器镜像。 + - import，导入容器基础镜像。 + - load，导入层叠镜像。 + - rm，删除本地容器镜像。 + - save, 导出层叠镜像至本地磁盘。 + - tag，给本地容器镜像打tag。 +- info，查看isula-build的运行环境和系统信息。 +- login，登录远端容器镜像仓库。 +- logout，退出远端容器镜像仓库。 +- version，查看isula-build和isula-builder的版本号。 + +>![](./public_sys-resources/icon-note.gif) **说明：** +>isula-build completion 和 isula-builder completion 命令用于生成bash命令补全脚本。该命令为命令行框架隐式提供，不会显示在help信息中。 + + + +以下按照上述维度依次详细介绍这些命令行指令的使用。 + + + + +## ctr-img: 容器镜像管理 + +isula-build 将所有容器镜像管理相关命令划分在子命令 `ctr-img` 下，命令原型为： + +``` +isula-build ctr-img [command] +``` + +### build: 容器镜像构建 + +ctr-img 的子命令 build 用于构建容器镜像，命令原型为： + +``` +isula-build ctr-img build [flags] +``` + +其中 build 包含如下 flags： + +- --build-arg：string列表，构建过程中需要用到的变量。 +- --build-static：KeyValue值，构建二进制一致性。目前包含如下Key值： + - build-time：string，使用固定时间戳来构建容器镜像；时间戳格式为“YYYY-MM-DD HH-MM-SS”。 +- -f, --filename：string，Dockerfile的路径，不指定则是使用当前路径的Dockerfile文件。 +- --iidfile：string，输出 image ID 到本地文件。 +- -o, --output：string，镜像导出的方式和路径。 +- --proxy：布尔值，继承主机侧环境的proxy环境变量（默认为true）。 +- --tag：string，设置构建成功的镜像的tag值。 +- --cap-add：string列表，构建过程中RUN指令所需要的权限。 + +**以下为各个 flags 的详解。** + +**\--build-arg** + +从命令行接受参数作为Dockerfile中的参数，用法： + +```sh +$ echo "This is bar file" > bar.txt +$ cat Dockerfile_arg +FROM busybox +ARG foo +ADD ${foo}.txt . +RUN cat ${foo}.txt +$ sudo isula-build ctr-img build --build-arg foo=bar -f Dockerfile_arg +STEP 1: FROM busybox +Getting image source signatures +Copying blob sha256:8f52abd3da461b2c0c11fda7a1b53413f1a92320eb96525ddf92c0b5cde781ad +Copying config sha256:e4db68de4ff27c2adfea0c54bbb73a61a42f5b667c326de4d7d5b19ab71c6a3b +Writing manifest to image destinationStoring signatures +STEP 2: ARG foo +STEP 3: ADD ${foo}.txt . +STEP 4: RUN cat ${foo}.txt +This is bar file +Getting image source signatures +Copying blob sha256:6194458b07fcf01f1483d96cd6c34302ffff7f382bb151a6d023c4e80ba3050a +Copying blob sha256:6bb56e4a46f563b20542171b998cb4556af4745efc9516820eabee7a08b7b869 +Copying config sha256:39b62a3342eed40b41a1bcd9cd455d77466550dfa0f0109af7a708c3e895f9a2 +Writing manifest to image destination +Storing signatures +Build success with image id: 39b62a3342eed40b41a1bcd9cd455d77466550dfa0f0109af7a708c3e895f9a2 +``` + +**\--build-static** + +指定为静态构建，即使用isula-build构建容器镜像时消除所有时间戳和其他构建因素（例如容器ID、hostname等）的差异。最终构建出满足静态要求的容器镜像。 + +在使用isula-build进行容器镜像构建时，假如给 build 子命令一个固定的时间戳，并在限定如下条件的时候： + +- 构建环境前后保持一致。 +- 构建Dockerfile前后保持一致。 +- 构建产生的中间数据前后保持一致。 +- 构建命令相同。 +- 第三方库版本一致。 + +对于容器镜像构建，isula-build支持相同的Dockerfile。如果构建环境相同，则多次构建生成的镜像内容和镜像ID相同。 + +–build-static接受k=v形式的键值对选项，当前支持的选项有： + +- build-time：字符串类型。构建静态镜像的固定时间戳，格式为“YYYY-MM-DD HH-MM-SS”。时间戳影响diff层创建修改时间的文件属性。 + + 使用示例如下： + + ```sh + $ sudo isula-build ctr-img build -f Dockerfile --build-static='build-time=2020-05-23 10:55:33' . + ``` + + 以此方式，同一环境多次构建出来的容器镜像和镜像ID均会保持一致。 + +**\--iidfile** + +将构建的镜像ID输出到文件，用法： + +``` +isula-build ctr-img build --iidfile filename +``` + +例如，将容器镜像ID输出到testfile的参考命令如下： + + ```sh +$ sudo isula-build ctr-img build -f Dockerfile_arg --iidfile testfile + ``` + + 查看testfile中的容器镜像ID： + + ```sh +$ cat testfile +76cbeed38a8e716e22b68988a76410eaf83327963c3b29ff648296d5cd15ce7b + ``` + + + +**\-o, --output** + +目前 -o, –output 支持如下形式： + +- `isulad:image:tag`：将构建成功的镜像直接推送到 iSulad。比如：`-o isulad:busybox:latest`。同时需要注意如下约束： + + - isula-build 和 iSulad 必须在同一个节点上 + - tag必须配置 + - isula-build client端需要将构建成功的镜像暂存成 `/var/tmp/isula-build-tmp-%v.tar` 再导入至 iSulad，用户需要保证 `/var/tmp/` 目录有足够磁盘空间 + +- `docker-daemon:image:tag`：将构建成功的镜像直接推送到 Docker daemon。比如：`-o docker-daemon:busybox:latest`。同时需要注意如下约束： +- isula-build 和 docker 必须在同一个节点上 + - tag必须配置 + +- `docker://registry.example.com/repository:tag`：将构建成功的镜像直接推送到远端镜像仓库。比如：`-o docker://localhost:5000/library/busybox:latest`。 + +- `docker-archive:/:image:tag`：将构建成功的镜像以Docker image的格式保存至本地。比如：`-o docker-archive:/root/image.tar:busybox:latest`。 + +除去各个flags之外，build子命令的命令行最后还会接收一个argument，该argument类型是string，意义为context，即该Dockerfile构建环境的上下文。该参数默认值为isula-build被执行的当前路径。该路径会影响 .dockerignore 和 Dockerfile的ADD/COPY指令 所检索的路径。 + +**\--proxy** + +选择构建时RUN指令启动的容器是否从环境上继承proxy相关环境变量”http_proxy”,“https_proxy”,“ftp_proxy”,“no_proxy”,“HTTP_PROXY”,“HTTPS_PROXY”,“FTP_PROXY”,“NO_PROXY”，默认为true。 + +当用户在Dockerfile配置proxy相关ARG或ENV，将覆盖所继承的环境变量。 + +注意：若client与daemon不在同一个终端运行，所能继承的环境变量为daemon所在终端的环境变量。 + +**\--tag** + +设置镜像构建成功之后，该镜像在本地磁盘存储时的tag。 + +**\--cap-add** + +添加构建过程中RUN指令所需权限，用法： + +``` +isula-build ctr-img build --cap-add ${CAP} +``` + +使用举例： + +```sh +$ sudo isula-build ctr-img build --cap-add CAP_SYS_ADMIN --cap-add CAP_SYS_PTRACE -f Dockerfile +``` + +> **说明：** +> +> - isula-build最大支持并发构建100个容器镜像。 +> - isula-build支持Dockerfile最大为1MiB。 +> - isula-build支持 .dockerignore 最大为 1MiB。 +> - 用户需保证Dockerfile文件的权限为仅当前用户可读写，避免别的用户进行篡改。 +> - 构建时，RUN指令会启动容器在容器内进行构建，目前 isula-build 仅支持使用主机网络。 +> - isula-build 导出的镜像压缩格式，目前仅支持tar.gz格式。 +> - isula-build 在每一个镜像构建stage完成后做一次提交，而不是每执行 Dockerfile的一行就提交一次。 +> - isula-build 暂不支持构建缓存。 +> - isula-build 仅在构建RUN指令时会启动构建容器。 +> - 目前不支持docker镜像格式的history功能。 +> - isula-build 的stage name支持以数字开头。 +> - isula-build 的stage name最长可为64个字符。 +> - isula-build 暂不支持对单次Dockerfile的构建进行资源限制。如有资源限制需求，可通过对 isula-builder 服务端配置资源限额的方式进行限制。 +> - isula-build 目前不支持Dockerfile里的ADD指令提供的数据来源是远端url。 + + + +### image: 查看本地持久化构建镜像 + +可通过images命令查看当前本地持久化存储的镜像： + +```sh +$ sudo isula-build ctr-img images +---------------------------------------------- ----------- ----------------- -------------------------- ------------ +REPOSITORY TAG IMAGE ID CREATED SIZE +---------------------------------------------- ----------- ----------------- -------------------------- ------------ +localhost:5000/library/alpine latest a24bb4013296 2020-20-19 19:59:197 5.85 MB + 39b62a3342ee 2020-20-38 38:66:387 1.45 MB +---------------------------------------------- ----------- ----------------- -------------------------- ------------ +``` + +**说明**：通过`isula-build ctr-img images`查看的镜像大小与`docker images`的显示上有一定差异。这是因为统计镜像大小时，isula-build是直接计算每层tar包大小之和，而docker是通过解压tar遍历diff目录计算文件大小之和，因此存在统计上的差异。 + + + +### import: 导入容器基础镜像 + +openEuler会随版本发布一个容器基础镜像，比如openEuler-docker.x86_64.tar.xz。可以通过`ctr-img import`指令将它导入到 isula-build。 + +命令原型如下： + +``` +isula-build ctr-img import [flags] +``` + +使用举例： + +```sh +$ sudo isula-build ctr-img import ./openEuler-docker.x86_64.tar.xz openeuler:20.03 +Import success with image id: 7317851cd2ab33263eb293f68efee9d724780251e4e92c0fb76bf5d3c5585e37 +$ sudo isula-build ctr-img images +---------------------------------------------- -------------------- ----------------- ------------------------ ------------ +REPOSITORY TAG IMAGE ID CREATED SIZE +---------------------------------------------- -------------------- ----------------- ------------------------ ------------ +openeuler 20.03 7317851cd2ab 2020-08-01 06:25:34 500 MB +---------------------------------------------- -------------------- ----------------- ------------------------ ------------ +``` + +>![](./public_sys-resources/icon-note.gif) **说明：** +>isula-build 支持导入最大1GiB的容器基础镜像。 + + + +### load: 导入层叠镜像 + +层叠镜像指的是通过 docker save 或 isula-build ctr-img save 等指令，将一个构建完成的镜像保存至本地之后，镜像压缩包内是一层一层 layer.tar 的镜像包。可以通过 ctr-img load 指令将它导入至 isula-build。 + +命令原型如下： + +``` +isula-build ctr-img load [flags] +``` + +目前支持的 flags 为： + +- -i, --input：本地tar包的路径 + +使用举例如下： + +```sh +$ sudo isula-build ctr-img load -i ubuntu.tarGetting image source signatures +Copying blob sha256:cf612f747e0fbcc1674f88712b7bc1cd8b91cf0be8f9e9771235169f139d507c +Copying blob sha256:f934e33a54a60630267df295a5c232ceb15b2938ebb0476364192b1537449093 +Copying blob sha256:943edb549a8300092a714190dfe633341c0ffb483784c4fdfe884b9019f6a0b4 +Copying blob sha256:e7ebc6e16708285bee3917ae12bf8d172ee0d7684a7830751ab9a1c070e7a125 +Copying blob sha256:bf6751561805be7d07d66f6acb2a33e99cf0cc0a20f5fd5d94a3c7f8ae55c2a1 +Copying blob sha256:c1bd37d01c89de343d68867518b1155cb297d8e03942066ecb44ae8f46b608a3 +Copying blob sha256:a84e57b779297b72428fc7308e63d13b4df99140f78565be92fc9dbe03fc6e69 +Copying blob sha256:14dd68f4c7e23d6a2363c2320747ab88986dfd43ba0489d139eeac3ac75323b2 +Copying blob sha256:a2092d776649ea2301f60265f378a02405539a2a68093b2612792cc65d00d161 +Copying blob sha256:879119e879f682c04d0784c9ae7bc6f421e206b95d20b32ce1cb8a49bfdef202 +Copying blob sha256:e615448af51b848ecec00caeaffd1e30e8bf5cffd464747d159f80e346b7a150 +Copying blob sha256:f610bd1e9ac6aa9326d61713d552eeefef47d2bd49fc16140aa9bf3db38c30a4 +Copying blob sha256:bfe0a1336d031bf5ff3ce381e354be7b2bf310574cc0cd1949ad94dda020cd27 +Copying blob sha256:f0f15db85788c1260c6aa8ad225823f45c89700781c4c793361ac5fa58d204c7 +Copying config sha256:c07ddb44daa97e9e8d2d68316b296cc9343ab5f3d2babc5e6e03b80cd580478e +Writing manifest to image destination +Storing signatures +Loaded image as c07ddb44daa97e9e8d2d68316b296cc9343ab5f3d2babc5e6e03b80cd580478e +``` + +>![](./public_sys-resources/icon-note.gif) **说明：** +> +>- isula-build load命令仅支持导入包含单个层叠镜像的镜像压缩文件。 +>- isula-build 支持导入最大50G的容器层叠镜像。 + + + +### rm: 删除本地持久化镜像 + +可通过rm命令删除当前本地持久化存储的镜像。命令原型为： + +``` +isula-build ctr-img rm IMAGE [IMAGE...] [FLAGS] +``` + +目前支持的 flags 为： + +- -a, –all：删除所有本地持久化存储的镜像。 +- -p, –prune：删除所有没有tag的本地持久化存储的镜像。 + +使用示例如下： + +```sh +$ sudo isula-build ctr-img rm -p +Deleted: sha256:78731c1dde25361f539555edaf8f0b24132085b7cab6ecb90de63d72fa00c01d +Deleted: sha256:eeba1bfe9fca569a894d525ed291bdaef389d28a88c288914c1a9db7261ad12c +``` + + + +### save: 导出层叠镜像 + +可通过save命令导出层叠镜像到本地磁盘。命令原型如下： + +``` +isula-build ctr-img save [REPOSITORY:TAG]|imageID -o xx.tar +``` + +以下示例通过 `image/tag` 的形式将镜像进行导出： + +```sh +$ sudo isula-build ctr-img save busybox:latest -o busybox.tar +Getting image source signatures +Copying blob sha256:50644c29ef5a27c9a40c393a73ece2479de78325cae7d762ef3cdc19bf42dd0a +Copying blob sha256:824082a6864774d5527bda0d3c7ebd5ddc349daadf2aa8f5f305b7a2e439806f +Copying blob sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef +Copying config sha256:21c3e96ac411242a0e876af269c0cbe9d071626bdfb7cc79bfa2ddb9f7a82db6 +Writing manifest to image destination +Storing signatures +Save success with image: busybox:latest +``` + +以下示例通过 `ImageID` 的形式将镜像进行导出： + +```sh +$ sudo isula-build ctr-img save 21c3e96ac411 -o busybox.tar +Getting image source signatures +Copying blob sha256:50644c29ef5a27c9a40c393a73ece2479de78325cae7d762ef3cdc19bf42dd0a +Copying blob sha256:824082a6864774d5527bda0d3c7ebd5ddc349daadf2aa8f5f305b7a2e439806f +Copying blob sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef +Copying config sha256:21c3e96ac411242a0e876af269c0cbe9d071626bdfb7cc79bfa2ddb9f7a82db6 +Writing manifest to image destination +Storing signatures +Save success with image: 21c3e96ac411 +``` + + + +### tag: 给本地持久化镜像打标签 + +可使用tag命令给本地持久化的容器镜像打tag。命令原型如下： + +``` +isula-build ctr-img tag / busybox:latest +``` + +使用举例： + +```sh +$ sudo isula-build ctr-img images +---------------------------------------------- ----------- ----------------- -------------------------- ------------ +REPOSITORY TAG IMAGE ID CREATED SIZE +---------------------------------------------- ----------- ----------------- -------------------------- ------------ +alpine latest a24bb4013296 2020-05-29 21:19:46 5.85 MB +---------------------------------------------- ----------- ----------------- -------------------------- ------------ +$ sudo isula-build ctr-img tag a24bb4013296 alpine:v1 +$ sudo isula-build ctr-img images +---------------------------------------------- ----------- ----------------- -------------------------- ------------ +REPOSITORY TAG IMAGE ID CREATED SIZE +---------------------------------------------- ----------- ----------------- -------------------------- ------------ +alpine latest a24bb4013296 2020-05-29 21:19:46 5.85 MB +alpine v1 a24bb4013296 2020-05-29 21:19:46 5.85 MB +---------------------------------------------- ----------- ----------------- -------------------------- ------------ +``` + + + +## info: 查看运行环境与系统信息 + +可以通过“isula-build info”指令查看 isula-build 目前的运行环境与系统信息。命令原型如下： + +``` + isula-build info [flags] +``` + +支持如下Flags： + +- -H, –human-readable 布尔值，以常用内存表示格式打印内存信息，使用1000次幂 + +使用示例： + +```sh +$ sudo isula-build info -H + General: + MemTotal: 7.63 GB + MemFree: 757 MB + SwapTotal: 8.3 GB + SwapFree: 8.25 GB + OCI Runtime: runc + DataRoot: /var/lib/isula-build/ + RunRoot: /var/run/isula-build/ + Builders: 0 + Goroutines: 12 + Store: + Storage Driver: overlay + Backing Filesystem: extfs + Registry: + Search Registries: + oepkgs.net + Insecure Registries: + localhost:5000 + oepkgs.net +``` + +## login: 登录远端镜像仓库 + +用户可以运行 login 命令来登录远程镜像仓库。命令原型如下： + +``` + isula-build login SERVER [FLAGS] +``` + +目前支持的flag有： + +``` + Flags: + -p, --password-stdin Read password from stdin + -u, --username string Username to access registry +``` + +通过stdin输入密码。以下示例通过通过管道将creds.txt里的密码传给isula-build的stdin进行输入： + +```sh + $ cat creds.txt | sudo isula-build login -u cooper -p mydockerhub.io + Login Succeeded +``` + +通过交互式输入密码： + +```sh + $ sudo isula-build login mydockerhub.io -u cooper + Password: + Login Succeeded +``` + +## logout: 退出远端镜像仓库 + +用户可以运行 logout 命令来登出远程镜像仓库。命令原型如下： + +``` + isula-build logout [SERVER] [FLAGS] +``` + +目前支持的flag有： + +``` + Flags: + -a, --all Logout all registries +``` + +使用示例如下： + +```sh + $ sudo isula-build logout -a + Removed authentications +``` + +## version: 版本查询 + +可通过version命令查看当前版本信息： + +```sh + $ sudo isula-build version + Client: + Version: 0.9.2 + Go Version: go1.13.3 + Git Commit: ccb2a13 + Built: Sat Aug 22 08:06:47 2020 + OS/Arch: linux/amd64 + + Server: + Version: 0.9.2 + Go Version: go1.13.3 + Git Commit: ccb2a13 + Built: Sat Aug 22 08:06:47 2020 + OS/Arch: linux/amd64 +``` + + +# 直接集成容器引擎 + +isula-build可以与iSulad和docker集成，将构建好的容器镜像导入到容器引擎的本地存储中。 + +## 与iSulad集成 + +支持将构建成功的镜像直接导出到iSulad。 + +命令行举例： + +```sh +$ sudo isula-build ctr-img build -f Dockerfile -o isulad:busybox:2.0 +``` + +通过在-o参数中指定iSulad，将构建好的容器镜像导出到iSulad，可以通过isula images查询： + +```sh +$ sudo isula images +isula images +REPOSITORY TAG IMAGE ID CREATED SIZE +busybox 2.0 2d414a5cad6d 2020-08-01 06:41:36 5.577 MB +``` + +> ![](./public_sys-resources/icon-note.gif) **说明：** +> - 要求isula-build和iSulad在同一节点。 +> - 直接导出镜像到iSulad时，isula-build client端需要将构建成功的镜像暂存成 `/var/tmp/isula-build-tmp-%v.tar` 再导入至 iSulad，用户需要保证 /var/tmp/ 目录有足够磁盘空间；同时如果在导出过程中 isula-build client进程被KILL或Ctrl+C终止，需要依赖用户手动清理 `/var/tmp/isula-build-tmp-%v.tar` 文件。 + +## 与Docker集成 + +支持将构建成功的镜像直接导出到Docker daemon。 + +命令行举例： + +```sh +$ sudo isula-build ctr-img build -f Dockerfile -o docker-daemon:busybox:2.0 +``` + +通过在-o参数中指定docker-daemon，将构建好的容器镜像导出到docker, 可以通过docker images查询。 + +```sh +$ sudo docker images +REPOSITORY TAG IMAGE ID CREATED SIZE +busybox 2.0 2d414a5cad6d 2 months ago 5.22MB +``` + +> ![](./public_sys-resources/icon-note.gif) **说明：** +> +> - 要求isula-build和Docker在同一节点。 + +# 附录 + + +## 命令行参数说明 + +**表1** ctr-img build 命令参数列表 + +| **命令** | **参数** | **说明** | +| ------------- | -------------- | ------------------------------------------------------------ | +| ctr-img build | --build-arg | string列表，构建过程中需要用到的变量 | +| | --build-static | KV值，构建二进制一致性。目前包含如下K值：- build-time：string，使用固定时间戳来构建容器镜像；时间戳格式为“YYYY-MM-DD HH-MM-SS” | +| | -f, --filename | string，Dockerfile的路径，不指定则是使用当前路径的Dockerfile文件 | +| | --iidfile | string，输出 image ID 到本地文件 | +| | -o, --output | string，镜像导出的方式和路径 | +| | --proxy | 布尔值，继承主机侧环境的proxy环境变量（默认为true） | +| | --tag | string，给构建的镜像添加tag | +| | --cap-add | string列表，构建过程中RUN指令所需要的权限 | + +**表2** ctr-img load 命令参数列表 + +| **命令** | **参数** | **说明** | +| ------------ | ----------- | --------------------------------- | +| ctr-img load | -i, --input | string，需要导入的本地tar包的路径 | + +**表3** ctr-img rm 命令参数列表 + +| **命令** | **参数** | **说明** | +| ---------- | ----------- | --------------------------------------------- | +| ctr-img rm | -a, --all | 布尔值，删除所有本地持久化存储的镜像 | +| | -p, --prune | 布尔值，删除所有没有tag的本地持久化存储的镜像 | + +**表4** ctr-img save 命令参数列表 + +| **命令** | **参数** | **说明** | +| ------------ | ------------ | ---------------------------------- | +| ctr-img save | -o, --output | string，镜像导出后在本地的存储路径 | + +**表5** login 命令参数列表 + +| **命令** | **参数** | **说明** | +| -------- | -------------------- | ------------------------------------------------------- | +| login | -p, --password-stdin | 布尔值，是否通过stdin读入密码；或采用交互式界面输入密码 | +| | -u, --username | string，登陆镜像仓库所使用的用户名 | + +**表6** logout 命令参数列表 + +| **命令** | **参数** | **说明** | +| -------- | --------- | ------------------------------------ | +| logout | -a, --all | 布尔值，是否登出所有已登陆的镜像仓库 | + +## 通信矩阵 + +isula-build两个组件进程之间通过unix socket套接字文件进行通信，无端口通信。 + +## 文件与权限 + +- isula-build 所有的操作均需要使用 root 权限。 + +- isula-build 运行涉及文件权限如下表所示： + +| **文件路径** | **文件/文件夹权限** | **说明** | +| ------------------------------------------- | ------------------- | ------------------------------------------------------------ | +| /usr/bin/isula-build | 550 | 命令行工具二进制文件。 | +| /usr/bin/isula-builder | 550 | 服务端isula-builder进程二进制文件。 | +| /usr/lib/systemd/system/isula-build.service | 640 | systemd配置文件，用于管理isula-build服务。 | +| /etc/isula-build/configuration.toml | 600 | isula-builder 总配置文件，包含设置 isula-builder 日志级别、持久化目录和运行时目录、OCI runtime等。 | +| /etc/isula-build/policy.json | 600 | 签名验证策略文件的语法文件。 | +| /etc/isula-build/registries.toml | 600 | 针对各个镜像仓库的配置文件，含可用的镜像仓库列表、镜像仓库黑名单。 | +| /etc/isula-build/storage.toml | 600 | 本地持久化存储的配置文件，包含所使用的存储驱动的配置。 | +| /var/run/isula_build.sock | 600 | 服务端isula-builder的本地套接字。 | +| /var/lib/isula-build | 700 | 本地持久化目录。 | +| /var/run/isula-build | 700 | 本地运行时目录。 | +| /var/tmp/isula-build-tmp-*.tar | 600 | 镜像导出至iSulad时的本地暂存目录。 | + + diff --git a/content/zh/menu/index.md b/content/zh/menu/index.md index af5e4b6f6..6a8b1279b 100644 --- a/content/zh/menu/index.md +++ b/content/zh/menu/index.md @@ -128,7 +128,7 @@ headless: true - [容器管理]({{< relref "./docs/Container/容器管理-4.md" >}}) - [镜像管理]({{< relref "./docs/Container/镜像管理-4.md" >}}) - [统计信息]({{< relref "./docs/Container/统计信息-4.md" >}}) - - [isula-build构建工具]({{< relref "./docs/Container/isula-build构建工具.md" >}}) + - [容器镜像构建]({{< relref "./docs/Container/isula-build构建工具.md" >}}) - [A-Tune用户指南]({{< relref "./docs/A-Tune/A-Tune.md" >}}) -- Gitee