Merge pull request #102983 from erikadoyle/reviewedits

Service Fabric content portfolio review (batch 3)

Author: Kellylorenebaker

articles/service-fabric/concepts-managed-identity.md

@@ -1,73 +1,70 @@
 ---
-title: Service Fabric Managed Identity overview
-description: This article is an overview of Managed Identity and its applications to Azure Service Fabric.
-
+title: Managed identities for Azure
+description: Learn about using Managed identities for Azure with Service Fabric.
 ms.topic: conceptual 
 ms.date: 12/09/2019
+ms.custom: sfrev
 ---
 
-# Managed Identity for Service Fabric Application (Preview)
+# Using Managed identities for Azure with Service Fabric (Preview)
 
-A common challenge when building cloud applications is how to manage the credentials in your code for authenticating to cloud services. Keeping credentials secure is an important task, since they never appear on developer workstations and are not checked into source control. The Managed Identity feature for Azure resources in Azure Active Directory (Azure AD) solves this problem. The feature provides Azure services with an automatically managed identity in Azure AD. You can use the identity to authenticate to any service that supports Azure AD authentication, including Key Vault, without any credentials in your code.
+A common challenge when building cloud applications is how to securely manage the credentials in your code for authenticating to various services without saving them locally on a developer workstation or in source control. *Managed identities for Azure* solve this problem for all your resources in Azure Active Directory (Azure AD) by providing them with automatically managed identities within Azure AD. You can use a service's identity to authenticate to any service that supports Azure AD authentication, including Key Vault, without any credentials stored in your code.
 
-The Managed Identity feature for Azure resources is free with Azure AD for Azure subscriptions. There is no additional cost.
+*Managed identities for Azure resources* are free with Azure AD for Azure subscriptions. There's no additional cost.
 
 > [!NOTE]
-> Managed Identity for Azure resources is the new name for the service formerly known as Managed Service Identity (MSI).
+> *Managed identities for Azure* is the new name for the service formerly known as Managed Service Identity (MSI).
 
-## Terminology
+## Concepts
 
