Container Image Building

• Container Image Building
  • Overview
  • Installation
    • Preparations
      • Installing isula-build
  • Configuring and Managing the isula-build Service
    • Configuring the isula-build Service
    • Managing the isula-build Service
      • (Recommended) Using systemd for Management
      • Directly Running isula-builder
  • Usage Guidelines
    • Prerequisites
    • Overview
    • ctr-img: Container Image Management
      • build: Container Image Build
      • image: Viewing Local Persistent Build Images
      • import: Importing a Basic Container Image
      • load: Importing Cascade Images
      • rm: Deleting a Local Persistent Image
      • save: Exporting Cascade Images
      • tag: Tagging Local Persistent Images
      • pull: Pulling an Image To a Local Host
      • push: Pushing a Local Image to a Remote Repository
    • info: Viewing the Operating Environment and System Information
    • login: Logging In to the Remote Image Repository
    • logout: Logging Out of the Remote Image Repository
    • version: Querying the isula-build Version
    • manifest: Manifest List Management
      • create: Manifest List Creation
      • annotate: Manifest List Update
      • inspect: Manifest List Inspect
      • push: Manifest List Push to the Remote Repository.
  • Directly Integrating a Container Engine
    • Integration with iSulad
    • Integration with Docker
  • Precautions
    • Constraints or Limitations
    • Differences with "docker build"
  • Appendix
    • Command Line Parameters
    • Communication Matrix
    • File and Permission

Overview

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 to process client management requests, and runs as a daemon process in the background.

Note:

• Currently, isula-build supports OCI image format (OCI Image Format Specification) and Docker image format (Image Manifest Version 2, Schema 2). Use the export ISULABUILD_CLI_EXPERIMENTAL=enabled command to enable the experimental feature for supporting OCI image format. When the experimental feature is disabled, isula-build will take Docker image format as the default image format. Otherwise, isula-build will take OCI image format as the default image format.

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 an isula-build-*.rpm installation package from the openEuler Yum source, for example, isula-build-0.9.5-6.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:

• /etc/isula-build/storage.toml: configuration file for local persistent storage, including the configuration of the storage driver in use.

For more settings, see containers-storage.conf.5.md.

• /etc/isula-build/registries.toml: configuration file for each image repository.

For more settings, see containers-registries.conf.5.md.

• /etc/isula-build/policy.json: image pull/push policy file. Note: Currently, this parameter cannot be configured.

Note:

• isula-build supports the preceding configuration file with the maximum size of 1 MB.
• The persistent working directory dataroot cannot be configured on the memory disk, for example, tmpfs.
• Currently, only overlay2 can be used as the underlying storage driver.
• Before setting the --group option, ensure that the corresponding user group has been created on a local OS and non-privileged users have been added to the group. After isula-builder is restarted, non-privileged users in the group can use the isula-build function. In addition, to ensure permission consistency, the owner group of the isula-build configuration file directory /etc/isula-build is set to the group specified by --group.

Managing the isula-build Service

Currently, openEuler uses systemd to manage the isula-build service. The isula-build software package contains the systemd service files. 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.

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:

  sudo systemctl start isula-build.service
  

• Run the following command to stop the isula-build service:

  sudo systemctl stop isula-build.service
  

• Run the following command to restart the isula-builder service:

  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.

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.
• --group: sets the owner group for the local socket file isula_build.sock so that non-privileged users in the group can use isula-build. The default owner group is isula.
• --experimental: whether to enable experimental features.

Note:

• If the command line parameters contain the same configuration items 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:

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 instruction in the Dockerfile. Therefore, 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.

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.

sudo yum install -y docker-engine

Note:

• 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 commands:

• 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.
  • pull: pulls an image to a local host.
  • push: pushes a local image to a remote repository.
• 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.
• manifest (experimental): manages the manifest list.

Note:

