Add run bundle-upgrade

adellape · adellape · commit 80a1ffe1e137 · 2021-02-08T19:53:48.000-07:00
diff --git a/modules/osdk-building-bundle-image.adoc b/modules/osdk-building-bundle-image.adoc
diff --git a/modules/osdk-bundle-deploy-olm.adoc b/modules/osdk-bundle-deploy-olm.adoc
@@ -3,17 +3,18 @@
 // * operators/operator_sdk/golang/osdk-golang-tutorial.adoc
 // * operators/operator_sdk/ansible/osdk-ansible-tutorial.adoc
 // * operators/operator_sdk/helm/osdk-helm-tutorial.adoc
+// * operators/operator_sdk/osdk-working-bundle-images.adoc
 
 ifeval::["{context}" == "osdk-golang-tutorial"]
 :golang:
 endif::[]
 
 [id="osdk-bundle-deploy-olm_{context}"]
-= Bundling and deploying with OLM
+= Bundling an Operator and deploying on Operator Lifecycle Manager
 
 Operator Lifecycle Manager (OLM) helps you to install, update, and generally manage the lifecycle of Operators and their associated services on a Kubernetes cluster. OLM is installed by default on {product-title} and runs as a Kubernetes extension so that you can use the web console and the OpenShift CLI (`oc`) for all Operator lifecycle management functions without any additional tools.
 
-This example walks through getting an Operator ready for OLM that uses the Bundle Format, the default packaging format for Operator SDK and OLM.
+The Operator Bundle Format is the default packaging method for Operator SDK and OLM. You can get your Operator ready for OLM by building, pushing, validating, and running a bundle image on OLM with the Operator SDK.
 
 .Prerequisites
 
@@ -28,7 +29,7 @@ endif::[]
 
 .Procedure
 
-. Run the following `make` commands to build and push your Operator image. Modify the `IMG` argument in the following steps to reference a repository that you have access to. You can obtain an account for storing containers at repository sites such as Quay.io.
+. Run the following `make` commands in your Operator project directory to build and push your Operator image. Modify the `IMG` argument in the following steps to reference a repository that you have access to. You can obtain an account for storing containers at repository sites such as Quay.io.
 
 .. Build the image:
 +
diff --git a/modules/osdk-bundle-upgrade-olm.adoc b/modules/osdk-bundle-upgrade-olm.adoc
@@ -0,0 +1,67 @@
+// Module included in the following assemblies:
+//
+// * operators/operator_sdk/osdk-working-bundle-images.adoc
+
+[id="osdk-bundle-upgrade-olm_{context}"]
+= Testing an Operator upgrade on Operator Lifecycle Manager
+
+You can quickly test upgrading your Operator by using Operator Lifecycle Manager (OLM) integration in the Operator SDK, without requiring you to manually manage index images and catalog sources.
+
+The `run bundle-upgrade` subcommand automates triggering an installed Operator to upgrade to a later version by specifying a bundle image for the later version.
+
+.Prerequisites
+
+- Operator installed with OLM by using the `run bundle` subcommand
+- A bundle image that represents a later version of the installed Operator
+
+.Procedure
+
+. If your Operator has not already been installed on OLM with the `run bundle` subcommand, install the earlier version of your Operator by specifying the bundle image. For example, for a Memcached Operator:
++
+[source,terminal]
+----
+$ operator-sdk run bundle <registry>/<user>/memcached-operator:v0.0.1
+----
++
+.Example output
+[source,terminal]
+----
+INFO[0009] Successfully created registry pod: quay-io-demo-memcached-operator-v0-0-1
+INFO[0009] Created CatalogSource: memcached-operator-catalog
+INFO[0010] OperatorGroup "operator-sdk-og" created
+INFO[0010] Created Subscription: memcached-operator-v0-0-1-sub
+INFO[0013] Approved InstallPlan install-bqggr for the Subscription: memcached-operator-v0-0-1-sub
+INFO[0013] Waiting for ClusterServiceVersion "my-project/memcached-operator.v0.0.1" to reach 'Succeeded' phase
+INFO[0013]   Waiting for ClusterServiceVersion "my-project/memcached-operator.v0.0.1" to appear
+INFO[0019]   Found ClusterServiceVersion "my-project/memcached-operator.v0.0.1" phase: Succeeded
+----
+
+. Upgrade the installed Operator by specifying the bundle image for the later Operator version:
++
+[source,terminal]
+----
+$ operator-sdk run bundle-upgrade <registry>/<user>/memcached-operator:v0.0.2
+----
++
+.Example output
+[source,terminal]
+----
+INFO[0002] Found existing subscription with name memcached-operator-v0-0-1-sub and namespace my-project
+INFO[0002] Found existing catalog source with name memcached-operator-catalog and namespace my-project
+INFO[0009] Successfully created registry pod: quay-io-demo-memcached-operator-v0-0-2
+INFO[0009] Updated catalog source memcached-operator-catalog with address and annotations
+INFO[0010] Deleted previous registry pod with name "quay-io-demo-memcached-operator-v0-0-1"
+INFO[0041] Approved InstallPlan install-gvcjh for the Subscription: memcached-operator-v0-0-1-sub
+INFO[0042] Waiting for ClusterServiceVersion "my-project/memcached-operator.v0.0.2" to reach 'Succeeded' phase
+INFO[0042]   Found ClusterServiceVersion "my-project/memcached-operator.v0.0.2" phase: InstallReady
+INFO[0043]   Found ClusterServiceVersion "my-project/memcached-operator.v0.0.2" phase: Installing
+INFO[0044]   Found ClusterServiceVersion "my-project/memcached-operator.v0.0.2" phase: Succeeded
+INFO[0044] Successfully upgraded to "memcached-operator.v0.0.2"
+----
+
+. Clean up the installed Operators:
++
+[source,terminal]
+----
+$ operator-sdk cleanup memcached-operator
+----
diff --git a/modules/osdk-common-prereqs.adoc b/modules/osdk-common-prereqs.adoc
@@ -6,6 +6,7 @@
 // * operators/operator_sdk/ansible/osdk-ansible-tutorial.adoc
 // * operators/operator_sdk/helm/osdk-helm-quickstart.adoc
 // * operators/operator_sdk/helm/osdk-helm-tutorial.adoc
