OSDOCS#5384: Document the explicit list of required credential permissions for Azure

Author: xenolinux

installing/installing_azure/installing-azure-account.adoc

@@ -26,6 +26,8 @@ include::modules/installation-azure-increasing-limits.adoc[leveloffset=+1]
 
 include::modules/installation-azure-permissions.adoc[leveloffset=+1]
 
+include::modules/minimum-required-permissions-ipi-azure.adoc[leveloffset=+1]
+
 include::modules/installation-azure-service-principal.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
@@ -42,5 +44,4 @@ include::modules/installation-azure-regions.adoc[leveloffset=+1]
 * Install an {product-title} cluster on Azure. You can
 xref:../../installing/installing_azure/installing-azure-customizations.adoc#installing-azure-customizations[install a customized cluster]
 or
-xref:../../installing/installing_azure/installing-azure-default.adoc#installing-azure-default[quickly install a cluster]
-with default options.
+xref:../../installing/installing_azure/installing-azure-default.adoc#installing-azure-default[quickly install a cluster] with default options.

installing/installing_azure/installing-azure-user-infra.adoc

@@ -51,6 +51,7 @@ include::modules/installation-azure-increasing-limits.adoc[leveloffset=+2]
 include::modules/csr-management.adoc[leveloffset=+2]
 
 include::modules/installation-azure-permissions.adoc[leveloffset=+2]
+include::modules/minimum-required-permissions-upi-azure.adoc[leveloffset=+2]
 include::modules/installation-azure-service-principal.adoc[leveloffset=+2]
 
 [role="_additional-resources"]

modules/installation-azure-create-resource-group-and-identity.adoc

