|
| 1 | +--- |
| 2 | +title: "Building a Catalog" |
| 3 | +linkTitle: "Building a Catalog" |
| 4 | +date: 2020-04-27 |
| 5 | +weight: 3 |
| 6 | +description: > |
| 7 | + Build a Catalog of Operators using [Operator-Registry](https://github.com/operator-framework/operator-registry) |
| 8 | +--- |
| 9 | + |
| 10 | +# Manifest format |
| 11 | + |
| 12 | +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. |
| 13 | +<pre></pre> |
| 14 | +``` |
| 15 | + # example bundle |
| 16 | + etcd |
| 17 | + ├── manifests |
| 18 | + │ ├── etcdcluster.crd.yaml |
| 19 | + │ └── etcdoperator.clusterserviceversion.yaml |
| 20 | + └── metadata |
| 21 | + └── annotations.yaml |
| 22 | +``` |
| 23 | +<pre></pre> |
| 24 | +When loading manifests into the database, the following invariants are validated: |
| 25 | +<pre> |
| 26 | + * The bundle must have at least one channel defined in the annotations. |
| 27 | + * Every bundle has exactly one ClusterServiceVersion. |
| 28 | + * If a ClusterServiceVersion `owns` a CRD, that CRD must exist in the bundle. |
| 29 | +</pre> |
| 30 | +Bundle directories are identified solely by the fact that they contain a ClusterServiceVersion, which provides an amount of freedom for layout of manifests. |
| 31 | +<pre></pre> |
| 32 | +Check out the [operator bundle design proposal](https://github.com/operator-framework/operator-registry/blob/master/docs/design/operator-bundle.md) for more detail on the bundle format. |
| 33 | +<pre></pre> |
| 34 | + |
| 35 | +# Bundle images |
| 36 | + |
| 37 | +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 and building that image: |
| 38 | + |
| 39 | +```Dockerfile |
| 40 | +FROM scratch |
| 41 | + |
| 42 | +# We are pushing an operator-registry bundle |
| 43 | +# that has both metadata and manifests. |
| 44 | +LABEL operators.operatorframework.io.bundle.mediatype.v1=registry+v1 |
| 45 | +LABEL operators.operatorframework.io.bundle.manifests.v1=manifests/ |
| 46 | +LABEL operators.operatorframework.io.bundle.metadata.v1=metadata/ |
| 47 | +LABEL operators.operatorframework.io.bundle.package.v1=test-operator |
| 48 | +LABEL operators.operatorframework.io.bundle.channels.v1=beta,stable |
| 49 | +LABEL operators.operatorframework.io.bundle.channel.default.v1=stable |
| 50 | + |
| 51 | +ADD test/*.yaml /manifests |
| 52 | +ADD test/metadata/annotations.yaml /metadata/annotations.yaml |
| 53 | +``` |
| 54 | + |
| 55 | +```sh |
| 56 | +podman build -t quay.io/my-container-registry-namespace/my-manifest-bundle:latest -f bundle.Dockerfile . |
| 57 | +``` |
| 58 | + |
| 59 | +Once you have built the container, you can publish it like any other container image: |
| 60 | + |
| 61 | +```sh |
| 62 | +podman push quay.io/my-container-registry-namespace/my-manifest-bundle:latest |
| 63 | +``` |
| 64 | + |
| 65 | +Of course, this build step can be done with any other OCI spec container tools like `docker`, `buildah`, `libpod`, etc. |
| 66 | +<pre></pre> |
| 67 | + |
| 68 | +# Building an index of Operators using opm |
| 69 | + |
| 70 | + |
| 71 | +<pre></pre> |
| 72 | +Index images are additive, so you can add a new version of your operator bundle when you publish a new version: |
| 73 | +<pre></pre> |
| 74 | +```sh |
| 75 | +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 |
| 76 | +``` |
| 77 | +<pre></pre> |
| 78 | +For more detail on using `opm` to generate index images, take a look at the [documentation](https://github.com/operator-framework/operator-registry/blob/master/docs/design/opm-tooling.md). |
| 79 | +<pre></pre> |
| 80 | +## Where should I go next? |
| 81 | + |
| 82 | +* [Use the catalog of operators locally](/docs/concepts/olm-architecture/operator-registry/using-catalog-locally/): Test your catalog locally |
| 83 | +* [Using a Catalog with OLM](/docs/concepts/olm-architecture/operator-registry/using-catalog-with-olm/): Make your operator available for OLM in a cluster |
| 84 | + |
| 85 | + |
0 commit comments