edit pass: azure-operator-service-manager-best-practices

Author: ShawnJackson

articles/operator-service-manager/best-practices-onboard-deploy.md

@@ -44,11 +44,11 @@ We recommend that you first onboard and deploy your simplest NFs (one or two cha
 
 The network function definition group (NFDG) represents the smallest component that you plan to reuse independently across multiple services. All parts of an NFDG are always deployed together. These parts are called `networkFunctionApplications` items.
 
-For example, it's natural to onboard a single NF composed of multiple Helm charts and images as a single NFDG if you always deploy those components together. In cases where multiple NFs are always deployed together, it's reasonable to have a single NFDG for all of them. Single NFDGs can have multiple NFDVs.
+For example, it's natural to onboard a single NF that consists of multiple Helm charts and images as a single NFDG if you always deploy those components together. In cases where multiple NFs are always deployed together, it's reasonable to have a single NFDG for all of them. Single NFDGs can have multiple NFDVs.
 
 For CNF NFDVs, the `networkFunctionApplications` list can contain only Helm packages. It's reasonable to include multiple Helm packages if they're always deployed and deleted together.
 
-For VNF NFDVs, the `networkFunctionApplications` list must contain at least one `VhdImageFile` value and one ARM template. The ARM template should deploy a single virtual machine (VM). To deploy multiple VMs for a single VNF, make sure to use separate ARM templates for each VM.
+For VNF NFDVs, the `networkFunctionApplications` list must contain at least one `VhdImageFile` value and one ARM template. The ARM template should deploy a single virtual machine (VM). To deploy multiple VMs for a single VNF, make sure to use a separate ARM template for each VM.
 
 The ARM template can deploy only Resource Manager resources from the following resource providers:
 
@@ -65,7 +65,7 @@ For ARM templates that contain anything beyond the preceding list, all `PUT` cal
 ### Common use cases that trigger an NFDV minor or major version update
 
 - Updating CGSs or configuration group values (CGVs) for an existing release that triggers a change to `deployParametersMappingRuleProfile`
-- Updating values that are hardcoded in the NFDV
+- Updating values that are hard-coded in the NFDV
 - Marking components as inactive to prevent them from being deployed via `applicationEnablement: Disabled`
 - A new NF release, such as charts and images
 
@@ -76,7 +76,7 @@ For ARM templates that contain anything beyond the preceding list, all `PUT` cal
 
 A network service design group (NSDG) is a composite of one or more NFDGs and any infrastructure components deployed at the same time. These components might include clusters and VMs in Nexus Kubernetes or Azure Kubernetes Service (AKS). A site network service (SNS) refers to a single NSDV. Such a design provides a consistent and repeatable deployment of the network service to a site from a single SNS `PUT` call.
 
-An example of an NSDG consists of:
+An example NSDG might consist of:
 
 - Authentication Server Function (AUSF) NF
 - Unified data management (UDM) NF
@@ -169,7 +169,7 @@ Azure Operator Service Manager is a regional service deployed across availabilit
 Consider the following requirements for high availability and disaster recovery:
 
 - To provide geo-redundancy, make sure you have a publisher in every region where you're planning to deploy NFs. Consider using pipelines to keep publisher artifacts and resources in sync across the regions.
-- The publisher name must be unique per region per Microsoft Entra tenant.
+- The publisher name must be unique for each Microsoft Entra tenant in each region.
 - If a region becomes unavailable, you can deploy (but not upgrade) an NF by using publisher resources in another region. Assuming that artifacts and resources are identical between the publishers, you need to change only the `networkServiceDesignVersionOfferingLocation` value in the SNS resource payload:
 
   <pre>
@@ -194,7 +194,7 @@ During installation and upgrade, by default:
 - The `atomic` and `wait` options are set to `true`.
 - The operation timeout is set to `27 minutes`.
 
-During initial onboarding, only while you're still debugging and developing artifacts, we recommend that you set the `atomic` flag to `false.` This setting prevents a Helm rollback upon failure and retains any logs or errors that might otherwise be lost. The optimal way to accomplish that is in the ARM template of the NF.
+During initial onboarding, only while you're still debugging and developing artifacts, we recommend that you set the `atomic` flag to `false`. This setting prevents a Helm rollback upon failure and retains any logs or errors that might otherwise be lost. The optimal way to accomplish it is in the ARM template of the NF.
 
 In the ARM template, add the following section:
 
@@ -221,7 +221,7 @@ The component name is defined in the NFDV:
 </pre>
 
 > [!IMPORTANT]
-> Make sure `atomic` and `wait` are set back to `true` after initial onboarding is complete.
+> Be sure to set `atomic` and `wait` back to `true` after initial onboarding is complete.
 
 ## Cleanup considerations
 
@@ -250,7 +250,7 @@ As the first step toward cleaning up an onboarded environment, delete publisher
 1. Publisher
 
 > [!IMPORTANT]
-> Make sure that the SNS is deleted before you delete the NFDV.
+> Be sure to delete the SNS before you delete the NFDV.
 
 Azure Operator Service Manager does not delete namespaces as part of any deletion operation. As such, after all resources are deleted, some artifacts might remain on the cluster. To remove any remaining artifacts, you should delete any workload namespaces created on the cluster. Including the namespace deletion operation as part of the workflow pipeline is a recommendation to automate the action.
 

articles/operator-service-manager/configuration-guide.md

@@ -18,8 +18,8 @@ JSON Schema is an Internet Engineering Task Force (IETF) standard that provide
 
 ### Where is JSON Schema used?
 
-* Azure Operator Service Manager uses JSON Schema notation as a meta-schema within CGS `ConfigurationGroupSchemaPropertiesFormat` object `schemaDefinition` properties.
-* Azure Operator Service Manager allows the designer and publisher to specify the JSON Schema when the operator must provide data (JSON values) during instantiation of a site network service (SNS) or NF.
+* Azure Operator Service Manager uses JSON Schema notation as a meta-schema within `schemaDefinition` properties for the CGS `ConfigurationGroupSchemaPropertiesFormat` object.
+* Azure Operator Service Manager allows the designer and publisher to specify JSON Schema when the operator must provide data (JSON values) during instantiation of a site network service (SNS) or NF.
 * Azure Operator Service Manager allows the meta-schema properties to be optional or required. Where a property is marked `required`, it must be specified in the JSON values.  
 
 ### What JSON keywords are supported?

articles/operator-service-manager/helm-requirements.md

@@ -78,15 +78,15 @@ spec:
         - containerPort: 80 
 ```
 
-The following `values.yaml` template shows an example of how you can provide the `registryPath` and `imagePullSecrets`values:
+The following `values.yaml` template shows an example of how you can provide the `registryPath` and `imagePullSecrets` values:
 
 ```json
 global: 
    imagePullSecrets: [] 
    registryPath: "" 
 ```
 
-The following `values.schema.json` file shows an example of how you can define the `registryPath` and `imagePullSecrets`values:
+The following `values.schema.json` file shows an example of how you can define the `registryPath` and `imagePullSecrets` values:
 
 ```json
 { 
@@ -126,7 +126,7 @@ Consider the following recommendations when you're using the legacy method.
 
 #### Avoid references to an external registry
 
-References to an external registry can cause validation problems. For example, if `deployment.yaml` uses a hardcoded registry path or external registry references, it fails validation.
+References to an external registry can cause validation problems. For example, if `deployment.yaml` uses a hard-coded registry path or external registry references, it fails validation.
 
 #### Perform manual validations
 
@@ -145,7 +145,7 @@ Here's another example:
 
 #### Use a static image repository and tags
 
-Each Helm chart should contain static image repository and tags. You set the static values through one of the following methods:
+Each Helm chart should contain a static image repository and tags. You set the static values through one of the following methods:
 
 * In the `image` line
 * In `values.yaml`, without exposing these values in the NFDV
@@ -188,7 +188,7 @@ global:
 
 ### Using the injectArtifactStoreDetails method
 
-To enable `injectArtifactStoreDetails`, set the `installOptions` parameter in the NF resource `roleOverrides` section to `true`, as shown in the following example:
+To enable `injectArtifactStoreDetails`, set the `installOptions` parameter in the NF resource's `roleOverrides` section to `true`, as shown in the following example:
 
 ```bash
 resource networkFunction 'Microsoft.HybridNetwork/networkFunctions@2023-09-01' = {
@@ -217,7 +217,7 @@ resource networkFunction 'Microsoft.HybridNetwork/networkFunctions@2023-09-01' =
 
 ## Cluster registry requirements for registryPath and imagePullSecrets
 
-With cluster registry, images are copied from Azure Container Registry to a local Docker repository on the Nexus Kubernetes cluster. You use a webhook method to inject the proper `registryPath` and `imagePullSecrets` values dynamically during the pod operations. This method overrides the values that are configured in the Helm package. You still must use legal dummy values where `registryPath` and `imagePullSecrets` are referenced, usually in the `global` section of `values.yaml`.
+With a cluster registry, images are copied from Azure Container Registry to a local Docker repository on the Nexus Kubernetes cluster. You use a webhook method to inject the proper `registryPath` and `imagePullSecrets` values dynamically during the pod operations. This method overrides the values that are configured in the Helm package. You still must use legal dummy values where `registryPath` and `imagePullSecrets` are referenced, usually in the `global` section of `values.yaml`.
 
 The following `values.yaml` example shows how you can provide the `registryPath` and `imagePullSecrets` values for compatibility with the cluster registry approach:
 
@@ -230,7 +230,7 @@ global:
 > [!NOTE]
 > If `registryPath` is left blank in the underlying Helm package, SNS deployment fails during image download.
 
-For more information on using cluster registry, see the [concept documentation](get-started-with-cluster-registry.md).
+For more information on using a cluster registry, see the [concept documentation](get-started-with-cluster-registry.md).
 
 ## Chart immutability restrictions
 

articles/operator-service-manager/publisher-resource-preview-management.md

@@ -11,9 +11,9 @@ ms.custom:
 
 # Publisher Resource Preview Management feature
 
-This article introduces the Publisher Resource Preview Management feature in Azure Network Function Manager. The Azure Network Function Manager Publisher API offers partners a seamless Azure Marketplace experience for onboarding network functions and network service designs.
+This article introduces the Publisher Resource Preview Management feature in Azure Network Function Manager.
 
-The Publisher API introduces features that enable Network Function (NF) Publishers and Service Designers to manage network function definitions (NFDs) and network service designs (NSDs) in various modes. These modes empower partners to exercise control over the usage of NFDs and NSDs. This control allows partners to target specific subscriptions, target all subscriptions, or deprecate a network function definition version (NFDV) or a network service design version (NSDV) if there are regressions. This article delves into the specifics of these modes.
+The Azure Network Function Manager Publisher API offers partners a seamless Azure Marketplace experience for onboarding network functions (NFs) and network service designs (NSDs). The Publisher API introduces features that enable NF publishers and service designers to manage network function definitions (NFDs) and NSDs in various modes. These modes empower partners to exercise control over the usage of NFDs and NSDs. This control allows partners to target specific subscriptions, target all subscriptions, or deprecate a network function definition version (NFDV) or a network service design version (NSDV) if there are regressions. This article delves into the specifics of these modes.
 
 The Publisher Resource Preview Management feature in Azure Network Function Manager empowers partners to seamlessly manage network function definitions and their versions. With the ability to control deployment states, access privileges, and version management, partners can provide a smooth experience for their customers while maintaining the quality and stability of their offerings.
 
@@ -53,7 +53,7 @@ The Publisher Resource Preview Management feature in Azure Network Function Mana
 - **Uploading** means the state is mutable and the artifacts within the manifest can be altered.
 - **Uploaded** means the state is immutable and the artifacts within the manifest can't be altered.
 
-Immutable artifacts are tested artifacts that can't be modified or overwritten. Use of immutable artifacts with Azure Operator Service Manager helps ensure the consistency, reliability, and security of its artifacts across environments and platforms. NFDVs and NSDVs with a version state of **Active** are enforced to deploy immutable artifacts.  
+Immutable artifacts are tested artifacts that can't be modified or overwritten. Use of immutable artifacts with Azure Operator Service Manager helps ensure the consistency, reliability, and security of its artifacts across environments and platforms. NFDVs and NSDVs that have a version state of **Active** are enforced to deploy immutable artifacts.  
 
 ### Update the artifact manifest state