Merge pull request #87534 from ekpgh/release-preview-hpc-cache

incorporate SME review feedback

Author: v-albemi

articles/hpc-cache/hpc-cache-add-storage.md

@@ -4,27 +4,29 @@ description: How to define storage targets so that your Azure HPC Cache can use
 author: ekpgh
 ms.service: hpc-cache
 ms.topic: conceptual
-ms.date: 08/30/2019
+ms.date: 09/06/2019
 ms.author: v-erkell
 ---
 
 # Add storage
 
-*Storage targets* are long-term storage for files that are accessed through an Azure HPC Cache instance. You can add NFS storage, like an on-premises hardware system, or store data in Azure Blob.
+*Storage targets* are back-end storage for files that are accessed through an Azure HPC Cache instance. You can add NFS storage, like an on-premises hardware system, or store data in Azure Blob.
 
-You can define up to ten different storage targets for one cache. The cache presents all of the storage targets in one client-facing filesystem called the aggregated namespace.
+You can define up to ten different storage targets for one cache. The cache presents all of the storage targets in one aggregated namespace.
 
 Remember that the storage exports must be accessible from your cache's virtual network. For on-premises hardware storage, you might need to set up a DNS server that can resolve hostnames for NFS storage access. Read more in [DNS access](hpc-cache-prereqs.md#dns-access).
 
-You can add storage targets while creating your Azure HPC Cache, or afterward. The procedure is slightly different depending on whether you're adding Azure Blob storage or an NFS-accessible export. Details for each are below.
+You can add storage targets while creating your Azure HPC Cache, or afterward. The procedure is slightly different depending on whether you're adding Azure Blob storage or an NFS export. Details for each are below.
 
-## Add storage targets while creating the cache 
+## Add storage targets while creating the cache
 
 Use the **Storage targets** tab of the cache creation wizard to define storage at the same time you create the cache instance.
 
 ![screenshot of storage targets page](media/create-targets.png)
 
-## Add storage targets from the cache 
+Click the **Add storage target** link to add storage.
+
+## Add storage targets from the cache
 
 From the Azure portal, open your cache instance and click **Storage targets** on the left sidebar. The storage target page lists all existing targets and gives a link to add a new one.
 
@@ -38,26 +40,26 @@ To define an Azure Blob container, enter this information.
 
 * **Storage target name** - Set a name that identifies this storage target in the Azure HPC Cache.
 * **Target type** - Choose **Blob**.
-* **Storage account** - Select the account with the container to reference. 
+* **Storage account** - Select the account with the container to reference.
 
