From e8cf98bebb2a038d8c97f730a63af84a6a7079fc Mon Sep 17 00:00:00 2001 From: Alex Dellapenta Date: Sun, 7 Feb 2021 23:12:36 -0700 Subject: [PATCH] Add run bundle-upgrade --- modules/osdk-building-bundle-image.adoc | 65 ------------------ modules/osdk-bundle-deploy-olm.adoc | 7 +- modules/osdk-bundle-upgrade-olm.adoc | 67 +++++++++++++++++++ ...-prereqs.adoc => osdk-common-prereqs.adoc} | 3 +- .../ansible/osdk-ansible-quickstart.adoc | 2 +- .../ansible/osdk-ansible-tutorial.adoc | 2 +- .../golang/osdk-golang-quickstart.adoc | 2 +- .../golang/osdk-golang-tutorial.adoc | 2 +- .../helm/osdk-helm-quickstart.adoc | 2 +- .../operator_sdk/helm/osdk-helm-tutorial.adoc | 2 +- .../osdk-working-bundle-images.adoc | 9 ++- 11 files changed, 85 insertions(+), 78 deletions(-) delete mode 100644 modules/osdk-building-bundle-image.adoc create mode 100644 modules/osdk-bundle-upgrade-olm.adoc rename modules/{osdk-create-operator-prereqs.adoc => osdk-common-prereqs.adoc} (94%) diff --git a/modules/osdk-building-bundle-image.adoc b/modules/osdk-building-bundle-image.adoc deleted file mode 100644 index 4982b2041c..0000000000 --- a/modules/osdk-building-bundle-image.adoc +++ /dev/null @@ -1,65 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-working-bundle-images.adoc - -[id="osdk-building-bundle-image_{context}"] -= Building a bundle image - -You can build, push, and validate an Operator bundle image using the Operator SDK. - -.Prerequisites - -* Operator SDK version 0.19.4 -* `podman` version 1.9.3+ -* An Operator project generated using the Operator SDK -* Access to a registry that supports link:https://docs.docker.com/registry/spec/manifest-v2-2/[Docker v2-2] - -.Procedure - -. From your Operator project directory, build the bundle image using the Operator SDK: -+ -[source,terminal] ----- -$ operator-sdk bundle create \ - //: \//<1> - -b podman <2> ----- -<1> The image tag that you want the bundle image to have. -<2> The CLI tool to use for building the container image, either `docker` (default), `podman`, or `buildah`. This example uses `podman`. -+ -[NOTE] -==== -If your local manifests are not located in the default `/deploy/olm-catalog//manifests`, specify the location with the `--directory` flag. -==== - -. Log in to the registry where you want to push the bundle image. For example: -+ -[source,terminal] ----- -$ podman login ----- - -. Push the bundle image to the registry: -+ -[source,terminal] ----- -$ podman push //: ----- - -. Validate the bundle image in the remote registry: -+ -[source,terminal] ----- -$ operator-sdk bundle validate \ - //: \ - -b podman ----- -+ -.Example output -[source,terminal] ----- -INFO[0000] Unpacked image layers bundle-dir=/tmp/bundle-041168359 container-tool=podman -INFO[0000] running podman pull bundle-dir=/tmp/bundle-041168359 container-tool=podman -INFO[0002] running podman save bundle-dir=/tmp/bundle-041168359 container-tool=podman -INFO[0002] All validation tests have completed successfully bundle-dir=/tmp/bundle-041168359 container-tool=podman ----- diff --git a/modules/osdk-bundle-deploy-olm.adoc b/modules/osdk-bundle-deploy-olm.adoc index 4ae81c6e81..f43df2e28f 100644 --- 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 new file mode 100644 index 0000000000..80878f9eb2 --- /dev/null +++ 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 //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 //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-create-operator-prereqs.adoc b/modules/osdk-common-prereqs.adoc similarity index 94% rename from modules/osdk-create-operator-prereqs.adoc rename to modules/osdk-common-prereqs.adoc index 3df7196fbf..2c07bde165 100644 --- a/modules/osdk-create-operator-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 index 0cfa39f3f7..dc58433d4e 100644 --- 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 index a164397d06..ca3e297e91 100644 --- 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 index e874158e19..55d0720c9b 100644 --- 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 index 47f9f7fa9c..8932c5739d 100644 --- 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 index ed14d4ea17..7d51b159c9 100644 --- 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 index c9c03aee2e..1b71481124 100644 --- 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 index d10b9e5620..7b4b5d4469 100644 --- 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.