- Notifications
You must be signed in to change notification settings - Fork0
Standalone, daemon-less, unprivileged Dockerfile and OCI compatible container image builder.
License
yaraskm/img
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Standalone, daemon-less, unprivileged Dockerfile and OCI compatiblecontainer image builder.
img is more cache-efficient than Docker and can also execute multiple build stages concurrently,as it internally usesBuildKit's DAG solver.
The commands/UX are the same asdocker {build,tag,push,pull,login,logout,save} so all youhave to do is replacedocker withimg in your scripts, command line, and/or life.
Table of Contents
This a glorified cli tool built on top ofbuildkit. The goal of this project is to beable to build container images as an unprivileged user.
Running unprivileged allows companies who use LDAP and other login mechanismsto useimg without needing root. This is very important in HPC environmentsand academia as well.
Currently this works out of the box on a Linux machine if you install viathe directions covered ininstalling from binaries. Thisinstallation will ensure you have the correct version ofimg and alsorunc.
The ultimate goal is to also have this work inside a container. There arepatches being made to container runtimes and Kubernetes to make this possible.For the on-going work toward getting patches into container runtimes andKubernetes, see:
- moby/moby#36644merged
- docker/cli#1347merged
- kubernetes/community#1934merged
- kubernetes/kubernetes#64283merged
The patches for runc has been merged into the upstream sinceecd55a4135e0a26de884ce436442914f945b1e76 (May 30, 2018).The upstream BuildKit can also run in rootless mode since65b526438b86a17cf35042011051ce15c8bfb92a (June 1, 2018).
You might also be interested in reading:
If you are curious about benchmarks comparing various container builders, checkout@AkihiroSuda's buildbenchresults.
You need to havenewuidmap installed. On Ubuntu,newuidmap is provided by theuidmap package.
You also need to haveseccomp installed. On Ubuntu,seccomp is provided by thelibseccomp-dev package.
runc will be installed on start from an embedded binary if it is not alreadyavailable locally. If you would like to disable the embedded runc you can useBUILDTAGS="seccomp noembed" while building from source withmake. Or the environment variableIMG_DISABLE_EMBEDDED_RUNC=1 on execution of theimg binary.
NOTE: These steps work only for Linux. Compile and run in a container(explained below) if you're on Windows or MacOS.
For installation instructions from binaries please visit theReleases Page.
$ mkdir -p$GOPATH/src/github.com/genuinetools$ git clone https://github.com/genuinetools/img$GOPATH/src/github.com/genuinetools/img$cd!$$ make$ sudo make install# For packagers if you would like to disable the embedded `runc`, please use:$ make BUILDTAGS="seccomp noembed"
There is anAPKBUILD.
$apk add imgThere is anAUR build.
#Use whichever AUR helper you prefer$yay -S img#Or build from thesource PKGBUILD$git clone https://aur.archlinux.org/packages/img.git$cd img$makepkg -si
There is anebuild.
$sudo emerge -a app-emulation/imgDocker imager.j3ss.co/img is configured to be executed as an unprivileged user with UID 1000 and it does not need--privileged sinceimg v0.5.11.
$docker run --rm -it \ --name img \ --volume $(pwd):/home/user/src:ro \ # for the build context and dockerfile, can be read-only since we won't modify it --workdir /home/user/src \ # set the builder working directory --volume "${HOME}/.docker:/root/.docker:ro" \ # for credentials to push to docker hub or a registry --security-opt seccomp=unconfined --security-opt apparmor=unconfined \ # required by runc r.j3ss.co/img build -t user/myimage .
To enable PID namespace isolation (which disallows build containers tokill(2) theimg process), you need to specify--privileged so that build containers can mount/proc with unshared PID namespaces.Note that even with--privileged,img works as an unprivileged user with UID 1000.
Seedocker/cli patch for how to allow mounting/proc without--privileged.
Sinceimg v0.5.11, you don't need to specify anysecurityContext for runningimg as a Kubernetes container.
However the following security annotations are needed:
container.apparmor.security.beta.kubernetes.io/img: unconfinedcontainer.seccomp.security.alpha.kubernetes.io/img: unconfinedTo enable PID namespace isolation, you need to setsecurityContext.procMount toUnmasked (or simply setsecurityContext.privileged totrue).securityContext.procMount is available since Kubernetes 1.12 with Docker 18.06/containerd 1.2/CRI-O 1.12.
Make sure you have user namespace support enabled. On some distros (Debian andArch Linux) this requires runningecho 1 > /proc/sys/kernel/unprivileged_userns_clone.
$img -himg - Standalone, daemon-less, unprivileged Dockerfile and OCI compatible container image builderUsage: img [OPTIONS] COMMAND [ARG...]Flags: -b, --backend string backend for snapshots ([auto native overlayfs fuse-overlayfs]) (default "auto") -d, --debug enable debug logging -h, --help help for img -s, --state string directory to hold the global state (default "/home/user/.local/share/img") -v, --version Print version information and quitCommands: build Build an image from a Dockerfile du Show image disk usage. help Help about any command login Log in to a Docker registry. logout Log out from a Docker registry. ls List images and digests. prune Prune and clean up the build cache. pull Pull an image or a repository from a registry. push Push an image or a repository to a registry. rm Remove one or more images. save Save an image to a tar archive (streamed to STDOUT by default). tag Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE. unpack Unpack an image to a rootfs directory. version Show the version information.Use "img [command] --help" for more information about a command.
$img build -hbuild - Build an image from a DockerfileUsage: img build [OPTIONS] PATHFlags: --build-arg list Set build-time variables --cache-from list Buildkit import-cache or Buildx cache-from specification --cache-to list Buildx cache-to specification -f, --file string Name of the Dockerfile (Default is 'PATH/Dockerfile') -h, --help help for build --label list Set metadata for an image --no-cache Do not use cache when building the image --no-console Use non-console progress UI -o, --output string BuildKit output specification (e.g. type=tar,dest=build.tar) --platform list Set platforms for which the image should be built -t, --tag list Name and optionally a tag in the 'name:tag' format --target string Set the target build stage to buildGlobal Flags: -b, --backend string backend for snapshots ([auto native overlayfs fuse-overlayfs]) (default "auto") -d, --debug enable debug logging -s, --state string directory to hold the global state (default "/home/user/.local/share/img")
Use just like you woulddocker build.
$img build -t r.j3ss.co/img.Building r.j3ss.co/img:latestSetting up the rootfs... this may take a bit.[+] Building 44.7s (16/16) FINISHED => local://dockerfile (Dockerfile) 0.0s => => transferring dockerfile: 1.15kB 0.0s => local://context (.dockerignore) 0.0s => => transferring context: 02B 0.0s => CACHED docker-image://docker.io/tonistiigi/copy:v0.1.1@sha256:854cee92ccab4c6d63 0.0s => => resolve docker.io/tonistiigi/copy:v0.1.1@sha256:854cee92ccab4c6d63183d147389e 0.0s => CACHED docker-image://docker.io/library/alpine@sha256:e1871801d30885a610511c867d 0.0s => => resolve docker.io/library/alpine@sha256:e1871801d30885a610511c867de0d6baca7ed 0.0s => docker-image://docker.io/library/golang:1.10-alpine@sha256:98c1f3458b21f50ac2e58 5.5s => => resolve docker.io/library/golang:1.10-alpine@sha256:98c1f3458b21f50ac2e5896d1 0.0s => => sha256:866414f805391b58973d4e3d76e5d32ae51baecb1c93762c9751b9d6c5 126B / 126B 0.0s => => sha256:ae8dbf6f23bf1c326de78fc780c6a870bf11eb86b45a7dc567 308.02kB / 308.02kB 0.0s => => sha256:44ccce322b34208317d748e998212cd677c16f1a58c2ff5e59578c 3.86kB / 3.86kB 0.0s => => sha256:0d01df27c53e651ecfa5c689dafb8c63c759761a757cc37e30eccc5e3a 153B / 153B 0.0s => => sha256:ff3a5c916c92643ff77519ffa742d3ec61b7f591b6b7504599d95a 2.07MB / 2.07MB 0.0s => => sha256:4be696a8d726150ed9636ea7156edcaa9ba8293df1aae49f9e 113.26MB / 113.26MB 0.0s => => sha256:98c1f3458b21f50ac2e5896d14a644eadb3adcae5afdceac0cc9c2 2.04kB / 2.04kB 0.0s => => sha256:bb31085d5c5db578edf3d4e5541cfb949b713bb7018bbac4dfd407 1.36kB / 1.36kB 0.0s => => unpacking docker.io/library/golang:1.10-alpine@sha256:98c1f3458b21f50ac2e5896 5.4s => local://context 0.8s => => transferring context: 116.83MB 0.8s => /bin/sh -c apk add --no-cache bash build-base gcc git libseccomp-dev linux 3.8s => copy /src-0 go/src/github.com/genuinetools/img/ 1.5s => /bin/sh -c go get -u github.com/jteeuwen/go-bindata/... 7.3s => /bin/sh -c make static && mv img /usr/bin/img 15.2s => /bin/sh -c git clone https://github.com/opencontainers/runc.git "$GOPATH/src/git 7.6s => /bin/sh -c apk add --no-cache bash git shadow shadow-uidmap strace 2.3s => copy /src-0/img usr/bin/img 0.5s => copy /src-0/runc usr/bin/runc 0.4s => /bin/sh -c useradd --create-home --home-dir $HOME user && chown -R user:user $H 0.4s => exporting to image 1.5s => => exporting layers 1.4s => => exporting manifest sha256:03e034afb839fe6399a271efc972da823b1b6297ea792ec94fa 0.0s => => exporting config sha256:92d033f9575176046db41f4f1feacc0602c8f2811f59d59f8e7b6 0.0s => => naming to r.j3ss.co/img:latest 0.0sSuccessfully built r.j3ss.co/img:latest
img and the underlyingbuildkit library support building containers for arbitrary platforms (OS and architecture combinations). Inimg this can be achieved using the--platform option, but note thatusing theRUN command during a build requires installing support for the desired platform, and anyFROM images used must exist for the target platform as well.
Some common platforms include:
- linux/amd64
- linux/arm64
- linux/arm/v7
- linux/arm/v6
- linux/s390x
- linux/ppc64le
- darwin/amd64
- windows/amd64
If you use multiple--platform options for the same build, they will be included into amanifest and should work for the different platforms built for.
The most common way to getRUN working in cross-platform builds is to install an emulator such as QEMU on the host system (static bindings are recommended to avoid shared library loading issues). To properly use the emulator inside the build environment, the kernelbinfmt_misc parameters must be set with the following flags:OCF.You can check the settings in/proc to ensure they are set correctly.
$cat /proc/sys/fs/binfmt_misc/qemu-arm| grep flagsflags: OCF
On Debian/Ubuntu the above should be available with theqemu-user-static package >=1:2.12+dfsg-3
NOTE: cross-OS builds are slightly more complicated to getRUN commands working, but follow from the same principle.
img can also use buildkit'sexporter types directly to output theresulting image to a Docker-type bundle or a rootfs tar without saving the imageitself locally. Builds will still benefit from caching.
The output type and destination are specified with the--output flag. The listof valid output specifications includes:
| flag | description |
|---|---|
-o type=tar,dest=rootfs.tar | export rootfs of target image to a tar archive |
-o type=tar | output a rootfs tar to stdout, for use in piped commands |
-o type=docker,dest=image.tar | save a Docker-type bundle of the image |
-o type=oci,dest=image.tar | save an OCI-type bundle of the image |
-o type=local,dest=rootfs/ | export the target image to this directory |
-o type=image,name=r.j3ss.co/img | build and tag an image and store it locally |
When used in conjunction with a Dockerfile which has a finalFROM scratch stage andonly copies files of interest from earlier stages withCOPY --from=..., this can beutilized to output arbitrary build artifacts for example.
$img ls -hls - List images and digests.Usage: img ls [OPTIONS]Flags: -f, --filter list Filter output based on conditions provided -h, --help help for lsGlobal Flags: -b, --backend string backend for snapshots ([auto native overlayfs fuse-overlayfs]) (default "auto") -d, --debug enable debug logging -s, --state string directory to hold the global state (default "/home/user/.local/share/img")
$img lsNAME SIZE CREATED AT UPDATED AT DIGESTjess/img:latest 1.534KiB 9 seconds ago 9 seconds ago sha256:27d862ac32022946d61afbb91ddfc6a1fa2341a78a0da11ff9595a85f651d51ejess/thing:latest 591B 30 minutes ago 30 minutes ago sha256:d664b4e9b9cd8b3067e122ef68180e95dd4494fd4cb01d05632b6e77ce19118e
If you need to use self-signed certs with your registry, seeUsing Self-Signed Certs with a Registry.
$img pull -hpull - Pull an image or a repository from a registry.Usage: img pull [OPTIONS] NAME[:TAG|@DIGEST]Flags: -h, --help help for pullGlobal Flags: -b, --backend string backend for snapshots ([auto native overlayfs fuse-overlayfs]) (default "auto") -d, --debug enable debug logging -s, --state string directory to hold the global state (default "/home/user/.local/share/img")
$img pull r.j3ss.co/stressPulling r.j3ss.co/stress:latest...Snapshot ref: sha256:2bb7a0a5f074ffe898b1ef64b3761e7f5062c3bdfe9947960e6db48a998ae1d6Size: 365.9KiB
If you need to use self-signed certs with your registry, seeUsing Self-Signed Certs with a Registry.
$img push -hpush - Push an image or a repository to a registry.Usage: img push [OPTIONS] NAME[:TAG]Flags: -h, --help help for push --insecure-registry Push to insecure registryGlobal Flags: -b, --backend string backend for snapshots ([auto native overlayfs fuse-overlayfs]) (default "auto") -d, --debug enable debug logging -s, --state string directory to hold the global state (default "/home/user/.local/share/img")
$img push jess/thingPushing jess/thing:latest...Successfully pushed jess/thing:latest
$img tag -htag - Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE.Usage: img tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]Flags: -h, --help help for tagGlobal Flags: -b, --backend string backend for snapshots ([auto native overlayfs fuse-overlayfs]) (default "auto") -d, --debug enable debug logging -s, --state string directory to hold the global state (default "/home/user/.local/share/img")
$img tag jess/thing jess/otherthingSuccessfully tagged jess/thing as jess/otherthing
$img save -hsave - Save an image to a tar archive (streamed to STDOUT by default).Usage: img save [OPTIONS] IMAGE [IMAGE...]Flags: --format string image output format (docker|oci) (default "docker") -h, --help help for save -o, --output string write to a file, instead of STDOUTGlobal Flags: -b, --backend string backend for snapshots ([auto native overlayfs fuse-overlayfs]) (default "auto") -d, --debug enable debug logging -s, --state string directory to hold the global state (default "/home/user/.local/share/img")
$img save jess/thing| docker load6c3d70c8619c: Loading layer [==================================================>] 9.927MB/9.927MB7e336c441b5e: Loading layer [==================================================>] 5.287MB/5.287MB533fecff21a8: Loading layer [==================================================>] 2.56MB/2.56MB3db7019eac28: Loading layer [==================================================>] 1.679kB/1.679kBLoaded image: jess/thing
$img unpack -hunpack - Unpack an image to a rootfs directory.Usage: img unpack [OPTIONS] IMAGEFlags: -h, --help help for unpack -o, --output string Directory to unpack the rootfs to. (defaults to rootfs/ in the current working directory)Global Flags: -b, --backend string backend for snapshots ([auto native overlayfs fuse-overlayfs]) (default "auto") -d, --debug enable debug logging -s, --state string directory to hold the global state (default "/home/user/.local/share/img")
$img unpack busyboxSuccessfully unpacked rootfs for busybox to: /home/user/rootfs
$img rm -hrm - Remove one or more images.Usage: img rm [OPTIONS] IMAGE [IMAGE...]Flags: -h, --help help for rmGlobal Flags: -b, --backend string backend for snapshots ([auto native overlayfs fuse-overlayfs]) (default "auto") -d, --debug enable debug logging -s, --state string directory to hold the global state (default "/home/user/.local/share/img")
$img du -hdu - Show image disk usage.Usage: img du [OPTIONS]Flags: -f, --filter list Filter output based on conditions provided -h, --help help for duGlobal Flags: -b, --backend string backend for snapshots ([auto native overlayfs fuse-overlayfs]) (default "auto") -d, --debug enable debug logging -s, --state string directory to hold the global state (default "/home/user/.local/share/img")
$img duID RECLAIMABLE SIZE DESCRIPTIONsha256:d9a48086f223d28a838263a6c04705c8009fab1dd67cc82c0ee821545de3bf7c true 911.8KiB pulled from docker.io/tonistiigi/copy@sha256:476e0a67a1e4650c6adaf213269a2913deb7c52cbc77f954026f769d51e1a14e7ia86xm2e4hzn2u947iqh9ph2 true 203.2MiB mount /dest from exec copy /src-0 /dest/go/src/github.com/genuinetools/img...sha256:9f131fba0383a6aaf25ecd78bd5f37003e41a4385d7f38c3b0cde352ad7676da true 958.6KiB pulled from docker.io/library/golang:alpine@sha256:a0045fbb52a7ef318937e84cf7ad3301b4d2ba6cecc2d01804f428a1e39d1dfcsha256:c4151b5a5de5b7e272b2b6a3a4518c980d6e7f580f39c85370330a1bff5821f1 true 472.3KiB pulled from docker.io/tonistiigi/copy@sha256:476e0a67a1e4650c6adaf213269a2913deb7c52cbc77f954026f769d51e1a14esha256:ae4ecac23119cc920f9e44847334815d32bdf82f6678069d8a8be103c1ee2891 true 148.9MiB pulled from docker.io/library/debian:buster@sha256:a7789365b226786a0cb9e0f142c515f9f2ede7164a6f6be4a1dc4bfe19d5ec9cbkrjrzv3nvp7lvzd5cw9vzut7* true 4.879KiB local source for dockerfilesha256:db193011cbfc238d622d65c4099750758df83d74571e8d7498392b17df381207 true 467.2MiB pulled from docker.io/library/golang:alpine@sha256:a0045fbb52a7ef318937e84cf7ad3301b4d2ba6cecc2d01804f428a1e39d1dfcwn4m5i5swdcjvt1ud5bvtr75h* true 4.204KiB local source for dockerfileReclaimable: 1.08GiBTotal: 1.08GiB
$img prune -hprune - Prune and clean up the build cache.Usage: img prune [OPTIONS]Flags: -h, --help help for pruneGlobal Flags: -b, --backend string backend for snapshots ([auto native overlayfs fuse-overlayfs]) (default "auto") -d, --debug enable debug logging -s, --state string directory to hold the global state (default "/home/user/.local/share/img")
$img pruneID RECLAIMABLE SIZE DESCRIPTIONj1yil8bdz35eyxp0m17tggknd true 5.08KiB local source for dockerfileje23wfyz2apii1au38occ8zag true 52.95MiB mount / from exec /bin/sh -c useradd --create-home...sha256:74906c0186257f2897c5fba99e1ea87eb8b2ee0bb03b611f5e866232bfbf6739 true 2.238MiB pulled from docker.io/tonistiigi/copy:v0.1.1@sha25...vr2pvhmrt1sjs8n7jodesrvnz* true 572.6MiB mount / from exec /bin/sh -c git clone https://git...afn0clz11yphlv6g8golv59c8 true 4KiB local source for contextqx5yql370piuscuczutrnansv* true 692.4MiB mount / from exec /bin/sh -c make static && mv img...uxocruvniojl1jqlm8gs3ds1e* true 113.8MiB local source for contextsha256:0b9cfed6a170b357c528cd9dfc104d8b404d08d84152b38e98c60f50d2ae718b true 1.449MiB pulled from docker.io/tonistiigi/copy:v0.1.1@sha25...vz0716utmnlmya1vhkojyxd4o true 55.39MiB mount /dest from exec copy /src-0/runc usr/bin/run...a0om6hwulbf9gd2jfgmxsyaoa true 646.5MiB mount / from exec /bin/sh -c go get -u github.com/...ys8y9ixi3didtbpvwbxuptdfq true 641.2MiB mount /dest from exec copy /src-0 go/src/github.co...sha256:f64a552a56ce93b6e389328602f2cd830280fd543ade026905e69895b5696b7a true 1.234MiB pulled from docker.io/tonistiigi/copy:v0.1.1@sha25...05wxxnq6yu5nssn3bojsz2mii true 52.4MiB mount /dest from exec copy /src-0/img usr/bin/imgwlrp1nxsa37cixf127bh6w2sv true 35.11MiB mount / from exec /bin/sh -c apk add --no-cache b...wy0173xa6rkoq49tf9g092r4z true 527.4MiB mount / from exec /bin/sh -c apk add --no-cache b...Reclaimed: 4.148GiBTotal: 4.148GiB
If you need to use self-signed certs with your registry, seeUsing Self-Signed Certs with a Registry.
$img login -hlogin - Log in to a Docker registry.Usage: img login [OPTIONS] [SERVER]Flags: -h, --help help for login -p, --password string Password --password-stdin Take the password from stdin -u, --username string UsernameGlobal Flags: -b, --backend string backend for snapshots ([auto native overlayfs fuse-overlayfs]) (default "auto") -d, --debug enable debug logging -s, --state string directory to hold the global state (default "/home/user/.local/share/img")
$imglogout -hlogout - Log out from a Docker registry.Usage: img logout [SERVER]Flags: -h, --help help for logoutGlobal Flags: -b, --backend string backend for snapshots ([auto native overlayfs fuse-overlayfs]) (default "auto") -d, --debug enable debug logging -s, --state string directory to hold the global state (default "/home/user/.local/share/img")
We do not allow users to pass all the custom certificate flags on commandsbecause it is unnecessarily messy and can be handled through Linux itself.Which we believe is a better user experience than having to pass threedifferent flags just to communicate with a registry using self-signed orprivate certificates.
Below are instructions on adding a self-signed or private certificate to yourtrusted ca-certificates on Linux.
Make sure you have the packageca-certificates installed.
Copy the public half of your CA certificate (the one user to sign the CSR) intothe CA certificate directory (as root):
$cp cacert.pem /usr/share/ca-certificatesRebuild the directory with your certificate included, run as root:
#On debian, this will bring up a menu.#Select the ask option, scroll to the certificate you are adding,#mark itfor inclusion, andselectok.$dpkg-reconfigure ca-certificates#On other distros...$update-ca-certificates
To mount a filesystem without root accsess,img automatically invokesnewuidmap(1)/newgidmap(1)SUID binaries to prepare SUBUIDs/SUBGIDs, which is typically required byapt.
Make sure you have sufficient entries (typically>=65536) in your/etc/subuid and/etc/subgid.
Theauto backend selects a backend based on what the current system supports,preferringoverlayfs, thenfuse-overlayfs, thennative.
Thenative backend creates image layers by simply copying files.copy_file_range(2) is used when available.
Theoverlayfs backend uses the kernel's native overlayfs support. It requiresa kernel patch from Ubuntu to be unprivileged, see#22.
Thefuse-overlayfs backend provides overlay support without any kernelpatches. It requires a Linux kernel >= 4.18 and forfuse-overlayfs to be installed.
Please do! This is a new project and can use some love <3. Check out theissues.
The local directories are mostly re-implementations ofbuildkit interfaces tobe unprivileged.
A lot of this is based on the work ofmoby/buildkit.Thanks@tonistiigi and@AkihiroSuda!
About
Standalone, daemon-less, unprivileged Dockerfile and OCI compatible container image builder.
Resources
License
Stars
Watchers
Forks
Packages0
Languages
- Go80.3%
- C10.2%
- Makefile6.1%
- Shell1.8%
- Dockerfile1.6%