Merge pull request #227346 from johnmarco/jm-cluster-domain-name-update

Add domain requirements to cluster articles

Author: prmerger-automator[bot]

articles/openshift/quickstart-openshift-arm-bicep-template.md

@@ -6,7 +6,7 @@ ms.service: azure-redhat-openshift
 ms.topic: quickstart
 ms.custom: mode-arm
 ms.author: johnmarc
-ms.date: 03/17/2022
+ms.date: 02/15/2023
 keywords: azure, openshift, aro, red hat, arm, bicep
 #Customer intent: I need to use ARM templates or Bicep files to deploy my Azure Red Hat OpenShift cluster.
 zone_pivot_groups: azure-red-hat-openshift
@@ -575,6 +575,9 @@ This section provides information on deploying the azuredeploy.json template.
 
 The azuredeploy.json template is used to deploy an Azure Red Hat OpenShift cluster. The following  parameters are required.
 
+> [!NOTE]
+> For the `domain` parameter, specify the domain prefix that will be used as part of the auto-generated DNS name for OpenShift console and API servers. This prefix is also used as part of the name of the resource group that is created to host the cluster VMs.
+
 | Property | Description | Valid Options | Default Value |
 |----------|-------------|---------------|---------------|
 | `domain` |The domain prefix for the cluster. | | none |

articles/openshift/quickstart-portal.md

@@ -5,7 +5,7 @@ author: johnmarco
 ms.author: johnmarc
 ms.service: azure-redhat-openshift
 ms.topic: quickstart
-ms.date: 11/30/2021
+ms.date: 02/14/2023
 ms.custom: mode-ui
 ---
 
