OCI backend for Pants

This release targets Pants 2.31.0. Install it with pants-backend-oci==0.10.0 in [GLOBAL].plugins in pants.toml.

Warning This plugin is in development. No stability is guaranteed! Contributions welcome.

This is a backend implementing support for building OCI images in pants; running them, and publishing them to container registries. To do this, this plugin uses three different tools:

• umoci for manipulating OCI images
• runc for exeuction
• skopeo for pulling and pushing images

Tool versions

The defaults are umoci v0.6.0, Skopeo v1.24.1, and runc v1.5.2. umoci uses official Linux binaries and matching macOS builds from tgolsson/umoci-binary. Skopeo binaries come from lework/skopeo-binary, since the Skopeo project does not publish standalone binaries. Both tools cover Linux/macOS on x86-64 and ARM64. runc is Linux-only, with v1.4.3, v1.3.6, and v1.2.9 also recorded. Use [umoci].version, [skopeo].version, or [runc].version to select another recorded version. Stable umoci now supports macOS without selecting the legacy pinned nightly version.

Kustomize injection publishes locally built image dependencies to their configured registry before inserting their image digest. An omitted registry tag defaults to latest.

Planned and missing features

• Currently there's no support for pulling tags, as that would break determinism
• Multi-platform SHA/.sig is untested/unsupported
• Container execution and in-container build steps require Linux (runc).

Targets

There's six targets currently implemented, of which five are generic:

• oci_pull_image
• oci_pull_images
• oci_image_build
• oci_image_empty
• oci_build_layer

And one with some special language semantics:

• oci_python_image - this is the same as oci_image_build, but will prefer to set the entrypoint to .pex files.

oci_pull_image

Pull an image from a repository with a specific digest.

oci_pull_image(
    name="base-python",
    repository="docker.io/library/python",
    sha="b78b777208be08edd8f297035cdfbacddb45170ad778fd643c792ee045187e39"
)

oci_pull_images

Pull multiple shas for an image, generating a target for each. In the below example, we'd get the targets :python#slim and :python#buster.

oci_pull_image(
    name="python",
    repository="docker.io/library/python",
    variants={
       "slim": "f8fbb2370c6314c806b2ddbec8d94375987e16bc122379bef979c6fc5e962920",
       "buster": "97c123c899c8c9ca46248f4002ec4173322e0a1086b386efefac163c64967ba2"
    }
)

oci_build_image

Build an image with the provided packages embedded.

oci_image_build(
    name="my-server",
    base=":python#slim",
    repository="my-registry.example.com/a-namespace/an-image",
    tag="latest",
    packages=[":my_pex"]
)

oci_python_image

Build a Python image with the provided packages embedded.

oci_python_image(
    name="my-server",
    base=":python#slim",
    repository="my-registry.example.com/a-namespace/an-image",
	main="/app/server/start.py",
    tag="latest",
    packages=[":my_pex"]
)

oci_image_empty

An empty base image with no contents at all. This is declared as //:empty automatically, but you can use this to create new targets.

oci_image_empty(
    name="empty",
)

oci_extract

Extract one or more files from another container image.

oci_extract(
    name="my-app-binary"
	base=[":some-app"],
	outputs=['/usr/bin/local/the-app'],
)

oci_build_layer

Run a command in an image, and capture the configured output into a layer artifact, that can be injected into other images. This matches the COPY --from workflows.

oci_build_layer(
    name="layer"
	base=[":rust-1-70"],
    packages=[":files"],
    env=['RUSTC_OPTS=...'],
	commands=['cd /my-package && cargo build --release'],
	outputs=['/my-package/target/release/my-package'],
)