+// * operators/operator_sdk/osdk-working-bundle-images.adoc
 
 ifeval::["{context}" == "osdk-ansible-quickstart"]
 :ansible:
@@ -14,7 +15,7 @@ ifeval::["{context}" == "osdk-ansible-tutorial"]
 :ansible:
 endif::[]
 
-[id="osdk-create-operator-prereqs_{context}"]
+[id="osdk-common-prereqs_{context}"]
 = Prerequisites
 
 - xref:../../../operators/operator_sdk/osdk-installing-cli.adoc#osdk-installing-cli[Operator SDK CLI installed]
diff --git a/operators/operator_sdk/ansible/osdk-ansible-quickstart.adoc b/operators/operator_sdk/ansible/osdk-ansible-quickstart.adoc
@@ -9,7 +9,7 @@ The Operator SDK includes options for generating an Operator project that levera
 
 To demonstrate the basics of setting up and running an link:https://docs.ansible.com/ansible/latest/index.html[Ansible]-based Operator using tools and libraries provided by the Operator SDK, Operator developers can build an example Ansible-based Operator for Memcached, a distributed key-value store, and deploy it to a cluster.
 
-include::modules/osdk-create-operator-prereqs.adoc[leveloffset=+1]
+include::modules/osdk-common-prereqs.adoc[leveloffset=+1]
 include::modules/osdk-quickstart.adoc[leveloffset=+1]
 
 [id="osdk-ansible-quickstart-next-steps"]
diff --git a/operators/operator_sdk/ansible/osdk-ansible-tutorial.adoc b/operators/operator_sdk/ansible/osdk-ansible-tutorial.adoc
@@ -22,7 +22,7 @@ Operator Lifecycle Manager (OLM):: Installation, upgrade, and role-based access
 This tutorial goes into greater detail than xref:../../../operators/operator_sdk/ansible/osdk-ansible-quickstart.adoc#osdk-ansible-quickstart[Operator SDK quickstart for Ansible-based Operators].
 ====
 
-include::modules/osdk-create-operator-prereqs.adoc[leveloffset=+1]
+include::modules/osdk-common-prereqs.adoc[leveloffset=+1]
 
 include::modules/osdk-create-project.adoc[leveloffset=+1]
 include::modules/osdk-project-file.adoc[leveloffset=+2]
diff --git a/operators/operator_sdk/golang/osdk-golang-quickstart.adoc b/operators/operator_sdk/golang/osdk-golang-quickstart.adoc
@@ -7,7 +7,7 @@ toc::[]
 
 To demonstrate the basics of setting up and running a Go-based Operator using tools and libraries provided by the Operator SDK, Operator developers can build an example Go-based Operator for Memcached, a distributed key-value store, and deploy it to a cluster.
 
