Skip to content

Commit

Permalink
docs/design: Remove all references to the bundle alpha opm commands
Browse files Browse the repository at this point in the history 
Signed-off-by: timflannagan <[email protected]>
  • Loading branch information
@timflannagan
timflannagan committed Feb 15, 2021
1 parent 12de30e commit 580c36f
Showing 1 changed file with 0 additions and 165 deletions.
165 changes: 0 additions & 165 deletions docs/design/operator-bundle.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -131,168 +131,3 @@ make build
```

Now, a binary named `opm` is now built in current directory and ready to be used.

### Generating Bundle Annotations and DockerFile

*Notes:*

* If there are `annotations.yaml` and `Dockerfile` existing in the directory, they will be overwritten.

Using `opm` CLI, bundle annotations can be generated from provided operator manifests. The overall `bundle generate` command usage is:

```bash
Usage:
opm alpha bundle generate [flags]
Flags:
-c, --channels string The list of channels that bundle image belongs to
-e, --default string The default channel for the bundle image
-d, --directory string The directory where bundle manifests for a specific version are located.
-h, --help help for generate
-u, --output-dir string Optional output directory for operator manifests
-p, --package string The name of the package that bundle image belongs to
Note:
* All manifests yaml must be in the same directory.
```

The `--directory/-d`, `--channels/-c`, `--package/-p` are required flags while `--default/-e` and `--output-dir/-u` are optional.

The command for `generate` task is:

```bash
$ ./opm alpha bundle generate --directory /test --package test-operator \
--channels stable,beta --default stable
```

The `--directory` or `-d` specifies the directory where the operator manifests, including CSVs and CRDs, are located. For example:

```bash
$ tree test
test
├── etcdcluster.crd.yaml
└── etcdoperator.clusterserviceversion.yaml
```

The `--package` or `-p` is the name of package of the operator such as `etcd`, which maps `channels` to a particular application definition. `channels` allow package authors to write different upgrade paths for different users (e.g. `beta` vs. `stable`). The `channels` list is provided via the `--channels` or `-c` flag. Multiple `channels` are separated by a comma (`,`). The default channel is provided optionally via `--default` or `-e` flag. If the default channel is not provided, the first channel in the list of channels is selected as the default.

**Note**: All information specified in `annotations.yaml` must also exist in the `LABEL` section of a `Dockerfile`.

After the generate command is executed, the `Dockerfile` is generated in the same directory where the command was run. By default, the `annotations.yaml` file is located in a folder named `metadata` in the same root directory as the input directory containing manifests.

For example:

```bash
$ tree test
test
├── my-manifests
│ ├── etcdcluster.crd.yaml
│ └── etcdoperator.clusterserviceversion.yaml
├── metadata
│   └── annotations.yaml
└── Dockerfile
```

If the `--output-dir` parameter is specified, that directory becomes the parent for a new pair of folders `manifests/` and `metadata/`, where `manifests/` is a copy of the passed in directory of manifests and `metadata/` is the folder containing the `annotations.yaml` file:

```bash
$ tree test
test
├── my-manifests
│ ├── etcdcluster.crd.yaml
│ └── etcdoperator.clusterserviceversion.yaml
├── my-output-manifest-dir
│ ├── manifests
│ │ ├── etcdoperator.clusterserviceversion.yaml
│ │ └── etcdoperator.clusterserviceversion.yaml
│   └── metadata
│ └── annotations.yaml
└── Dockerfile
```

The `Dockerfile` can be used manually to build the bundle image using various container image tooling such as Docker, Podman or Buildah.

The following example uses `docker` to build the bundle image:

```bash
docker build -f /path/to/Dockerfile -t quay.io/test/test-operator:latest /path/to/manifests/
```

### Build Bundle Image

An operator bundle image can be built from the provided operator manifests using the `build` command (see *Notes* below).

The overall `bundle build` command usage is:

```bash
Usage:
opm alpha bundle build [flags]
Flags:
-c, --channels string The list of channels that bundle image belongs to
-e, --default string The default channel for the bundle image
-d, --directory string The directory where bundle manifests for a specific version are located
-h, --help help for build
-b, --image-builder string Tool to build container images. One of: [docker, podman, buildah] (default "docker")
-u, --output-dir string Optional output directory for operator manifests
-0, --overwrite To overwrite annotations.yaml if existing
-p, --package string The name of the package that bundle image belongs to
-t, --tag string The name of the bundle image will be built
Note:
* Bundle image is not runnable.
* All manifests yaml must be in the same directory.
```

The command for the `build` task is:

```bash
$ ./opm alpha bundle build --directory /test --tag quay.io/coreos/test-operator.v0.1.0:latest \
--package test-operator --channels stable,beta --default stable
```

The `--directory` or `-d` specifies the directory location that contains the manifests for a specific version of an operator. The `--tag` or `-t` specifies the image tag that you want the operator bundle image to have. By using `build` command, the `annotations.yaml` and `Dockerfile` are automatically generated in the background.

The default image builder is `Docker`. However, `Buildah` and `Podman` are also supported. An image builder can be specified via `--image-builder` or the optional `-b` tag in the `build` command. For example:

```bash
$ ./opm alpha bundle build --directory /test/0.1.0/ \
--tag quay.io/coreos/test-operator.v0.1.0:latest \
--image-builder podman --package test-operator \
--channels stable,beta --default stable
```

The `--package` or `-p` is the name of the package for the operator such as `etcd`, which maps `channels` to a particular application definition. Here, `channels` allow package authors to write different upgrade paths for different users (e.g. `beta` vs. `stable`). The `channels` list is provided via `--channels` or `-c` flag. Multiple `channels` are separated by a comma (`,`). The default channel is provided optionally via `--default` or `-e` flag.

*Notes:*

* If there is `Dockerfile` existing in the directory, it will be overwritten.
* If there is an existing `annotations.yaml` in `/metadata` directory, the cli will attempt to validate it and returns any found errors. If the ``annotations.yaml`` is valid, it will be used as a part of build process. The optional boolean `--overwrite/-o` flag can be enabled (false by default) to allow cli to overwrite the `annotations.yaml` if existed.

### Validate Bundle Image

Operator bundle image can validate bundle image that is publicly available in an image registry using `validate` command (see *Notes* below). The overall `bundle validate` command usage is:

```bash
Usage:
opm alpha bundle validate [flags]
Flags:
-t, --tag string The name of the bundle image will be built
-b, --image-builder string Tool to extract container images. One of: [docker, podman] (default "docker")
-h, --help help for build
```

The command for `validate` task is:

```bash
./opm alpha bundle validate --tag quay.io/coreos/test-operator.v0.1.0:latest --image-builder docker
```

The `validate` command will first extract the content of the bundle image into a temporary directory after it pulls the image from its image registry. Then, it will validate the format of bundle image to ensure manifests and metadata are located in their appropriate directories (`/manifests/` for bundle manifests files such as CSV and `/metadata/` for metadata files such as `annotations.yaml`). Also, it will validate the information in `annotations.yaml` to confirm that metadata is matching the provided data. For example, the provided media type in annotations.yaml just matches the actual media type is provided in the bundle image.

After the bundle image format is confirmed, the command will validate the bundle contents such as manifests and metadata files if the bundle format is `RegistryV1` or "Plain" type. "RegistryV1" format means it contains `ClusterServiceVersion` and its associated Kubernetes objects while `PlainType` means it contains all Kubernetes objects. The content validation process will ensure the individual file in the bundle image is valid and can be applied to an OLM-enabled cluster provided all necessary permissions and configurations are met.

*Notes:*

* The bundle content validation is best effort which means it will not guarantee 100% accuracy due to nature of Kubernetes objects may need certain permissions and configurations, which users may not have, in order to be applied successfully in a cluster.

0 comments on commit 580c36f

Please sign in to comment.