jelipo/ocipack-rs

🚅 Quickly build simple Docker/OCI images without runtime

ocipack

一个可以快速构建 OCI/Docker 镜像的工具

特性

• 在没有Docker/Containerd等容器引擎环境下构建简单镜像
• 兼容 Dockerfile 大部分配置项，降低上手难度
• 支持 OCI 和 Docker 镜像格式，并支持互相转换
• 支持镜像Pull和Push时使用 socks5/http 代理
• 一个单独的二进制，Linux下静态编译无依赖，alpine也可使用
• 支持 Windows MacOS Linux 三个平台的使用
• 支持性能非常好的zstd解压缩算法

下载和安装

Linux 和 MacOS

curl -L https://github.com/jelipo/ocipack-rs/releases/download/0.6.0/ocipack-0.6.0-amd64_$(uname).tar.gz | tar xzv

# 把下载解压完成的 `ocipack` 放到 `/usr/local/bin/` （可选操作）
sudo cp ocipack /usr/local/bin/ &&  sudo chmod +x /usr/local/bin/ocipack

Windows

curl.exe -L https://github.com/jelipo/ocipack-rs/releases/download/0.6.0/ocipack-0.6.0-amd64_windows.zip -o ocipack.zip

tar -xf ocipack.zip

简介

作者在学习云原生和写代码的时候，经常需要构建一个简单的镜像，但是有时候会因为各种原因导致并不轻松。

• 着急开发，但是没有Docker/Containerd等环境。
• 居家办公需要连接VPN到组织的网络中，但是 Windows 和 MacOS 使用虚拟机运行Docker，这意味着虚拟机中的Docker 无法通过宿主的VPN网络Pull和Push镜像。
• Linux服务器上，Docker/Containerd 等引擎在构建时拉取公共镜像因为众所周知的原因速度非常慢。即使有socks5/http 代理，但是服务器上可能还有正在运行的容器化进程，配置代理意味着可能要重启，且整个容器引擎都会走代理，一般是不可接受的，况且频繁配置也很麻烦。
• CI/CD环境中，你可能可以使用Docker多阶段构建、CI工具提供的环境构建一个镜像并打包成Image并上传到Registry中。
  通常这是两个步骤:构建产物和构建成镜像并Push，但是有时候CI环境并不如我们的意(可能没有容器环境、只有Docker in Docker 无法Push 等问题)，而且需要学习每个CI环境来完成我们的这两个步骤。
  如果有一个通用的工具可以把产物构建成镜像并Push到Registry就可以大大提升我们对不同CI环境的兼容。

针对以上问题，所以写了一个小工具去解决这些问题。
也有很多别的工具可以解决，重复造轮子的目的，也是为了加深Rust的编写能力和Image知识。

限制

因为本工具没有任何Runtime，所以Dockerfile配置项中需要Runtime支持的一律无法正常支持。
为了便于上手使用，本工具只是使用常见的Dockerfile作为配置，降低使用门槛，但并不是完全兼容Dockerfile

	Filed
支持的配置项	FROM LABEL CMD COPY ENV USER WORKDIR EXPOSE
暂不支持但未来会支持	ADD(可以暂时用COPY代替) ENTRYPOINT VOLUME
不会支持	ARG RUN MAINTAINER
多阶段构建	不支持

目前的Image Manifest主流为Docker，但是Docker Manifest格式也分为多个版本，本工具对于Docker格式只支持Image Manifest V 2, Schema 2 ，对于老版本的Image Manifest V 2, Schema 1 不支持，也不计划进行支持。

版本	是否支持
Image Manifest V 2, Schema 2	✅
Image Manifest V 2, Schema 1	❌
OCI Image Manifest	✅

使用举例

很多时候，我们需要的功能只是把文件COPY进Base Image，然后运行。

创建一个Dockerfile文件，这个Dockerfile 既是我们构建Image的配置文件，也是我们计划运行我们构建好的镜像时打印内容的文件。写入以下内容:

FROM ubuntu:22.04
COPY Dockerfile /root/
CMD cat /root/Dockerfile

接着运行以下命令：

./ocipack build \
  --source=dockerfile:./Dockerfile \
  --target=registry:my.harbor.com/jelipo/demo:v1 \
  --target-auth=jelipo:my_password

如果顺利，末尾将会输出:

Build job successful!

