Docs improvements (#3302)

docs/hugo/content/guide/authentication/credential-format.md

@@ -39,26 +39,11 @@ Set the following additional environment variables:
 ```bash
 export MI_RESOURCE_GROUP="my-rg"  # The resource group containing the managed identity that will be used by ASO
 export MI_NAME="my-mi"            # The name of the managed identity that will be used by ASO
-export APPLICATION_OBJECT_ID=$(az resource show --id /subscriptions/${AZURE_SUBSCRIPTION_ID}/resourceGroups/${MI_RESOURCE_GROUP}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/${MI_NAME} --query "properties.principalId" -o tsv | tr -d '[:space:]')
 ```
 
 Create the Federated Identity Credential registering your service account with AAD:
 ```bash
-cat <<EOF > body.json
-{
-  "name": "aso-federated-credential",
-  "type":"Microsoft.ManagedIdentity/userAssignedIdentities/federatedIdentityCredentials",
-  "properties": {
-    "issuer":"${SERVICE_ACCOUNT_ISSUER}",
-    "subject":"system:serviceaccount:azureserviceoperator-system:azureserviceoperator-default",
-    "audiences": [
-      "api://AzureADTokenExchange"
-    ]
-  }
-}
-EOF
-
-az rest --method put --url /subscriptions/${AZURE_SUBSCRIPTION_ID}/resourcegroups/${MI_RESOURCE_GROUP}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/${MI_NAME}/federatedIdentityCredentials/aso-federated-credential?api-version=2022-01-31-preview --body @body.json
+az identity federated-credential create --name aso-federated-credential --identity-name ${MI_NAME} --resource-group ${MI_RESOURCE_GROUP} --issuer ${SERVICE_ACCOUNT_ISSUER} --subject "system:serviceaccount:azureserviceoperator-system:azureserviceoperator-default" --audiences "api://AzureADTokenExchange"
 ```
 
 {{% /tab %}}

docs/hugo/content/guide/diagnosing-problems.md

@@ -36,6 +36,39 @@ aso-sample-rg   False     Info       Reconciling     The resource is in the proc
 ```
 if this isn't happening then check the [controller logs](#getting-aso-controller-pod-logs).
 
+### Resource stuck deleting 
+
+This presents slightly differently for different resources, some examples are:
+
+* [#2478](https://github.com/Azure/azure-service-operator/issues/2478)
+* [#2586](https://github.com/Azure/azure-service-operator/issues/2586)
+* [#2607](https://github.com/Azure/azure-service-operator/issues/2607)
+
+For example, you might see something like this:
+```
+deleting resource "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/dev-rg/providers/Microsoft.KeyVault/vaults/kvname/providers/Microsoft.Authorization/roleAssignments/kv-role-assignement3": DELETE https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/dev-rg/providers/Microsoft.KeyVault/vaults/kvname/providers/Microsoft.Authorization/roleAssignments/kv-role-assignement3
+--------------------------------------------------------------------------------
+RESPONSE 400: 400 Bad Request
+ERROR CODE: InvalidRoleAssignmentId
+--------------------------------------------------------------------------------
+{
+    "error": {
+        "code": "InvalidRoleAssignmentId",
+        message": "The role assignment ID 'kv-role-assignement3' is not valid. The role assignment ID must be a GUID."
+    }
+}
+--------------------------------------------------------------------------------
+```
+
+This can happen because the resource was created with an invalid name, and when ASO is trying to delete it,
+it cannot delete the resource because the name is invalid.
+
+_Usually_, ASO will prevent this situation from happening by blocking the original apply that attempts to create the resource, 
+but from time to time that protection may be imperfect.
+
+If you see this problem, the resource wasn't ever created successfully in Azure and so it is safe to instruct ASO to 
+skip deletion of the Azure resource. This can be done by adding the `serviceoperator.azure.com/reconcile-policy: skip` 
+annotation to the resource in your cluster.
 
 ## Getting ASO controller pod logs
 The last stop when investigating most issues is to look at the ASO pod logs. We expect that

docs/hugo/content/guide/frequently-asked-questions.md

@@ -179,3 +179,14 @@ reconcile-policy: skip on the old one, deleting it, and then creating the `RoleA
 allowing it to adopt the existing resource in Azure) you must manually specify the AzureName
 of the `RoleAssignment` as the original UUID. Otherwise, the UUID defaulting algorithm will choose a different UUID since
 the namespace has changed.
+
+### How can I import existing Azure resources into ASO?
+
+See [Annotations understood by the operator]({{< relref "annotations#serviceoperatorazurecomreconcile-policy" >}}) for
+details about how to control whether the operator modifies Azure resources or just watches them.
+
+There are a few options for importing resources into your cluster:
+* If you're looking to import a large number of Azure resources you can use [asoctl]( {{< relref "tools/asoctl" >}}).
+* If you're looking to import a small number of resources, you can also manually create the resources in your cluster 
+  yourself and apply them. As long as the resource name, type and subscription are the same as the existing Azure 
+  resource, ASO will automatically adopt the resource. Make sure to use the `reconcile-policy` you want.