DOCSEARCHbyAlgolia
Submit Docs

ORAS (OCI Registry As Storage)

repository·main·Indexed 24 days ago

https://github.com/oras-project/oras

ORAS is a CLI tool designed to interact with OCI registries to push and pull non-container artifacts, such as Helm charts and WebAssembly modules. It provides commands for managing artifacts, including push, pull, copy, backup, and restore, as well as specialized tools for managing blobs, manifests, and referrers via the `oras attach` and `oras discover` commands.

Tokens
23.1K
Snippets
57
Records
121
Agent score
81%

What's inside ORAS

  1. Scenarios for managing multi-platform artifacts with ORAS

    main

    ORAS is designed to handle several multi-platform management workflows that traditional tools like docker or docker buildx struggle with (such as requiring remote registries or being unavailable in air-gapped environments).

    Key supported scenarios include:

    • Local Filesystem Creation: Assembling a multi-arch image by creating an OCI image index that references architecture-specific images already stored locally. This is ideal for air-gapped environments.
    • Registry-only Creation: Assembling a multi-arch image using arch-specific images already pushed to a remote registry, without downloading them to the local filesystem.
    • Hybrid Creation: Combining architecture-specific images from both a local filesystem and a remote registry into a single OCI image index.
    • Updating Existing Images: Retrieving an existing multi-arch image, modifying the index (replacing or adding architectures), and pushing the updated version back to a local filesystem or registry.
    • Non-container Artifacts: Building multi-platform indexes for other artifact types by correctly populating the artifactType property in the index manifest and child descriptors.

  2. Recommended error message structure for ORAS CLI

    main

    When generating error messages for the ORAS CLI, follow this structured format to ensure they are helpful and actionable for the user:

    {Error|Error response from registry}: {Error description (HTTP status code can be printed out if any)}
[Usage: {Command usage}]
[{Recommended solution}]

    Component Details:

    • Error/Error response from registry: The primary error identifier. Use Error response from registry if the error originates from the server side.
    • Error description: A clear explanation of what went wrong. If the error is from a registry, include the HTTP status code.
    • Command usage (Optional): Highly recommended when user input fails to follow standard usage or examples. This helps the user correct their command immediately.
    • Recommended solution (Optional): Provide a specific, actionable step the user can take to resolve the issue (e.g., "Run 'oras copy -h' for more options").

  3. Guidelines for writing ORAS CLI error messages

    main

    When encountering errors in the ORAS CLI, error messages are designed to be descriptive and actionable. A high-quality error message in ORAS typically includes:

    • Error description: A clear explanation of what went wrong.
    • HTTP status code: (Optional) Included when errors originate from the server side to help identify the nature of the remote failure.
    • Suggestion: A recommended solution or an executable command to resolve the issue. Where possible, ORAS provides links to versioned troubleshooting documentation.

    If an error message is insufficient for troubleshooting, use the --verbose flag to print more detailed logs.

  4. Understand the ORAS Index Manifest structure

    main

    The oras manifest index command family manipulates index manifests following the OCI Image Index Specification. When using ORAS to manage these indexes, the following properties are populated:

    • schemaVersion: Always 2.
    • mediaType: Always "application/vnd.oci.image.index.v1+json".
    • artifactType: Set via the --artifact-type option if provided.
    • manifests: An array of descriptors for child manifests. Each descriptor includes:
      • mediaType: Matches the associated manifest's media type.
      • artifactType: Matches the associated manifest's artifactType (if set via --artifact-type during an earlier oras push).
      • digest: The blob digest of the manifest.
      • size: The size of the manifest blob in bytes.
      • platform: Describes the specific platform (e.g., architecture/OS). This information is derived from the --artifact-platform option used during the original oras push command.
    • annotations: Populated via the --annotation command line option.

  5. Understand the types of ORAS output

    main

    ORAS categorizes its output into four distinct types based on the target user and purpose:

    1. Status output: Progress information, such as progress bars during pull or push operations.
    2. Metadata output: Information about processed objects (e.g., filename, digest) in formats like JSON or text.
    3. Content output: Raw data obtained from a remote registry or file system (e.g., the actual artifact content).
    4. Error output: Helpful error messages designed to guide users toward troubleshooting their mistakes.

  6. Understand the difference between --debug and --verbose

    main
    In ORAS, --debug is the preferred flag for deep diagnostics (showing network traffic), consistent with tools like Docker and Helm. The --verbose flag is being deprecated to reduce ambiguity and avoid overloading the diagnostic experience. Use --debug for troubleshooting connectivity or registry issues.

  8. Understand the difference between --output and --format flags

    main

    ORAS follows GNU design principles for output management. To avoid confusion when scripting or automating tasks, use the flags as follows:

    • --output: Specifies the destination (a file or directory) where the content should be created.
    • --format: Specifies the data representation of the output (e.g., json or a custom Go template).

    This design is consistent with other container tools like Docker, Podman, and Skopeo.

  9. Manage non-container artifacts using `artifactType`

    main

    When managing multi-platform artifacts that are not standard container images, the artifactType field is critical for client selection.

    1. Top-level Type: The index manifest itself should have an artifactType indicating the overall type of the multi-platform collection.
    2. Child Manifest Types: If individual child manifests have their own artifactType properties, ORAS automatically copies these values into the descriptors within the index manifest. This allows clients to efficiently select only the specific artifact types they expect.

    Use the --artifact-type flag with oras manifest index create or oras manifest index update to control these values.

  10. Backup and restore OCI artifacts with oras backup and oras restore

    main
    The oras backup and oras restore commands provide a structured, OCI-compliant method for persisting and rehydrating artifacts and their referrers. This allows users to create portable backups of registry state, including all tags and their referrers, and restore them to a registry. This functionality is designed for registry state management and scriptable workflows.

  11. The limitations of `docker save/load` for OCI Artifacts

    main

    While docker save and docker load are standard for container images, they are insufficient for modern OCI workflows because:

    • They cannot handle artifacts beyond container images (e.g., Helm charts, SBOMs, or AI models).
    • They often lose referrers and metadata during the export/import process.
    • They do not support the full range of OCI artifacts managed by tools like oras.

    For promoting artifacts across isolated environments (like moving from DEV to PROD registries), use oras capabilities to ensure referrers and metadata are preserved end-to-end.

  12. How ORAS restores artifacts with full references

    main

    The oras restore command automatically detects the reference format used in the backup's org.opencontainers.image.ref.name annotation:

    1. Tag-only format (e.g., "latest"): Matches against the tag portion of the restore target.
    2. Full reference format (e.g., "docker.io/library/alpine:latest"): Automatically extracts and matches the tag, then remaps it to the provided restore target.

    This allows you to restore an artifact to a different registry seamlessly.

    # Backup with full reference
oras backup --output backup.tar --full-reference docker.io/library/alpine:latest

# Restore to different registry (auto-remaps)
oras restore --input backup.tar registry.mycompany.com/alpine:latest
# Result: docker.io/library/alpine:latest → registry.mycompany.com/alpine:latest