Skip to content

cli-usage.md

Latest commit

 

History

History
253 lines (180 loc) · 9.23 KB

cli-usage.md

File metadata and controls

253 lines (180 loc) · 9.23 KB

Using the SOCI CLI

This document provides instructions on how to use the SOCI CLI. And a comprehensive list of all the cli commands in one place.

Global flags

  • --address , -a: Address for containerd's GRPC server
  • --namespace, -n: Namespace to use with commands
  • --timeout: Timeout for commands
  • --debug: Enable debug output
  • --content-store: Use a specific content store (soci or containerd)

CLI commands

soci create

Creates SOCI index for an image (SOCI Index Manifest v1)

Output of this command is SOCI layers and SOCI index stored in a local directory

Note

SOCI layer is named as <image-layer-digest>.soci.layer

SOCI index is named as <image-manifest-digest>.soci.index

This command creates SOCI Index Manifest v1 artifacts. For production use, consider using soci convert to create SOCI Index Manifest v2 enabled images.

Usage: soci create [flags] <image_ref>

Flags:

  • --span-size : Span size that soci index uses to segment layer data. Default is 4MiB
  • --min-layer-size : Minimum layer size to build zTOC for. Smaller layers won't have zTOC and not lazy pulled. Default is 10MiB
  • --force or -f : Force recreate zTOCs for layers even if they already exist. Defaults to false.
  • --optimizations : Enable experimental features by name. Usage is --optimizations opt_name.
    • xattr : When true, adds DisableXAttrs annotation to SOCI index. This annotation often helps performance at pull time.
      • There is currently a bug using this on an image with volume-mounts in a layer without whiteout directories or xattrs. If in doubt, do not use this on images with volume mounts.

Example:

soci create public.ecr.aws/soci-workshop-examples/ffmpeg:latest

soci convert

Converts an OCI image to a SOCI-enabled image (SOCI Index Manifest v2)

This command creates a new SOCI-enabled image that packages the original image and SOCI index into a single, strongly-linked artifact. The SOCI-enabled image can be pushed and deployed like any other image, and the SOCI index will move with it across registries.

Note

SOCI Index Manifest v2 is the recommended approach for production deployments as it provides immutable binding between the image and SOCI index, preventing runtime behavior changes.

Usage: soci convert [flags] <source> <dest>

Flags:

  • --span-size : Span size that soci index uses to segment layer data. Default is 4MiB
  • --min-layer-size : Minimum layer size to build zTOC for. Smaller layers won't have zTOC and not lazy pulled. Default is 10MiB
  • --optimizations : Enable experimental features by name. Usage is --optimizations opt_name.
    • xattr : When true, adds DisableXAttrs annotation to SOCI index. This annotation often helps performance at pull time.
  • --all-platforms : Convert all platforms of a multi-platform image
  • --platform : Convert only the specified platform (e.g., linux/amd64)
  • --standalone : Run in standalone mode without a containerd runtime. Reads an OCI image layout (tar or directory) from disk and writes a converted OCI image layout without requiring a running containerd instance. See Standalone mode below.
  • --format : Output format for standalone mode: oci-archive (tar, default) or oci-dir (directory). Only used with --standalone.

Example:

soci convert public.ecr.aws/soci-workshop-examples/ffmpeg:latest public.ecr.aws/soci-workshop-examples/ffmpeg:latest-soci

Multi-platform example:

soci convert --all-platforms public.ecr.aws/soci-workshop-examples/ffmpeg:latest public.ecr.aws/soci-workshop-examples/ffmpeg:latest-soci

Standalone mode

Standalone mode enables SOCI conversion without a running containerd daemon. This is useful in CI/CD pipelines and other environments where containerd is unavailable or running it would require privileged access.

In standalone mode, <source> and <dest> are file paths (not image references). The source can be an OCI image layout tar archive or directory. The output format is controlled by the --format flag.

Standalone mode does not require containerd, sudo, or any other daemon. You can use tools like skopeo or crane to download and push images.

Note

The input tar or directory must be in OCI image layout format. Docker-style tarballs (e.g., from docker save or crane pull without --format oci) are not compatible.

Tar output format workflow (using skopeo):

