Clean up minor issues with command-line code and documentation

1. Clarify a few helper texts in cli code
2. Improve librar document to specific input information
3. Move `bundle` comands under hidden `alpha` command

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

Author: dinhxuanvu

cmd/opm/bundle/build.go cmd/opm/alpha/bundle/build.go

@@ -7,17 +7,21 @@ import (
 )
 
 var (
-	dirBuildArgs     string
-	tagBuildArgs     string
-	imageBuilderArgs string
+	dirBuildArgs       string
+	tagBuildArgs       string
+	imageBuilderArgs   string
+	packageNameArgs    string
+	channelsArgs       string
+	channelDefaultArgs string
+	overwriteArgs      bool
 )
 
 // newBundleBuildCmd returns a command that will build operator bundle image.
 func newBundleBuildCmd() *cobra.Command {
 	bundleBuildCmd := &cobra.Command{
 		Use:   "build",
 		Short: "Build operator bundle image",
-		Long: `The opm bundle build command will generate operator
+		Long: `The "opm alpha bundle build" command will generate operator
         bundle metadata if needed and build bundle image with operator manifest
         and metadata.
 
@@ -29,30 +33,46 @@ func newBundleBuildCmd() *cobra.Command {
         After the build process is completed, a container image would be built
         locally in docker and available to push to a container registry.
 
-        $ opm bundle build -dir /test/0.0.1/ -t quay.io/example/operator:v0.0.1
+        $ opm alpha bundle build --directory /test/ --tag quay.io/example/operator:v0.1.0 \
+		--package test-operator --channels stable,beta --default stable --overwrite
 
         Note: Bundle image is not runnable.
         `,
 		RunE: buildFunc,
 	}
 
-	bundleBuildCmd.Flags().StringVarP(&dirBuildArgs, "directory", "d", "", "The directory where bundle manifests are located.")
+	bundleBuildCmd.Flags().StringVarP(&dirBuildArgs, "directory", "d", "", "The directory where bundle manifests and metadata are located")
 	if err := bundleBuildCmd.MarkFlagRequired("directory"); err != nil {
 		log.Fatalf("Failed to mark `directory` flag for `build` subcommand as required")
 	}
 
-	bundleBuildCmd.Flags().StringVarP(&tagBuildArgs, "tag", "t", "", "The name of the bundle image will be built.")
+	bundleBuildCmd.Flags().StringVarP(&tagBuildArgs, "tag", "t", "", "The image tag applied to the bundle image")
 	if err := bundleBuildCmd.MarkFlagRequired("tag"); err != nil {
 		log.Fatalf("Failed to mark `tag` flag for `build` subcommand as required")
 	}
 
+	bundleBuildCmd.Flags().StringVarP(&packageNameArgs, "package", "p", "", "The name of the package that bundle image belongs to")
+	if err := bundleBuildCmd.MarkFlagRequired("package"); err != nil {
+		log.Fatalf("Failed to mark `package` flag for `build` subcommand as required")
+	}
+
+	bundleBuildCmd.Flags().StringVarP(&channelsArgs, "channels", "c", "", "The list of channels that bundle image belongs to")
+	if err := bundleBuildCmd.MarkFlagRequired("channels"); err != nil {
+		log.Fatalf("Failed to mark `channels` flag for `build` subcommand as required")
+	}
+
 	bundleBuildCmd.Flags().StringVarP(&imageBuilderArgs, "image-builder", "b", "docker", "Tool to build container images. One of: [docker, podman, buildah]")
 
+	bundleBuildCmd.Flags().StringVarP(&channelDefaultArgs, "default", "e", "", "The default channel for the bundle image")
+
+	bundleBuildCmd.Flags().BoolVarP(&overwriteArgs, "overwrite", "o", false, "To overwrite annotations.yaml locally if existed. By default, overwrite is set to `false`.")
+
 	return bundleBuildCmd
 }
 
 func buildFunc(cmd *cobra.Command, args []string) error {
-	err := bundle.BuildFunc(dirBuildArgs, tagBuildArgs, imageBuilderArgs)
+	err := bundle.BuildFunc(dirBuildArgs, tagBuildArgs, imageBuilderArgs,
+		packageNameArgs, channelsArgs, channelDefaultArgs, overwriteArgs)
 	if err != nil {
 		return err
 	}

cmd/opm/bundle/cmd.go cmd/opm/alpha/bundle/cmd.go

@@ -6,10 +6,9 @@ import (
 
 func NewCmd() *cobra.Command {
 	runCmd := &cobra.Command{
-		Hidden: true,
-		Use:    "bundle",
-		Short:  "Operator bundle commands",
-		Long:   `Generate operator bundle metadata and build bundle image.`,
+		Use:   "bundle",
+		Short: "Operator bundle commands",
+		Long:  `Generate operator bundle metadata and build bundle image.`,
 	}
 
 	runCmd.AddCommand(newBundleGenerateCmd())

cmd/opm/alpha/bundle/generate.go

@@ -0,0 +1,51 @@
+package bundle
+
+import (
+	"github.com/operator-framework/operator-registry/pkg/lib/bundle"
+	log "github.com/sirupsen/logrus"
+	"github.com/spf13/cobra"
+)
+
+// newBundleGenerateCmd returns a command that will generate operator bundle
+// annotations.yaml metadata
+func newBundleGenerateCmd() *cobra.Command {
+	bundleGenerateCmd := &cobra.Command{
+		Use:   "generate",
+		Short: "Generate operator bundle metadata and Dockerfile",
+		Long: `The "opm alpha bundle generate" command will generate operator
+        bundle metadata if needed and a Dockerfile to build Operator bundle image.
+
+        $ opm alpha bundle generate --directory /test/ --package test-operator \
+		--channels stable,beta --default stable
+        `,
+		RunE: generateFunc,
+	}
+
+	bundleGenerateCmd.Flags().StringVarP(&dirBuildArgs, "directory", "d", "", "The directory where bundle manifests are located.")
+	if err := bundleGenerateCmd.MarkFlagRequired("directory"); err != nil {
+		log.Fatalf("Failed to mark `directory` flag for `generate` subcommand as required")
+	}
+
+	bundleGenerateCmd.Flags().StringVarP(&packageNameArgs, "package", "p", "", "The name of the package that bundle image belongs to")
+	if err := bundleGenerateCmd.MarkFlagRequired("package"); err != nil {
+		log.Fatalf("Failed to mark `package` flag for `generate` subcommand as required")
+	}
+
+	bundleGenerateCmd.Flags().StringVarP(&channelsArgs, "channels", "c", "", "The list of channels that bundle image belongs to")
+	if err := bundleGenerateCmd.MarkFlagRequired("channels"); err != nil {
+		log.Fatalf("Failed to mark `channels` flag for `generate` subcommand as required")
+	}
+
+	bundleGenerateCmd.Flags().StringVarP(&channelDefaultArgs, "default", "e", "", "The default channel for the bundle image")
+
+	return bundleGenerateCmd
+}
+
+func generateFunc(cmd *cobra.Command, args []string) error {
+	err := bundle.GenerateFunc(dirBuildArgs, packageNameArgs, channelsArgs, channelDefaultArgs, true)
+	if err != nil {
+		return err
+	}
+
+	return nil
+}

cmd/opm/alpha/cmd.go

@@ -0,0 +1,17 @@
+package alpha
+
+import (
+	"github.com/operator-framework/operator-registry/cmd/opm/alpha/bundle"
+	"github.com/spf13/cobra"
+)
+
+func NewCmd() *cobra.Command {
+	runCmd := &cobra.Command{
+		Hidden: true,
+		Use:    "alpha",
+		Short:  "Run an alpha subcommand",
+	}
+
+	runCmd.AddCommand(bundle.NewCmd())
+	return runCmd
+}

cmd/opm/bundle/generate.go

@@ -1,10 +1,12 @@
 package main
 
 import (
+	"os"
+
 	"github.com/sirupsen/logrus"
 	"github.com/spf13/cobra"
 
-	"github.com/operator-framework/operator-registry/cmd/opm/bundle"
+	"github.com/operator-framework/operator-registry/cmd/opm/alpha"
 	"github.com/operator-framework/operator-registry/cmd/opm/registry"
 )
 
@@ -13,12 +15,23 @@ func main() {
 		Use:   "opm",
 		Short: "operator package manager",
 		Long:  "CLI to interact with operator-registry and build indexes of operator content",
+		PreRunE: func(cmd *cobra.Command, args []string) error {
+			if debug, _ := cmd.Flags().GetBool("debug"); debug {
+				logrus.SetLevel(logrus.DebugLevel)
+			}
+			return nil
+		},
 	}
 
 	rootCmd.AddCommand(registry.NewOpmRegistryCmd())
-	rootCmd.AddCommand(bundle.NewCmd())
+	rootCmd.AddCommand(alpha.NewCmd())
 
-	if err := rootCmd.Execute(); err != nil {
+	rootCmd.Flags().Bool("debug", false, "enable debug logging")
+	if err := rootCmd.Flags().MarkHidden("debug"); err != nil {
 		logrus.Panic(err.Error())
 	}
+
+	if err := rootCmd.Execute(); err != nil {
+		os.Exit(1)
+	}
 }

cmd/opm/main.go

@@ -1,4 +1,4 @@
-overwrite# Operator Bundle
+# Operator Bundle
 
 An `Operator Bundle` is a container image that stores Kubernetes manifests and metadata associated with an operator. A bundle is meant to present a *specific* version of an operator.
 
@@ -18,19 +18,27 @@ An `Operator Bundle` is built as a scratch (non-runnable) container image that c
 ### Bundle Annotations
 
 We use the following labels to annotate the operator bundle image.
-* The label `operators.operatorframework.io.bundle.resources` represents the bundle type:
-    * The value `manifests` implies that this bundle contains operator manifests only.
-    * The value `metadata` implies that this bundle has operator metadata only.
-    * The value `manifests+metadata` implies that this bundle contains both operator metadata and manifests.
-* The label `operators.operatorframework.io.bundle.mediatype` reflects the media type or format of the operator bundle. It could be helm charts, plain Kubernetes manifests etc.
+* The label `operators.operatorframework.io.bundle.mediatype.v1` reflects the media type or format of the operator bundle. It could be helm charts, plain Kubernetes manifests etc.
+* The label `operators.operatorframework.io.bundle.manifests.v1 `reflects the path in the image to the directory that contains the operator manifests.
+* The label `operators.operatorframework.io.bundle.metadata.v1` reflects the path in the image to the directory that contains metadata files about the bundle.
+* The `manifests.v1` and `metadata.v1` labels imply the bundle type:
+    * The value `manifests.v1` implies that this bundle contains operator manifests.
+    * The value `metadata.v1` implies that this bundle has operator metadata.
+* The label `operators.operatorframework.io.bundle.package.v1` reflects the package name of the bundle.
+* The label `operators.operatorframework.io.bundle.channels.v1` reflects the list of channels the bundle is subscribing to when added into an operator registry
+* The label `operators.operatorframework.io.bundle.channel.default.v1` reflects the default channel an operator should be subscribed to when installed from a registry
 
 The labels will also be put inside a YAML file, as shown below.
 
 *annotations.yaml*
 ```yaml
 annotations:
-  operators.operatorframework.io.bundle.resources: "manifests+metadata"
-  operators.operatorframework.io.bundle.mediatype: "registry+v1"
+  operators.operatorframework.io.bundle.mediatype.v1: "registry+v1"
+  operators.operatorframework.io.bundle.manifests.v1: "manifests/"
+  operators.operatorframework.io.bundle.metadata.v1: "metadata/"
+  operators.operatorframework.io.bundle.package.v1: "test-operator"
+  operators.operatorframework.io.bundle.channels.v1: "beta,stable"
+  operators.operatorframework.io.bundle.channel.default.v1: "stable"
 ```
 
 *Notes:*
@@ -57,11 +65,15 @@ FROM scratch
 
 # We are pushing an operator-registry bundle
 # that has both metadata and manifests.
-LABEL operators.operatorframework.io.bundle.resources=manifests+metadata
-LABEL operators.operatorframework.io.bundle.mediatype=registry+v1
+LABEL operators.operatorframework.io.bundle.mediatype.v1=registry+v1
+LABEL operators.operatorframework.io.bundle.manifests.v1=manifests/
+LABEL operators.operatorframework.io.bundle.metadata.v1=metadata/
+LABEL operators.operatorframework.io.bundle.package.v1=test-operator
+LABEL operators.operatorframework.io.bundle.channels.v1=beta,stable
+LABEL operators.operatorframework.io.bundle.channel.default.v1=stable
 
 ADD test/*.yaml /manifests
-ADD test/annotations.yaml /metadata/annotations.yaml
+ADD test/metadata/annotations.yaml /metadata/annotations.yaml
 ```
 
 Below is the directory layout of the operator bundle inside the image:
@@ -126,7 +138,8 @@ The `--directory/-d`, `--channels/-c`, `--package/-p` are required flags while `
 
 The command for `generate` task is:
 ```bash
-$ ./operator-sdk bundle generate --directory /test --package test-operator --channels stable,beta --default stable
+$ ./operator-sdk bundle generate --directory /test --package test-operator \
+--channels stable,beta --default stable
 ```
 
 The `--directory` or `-d` specifies the directory where the operator manifests are located. The `Dockerfile` is generated in the same directory where the YAML manifests are located while the `annotations.yaml` file is located in a folder named `metadata`. For example:
@@ -166,14 +179,16 @@ Flags:
 
 The command for `build` task is:
 ```bash
-$ ./operator-sdk bundle build --directory /test --tag quay.io/coreos/test-operator.v0.1.0:latest --package test-operator --channels stable,beta --default stable
+$ ./operator-sdk 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 where the operator manifests are located. 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 specified via `--image-builder` or `-b` optional tag in `build` command. For example:
 ```bash
-$ ./operator-sdk 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
+$ ./operator-sdk 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 package fo the operator such as `etcd` which which map `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 `--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 channel list is selected as default.

docs/design/operator-bundle.md

@@ -40,6 +40,19 @@ func ExecuteCommand(cmd *exec.Cmd) error {
 	return nil
 }
 
+// BuildFunc is used to build bundle container image from a list of manifests
+// that exist in local directory and it also generates Dockerfile annotations.yaml
+// which contains media type, package name and channels information if the file
+// doesn't exist locally.
+// Inputs:
+// @directory: The local directory where bundle manifests and metadata are located
+// @imageTag: The image tag that is applied to the bundle image
+// @imageBuilder: The image builder tool that is used to build container image
+// (docker, buildah or podman)
+// @packageName: The name of the package that bundle image belongs to
+// @channels: The list of channels that bundle image belongs to
+// @channelDefault: The default channel for the bundle image
+// @overwrite: Boolean flag to enable overwriting annotations.yaml locally if existed
 func BuildFunc(directory, imageTag, imageBuilder, packageName, channels, channelDefault string, overwrite bool) error {
 	// Generate annotations.yaml and Dockerfile
 	err := GenerateFunc(directory, packageName, channels, channelDefault, overwrite)

pkg/lib/bundle/build.go

@@ -36,6 +36,12 @@ type AnnotationMetadata struct {
 // GenerateFunc builds annotations.yaml with mediatype, manifests &
 // metadata directories in bundle image, package name, channels and default
 // channels information and then writes the file to `/metadata` directory.
+// Inputs:
+// @directory: The local directory where bundle manifests and metadata are located
+// @packageName: The name of the package that bundle image belongs to
+// @channels: The list of channels that bundle image belongs to
+// @channelDefault: The default channel for the bundle image
+// @overwrite: Boolean flag to enable overwriting annotations.yaml locally if existed
 func GenerateFunc(directory, packageName, channels, channelDefault string, overwrite bool) error {
 	var mediaType string