DOCSEARCHbyAlgolia
Submit Docs

OCI Image Format Specification

repository·main·Indexed 25 days ago

https://github.com/opencontainers/image-spec

The OCI Image Format project defines the standard for container image formats to ensure interoperability between container engines and registries. This specification covers image configuration, layer management (DiffID and ChainID), content-addressable ImageIDs, and standard annotations. It includes the core specification, Go types (specs-go), JSON Schemas, and guidance on converting image configurations to OCI Runtime bundles.

Tokens
13.7K
Snippets
21
Records
78
Agent score
88%

What's inside opencontainers-image-spec

  1. Overview of OCI Image Format Specification

    main

    The OCI Image Format project maintains the specification for software shipping container images. This repository provides the core specification, Go types (specs-go), intra-blob validation tooling, and JSON Schemas (schema).

    Note: The provided Go types and validation tooling are compatible with the current Go release; earlier Go releases are not supported.

  2. Understand OCI Image Configuration

    main
    An OCI Image is an ordered collection of root filesystem changes (layers) and execution parameters. The configuration is defined using the application/vnd.oci.image.config.v1+json media type. This JSON structure is immutable; any change to the configuration results in a new ImageID because the ID is derived from the SHA256 hash of this JSON.

  3. Understand OCI Content Descriptors

    main
    An OCI image is a Merkle Directed Acyclic Graph (DAG) where references between components are expressed through Content Descriptors. A Descriptor describes the disposition of the targeted content, including its type, a unique identifier (digest), and its byte size. Descriptors are used to securely reference external content within other OCI formats using the application/vnd.oci.descriptor.v1+json media type.

  4. Understand the OCI Image Index Specification

    main
    An OCI Image Index is a high-level manifest that points to one or more specific image manifests. It is primarily used to support multiple platforms (e.g., different architectures or operating systems) under a single index. While optional for providers, image consumers SHOULD be prepared to process them. The specification defines the application/vnd.oci.image.index.v1+json media type.

  5. Understand the OCI Image Format components

    main

    An OCI Image is composed of several key components that work together to define a container image. When building or interacting with images, you must account for these elements:

    • Image Manifest: A document describing the components (layers, config, etc.) that make up a container image.
    • Image Index (Optional): An annotated list of manifests, often used to provide different implementations of an image for different platforms.
    • Image Layout: The filesystem layout representing the contents of an image on disk.
    • Filesystem Layers: Changeset archives that, when unpacked, form the final runnable filesystem.
    • Image Configuration: A document that determines layer ordering and provides configuration (like environment variables and arguments) suitable for translation into an OCI Runtime Bundle.
    • Descriptor: A reference describing the type, metadata, and content address of referenced content.
    • Media Types: The specific identifiers used to categorize the content within the specification.

  6. Convert OCI Image Configuration to OCI Runtime Configuration

    main

    When extracting an OCI Image into an OCI Runtime bundle, the application/vnd.oci.image.config.v1+json blob must be converted into an OCI runtime configuration blob.

    A compliant converter MUST create a "default generated runtime configuration" based on the image configuration. This configuration MAY be overridden or combined with externally provided inputs from the caller.

    Key conversion logic includes:

    • Verbatim Fields: Direct mapping of specific fields.
    • Annotation Fields: Mapping image metadata to runtime annotations.
    • Parsed Fields: Translating complex fields like Config.User into runtime-specific structures.

  7. Propose a motion for project changes

    main

    To propose a motion (a formal proposal for change), a maintainer SHOULD use the <dev@opencontainers.org> mailing list. The proposal MUST include another maintainer as a co-sponsor.

    Note: For motions with sensitive security implications, you MUST use the <security@opencontainers.org> mailing list instead.

  8. Apply OCI Layer Changesets

    main

    OCI layers are applied to an existing filesystem rather than just extracted.

    Rules for applying entries:

    • If the target path is a directory and the entry is a directory: The existing directory's attributes MUST be replaced by the attributes in the changeset.
    • For all other cases: The implementation MUST perform the semantic equivalent of:
      1. Removing the existing file path (e.g., unlink(2) on Linux).
      2. Recreating the file path based on the contents and attributes of the changeset entry.
    • Whiteouts: If .wh. entries are present, they must be processed to remove the corresponding files/directories from the target filesystem.

  9. Understand Annotation Precedence Rules

    main

    OCI images can be annotated in three ways:

    1. Config.Labels in the image configuration.
    2. annotations in the image manifest.
    3. annotations in the image index.

    Precedence Rule: If there is a conflict (same key but different value) between an implicit annotation (derived from image config), a manifest annotation, or an index annotation, the value specified in Config.Labels MUST take precedence.

  10. Understand the OCI Image execution workflow

    main

    An OCI implementation typically follows this workflow to run an image:

    1. Download: An OCI implementation downloads an OCI Image.
    2. Unpack: The image is unpacked into an OCI Runtime filesystem bundle (as defined by the OCI Runtime Spec).
    3. Run: The OCI Runtime executes the filesystem bundle.

    The OCI Image Format contains all necessary metadata to launch an application, including commands, arguments, and environment variables.

  11. Representing File Changes in Layers

    main

    OCI layers represent filesystem changesets (Additions, Modifications, and Removals) within a tar archive.

    • Additions and Modifications: These are represented by including the full file or directory in the tar archive.
    • Removals (Whiteouts): To signify that a file or directory must be removed when the layer is applied, use a whiteout file. This is achieved by prefixing the basename of the entry with .wh..

    Example: To remove /etc/my-app-config, the tar archive must contain an entry named ./etc/.wh.my-app-config.

  12. Use Whiteouts to delete files in image layers

    main

    To signify that a path should be deleted in a lower (parent) layer, use a whiteout file. A whiteout file is an empty file with a special filename consisting of the prefix .wh. followed by the basename of the path to be deleted.

    Rules for Whiteouts:

    • A .wh. file without a basename is invalid and should return an error.
    • Whiteout files MUST only apply to resources in lower/parent layers. They cannot hide files present in the same layer.
    • Once applied, the whiteout file itself MUST be hidden.
    • Implementations SHOULD generate layers such that whiteout files appear before sibling directory entries.

    Example: If a base layer contains:

    file1
a/file2
b/
c/file3

    To delete file1, file2, and the directory b/, the next layer should contain:

    .wh.file1
a/.wh.file2
.wh.b
c/file3