• The isula-build completion and isula-builder completion commands are used to generate the bash command completion script. These commands are implicitly provided by the command line framework and is not displayed in the help information.
• isula-build client does not have any configuration file. To use isula-build experimental features, enable the environment variable ISULABUILD_CLI_EXPERIMENTAL on the client using the export ISULABUILD_CLI_EXPERIMENTAL=enabled command.

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 format 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 format is as follows:

isula-build ctr-img build [flags]

The build command contains the following flags:

• --build-arg: string list containing 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 indicating that a container image is built at a specified timestamp. The timestamp format is YYYY-MM-DD HH-MM-SS.
• -f, --filename: string indicating the path of the Dockerfiles. If this parameter is not specified, the current path is used.
• --format: string indicating the image format oci or docker (ISULABUILD_CLI_EXPERIMENTAL needs to be enabled).
• --iidfile: string indicating a local file to which the ID of the image is output.
• -o, --output: string indicating the image export mode and path.
• --proxy: boolean, which inherits the proxy environment variable on the host. The default value is true.
• --tag: string indicating the tag value of the image that is successfully built.
• --cap-add: string list containing permissions required by the RUN instruction during the build process.

The following describes the flags in detail.

--build-arg

Parameters in the Dockerfile are inherited from the commands. The usage is as follows:

$ 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

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 key=value 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:

  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.

--format

This option can be used when the experiment feature is enabled. The default image format is oci. You can specify the image format to build. For example, the following commands are used to build an OCI image and a Docker image, respectively.

export ISULABUILD_CLI_EXPERIMENTAL=enabled; sudo isula-build ctr-img build -f Dockerfile --format oci .

export ISULABUILD_CLI_EXPERIMENTAL=enabled; sudo isula-build ctr-img build -f Dockerfile --format docker .

--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:

sudo isula-build ctr-img build -f Dockerfile_arg --iidfile testfile

Check the container image ID in the testfile file.

$ 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. The following restrictions apply:

  • 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. The following restrictions apply:

• 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 in Docker image format, for example, -o docker://localhost:5000/library/busybox:latest.

• docker-archive:<path>/<filename>: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.

When experiment feature is enabled, you can build image in OCI image format with:

• oci://registry.example.com/repository:tag: directly pushes the successfully built image to the remote image repository in OCI image format(OCI image format should be supported by the remote repository), for example, -o oci://localhost:5000/library/busybox:latest.

• oci-archive:<path>/<filename>:image:tag: saves the successfully built image to the local host in OCI image format, for example, -o oci-archive:/root/image.tar:busybox:latest.

In addition to the 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 instructions of the .dockerignore file and Dockerfile.

--proxy

Specifies whether the container started by the RUN instruction inherits the proxy-related environment variables http_proxy, https_proxy, ftp_proxy, no_proxy, HTTP_PROXY, HTTPS_PROXY, and FTP_PROXY. The default value 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 running on different terminals, the environment variables of the terminal where the daemon is running are inherited.

--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 instruction during the build process:

isula-build ctr-img build --cap-add ${CAP}

Example:

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 MB.
• isula-build supports a .dockerignore file with a maximum size of 1 MB.
• 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 instruction starts the container to build in the container. Currently, isula-build supports the host network only.
• isula-build only supports the tar 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 instruction 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 isula-builder.
• Currently, isula-build does not support a remote URL as the data source of the ADD instruction in the Dockerfile.
• The local tar package exported using the docker-archive and oci-archive types are not compressed, you can manually compress the file as required.

image: Viewing Local Persistent Build Images

You can run the images command to view the images in the local persistent storage.

$ sudo isula-build ctr-img images
---------------------------------------  -----------  -----------------  ------------------------  ------------
REPOSITORY                               TAG          IMAGE ID           CREATED                   SIZE
---------------------------------------  -----------  -----------------  ------------------------  ------------
localhost:5000/library/alpine            latest       a24bb4013296       2022-01-17 10:02:19       5.85 MB
<none>                                   <none>       39b62a3342ee       2022-01-17 10:01:12       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 packages and traversing the diff directory. Therefore, the statistics are different.

import: Importing a Basic Container Image

