Merge pull request #78670 from anarnold97/OADP-4454-Configuring-Azure

OADP-4454: Fixing configuration error in Azure installation docs

Author: stevsmit

modules/migration-configuring-azure.adoc

@@ -6,29 +6,44 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="migration-configuring-azure_{context}"]
-= Configuring Microsoft Azure
+= Configuring {azure-full}
 
 ifdef::installing-3-4,installing-mtc[]
-You configure a Microsoft Azure Blob storage container as a replication repository for the {mtc-full} ({mtc-short}).
+You configure a {azure-full} Blob storage container as a replication repository for the {mtc-full} ({mtc-short}).
 endif::[]
 ifdef::installing-oadp-azure[]
-You configure Microsoft Azure for the OpenShift API for Data Protection (OADP).
+You configure {azure-full} for {oadp-first}.
 endif::[]
 
 .Prerequisites
 
-* You must have the link:https://docs.microsoft.com/en-us/cli/azure/install-azure-cli[Azure CLI] installed.
+* You must have the link:https://docs.microsoft.com/en-us/cli/azure/install-azure-cli[{azure-short} CLI] installed.
 ifdef::installing-3-4,installing-mtc[]
 * The Azure Blob storage container must be accessible to the source and target clusters.
 * If you are using the snapshot copy method:
 ** The source and target clusters must be in the same region.
 ** The source and target clusters must have the same storage class.
 ** The storage class must be compatible with snapshots.
 endif::[]
+ifdef::installing-oadp-azure[]
+
+Tools that use {azure-short} services should always have restricted permissions to make sure that {azure-short} resources are safe. Therefore, instead of having applications sign in as a fully privileged user, {azure-short} offers service principals. An {azure-short} service principal is a name that can be used with applications, hosted services, or automated tools.
+
+This identity is used for access to resources.
 
+* Create a service principal
+* Sign in using a service principal and password
+* Sign in using a service principal and certificate
+* Manage service principal roles
+* Create an {azure-short} resource using a service principal
+* Reset service principal credentials
+
+For more details, see link:https://learn.microsoft.com/en-us/cli/azure/azure-cli-sp-tutorial-1?tabs=bash[Create an {azure-short} service principal with Azure CLI].
+endif::[]
+ifndef::installing-oadp-azure[]
 .Procedure
 
-. Log in to Azure:
+. Log in to {azure-short}:
 +
 [source,terminal]
 ----
@@ -42,7 +57,7 @@ $ az login
 $ AZURE_RESOURCE_GROUP=Velero_Backups
 ----
 
-. Create an Azure resource group:
+. Create an {azure-short} resource group:
 +
 [source,terminal]
 ----
@@ -57,7 +72,7 @@ $ az group create -n $AZURE_RESOURCE_GROUP --location CentralUS <1>
 $ AZURE_STORAGE_ACCOUNT_ID="velero$(uuidgen | cut -d '-' -f5 | tr '[A-Z]' '[a-z]')"
 ----
 
-. Create an Azure storage account:
+. Create an {azure-short} storage account:
 +
 [source,terminal]
 ----
@@ -92,14 +107,35 @@ $ az storage container create \
 +
 [source,terminal]
 ----
-$ AZURE_SUBSCRIPTION_ID=`az account list --query '[?isDefault].id' -o tsv` \
-  AZURE_TENANT_ID=`az account list --query '[?isDefault].tenantId' -o tsv` \
-  AZURE_CLIENT_SECRET=`az ad sp create-for-rbac --name "velero" \
-  --role "Contributor" --query 'password' -o tsv` \
-  AZURE_CLIENT_ID=`az ad sp list --display-name "velero" \
-  --query '[0].appId' -o tsv`
+$ AZURE_SUBSCRIPTION_ID=`az account list --query '[?isDefault].id' -o tsv`
+  AZURE_TENANT_ID=`az account list --query '[?isDefault].tenantId' -o tsv`
 ----
 
+. Create a service principal with the `Contributor` role, assigning a specific `--role` and `--scopes`:
++
+[source,terminal]
+----
+$ AZURE_CLIENT_SECRET=`az ad sp create-for-rbac --name "velero" \
+                                                --role "Contributor" \
+                                                --query 'password' -o tsv \
+                                                --scopes /subscriptions/$AZURE_SUBSCRIPTION_ID/resourceGroups/$AZURE_RESOURCE_GROUP`
+----
++
+The CLI generates a password for you. Ensure you capture the password.
+
+. After creating the service principal, obtain the client id.
++
+[source,terminal]
+----
+$ AZURE_CLIENT_ID=`az ad app credential list --id <your_app_id>`
+----
++
+[NOTE]
+====
+For this to be successful, you must know your {azure-short} application ID.
+====
+endif::[]
+ifndef::installing-oadp-azure[]
 . Save the service principal credentials in the `credentials-velero` file:
 +
 [source,terminal]
@@ -114,8 +150,9 @@ AZURE_CLOUD_NAME=AzurePublicCloud
 EOF
 ----
 +
-You use the `credentials-velero` file to add Azure as a replication repository.
-
+You use the `credentials-velero` file to add {azure-short} as a replication repository.
+endif::[]
+////
 ifdef::installing-oadp-azure[]
 . Obtain the storage account access key:
 +
@@ -165,5 +202,6 @@ EOF
 ----
 <1> Mandatory. You cannot back up internal images if the `credentials-velero` file contains only the service principal credentials.
 +
-You use the `credentials-velero` file to create a `Secret` object for Azure before you install the Data Protection Application.
+You use the `credentials-velero` file to create a `Secret` object for {azure-short} before you install the Data Protection Application.
 endif::[]
+////