ocibuild_index (ocibuild v0.10.4)

View Source

ocibuild_index - OCI Image Index creation and manipulation.

This module handles OCI Image Index (multi-platform manifest list) operations. An image index allows a single tag to reference multiple platform-specific images.

See: https://github.com/opencontainers/image-spec/blob/main/image-index.md

Summary

Types

index()
manifest_descriptor()
platform()

Functions

create(PlatformManifests)

Create an OCI image index from a list of platform-specific manifest descriptors.

matches_platform(Platform, Target)

Check if a platform matches a target platform.

media_type()

Return the OCI media type for image indexes.

parse(JsonBinary)

Parse a JSON binary into an image index.

select_manifest/2

Select a manifest descriptor matching the given platform.

to_json/1

Serialize an image index to JSON binary.

Types

index()

-opaque index()

manifest_descriptor()

-type manifest_descriptor() ::
          #{media_type := binary(),
            digest := binary(),
            size := non_neg_integer(),
            platform := platform(),
            annotations => map()}.

platform()

-type platform() :: ocibuild:platform().

Functions

create(PlatformManifests)

-spec create([{platform(), Digest :: binary(), Size :: non_neg_integer()}]) -> index().

Create an OCI image index from a list of platform-specific manifest descriptors.

Each descriptor is a tuple of {Platform, ManifestDigest, ManifestSize}.

Index = ocibuild_index:create([
    {#{os => ~"linux", architecture => ~"amd64"}, ~"sha256:abc...", 1234},
    {#{os => ~"linux", architecture => ~"arm64"}, ~"sha256:def...", 1235}
]).

matches_platform(Platform, Target)

-spec matches_platform(platform(), platform()) -> boolean().

Check if a platform matches a target platform.

Matches are based on OS and architecture. If the target specifies a variant, that must also match.

Example:

true = ocibuild_index:matches_platform(
    #{os => ~"linux", architecture => ~"amd64"},
    #{os => ~"linux", architecture => ~"amd64"}
).

media_type()

-spec media_type() -> binary().

Return the OCI media type for image indexes.

parse(JsonBinary)

-spec parse(binary()) -> {ok, index()} | {error, term()}.

Parse a JSON binary into an image index.

{ok, Index} = ocibuild_index:parse(JsonBinary).

select_manifest/2

-spec select_manifest(index(), platform()) -> {ok, manifest_descriptor()} | {error, not_found}.

Select a manifest descriptor matching the given platform.

Returns the first manifest that matches both OS and architecture. If the platform specifies a variant, that is also matched.

{ok, Descriptor} = ocibuild_index:select_manifest(Index,
    #{os => ~"linux", architecture => ~"arm64"}).

to_json/1

-spec to_json(index()) -> binary().

Serialize an image index to JSON binary.

The output conforms to the OCI Image Index specification.