A tar file in rootfs form can be imported into isula-build via the ctr-img import command.

The command format is as follows:

isula-build ctr-img import [flags]

Example:

$ sudo isula-build ctr-img import busybox.tar mybusybox:latest
Getting image source signatures
Copying blob sha256:7b8667757578df68ec57bfc9fb7754801ec87df7de389a24a26a7bf2ebc04d8d
Copying config sha256:173b3cf612f8e1dc34e78772fcf190559533a3b04743287a32d549e3c7d1c1d1
Writing manifest to image destination
Storing signatures
Import success with image id: "173b3cf612f8e1dc34e78772fcf190559533a3b04743287a32d549e3c7d1c1d1"
$ sudo isula-build ctr-img images
---------------------------------------  -----------  -----------------  ------------------------  ------------
REPOSITORY                               TAG          IMAGE ID           CREATED                   SIZE
---------------------------------------  -----------  -----------------  ------------------------  ------------
mybusybox                                latest       173b3cf612f8       2022-01-12 16:02:31       1.47 MB
---------------------------------------  -----------  -----------------  ------------------------  ------------

Note

• isula-build supports the import of container basic images with a maximum size of 1 GB.

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 format is as follows:

isula-build ctr-img load [flags]

Currently, the following flags are supported:

• -i, --input: path of the local .tar package.

Example:

$ sudo isula-build ctr-img load -i ubuntu.tar
Getting 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

Note:

• isula-build allows you to import a container image with a maximum size of 50 GB.
• isula-build automatically recognizes the image format and loads it from the cascade image file.

rm: Deleting a Local Persistent Image

You can run the rm command to delete an image from the local persistent storage. The command format 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:

$ 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 format is as follows:

isula-build ctr-img save [REPOSITORY:TAG]|imageID -o xx.tar

Currently, the following flags are supported:

• -f, --format: which indicates the exported image format: oci or docker (ISULABUILD_CLI_EXPERIMENTAL needs to be enabled)
• -o, --output: which indicates the local path for storing the exported images.

The following example shows how to export an image using image/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

The following example shows how to export an image using 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

The following example shows how to export multiple images to the same tarball:

$ sudo isula-build ctr-img save busybox:latest nginx:latest -o all.tar
Getting image source signatures
Copying blob sha256:eb78099fbf7fdc70c65f286f4edc6659fcda510b3d1cfe1caa6452cc671427bf
Copying blob sha256:29f11c413898c5aad8ed89ad5446e89e439e8cfa217cbb404ef2dbd6e1e8d6a5
Copying blob sha256:af5bd3938f60ece203cd76358d8bde91968e56491daf3030f6415f103de26820
Copying config sha256:b8efb18f159bd948486f18bd8940b56fd2298b438229f5bd2bcf4cedcf037448
Writing manifest to image destination
Storing signatures
Getting image source signatures
Copying blob sha256:e2d6930974a28887b15367769d9666116027c411b7e6c4025f7c850df1e45038
Copying config sha256:a33de3c85292c9e65681c2e19b8298d12087749b71a504a23c576090891eedd6
Writing manifest to image destination
Storing signatures
Save success with image: [busybox:latest nginx:latest]

NOTE:

• Save exports an image in .tar format by default. If necessary, you can save the image and then manually compress it.
• When exporting an image using image name, specify the entire image name in the REPOSITORY:TAG format.

tag: Tagging Local Persistent Images

You can run the tag command to add a tag to a local persistent container image. The command format is as follows:

isula-build ctr-img tag <imageID>/<imageName> busybox:latest

Example:

$ 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
---------------------------------------  -----------  -----------------  ------------------------  ------------

pull: Pulling an Image To a Local Host

Run the pull command to pull an image from a remote image repository to a local host. Command format:

isula-build ctr-img pull REPOSITORY[:TAG]

Example:

