Add opm docs

README.md

@@ -6,6 +6,7 @@ Operator Registry runs in a Kubernetes or OpenShift cluster to provide operator
 
 This project provides the following binaries:
 
+ * `opm`, which generates and updates registry databases as well as the index images that encapsulate them.
  * `initializer`, which takes as an input a directory of operator manifests and outputs a sqlite database containing the same data for querying.
  * `registry-server`, which takes a sqlite database loaded with manifests, and exposes a gRPC interface to it.
  * `configmap-server`, which takes a kubeconfig and a configmap reference, and parses the configmap into the sqlite database before exposing it via the same interface as `registry-server`.
@@ -16,82 +17,75 @@ And libraries:
  * `pkg/api` - providing low-level client libraries for the gRPC interface exposed by `registry-server`.
  * `pkg/registry` - providing basic registry types like Packages, Channels, and Bundles.
  * `pkg/sqlite` - providing interfaces for building sqlite manifest databases from `ConfigMap`s or directories, and for querying an existing sqlite database.
+ * `pkg/lib` - providing external interfaces for interacting with this project as an api that defines a set of standards for operator bundles and indexes.
+ * `pkg/containertools` - providing an interface to interact with and shell out to common container tooling binaries (if installed on the environment)
 
 # Manifest format
 
 
-We refer to a directory of files with one ClusterServiceVersion as a "bundle". A bundle is typically just a ClusterServiceVersion and the CRDs that define the owned APIs of the CSV, though additional objects may be included.
+We refer to a directory of files with one ClusterServiceVersion as a "bundle". A bundle typically includes a ClusterServiceVersion and the CRDs that define the owned APIs of the CSV in its manifest directory, though additional objects may be included. It also includes an annotations file in its metadata folder which defines some higher level aggregate data that helps to describe the format and package information about how the bundle should be added into an index of bundles.
 
 ```
  # example bundle
- 0.6.1
- ├── etcdcluster.crd.yaml
- └── etcdoperator.clusterserviceversion.yaml
+ etcd
+ ├── manifests
+ │   ├── etcdcluster.crd.yaml
+ │   └── etcdoperator.clusterserviceversion.yaml
+ └── metadata
+     └── annotations.yaml
 ```
 
 When loading manifests into the database, the following invariants are validated:
 
- * Every package has at least one channel
- * Every ClusterServiceVersion pointed to by a channel in a package exists
+ * The bundle must have at least one channel defined in the annotations.
  * Every bundle has exactly one ClusterServiceVersion.
  * If a ClusterServiceVersion `owns` a CRD, that CRD must exist in the bundle.
- * If a ClusterServiceVersion `replaces` another, both the old and the new must exist in the package.
 
 Bundle directories are identified solely by the fact that they contain a ClusterServiceVersion, which provides an amount of freedom for layout of manifests.
 
-It's recommended to follow a layout that makes it clear which bundles are part of which package, as in [manifests](manifests):
+Check out the [operator bundle design](docs/design/operator-bundle.md) for more detail on the bundle format.
 
