Update safe-upgrade-practices.md

Author: msftadam

articles/operator-service-manager/safe-upgrade-practices.md

@@ -3,15 +3,15 @@ title: Get started with Azure Operator Service Manager Safe Upgrade Practices
 description: Safely execute complex upgrades of CNF workloads on Azure Operator Nexus
 author: msftadam
 ms.author: adamdor
-ms.date: 08/30/2024
+ms.date: 02/19/2024
 ms.topic: upgrade-and-migration-article
 ms.service: azure-operator-service-manager
 ---
 
 # Get started with safe upgrade practices
 This article introduces Azure Operator Service Manager (AOSM) safe upgrade practices (SUP). This feature set enables an end user to safely execute complex upgrades of Container Network Function (CNF) workloads hosted on Azure Operator Nexus, in compliance with partner In Service Software Upgrade (ISSU) requirements, where applicable. Look for future articles in these services to expand on SUP features and capabilities.
 
-## Introduction
+## Introduction to safe upgrades
 A given network service supported by Azure Operator Service Manager will be composed of one to many container based network functions (CNFs) which, over time, will require  software updates. For each  update, it is necessary to run one to many helm operations, upgrading dependent network function applications (NfApps), in a particular order, in a manner which least impacts the network service. At Azure Operator Service Manager, Safe Upgrade Practices represents a set of features, which can automate the CNF operations required to update a network service on Azure Operator Nexus.
 
 * SNS Reput update - Execute helm upgrade operation across all NfApps in NFDV.
@@ -26,7 +26,7 @@ A given network service supported by Azure Operator Service Manager will be comp
 * Execute NF-level Rollback On Failure - Based on flag, rollback all completed NfApps on failure.
 * Image Preloading - Ability to preload images to edge repository.
 
-## Upgrade approach
+## Safe upgrade approach
 To update an existing Azure Operator Service Manager site network service (SNS), the Operator executes a reput update request against the deployed SNS resource. Where the SNS contains CNFs with multiple NfApps, the request is fanned out across all NfApps defined in the network function definition version (NFDV). By default, in the order, which they appear, or optionally in the order defined by UpdateDependsOn parameter.
 
 For each NfApp, the reput update request supports increasing a helm chart version, adding/removing helm values and/or adding/removing any NfApps. Time-outs can be set per NfApp, based on known allowable runtimes, but NfApps can only be processed in serial order, one after the other. The reput update implements the following processing logic:
@@ -41,12 +41,13 @@ For each NfApp, the reput update request supports increasing a helm chart versio
 To ensure outcomes, NfApp testing is supported using helm, either helm upgrade pre/post tests, or standalone helm tests. For pre/post tests failures, the atomic parameter is honored. With atomic/true, the failed chart is rolled back. With atomic/false, no rollback is executed. For standalone helm tests, the rollbackOnTestFailure parameter us honored. With rollbackOnTestFailure/true, the failed chart is rolled back. With rollbackOnTestFailure/false, no rollback is executed.
 
 ## Considerations for in-service upgrades
-Azure Operator Service Manager generally supports in service upgrades, an upgrade method which advances a deployment version without interrupting the running service. Some considerations are neccesary to ensure the proper behavior of AOSM during ISSU operations. 
-* Where AOSM is performaning an upgrade against an ordered set of multiple nfApps, AOSM will first upgrade or create all new nfApps, then delete all old nfApps. This ensures service is not impacted until all new nfApps are ready but requires extra platform capacity for transiet hosting of both old and new nfApps. 
-* Where AOSM is upgrading an NfApp with multiple replica, AOSM will honor the deployment profile settings for rolling or recreate option. Where rolling is used, it's recommended to expose the values `maxUnavailable` and `maxSurge` as parameters, which can then be set via operator CGV at run-time.
+Azure Operator Service Manager generally supports in service upgrades, an upgrade method which advances a deployment version without interrupting the running service. Some considerations are necessary to ensure the proper behavior of AOSM during ISSU operations. 
+* Where AOSM performs an upgrade against an ordered set of multiple nfApps, AOSM first upgrades or creates all new nfApps, then deletes all old nfApps. This approach ensures service is not impacted until all new nfApps are ready but requires extra platform capacity for transient hosting of both old and new nfApps. 
+* Where AOSM upgrades an NfApp with multiple replica, AOSM honors the deployment profile settings for rolling or recreate option. Where rolling is used, expose the values `maxUnavailable` and `maxSurge` as CGS parameters, which can then be set via operator CGV at run-time.
+
 Ultimately, the ability for a given service to be upgraded without interruption is a feature of the service itself. Consult further with the service publisher to understand the in-service upgrade capabilities and ensure they are aligned with the proper AOSM behavioral options.
 
-## Upgrade prerequisites
+## Safe upgrade prerequisites
 When planning for an upgrade using Azure Operator Service Manager, address the following requirements in advance of upgrade execution to optimize the time spent attempting the upgrade.
 
 - Onboard updated artifacts using publisher and/or designer workflows.
