Merge pull request #229354 from pgoyal01/release-preview-operator-nexus

Active voice changes

Author: v-regandowner

articles/operator-nexus/quickstarts-tenant-workload-deployment.md

@@ -13,16 +13,12 @@ ms.custom: template-quickstart #Required; leave this attribute/value as-is.
 
 This how-to guide explains the steps for deploying VNF and CNF workloads. Section V (for VM-based deployments) deals with creating VMs and to deploy VNF workloads. Section K (for Kubernetes; based deployments) specifies steps for creating AKS-Hybrid clusters for deploying  CNF workloads.
 
-These examples don't specify all required parameters and, thus, shouldn't be used verbatim.
+You shouldn't use the examples verbatim as they don't specify all required parameters.
 
 ## Before you begin
 
 You should complete the prerequisites specified [here](./quickstarts-tenant-workload-prerequisites.md).
 
-**Capacity Note:**
-
-Say, each server has two CPU chipsets and each CPU chip has 28 cores. Then with hyperthreading enabled (default), the CPU chip supports 56 vCPUs. 10 vCPUs are reserved for infrastructure (OS, agents, emulator thread, etc.) with the remaining 46 vCPUs available for your workloads (maximum VM size).
-
 ## Section V: how to create VMs for deploying VNF workloads
 
 Step-V1: [Create isolation-domains for VMs](#step-v1-create-isolation-domain-for-vm-workloads)
@@ -71,9 +67,9 @@ This section describes how to create the following networks for VM Workloads:
 
 #### Create an L2 network
 
-You'll need to create an L2 network if necessary for your VM. You can repeat the instructions for each L2 network required.
+Create an L2 network, if necessary, for your VM. You can repeat the instructions for each L2 network required.
 
-You'll need the resource ID of the L2 isolation-domain you [created](#l2-isolation-domain) that configures the VLAN for this network.
+Gather the resource ID of the L2 isolation-domain you [created](#l2-isolation-domain) that configures the VLAN for this network.
 
 Example CLI command:
 
@@ -88,16 +84,18 @@ Example CLI command:
 
 #### Create an L3 network
 
-You'll need to create an L3 network if necessary for your VM. You can repeat the instructions for each L3 network required.
+Create an L3 network, if necessary, for your VM. Repeat the instructions for each L3 network required.
 
-You'll need:
+You need:
 
 - resource ID of the L3 isolation-domain you [created](#l3-isolation-domain) that configures the VLAN for this network.
 - The ipv4-connected-prefix must match the i-pv4-connected-prefix that is in the L3 isolation-domain
 - The ipv6-connected-prefix must match the i-pv6-connected-prefix that is in the L3 isolation-domain
 - The ip-allocation-type can be either "IPv4", "IPv6", or "DualStack" (default)
 - The VLAN value must match what is in the L3 isolation-domain
-- The MTU of the network doesn't need to be specified here, but the network will be configured with the same MTU information
+
+<!--- The MTU wasn't specified during l2 isolation domain creation so what is "same" 
+- The MTU of the network doesn't need to be specified here, but the network will be configured with the MTU information --->
 
 ```azurecli
   az networkcloud l3network create --name "<YourL3NetworkName>" \
@@ -114,9 +112,9 @@ You'll need:
 
 #### Create a trunked network
 
-You'll need to create a trunked network if necessary for your VM. You can repeat the instructions for each Trunked network required.
+Create a trunked network, if necessary, for your VM. Repeat the instructions for each trunked network required.
 
-You'll need to gather the resourceId(s) of the L2 and L3 isolation-domains you created earlier to configure the VLAN(s) for this network.
+Gather the resourceId(s) of the L2 and L3 isolation-domains you created earlier to configure the VLAN(s) for this network.
 You can include as many L2 and L3 isolation-domains as needed.
 
 ```azurecli
@@ -137,7 +135,7 @@ You can include as many L2 and L3 isolation-domains as needed.
 
 ### Create cloud services network
 
-Your VM will require one Cloud Services Network. You'll need the egress endpoints you want to add to the proxy for your VM to access.
+Your VM requires at least one Cloud Services Network. You need the egress endpoints you want to add to the proxy for your VM to access.
 
 ```azurecli
   az networkcloud cloudservicesnetwork create --name "<YourCloudServicesNetworkName>" \
@@ -150,9 +148,9 @@ Your VM will require one Cloud Services Network. You'll need the egress endpoint
 
 ### Step V3: create a VM
 
-Operator Nexus Virtual Machines (VM) can be used for hosting VNF(s) within a Telco network.
-Operator Nexus provides `az networkcloud virtualmachine create` to enable users to create a customized
-VM. For creating a virtual machine on your cluster, have it [Microsoft Azure Arc-enrolled](//azure/azure-arc/servers/overview),
+Operator Nexus Virtual Machines (VM) are used for hosting VNF(s) within a Telco network.
+The Nexus platform provides `az networkcloud virtualmachine create` to create a customized VM.
+For hosting a VNF on your VM, have it [Microsoft Azure Arc-enrolled](//azure/azure-arc/servers/overview),
 and provide a way to ssh to it via Azure CLI.
 
 #### Parameters
@@ -167,7 +165,7 @@ and provide a way to ssh to it via Azure CLI.
   - **SERVICE_PRINCIPAL_SECRET**=
 - A tenant ID
   - **TENANT_ID**=
-- If the VM image is hosted in a managed ACR, a generated token for access
+- For a VM image hosted in a managed ACR, a generated token for access
   - **ACR_URL**=
   - **ACR_USERNAME**=
   - **ACR_TOKEN**=
@@ -233,13 +231,16 @@ az deployment group create --resource-group _RESOURCE_GROUP_ --subscription=_SUB
 
 #### 3. SSH to the VM
 
-It will take a few minutes for the VM to be created and then Arc connected, so should it fail at first, try again after a short wait.
+It takes a few minutes for the VM to be created and then Arc connected. Should your attempt fail at first, try again after a short wait.
 
 ```azurecli
 az ssh vm -n _VMNAME_ -g _RESOURCE_GROUP_ --subscription _SUBSCRIPTION_ --private-key _SSH_PRIVATE_KEY_ --local-user _ADMINUSER_
 ```
 
-Here's some information you'll need.
+**Capacity Note:**
+If each server has two CPU chipsets and each CPU chip has 28 cores. Then with hyper-threading enabled (default), the CPU chip supports 56 vCPUs. With 8 vCPUs in each chip reserved for infrastructure (OS, agents), the remaining 48 are available for tenant workloads.
+
+Gather this information:
 
 - The `resourceId` of the `cloudservicesnetwork`
 - The `resourceId(s)` for each of the L2/L3/Trunked networks
@@ -311,7 +312,8 @@ You should have the following information already:
 - BGP peering and network policies information for your L3 isolation-domain(s)
 - VLANs for all your layer 2 network(s)
 - VLANs for all your trunked network(s)
-- MTU needs to be passed during creation of isolation-domain, due to a known issue. The issue will be fixed with the 11/15 release.
+<!--- The MTU isn't being specified and "11/15"?
+- MTU needs to be passed during creation of isolation-domain, due to a known issue. The issue will be fixed with the 11/15 release. --->
 
 #### L2 isolation domain
 
@@ -339,7 +341,7 @@ At a minimum, you need to create a "Default CNI network" and a "Cloud Services n
 
 ##### Create an L2 network for AKS-Hybrid cluster
 
-You'll need the resourceId of the [L2 isolation-domain](#l2-isolation-domain-1) you created earlier that configures the VLAN for this network.
+You need the resourceId of the [L2 isolation-domain](#l2-isolation-domain-1) you created earlier that configures the VLAN for this network.
 
 For your network, the valid values for
 `hybrid-aks-plugin-type` are `OSDevice`, `SR-IOV`, `DPDK`; the default value is `SR-IOV`.
@@ -356,16 +358,17 @@ For your network, the valid values for
 
 ##### Create an L3 network for AKS-Hybrid cluster
 
-You'll need the following information:
+You need the following information:
 
 - The `resourceId` of the [L3 isolation-domain](#l3-isolation-domain) domain you created earlier that configures the VLAN for this network.
 - The `ipv4-connected-prefix` must match the i-pv4-connected-prefix that is in the L3 isolation-domain
 - The `ipv6-connected-prefix` must match the i-pv6-connected-prefix that is in the L3 isolation-domain
 - The `ip-allocation-type` can be either "IPv4", "IPv6", or "DualStack" (default)
 - The VLAN value must match what is in the L3 isolation-domain
-- The MTU of the network doesn't need to be specified here as the network will be configured with the MTU specified during isolation-domain creation
+<!--- The MTU wasn't specified during l2 isolation domain creation so what is "same" 
+- The MTU of the network doesn't need to be specified here as the network will be configured with the MTU specified during isolation-domain creation --->
 
-You'll also need to configure the following information for your aks-hybrid cluster
+You also need to configure the following information for your aks-hybrid cluster
 
 - hybrid-aks-ipam-enabled: If you want IPAM enabled for this network within your AKS-hybrid cluster. Default: True
 - hybrid-aks-plugin-type: valid values are `OSDevice`, `SR-IOV`, `DPDK`. Default: `SR-IOV`
@@ -387,9 +390,9 @@ You'll also need to configure the following information for your aks-hybrid clus
 
 ##### Create a trunked network for AKS-hybrid cluster
 
-You'll need to gather the resourceId(s) of the L2 and L3 isolation-domains you created earlier that configured the VLAN(s) for this network. You're allowed to include as many L2 and L3 isolation-domains as needed.
+Gather the resourceId(s) of the L2 and L3 isolation-domains you created earlier that configured the VLAN(s) for this network. You can include as many L2 and L3 isolation-domains as needed.
 
-You'll also need to configure the following information for your network
+You also need to configure the following information for your network
 
 - hybrid-aks-plugin-type: valid values are `OSDevice`, `SR-IOV`, `DPDK`. Default: `SR-IOV`
 
@@ -412,14 +415,14 @@ You'll also need to configure the following information for your network
 
 ##### Create default CNI network for AKS-Hybrid cluster
 
-You'll need the following information:
+You need the following information:
 
 - `resourceId` of the L3 isolation-domain you created earlier that configures the VLAN for this network.
 - The ipv4-connected-prefix must match the i-pv4-connected-prefix that is in the L3 isolation-domain
 - The ipv6-connected-prefix must match the i-pv6-connected-prefix that is in the L3 isolation-domain
 - The ip-allocation-type can be either "IPv4", "IPv6", or "DualStack" (default)
 - The VLAN value must match what is in the L3 isolation-domain
-- The network MTU doesn't need to be specified here, but the network will be configured with the same MTU information
+- You don't need to specify the network MTU here, as the network will be configured with the same MTU information as used previously
 
 ```azurecli
   az networkcloud defaultcninetwork create --name "<YourDefaultCniNetworkName>" \
@@ -436,9 +439,7 @@ You'll need the following information:
 
 ##### Create cloud services network for AKS-Hybrid cluster
 
-You'll need the following information:
-
-- The egress endpoints you want to add to the proxy for your VM to access.
+You need the egress endpoints you want to add to the proxy for your VM to access.
 
 ```azurecli
   az networkcloud cloudservicesnetwork create --name "<YourCloudServicesNetworkName>" \
@@ -449,7 +450,7 @@ You'll need the following information:
     --additional-egress-endpoints "[{\"category\":\"< YourCategory >\",\"endpoints\":[{\"< domainName1 >\":\"< endpoint1 >\",\"port\":< portnumber1 >}]}]"
 ```
 
-#### Step K2b. ceate vNET for the tenant networks of AKS-Hybrid cluster
+#### Step K2b. Create vNET for the tenant networks of AKS-Hybrid cluster
 
 For each previously created tenant network, a corresponding AKS-Hybrid vNET network needs to be created
 
@@ -507,7 +508,7 @@ Now that you've created the cluster, connect to your AKS-Hybrid cluster by runni
 running this command. If you have multiple Azure subscriptions, select the appropriate
 subscription ID using the `az account set` command.
 
-This command downloads the kubeconfig of your AKS-Hybrid cluster to your local machine
+This command downloads the `kubeconfig` of your AKS-Hybrid cluster to your local machine
 and opens a proxy connection channel to your on-premises AKS-Hybrid cluster.
 The channel is open for as long as this command is running. Let this command run for
 as long as you want to access your cluster. If this command times out, close the CLI

articles/operator-nexus/quickstarts-tenant-workload-prerequisites.md

@@ -20,32 +20,31 @@ This guide explains prerequisites for creating VMs for VNF workloads and AKS-Hyb
 
 ## Preparation
 
-You'll need to create various networks based on your workload needs. The following are some
+You need to create various networks based on your workload needs. The following are some
 recommended questions to consider, but this list is by no means exhaustive. Consult with
 the appropriate support team(s) for help:
 
 - What type of network(s) would you need to support your workload?
   - A layer 3 network requires a VLAN and subnet assignment
     - Subnet must be large enough to support IP assignment to each of the VM
-    - Note the first three usable IP addresses are reserved for internal use by the
-      platform. For instance, to support 6 VMs, then the minimum CIDR for
+    - Note the platform reserves the first three usable IP addresses for internal use.
+      For instance, to support 6 VMs, then the minimum CIDR for
       your subnet is /28 (14 usable address – 3 reserved == 11 addresses available)
     - A layer 2 network requires only a single VLAN assignment
     - A trunked network requires the assignment of multiple VLANs
-  - Determine how many networks of each type you'll need
+  - Determine how many networks of each type you need
   - Determine the MTU size of each of your networks (maximum is 9000)
-  - Determine the BGP peering info for each network, and whether they'll need to talk to
+  - Determine the BGP peering info for each network, and whether they need to talk to
     each other. You should group networks that need to talk to each other into the same L3
     isolation-domain, as each L3 isolation-domain can support multiple layer 3 networks.
-  - You'll be provided with a proxy to allow your VM to reach other external endpoints.
-    You'll be asked later to create a `cloudservicesnetwork` where you'll need to supply the
-    endpoints to be proxied, so now will be a good time to gather that list of endpoints
-    (you can update the list of endpoints after the network is created)
-  - For AKS-Hybrid cluster, you'll also be creating a `defaultcninetwork` to support your
-    cluster CNI networking needs, you'll need to come up with another VLAN/subnet
-    assignment similar to a layer 3 network.
+  - Platform provides a proxy to allow your VM to reach other external endpoints.
+    Creating a `cloudservicesnetwork` requires the endpoints to be proxied. So gather the list of endpoints.
+    You can modify the list of endpoints after the network creation.
+  - For AKS-Hybrid cluster, you need to create a `defaultcninetwork` to support your
+    cluster CNI networking needs. You need another VLAN/subnet
+    assignment for the `defaultcninetwork` similar to a layer 3 network.
 
-You'll need:
+You need:
 
 - your Azure account and the subscription ID of Operator Nexus cluster deployment
 - the `custom location` resource ID of your Operator Nexus cluster
@@ -63,18 +62,18 @@ Install latest version of the
 
 ## Operator Nexus workload images
 
-These images will be used when creating your workload VMs. Make sure each is a
-containerized image in either `qcow2` or `raw` disk format and is uploaded to an Azure Container
+Make sure that each image, used for creating your workload VMs, is a
+containerized image in either `qcow2` or `raw` disk format. Upload these images to an Azure Container
 Registry. If your Azure Container Registry is password protected, you can supply this info when creating your VM.
 Refer to [Operator Nexus VM disk image build procedure](#operator-nexus-vm-disk-image-build-procedure) for an example for pulling from an anonymous Azure Container Registry.
 
 ### Operator Nexus VM disk image build procedure
 
-This is a paper-exercise example of an anonymous pull of an image from Azure Container Registry.  
-It assumes that you already have an existing VM instance image in `qcow2` format and that the image is set up to boot with cloud-init. A working docker build and runtime environment  is required.
+This build procedure is a paper-exercise example of an anonymous pull of an image from Azure Container Registry.  
+It assumes that you already have an existing VM instance image in `qcow2` format and that the image can boot with cloud-init. The procedure requires a working docker build and runtime environment.
 
 Create a dockerfile that copies the `qcow2` image file into the container's /disk directory. Place in an expected directory with correct permissions.
-For example, a Dockerfile named `workload-vm-img-dockerfile`:
+For example, a Dockerfile named `aods-vm-img-dockerfile`:
 
 ```bash
 FROM scratch
@@ -85,7 +84,7 @@ Using the docker command, build the image and tag to a Docker registry (such as
 The docker command assumes the `qcow2` file is in the same directory as your Dockerfile.
 
 ```bash
-  docker build -f workload-vm-img-dockerfile -t devtestacr.azurecr.io/your-favorite-image:v1 .
+  docker build -f aods-vm-img-dockerfile -t devtestacr.azurecr.io/your-favorite-image:v1 .
   FROM scratch
   ADD --chown=107:107 your-favorite-image.qcow2 /disk/
 ```
@@ -131,7 +130,7 @@ This VM image build procedure is derived from [kubevirt](https://kubevirt.io/use
 
 ## Miscellaneous prerequisites
 
-To deploy your workloads you'll also need:
+To deploy your workloads, you need:
 
 - to create resource group or find a resource group to use for your workloads
-- the network fabric resource ID, you'll need this ID to create isolation-domains
+- the network fabric resource ID to create isolation-domains.