-The following terms are used throughout the Managed Identity for Azure resources documentation set:
+Managed identities for Azure is based upon several key concepts:
 
 - **Client ID** - a unique identifier generated by Azure AD that is tied to an application and service principal during its initial provisioning (also see [application ID](/azure/active-directory/develop/developer-glossary#application-id-client-id).)
 
 - **Principal ID** - the object ID of the service principal object for your Managed Identity that is used to grant role-based access to an Azure resource.
 
 - **Service Principal** - an Azure Active Directory object, which represents the projection of an AAD application in a given tenant (also see [service principal](../active-directory/develop/developer-glossary.md#service-principal-object).)
 
+The are two types of managed identities:
 
-## About Managed Identities in Azure
-
-- [Types of Managed Identity(MI) in Azure](https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/overview#how-does-the-managed-identities-for-azure-resources-work)
-
-- [How does System-Assigned Managed Identity work in Azure](https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/overview#how-a-system-assigned-managed-identity-works-with-an-azure-vm)
-
-- [How does User-Defined Managed Identity(MI) work in Azure](https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/overview#how-a-user-assigned-managed-identity-works-with-an-azure-vm)
+- A **System-assigned managed identity** is enabled directly on an Azure service instance.  The lifecycle of a system-assigned identity is unique to the Azure service instance that it's enabled on.
+- A **user-assigned managed identity** is created as a standalone Azure resource. The identity can be assigned to one or more Azure service instances and is managed separately from the lifecycles of those instances.
 
+To further understand the difference between managed identity types, see [How do managed identities for Azure resources work?](../active-directory/managed-identities-azure-resources/overview.md#how-does-the-managed-identities-for-azure-resources-work)
 
 ## Supported scenarios for Service Fabric applications
 
-Managed identities for Service Fabric is only supported in Azure deployed Service Fabric clusters, and only for applications deployed as Azure resources; an application which is not deployed as an Azure resource cannot be assigned an identity. Conceptually speaking, support for managed identities in Azure Service Fabric cluster consists of two phases:
+Managed identities for Service Fabric are only supported in Azure-deployed Service Fabric clusters, and only for applications deployed as Azure resources; an application that is not deployed as an Azure resource cannot be assigned an identity. Conceptually speaking, support for managed identities in Azure Service Fabric cluster consists of two phases:
 
 1. Assign one or more managed identities to the application resource; an application may be assigned a single system-assigned identity, and/or up to 32 user-assigned identities, respectively.
 
 2. Within the application's definition, map one of the identities assigned to the application to any individual service comprising the application.
 
-The system-assigned identity of an application is unique to that application; a user-assigned identity is a standalone resource, which may be assigned to multiple applications. Within an application, a single identity (whether system-assigned or user-assigned) can be assigned to multiple services of the application, but each individual service can only be assigned one identity. Lastly, a service must be assigned an identity explicitly to have access to this feature. In effect, the mapping of an application's identities to its constituent services allows for an in-application isolation - a service may only use the identity mapped to it (and none at all if it was not explicitly assigned one.)  
-
-The list of supported scenarios for the preview release is as follows:
+The system-assigned identity of an application is unique to that application; a user-assigned identity is a standalone resource, which may be assigned to multiple applications. Within an application, a single identity (whether system-assigned or user-assigned) can be assigned to multiple services of the application, but each individual service can only be assigned one identity. Lastly, a service must be assigned an identity explicitly to have access to this feature. In effect, the mapping of an application's identities to its constituent services allows for in-application isolation — a service may only use the identity mapped to it.  
 
-   - Deploy a new application with one or more services, and one or more assigned identities
+Currently, the following scenarios are supported for this preview feature:
 
-   - Assign one or more managed identities to an existing application in order to access Azure resources; the application must have been deployed as an Azure resource itself
+- Deploy a new application with one or more services and one or more assigned identities
 
+- Assign one or more managed identities to an existing (Azure-deployed) application in order to access Azure resources
 
 The following scenarios are not supported or not recommended; note these actions may not be blocked, but can lead to outages in your applications:
 
-   - Remove or change the identities assigned to an application; if you must make changes, submit separate deployments to first add a new identity assignment, and then to remove a previously assigned one. Removal of an identity from an existing application can have undesirable effects, including leaving your application in a state that is not upgradeable. It is safe to delete the application altogether if the removal of an identity is necessary; note this will delete the system-assigned identity (if so defined) associated with the application, and will remove any associations with the user-assigned identities assigned to the application.
+- Remove or change the identities assigned to an application; if you must make changes, submit separate deployments to first add a new identity assignment, and then to remove a previously assigned one. Removal of an identity from an existing application can have undesirable effects, including leaving your application in a state that is not upgradeable. It is safe to delete the application altogether if the removal of an identity is necessary; note this will delete the system-assigned identity (if so defined) associated with the application, and will remove any associations with the user-assigned identities assigned to the application.
 
-   - SF support for managed identities is not integrated at this time into the [AzureServiceTokenProvider](../key-vault/service-to-service-authentication.md); the integration will be achieved by the end of the preview period for the managed identity feature.
+- Service Fabric support for managed identities is not integrated at this time into the [AzureServiceTokenProvider](../key-vault/service-to-service-authentication.md); the integration will be achieved by the end of the preview period for the managed identity feature.
 
 >
 > [!NOTE]
 >
-> This feature is in preview; as such, it may be subject to frequent changes, and may not be suitable for production deployments.
+> This feature is in preview. It may be subject to frequent changes and not suitable for production deployments.
 
 ## Next steps
-* [Deploy a new Azure Service Fabric cluster with managed identity support](./configure-new-azure-service-fabric-enable-managed-identity.md) 
-* [Enable managed identity support in an existing Azure Service Fabric cluster](./configure-existing-cluster-enable-managed-identity-token-service.md)
-* [Deploy an Azure Service Fabric application with a system-assigned managed identity](./how-to-deploy-service-fabric-application-system-assigned-managed-identity.md)
-* [Deploy an Azure Service Fabric application with a user-assigned managed identity](./how-to-deploy-service-fabric-application-user-assigned-managed-identity.md)
-* [Leverage the managed identity of a Service Fabric application from service code](./how-to-managed-identity-service-fabric-app-code.md)
-* [Grant an Azure Service Fabric application access to other Azure resources](./how-to-grant-access-other-resources.md)
-* [Declaring and using application secrets as KeyVaultReferences](./service-fabric-keyvault-references.md) 
+
+- [Deploy a new Azure Service Fabric cluster with managed identity support](./configure-new-azure-service-fabric-enable-managed-identity.md)
+- [Enable managed identity support in an existing Azure Service Fabric cluster](./configure-existing-cluster-enable-managed-identity-token-service.md)
+- [Deploy an Azure Service Fabric application with a system-assigned managed identity](./how-to-deploy-service-fabric-application-system-assigned-managed-identity.md)
+- [Deploy an Azure Service Fabric application with a user-assigned managed identity](./how-to-deploy-service-fabric-application-user-assigned-managed-identity.md)
+- [Leverage the managed identity of a Service Fabric application from service code](./how-to-managed-identity-service-fabric-app-code.md)
+- [Grant an Azure Service Fabric application access to other Azure resources](./how-to-grant-access-other-resources.md)
+- [Declaring and using application secrets as KeyVaultReferences](./service-fabric-keyvault-references.md)

articles/service-fabric/configure-container-repository-credentials.md

@@ -1,16 +1,14 @@
 ---
 title: Azure Service Fabric - Configure container repository credentials
 description: Configure repository credentials to download images from container registry
-author: arya
-
 ms.topic: conceptual
 ms.date: 12/09/2019
-ms.author: arya
+ms.custom: sfrev
 ---
 
 # Configure repository credentials for your application to download container images
 
-Configure container registry authentication by adding `RepositoryCredentials` to `ContainerHostPolicies` of the ApplicationManifest.xml file. Add the account and password for the myregistry.azurecr.io container registry, which allows the service to download the container image from the repository.
+Configure container registry authentication by adding `RepositoryCredentials` to the `ContainerHostPolicies` section of your application manifest. Add the account and password for your container registry (*myregistry.azurecr.io* in the example below), which allows the service to download the container image from the repository.
 
 ```xml
 <ServiceManifestImport>
@@ -51,7 +49,7 @@ Service Fabric then uses the default repository credentials which can be specifi
 * DefaultContainerRepositoryAccountName (string)
 * DefaultContainerRepositoryPassword (string)
 * IsDefaultContainerRepositoryPasswordEncrypted (bool)
-* DefaultContainerRepositoryPasswordType (string) --- Supported starting with the 6.4 runtime
+* DefaultContainerRepositoryPasswordType (string)
 
 Here is an example of what can be added inside the `Hosting` section in the ClusterManifestTemplate.json file. The `Hosting` section can be added at cluster creation or later in a configuration upgrade. For more information, see [Change Azure Service Fabric cluster settings](service-fabric-cluster-fabric-settings.md) and [Manage Azure Service Fabric application secrets](service-fabric-application-secret-management.md)
 
@@ -86,19 +84,19 @@ Here is an example of what can be added inside the `Hosting` section in the Clus
 ]
 ```
 
-## Leveraging the Managed Identity of the virtual machine scale set by using Managed Identity Service (MSI)
+## Use tokens as registry credentials
 
-Service Fabric supports using tokens as credentials to download images for your containers.  This feature leverages the managed identity of the underlying virtual machine scale set to authenticate to the registry, eliminating the need for managing user credentials.  See [Managed Service Identity](https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/overview) for more on MSI.  Using this feature requires the follows steps:
+Service Fabric supports using tokens as credentials to download images for your containers.  This feature leverages the *managed identity* of the underlying virtual machine scale set to authenticate to the registry, eliminating the need for managing user credentials.  See [Managed identities for Azure resources](../active-directory/managed-identities-azure-resources/overview.md) for more info.  Using this feature requires the follows steps:
 
-1.  Ensure that System Assigned Managed Identity is enabled for the VM (see screenshot below)
+1. Ensure that *System Assigned Managed Identity* is enabled for the VM.
 
-    ![Create virtual machine scale set identity](./media/configure-container-repository-credentials/configure-container-repository-credentials-acr-iam.png)
+    ![Azure portal: Create virtual machine scale set identity option](./media/configure-container-repository-credentials/configure-container-repository-credentials-acr-iam.png)
 
-2.  After that, grant permissions to the VM(SS) to pull/read images from the registry.  Go to Access Control (IAM) of your ACR via Azure Blade and give your VM(SS) the correct permissions, as seen below:
+2. Grant permissions to the virtual machine scale set to pull/read images from the registry. From the Access Control (IAM) blade of your Azure Container Registry in the Azure portal, add a *role assignment* for your virtual machine:
 
     ![Add VM principal to ACR](./media/configure-container-repository-credentials/configure-container-repository-credentials-vmss-identity.png)
 
-3.  Once the above steps are completed, modify your applicationmanifest.xml file.  Find the tag labeled “ContainerHostPolicies” and add the attribute `‘UseTokenAuthenticationCredentials=”true”`.
+3. Next, modify your application manifest. In the `ContainerHostPolicies` section, add the attribute `‘UseTokenAuthenticationCredentials=”true”`.
 
     ```xml
       <ServiceManifestImport>
@@ -117,4 +115,4 @@ Service Fabric supports using tokens as credentials to download images for your
 
 ## Next steps
 
-* See more about [Container registry authentication](/azure/container-registry/container-registry-authentication).
+* See more about [Container registry authentication](../container-registry/container-registry-authentication.md).

articles/service-fabric/configure-existing-cluster-enable-managed-identity-token-service.md

@@ -1,24 +1,25 @@
 ---
-title: Azure Service Fabric - Configure an existing Azure Service Fabric cluster to enable managed identity support
-description: This article shows you how to configure an existing Azure Service Fabric cluster to enable support for managed identities
-
+title: Configure managed identity support in an existing Service Fabric cluster
+description: Here's how to enable managed identities support in an existing Azure Service Fabric cluster
 ms.topic: article
 ms.date: 12/09/2019
+ms.custom: sfrev
 ---
 
-# Configure an existing Azure Service Fabric cluster to enable Managed Identity support (preview)
-In order to access the managed identity feature for Azure Service Fabric applications, you must first enable the **Managed Identity Token Service** on the cluster. This service is responsible for the authentication of Service Fabric applications using their managed identities, and for obtaining access tokens on their behalf. Once the service is enabled, you can see it in Service Fabric Explorer under the **System** section in the left pane, running under the name **fabric:/System/ManagedIdentityTokenService**.
+# Configure managed identity support in an existing Service Fabric cluster (preview)
+
+To use [Managed identities for Azure resources](../active-directory/managed-identities-azure-resources/overview.md) in your Service Fabric applications, first enable the *Managed Identity Token Service* on the cluster. This service is responsible for the authentication of Service Fabric applications using their managed identities, and for obtaining access tokens on their behalf. Once the service is enabled, you can see it in Service Fabric Explorer under the **System** section in the left pane, running under the name **fabric:/System/ManagedIdentityTokenService**.
 
 > [!NOTE]
 > Service Fabric runtime version 6.5.658.9590 or higher is required to enable the **Managed Identity Token Service**.  
-> 
+>
 > You can find the Service Fabric version of a cluster from the Azure portal by opening the cluster resource and checking the **Service Fabric version** property in the **Essentials** section.
-> 
+>
 > If the cluster is on **Manual** upgrade mode, you will need to first upgrade it to 6.5.658.9590 or later.
 
+## Enable *Managed Identity Token Service* in an existing cluster
 
-## Enable the Managed Identity Token Service in an existing cluster
-To enable the Managed Identity Token Service in an existing cluster, you will need to initiate a cluster upgrade specifying two changes: enabling the Managed Identity Token Service, and requesting a restart of each node. To do so, add the following two snippets in the Azure Resource Manager template:
+To enable the Managed Identity Token Service in an existing cluster, you will need to initiate a cluster upgrade specifying two changes: (1) Enabling the Managed Identity Token Service, and (2) requesting a restart of each node. First, add the following snippet your cluster Azure Resource Manager template:
 
 ```json
 "fabricSettings": [