Merge pull request #51790 from apinnick/GH45375-azure-install

GH#45375: Azure installation admin role

Author: apinnick

modules/installation-azure-service-principal.adoc

@@ -16,42 +16,39 @@ endif::[]
 [id="installation-azure-service-principal_{context}"]
 = Creating a service principal
 
-Because {product-title} and its installation program must create Microsoft Azure
-resources through Azure Resource Manager, you must create a service principal
-to represent it.
+Because {product-title} and its installation program create Microsoft Azure resources by using the Azure Resource Manager, you must create a service principal to represent it.
 
 .Prerequisites
 
 * Install or update the link:https://docs.microsoft.com/en-us/cli/azure/install-azure-cli-yum?view=azure-cli-latest[Azure CLI].
-* Install the `jq` package.
 * Your Azure account has the required roles for the subscription that you use.
 
 .Procedure
 
 ifdef::ash[]
-. Register your Azure Stack Cloud environment with your Azure CLI. For more details on this process, see Microsoft's documentation for link:https://docs.microsoft.com/en-us/azure-stack/mdc/azure-stack-version-profiles-azurecli-2-tzl#connect-to-azure-stack-hub[Connecting to Azure Stack Hub].
-
-.. Register your environment with the Azure CLI:
+. Register your environment:
 +
 [source,terminal]
 ----
-$ az cloud register -n <environment_name> --endpoint-resource-manager <arm_endpoint>
+$ az cloud register -n AzureStackCloud --endpoint-resource-manager <endpoint> <1>
 ----
+<1> Specify the Azure Resource Manager endpoint, \`https://management.<region>.<fqdn>/`.
++
+See the link:https://docs.microsoft.com/en-us/azure-stack/mdc/azure-stack-version-profiles-azurecli-2-tzl#connect-to-azure-stack-hub[Microsoft documentation] for details.
 
-.. Set the active environment:
+. Set the active environment:
 +
 [source,terminal]
 ----
-$ az cloud set -n <environment_name>
+$ az cloud set -n AzureStackCloud
 ----
 
-.. Update your environment configuration to use the specific API version for Azure Stack Hub:
+. Update your environment configuration to use the specific API version for Azure Stack Hub:
 +
 [source,terminal]
 ----
 $ az cloud update --profile 2019-03-01-hybrid
 ----
-
 endif::ash[]
 
 . Log in to the Azure CLI:
@@ -60,14 +57,14 @@ endif::ash[]
 ----
 $ az login
 ----
-+
-Log in to Azure in the web console by using your credentials.
 ifdef::ash[]
++
 If you are in a multitenant environment, you must also supply the tenant ID.
 endif::ash[]
 
 . If your Azure account uses subscriptions, ensure that you are using the right
-subscription.
+subscription:
+
 .. View the list of available accounts and record the `tenantId` value for the
 subscription you want to use for your cluster:
 +
@@ -129,19 +126,17 @@ endif::[]
   }
 }
 ----
-<1> Ensure that the value of the `tenantId` parameter is the UUID of the
-correct subscription.
+<1> Ensure that the value of the `tenantId` parameter is the correct subscription ID.
 
 .. If you are not using the right subscription, change the active subscription:
 +
 [source,terminal]
 ----
-$ az account set -s <id> <1>
+$ az account set -s <subscription_id> <1>
 ----
-<1> Substitute the value of the `id` for the subscription that you want to
-use for `<id>`.
+<1> Specify the subscription ID.
 
-.. If you changed the active subscription, display your account information again:
+.. Verify the subscription ID update:
 +
 [source,terminal]
 ----
@@ -170,94 +165,45 @@ endif::[]
 }
 ----
 
-. Record the values of the `tenantId` and `id` parameters from the previous
-output. You need these values during {product-title} installation.
+. Record the `tenantId` and `id` parameter values from the output. You need these values during the {product-title} installation.
 
 . Create the service principal for your account:
 +
 [source,terminal]
 ----
-$ az ad sp create-for-rbac --role Contributor --name <service_principal> <1>
+$ az ad sp create-for-rbac --role Contributor --name <service_principal> \ <1>
+  --scopes /subscriptions/<subscription_id> <2>
 ----
-<1> Replace `<service_principal>` with the name to assign to the service principal.
+<1> Specify the service principal name.
+<2> Specify the subscription ID.
 +
 .Example output
 [source,terminal]
 ----
