Add bundle dependencies specification documentation

Signed-off-by: Vu Dinh <[email protected]>

Author: dinhxuanvu

docs/design/operator-bundle.md

@@ -17,7 +17,7 @@ An `Operator Bundle` is built as a scratch (non-runnable) container image that c
 
 ### Bundle Manifest Format
 
-The standard bundle format requires two directories named `manifests` and `metatdata`. The `manifests` directory is where all operator manifests are resided including ClusterServiceVersion (CSV), CustomResourceDefinition (CRD) and other supported Kubernetes types. The `metadata` directory is where operator metadata is located including `annotations.yaml` which contains additional information such as package name, channels and media type.
+The standard bundle format requires two directories named `manifests` and `metatdata`. The `manifests` directory is where all operator manifests are resided including ClusterServiceVersion (CSV), CustomResourceDefinition (CRD) and other supported Kubernetes types. The `metadata` directory is where operator metadata is located including `annotations.yaml` which contains additional information such as package name, channels and media type. Also, `dependencies.yaml` which contains the operator dependency information can be included in `metadata` directory.
 
 Below is the directory layout of an operator bundle inside a bundle image:
 ```bash
@@ -27,7 +27,8 @@ $ tree
 │   ├── etcdcluster.crd.yaml
 │   └── etcdoperator.clusterserviceversion.yaml
 └── metadata
-    └── annotations.yaml
+    ├── annotations.yaml
+    └── dependencies.yaml
 ```
 
 *Notes:*
@@ -64,6 +65,26 @@ annotations:
 * The potential use case for the `LABELS` is - an external off-cluster tool can inspect the image to check the type of a given bundle image without downloading the content.
 * The annotations for bundle manifests and metadata are reserved for future use. They are set to be `manifests/` and `metadata/` for the time being.
 
+### Bundle Dependencies
+
+The dependencies of an operator are listed as a list in `dependencies.yaml` file inside `/metadata` folder of a bundle. This file is optional and only used to specify explicit operator version dependencies at first. Eventually, operator authors can migrate the API-based dependencies into `dependencies.yaml` as well in the future. The ultimate goal is to have `dependencies.yaml` as a centralized metadata for operator dependencies and moving the dependency information away from CSV.
+
+The dependency list will contain a `type` field for each item to specify what kind of dependency this is. There are two supported `type` of operator dependencies. It can be a package type (`olm.package`) meaning this is a dependency for a specific operator version. For `olm.package` type, the dependency information should include the `package` name and the `version` of the package in semver format. We use `blang/semver` library for semver parsing (https://github.com/blang/semver). For example, you can specify an exact version such as `0.5.2` or a range of version such as `>0.5.1` (https://github.com/blang/semver#ranges). In addition, the author can specify dependency that is similiar to existing CRD/API-based using `olm.gvk` type and then specify GVK information as how it is done in CSV. This is a path to enable operator authors to consolidate all dependencies (API or explicit version) to be in the same place.
+
+An example of a `dependencies.yaml` that specifies Prometheus operator and etcd CRD dependencies:
+
+```
+dependencies:
+  - type: olm.package
+    name: prometheus
+    version: >0.27.0
+  - type: olm.gvk
+    name: etcdclusters.etcd.database.coreos.com
+    group: etcd.database.coreos.com
+    kind: EtcdCluster
+    version: v1beta2
+```
+
 ### Bundle Dockerfile
 
 This is an example of a `Dockerfile` for operator bundle:

pkg/api/registry.proto

@@ -12,7 +12,7 @@ service Registry {
 	rpc GetChannelEntriesThatProvide(GetAllProvidersRequest) returns (stream ChannelEntry) {}
 	rpc GetLatestChannelEntriesThatProvide(GetLatestProvidersRequest) returns (stream ChannelEntry) {}
 	rpc GetDefaultBundleThatProvides(GetDefaultProviderRequest) returns (Bundle) {}
-  rpc ListBundles() returns (stream Bundle) {}
+  rpc ListBundles(ListBundlesRequest) returns (stream Bundle) {}
 }
 
 
@@ -69,6 +69,8 @@ message ChannelEntry{
 
 message ListPackageRequest{}
 
+message ListBundlesRequest{}
+
 message GetPackageRequest{
 	string name = 1;
 }