skopeo copy docker://public.ecr.aws/soci-workshop-examples/ffmpeg:latest oci-archive:ffmpeg.tar
soci convert --standalone ffmpeg.tar ffmpeg-soci.tar
skopeo copy oci-archive:ffmpeg-soci.tar docker://public.ecr.aws/soci-workshop-examples/ffmpeg:latest-soci

Directory output format workflow (using skopeo):

skopeo copy docker://public.ecr.aws/soci-workshop-examples/ffmpeg:latest oci:ffmpeg-oci
soci convert --standalone --format oci-dir ffmpeg-oci ffmpeg-soci-oci
skopeo copy oci:ffmpeg-soci-oci docker://public.ecr.aws/soci-workshop-examples/ffmpeg:latest-soci

soci push

Push SOCI artifacts to a registry by image reference (SOCI Index Manifest v1 only)

This command pushes SOCI Index Manifest v1 artifacts to the registry. If multiple soci indices exist for the given image, the most recent one will be pushed.

Note

This command only works with SOCI Index Manifest v1 artifacts created by soci create. For SOCI Index Manifest v2, use standard image push commands (e.g., nerdctl push) on the SOCI-enabled image created by soci convert.

Usage: soci push [flags] <image_ref>

After pushing the soci artifacts, they should be available in the registry. Soci artifacts will be pushed only if they are available in the snapshotter's local content store.

Flags:

  • --max-concurrent-uploads: Max concurrent uploads. Default is 3.
  • --quiet, -q: Enable quiet mode

Example:

soci push public.ecr.aws/soci-workshop-examples/ffmpeg:latest

soci rebuild_db

Use after pulling an image to discover SOCI indices/ztocs or after "index rm" when using the containerd content store to clear the database of removed zTOCs.

Example:

soci rebuild_db

soci index

Manage indices

Sub commands:

  • info : Get detailed info about an index.

    Usage: soci index info <index-digest>

    Example:

    soci index info sha256:5c0f5cb700f596d

  • list, ls : List indices

    Flags:

    • --ref : Filter indices to those that are associated with a specific image ref
    • --quiet, -q: Only display the index digests
    • --platform, -p: Filter indices to a specific platform

    Example:

    soci index ls

  • remove, rm : Remove an index from local db, and from content store if supported Usage: soci index rm <digest> Flags:

    • --ref : Only remove indices that are associated with a specific image ref

    Example:

    soci index rm sha256:5c0f5cb700f596d

soci ztoc

Sub commands:

  • info : Get detailed info about a ztoc

    Usage: soci ztoc info <digest>

  • list, ls : List ztocs

    Flags:

    • --ztoc-digest: Filter ztocs by digest
    • --image-ref : Filter ztocs to those that are associated with a specific image
    • --quiet, -q : Only display the index digests

    Example:

    soci ztoc ls

  • get-file: Retrieve a file from a local image layer using a specified ztoc

    Usage: soci ztoc get-file <digest> <file>

    Flags:

    • --output, -o : The file to write the extracted content. Defaults to stdout

    Example:

    soci ztoc get-file sha256:5c0f5cb700f596d index.js

  • info : Get detailed info about a ztoc

    Usage: soci ztoc info <digest>

    Example:

    soci ztoc info sha256:5c0f5cb700f596d

soci prefetch

Manage prefetch artifacts that define which spans should be prefetched for lazy-loaded layers.

Subcommands:

  • ls (or list): List all prefetch artifacts

    Usage: soci prefetch ls [flags]

    Flags:

    • --json: Output in JSON format

    Output columns:

    • DIGEST: The digest of the prefetch artifact
    • LAYER DIGEST: The digest of the layer this prefetch artifact applies to
    • SPANS: Total number of spans to prefetch
    • CREATED: When the prefetch artifact was created (relative time)

    Example:

    soci prefetch ls

  • info: Display detailed information about a prefetch artifact

    Usage: soci prefetch info [flags] <digest>

    Arguments:

    • <digest>: The digest of the prefetch artifact to inspect

    Flags:

    • --json: Output raw JSON

    Example:

    soci prefetch info sha256:f8715bbab4e73d8f282010f4c0eb1a9ed863e95a7bc3e2cd0c8e332569ebe233