Crate container_registry

container-registry

The container-registry crate implements a minimal “best effort” container registry suitable for plugging into axum.

Feature set and standard conformity

This crate has been cleaned up and factored out from the small PaaS rockslide, its feature set represents the requirements of said software. While it tries to follow the OCI distribution and manifest specifications, it was primarily written while reverse engineering real requests from podman and Docker, thus while it may violate the specification some ways, it is certain to cover the basic use cases when using either tool.

The core functionality covered by this crate consists of

• authentication via HTTP basic auth,
• image uploading via podman or docker,
• image downloading via podman or docker, and
• storing container images on the local filesystem.

Dependencies

An image registry cannot exist outside a web framework, unless it were to ship one itself. The framework underlying this crate is axum for now; wile support for other frameworks could be added with reasonable effort, no such work has been done at this time.

Production readiness

The crate has not been thoroughly battle tested in contested production environments, or seen a deep review, so relying on it for mission critical deployments is probably a bad idea. At this point, it should make a reasonable drop-in replacement for other registries that are not publically accessible and can likely fulfill its role in system level tests.

Use as a binary

container-registry includes a bare-bones installable binary that exposes most of its features from the command line. It is automatically built if the bin features is enabled:

cargo install container-registry --features bin

Use a library

To use this crate as a library, use the ContainerRegistry type. Here is a minimal example, supplying a unit value (()) to indicate it does not use any hooks, and true as the auth provider, which will accept any username and password combination as valid:

use container_registry::auth;
use sec::Secret;

// The registry requires an existing (empty) directory, which it will initialize.
let storage = tempdir::TempDir::new("container_registry_test")
    .expect("could not create storage dir");

// Setup an auth scheme that allows uploading with a master password, read-only
// access otherwise.
let auth = Arc::new(auth::Anonymous::new(
    auth::Permissions::ReadOnly,
    Secret::new("master password".to_owned())
));

// Instantiate the registry.
let registry = container_registry::ContainerRegistry::builder()
    .storage(storage.path())  // Note: When testing, use `build_for_testing` instead.
    .auth_provider(auth)
    .build()
    .expect("failed to instantiate registry");

// Create an axum app router and mount our new registry on it.
let app = Router::new()
    .merge(registry.make_router())
    // 1 GB body limit.
    .layer(DefaultBodyLimit::max(1024 * 1024 * 1024));

Afterwards, app can be launched via axum::serve(), see its documentation for details.

Modules

auth

Authentication backends.

hooks

Notification hooks for registry changes.

storage

Storage backends.

test_support

Testing support.

Structs

ContainerRegistry

A container registry storing OCI containers.

ContainerRegistryBuilder

Builder for a new instance of the container registry.

ImageDigest

An image hash.

Enums

ImageDigestParseError

Error parsing a specific image digest.

RegistryError

A container registry error.