+# Bundle images
+
+Using [OCI spec](https://github.com/opencontainers/image-spec/blob/master/spec.md) container images as a method of storing the manifest and metadata contents of individual bundles, `opm` interacts directly with these images to generate and incrementally update the database. Once you have your [manifests defined](https://operator-framework.github.io/olm-book/docs/packaging-an-operator.html#writing-your-operator-manifests) and have created a directory in the format defined above, building the image is as simple as defining a [Dockerfile](docs/design/operator-bundle.md#Bundle-Dockerfile) and building that image:
+
+
+```sh
+podman build -t quay.io/my-container-registry-namespace/my-manifest-bundle:latest -f bundle.Dockerfile .
 ```
-manifests
-├── etcd
-│   ├── 0.6.1
-│   │   ├── etcdcluster.crd.yaml
-│   │   └── etcdoperator.clusterserviceversion.yaml
-│   ├── 0.9.0
-│   │   ├── etcdbackup.crd.yaml
-│   │   ├── etcdcluster.crd.yaml
-│   │   ├── etcdoperator.v0.9.0.clusterserviceversion.yaml
-│   │   └── etcdrestore.crd.yaml
-│   ├── 0.9.2
-│   │   ├── etcdbackup.crd.yaml
-│   │   ├── etcdcluster.crd.yaml
-│   │   ├── etcdoperator.v0.9.2.clusterserviceversion.yaml
-│   │   └── etcdrestore.crd.yaml
-│   └── etcd.package.yaml
-└── prometheus
-    ├── 0.14.0
-    │   ├── alertmanager.crd.yaml
-    │   ├── prometheus.crd.yaml
-    │   ├── prometheusoperator.0.14.0.clusterserviceversion.yaml
-    │   ├── prometheusrule.crd.yaml
-    │   └── servicemonitor.crd.yaml
-    ├── 0.15.0
-    │   ├── alertmanager.crd.yaml
-    │   ├── prometheus.crd.yaml
-    │   ├── prometheusoperator.0.15.0.clusterserviceversion.yaml
-    │   ├── prometheusrule.crd.yaml
-    │   └── servicemonitor.crd.yaml
-    ├── 0.22.2
-    │   ├── alertmanager.crd.yaml
-    │   ├── prometheus.crd.yaml
-    │   ├── prometheusoperator.0.22.2.clusterserviceversion.yaml
-    │   ├── prometheusrule.crd.yaml
-    │   └── servicemonitor.crd.yaml
-    └── prometheus.package.yaml
+
+Once you have built the container, you can publish it like any other container image:
+
+```sh
+podman push quay.io/my-container-registry-namespace/my-manifest-bundle:latest
 ```
 
-# Building a catalog of Operators using `operator-registry`
+Of course, this build step can be done with any other OCI spec container tools like `docker`, `buildah`, `libpod`, etc.
+
+# Building an index of Operators using `opm`
 
-The [Dockerfile](upstream-example.Dockerfile) provides an example of using the `initializer` and `registry-server` to build a minimal container that provides a `gRPC` API over the example manifests in [manifests](manifests).
+Now that you have published the container image containing your manifests, how do you actually make that bundle available to other users' Kubernetes clusters so that the Operator Lifecycle Manager can install the operator? This is where the meat of the `operator-registry` project comes in. OLM has the concept of [CatalogSources](https://operator-framework.github.io/olm-book/docs/glossary.html#catalogsources) which define a reference to what packages are available to install onto a cluster. To make your bundle available, you can add the bundle to a container image which the CatalogSource points to. This image contains a database of pointers to bundle images that OLM can pull and extract the manifests from in order to install an operator. So, to make your operator available to OLM, you can generate an index image via opm with your bundle reference included:
 
 ```sh
-docker build -t example-registry:latest -f upstream-example.Dockerfile .
-docker push example-registry:latest
+opm index add --bundles quay.io/my-container-registry-namespace/my-manifest-bundle:0.0.1 --tag quay.io/my-container-registry-namespace/my-index:1.0.0
+podman push quay.io/my-container-registry-namespace/my-index:1.0.0
 ```
 
-# Using the catalog with Operator Lifecycle Manager
+The resulting image is referred to as an "Index". It is an image which contains a database of pointers to operator manifest content that is easily queriable via an included API that is served when the container image is run.
+
+Now that image is available for clusters to use and reference with CatalogSources on their cluster.
+
+Index images are additive, so you can add a new version of your operator bundle when you publish a new version:
+
+```sh
+opm index add --bundles quay.io/my-container-registry-namespace/my-manifest-bundle:0.0.2 --from-index quay.io/my-container-registry-namespace/my-index:1.0.0 --tag quay.io/my-container-registry-namespace/my-index:1.0.1
+```
+
+For more detail on using `opm` to generate index images, take a look at the [documentation](docs/design/opm-tooling.md).
+
+# Using the index with Operator Lifecycle Manager
 
-To add a catalog packaged with `operator-registry` to your cluster for use with [Operator Lifecycle Manager](https://github.com/operator-framework/operator-lifecycle-manager) (OLM) create a `CatalogSource` referencing the image you created and pushed above:
+To add an index packaged with `operator-registry` to your cluster for use with [Operator Lifecycle Manager](https://github.com/operator-framework/operator-lifecycle-manager) (OLM) create a `CatalogSource` referencing the image you created and pushed above:
 
 ```yaml
 apiVersion: operators.coreos.com/v1alpha1

docs/design/opm-tooling.md

@@ -0,0 +1,102 @@
+# Operator Registry Tooling
+
+When compiled, the `operator-registry` project results in a collection of tools that in aggregate define a way of packaging and delivering operator manifests to Kubernetes clusters. Historically, this is done with multiple tools. For example, you can use `initializer` to generate an immutable database and then use `registry-serve` to serve the database via an API. We have added the `opm` tool that aggregates these functions togeother and allows a user to interact with container images and tooling directly to generate and update registry databases in a mutable way.
+
+The following document describes the tooling that `opm` provides along with descriptions of how to use them including each command's purpose, their inputs and outputs, and some examples.
+
+## opm
+
+`opm` (Operator Package Manager) is a tool that is used to generate and interact with operator-registry catalogs, both the underlying databases (generally referred to as the `registry`) and their images (the `index`). This is divided into two main commands: `registry` which is used to initialize, update and serve an API of the underlying database of manifests and references and `index` which is used to interact with an OCI container runtime to generate the registry database and package it in a container image.
+
+### registry
+
+`opm registry` generates and updates registry database objects.
+
+#### add
+
+First, let's look at adding a version of an operator bundle to a registry database. For example:
+
+`opm registry add -b "quay.io/operator-framework/operator-bundle-prometheus:0.14.0" -d "test-registry.db"`
+
+Dissecting this command, we called `opm registry add` to pull a container image that includes the manifests for the 0.14.0 version of the `prometheus` operator. We then unpacked those manifests from the container image and attempted to insert them into the registry database `test-registry.db`. Since that database file didn't currently exist on disk, the database was initialized first and then prometheus 0.14.0 was added to the empty database.
+
+Now imagine that the 0.15.0 version of the `prometheus operator` was just released. We can add that operator to our existing database by calling add again and pointing to the new container image:
+
+`opm registry add -b "quay.io/operator-framework/operator-bundle-prometheus:0.15.0" -d "test-registry.db"`
+
+Great! The existing `test-registry.db` file is updated. Now we have a registry that contains two versions of the operator and defines an update graph that, when added to a cluster, will signal to the Operator Lifecycle Manager that if you have already installed version `0.14.0` that `0.15.0` can be used to upgrade your installation.
+
+#### rm
+
+`opm` also currently supports removing entire packages from a registry. For example:
+
+`opm registry rm -o "prometheus" -d "test-registry.db"`
+
+Calling this on our existing test registry removes all versions of the prometheus operator entirely from the database.
+
+#### serve
+
+`opm` also includes a command to connect to an existing database and serve a `gRPC` API that handles requests for data about the registry:
+
+`opm registry serve -d "test-registry.db" -p 50051`
+
+### index
+
+`opm index` is, for the most part, a wrapper for `opm registry` that abstracts the underlying database interaction to instead make it easier to speak about the container images that are actually shipped to clusters directly. In particular, this makes it easy to say "given my operator index image, I want to add a new version of my operator and get an updated container image that I can automatically ship to clusters".
+
+#### add
+
+Index add works much the same way as registry add. For example:
+
+`opm index add --bundles quay.io/operator-framework/operator-bundle-prometheus:0.14.0 --tag quay.io/operator-framework/monitoring-index:1.0.0`
+
+Just like `opm registry add`, this command pulls a given container bundle and attempts to put it into a registry. The real difference is that the result is more than just a database file. By default, this command actually builds a container image and, looking at the `--tag` flag, will tag the output image as `quay.io/operator-framework/monitoring-index:1.0.0`. The resulting image has the database and the opm binary in it and, when run, calls the `registry serve` command on the database that was generated.
+
+Just like registry add command, the updates are cumulative. In this case, rather than pointing at a database file, we can use the `--from-index` flag to specify a previous index to build off of a previous registry:
+
+`opm index add --bundles quay.io/operator-framework/operator-bundle-prometheus:0.15.0 --from-index quay.io/operator-framework/monitoring:1.0.0 --tag quay.io/operator-framework/monitoring:1.0.1`
+
+This results in a fresh image that includes the updated prometheus operator in the prometheus package's update graph.
+
+At a high level, this command operates by wrapping `registry add` around some additional interaction with pulling and building container images. To that end, the last thing it does is actually shell out to a container CLI tool to build the resulting container (by default, `podman build`). It does this by generating a dockerfile and then passing that file to the shell command. For example:
+
+```dockerfile
+FROM quay.io/operator-framework/upstream-registry-builder AS builder
+
+FROM scratch
+LABEL operators.operatorframework.io.index.database.v1=./index.db
+COPY database ./
+COPY --from=builder /build/bin/opm /opm
+COPY --from=builder /bin/grpc_health_probe /bin/grpc_health_probe
+EXPOSE 50051
+ENTRYPOINT ["/opm"]
+CMD ["registry", "serve", "--database", "index.db"]
+```
+
+Of note here is that we use a builder image to get the latest upstream released version of opm in order to call `opm registry serve` to host the gRPC API. If a developer or CI system would prefer to point to a different version of `opm` to serve their operator (perhaps one in a private release or a fork) then they just need to deliver their own version in a container and then use the `--binary-image` command. ex:
+
+`opm index add --bundles quay.io/operator-framework/operator-bundle-prometheus:0.14.0 --tag quay.io/operator-framework/monitoring-index:1.0.0 --binary-image quay.io/$user/my-opm-source`
+
+This will update the above dockerfile and replace the builder image with the image specified in the `--binary-image` flag.
+
+We are aware of the fact that, in many cases, users will want to make other changes to this dockerfile (adding additional labels, adding other binaries for metrics, using a different port, etc.). For these more complex use cases, we have added the `--generate` and `--out-dockerfile` flags. Adding `--generate` will skip the container build command entirely and instead write a Dockerfile to the local filesystem. By default this file is called `index.Dockerfile` and is put in the directory you run `opm` from. If you want to rename this generated dockerfile and write it somewhere else, just specify the `--out-dockerfile` flag:
+
+`opm index add --bundles quay.io/operator-framework/operator-bundle-prometheus:0.14.0 --generate --out-dockerfile "my.Dockerfile"`
+
+Running this command will still generate the updated registry database, but it will store it locally and additionally write `my.Dockerfile` which can be modified as needed.
+
+#### rm
+
+Like `opm registry rm`, this command will remove all versions an entire operator package from the index and results in a container image that does not include that package. It supports virtually all of the same options and flags as `opm index add` with the exception of replacing `--bundles` with `--operators`. Ex:
+
+`opm index rm --operators prometheus --tag quay.io/operator-framework/monitoring-index:1.0.2 --binary-image quay.io/$user/my-opm-source`
+
+This will result in the tagged container image `quay.io/operator-framework/monitoring-index:1.0.2` with a registry that no longer contains the `prometheus` operator at all.
+
+### Container Tooling
+
+Of note, many of these commands require some form of shelling to common container tooling (in the general case at least to pull the bundle image and extract the contents to update the registry). By default, the container tool that `opm` shells to is [podman](https://podman.io/). However, we also support overriding this via the `--container-tool` flag in all of these commands:
+
+`opm registry add -b "quay.io/operator-framework/operator-bundle-prometheus:0.14.0" -d "test-registry.db" --container-tool docker`
+
+This will run `opm registry add` via the docker runtime.