@@ -73,6 +73,17 @@ $ export RESOURCE_GROUP_ID=`az group show -g ${RESOURCE_GROUP} --query id --out
 ----
 $ az role assignment create --assignee "${PRINCIPAL_ID}" --role 'Contributor' --scope "${RESOURCE_GROUP_ID}"
 ----
++
+[NOTE]
+====
+If you want to assign a custom role with all the required permissions to the identity, run the following command:
+[source,terminal]
+----
+$ az role assignment create --assignee "${PRINCIPAL_ID}" --role <custom_role> \ <1>
+--scope "${RESOURCE_GROUP_ID}"
+----
+<1> Specifies the custom role name.
+====
 endif::azure[]
 
 ifeval::["{context}" == "installing-azure-user-infra"]

modules/installation-azure-finalizing-encryption.adoc

@@ -6,12 +6,30 @@
 // * installing/installing_azure/installing-azure-private.adoc
 // * installing/installing_azure/installing-azure-vnet.adoc
 
+
+ifeval::["{context}" == "installing-azure-customizations"]
+:azure-public:
+endif::[]
+ifeval::["{context}" == "installing-azure-government-region"]
+:azure-gov:
+endif::[]
+ifeval::["{context}" == "installing-azure-network-customizations"]
+:azure-public:
+endif::[]
+ifeval::["{context}" == "installing-azure-private"]
+:azure-public:
+endif::[]
+ifeval::["{context}" == "installing-azure-vnet"]
+:azure-public:
+endif::[]
+
 :_content-type: PROCEDURE
 [id="finalizing-encryption_{context}"]
 = Finalizing user-managed encryption after installation
 If you installed {product-title} using a user-managed encryption key, you can complete the installation by creating a new storage class and granting write permissions to the Azure cluster resource group.
 
 .Procedure
+
 . Obtain the identity of the cluster resource group used by the installer:
 .. If you specified an existing resource group in `install-config.yaml`, obtain its Azure identity by running the following command:
 +
@@ -63,6 +81,7 @@ $ az identity show -g <cluster_resource_group> \// <1>
 <1> Specifies the name of the cluster resource group created by the installation program.
 <2> Specifies the name of the cluster service principal created by the installation program.
 The identity is in the format of `12345678-1234-1234-1234-1234567890`.
+ifdef::azure-gov[]
 . Create a role assignment that grants the cluster service principal `Contributor` privileges to the disk encryption set by running the following command:
 +
 [source,terminal]
@@ -73,6 +92,20 @@ $ az role assignment create --assignee <cluster_service_principal_id> \// <1>
 ----
 <1> Specifies the ID of the cluster service principal obtained in the previous step.
 <2> Specifies the ID of the disk encryption set.
+endif::azure-gov[]
+ifdef::azure-public[]
+. Create a role assignment that grants the cluster service principal necessary privileges to the disk encryption set by running the following command:
++
+[source,terminal]
+----
+$ az role assignment create --assignee <cluster_service_principal_id> \// <1>
+     --role <privileged_role> \// <2>
+     --scope <disk_encryption_set_id> \// <3>
+----
+<1> Specifies the ID of the cluster service principal obtained in the previous step.
+<2> Specifies the Azure role name. You can use the `Contributor` role or a custom role with the necessary permissions.
+<3> Specifies the ID of the disk encryption set.
+endif::azure-public[]
 +
 . Create a storage class that uses the user-managed disk encryption set:
 .. Save the following storage class definition to a file, for example `storage-class-definition.yaml`:
@@ -102,3 +135,21 @@ volumeBindingMode: WaitForFirstConsumer
 $ oc create -f storage-class-definition.yaml
 ----
 . Select the `managed-premium` storage class when you create persistent volumes to use encrypted storage.
+
+
+
+ifeval::["{context}" == "installing-azure-customizations"]
+:!azure-public:
+endif::[]
+ifeval::["{context}" == "installing-azure-government-region"]
+:!azure-gov:
+endif::[]
+ifeval::["{context}" == "installing-azure-network-customizations"]
+:!azure-public:
+endif::[]
+ifeval::["{context}" == "installing-azure-private"]
+:!azure-public:
+endif::[]
+ifeval::["{context}" == "installing-azure-vnet"]
+:!azure-public:
+endif::[]

modules/installation-azure-permissions.adoc

@@ -11,6 +11,4 @@
 * `User Access Administrator`
 * `Owner`
 
-To set roles on the Azure portal, see the
-link:https://docs.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal[Manage access to Azure resources using RBAC and the Azure portal]
-in the Azure documentation.
+To set roles on the Azure portal, see the link:https://docs.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal[Manage access to Azure resources using RBAC and the Azure portal] in the Azure documentation.

modules/installation-azure-service-principal.adoc

@@ -11,6 +11,12 @@ endif::[]
 ifeval::["{context}" == "installing-azure-stack-hub-account"]
 :ash:
 endif::[]
+ifeval::["{context}" == "installing-azure-account"]
+:ipi:
+endif::[]
+ifeval::["{context}" == "installing-azure-user-infra"]
+:upi:
+endif::[]
 
 :_content-type: PROCEDURE
 [id="installation-azure-service-principal_{context}"]
@@ -22,6 +28,12 @@ Because {product-title} and its installation program create Microsoft Azure reso
 
 * Install or update the link:https://docs.microsoft.com/en-us/cli/azure/install-azure-cli-yum?view=azure-cli-latest[Azure CLI].
 * Your Azure account has the required roles for the subscription that you use.
+ifdef::ipi[]
+* If you want to use a custom role, you have created a link:https://learn.microsoft.com/en-us/azure/role-based-access-control/custom-roles[custom role] with the required permissions listed in the _Required Azure permissions for installer-provisioned infrastructure_ section.
+endif::ipi[]
+ifdef::upi[]
+* If you want to use a custom role, you have created a link:https://learn.microsoft.com/en-us/azure/role-based-access-control/custom-roles[custom role] with the required permissions listed in the _Required Azure permissions for user-provisioned infrastructure_ section.
+endif::upi[]
 
 .Procedure
 
@@ -167,6 +179,7 @@ endif::[]
 
 . Record the `tenantId` and `id` parameter values from the output. You need these values during the {product-title} installation.
 
+ifdef::ash[]
 . Create the service principal for your account:
 +
 [source,terminal]
@@ -181,6 +194,35 @@ $ az ad sp create-for-rbac --role Contributor --name <service_principal> \ <1>
 [source,terminal]
 ----
 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": "ac461d78-bf4b-4387-ad16-7e32e328aec6",
+  "displayName": <service_principal>",
+  "password": "00000000-0000-0000-0000-000000000000",
+  "tenantId": "8049c7e9-c3de-762d-a54e-dc3f6be6a7ee"
+}
+----
+endif::ash[]
+
+ifndef::ash[]
+. Create the service principal for your account:
++
+[source,terminal]
+----
+$ az ad sp create-for-rbac --role <role_name> \// <1>
+     --name <service_principal> \// <2>
+     --scopes /subscriptions/<subscription_id> <3>
+----
+<1> Defines the role name. You can use the `Contributor` role, or you can specify a custom role which contains the necessary permissions.
+<2> Defines the service principal name.
+<3> Specifies the subscription ID.
++
+.Example output
+[source,terminal]
+----
+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
@@ -191,12 +233,13 @@ control. For more information, see https://aka.ms/azadsp-cli
   "tenantId": "8049c7e9-c3de-762d-a54e-dc3f6be6a7ee"
 }
 ----
+endif::ash[]
 
 . Record the values of the `appId` and `password` parameters from the previous
 output. You need these values during {product-title} installation.
 
 ifndef::ash[]
-. Assign the `User Access Administrator` role by running the following command:
+. If you applied the `Contributor` role to your service principal, assign the `User Administrator Access` role by running the following command:
 +
 [source,terminal]
 ----
@@ -212,3 +255,9 @@ endif::[]
 ifeval::["{context}" == "installing-azure-stack-hub-account"]
 :!ash:
 endif::[]
+ifeval::["{context}" == "installing-azure-account"]
+:!ipi:
+endif::[]
+ifeval::["{context}" == "installing-azure-user-infra"]
+:!upi:
+endif::[]