Document pkg/runtime interface implementation details and planned CRI-O-native field mappings

[Copilot]

pkg/runtime lacked a clear explanation of how the concrete runtime implements the runtime.Runtime interface, especially where each returned field comes from and how fallback/merge logic works. This PR adds a runtime-focused reference document that explains the current containerd implementation and also outlines a planned CRI-O field parsing path for future runtime work.

• New runtime implementation reference

  • Added docs/runtime-spec/runtime-interface-implementation.md
  • Documents the current containerd.ContainerdRuntime as the concrete runtime.Runtime implementation
  • Organizes the content by:
    • interface method flow
    • runtime dependencies and data sources
    • per-model field mapping
    • fallback / merge / inferred logic
    • explicitly unimplemented or partially populated fields

• Per-method implementation mapping

  • Covers all runtime.Runtime methods, including:
    • Connect / Close
    • container queries and detail paths
    • image metadata / config / layer resolution
    • pod grouping
    • process / top / mount inspection
  • Explains which methods return lightweight summaries vs. enriched runtime detail

• Per-field source tracing

  • Documents where fields are populated from across:
    • containerd metadata APIs
    • OCI spec
    • CRI runtime service
    • procfs
    • mountinfo
    • cgroup fs
    • inferred convention-based paths
  • Calls out precedence rules for multi-source fields such as:
    • container naming
    • environment
    • shared PID
    • cgroup path
    • mount origin/state
    • pod network metadata
    • runtime/shim/rootfs profile fields

• Planned CRI-O implementation guidance

  • Extends the same document with a clearly marked planning section for a future CRI-O runtime implementation
  • Reworks the CRI-O section to be organized around CRI-O's own concepts instead of containerd-specific terminology
  • Describes suggested parsing paths for:
    • container fields
    • container detail fields
    • runtime-specific fields
    • image/image-layer fields
    • pod, process, top, and mount views
  • Identifies recommended data sources and supporting libraries for CRI-O, including:
    • CRI RuntimeService
    • CRI ImageService
    • crio.conf / storage.conf
    • go.podman.io/image/v5 (formerly containers/image)
    • go.podman.io/storage (formerly containers/storage)
    • conmon
    • procfs / mountinfo / cgroup fs
  • Explicitly avoids forcing containerd-only concepts such as snapshot, content store, and shim onto the CRI-O design
  • Calls out where CRI-O-specific model extensions are preferable to compatibility mapping through containerd-shaped fields

• Extension-friendly structure

  • Adds a reusable documentation template for future runtime implementations
  • Defines the expected shape for documenting:
    • implementation dependencies
    • method behavior
    • field mapping tables
    • merge precedence
    • known gaps
  • Now includes concrete planning guidance that can be used as a starting point when adding pkg/runtime/crio

• Discoverability

  • Added a README link to the new document from the runtime abstraction section

Example interface excerpt referenced by the new document:

type Runtime interface {
    Connect(ctx context.Context) error
    Close() error

    ListContainers(ctx context.Context) ([]*models.Container, error)
    GetContainer(ctx context.Context, id string) (*models.Container, error)
    GetContainerDetail(ctx context.Context, id string) (*models.ContainerDetail, error)
    GetContainerRuntimeInfo(ctx context.Context, id string) (*models.ContainerDetail, error)

    ListImages(ctx context.Context) ([]*models.Image, error)
    GetImage(ctx context.Context, ref string) (*models.Image, error)
    GetImageLayers(ctx context.Context, imageID, snapshotter, rwSnapshotKey string) ([]*models.ImageLayer, error)
    GetImageConfigInfo(ctx context.Context, imageID string) (*models.ImageConfigInfo, error)

    ListPods(ctx context.Context) ([]*models.Pod, error)
    GetContainerProcesses(ctx context.Context, id string) ([]*models.Process, error)
    GetContainerTop(ctx context.Context, id string) (*models.ProcessTop, error)
    GetContainerMounts(ctx context.Context, id string) ([]*models.Mount, error)
}

Original prompt

请将pkg/runtime 中具体运行时是如何实现runtime接口的，需要详细包含每个字段的获取方式，途径和相关逻辑

输出的文档要保证易于扩展，未来会增加其他运行时实现

---

💬 Send tasks to Copilot coding agent from Slack and Teams to turn conversations into code. Copilot posts an update in your thread when it's finished.

[Iceber]

@copilot 我准备增加基于cri-o的具体实现，请帮我先基于crio完善文档，梳理字段的解析路径

[Copilot]

@copilot 我准备增加基于cri-o的具体实现，请帮我先基于crio完善文档，梳理字段的解析路径

已补充 CRI-O 规划章节，明确区分“当前已实现的 containerd”和“未来 CRI-O 实现建议”，把 runtime.Runtime 各方法及主要字段的解析来源、路径、fallback 和分阶段落地建议都梳理进去了。对应提交：39b165f

[Iceber]

@copilot 重新整理crio的部分，其中可以扩展只与crio有关的字段，并忽视对应的containerd字段，例如snapshot和content概念和shim概念，而且使用自己的containers image 和 storage ，conmon
在文档中数据获取流程中也可以说明借助的库，例如containers组织中的库

[Copilot]

@copilot 重新整理crio的部分，其中可以扩展只与crio有关的字段，并忽视对应的containerd字段，例如snapshot和content概念和shim概念，而且使用自己的containers im...

已按 CRI-O 自身语义重写这部分文档：把数据流改成 CRI Runtime/Image、go.podman.io/image/v5、go.podman.io/storage、conmon、宿主机观测几层来描述，并把 SnapshotKey / Snapshotter / Shim 明确降为兼容字段或建议扩展项，不再作为核心概念。对应提交：0e43bc3。本次无 UI 变更，因此没有截图。