@@ -32,6 +32,9 @@ Create a service principal, as explained in [Use the portal to create an Azure A
         *	Select **Master VM Size** and **Worker VM Size**.
 
     ![**Basics** tab on Azure portal](./media/Basics.png)
+    
+    > [!NOTE]
+    > In the **Domain name** field, you can either specify a domain name (e.g., *example.com*) or a prefix (e.g., *abc*) that will be used as part of the auto-generated DNS name for OpenShift console and API servers. This prefix is also used as part of the name of the resource group (e.g., *aro-abc*) that is created to host the cluster VMs.
 
 4. On the **Authentication** tab of the **Azure Red Hat OpenShift** dialog, complete the following sections.
 

articles/openshift/tutorial-create-cluster.md

@@ -11,7 +11,7 @@ ms.date: 10/26/2020
 
 # Tutorial: Create an Azure Red Hat OpenShift 4 cluster
 
-In this tutorial, part one of three, you'll prepare your environment to create an Azure Red Hat OpenShift cluster running OpenShift 4, and create a cluster. You'll learn how to:
+In this tutorial, part one of three, you prepare your environment to create an Azure Red Hat OpenShift cluster running OpenShift 4, and create a cluster. You learn how to:
 > [!div class="checklist"]
 > * Setup the prerequisites 
 > * Create the required virtual network and subnets
@@ -21,9 +21,9 @@ In this tutorial, part one of three, you'll prepare your environment to create a
 
 If you choose to install and use the CLI locally, this tutorial requires that you're running the Azure CLI version 2.30.0 or later. Run `az --version` to find the version. If you need to install or upgrade, see [Install Azure CLI](/cli/azure/install-azure-cli).
 
-Azure Red Hat OpenShift requires a minimum of 40 cores to create and run an OpenShift cluster. The default Azure resource quota for a new Azure subscription does not meet this requirement. To request an increase in your resource limit, see [Standard quota: Increase limits by VM series](../azure-portal/supportability/per-vm-quota-requests.md).
+Azure Red Hat OpenShift requires a minimum of 40 cores to create and run an OpenShift cluster. The default Azure resource quota for a new Azure subscription doesn't meet this requirement. To request an increase in your resource limit, see [Standard quota: Increase limits by VM series](../azure-portal/supportability/per-vm-quota-requests.md).
 
-* For example to check the current subscription quota of the smallest supported virtual machine family SKU "Standard DSv3":
+* For example, to check the current subscription quota of the smallest supported virtual machine family SKU "Standard DSv3":
 
     ```azurecli-interactive
     LOCATION=eastus
@@ -34,9 +34,9 @@ Azure Red Hat OpenShift requires a minimum of 40 cores to create and run an Open
 
 ### Verify your permissions
 
-During this tutorial, you will create a resource group, which will contain the virtual network for the cluster. You must have either Contributor and User Access Administrator permissions, or Owner permissions, either directly on the virtual network, or on the resource group or subscription containing it.
+During this tutorial, you'll create a resource group, which contains the virtual network for the cluster. To do this, you'll need Contributor and User Access Administrator permissions or Owner permissions, either directly on the virtual network or on the resource group or subscription containing it.
 
-You will also need sufficient Azure Active Directory permissions (either a member user of the tenant, or a guest user assigned with role **Application administrator**) for the tooling to create an application and service principal on your behalf for the cluster. See [Member and guest users](../active-directory/fundamentals/users-default-permissions.md#member-and-guest-users) and [Assign administrator and non-administrator roles to users with Azure Active Directory](../active-directory/fundamentals/active-directory-users-assign-role-azure-portal.md) for more details.
+You'll also need sufficient Azure Active Directory permissions (either a member user of the tenant, or a guest assigned with role **Application administrator**) for the tooling to create an application and service principal on your behalf for the cluster. See [Member and guests](../active-directory/fundamentals/users-default-permissions.md#member-and-guest-users) and [Assign administrator and non-administrator roles to users with Azure Active Directory](../active-directory/fundamentals/active-directory-users-assign-role-azure-portal.md) for more details.
 
 ### Register the resource providers
 
@@ -74,29 +74,32 @@ You will also need sufficient Azure Active Directory permissions (either a membe
 ### Get a Red Hat pull secret (optional)
 
    > [!NOTE] 
-   > ARO pull secret does not change the cost of the RH OpenShift license for ARO.
+   > ARO pull secret doesn't change the cost of the RH OpenShift license for ARO.
 
-A Red Hat pull secret enables your cluster to access Red Hat container registries along with additional content. This step is optional but recommended. Please note that the field `cloud.openshift.com` will be removed from your secret even if your pull-secret contains that field. This field enables an extra monitoring feature which sends data to RedHat and is thus disabled by default. To enable this feature, see https://docs.openshift.com/container-platform/4.11/support/remote_health_monitoring/enabling-remote-health-reporting.html . 
+A Red Hat pull secret enables your cluster to access Red Hat container registries along with other content. This step is optional but recommended. The field `cloud.openshift.com` is removed from your secret even if your pull-secret contains that field. This field enables an extra monitoring feature, which sends data to RedHat and is thus disabled by default. To enable this feature, see https://docs.openshift.com/container-platform/4.11/support/remote_health_monitoring/enabling-remote-health-reporting.html . 
 
-1. [Navigate to your Red Hat OpenShift cluster manager portal](https://console.redhat.com/openshift/install/azure/aro-provisioned) and log in.
+1. [Navigate to your Red Hat OpenShift cluster manager portal](https://console.redhat.com/openshift/install/azure/aro-provisioned) and sign-in.
 
-   You will need to log in to your Red Hat account or create a new Red Hat account with your business email and accept the terms and conditions.
+   You'll need to log in to your Red Hat account or create a new Red Hat account with your business email and accept the terms and conditions.
 
-1. Click **Download pull secret** and download a pull secret to be used with your ARO cluster.
+1. Select **Download pull secret** and download a pull secret to be used with your ARO cluster.
 
     Keep the saved `pull-secret.txt` file somewhere safe. The file will be used in each cluster creation if you need to create a cluster that includes samples or operators for Red Hat or certified partners.
 
     When running the `az aro create` command, you can reference your pull secret using the `--pull-secret @pull-secret.txt` parameter. Execute `az aro create` from the directory where you stored your `pull-secret.txt` file. Otherwise, replace `@pull-secret.txt` with `@/path/to/my/pull-secret.txt`.
 
-    If you are copying your pull secret or referencing it in other scripts, your pull secret should be formatted as a valid JSON string.
+    If you're copying your pull secret or referencing it in other scripts, your pull secret should be formatted as a valid JSON string.
 
 ### Prepare a custom domain for your cluster (optional)
 
 When running the `az aro create` command, you can specify a custom domain for your cluster by using the `--domain foo.example.com` parameter.
 
-If you provide a custom domain for your cluster note the following points:
+> [!NOTE]
+> Although adding a domain name is optional when creating a cluster through Azure CLI, a domain name (or a prefix used as part of the auto-generated DNS name for OpenShift console and API servers) is needed when adding a cluster through the portal. See [Quickstart: Deploy an Azure Red Hat OpenShift cluster using the Azure portal](quickstart-portal.md#create-an-azure-red-hat-openshift-cluster) for more information. 
+
+If you provide a custom domain for your cluster, note the following points:
 
-* After creating your cluster, you must create 2 DNS A records in your DNS server for the `--domain` specified:
+* After creating your cluster, you must create two DNS A records in your DNS server for the `--domain` specified:
     * **api** - pointing to the api server IP address
     * **\*.apps** - pointing to the ingress IP address
     * Retrieve these values by executing the following command after cluster creation: `az aro show -n -g --query '{api:apiserverProfile.ip, ingress:ingressProfiles[0].ip}'`.
@@ -107,7 +110,7 @@ If you provide a custom domain for your cluster note the following points:
 
 ### Create a virtual network containing two empty subnets
 
-Next, you will create a virtual network containing two empty subnets. If you have existing virtual network that meets your needs, you can skip this step.
+Next, you'll create a virtual network containing two empty subnets. If you have existing virtual network that meets your needs, you can skip this step.
 
 1. **Set the following variables in the shell environment in which you will execute the `az` commands.**
 
@@ -119,7 +122,7 @@ Next, you will create a virtual network containing two empty subnets. If you hav
 
 2. **Create a resource group.**
 
-   An Azure resource group is a logical group in which Azure resources are deployed and managed. When you create a resource group, you are asked to specify a location. This location is where resource group metadata is stored, and it is also where your resources run in Azure if you don't specify another region during resource creation. Create a resource group using the [az group create](/cli/azure/group#az-group-create) command.
+   An Azure resource group is a logical group in which Azure resources are deployed and managed. When you create a resource group, you're asked to specify a location. This location is where resource group metadata is stored, and it is also where your resources run in Azure if you don't specify another region during resource creation. Create a resource group using the [az group create](/cli/azure/group#az-group-create) command.
 
    > [!NOTE] 
    > Azure Red Hat OpenShift is not available in all regions where an Azure resource group can be created. See [Available regions](https://azure.microsoft.com/global-infrastructure/services/?products=openshift) for information on where Azure Red Hat OpenShift is supported.
@@ -203,7 +206,7 @@ Next, you will create a virtual network containing two empty subnets. If you hav
 ## Create the cluster
 
 Run the following command to create a cluster. If you choose to use either of the following options, modify the command accordingly:
-* Optionally, you can [pass your Red Hat pull secret](#get-a-red-hat-pull-secret-optional) which enables your cluster to access Red Hat container registries along with additional content. Add the `--pull-secret @pull-secret.txt` argument to your command.
+* Optionally, you can [pass your Red Hat pull secret](#get-a-red-hat-pull-secret-optional), which enables your cluster to access Red Hat container registries along with other content. Add the `--pull-secret @pull-secret.txt` argument to your command.
 * Optionally, you can [use a custom domain](#prepare-a-custom-domain-for-your-cluster-optional). Add the `--domain foo.example.com` argument to your command, replacing `foo.example.com` with your own custom domain.
 
 > [!NOTE]