Add --layer-index and --layer-type flags to pull artifact

[ruslan-shaydullin]

Closes #4243

What

Adds --layer-index <int> to flux pull artifact. When set, the
underlying oci.Client.Pull is called with WithPullLayerIndex(n) so
the chosen layer is extracted instead of the default first layer. Lets
users pull arbitrary layers from OCI artifacts that were not produced
by flux.

Per review feedback, also adds --layer-type <tarball|static> exposing
WithPullLayerType. The two are orthogonal: --layer-index selects
which layer to pull, --layer-type overrides how it is extracted —
tarball untars it to the output directory, static copies the blob
to the output file. With --layer-type=static the --output path is
validated as a file path (existing parent directory) instead of an
existing directory.

Compatibility

Default flow is unchanged — without --layer-index the command behaves
exactly as before (extracts the first layer with layerIndex: 0 in
oci.Client.Pull). Without --layer-type the extraction mode is
auto-detected from the layer content, as before.

Precedent

This continues the work from PR #4790 (closed without merge after
21 months of inactivity — no review feedback on the thread, likely
stale-bot closure). That PR no longer applies cleanly because of
unrelated refactors in pull_artifact.go, so this is rewritten from
scratch using the same flag name.

Tests

The new internal/flags.LayerType flag type has a table test following
the existing internal/flags convention. No existing
pull_artifact_test.go in the repo; the CLI wiring itself follows the
existing pull_artifact precedent of no test file. Happy to add coverage
if maintainers prefer.

Local testing notes

On Apple Silicon the Makefile's setup-envtest use latest --arch=amd64
step fails (bad CPU type in executable). Ran envtest manually with
--arch=arm64 and KUBEBUILDER_ASSETS pointed at the arm64 dir; the
full cmd/flux/... test suite passes. CI on linux/amd64 should be
unaffected.

[matheuscscp]

This PR is adding --layer-index <int>, not --layer-selector <string> like discussed in #4243

[ruslan-shaydullin]

This PR is adding --layer-index <int>, not --layer-selector <string> like discussed in #4243

I picked --layer-index <int> for a couple of reasons: it's the literal mapping to oci.WithPullLayerIndex(int) (zero-based position), and it matches the flag name in the closed PR #4790 from @ptfpinho23. To me "selector" implied filtering by media-type, which would map to a different option (oci.WithPullLayerType).

If you'd prefer the issue wording: rename to --layer-selector <int> keeping position semantics, or switch to a string-typed flag mapping to WithPullLayerType for media-type filtering. Which one were you thinking?

[ruslan-shaydullin]

Hey @matheuscscp — circling back on this. Any leaning between the three? Keeping --layer-index, renaming to --layer-selector (same int semantics), or switching to a string flag via WithPullLayerType are all simple for me, so just let me know which direction you'd prefer.

[matheuscscp]

The original issue suggested using WithPullLayerType, does it not solve your problem? Isn't --layer-type <string> an option?

https://github.com/fluxcd/pkg/blob/5a7f3ce0de742b6c561a50f90940d81cf6fc698d/oci/pull.go#L50

[matheuscscp]

Maybe add both since there's both in the library?

[ruslan-shaydullin]

Took another look at WithPullLayerType in the current package — turns out it doesn't select a layer by media type at all. It controls how the already-selected layer gets extracted: tarball untars into a directory, static copies the blob to a file, and leaving it unset auto-detects. So the two options are actually orthogonal, which means "add both" works out nicely: --layer-index picks the layer, --layer-type overrides extraction.

I've pushed a commit adding --layer-type tarball|static. For static, --output is now validated as a file path, since the layer gets written out as a single file.

[matheuscscp]

@stratch1989 Can you pls share a bit how your real-world use case looks like?

[ruslan-shaydullin]

Candid answer: this didn't come out of an incident on my end. I picked up #4243 from the backlog because it had two things going for it — a maintainer-endorsed design sketch, and a prior attempt (#4790) that died of inactivity rather than because anyone rejected the idea.

The use case I'm building for is the one @errordeveloper laid out in the issue: parity between what OCIRepository can do in-cluster and what the CLI can do locally. Right now flux pull artifact can't handle artifacts that weren't produced by flux, so there's no way to locally inspect or debug what the controller would extract from an ORAS- or crane-pushed artifact. As @stefanprodan put it in the thread: "Currently the Flux CLI can't pull artifacts not created by it."

One thing worth flagging while we're here: OCIRepository's layerSelector matches layers by media type, whereas the current pkg pull options only expose index + extraction mode — so this PR doesn't get us to full parity. If media-type selection is the shape you'd actually want, that needs a small addition in fluxcd/pkg first. Happy to pick that up as a follow-up.

[matheuscscp]

Let's keep this open until we have a use case.