pants-backend-oci 0.8.0

An OCI plugin for the Pants build system

OCI backend for Pants

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

Planned and missing features

• Currently there's no support for pulling tags, as that would break determinism
• Multi-platform SHA/.sig is untested/unsupported
• skopeo doesn't support MacOS, preventing pulling and pushing images.
• No "in-container" build steps

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"
)

Argument	Meaning	Default value
name	The target name	Same as any other target, which is the directory name
repository	Fully qualified repository name	Required
sha	The digest of the image, minus the @sha: prefix.	Required
anonymous	Whether to pull the image anonymously.	false
decsription	A description of the target
tags	List of tags	[]

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"
    }
)

Argument	Meaning	Default value
name	The target name	Same as any other target, which is the directory name
repository	Fully qualified repository name	Required
variants	Dictionary with local tags to the remote sha	Required
anonymous	Whether to pull the image anonymously	false
decsription	A description of the target
tags	List of tags	[]

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"]
)

Argument	Meaning	Default value
name	The target name	Same as any other target, which is the directory name
base	The base image to use. Matches the FROM directive in a Dockerfile	Required
packages	Packaged targets to include. The first element will be used as the entrypoint.	[]
repository	Fully qualified repository name	Required when publishing
tag	Remote tag to use	Required when publishing
decsription	A description of the target
tags	List of tags	[]

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"]
)

Argument	Meaning	Default value
name	The target name	Same as any other target, which is the directory name
base	The base image to use. Matches the FROM directive in a Dockerfile	Required
packages	Packaged targets to include. The first element will be used as the entrypoint.	[]
python_main	The main file to run	The last .pex in the dependency list
repository	Fully qualified repository name	Required when publishing
tag	Remote tag to use	Required when publishing
decsription	A description of the target
tags	List of tags	[]

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",
)

Argument	Meaning	Default value
name	The target name	Same as any other target, which is the directory name
decsription	A description of the target
tags	List of tags	[]

oci_build_layer

Run an image command, 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=...'], command=['cd /my-package && cargo build --release'], outputs=['/my-package/target/release/my-package'], )

| Argument      | Meaning                                                                        | Default value                                          |
|---------------|--------------------------------------------------------------------------------|--------------------------------------------------------|
| `name`        | The target name                                                                | Same as any other target, which is the directory name  |
| `packages`    | Packaged targets to include. The first element will be used as the entrypoint. | `[]`                                                   |
| `env`         | Environment variables to set. Does not support interpolation.                  | `[]`                                                   |
| `outputs`     | Paths to capture into the built layer.                                         | `[]`                                                   |
| `exclude`     | Globs to not include in the output.                                            | `[]`                                                   |
| `decsription` | A description of the target                                                    |                                                        |
| `output_path` | The output path during `pants package`                                         | A variant generated from the target name and directory |
| `tags`        | List of tags                                                                   | `[]`                                                   |