Target image:
my.harbor.com/jelipo/demo:v1

当看到Build job successful字样时，说明我们已经构建完成并上传到了Registry。

接下来我们执行docker run -it --rm my.harbor.com/jelipo/demo:v1时会输出我们的Dockerfile文件的内容。

拉取镜像并打包成文件

如果只需要下载镜像保存到文件，可以把 --target参数改为 tgz:file_path，还可以使用socks5代理访问。

./ocipack build \
  --source=registry:redis:latest \
  --target=tgz:redis.tgz \
  --source-proxy=socks5://127.0.0.1:1080

功能

构建（Build）

最主要的功能，拉取Base Image，然后把文件COPY进Image，然后Push。
使用ocipack build子命令。

# 当base image的registry为http而非https时需要启用
-a, --allow-insecure 
        Allow insecure registry 
# 连接超时时间
    --conn-timeout <CONN_TIMEOUT>
        [OPTION] Connection timeout in seconds [default: 600]
# 新Image的格式
-f, --format <FORMAT>
        [OPTION] Target format type. Support 'docker' and 'oci' [default: docker]
# 指定Dockerfile的路径
-s, --source <SOURCE>
        Source type. Support dockerfile type Example:'dockerfile:/path/to/.Dockerfile'
# Base Image的auth验证信息，支持环境变量
    --source-auth <SOURCE_AUTH>
        [OPTION] Auth of pull source image. Example:'myname:mypass','myname:${MY_PASSWORD_ENV}'
# Base Image的代理信息
    --source-proxy <SOURCE_PROXY>
        [OPTION] Proxy of pull source image.
        Example:'socks5://127.0.0.1:1080','http://name:pass@example:8080'
 # Target Image的信息
-t, --target <TARGET>
        Target type. Support registry/tar/tgz. Example:'registry:my.container.com/target/image:1.1','tgz:image.tgz'
# 当Target Image的Registry为http而非https时需要启用
    --target-allow-insecure
        Allow target insecure registry 
# Target Image的auth验证信息，支持环境变量
    --target-auth <TARGET_AUTH>
        [OPTION] Auth of push target image. Example:'myname:mypass','myname:${MY_PASSWORD_ENV}'
# Target Image的代理信息
    --target-proxy <TARGET_PROXY>
        [OPTION] Proxy of push target image.
        Example:'socks5://127.0.0.1:1080','http://name:pass@example:8080'
# 新layer使用zstd压缩，zstd拥有更好的 解压缩速度 和 压缩比（很多Runtime不支持zstd，谨慎使用）
    --use-zstd
        [OPTION] Compress files using zstd

可能遇到的问题

Base Image 拉取非常慢

如果是hub.docker.com中的公共镜像，因为网络原因本身就很慢，可以使用--source-proxy设置一个代理加速访问。

Pull 或 Push 的 Registry 不支持HTTPS协议

目前大多数容器引擎或者工具都会默认使用HTTPS访问Registry，但是很多内网或者学习使用时会使用HTTP协议的 Registry 。

当 Pull 镜像的Registry是HTTP协议，添加--allow-insecure选项。

如果 Push 的Registry是HTTP协议，添加--target-allow-insecure选项。

执行命令后，在Linux history中会显示我的密码

本工具支持从环境变量中读取密码，可以在build子命令的help中看--source-auth或者--target-auth的说明。

构建出来的Image是Docker Manifest格式的，想要OCI格式的

添加--format=oci选项。

转换(Transform)

此功能主要是为了 Docker和OCI 之间的转换。主要命令跟build子命令大同小异，可以参考上面的构建（Build）。
可以使用ocipack transform -h查看详情。

清理缓存(Clean)

因为无论 Pull 还是 Push ，都会需要缓存到本地，以便下次 Pull 时的加速。

可以使用ocipack clean子命令清理本地的缓存文件夹，可以使用ocipack clean -h查看更多参数选项。

查看Image信息(Show Info)

当你想查看Registry中的Image信息，但是又无从下手的时候，可以使用此命令查看详细信息。

例如ocipack show-info -i registry:nginx:latest查看nginx:latest的详细信息。

挖坑

• 支持导出或者导入本地的容器引擎。
• 更多的Dockerfile配置项。
• 创建新Image时提供 使用zstd压缩所有layer。
  

最后

感谢使用，如有问题请反馈。