release: add optional OCI images

This adds three OCI archive format files to the release containing
FreeBSD base images suitable for static linked, dynamic linked and shell
workloads. The shell image also contains pkg-bootstrap and can be easily
extended by installing packages (including pkgbase packages).

Reviewed by: dch, cpersiva, jlduran, zlei
Differential Revision: https://reviews.freebsd.org/D46759
MFC after: 2 days

4 files changed, 53 insertions, 1 deletions

diff --git a/share/examples/Makefile b/share/examples/Makefile
index 58f5a2109ec3..560fdae6de5b 100644
--- a/share/examples/Makefile
+++ b/share/examples/Makefile
@@ -21,6 +21,7 @@ LDIRS=	BSD_daemon \
 	libvgl \
 	mdoc \
 	netgraph \
+	oci \
 	perfmon \
 	ppi \
 	ppp \
@@ -199,6 +200,11 @@ SE_NETGRAPH= \
 	virtual.chain \
 	virtual.lan \
 
+SE_DIRS+=	oci
+SE_OCI= \
+	README \
+	Containerfile.pkg
+
 SE_DIRS+=	perfmon
 SE_PERFMON= \
 	Makefile \
diff --git a/share/examples/oci/Containerfile.pkg b/share/examples/oci/Containerfile.pkg
new file mode 100644
index 000000000000..ed8ac7caf4b6
--- /dev/null
+++ b/share/examples/oci/Containerfile.pkg
@@ -0,0 +1,27 @@
+# This is an example showing how to extend the freebsd-minimal OCI image by
+# installing additional packages while keeping the resulting image as small as
+# possible.
+
+# The OS version matching the desired freebsd-minimal image
+ARG version=15.0-CURRENT-amd64
+
+# Select freebsd-minimal as our starting point.
+FROM localhost/freebsd-minimal:${version}
+
+# A list of package(s) to install
+ARG packages
+
+# Install package management tools. We specify 'FreeBSD' as the repository to
+# use for downloading pkg since the freebsd-minimal image has both FreeBSD and
+# FreeBSD-base pkg repo configs installed and FreeBSD-base does not contain the
+# pkg package.
+RUN env ASSUME_ALWAYS_YES=yes pkg bootstrap -r FreeBSD && pkg update
+
+# Install some package(s).
+RUN pkg install -y ${packages}
+
+# Clean up and remove package management overhead. We delete downloaded
+# packages, uninstall pkg and delete the repository metadata downloaded by 'pkg
+# install'.  This retains the record of which packages are installed in the
+# image.
+RUN pkg clean -ay && pkg delete -fy pkg && rm -rf /var/db/pkg/repos
diff --git a/share/examples/oci/README b/share/examples/oci/README
new file mode 100644
index 000000000000..212687251754
--- /dev/null
+++ b/share/examples/oci/README
@@ -0,0 +1,7 @@
+This example Containerfile shows how to add packages to freebsd-minimal while
+minimising the package metadata overhead.
+
+For instance, To build a new image called 'my-new-image:latest' containing the
+nginx package:
+
+# podman build --squash --build-arg packages=nginx --tag my-new-image:latest -f Containerfile.pkg
diff --git a/share/man/man7/release.7 b/share/man/man7/release.7
index c81f540d9463..5c5c11efd0fb 100644
--- a/share/man/man7/release.7
+++ b/share/man/man7/release.7
@@ -22,7 +22,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd August 6, 2023
+.Dd September 26, 2024
 .Dt RELEASE 7
 .Os
 .Sh NAME
@@ -443,6 +443,18 @@ values, run:
 cd /usr/src
 make -C release list-cloudware
 .Ed
+.Sh OCI IMAGES
+The
+.Fx
+release build tools have experimental support for building
+Open Container Initiative (OCI) format container base images.
+This is enabled using a
+.Fa release.conf
+variable:
+.Bl -tag -width Ev
+.It Va WITH_OCIIMAGES
+Set to a non-null value to build OCI base images.
+.El
 .Sh MAKEFILE TARGETS
 The release makefile
 .Pq Pa src/release/Makefile