* [Usage](#usage) * [Configuration](#configuration) * [Starting the Service](#starting-the-service) * [Using systemd (RPM package installation)](#using-systemd-rpm-package-installation) * [Using binary file](#using-binary-file) * [isula-builder supported flags:](#isula-builder-supported-flags) * [Features](#features) * [Container Image Building](#container-image-building) * [--build-arg](#--build-arg) * [--build-static](#--build-static) * [--iidfile](#--iidfile) * [-o, --output](#-o---output) * [--proxy](#--proxy) * [--tag](#--tag) * [Viewing a Local Persistent Image](#viewing-a-local-persistent-image) * [Importing a Base Image from a Tarball](#importing-a-base-image-from-a-tarball) * [Saving a Local Persistent Image](#saving-a-local-persistent-image) * [Deleting a Local Persistent Image](#deleting-a-local-persistent-image) * [-a, --all](#-a---all) * [-p, --prune](#-p---prune) * [Authentication of the Remote Image Repository](#authentication-of-the-remote-image-repository) * [-a, --all](#-a---all-1) * [Version query](#version-query) * [Tag an image](#tag-an-image) * [Show system information](#show-system-information) * [Load an image](#load-an-image) # Usage ## Configuration isula-builder contains the following configuration files: - `/etc/isula-build/configuration.toml`: isula-builder overall configuration file, which is used to set the isula-builder log level, persistency and runtime directories, OCI runtime. Besides, other configs path are also included. - debug: specifies whether to enable the debug log function. The options are true or false - loglevel: specifies the log level. The value can be "debug", "info", "warn", or "error" - data_root: set the local persistency directory - run_root: set runtime data directory - runtime: runtime type. Currently, "runc" is supported only - storage_config_path: path of the configuration file for local persistent storage - registry_config_path: specifies the address of the image repository configuration file - `/etc/isula-build/storage.toml`: configuration file of the local persistent storage, including the configuration of the used storage driver - driver: specifies the storage driver type. Currently, overlay2 is supported - runroot: temporary storage directory - graphroot: readable and writable image storage directory - 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`: config for registries setting, including the list of available image repositories and image repository blocklist - registries.search: search domain of the image repository. Only the image repositories in the list can be detected - registries.insecure: indicates the address of the insecure image repository that can be accessed. Image repositories in this list are not authenticated(Not recommended) - For more settings, see [containers-registries.conf.5.md](https://github.com/containers/image/blob/master/docs/containers-registries.conf.5.md) Before starting the isula-builder service, user should configure the service as required. If not familiar with the configuration, we can directly use the default configuration of the RPM package to start the service. ## Starting the Service ### Using systemd (RPM package installation) Modify the configuration in the preceding configuration file. - `systemctl start isula-build.service`: start isula-build service - `systemctl stop isula-build.service`: stop isula-build service - `systemctl restart isula-build`: restart isula-build service - `journalctl -u isula-build`: look up isula-build logs ### Using binary file Some configurations can be set through the flag of the isula-builder. For example: - `isula-builder --dataroot "/var/lib/isula-build" --debug=false` ### isula-builder supported flags: ```bash -c, --config string config file path (default "/etc/isula/build.toml") --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 ``` - -c, --config: configuration file. The default path is "/etc/isula-build/configuration.toml". For details about the configuration method, see section "Configuration" - -d, --debug: indicates whether to enable the debug mode - --log-level: log level. The value can be "debug", "info", "warn" or "error". The default value is info - --dataroot: local persistent path. The default path is /var/lib/isula-build/ - --runroot: Runtime path. The default value is /var/run/isula-build/ - --storage-driver: underlaying graphdriver type - --storage-opt: underlying graphdriver configuration When the command line startup parameter is the same as the configuration option in the configuration file, the command line parameter is preferentially used for startup. ## Features ### Container Image Building `isula-build ctr-img build` The build contains the following flags: - --build-arg: string slice, which is used during the build process - --build-static: string slice. Build binary equivalence. If this parameter is set, all timestamp differences and other build process differences (including the container ID and host name) will be eliminated, and a container image that meets BE requirements will be built. - -f, --filename: string, indicates the path of the Dockerfile. If this parameter is not specified, the Dockerfile in the current path is used - --iidfile: string, output image ID to the local file - -o, --output: string, specifies the image export mode and path - --proxy: bool, which inherits the proxy environment variable on the host side. The default value is true - --tag: string, add tag to the built image #### --build-arg Receive parameters from the command line as parameters in the Dockerfile. Usage: `isula-build ctr-img build --build-arg foo=bar -f Dockerfile` ```bash $ 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 destination Storing 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 The BE (Binary Equivalence) aims to implement repeated build of the same version based on the same source code, environment and ensure that the build results are the same. The BE must meet the following requirements: - The build environment must be consistent, including the operating system, compiler, environment variables, and configuration information - The image storage path in the environment is the same - The build commands are the same - The third-party library versions are the same For container image building, isula-build supports the same Dockerfile. If the build environments are the same, the image content and ID generated after multiple builds are the same. If this parameter is set to BE, all timestamp differences and other build process differences (including the container ID and host name) will be eliminated, and a container image that meets BE requirements will be built. These options are supported by `--build-static` currently: * build-time: string. A fixed timestamp with the format of `YYYY-MM-DD HH-MM-SS` used to build a static image. The timestamp affects the file attributes of creation and modification time in the diff layer. Finally, a container image that meets BE requirements is built. Usage: `isula-build ctr-img build -f Dockerfile --build-static='build-time=2020-05-23 10:55:33' -o docker-archive:./my-image.tar` #### --iidfile Export the built image ID to a file. Usage: `isula-build ctr-img build --iidfile testfile` ```bash $ sudo isula-build ctr-img build -f Dockerfile_arg --iidfile testfile $ cat testfile 76cbeed38a8e716e22b68988a76410eaf83327963c3b29ff648296d5cd15ce7b ``` #### -o, --output Currently, -o, --output supports the following formats: - `isulad:image:tag`: Push the successfully built image to iSulad(The isula-build and iSulad must be on the same node and image must has tag with it) Example: `-o isulad:busybox:latest` - `docker-daemon:image:tag`: Push the successfully built image to Docker daemon(The isula-build and Docker must be on the same node) Example: `-o docker-daemon:busybox:latest` - `docker://registry.example.com/repository:tag`: Push the built image directly to remote image repository Example: `-o docker://docker.io/library/busybox:latest` - `docker-archive:/:image:tag`: Save the built image as a Docker image on the local host Example: `-o docker-archive:/root/image.tar:busybox:latest` In addition, the command line of the build subcommand also receives an argument(string), which indicates the context: the context of the Dockerfile build environment. The default value of this parameter is the current path(`.`) where the isula-build command is executed. This path affects the path searched by the ADD/COPY command of .dockerignore and Dockerfile. #### --proxy Indicates whether the container started by running the RUN command inherits the proxy environment variable "http_proxy","https_proxy","ftp_proxy","no_proxy","HTTP_PROXY","HTTPS_PROXY","FTP_PROXY","NO_PROXY". The default value is true. #### --tag add tag to the built image Usage: `isula-build ctr-img build --tag busybox:latest` ### Viewing a Local Persistent Image We can run the images command to view the image stored locally. ```bash $ sudo isula-build ctr-img images ---------------------------------------------- ----------- ----------------- -------------------------- ------------ REPOSITORY TAG IMAGE ID CREATED SIZE ---------------------------------------------- ----------- ----------------- -------------------------- ------------ docker.io/library/alpine latest a24bb4013296 2020-20-19 19:59:19 5.85 MB 39b62a3342ee 2020-20-19 20:06:38 1.45 MB ---------------------------------------------- ----------- ----------------- -------------------------- ------------ ``` ### Importing a Base Image from a Tarball We can run the `import` command to import a base image into the image store from a tarball. Usage: `isula-build ctr-img import file [REPOSITORY[:TAG]]` ```bash $ sudo isula-build ctr-img import busybox.tar Import success with image id: bf7b3b8ad6d842fb6e0c2dd60727ccb60a86c0e8781a35ae39de5aeef9979189 ``` ```bash $ sudo isula-build ctr-img import busybox.tar busybox:isula Import success with image id: 2d77083e646bf77e25547ea489b00ed8ec318cc37ba81c41e7ec92bca2845033 ``` ### Saving a Local Persistent Image we can run the `save` command to save the image stored locally and make it a tarball. Usage: `isula-build ctr-img save [REPOSITORY:TAG]|imageID -o xx.tar` ```bash $ sudo isula-build ctr-img save busybox:latest -o busybox.tar Save success with image: busybox:latest ``` ```bash $ sudo isula-build ctr-img save 21c3e96ac411 -o busybox.tar Save success with image: 21c3e96ac411 ``` ### Deleting a Local Persistent Image We can run the `rm` command to delete the image stored locally. Currently, the following flags are supported: ```bash Flags: -a, --all remove all images -h, --help help for rm -p, --prune remove all untagged images ``` #### -a, --all Deleting All Images Stored Locally and Persistently #### -p, --prune Deleting All Images That Do Not Have Tags and Are Stored Locally and Persistently Usage: `isula-build ctr-img rm -p` ```bash $ sudo isula-build ctr-img rm -p Deleted: sha256:78731c1dde25361f539555edaf8f0b24132085b7cab6ecb90de63d72fa00c01d Deleted: sha256:eeba1bfe9fca569a894d525ed291bdaef389d28a88c288914c1a9db7261ad12c ``` ### Tag an image We can use the `tag` command to add an additional tag to an image. Usage: `isula-build ctr-img tag / busybox:latest` ```bash $ sudo isula-build ctr-img images ---------------------------------------------- ----------- ----------------- -------------------------- ------------ REPOSITORY TAG IMAGE ID CREATED SIZE ---------------------------------------------- ----------- ----------------- -------------------------- ------------ docker.io/library/alpine latest a24bb4013296 2020-05-29 21:19:46 5.85 MB ---------------------------------------------- ----------- ----------------- -------------------------- ------------ $ sudo isula-build ctr-img tag a24bb4013296 alpine:latest $ sudo isula-build ctr-img images ---------------------------------------------- ----------- ----------------- -------------------------- ------------ REPOSITORY TAG IMAGE ID CREATED SIZE ---------------------------------------------- ----------- ----------------- -------------------------- ------------ docker.io/library/alpine latest a24bb4013296 2020-05-29 21:19:46 5.85 MB localhost/alpine latest a24bb4013296 2020-05-29 21:19:46 5.85 MB ---------------------------------------------- ----------- ----------------- -------------------------- ------------ ``` ### Authentication of the Remote Image Repository We can `login` or `logout` an image repository Login Usage： `isula-build login dockerhub.io` We can run the `login` command to login into an image repository Currently, the following flags are supported: ```bash Flags: -p, --password-stdin Read password from stdin -u, --username string Username to access registry ``` `cat creds.txt | sudo isula-build login -u cooper -p mydockerhub.io` ```bash $ sudo isula-build login mydockerhub.io -u cooper Password: Login Succeeded ``` Logout Usage: `isula-build logout mydockerhub.io` We can run the `logout` command to logout from an image repository Currently, the following flags are supported: ```bash Flags: -a, --all Logout all registries ``` #### -a, --all logout from all registries ```bash $ sudo isula-build logout -a Removed authentications ``` ### Version query We can run the `version` command to view the current version information. ```bash $ sudo isula-build version Client: Version: 0.0.9 Go Version: go1.13.3 Git Commit: c687e4b Built: Thu Jun 11 19:02:45 2020 OS/Arch: linux/amd64 Server: Version: 0.0.9 Go Version: go1.13.3 Git Commit: c687e4b Built: Thu Jun 11 19:02:45 2020 OS/Arch: linux/amd64 ``` ### Show system information We can use the `info` command to view isula-build system information. Currently, the following flags are supported: ```bash Flags: -H, --human-readable print memory info in human readable format, use powers of 1000 ``` #### -H, --human-readable print memory info in human readable format, use powers of 1000 Usage: `isula-build info -H` ```bash $ sudo isula-build info -H General: MemTotal: 10.3 GB MemFree: 2.24 GB SwapTotal: 8.46 GB SwapFree: 8.45 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: docker.io Insecure Registries: localhost:5000 ``` ### Load an image We can use the `load` command to load an image from the tarfile. Usage: `isula-build ctr-img load [flags]` Currently, the following flags are supported: ```bash Flags: -i, --input string Path to local tarball ``` Use this command as follow: ```bash $ sudo isula-build ctr-img load -i image.tar Getting image source signatures Copying blob sha256:37841116ad3b1eeea972c75ab8bad05f48f721a7431924bc547fc91c9076c1c8 Copying blob sha256:6eb4c21cc3fcb729a9df230ae522c1d3708ca66e5cf531713dbfa679837aa287 Copying config sha256:76a4dd2d5d6a18323ac8d90f959c3c8562bf592e2a559bab9b462ab600e9e5fc Writing manifest to image destination Storing signatures Loaded image as 76a4dd2d5d6a18323ac8d90f959c3c8562bf592e2a559bab9b462ab600e9e5fc ```