-include::modules/osdk-create-operator-prereqs.adoc[leveloffset=+1]
+include::modules/osdk-common-prereqs.adoc[leveloffset=+1]
 include::modules/osdk-quickstart.adoc[leveloffset=+1]
 
 [id="osdk-golang-quickstart-next-steps"]
diff --git a/operators/operator_sdk/golang/osdk-golang-tutorial.adoc b/operators/operator_sdk/golang/osdk-golang-tutorial.adoc
@@ -18,7 +18,7 @@ Operator Lifecycle Manager (OLM):: Installation, upgrade, and role-based access
 This tutorial goes into greater detail than xref:../../../operators/operator_sdk/golang/osdk-golang-quickstart.adoc#osdk-golang-quickstart[Operator SDK quickstart for Go-based Operators].
 ====
 
-include::modules/osdk-create-operator-prereqs.adoc[leveloffset=+1]
+include::modules/osdk-common-prereqs.adoc[leveloffset=+1]
 
 include::modules/osdk-create-project.adoc[leveloffset=+1]
 include::modules/osdk-project-file.adoc[leveloffset=+2]
diff --git a/operators/operator_sdk/helm/osdk-helm-quickstart.adoc b/operators/operator_sdk/helm/osdk-helm-quickstart.adoc
@@ -9,7 +9,7 @@ The Operator SDK includes options for generating an Operator project that levera
 
 To demonstrate the basics of setting up and running an link:https://helm.sh/docs/[Helm]-based Operator using tools and libraries provided by the Operator SDK, Operator developers can build an example Helm-based Operator for Nginx and deploy it to a cluster.
 
-include::modules/osdk-create-operator-prereqs.adoc[leveloffset=+1]
+include::modules/osdk-common-prereqs.adoc[leveloffset=+1]
 include::modules/osdk-quickstart.adoc[leveloffset=+1]
 
 [id="osdk-helm-quickstart-next-steps"]
diff --git a/operators/operator_sdk/helm/osdk-helm-tutorial.adoc b/operators/operator_sdk/helm/osdk-helm-tutorial.adoc
@@ -22,7 +22,7 @@ Operator Lifecycle Manager (OLM):: Installation, upgrade, and role-based access
 This tutorial goes into greater detail than xref:../../../operators/operator_sdk/helm/osdk-helm-quickstart.adoc#osdk-helm-quickstart[Operator SDK quickstart for Helm-based Operators].
 ====
 
-include::modules/osdk-create-operator-prereqs.adoc[leveloffset=+1]
+include::modules/osdk-common-prereqs.adoc[leveloffset=+1]
 
 include::modules/osdk-create-project.adoc[leveloffset=+1]
 include::modules/osdk-helm-existing-chart.adoc[leveloffset=+2]
diff --git a/operators/operator_sdk/osdk-working-bundle-images.adoc b/operators/operator_sdk/osdk-working-bundle-images.adoc
@@ -5,11 +5,14 @@ include::modules/common-attributes.adoc[]
 
 toc::[]
 
-You can use the Operator SDK to package Operators using the Bundle Format.
+You can use the Operator SDK to package, deploy, and upgrade Operators in the Bundle Format on Operator Lifecycle Manager (OLM).
 
-include::modules/osdk-building-bundle-image.adoc[leveloffset=+1]
+include::modules/osdk-bundle-deploy-olm.adoc[leveloffset=+1]
+include::modules/osdk-bundle-upgrade-olm.adoc[leveloffset=+1]
 
 [id="osdk-working-bundle-images-additional-resources"]
 == Additional resources
 
-* See xref:../../operators/understanding/olm-packaging-format.adoc#olm-bundle-format_olm-packaging-format[Operator Framework packaging formats] for more details on the Bundle Format.
+* See xref:../../operators/understanding/olm-packaging-format.adoc#olm-bundle-format_olm-packaging-format[Operator Framework packaging formats] for details on the Bundle Format.
+* See xref:../../operators/admin/olm-managing-custom-catalogs.html#olm-managing-custom-catalogs#[Managing custom catalogs] for details on adding bundle images to index images by using the `opm` command.
+* See xref:../../operators/understanding/olm/olm-workflow.adoc#olm-workflow[Operator Lifecycle Manager workflow] for details on how upgrades work for installed Operators.
