Skip to content

[deckhouse-cli] Add new cr command for registry operations#344

Open
Glitchy-Sheep wants to merge 14 commits intomainfrom
feat/new-cr-fs-commands
Open

[deckhouse-cli] Add new cr command for registry operations#344
Glitchy-Sheep wants to merge 14 commits intomainfrom
feat/new-cr-fs-commands

Conversation

@Glitchy-Sheep
Copy link
Copy Markdown
Contributor

@Glitchy-Sheep Glitchy-Sheep commented May 6, 2026

Add cr command group for container-registry operations

Introduces d8 cr: Crane-like workflows under one subtree, with the same registry auth as the rest of the CLI (d8 login / Docker config).

Command Tree

The PR adds the following commands to d8:

d8 cr
├─ [global flags]
│  ├─ -v, --verbose                            # Verbose debug logs on stderr (registry/network details).
│  ├─ --insecure                               # Plain HTTP / skip TLS verify; localhost & RFC1918 often already HTTP.
│  ├─ --allow-nondistributable-artifacts       # Push: include foreign/non-distributable layers.
│  └─ --platform os/arch[/variant][:osversion] # Multi-arch: resolve one platform (image-level cmds).
│
├─ pull IMAGE... PATH
│  ├─ Pull one or more remote images to local path
│  └─ flags:
│     ├─ -c, --cache-path <dir>      # Layer cache dir; reused across pulls.
│     └─ --format tarball|legacy|oci # Output: docker tarball (default), legacy tar, or OCI layout dir.
│
├─ push PATH IMAGE
│  ├─ Push local tar/OCI layout to registry
│  └─ flags:
│     ├─ --index             # OCI layout: push top-level index as-is (multi-manifest).
│     └─ --image-refs <file> # Also write pushed repo@digest to this file.
│
├─ export IMAGE [TARBALL]
│  └─ Export merged filesystem as verbatim tar stream
│
├─ ls REPO
│  ├─ List repository tags
│  └─ flags
│     ├─ --full-ref             # Full refs (registry/repo:tag) instead of tag names only.
│     └─ -O, --omit-digest-tags # Hide synthetic sha256-* tags.
│
├─ catalog REGISTRY
│  ├─ List repositories in registry
│  └─ flags
│     └─ --full-ref		# Full repo paths (registry/repo) instead of names only.
│
├─ manifest IMAGE
│  └─ Print raw manifest JSON
│
├─ config IMAGE
│  └─ Print raw config JSON
│
├─ digest [IMAGE]
│  ├─ Print image digest from registry or tarball
│  └─ flags
│     ├─ --tarball <path> # Digest from local tarball instead of registry.
│     └─ --full-ref       # Full repo@sha256:… instead of digest-only line (no --tarball).
│
└─ fs # A utility subcommand to work with image files (list, cat)
   ├─ ls IMAGE [PATH]
   │  ├─ List files (merged filesystem)
   │  └─ flags
   │     └─ -l, --long		# Long rows: mode, size, path
   │
   ├─ cat IMAGE PATH
   │  └─ Print regular file contents (merged FS)
   │
   ├─ tree IMAGE [PATH]
   │  ├─ Show filesystem tree
   │  └─ flags
   │     ├─ -L, --depth <n> # Max depth (0 = unlimited).
   │     ├─ --dirsfirst     # Directories before files in each listing (convenient).
   │     └─ --size          # Human-readable sizes on file nodes (text tree).
   │
   └─ extract IMAGE
      ├─ Extract merged filesystem to local directory (safe extraction)
      └─ flags
         └─ -o, --output <dir> (required)		# Destination directory for extracted files.

Presentation (Basic Flows)

out

How to review

The d8 cr follows the project conventions:

  • cmd/command_name.go for commands
  • cmd/cmd/subcommand.go for subcommands.
  • The cr package also have its own internal structure to isolate domain specific logic
  1. Start from the root command surface (cmd/d8/root.go, internal/cr/cmd/*).
  2. Verify internals by layer (image -> imageio -> imagefs -> registry -> output).

- introduce domain types and error sentinels
- add scope guard against path traversal
- detect OCI whiteout markers

Signed-off-by: Roman Berezkin <[email protected]>
- layer walker that resolves union mounts and whiteouts
- streaming reader of layered image filesystem
- file extractor with destination scope enforcement

Signed-off-by: Roman Berezkin <[email protected]>
- cover whiteout matching and scope safety
- table-driven cases for layered fs traversal
- end-to-end pipeline coverage

Signed-off-by: Roman Berezkin <[email protected]>
- resolve image references in tag, digest, and mixed forms
- cover edge cases in reference parsing

Signed-off-by: Roman Berezkin <[email protected]>
- OCI image layout reader and writer
- tarball format adapter for image io
- roundtrip tests for layout and tarball

Signed-off-by: Roman Berezkin <[email protected]>
- text-format renderer for image metadata
- table-driven output tests

Signed-off-by: Roman Berezkin <[email protected]>
- transport-level options and timeouts
- catalog, tags, fetch, push, inspect operations
- options coverage and push regression tests

Signed-off-by: Roman Berezkin <[email protected]>
- shared root flags for registry endpoint and auth
- common flag-name constants in rootflagnames
- root flag wiring with tests

Signed-off-by: Roman Berezkin <[email protected]>
- catalog, config, digest, manifest, ls, push, pull subcommands
- export to local layout
- pull happy-path test

Signed-off-by: Roman Berezkin <[email protected]>
- fs root group with cat, ls, tree, extract subcommands
- tree rendering with depth limits
- tree subcommand tests

Signed-off-by: Roman Berezkin <[email protected]>
- bash, zsh, fish completion generation
- completion regression tests

Signed-off-by: Roman Berezkin <[email protected]>
- integration suite covering cr command surface
- smoke test for top-level command registration

Signed-off-by: Roman Berezkin <[email protected]>
Signed-off-by: Roman Berezkin <[email protected]>
@Glitchy-Sheep Glitchy-Sheep self-assigned this May 6, 2026
@Glitchy-Sheep Glitchy-Sheep added the enhancement New feature or request label May 6, 2026
@Glitchy-Sheep Glitchy-Sheep changed the title Add [deckhouse-cli] Add new cr command for registry operations May 6, 2026
- `cr push --index` of an OCI layout with one nested index publishes that inner index directly, so the registry stores the real multi-arch index with no 1-entry wrapper.
- `--index` only matters for multi-entry layouts; single-entry layouts always unwrap in `LoadLocal` to their inner image or index.
- New test pins the unwrap by digest comparison so the wrapper can't sneak back in.

Signed-off-by: Roman Berezkin <[email protected]>
@Glitchy-Sheep Glitchy-Sheep marked this pull request as ready for review May 6, 2026 11:11
@Glitchy-Sheep Glitchy-Sheep requested a review from ldmonster as a code owner May 6, 2026 11:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant