# Plain bundle metadata proposal

## Summary
A bundle is a collection of Kubernetes manifests that can be sourced and applied to the cluster. Plain bundles are bundles that conform to the specifications of the [plain bundle spec](https://github.com/operator-framework/rukpak/blob/main/docs/plain-bundle-spec.md) and can be unpacked by the plain provisioner. Currently plain bundles do not have associated with them any additional metadata- they are simply a collection of manifests in a directory. Metadata in this context refers to information that is used to identify the bundle externally: things like schema version, package name, and any other information that might be important for tools that interact with the bundle. This proposal seeks to introduce a minimal set of metadata to plain bundles such that the associated metadata can become part of the plain bundle spec.

## Background
Metadata already exists and is well established for the registry+v1 bundle format. See the [operator bundle enhancement](https://github.com/openshift/enhancements/blob/master/enhancements/olm/operator-bundle.md#docker) for a high level overview of the structure of the metadata expected for registry+v1 bundles. This work has also been introduced upstream as part of the [manifest bundle KEP](https://github.com/kubernetes/enhancements/tree/master/keps/sig-cluster-lifecycle/addons/2494-Manifest-Bundle).

In the existing format, metadata can be provided via labels on the bundle image, or via a separate file that exists under /metadata in the bundle filesystem. Under /metadata an annotations.yaml and a properties.yaml can be provided that ultimately provide additional resolution information to the resolver. These files provide information like the package and default channel of the bundle, the location of the manifests and metadata within the bundle, and the bundle kind (mediatype). Additional metadata includes the GVK provided and required by the bundle, as well as additional constraints.

## Proposed metadata structure
For the plain+v0 bundle mediatype, metadata should be be minimal and scoped only to the information that is always useful for those interacting with the bundle. It should also only be stored in one place -- instead of a combination of image labels and files like in the registry+v1 format, only one is preferable. The metadata could live in a file on the bundle filesystem, for example a `bundle.yaml` file alongside the `manifests` directory. The metadata information can include the following:
* Bundle type
* Bundle schema version
* Package name

This information can be encoded in a YAML file that provides Kubernetes-style GVK for the plain+v0 format, for example

apiVersion: bundles.rukpak.io/v0
kind: Plain 

From this GVK, it's clear that the provided bundle is at schema version 0 and is a plain bundle. The plain provisioner, when interacting with this bundle, can lookup the metadata file and confirm that the bundle is the correct Kind and is at a version that is supported. This is the minimum amount of metadata that can be provided in a bundle that is useful to other components on-cluster. It is also easily extendable to other bundle types and different api versions. For a WIP implementation, see [this PR](https://github.com/operator-framework/rukpak/pull/172/files).

As a alternative metadata format, with additional information such as package name included, the following format can be provided:

apiVersion: bundles.rukpak.io/v0
kind: Plain 
metadata:
  name: <bundle name>
spec:
  package: <package name>

## Follow-up Questions
* Should metadata be mandatory or optional?
* Additional metadata fields to add a plain bundle to a catalog?
* Package
* Channel
* GVKs provided/required
* Runtime constraints (minKubeVersion)