docs: OLM integration docs reference new commands (new and legacy CLI) (#3320)

Author: Eric Stroczynski

cmd/operator-sdk/bundle/cmd.go

@@ -38,26 +38,32 @@ An operator bundle is a portable operator packaging format understood by Kuberne
 native software, like the Operator Lifecycle Manager.
 
 More information about operator bundles and metadata:
-https://github.com/operator-framework/operator-registry#manifest-format.
-
-More information about the integration with OLM via SDK:
-https://sdk.operatorframework.io/docs/olm-integration/
+https://github.com/operator-framework/operator-registry/blob/master/docs/design/operator-bundle.md
 `,
 }
 return cmd
 }
 
 func NewCmdLegacy() *cobra.Command {
 cmd := newCmd()
+// TODO(estroz): uncomment this once OLM integration docs are updated.
+//	cmd.Long += `
+// More information about the integration with OLM via SDK:
+// https://sdk.operatorframework.io/docs/olm-integration/legacy
+// `
 cmd.AddCommand(
 newCreateCmd(),
-newValidateCmd(),
+newValidateCmdLegacy(),
 )
 return cmd
 }
 
 func NewCmd() *cobra.Command {
 cmd := newCmd()
+cmd.Long += `
+More information about the integration with OLM via SDK:
+https://sdk.operatorframework.io/docs/olm-integration
+`
 cmd.AddCommand(
 newValidateCmd(),
 )

cmd/operator-sdk/bundle/validate.go

@@ -38,53 +38,90 @@ import (
 internalregistry "github.com/operator-framework/operator-sdk/internal/registry"
 )
 
-type bundleValidateCmd struct {
-bundleCmd
+const (
+longHelp = `The 'operator-sdk bundle validate' command can validate both content and format of an operator bundle
+image or an operator bundle directory on-disk containing operator metadata and manifests. This command will exit
+with an exit code of 1 if any validation errors arise, and 0 if only warnings arise or all validators pass.
 
-outputFormat string
-}
+More information about operator bundles and metadata:
+https://github.com/operator-framework/operator-registry/blob/master/docs/design/operator-bundle.md
 
-// newValidateCmd returns a command that will validate an operator bundle image.
-func newValidateCmd() *cobra.Command {
-c := bundleValidateCmd{}
-cmd := &cobra.Command{
-Use: "validate",
-Short: "Validate an operator bundle image",
-Long: `The 'operator-sdk bundle validate' command can validate both content and
-format of an operator bundle image or an operator bundles directory on-disk
-containing operator metadata and manifests. This command will exit with an
-exit code of 1 if any validation errors arise, and 0 if only warnings arise or
-all validators pass.
+NOTE: if validating an image, the image must exist in a remote registry, not just locally.
+`
 
-More information about operator bundles and metadata:
-https://github.com/operator-framework/operator-registry#manifest-format.
+examples = `The following command flow will generate test-operator bundle manifests and metadata,
+then validate them for 'test-operator' version v0.1.0:
+
+ # Generate manifests and metadata locally.
+ $ make bundle
+
+ # Validate the directory containing manifests and metadata.
+ $ operator-sdk bundle validate ./bundle
+
+To build and validate an image built with the above manifests and metadata:
+
+ # Create a registry namespace or use an existing one.
+ $ export NAMESPACE=<your registry namespace>
+
+ # Build and push the image using the docker CLI.
+ $ docker build -f bundle.Dockerfile -t quay.io/$NAMESPACE/test-operator:v0.1.0 .
+ $ docker push quay.io/$NAMESPACE/test-operator:v0.1.0
 
-NOTE: if validating an image, the image must exist in a remote registry, not
-just locally.
-`,
-Example: `The following command flow will generate test-operator bundle image manifests
-and validate them, assuming a bundle for 'test-operator' version v0.1.0 exists at
-<project-root>/deploy/olm-catalog/test-operator/manifests:
+ # Ensure the image with modified metadata and Dockerfile is valid.
+ $ operator-sdk bundle validate quay.io/$NAMESPACE/test-operator:v0.1.0
+`
+
+examplesLegacy = `The following command flow will generate test-operator bundle manifests and metadata,
+then validate them for 'test-operator' version v0.1.0:
 
- # Generate manifests locally.
- $ operator-sdk bundle create --generate-only
+ # Generate manifests and metadata locally.
+ $ operator-sdk generate bundle --version 0.1.0
 
  # Validate the directory containing manifests and metadata.
  $ operator-sdk bundle validate ./deploy/olm-catalog/test-operator
 
-To build and validate an image:
+To build and validate an image built with the above manifests and metadata:
 
  # Create a registry namespace or use an existing one.
  $ export NAMESPACE=<your registry namespace>
 
  # Build and push the image using the docker CLI.
- $ operator-sdk bundle create quay.io/$NAMESPACE/test-operator:v0.1.0
+ $ docker build -f bundle.Dockerfile -t quay.io/$NAMESPACE/test-operator:v0.1.0 .
  $ docker push quay.io/$NAMESPACE/test-operator:v0.1.0
 
  # Ensure the image with modified metadata and Dockerfile is valid.
  $ operator-sdk bundle validate quay.io/$NAMESPACE/test-operator:v0.1.0
+`
+)
+
+type bundleValidateCmd struct {
+bundleCmd
+
+outputFormat string
+}
 
-`,
+// newValidateCmd returns a command that will validate an operator bundle.
+func newValidateCmd() *cobra.Command {
+cmd := makeValidateCmd()
+cmd.Long = longHelp
+cmd.Example = examples
+return cmd
+}
+
+// newValidateCmdLegacy returns a command that will validate an operator bundle for the legacy CLI.
+func newValidateCmdLegacy() *cobra.Command {
+cmd := makeValidateCmd()
+cmd.Long = longHelp
+cmd.Example = examplesLegacy
+return cmd
+}
+
+// makeValidateCmd makes a command that will validate an operator bundle. Help text must be customized.
+func makeValidateCmd() *cobra.Command {
+c := bundleValidateCmd{}
+cmd := &cobra.Command{
+Use: "validate",
+Short: "Validate an operator bundle",
 RunE: func(cmd *cobra.Command, args []string) (err error) {
 if viper.GetBool(flags.VerboseOpt) {
 log.SetLevel(log.DebugLevel)

website/content/en/build/_index.html

@@ -68,7 +68,7 @@ <h2 class="of-heading of-heading--xl">READ THE USER GUIDES</h2>
  <div class="of-section--largetext__item">
  <h2 class="of-heading of-heading--xl">PUBLISH YOUR OPERATOR</h2>
  <p class="of-section--largetext__content">Learn about how you can package your Operator and share with the Kubernetes community using Operator Lifecycle Manager's package management.</p>
- <a href="/docs/olm-integration/user-guide" class="of-button of-button--tertiary">Learn More
+ <a href="/docs/olm-integration/quickstart-bundle" class="of-button of-button--tertiary">Learn More
  <svg class="of-button__icon" enable-background="new 0 0 22 22" version="1.1" viewBox="0 0 22 22" xml:space="preserve" xmlns="http://www.w3.org/2000/svg">
  <path d="M19.5,8l-7.3-7.6c-0.4-0.4-1.1-0.4-1.5,0L9.3,1.8c-0.4,0.4-0.4,1.1,0,1.6l5.2,5.5H1.1C0.5,8.9,0,9.3,0,10V12 c0,0.6,0.5,1.1,1.1,1.1h13.5l-5.2,5.5c-0.4,0.4-0.4,1.1,0,1.6l1.4,1.5c0.4,0.4,1.1,0.4,1.5,0l9.4-9.9c0.4-0.4,0.4-1.1,0-1.6L19.5,8z "/>
  </svg>

website/content/en/docs/ansible/quickstart.md

@@ -243,7 +243,7 @@ INFO[0000] operator-sdk Version: 0.0.5+git
 
 OLM will manage creation of most if not all resources required to run your operator,
 using a bit of setup from other `operator-sdk` commands. Check out the OLM integration
-[user guide][olm-user-guide] for more information.
+[user guide][quickstart-bundle] for more information.
 
 ### Create a Memcached CR
 
@@ -376,4 +376,5 @@ For more information, refer [cli][addcli] doc.
 [docker-tool]:https://docs.docker.com/install/
 [kubectl-tool]:https://kubernetes.io/docs/tasks/tools/install-kubectl/
 [addcli]: /docs/cli/operator-sdk_add_api
-[olm-user-guide]: /docs/olm-integration/user-guide
+<!-- TODO: update this link to the non-legacy doc once the ansible plugin is publicly available -->
+[quickstart-bundle]: /docs/olm-integration/legacy/quickstart-bundle

website/content/en/docs/cli/operator-sdk_bundle.md

@@ -12,10 +12,7 @@ An operator bundle is a portable operator packaging format understood by Kuberne
 native software, like the Operator Lifecycle Manager.
 
 More information about operator bundles and metadata:
-https://github.com/operator-framework/operator-registry#manifest-format.
-
-More information about the integration with OLM via SDK:
-https://sdk.operatorframework.io/docs/olm-integration/
+https://github.com/operator-framework/operator-registry/blob/master/docs/design/operator-bundle.md
 
 
 ### Options
@@ -28,5 +25,5 @@ https://sdk.operatorframework.io/docs/olm-integration/
 
 * [operator-sdk](../operator-sdk) - An SDK for building operators with ease
 * [operator-sdk bundle create](../operator-sdk_bundle_create) - Create an operator bundle image
-* [operator-sdk bundle validate](../operator-sdk_bundle_validate) - Validate an operator bundle image
+* [operator-sdk bundle validate](../operator-sdk_bundle_validate) - Validate an operator bundle
 

website/content/en/docs/cli/operator-sdk_bundle_validate.md

@@ -3,21 +3,18 @@ title: "operator-sdk bundle validate"
 ---
 ## operator-sdk bundle validate
 
-Validate an operator bundle image
+Validate an operator bundle
 
 ### Synopsis
 
-The 'operator-sdk bundle validate' command can validate both content and
-format of an operator bundle image or an operator bundles directory on-disk
-containing operator metadata and manifests. This command will exit with an
-exit code of 1 if any validation errors arise, and 0 if only warnings arise or
-all validators pass.
+The 'operator-sdk bundle validate' command can validate both content and format of an operator bundle
+image or an operator bundle directory on-disk containing operator metadata and manifests. This command will exit
+with an exit code of 1 if any validation errors arise, and 0 if only warnings arise or all validators pass.
 
 More information about operator bundles and metadata:
-https://github.com/operator-framework/operator-registry#manifest-format.
+https://github.com/operator-framework/operator-registry/blob/master/docs/design/operator-bundle.md
 
-NOTE: if validating an image, the image must exist in a remote registry, not
-just locally.
+NOTE: if validating an image, the image must exist in a remote registry, not just locally.
 
 
 ```
@@ -27,29 +24,27 @@ operator-sdk bundle validate [flags]
 ### Examples
 
 ```
-The following command flow will generate test-operator bundle image manifests
-and validate them, assuming a bundle for 'test-operator' version v0.1.0 exists at
-<project-root>/deploy/olm-catalog/test-operator/manifests:
+The following command flow will generate test-operator bundle manifests and metadata,
+then validate them for 'test-operator' version v0.1.0:
 
- # Generate manifests locally.
- $ operator-sdk bundle create --generate-only
+ # Generate manifests and metadata locally.
+ $ operator-sdk generate bundle --version 0.1.0
 
  # Validate the directory containing manifests and metadata.
  $ operator-sdk bundle validate ./deploy/olm-catalog/test-operator
 
-To build and validate an image:
+To build and validate an image built with the above manifests and metadata:
 
  # Create a registry namespace or use an existing one.
  $ export NAMESPACE=<your registry namespace>
 
  # Build and push the image using the docker CLI.
- $ operator-sdk bundle create quay.io/$NAMESPACE/test-operator:v0.1.0
+ $ docker build -f bundle.Dockerfile -t quay.io/$NAMESPACE/test-operator:v0.1.0 .
  $ docker push quay.io/$NAMESPACE/test-operator:v0.1.0
 
  # Ensure the image with modified metadata and Dockerfile is valid.
  $ operator-sdk bundle validate quay.io/$NAMESPACE/test-operator:v0.1.0
 
-
 ```
 
 ### Options

website/content/en/docs/golang/legacy/quickstart.md

@@ -319,6 +319,7 @@ if err != nil {
 reqLogger.Info("Memcached resource not found. Ignoring since object must be deleted")
 return reconcile.Result{}, nil
 }
+}
 ...
 ```
 
@@ -411,7 +412,7 @@ You can use a specific kubeconfig via the flag `--kubeconfig=<path/to/kubeconfig
 
 OLM will manage creation of most if not all resources required to run your operator,
 using a bit of setup from other `operator-sdk` commands. Check out the OLM integration
-[user guide][olm-user-guide] for more information.
+[user guide][quickstart-bundle] for more information.
 
 ## Create a Memcached CR
 
@@ -639,19 +640,23 @@ By default, SDK operator projects are set up to [export metrics][metrics_doc] th
 
 ```go
 func serveCRMetrics(cfg *rest.Config) error {
- ...
-filteredGVK, err := k8sutil.GetGVKsFromAddToScheme(apis.AddToScheme)
+ ...
+
+ filteredGVK, err := k8sutil.GetGVKsFromAddToScheme(apis.AddToScheme)
 if err != nil {
 return err
 }
 
-  ...
+ ...
 
 // Generate and serve custom resource specific metrics.
 err = kubemetrics.GenerateAndServeCRMetrics(cfg, ns, filteredGVK, metricsHost, operatorMetricsPort)
 if err != nil {
 return err
 }
+
+ ...
+}
 ```
 
 The `kubemetrics.GenerateAndServeCRMetrics` function requires an RBAC rule to list all GroupVersionKinds in the list of watched namespaces, so you might need to [filter](https://github.com/operator-framework/operator-sdk/blob/v0.15.2/pkg/k8sutil/k8sutil.go#L161) the kinds returned by [`k8sutil.GetGVKsFromAddToScheme`](https://godoc.org/github.com/operator-framework/operator-sdk/pkg/k8sutil#GetGVKsFromAddToScheme) more stringently to avoid authorization errors such as `Failed to list *unstructured.Unstructured`.
@@ -860,6 +865,6 @@ When the operator is not running in a cluster, the Manager will return an error
 [scheme_builder]: https://godoc.org/sigs.k8s.io/controller-runtime/pkg/scheme#Builder
 [typical-status-properties]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties
 [godoc-conditions]: https://godoc.org/github.com/operator-framework/operator-sdk/pkg/status#Conditions
-[olm-user-guide]: /docs/olm-integration/user-guide
+[quickstart-bundle]: /docs/olm-integration/legacy/quickstart-bundle
 [new_docs]:/docs/golang/quickstart
-[new_CLI]:/docs/new-cli
+[new_CLI]:/docs/new-cli

website/content/en/docs/golang/legacy/references/markers.md

@@ -14,7 +14,8 @@ This section details ClusterServiceVersion (CSV) [code markers][code-markers-des
 
 ## Usage
 
-All markers have a `+operator-sdk:gen-csv` prefix, denoting that they're parsed while executing [`operator-sdk generate csv`][generate-csv-cli].
+All markers have a `+operator-sdk:gen-csv` prefix, denoting that they're parsed while executing
+[`operator-sdk generate bundle`][cli-gen-bundle] or [`operator-sdk generate packagemanifests`][cli-gen-packagemanifests].
 
 ### Paths
 
@@ -203,6 +204,7 @@ customresourcedefinitions:
 
 [markers]:https://pkg.go.dev/sigs.k8s.io/controller-tools/pkg/markers
 [code-markers-design]:https://github.com/operator-framework/operator-sdk/blob/master/proposals/sdk-code-annotations.md
-[generate-csv-cli]:/docs/cli/operator-sdk_generate_csv
+[cli-gen-bundle]:/docs/cli/operator-sdk_generate_bundle
+[cli-gen-packagemanifests]:/docs/cli/operator-sdk_generate_packagemanifests
 [csv-x-desc]:https://github.com/openshift/console/blob/feabd61/frontend/packages/operator-lifecycle-manager/src/components/descriptors/types.ts#L3-L39
 [csv-spec]:https://github.com/operator-framework/operator-lifecycle-manager/blob/e0eea22/doc/design/building-your-csv.md

website/content/en/docs/golang/references/markers.md

@@ -14,7 +14,8 @@ This section details ClusterServiceVersion (CSV) [code markers][code-markers-des
 
 ## Usage
 
-All markers have a `+operator-sdk:gen-csv` prefix, denoting that they're parsed while executing [`operator-sdk generate csv`][generate-csv-cli].
+All markers have a `+operator-sdk:gen-csv` prefix, denoting that they're parsed while executing
+[`operator-sdk generate kustomize manifests`][cli-gen-kustomize-manifests].
 
 ### Paths
 
@@ -203,6 +204,6 @@ customresourcedefinitions:
 
 [markers]:https://pkg.go.dev/sigs.k8s.io/controller-tools/pkg/markers
 [code-markers-design]:https://github.com/operator-framework/operator-sdk/blob/master/proposals/sdk-code-annotations.md
-[generate-csv-cli]:/docs/cli/operator-sdk_generate_csv
+[cli-gen-kustomize-manifests]:/docs/new-cli/operator-sdk_generate_kustomize_manifests
 [csv-x-desc]:https://github.com/openshift/console/blob/feabd61/frontend/packages/operator-lifecycle-manager/src/components/descriptors/types.ts#L3-L39
 [csv-spec]:https://github.com/operator-framework/operator-lifecycle-manager/blob/e0eea22/doc/design/building-your-csv.md

website/content/en/docs/helm/quickstart.md

@@ -224,7 +224,7 @@ INFO[0000] operator-sdk Version: v0.2.0+git
 
 OLM will manage creation of most if not all resources required to run your operator,
 using a bit of setup from other `operator-sdk` commands. Check out the OLM integration
-[user guide][olm-user-guide] for more information.
+[user guide][quickstart-bundle] for more information.
 
 ## Deploy the Nginx custom resource
 
@@ -313,4 +313,5 @@ For more information, refer [cli][addcli] doc.
 [helm-values]:https://helm.sh/docs/intro/using_helm/#customizing-the-chart-before-installing
 [helm-official]:https://helm.sh/docs/
 [addcli]: /docs/cli/operator-sdk_add_api
-[olm-user-guide]: /docs/olm-integration/user-guide
+<!-- TODO: update this link to the non-legacy doc once the helm plugin is publicly available -->
+[quickstart-bundle]: /docs/olm-integration/legacy/quickstart-bundle