$ sudo isula-build ctr-img pull example-registry/library/alpine:latest
Getting image source signatures
Copying blob sha256:8f52abd3da461b2c0c11fda7a1b53413f1a92320eb96525ddf92c0b5cde781ad
Copying config sha256:e4db68de4ff27c2adfea0c54bbb73a61a42f5b667c326de4d7d5b19ab71c6a3b
Writing manifest to image destination
Storing signatures
Pull success with image: example-registry/library/alpine:latest

push: Pushing a Local Image to a Remote Repository

Run the push command to push a local image to a remote repository. Command format:

isula-build ctr-img push REPOSITORY[:TAG]

Currently, the following flags are supported:

• -f, --format: indicates the pushed image format oci or docker (ISULABUILD_CLI_EXPERIMENTAL needs to be enabled)

Example:

$ sudo isula-build ctr-img push example-registry/library/mybusybox:latest
Getting image source signatures
Copying blob sha256:d2421964bad195c959ba147ad21626ccddc73a4f2638664ad1c07bd9df48a675
Copying config sha256:f0b02e9d092d905d0d87a8455a1ae3e9bb47b4aa3dc125125ca5cd10d6441c9f
Writing manifest to image destination
Storing signatures
Push success with image: example-registry/library/mybusybox:latest

NOTE:

• Before pushing an image, log in to the corresponding image repository.

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 format 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.
• -V, --verbose: Boolean. The memory usage is displayed during system running.

Example:

$ 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
   Runtime:
   MemSys:           68.4 MB
     HeapSys:          63.3 MB
     HeapAlloc:        7.41 MB
     MemHeapInUse:     8.98 MB
     MemHeapIdle:      54.4 MB
     MemHeapReleased:  52.1 MB

login: Logging In to the Remote Image Repository

You can run the login command to log in to the remote image repository. The command format 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.

 $ cat creds.txt | sudo isula-build login -u cooper -p mydockerhub.io
 Login Succeeded

Enter the password in interactive mode.

 $ 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 format is as follows:

 isula-build logout [SERVER] [FLAGS]

Currently, the following flags are supported:

 Flags:
   -a, --all   Logout all registries

Example:

 $ 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.

 $ sudo isula-build version
 Client:
   Version:       0.9.5
   Go Version:    go1.15.7
   Git Commit:    b82408f
   Built:         Tue Mar 30 11:08:00 2021
   OS/Arch:       linux/amd64

 Server:
   Version:       0.9.5
   Go Version:    go1.15.5
   Git Commit:    64dbad50
   Built:         Mon Apr 12 20:30:31 2021
   OS/Arch:       linux/amd64

manifest: Manifest List Management

The manifest list contains the image information corresponding to different system architectures. You can use the same manifest (for example, openeuler:latest) in different architectures to obtain the image of the corresponding architecture. The manifest contains the create, annotate, inspect, and push subcommands.

NOTE:

• manifest is an experiment feature. When using this feature, you need to enable the experiment options on the client and server. For details, see Client Overview and Configuring Services.

create: Manifest List Creation

The create subcommand of the manifest command is used to create a manifest list. The command format is as follows:

isula-build manifest create MANIFEST_LIST MANIFEST [MANIFEST...]

You can specify the name of the manifest list and the remote images to be added to the list. If no remote image is specified, an empty manifest list is created.

Example:

sudo isula-build manifest create openeuler localhost:5000/openeuler_x86:latest localhost:5000/openeuler_aarch64:latest

annotate: Manifest List Update

The annotate subcommand of the manifest command is used to update the manifest list. The command format is as follows:

isula-build manifest annotate MANIFEST_LIST MANIFEST [flags]

You can specify the manifest list to be updated and the images in the manifest list, and use flags to specify the options to be updated. This command can also be used to add new images to the manifest list.

Currently, the following flags are supported:

• --arch: Applicable architecture of the rewritten image. The value is a string.
• --os: Indicates the applicable system of the image. The value is a string.
• --os-features: Specifies the OS features required by the image. This parameter is a string and rarely used.
• --variant: Variable of the image recorded in the list. The value is a string.

Example:

sudo isula-build manifest annotate --os linux --arch arm64 openeuler:latest localhost:5000/openeuler_aarch64:latest

