diff --git a/version_updates.md b/version_updates.md new file mode 100644 index 0000000..a17f070 --- /dev/null +++ b/version_updates.md @@ -0,0 +1,176 @@ +# OpenStackVersion + +## Overview + +This document describes how to use the OpenStackVersion +CR to apply a minor updates to a deployed OpenStack +installation (including both Controlplane and Dataplane +Services) + +## Requirements + + * Use of OLM (Operator Lifecycle Manager) is assumed + * The CSV (ClusterServiceVersion) for the openstack-operator + is used as the primary resource for versioning and the + associated ENV variables for OpenStack service containers. + These are typically prefixed with RELATED\_IMAGE... + The CSV defines the version. + * OpenStack operators are always upgraded first via OLM. This + can be either via manual or automatic. Upgrading operators + may trigger OpenStackVersion to provide access to a new + available version. + * And ENV called OPENSTACK\_RELEASE\_VERSION must be set in the CSV + for openstack-operator. This controls the 'availableVersion' + of OpenStackVersion. + + +## General Update Workflow + +OpenStack is installed by following the normal installation procedure. When +an OpenStackControlplane resource is created in any given namespace an +OpenStackVersion resource will be immediately created when the OpenStackControlPlane +is reconciled (1 OpenStackVersion per namespace). + +When a new set of Operators is installed via OLM (either manually or automatically) +the OpenStackVersion resources will reconcile and a new 'AvailableVersion' will +be set on each CR. + +In order to apply an update an administrator sets the 'TargetVersion' to the +same value as the 'AvailableVersion' on the OpenStackVersion resources. This +triggers the OpenStackVersion to reconcile and will update the images +on the associated OpenStackControlplane and OpenStackDataplane resources in +that namespace. + +```shell +$ oc get openstackversion +NAME TARGET VERSION AVAILABLE VERSION DEPLOYED VERSION +openstack 1.0.0 1.0.1 1.0.0 +``` + +```yaml +apiVersion: core.openstack.org/v1beta1 +kind: OpenStackVersion +metadata: + labels: + name: openstack +spec: + targetVersion: 1.0.1 +``` + +## Custom images for Cinder Volume +In order to allow administrators to configure customized Cinder volume backends +with certified 3rd party vendor containerImages for any of the backends, +administrators will be allowed to explicitly specify those images overriding the +default containerImage during automatic updates. This is a manual operation +because there is no way to fully automate the selection of those images at this +time. To configure a Cinder volume backend named 'pure' with a different image +during the updates, the administrator can add the name 'pure' to the +'cinderVolumeImages' map withing the 'customContainerImages' section of +the OpenStackVersion CR and set a custom image to be used for that volume backend. +Multiple named Cinder volume backends may be configured in this manner. + +NOTE: if the backend does not require a custom container the default cinder +volume container is used automatically. This means if you are only using +backends that requires the default cinder volume container no +edits to the OpenStackVersion resource are needed. + +```yaml +apiVersion: core.openstack.org/v1beta1 +kind: OpenStackVersion +metadata: + labels: + name: openstack +spec: + targetVersion: 1.0.1 + customContainerImages: + cinderVolumeImages: + default: quay.io/podified-antelope-centos9/openstack-cinder-volume@sha256:886942a49a89be8ee12b3b6c220cbea3aead4ee3d9f18f97757eb7d795f241c6 + pure: +``` + +## Custom images for Manila Share + +Similar to the Cinder example above certified Manila Share images +may be customized by updating the 'manilaShareImages' map +within the 'customContainerImages' section of the OpenStackVersion +CR and then set to a custom container image for the named backend. + +```yaml +apiVersion: core.openstack.org/v1beta1 +kind: OpenStackVersion +metadata: + labels: + name: openstack +spec: + targetVersion: 1.0.1 + customContainerImages: + manilaShareImages: + default: quay.io/podified-antelope-centos9/openstack-manila-share@sha256:55c6acf35d6a4e26228a49d5dcc86a8e0ca54d32b55e3465535b2aa0111f76e2 + custom: +``` + +## Custom Images for Neutron ML2 + +TBD. There is currently no formal interface to deploy custom ml2 drivers +for neutron other than OVN. If such an interface evolves we can +add a mechanism to customize any container images associated with +that interface to OpenStackVersion. + +## Custom images for other OpenStack services + +In general administrators should not need to customize containerImages +for any other OpenStack services images. The exception would be +the need to apply a hotfix. In order to accommodate a hotfixed or +patched containerImage you can update the 'customContainerImages' +struct on the OpenStackVersion with the customized image. +For example if you need to hotfix the Glance API service container image +you would add the following update to the glanceAPIImage field within +the customContainerImages section: + +```yaml +apiVersion: core.openstack.org/v1beta1 +kind: OpenStackVersion +metadata: + labels: + name: openstack +spec: + targetVersion: 1.0.1 + customContainerImages: + glanceAPIImage: +``` + +## ordering of service updates: normal vs minor updates + +Container image updates currently occur in parallel when updating +custom images of the OpenStackVersion resource. On the ControlPlane +this means that any image customizations on the OpenStackVersion +resource will be applied immediately. And on the Dataplane +those updates will be applied during the next 'deployment'. + +The exception to this is if targetVersion is changed thus causing a minor update +sequence to occur. If a minor update is triggered a special sequence is +followed until all ControlPlane and Dataplane components have their deployedVersion +set to the new targetVersion value. The minor update sequence is as follows: + +1. OVN controller updates. The OVN controllers on both the ControlPlane and DataplaneNodesets + are updated. These services can be updated in parallel however the ControlPlane components + will begin automatically immediately after the targetVersion is edited. DataplaneNodeset + updates currently are required to be executed manually. +2. All the remaining services on ControlPlane are updated to the new service image containers. +3. The rest of the Dataplane service containers are updated. DataplaneNodesets updates + are currently required to be executed manually. + +TODO: If a situation arises where we need to update one service before +another we can use OpenStackVersion to implement this in the future which +may require the addition of more conditional steps to orchestrate +the update at a high level. + +## Things currently not supported + + * Rolling back to a prior openstack version directly via OpenStackVersion. + A rollback would require the administrator to install an old CSV, + and patch various CRs to update the containerImages among other things. + While a rollback may be allowed for development testing in production + rollbacks are not recommended/supported. + * Major upgrades are not targeted at this time. However the OpenStackVersion + CR may be useful as a means to help drive those as well.