**Explore:** Recursive pulling should be filterable

[ewrenn8]

Describe the problem/challenge you have
Looking at the recursive bundle proposal, we realized we may want to selectively pull bundles referenced from the ImagesLock. For kapp-controller's packaging use case, we would like to only pull bundles that we know are repositories, so that any non repo references in the ImagesLock are not pulled (kapp-controller has no use for these).

Describe the solution you'd like
Some type of filterability on recursive bundle pulls. One solution could be allowing users to specify an annotation filter from the command line which will cause imgpkg to only pull bundles in the ImagesLock which have that annotation applied to them. Concretely, I could imagine the annotation for kapp-controller's repository being kapp-controller.carvel.dev/package-repository and then selecting on the when recursively pulling.

[joaopapereira]

@ewrenn8 thanks for the issue.

After thinking a little bit about this feature I have some questions:

1. This enhancement should only apply to the pull command correct?
2. What would you expect to happen if a user executes the pull command without providing the recursive flag and provide a filter? Currently, this would only pull the configuration for the bundle.
3. On your proposed solution you provide an example of the annotation to filter on. How much flexibility does your use case need? Is it enough to search for the presence of an annotation or do we want to ensure that an annotation has a particular value associated with it?
4. Let's imagine we have bundle1 that contains bundle2 that contains bundle3 and only bundle3 has the annotation. Is the intent of this filter to only pull the configuration present in bundle3? Or all the bundles in the path?

[ewrenn8]

1. Yea, this would only apply to pull. I don't think this wouldn't make much sense to implement for copy since it could lead to a lot of unnecessary errors if a bundle is partially copied but users try to pull without the same filter or install things that were excluded from the copy. If it turns out folks really want this on copy, we can give it some more though then.
2. I would expect that scenario to either error saying the filter can only be used when recursively pulling, or just pull the top level bundle as it would without the filter. Maybe the first option is more restrictive at first and can be switched to the second option without causing a breaking change in the case it is a nuisance.
3. Good point, I think it should key off of presence + value, so maybe amending that use case to be kapp-controller.carvel.dev/repository: true makes sense.
4. In that scenario, I would expect only to have the top level bundle pulled since bundle2 didnt have the annotation, so we just stop there. I don't feel too strongly either way, but if the implementation means that we would have to pull every single bundle just to check if any children have the annotation, it doesn't seem like that would save us much work.

[iamhsk]

@ewrenn8 Could you tell me more why kapp-controller would like to only pull repositories? What benefits does it provide to end-users besides the fact that may speed up the pull operation?

[ewrenn8]

When making packages available to a cluster via a repo, kapp-controller only cares about bundles that are repos, since those are the only ones that will contain package CR yamls. Due to the nature of bundles, each repo's ImagesLock will also reference bundles used by the packages to store their k8s manifests, which kapp-controller has no use for, so we'd like to avoid pulling them and consuming disk space + time for artifacts that will just be thrown away. This problem also scales with the number of packages since each new package adds another bundle that would get pulled, whereas, if we could filter by repo, a new package wouldn't increase the number of artifacts pulled.

As for value added to the end user, I would say it just gives them more granular control over imgpkg's pull behavior, which potentially speeds up operations using imgpkg.

[aaronshurley]

Let's use this story to propose a solution (consider the UX, is there a general way to reference bundles?).

Expected outcome:

• a well-defined story
• identified blockers

[aaronshurley]

Follow-up implementation stories have been created:

• Pulling a nested bundle should allow filtering #116
• [UX] Pulling a nested bundle should allow filtering #118

Closing this issue.