-Changing "<service_principal>" to a valid URI of "http://<service_principal>", which is the required format used for service principal names
-Retrying role assignment creation: 1/36
-Retrying role assignment creation: 2/36
-Retrying role assignment creation: 3/36
-Retrying role assignment creation: 4/36
+Creating 'Contributor' role assignment under scope '/subscriptions/<subscription_id>'
+The output includes credentials that you must protect. Be sure that you do not 
+include these credentials in your code or check the credentials into your source 
+control. For more information, see https://aka.ms/azadsp-cli
 {
-  "appId": "8bd0d04d-0ac2-43a8-928d-705c598c6956",
-  "displayName": "<service_principal>",
-  "name": "http://<service_principal>",
-  "password": "ac461d78-bf4b-4387-ad16-7e32e328aec6",
-  "tenant": "6048c7e9-b2ad-488d-a54e-dc3f6be6a7ee"
+  "appId": "ac461d78-bf4b-4387-ad16-7e32e328aec6",
+  "displayName": <service_principal>",
+  "password": "00000000-0000-0000-0000-000000000000",
+  "tenantId": "8049c7e9-c3de-762d-a54e-dc3f6be6a7ee"
 }
 ----
 
 . Record the values of the `appId` and `password` parameters from the previous
 output. You need these values during {product-title} installation.
 
 ifndef::ash[]
-. Grant additional permissions to the service principal.
-+
---
-** You must always add the `Contributor` and `User Access Administrator` roles to the app registration service principal so the cluster can assign credentials for its components.
-** To operate the Cloud Credential Operator (CCO) in _mint mode_, the app registration service principal also requires the `Azure Active Directory Graph/Application.ReadWrite.OwnedBy` API permission.
-** To operate the CCO in _passthrough mode_, the app registration service principal does not require additional API permissions.
---
-+
-For more information about CCO modes, see "About the Cloud Credential Operator" in the "Managing cloud provider credentials" section of the _Authentication and authorization_ guide.
-+
-[NOTE]
-====
-If you limit the service principal scope of the {product-title} installation program to an already existing Azure resource group, you must ensure all other resources used by the installation program in your environment have the necessary permissions, such as the public DNS zone and virtual network. Destroying a cluster using the installation program deletes this resource group.
-====
-
-.. To assign the `User Access Administrator` role, run the following command:
+. Assign the `User Access Administrator` role by running the following command:
 +
 [source,terminal]
 ----
 $ az role assignment create --role "User Access Administrator" \
-    --assignee-object-id $(az ad sp list --filter "appId eq '<appId>'" \
-       | jq '.[0].id' -r) <1>
-----
-<1> Replace `<appId>` with the `appId` parameter value for your service principal.
-
-.. To assign the `Azure Active Directory Graph` permission, run the following
-command:
-+
-[source,terminal]
-----
-$ az ad app permission add --id <appId> \ <1>
-     --api 00000002-0000-0000-c000-000000000000 \
-     --api-permissions 824c81eb-e3f8-4ee6-8f6d-de7f50d565b7=Role
-----
-<1> Replace `<appId>` with the `appId` parameter value for your service principal.
-+
-.Example output
-[source,terminal]
-----
-Invoking "az ad app permission grant --id 46d33abc-b8a3-46d8-8c84-f0fd58177435 --api 00000002-0000-0000-c000-000000000000" is needed to make the change effective
-----
-+
-For more information about the specific permissions that you grant with this
-command, see the
-link:https://blogs.msdn.microsoft.com/aaddevsup/2018/06/06/guid-table-for-windows-azure-active-directory-permissions/[GUID Table for Windows Azure Active Directory Permissions].
-.. Approve the permissions request. If your account does not have the
-Azure Active Directory tenant administrator role, follow the guidelines for
-your organization to request that the tenant administrator approve your
-permissions request.
-+
-[source, terminal]
-----
-$ az ad app permission grant --id <appId> \ <1>
-     --api 00000002-0000-0000-c000-000000000000
+  --assignee-object-id $(az ad sp show --id <appId> --query id -o tsv) <1>
 ----
-<1> Replace `<appId>` with the `appId` parameter value for your service principal.
+<1> Specify the `appId` parameter value for your service principal.
 endif::ash[]
 
 ifeval::["{context}" == "installing-azure-stack-hub-user-infra"]