Expansion of package metadata fields

[marshall007]

Is your feature request related to a problem? Please describe.

There is a variety of metadata we wish to capture and present in uds-marketplace. Presently, we are supplementing Zarf package metadata with YAML configs (source). You can also see a working list of metadata fields in this spreadsheet.

We wish to move most or all of this data into the ZarfPackageConfig managed within individual package repos.

Describe the solution you'd like

Much of the metadata we wish to capture could be populated on existing ZarfPackageConfig.metadata fields, but before we go do that we'd appreciate:

1. some clarification of the current schema
2. discuss options for making the metadata easier to consume

Clarification of Existing Metadata

• ZarfMetadata.description: "Additional information about this package."
  • Present: typical usage in the form of "UDS Package for "
  • Ask: clarify intent, should this be a short "tagline" or long-form product description?
• ZarfMetadata.url: "Link to package information when online."
  • Present: only used on uds-package-postgres-operator and uds-package-valkey. Links to upstream GitHub project.
  • Ask: clarify intent, should this be a link to the upstream software product page?
• ZarfMetadata.image: "An image URL to embed in this package (Reserved for future use in Zarf UI)."
  • Present: never used
  • Ask: embed the image as an additional layer. Consider renaming to icon to avoid overloading the ambiguous term image
• ZarfMetadata.authors: "Comma-separated list of package authors (including contact info)."
  • Present: never used
  • Ask: clarify intent, is this the Zarf package maintainers or upstream software maintainers? Consider enforcing strict compliance with RFC 5322 Address Specification
• ZarfMetadata.documentation/ZarfMetadata.source: "Link to package <documentation|source> when online."
  • Present: never used
  • Ask: clarify intent, should this be a link to upstream software documentation/source code?
• ZarfMetadata.vendor: "Name of the distributing entity, organization or individual."
  • Present: never used
  • Ask: clarify intent, Zarf package vendor or upstream software vendor? Like authors, consider enforcing strict compliance with RFC 5322 Address Specification

Additional Metadata Required by uds-marketplace

• title: pretty (titlecase) version of the upstream software product name
• icon: could use ZarfMetadata.image if it were wired up
• vendor-url: no obvious place for this currently
• description: long-form description of upstream software product
• tagline: short-form description
• link: additional links not captured by well-defined metadata fields (helm chart source, reference architecture, etc)
• contracting vehicle: details TBD
• pricing model: details TBD
• categories: a loosely standardized list of categories
• FIPS compliant image(s) : whether the images included in the package are known to use FIPS validated crypto
• control mapping: NIST SP 800-53 control mappings
• impact level: details TBD
• infrastructure: list providers the application depends on or supports (ex. if GCP or AWS specific APIs are required)

Given that the existing fields seem to be derived from the OCI image spec's pre-defined annotation keys, perhaps we should consider dropping these metadata fields entirely and provide a more direct means of specifying image annotations:

kind: ZarfPackageConfig
metadata:
  name: my-package
  annotations:
    org.opencontainers.image.title: My Package
    org.opencontainers.image.description: |
      This is a package I created for My Software. Maybe I can put markdown here, but that is not clearly specified!

Artifact Hub has a number of annotations they support, so perhaps this is the way to go for the evolving list of UDS-specific metadata we require.

Making Metadata Easier to Consume

Right now the only way to access this metadata from a package published in OCI is to:

1. traverse the image index -> manifest -> .layers[]
2. find the one with .annotations["org.opencontainers.image.title"] == "zarf.yaml"
3. download the layer as a blob and parse the YAML

It would be great metadata were made available:

1. consistently as annotations when possible
2. on the multi-arch image index (not just the platform-specific manifests)
3. as JSON instead of YAML with an appropriate zarf mediatype extension when in an image layer (or separate OCI artifact that can be fetched independently)

[AustinAbro321]

We are actually already planning to get rid of several metadata fields in favor of annotations. See #2636. This change will occur when the new Zarf schema, v1beta1, is released.

We actually do have some code to create annotations at the moment, but it's not intuitive to the user.

zarf/src/pkg/zoci/push.go

Lines 91 to 113 in 93128e8

	func annotationsFromMetadata(metadata *v1alpha1.ZarfMetadata) map[string]string {
	annotations := map[string]string{
	ocispec.AnnotationTitle: metadata.Name,
	ocispec.AnnotationDescription: metadata.Description,
	}
	if url := metadata.URL; url != "" {
	annotations[ocispec.AnnotationURL] = url
	}
	if authors := metadata.Authors; authors != "" {
	annotations[ocispec.AnnotationAuthors] = authors
	}
	if documentation := metadata.Documentation; documentation != "" {
	annotations[ocispec.AnnotationDocumentation] = documentation
	}
	if source := metadata.Source; source != "" {
	annotations[ocispec.AnnotationSource] = source
	}
	if vendor := metadata.Vendor; vendor != "" {
	annotations[ocispec.AnnotationVendor] = vendor
	}
	return annotations

There is an easier way to get annotations than grabbing the zarf.yaml from the layer, you can use the manifest config instead. I will say I'd be in favor of changing the manifest config to be a Zarf package rather than having the zarf.yaml as a layer. That is mostly separate issue, but would make accessing the file easier

I agree we should also add annotations to the index and manifests. We could do something similar to a regular container image see - busybox.

[AustinAbro321]

Created #2976 to track the ask for annotations on indexes / manifests