@@ -65,7 +66,7 @@ When planning for an upgrade using Azure Operator Service Manager, address the f
 - Update templates to ensure that upgrade parameters are set based on confidence in the upgrade and desired failure behavior.
   - Settings used for production may suppress failures details, while settings used for debugging, or testing, may choose to expose these details.
 
-## Upgrade procedure
+## Safe upgrade procedure
 Follow the following process to trigger an upgrade with Azure Operator Service Manager.
 
 ### Create new NFDV resource
@@ -86,7 +87,7 @@ With onboarding complete, the reput operation is submitted. Depending on the num
 ### Examine reput results
 If the reput is reporting a successful result, the upgrade is complete and the user should validate the state and availability of the service. If the reput is reporting a failure, follow the steps in the upgrade failure recovery section to continue.
 
-## Retry procedure
+## Safe upgrade retry procedure
 In cases where a reput update fails, the following process can be followed to retry the operation.
 
 ### Diagnose failed NfApp
@@ -98,7 +99,7 @@ After fixing the failed NfApp, but before attempting an upgrade retry, consider
 ### Issue SNS reput retry (repeat until success)
 By default, the reput retries NfApps in the declared update order, unless they are skipped using applicationEnablement flag.
 
-## How skip nfApps using applicationEnablement
+## Skip nfApps using applicationEnablement
 In the NFDV resource, under deployParametersMappingRuleProfile there is the property applicationEnablement of type enum, which takes values: Unknown, Enabled, or disabled. It can be used to exclude NfApp operations during network function (NF) deployment.
 
 ### Publisher changes
@@ -164,7 +165,7 @@ The NFDV is used by publisher to set default values for applicationEnablement.
 ```
 
 #### Sample configuration group schema (CGS) resource
-The CGS is used by the publisher to require a roleOverrideValues variable to be provided by Operator at run-time. RoleOverrideValues can include non-default settings for applicationEnablement.
+The CGS is used by the publisher to require a roleOverrideValues variable to be provided by Operator at run-time. RoleOverrideValues can include nondefault settings for applicationEnablement.
 
 ```json
 {
@@ -224,7 +225,7 @@ The CGS is used by the publisher to require a roleOverrideValues variable to be
 Operators inherit default applicationEnablement values as defined by the NFDV. If applicationEnablement is parameterized in CGS, then it must be passed through the deploymentValues property at runtime. 
 
 #### Sample configuration group value (CGV) resource
-The CGV is used by the operator to set the roleOverrideValues variable at run-time. RoleOverrideValues include non-default settings for applicationEnablement.
+The CGV is used by the operator to set the roleOverrideValues variable at run-time. RoleOverrideValues include nondefault settings for applicationEnablement.
 
 ```json
 {
@@ -243,7 +244,7 @@ The CGV is used by the operator to set the roleOverrideValues variable at run-ti
 ```
 
 #### Sample NF ARM template
-The NF ARM template is used by operator to submit the roleOverrideValues variable(s), set by CGV, to the resource provider (RP). The operator can change the applicationEnablement setting in CGV, as needed, and resubmit the same NF ARM template, to alter behavior between iterations.
+The NF ARM template is used by operator to submit the roleOverrideValues variable, set by CGV, to the resource provider (RP). The operator can change the applicationEnablement setting in CGV, as needed, and resubmit the same NF ARM template, to alter behavior between iterations.
 
 ```json
 {
@@ -305,10 +306,10 @@ The NF ARM template is used by operator to submit the roleOverrideValues variabl
 }
 ```
 
-## How to skip NfApps which have no change
+## Skip NfApps which have no change
 The SkipUpgrade feature is designed to optimize the time taken for CNF upgrades. When the publisher enables this flag in the `RoleOverrideValues` under `UpgradeOptions`, the AOSM service layer performs certain prechecks, to determine whether an upgrade for a specific `NFApplication` can be skipped. If all precheck criteria are met, the upgrade is skipped for that application. Otherwise, an upgrade is executed at the cluster level.
 
-### PreCheck Criteria
+### Precheck Criteria
 An upgrade can be skipped if all the following conditions are met:
 1. The `NFApplication` provisioning state is Succeeded.
 2. There is no change in the Helm chart name or version.
@@ -341,7 +342,7 @@ To enable the SkipUpgrade feature via `RoleOverrideValues`, refer to the followi
 ```
 #### Explanation of the Example
 - **NfApplication: `hellotest`**
-  - The `skipUpgrade` flag is enabled. If the upgrade request for `hellotest` meets the precheck criteria, the upgrade will be skipped at the service level.
+  - The `skipUpgrade` flag is enabled. If the upgrade request for `hellotest` meets the precheck criteria, the upgrade is skipped.
 - **NfApplication: `runnerTest`**
   - The `skipUpgrade` flag is not specified. Therefore, `runnerTest` executes a traditional Helm upgrade at the cluster level, even if the precheck criteria are met.