feat(image): collect OCI annotations for discovered images

[hiddeco]

Part of #2147

This change enables the collection of OCI annotations from image indexes and manifests for discovered OCI images.

The annotations are stored to an Annotations field in each DiscoveredImageReference entry of a Warehouse, and then copied to the Annotations field of Image objects in Freight resources.

# Warehouse example
status:
 discoveredArtifacts:
    discoveredAt: 2025-03-20T21:48:51Z
    images:
      - references:
          - annotations:
              org.opencontainers.image.licenses: Apache-2.0
              org.opencontainers.image.revision: 0f7deb13c8deab7b7da6c5cc9a59b1393d187e75
              org.opencontainers.image.source: https://github.com/example/repository
              org.opencontainers.image.version: 1.2.3
            digest: sha256:675cab6cf2a9fb95d16b2368ce3281f8fbb008fdd4e7bc769663e4c732c0da77
            tag: 1.2.3
...

# Freight example
images:
  - repoURL: ghcr.io/example/repository/image
    tag: 1.2.3
    digest: sha256:675cab6cf2a9fb95d16b2368ce3281f8fbb008fdd4e7bc769663e4c732c0da77
    annotations:
       org.opencontainers.image.licenses: Apache-2.0
       org.opencontainers.image.revision: 0f7deb13c8deab7b7da6c5cc9a59b1393d187e75
       org.opencontainers.image.source: https://github.com/example/repository
       org.opencontainers.image.version: 1.2.3
...

This allows the UI to potentially present more information about images, for example by detecting pre-defined annotation keys from the OCI specification.

Note: Because of caching considerations and potential performance impacts noted in the above issue, the annotations can not be put to use yet to e.g. determine the build date or version of (all) images during image discovery, as this would require deeper inspection of layers attached to all tags.

[netlify]

✅ Deploy Preview for docs-kargo-io ready!

Name	Link
🔨 Latest commit	56ff39a
🔍 Latest deploy log	https://app.netlify.com/sites/docs-kargo-io/deploys/67e31927483f800008e8567b
😎 Deploy Preview	https://deploy-preview-3676.docs.kargo.io
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[codecov]

Codecov Report

Attention: Patch coverage is 7.10383% with 340 lines in your changes missing coverage. Please review.

Project coverage is 21.82%. Comparing base (f2da591) to head (56ff39a).
Report is 16 commits behind head on main.

Files with missing lines	Patch %	Lines
api/v1alpha1/generated.pb.go	0.62%	316 Missing ⚠️
api/v1alpha1/zz_generated.deepcopy.go	0.00%	18 Missing ⚠️
internal/image/repository_client.go	68.42%	5 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3676      +/-   ##
==========================================
+ Coverage   21.79%   21.82%   +0.02%     
==========================================
  Files         310      312       +2     
  Lines       64706    65571     +865     
==========================================
+ Hits        14105    14311     +206     
- Misses      49836    50490     +654     
- Partials      765      770       +5     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[jessesuen]

This is more of a question about how OCI annotations work, than than this PR.

Can OCI annotations be added or modified after the fact? e.g. is it possible to annotate an existing image already pushed? The reason I ask: currently, we consider Freight immutable. e.g. we generate new Freight when we detect a different image digest but with the same semvers.

Annotations, if mutable, pose a challenge in that if the image annotations can change (e.g. due to bad timing/race condition of Kargo image discovery vs. image push), then we may be left with a Kargo Freight that has stale/missing annotations. If so, we may need to account for this scenario somehow.

[krancour]

Can OCI annotations be added or modified after the fact?

Manifests are immutable. So "adding" an annotation is really pushing a new manifest. The new manifest will have a different digest. The new manifest could have the same tag as the original.

So, overwriting an existing tag with new annotations is exactly the same thing as overwriting an existing tag with a new image and the former shouldn't be done for all the same reasons that are widely recognized for not doing the latter.

[krancour]

Is this only because we're currently retrieving a limited amount of data from the registry unless something like latest build or a platform constraint forces us to? Or was there some other reason for this? You know much more than I do about these annotations.

[hiddeco]

If you have a multi-platform image with multiple architectures, this would/could round-robin collect annotations from each architecture — resulting in an unpredictable end result.

[hiddeco]

I.e. we can't collect more specific details because the details at that level may contradict each other.

[krancour]

Ohhhh. I don't know why that wasn't obvious right away. I get it.

[krancour]

🔥