From 5895d8df71e35303ffcec9a8455baf6e09a56cde Mon Sep 17 00:00:00 2001 From: Billy Tat Date: Mon, 27 May 2019 16:06:51 -0700 Subject: [PATCH] Add Stratos upgrade section. Warn about not resetting values during upgrades (#443) Reorganize upgrade chapter --- xml/cap_admin_upgrade.xml | 135 ++++++++++++++++++++++++---------- xml/cap_depl_stratos.xml | 10 +++ xml/repeated-content-decl.ent | 23 ------ 3 files changed, 108 insertions(+), 60 deletions(-) diff --git a/xml/cap_admin_upgrade.xml b/xml/cap_admin_upgrade.xml index 01d2a199..36afc17f 100644 --- a/xml/cap_admin_upgrade.xml +++ b/xml/cap_admin_upgrade.xml @@ -15,35 +15,101 @@ yes - - Upgrading &productname; - - - uaa, scf, and Stratos together make up - a &productname; release. Maintenance updates are delivered as container - images from the &suse; registry and applied with &helm;. - - - + + uaa, scf, and Stratos together make up + a &productname; release. Maintenance updates are delivered as container + images from the &suse; registry and applied with &helm;. + + For additional upgrade information, always review the release notes published at . + + + Important Considerations + + + Before performing an upgrade, be sure to take note of the following: - - <command>helm rollback</command> is not supported - - helm rollback is not supported in &productname; or in - upstream &cf;, and may break your cluster completely, because database - migrations only run forward and cannot be reversed. Database schema can - change over time. During upgrades both pods of the current and the next - release may run concurrently, so the schema must stay compatible with the - immediately previous release. But there is no way to guarantee such - compatibility for future upgrades. One way to address this is to perform a - full raw data backup and restore. (See - ) - - + + + Perform Upgrades in Sequence + + + ∩ only supports upgrading releases in sequential order. If there are + any intermediate releases between your current release and your target + release, they must be installed. Skipping + releases is not supported. See + for more information. + + + + + Preserve &helm; Value Changes during Upgrades + + + During a helm upgrade, always ensure the + --reuse-values flag is specified and your + scf-config-values-yaml file is passed. This will + preserve any previously set &helm; values while allowing additional + &helm; value changes to be made. + + + + + Use --recreate-pods during a helm upgrade + + + Note that using --recreate-pods will cause downtime for + applications, but is required as multiple versions of statefulsets may + co-exist which can cause incompatibilities between dependent statefulsets, + and result in a broken upgrade. + + + When upgrading from &productname; 1.3.0 to 1.3.1, running + helm upgrade does not require the + --recreate-pods option to be used. A change to the + active/passive model has allowed for previously unready pods to be + upgraded, which allows for zero app downtime during the upgrade process. + + + Upgrades between other versions will require the + --recreate-pods option when using the + helm upgrade command. + + + + + helm rollback Is Not Supported + + + helm rollback is not supported in &productname; or in + upstream &cf;, and may break your cluster completely, because database + migrations only run forward and cannot be reversed. Database schema can + change over time. During upgrades both pods of the current and the next + release may run concurrently, so the schema must stay compatible with the + immediately previous release. But there is no way to guarantee such + compatibility for future upgrades. One way to address this is to perform a + full raw data backup and restore. (See + ) + + + + + Do Not Make Changes to Pod Counts During a Upgrade + + + If sizing changes need to be mader, make the change either before or after + an upgrade. See . + + + + + + + + Upgrading &productname; The supported upgrade method is to install all upgrades, in order. Skipping @@ -53,11 +119,6 @@ &releases-table; - - Do not make changes to pod counts when you upgrade. You may make sizing - changes before or after an upgrade (see ). - - Use &helm; to check for updates: @@ -102,15 +163,12 @@ suse/uaa 2.7.0 A Helm chart for SUSE UAA - When you have verified that the upgrade is the next release from your - current release, run the following commands to perform the upgrade. What if - you missed a release? See . + Verify the latest release is the next sequential release from your + currently-installed release. If it is, proceed with the commands below to + perform the upgrade. If any releases have been missed, see + . - - &recreate-pods; - - Just like your initial installation, wait for each command to complete before running the next command. Monitor progress with the @@ -120,9 +178,11 @@ suse/uaa 2.7.0 A Helm chart for SUSE UAA &prompt.user;helm upgrade --force --recreate-pods susecf-uaa suse/uaa \ +--reuse-values \ --values scf-config-values.yaml + Then extract the uaa secret for scf to use: @@ -142,6 +202,7 @@ suse/uaa 2.7.0 A Helm chart for SUSE UAA &prompt.user;helm upgrade --force --recreate-pods susecf-scf suse/cf \ +--reuse-values \ --values scf-config-values.yaml \ --set "secrets.UAA_CA_CERT=${CA_CERT}" @@ -151,9 +212,9 @@ suse/uaa 2.7.0 A Helm chart for SUSE UAA &prompt.user;helm upgrade --force --recreate-pods susecf-console suse/console \ +--reuse-values \ --values scf-config-values.yaml - diff --git a/xml/cap_depl_stratos.xml b/xml/cap_depl_stratos.xml index da228c49..951b8eb3 100644 --- a/xml/cap_depl_stratos.xml +++ b/xml/cap_depl_stratos.xml @@ -606,6 +606,16 @@ gp2scoped kubernetes.io/aws-ebs 1d + + Upgrading Stratos + + + For instructions to upgrade Stratos, follow the process described in + . Take note that uaa and + scf, other components along with Stratos that make up a + ∩ release, are upgraded prior to upgrading Stratos. + + Stratos Metrics diff --git a/xml/repeated-content-decl.ent b/xml/repeated-content-decl.ent index 1f71dc0b..2a362e77 100644 --- a/xml/repeated-content-decl.ent +++ b/xml/repeated-content-decl.ent @@ -232,29 +232,6 @@ Before you start deploying &productname;, review the following documents: '> - - - - - - Using --recreate-pods during a helm upgrade - - - Note that --recreate-pods will cause downtime for - applications, but is required as multiple versions of statefulsets may - co-exist which can cause incompatibilities between dependent statefulsets, - and result in a broken upgrade. - - - When upgrading from &productname; 1.3.0 to 1.3.1, running helm upgrade does not require the --recreate-pods option to be used. A change to the active/passive model has allowed for previously unready pods to be upgraded, which allows for zero app downtime during the upgrade process. - - - Upgrades between other versions will require the --recreate-pods option when using the helm upgrade command. - - - -'>