inspect: Manifest List Inspect

The inspect subcommand of the manifest command is used to query the manifest list. The command format is as follows:

isula-build manifest inspect MANIFEST_LIST

Example:

$ sudo isula-build manifest inspect openeuler:latest
{
    "schemaVersion": 2,
    "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
    "manifests": [
        {
            "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
            "size": 527,
            "digest": "sha256:bf510723d2cd2d4e3f5ce7e93bf1e52c8fd76831995ac3bd3f90ecc866643aff",
            "platform": {
                "architecture": "amd64",
                "os": "linux"
            }
        },
        {
            "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
            "size": 527,
            "digest": "sha256:f814888b4bb6149bd39ba8375a1932fb15071b4dbffc7f76c7b602b06abbb820",
            "platform": {
                "architecture": "arm64",
                "os": "linux"
            }
        }
    ]
}

push: Manifest List Push to the Remote Repository

The manifest subcommand push is used to push the manifest list to the remote repository. The command format is as follows:

isula-build manifest push MANIFEST_LIST DESTINATION

Example:

sudo isula-build manifest push openeuler:latest localhost:5000/openeuler:latest

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:

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.

$ sudo isula images
isula images
REPOSITORY                     TAG        IMAGE ID             CREATED              SIZE
busybox                        2.0        2d414a5cad6d         2020-08-01 06:41:36  5.577 MB

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/lib/isula-build/tmp/[build_id]/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/lib/isula-build/tmp/[build_id]/isula-build-tmp-%v.tar file.

Integration with Docker

Images that are successfully built can be directly exported to the Docker daemon.

Example:

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.

$ sudo docker images
REPOSITORY                                          TAG                 IMAGE ID            CREATED             SIZE
busybox                                             2.0                 2d414a5cad6d        2 months ago        5.22MB

Note:

• The isula-build and Docker must be on the same node.

Precautions

This chapter is something about constraints, limitations and differences with docker build when use isula-builder build images.

Constraints or Limitations

1. When export an image to iSulad, a tag is necessary.
2. Because the OCI runtime, for example, runc, will be called by isula-builder when executing the RUN instruction, the integrity of the runtime binary should be guaranteed by the user.
3. DataRoot should not be set to tmpfs.
4. Overlay2 is the only storage driver supported by isula-builder currently.
5. Docker image is the only image format supported by isula-builder currently.
6. You are advised to set file permission of the Dockerfile to 0600 to avoid tampering by other users.
7. Only host network is supported by the RUN instruction currently.
8. When export image to a tar package, only tar compression format is supported by isula-builder currently.
9. The base image size is limited to 1 GB when importing a base image using import.

Differences with "docker build"

isula-build complies with Dockerfile specification, but there are also some subtle differences between isula-builder and docker build as follows:

1. isula-builder commits after each build stage, but not every line.
2. Build cache is not supported by isula-builder.
3. Only RUN instruction will be executed in the build container.
4. Build history is not supported currently.
5. Stage name can be start with a number.
6. The length of the stage name is limited to 64 in isula-builder.
7. ADD instruction source can not be a remote URL currently.
8. Resource restriction on a single build is not supported. If resource restriction is required, you can configure a resource limit on isula-builder.
9. isula-builder add each origin layer tar size to get the image size, but docker only uses the diff content of each layer. So the image size listed by isula-builder images is different.
10. Image name should be in the NAME:TAG format. For example busybox:latest, where latest must not be omitted.

Appendix

Command Line Parameters

Table 1 Parameters of the ctr-img build command

Table 2 Parameters of the ctr-img load command

Table 3 Parameters of the ctr-img push command

Table 4 Parameters of the ctr-img rm command

Table 5 Parameters of the ctr-img save command

Table 6 Parameters of the login command

Table 7 Parameters of the logout command

Table 8 Parameters of the manifest annotate command

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. To perform operations as a non-privileged user, you need to configure the --group option.

• The following table lists the file permissions involved in the running of isula-build.