-  You will need to authorize the cache instance to access the storage account as described in [Add the access role](#add-the-access-control-role-to-your-account).
+  You will need to authorize the cache instance to access the storage account as described in [Add the access roles](#add-the-access-control-roles-to-your-account).
 * **Storage container** - Select the Blob container for this target.
 
 * **Virtual namespace path** - Set the client-facing filepath for this storage target. Read [Configure aggregated namespace](hpc-cache-namespace.md) to learn more about the virtual namespace feature.
 
-  The namespace path value must end with a slash (``/``) and should not start with one.
+<!--  The namespace path value must end with a slash (``/``) and should not start with one.  -->
 
-When finished, click **Ok** to add the storage target.
+When finished, click **OK** to add the storage target.
 
-### Add the access control role to your account
+### Add the access control roles to your account
 
 The Azure HPC Cache uses [role-based access control (RBAC)](https://docs.microsoft.com/azure/role-based-access-control/index) to authorize the cache application to access your storage account for Azure Blob storage targets.
 
-The storage account owner must explicitly add the role [Storage Account Contributor](https://docs.microsoft.com/azure/role-based-access-control/built-in-roles#storage-account-contributor) for the user "StorageCache Resource Provider".
+The storage account owner must explicitly add the rolls [Storage Account Contributor](https://docs.microsoft.com/azure/role-based-access-control/built-in-roles#storage-account-contributor) and [Storage Blob Data Contributor](https://docs.microsoft.com/azure/role-based-access-control/built-in-roles#storage-blob-data-contributor) for the user "StorageCache Resource Provider".
 
 You can do this ahead of time, or by clicking a link on the page where you add a Blob storage target.
 
-Steps to add the RBAC role: 
+Steps to add the RBAC roles:
 
 1. Open the **Access control (IAM)** page for the storage account. (The link in the **Add storage target** page automatically opens this page for the selected account.)
 
@@ -67,15 +69,17 @@ Steps to add the RBAC role:
 
 1. In the **Assign access to** field, leave the default value selected ("Azure AD user, group, or service principal").  
 
-1. In the **Select** field, search for "storagecache".  This string should match one security principal, named "HPC Cache Resource Provider". Click that principal to select it. 
+1. In the **Select** field, search for "storagecache".  This string should match one security principal, named "HPC Cache Resource Provider". Click that principal to select it.
+
+1. Click the **Save** button to add the role assignment to the storage account.
 
-1. Click the **Save** button to add the role assignment to the storage account. 
+1. Repeat this process to assign the role "Storage Blob Data Contributor".  
 
 ![screenshot of add role assignment GUI](media/hpc-cache-add-role.png)
 
 ## Add a new NFS storage target
 
-An NFS storage target has some extra fields to specify how to reach the storage export and how to efficiently cache its data. Also, you can create multiple storage targets from one NFS host if it has different exports available. 
+An NFS storage target has some extra fields to specify how to reach the storage export and how to efficiently cache its data. Also, you can create multiple namespace paths from one NFS host if it has more than one export available.
 
 ![Screenshot of add storage target page with NFS target defined](media/hpc-cache-add-nfs-target.png)
 
@@ -91,17 +95,17 @@ Provide this information for an NFS-backed storage target:
 
 You can create multiple namespace paths to represent different exports on the same NFS storage system, but you must create them all from one storage target.
 
-For each export, fill in these values: 
+For each export, fill in these values:
 
 * **Virtual namespace path** - Set the client-facing filepath for this storage target. Read [Configure aggregated namespace](hpc-cache-namespace.md) to learn more about the virtual namespace feature.
 
-  The virtual path should start with a slash ``/``.
+<!--  The virtual path should start with a slash ``/``. -->
 
-* **NFS export path** - Enter the path to the data export to mount at this namespace path. 
+* **NFS export path** - Enter the path to the NFS export.
 
-* **Subdirectory path** - If you want to mount a specific subdirectory of the export, enter it here. If not, enter a slash (``/``).
+* **Subdirectory path** - If you want to mount a specific subdirectory of the export, enter it here. If not, leave this field blank. 
 
-When finished, click **Ok** to add the storage target.
+When finished, click **OK** to add the storage target.
 
 ### Choose a usage model 
 <!-- link in GUI to this heading -->

articles/hpc-cache/hpc-cache-create.md

@@ -4,130 +4,84 @@ description: How to create an Azure HPC Cache instance
 author: ekpgh
 ms.service: hpc-cache
 ms.topic: tutorial
-ms.date: 08/30/2019
+ms.date: 09/06/2019
 ms.author: v-erkell
 ---
 
-# Create a cache
+# Create an Azure HPC Cache
 
-Use the Azure portal to create the cache instance.
+Use the Azure portal to create your cache.
 
-![screenshot of cache overview in Azure portal, with create button at the bottom](media/hpc-cache-home-page.png) 
+![screenshot of cache overview in Azure portal, with create button at the bottom](media/hpc-cache-home-page.png)
 
-## Basics
+## Define basic details
 
 ![screenshot of project details page in Azure portal](media/create-1.png)
 
-In **Project Details**, select the subscription and resource group that will host the Azure HPC Cache. Make sure the subscription is the one that was whitelisted by the preview team.
+In **Project Details**, select the subscription and resource group that will host the Azure HPC Cache. Make sure the subscription is on the [preview access](hpc-cache-prereqs.md#azure-subscription) list.
 
 In **Service Details**, set the cache name and these other attributes:
 
 * Location - Select one of the [supported regions](hpc-cache-overview.md#region-availability).
 * Virtual network - You can select an existing one or create a new virtual network.
-* Subnet - Choose or create a subnet with at least 64 IP addresses (/24) that will be used only for the Azure HPC Cache. 
+* Subnet - Choose or create a subnet with at least 64 IP addresses (/24) that will be used only for the Azure HPC Cache.
 
-## Set cache size
+## Set cache capacity
 <!-- change link in GUI -->
 
-On the **Cache** page, you must set the capacity of your Azure HPC Cache.
+On the **Cache** page, you must set the capacity of your Azure HPC Cache. This value determines how much data your cache can hold and how quickly it can service client requests. After the public preview period, capacity will also affect the cache's cost.
 
-Cache capacity is determined by two factors:
+Cache capacity is measured in input/output operations per second (IOPS). Choose the capacity by setting these two values:
 
-* The number of operations per second that you want the cache to support (throughput)
-* The amount of data you want to have room for in the cache storage
+* The maximum data transfer rate for the cache (throughput), in GB/second
+* The amount of storage allocated for cached data, in TB
 
-Choose one of the available throughput values (in GB/second) and cache storage sizes (in TB). The IOPS capacity is calculated and shown underneath the value selectors. 
+Choose one of the available throughput values and cache storage sizes. The IOPS capacity is calculated and shown below the value selectors.
+
+Keep in mind that the actual data transfer rate depends on workload, network speeds, and the type of storage targets. If a file isn't in the cache, or it is marked as stale, the service will use some throughput to fetch it from backend storage. The value you choose sets the maximum throughput for the entire cache, and not all of it is available for client requests.
+
+For cache storage, Azure HPC Cache manages which files are cached and preloaded to maximize cache hit rates. The cache contents are continuously assessed and files are moved to long-term storage when they are less frequently accessed. Choose a cache storage size that can comfortably hold the active set of working files with additional space for metadata and other overhead.
 
 ![screenshot of cache sizing page](media/create-cache-iops.png)
 
 ## Add storage targets
 
-Storage targets are the long-term storage for the contents of your cache. You can define storage targets while creating the cache, but you can also add them afterward with the link in the **Configure** section of your cache's page in the portal.
+Storage targets are the back-end, long-term storage for the contents of your cache.
+
+You can define storage targets while creating the cache, but you can also add them afterward with the link in the **Configure** section of your cache's page in the portal.
 
 ![screenshot of storage targets page](media/create-targets.png)
 
-Click the **Add storage target link** to define your back-end storage systems. The storage can be Azure Blob containers or on-premises NFS systems. 
+Click the **Add storage target link** to define your back-end storage systems. The storage can be Azure Blob containers or on-premises NFS systems.
 
 You can define up to ten different storage targets.
 
 For step-by-step instructions to add a storage target, read [Add storage](hpc-cache-add-storage.md). The procedure is different for Blob storage or for NFS exports.
 
-For both types of storage, you must specify the back-end storage system's address or container name and the client-facing namespace path to show for it.
-
-When creating a Blob storage target, make sure the cache has access permissions to the storage account, as described in [Add the access control role](hpc-cache-add-storage.md#add-the-access-control-role-to-your-account).
-
-When creating an NFS storage target, specify a [usage model](hpc-cache-add-storage.md#choose-a-usage-model). The usage model tells the cache how to optimize cache utilization for your workflow.
-
-<!-- ## Storage target details 
-
-Slightly different information is used for Blob storage targets than for NFS storage targets.
-
-Both NFS and Blob storage targets require this *common information*: 
-
-* **Storage target name** - Set the name that the Azure HPC Cache will display for this storage target.
-* **Target type** - Select either Blob or NFS depending on the type of access for the long-term storage.
-* **Virtual namespace path** - Set the client-facing filepath for this storage target. Read [Configure aggregated namespace](hpc-cache-namespace.md) to learn more about the virtual namespace feature.
-
-*For an NFS storage target*, you must specify how to reach the storage export and how to efficiently cache its data:
-
-* **Hostname:Export** - Provide the fully qualified domain name (FQDN) and export that the storage target will point to. You can create multiple storage targets to represent different exports on the same NFS storage system.
-
-> [!NOTE] 
-> Although the example in a screenshot below uses an IP address, FQDN is preferred. An IP address can be used if necessary.
-
-* **Usage model** - Choose one of the data caching profiles based on your workflow, described in [Choose a usage model, below](#choose-a-usage-model-nfs-storage-targets-only).
-
-*For a Blob storage target*, you also need to supply this information: 
-
-* **Storage account** - The account that hosts the container
-* **Storage container** - The name of the empty container to reference
-
-  You can move data to the Blob storage target after the cache is created. Consult your Azure HPC Cache support representative for instructions.
-* If you have not already done it, add the access role permission to the storage account as explained [below](#add-the-access-control-role-to-your-account-blob-storage-only).
-
-![screenshot of blob storage target creation form](media/create-add-blob.png)
-
-### Add the access control role to your account (Blob storage only)
-
-The Azure HPC Cache uses [role-based access control (RBAC)](https://docs.microsoft.com/azure/role-based-access-control/index) to authorize the cache application to access your storage account for Azure Blob storage targets.
-
-The storage account owner must explicitly add the role [Storage Account Contributor](https://docs.microsoft.com/azure/role-based-access-control/built-in-roles#storage-account-contributor) for the user "StorageCache Resource Provider".
-
-You can do this when you add the Blob storage target as part of creating the cache instance. Links are provided in the storage target section of the creation wizard.
-
-Steps to add the RBAC role: 
+For both types of storage, you must specify how to find the back-end storage system (either an NFS address or a Blob container name) and the client-facing namespace path.
 
-1. Open the **Access control (IAM)** page for the storage account.
-1. Click the **+** at the top of the page and choose **Add a role assignment**.
-1. Select the role "Storage Account Contributor" from the list.
-1. In the **Assign access to** field, leave the default value selected ("Azure AD user, group, or service principal").  
-1. In the **Select** field, search for "storagecache".  This string should match one security principal, named HPC Cache Resource Provider. Click that principal to select it. 
-1. Click the **Save** button to add the role assignment to the storage account. 
+When creating a Blob storage target, make sure the cache has access permissions to the storage account, as described in [Add the access control roles](hpc-cache-add-storage.md#add-the-access-control-roles-to-your-account). If you are not sure the role configuration will be successful, create the cache first and then add the Blob storage afterward.
 
-![screenshot of add role assignment GUI](media/add-role.png)
+When creating an NFS storage target, specify a [usage model](hpc-cache-add-storage.md#choose-a-usage-model). The usage model setting helps the cache optimize your workflow.
 
-### Choose a usage model (NFS storage targets only)
-<!-- link in GUI to this heading --> 
-<!-- 
+## Add resource tags (optional)
 
-When you create a storage target that points to an NFS storage system, you need to choose the *usage model* for that target. This model determines how your data is cached.
+The **Tags** page lets you add [resource tags](https://go.microsoft.com/fwlink/?linkid=873112) to your Azure HPC Cache. 
 
-* Read heavy - If you mostly use the cache to speed up data read access, choose this option. 
-* Read/write - If clients use the cache to read and write, choose this option.
-* Clients bypass the cache - Choose this option if your clients write data directly to the storage system without first writing to the cache.
+## Finish creating the cache
 
-![screenshot of NFS storage target creation form](media/create-add-nfs.png)  -->
+After configuring the new cache, click the **Review + create** tab. The portal validates your selections and lets you review your choices. If everything is correct, click **Create**. 
 
-## Finished cache
+Cache creation takes about 10 minutes. You can track the progress in the Azure portal's notifications panel. When it finishes, a notification appears with a link to the new Azure HPC Cache instance. 
 
-After about 10 minutes, the Azure HPC Cache is visible in your subscription's **Resources** list.
+The cache also is visible in your subscription's **Resources** list. 
 
 ![screenshot of Azure HPC Cache instance in Azure portal](media/finished-hpc-cache.png)
 
 ## Next steps
 
-After your cache appears in the **Resources** list, you can mount it for access, use it to move your working set data to a new Azure Blob storage target, or define additional data sources.
+After your cache appears in the **Resources** list, you can mount it for client access, use it to move your working set data to a new Azure Blob storage target, or define additional data sources.
 
-* [Access the Azure HPC Cache system](hpc-cache-mount.md) 
+* [Mount the Azure HPC Cache](hpc-cache-mount.md)
 * [Move data to Azure Blob storage for Azure HPC Cache](hpc-cache-ingest.md)
-* [Add storage targets](hpc-cache-add-storage.md)
+* [Add storage targets](hpc-cache-add-storage.md)

articles/hpc-cache/hpc-cache-ingest-parallelcp.md

@@ -82,7 +82,7 @@ sudo apt install -y gcc bison gcc binutils make parallel
 cd
 wget https://mirrors.kernel.org/gnu/libc/glibc-2.27.tar.bz2
 tar jxf glibc-2.27.tar.bz2
-ln -s /nfs/cache1 hpccache   
+ln -s /nfs/cache1 hpccache
 time parallelcp glibc-2.27 avere/glibc-2.27
 cd
 mkdir obj