DOCSEARCHbyAlgolia
Submit Docs

SOCI Snapshotter Documentation

repository·main·Indexed 20 days ago

https://github.com/awslabs/soci-snapshotter

SOCI (Seekable OCI) Snapshotter is a containerd plugin that enables lazy loading for OCI images, allowing containers to start without downloading the full image by fetching required data on demand via a SOCI index artifact. It supports Load Order Documents (LODs) for workload-specific optimization, background prefetching, and two index manifest versions (v1 and v2). The project includes the soci-snapshotter-grpc service and a SOCI CLI for creating, converting, and managing indices.

Tokens
36.2K
Snippets
113
Records
160
Agent score
72%

What's inside SOCI Snapshotter

  1. Overview of SOCI Snapshotter

    main

    SOCI (Seekable OCI) Snapshotter is a containerd snapshotter plugin designed to enable lazy loading of standard OCI images.

    Instead of downloading the entire container image before launching a container, SOCI allows the container to start immediately by loading data on demand and prefetching data in the background. This significantly reduces container startup times by avoiding the download of unnecessary image data (which can account for up to 76% of startup time in some scenarios).

    Key features include:

    • No image conversion (v1): SOCI can load from original, unmodified OCI images by building a separate "SOCI index" artifact that lives in the remote registry alongside the image. This avoids modifying CI/CD pipelines and preserves image signatures.
    • Lazy Loading: Data is fetched from the registry only when the application actually accesses it.
    • Background Prefetching: Reduces latency by fetching data in the background.

  2. How SOCI Prefetch works at runtime

    main

    SOCI Prefetch optimizes container startup by warming up critical data before the container starts.

    The Workflow:

    1. Index Build Time: The user specifies files via CLI. SOCI finds the topmost layer for those files, computes the necessary span ranges, and creates a prefetch artifact stored as a separate layer in the SOCI index.
    2. Container Startup (Runtime): When containerd requests a mount via the SOCI Snapshotter, the snapshotter downloads the SOCI Index, zTOC, and the Prefetch Artifacts. It parses the metadata, filters entries matching the current layer, merges overlapping spans, and downloads the specified spans in parallel (best-effort) before the container starts.

    This allows workloads to benefit from sub-file granularity (e.g., reading headers from large files) without requiring full image copies.

  3. Avoid using the term 'SOCI Image'

    main
    In the SOCI ecosystem, there is no such thing as a "SOCI Image". The underlying image remains an unmodified OCI image. When discussing an image that has been prepared for lazy loading, you should refer to the SOCI index itself rather than calling it a SOCI image.

  4. Performance considerations when using SOCI

    main

    SOCI achieves faster container startup by blending the image pull phase with the container run phase. Instead of waiting for a full download, the container starts running while the image is still being pulled in the background.

    When deploying SOCI, be aware of the following performance tradeoffs:

    • Filesystem Latency: Because image pulls happen in parallel with execution, individual filesystem accesses may experience higher latency, especially before the pull completes. Avoid SOCI if your application is highly sensitive to filesystem latency variation.
    • Healthchecks: The total container startup time may increase due to the background pull. You may need to relax healthcheck timeouts to prevent containers from being marked as unhealthy before they have finished initializing.

  5. Understand the zTOC (Compression Table of Contents) format

    main

    A zTOC is a binary file serialized on disk that provides the mapping between files and compressed data spans.

    While the on-disk format is binary, its logical structure includes:

    • version: The zTOC version.
    • build_tool: The tool used to generate the index.
    • size: The size of the layer.
    • span_size: The size of a compression span.
    • num_spans: Total number of spans.
    • num_files: Total number of files.
    • files: An array of file metadata objects. Each object contains:
      • filename: The path of the file.
      • offset: The offset in the uncompressed TAR.
      • size: The file size.
      • type: The file type (e.g., dir, reg).
      • start_span / end_span: The range of compression spans covering this file.

    This structure allows the snapshotter to jump to the correct compression checkpoint (zInfo) and decompress only the necessary span to retrieve a file.

    {
  "version": "0.9",
  "build_tool": "AWS SOCI CLI v0.1",
  "size": 1086672,
  "span_size": 4194304,
  "num_spans": 9,
  "num_files": 4102,
  "num_multi_span_files": 8,
  "files": [
    {
      "filename": "etc/",
      "offset": 512,
      "size": 0,
      "type": "dir",
      "start_span": 0,
      "end_span": 0
    },
    {
      "filename": "var/log/dpkg.log",
      "offset": 34542592,
      "size": 202359,
      "type": "reg",
      "start_span": 8,
      "end_span": 8
    }
  ]
}

  6. Compare SOCI Index Manifest v1 and v2

    main

    SOCI Index Manifest v2 (Recommended)

    Concept: Bundles the SOCI index and image into a single, strongly-linked, multi-architecture image.

    • Pros:
      • Combines SOCI index and image into a single artifact.
      • Image properties are immutable and won't change dynamically without deployments.
      • SOCI index moves across registries automatically with the image.
      • Supports managed rollouts via standard deployment workflows.
      • Shares image content (layers) with the original image, resulting in minimal storage overhead (kilobytes).
    • Cons:
      • Requires managing additional SOCI-enabled images in your registry.

    SOCI Index Manifest v1

    Concept: Uses the OCI Referrers API to discover standalone SOCI index artifacts.

    • Pros:
      • Standalone artifact that can be managed independently of the image.
      • Can be added or removed without affecting the original image.
      • Shares image content with the original image.
    • Cons:
      • Dynamically adding/removing indexes can cause unpredictable runtime changes (e.g., during scaling or redeployment).
      • SOCI indexes are not automatically copied between registries when the image is moved.

  7. How SOCI handles workload-specific load order optimization

    main

    SOCI supports optimizing container launch times through Load Order Documents (LODs). Unlike traditional snapshotters that tie prefetching directly to an image or layer (which can lead to high registry costs and poor cache hits when layers are shared), SOCI decouples the prefetch list from the image/layer artifacts.

    Key features of the LOD approach:

    • Flexibility: A single image can be associated with multiple LODs.
    • Workload-Specific: LODs allow administrators to specify different prefetch patterns based on the specific application running, even if they share the same base layer (e.g., a shared Python3 base layer).
    • Subfile Granularity: LODs can specify individual files or even specific file-segments, which is useful for workloads like machine learning that only need to read small headers from very large files.
    • Retrieval: At container launch time, the appropriate LOD is retrieved using business logic defined by the administrator.

  8. SOCI on Kubernetes Limitations and Requirements

    main

    When using SOCI on Kubernetes, be aware of the following constraints:

    1. Full Node Usage: SOCI must be used for all containers on a node. If an image is pulled using the default OverlayFS and a pod is later scheduled to use SOCI, the pod launch will fail because the image is not present in the SOCI snapshotter.
    2. Node Launch Configuration: SOCI must be configured at the time of node launch. If not, the 'pause' container will be pulled using the default OverlayFS snapshotter, which will prevent SOCI pods from launching as they won't find the pause container in the SOCI snapshotter.
    3. Containerd Version Requirement: For proper storage limit enforcement and garbage collection, ensure you are using containerd >= 1.7.16. Versions prior to this may have bugs where Kubelet calculates SOCI disk utilization incorrectly.

  9. How SOCI Index Manifest v1 discovery works

    main

    SOCI Index Manifest v1 uses the OCI referrers API to associate an index with an image.

    Key behaviors:

    • Automatic Discovery: The SOCI snapshotter checks the registry for a v1 manifest when launching a container and uses it if found.
    • Security Note: Since v1 indexes can be added to a registry independently of the image, support is disabled by default since SOCI v0.10.0. You must explicitly enable it if you intend to use v1 manifests.
    • Registry Interaction: The association is one-way (the index points to the image). If you copy an image between registries, the SOCI index will not be copied automatically. You must explicitly copy the index, or lazy loading will fail.

  10. How SOCI retrieves indices: Referrers API vs Fallback

    main

    The SOCI CLI and snapshotter automatically select the retrieval method based on registry capabilities:

    Referrers API

    When a registry supports the OCI Referrers API, the snapshotter queries a specific registry endpoint for all artifacts referencing a given image digest. This is the preferred, modern method.

    Fallback Mechanism

    For registries lacking the Referrers API, SOCI uses a fallback mechanism where SOCI indices are stored within an OCI Image Index that is tagged with the digest of the manifest it refers to.

    Example Workflow: If an image myregistry.com/image:latest has digest sha:123, the fallback mechanism creates a new image index named myregistry.com/image:sha-123. This index contains the SOCI index descriptor. At runtime, the SOCI snapshotter pulls this fallback index and performs client-side filtering to find the correct SOCI index.

  11. How SOCI snapshotter pull modes work

    main

    The SOCI snapshotter is a remote snapshotter that enables lazy loading of container image contents when a SOCI index is present in the remote registry.

    Pulling Behaviors:

    • With SOCI Index: The snapshotter lazily loads indexed layers. Indexed layers are mounted as a FUSE mountpoint, while non-indexed (sparse) layers are downloaded and uncompressed at launch time like a standard snapshotter.
    • Without SOCI Index: If no index is found, the snapshotter falls back to the default snapshotter behavior (e.g., overlayfs), downloading and uncompressing all image layers at launch time.

    Layer Mounting Summary:

    Layer TypeMechanismBehavior
    Indexed LayerFUSE mountpointLazily loaded while the container is running
    Non-indexed LayerNormal overlay layerSynchronously downloaded at launch time

  12. SOCI Index Manifest Versions

    main

    SOCI supports two versions of the Index Manifest, which determine how images are handled:

    SOCI Index Manifest v1

    • Mechanism: Builds a separate index artifact that lives in the remote registry next to the original, unmodified OCI image.
    • Pros: No build-time conversion required; does not invalidate existing image signatures; works with existing CI/CD pipelines.
    • Cons: May lead to performance changes if an index is added or removed from a widely deployed image.

    SOCI Index Manifest v2

    • Mechanism: Uses a build-time conversion step to produce a new image artifact.
    • Pros: Addresses performance concerns associated with v1.
    • Cons: Requires a conversion step in the pipeline and creates a new image artifact.