update prereqs and formatting

JnHs · JnHs · commit d4c6dd508297 · 2022-02-16T11:10:49.000-08:00
diff --git a/articles/azure-arc/kubernetes/quickstart-connect-cluster.md b/articles/azure-arc/kubernetes/quickstart-connect-cluster.md
@@ -1,53 +1,61 @@
 ---
-title: 'Quickstart: Connect an existing Kubernetes cluster to Azure Arc'
-description: "In this quickstart, learn how to connect an Azure Arc-enabled Kubernetes cluster."
+title: Quickstart: Connect an existing Kubernetes cluster to Azure Arc
+description: In this quickstart, you learn how to connect an Azure Arc-enabled Kubernetes cluster.
 ms.service: azure-arc
 ms.topic: quickstart
-ms.date: 09/09/2021
+ms.date: 02/16/2022
 ms.custom: template-quickstart, mode-other, devx-track-azurecli 
 ms.devlang: azurecli
 keywords: "Kubernetes, Arc, Azure, cluster"
 ---
 
 # Quickstart: Connect an existing Kubernetes cluster to Azure Arc
 
-In this quickstart, you'll learn the benefits of Azure Arc-enabled Kubernetes and how to connect an existing Kubernetes cluster to Azure Arc. For a conceptual look at connecting clusters to Azure Arc, see the [Azure Arc-enabled Kubernetes Agent Architecture article](./conceptual-agent-overview.md).
+Get started with Azure Arc-enabled Kubernetes by using Azure CLI or Azure PowerShell to connect an existing Kubernetes cluster to Azure Arc.
 
-[!INCLUDE [quickstarts-free-trial-note](../../../includes/quickstarts-free-trial-note.md)]
+For a conceptual look at connecting clusters to Azure Arc, see [Azure Arc-enabled Kubernetes agent overview](./conceptual-agent-overview.md).
 
 ## Prerequisites
 
 ### [Azure CLI](#tab/azure-cli)
 
+* An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
+
+* A basic understanding of [Kubernetes core concepts](/azure/aks/concepts-clusters-workloads).
+
 * [Install or upgrade Azure CLI](/cli/azure/install-azure-cli) to version >= 2.16.0 and <= 2.29.0
 
 * Install the **connectedk8s** Azure CLI extension of version >= 1.2.0:
 
-  ```console
+  ```
   az extension add --name connectedk8s
   ```
 
 * [Log in to Azure CLI](/cli/azure/authenticate-azure-cli) using the identity (user or service principal) that you want to use for connecting your cluster to Azure Arc.
-    * The identity used needs to at least have 'Read' and 'Write' permissions on the Azure Arc-enabled Kubernetes resource type (`Microsoft.Kubernetes/connectedClusters`).
-    * The [Kubernetes Cluster - Azure Arc Onboarding built-in role](../../role-based-access-control/built-in-roles.md#kubernetes-cluster---azure-arc-onboarding) is useful for at-scale onboarding as it has the granular permissions required to only connect clusters to Azure Arc. This role doesn't have the permissions to update, delete, or modify any other clusters or other Azure resources.
+  * The identity used needs to at least have 'Read' and 'Write' permissions on the Azure Arc-enabled Kubernetes resource type (`Microsoft.Kubernetes/connectedClusters`).
+  * The [Kubernetes Cluster - Azure Arc Onboarding built-in role](../../role-based-access-control/built-in-roles.md#kubernetes-cluster---azure-arc-onboarding) is useful for at-scale onboarding as it has the granular permissions required to only connect clusters to Azure Arc. This role doesn't have the permissions to update, delete, or modify any other clusters or other Azure resources.
 
 * An up-and-running Kubernetes cluster. If you don't have one, you can create a cluster using one of these options:
-    * [Kubernetes in Docker (KIND)](https://kind.sigs.k8s.io/)
-    * Create a Kubernetes cluster using Docker for [Mac](https://docs.docker.com/docker-for-mac/#kubernetes) or [Windows](https://docs.docker.com/docker-for-windows/#kubernetes)
-    * Self-managed Kubernetes cluster using [Cluster API](https://cluster-api.sigs.k8s.io/user/quick-start.html)
-    * If you want to connect a OpenShift cluster to Azure Arc, you need to execute the following command just once on your cluster before running `az connectedk8s connect`:
+  * [Kubernetes in Docker (KIND)](https://kind.sigs.k8s.io/)
+  * Create a Kubernetes cluster using Docker for [Mac](https://docs.docker.com/docker-for-mac/#kubernetes) or [Windows](https://docs.docker.com/docker-for-windows/#kubernetes)
+  * Self-managed Kubernetes cluster using [Cluster API](https://cluster-api.sigs.k8s.io/user/quick-start.html)
+  * If you want to connect a OpenShift cluster to Azure Arc, you need to execute the following command just once on your cluster before running `az connectedk8s connect`:
 
-        ```console
+        ```
         oc adm policy add-scc-to-user privileged system:serviceaccount:azure-arc:azure-arc-kube-aad-proxy-sa
         ```
 
     >[!NOTE]
     > The cluster needs to have at least one node of operating system and architecture type `linux/amd64`. Clusters with only `linux/arm64` nodes aren't yet supported.
 
-* A `kubeconfig` file and context pointing to your cluster.
+* A [kubeconfig file](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) and context pointing to your cluster.
 
 ### [Azure PowerShell](#tab/azure-powershell)
 
+* An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
+
+* A basic understanding of [Kubernetes core concepts](/azure/aks/concepts-clusters-workloads).
+
 * [Azure PowerShell version 5.9.0 or later](/powershell/azure/install-az-ps)
 
 * Install the **Az.ConnectedKubernetes** PowerShell module:
@@ -61,23 +69,23 @@ In this quickstart, you'll learn the benefits of Azure Arc-enabled Kubernetes an
     > the `Install-Module` cmdlet.
 
 * [Log in to Azure PowerShell](/powershell/azure/authenticate-azureps) using the identity (user or service principal) that you want to use for connecting your cluster to Azure Arc.
-    * The identity used needs to at least have 'Read' and 'Write' permissions on the Azure Arc-enabled Kubernetes resource type (`Microsoft.Kubernetes/connectedClusters`).
-    * The [Kubernetes Cluster - Azure Arc Onboarding built-in role](../../role-based-access-control/built-in-roles.md#kubernetes-cluster---azure-arc-onboarding) is useful for at-scale onboarding as it has the granular permissions required to only connect clusters to Azure Arc. This role doesn't have the permissions to update, delete, or modify any other clusters or other Azure resources.
+  * The identity used needs to at least have 'Read' and 'Write' permissions on the Azure Arc-enabled Kubernetes resource type (`Microsoft.Kubernetes/connectedClusters`).
+  * The [Kubernetes Cluster - Azure Arc Onboarding built-in role](../../role-based-access-control/built-in-roles.md#kubernetes-cluster---azure-arc-onboarding) is useful for at-scale onboarding as it has the granular permissions required to only connect clusters to Azure Arc. This role doesn't have the permissions to update, delete, or modify any other clusters or other Azure resources.
 
 * An up-and-running Kubernetes cluster. If you don't have one, you can create a cluster using one of these options:
-    * [Kubernetes in Docker (KIND)](https://kind.sigs.k8s.io/)
-    * Create a Kubernetes cluster using Docker for [Mac](https://docs.docker.com/docker-for-mac/#kubernetes) or [Windows](https://docs.docker.com/docker-for-windows/#kubernetes)
-    * Self-managed Kubernetes cluster using [Cluster API](https://cluster-api.sigs.k8s.io/user/quick-start.html)
-    * If you want to connect a OpenShift cluster to Azure Arc, you need to execute the following command just once on your cluster before running `New-AzConnectedKubernetes`:
+  * [Kubernetes in Docker (KIND)](https://kind.sigs.k8s.io/)
+  * Create a Kubernetes cluster using Docker for [Mac](https://docs.docker.com/docker-for-mac/#kubernetes) or [Windows](https://docs.docker.com/docker-for-windows/#kubernetes)
+  * Self-managed Kubernetes cluster using [Cluster API](https://cluster-api.sigs.k8s.io/user/quick-start.html)
+  * If you want to connect a OpenShift cluster to Azure Arc, you need to execute the following command just once on your cluster before running `New-AzConnectedKubernetes`:
 
-        ```console
+        ```
         oc adm policy add-scc-to-user privileged system:serviceaccount:azure-arc:azure-arc-kube-aad-proxy-sa
         ```
 
     >[!NOTE]
     > The cluster needs to have at least one node of operating system and architecture type `linux/amd64`. Clusters with only `linux/arm64` nodes aren't yet supported.
 
-* A `kubeconfig` file and context pointing to your cluster.
+* A [kubeconfig file](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) and context pointing to your cluster.
 
 * Install [Helm 3](https://helm.sh/docs/intro/install). Ensure that the Helm 3 version is &lt; 3.7.0.
 
@@ -100,17 +108,20 @@ In this quickstart, you'll learn the benefits of Azure Arc-enabled Kubernetes an
 |`*.servicebus.windows.net`, `guestnotificationservice.azure.com`, `*.guestnotificationservice.azure.com`, `sts.windows.net` | For [Cluster Connect](cluster-connect.md) and for [Custom Location](custom-locations.md) based scenarios. |
 |`https://k8connecthelm.azureedge.net` | `az connectedk8s connect` uses Helm 3 to deploy Azure Arc agents on the Kubernetes cluster. This endpoint is needed for Helm client download to facilitate deployment of the agent helm chart. |
 
-## 1. Register providers for Azure Arc-enabled Kubernetes
+## Register providers for Azure Arc-enabled Kubernetes
 
 ### [Azure CLI](#tab/azure-cli)
 
 1. Enter the following commands:
+
     ```azurecli
     az provider register --namespace Microsoft.Kubernetes
     az provider register --namespace Microsoft.KubernetesConfiguration
     az provider register --namespace Microsoft.ExtendedLocation
     ```
-2. Monitor the registration process. Registration may take up to 10 minutes.
+
+1. Monitor the registration process. Registration may take up to 10 minutes.
+
     ```azurecli
     az provider show -n Microsoft.Kubernetes -o table
     az provider show -n Microsoft.KubernetesConfiguration -o table
@@ -122,22 +133,24 @@ In this quickstart, you'll learn the benefits of Azure Arc-enabled Kubernetes an
 ### [Azure PowerShell](#tab/azure-powershell)
 
 1. Enter the following commands:
+
     ```azurepowershell
     Register-AzResourceProvider -ProviderNamespace Microsoft.Kubernetes
     Register-AzResourceProvider -ProviderNamespace Microsoft.KubernetesConfiguration
     Register-AzResourceProvider -ProviderNamespace Microsoft.ExtendedLocation
     ```
+
 1. Monitor the registration process. Registration may take up to 10 minutes.
+
     ```azurepowershell
     Get-AzResourceProvider -ProviderNamespace Microsoft.Kubernetes
     Get-AzResourceProvider -ProviderNamespace Microsoft.KubernetesConfiguration
     Get-AzResourceProvider -ProviderNamespace Microsoft.ExtendedLocation
     ```
 
     Once registered, you should see the `RegistrationState` state for these namespaces change to `Registered`.
----
 
-## 2. Create a resource group
+## Create a resource group
 
 Run the following command:
 
@@ -171,7 +184,7 @@ ResourceId        : /subscriptions/00000000-0000-0000-0000-000000000000/resource
 
 ---
 
-## 3. Connect an existing Kubernetes cluster
+## Connect an existing Kubernetes cluster
 
 Run the following command:
 
@@ -182,10 +195,11 @@ az connectedk8s connect --name AzureArcTest1 --resource-group AzureArcTest
 ```
 
 > [!NOTE]
-> If you are logged into Azure CLI using a service principal, an [additional parameter](troubleshooting.md#enable-custom-locations-using-service-principal) needs to be set for enabling the custom location feature on the cluster.
+> If you are logged into Azure CLI using a service principal, an [additional parameter](troubleshooting.md#enable-custom-locations-using-service-principal) needs to be set to enable the custom location feature on the cluster.
 
 Output:
-<pre>
+
+```
 Helm release deployment succeeded
 
     {
@@ -218,7 +232,7 @@ Helm release deployment succeeded
       "totalNodeCount": null,
       "type": "Microsoft.Kubernetes/connectedClusters"
     }
-</pre>
+```
 
 > [!TIP]
 > The above command without the location parameter specified creates the Azure Arc-enabled Kubernetes resource in the same location as the resource group. To create the Azure Arc-enabled Kubernetes resource in a different location, specify either `--location <region>` or `-l <region>` when running the `az connectedk8s connect` command.
@@ -230,20 +244,19 @@ New-AzConnectedKubernetes -ClusterName AzureArcTest1 -ResourceGroupName AzureArc
 ```
 
 Output:
-<pre>
+
+```
 Location Name          Type
 -------- ----          ----
 eastus   AzureArcTest1 microsoft.kubernetes/connectedclusters
-</pre>
+```
 
----
+## Connect using an outbound proxy server
 
-## 4a. Connect using an outbound proxy server
+If your cluster is behind an outbound proxy server, requests must be routed via the outbound proxy server.
 
 ### [Azure CLI](#tab/azure-cli)
 
-If your cluster is behind an outbound proxy server, Azure CLI and the Azure Arc-enabled Kubernetes agents need to route their requests via the outbound proxy server.
-
 1. Set the environment variables needed for Azure CLI to use the outbound proxy server:
 
     ```bash
@@ -258,15 +271,14 @@ If your cluster is behind an outbound proxy server, Azure CLI and the Azure Arc-
     az connectedk8s connect --name <cluster-name> --resource-group <resource-group> --proxy-https https://<proxy-server-ip-address>:<port> --proxy-http http://<proxy-server-ip-address>:<port> --proxy-skip-range <excludedIP>,<excludedCIDR> --proxy-cert <path-to-cert-file>
     ```
 
-    > [!NOTE]
-    > * Some network requests such as the ones involving in-cluster service-to-service communication need to be separated from the traffic that is routed via the proxy server for outbound communication. The `--proxy-skip-range` parameter can be used to specify the CIDR range and endpoints in a comma-separated way so that any communication from the agents to these endpoints do not go via the outbound proxy. At a minimum, the CIDR range of the services in the cluster should be specified as value for this parameter. For example, let's say `kubectl get svc -A` returns a list of services where all the services have ClusterIP values in the range `10.0.0.0/16`. Then the value to specify for `--proxy-skip-range` is `10.0.0.0/16,kubernetes.default.svc,.svc.cluster.local,.svc`.
-    > * `--proxy-http`, `--proxy-https`, and `--proxy-skip-range` are expected for most outbound proxy environments. `--proxy-cert` is *only* required if you need to inject trusted certificates expected by proxy into the trusted certificate store of agent pods.
-    > * The outbound proxy has to be configured to allow websocket connections.
+> [!NOTE]
+>
+> * Some network requests such as the ones involving in-cluster service-to-service communication need to be separated from the traffic that is routed via the proxy server for outbound communication. The `--proxy-skip-range` parameter can be used to specify the CIDR range and endpoints in a comma-separated way so that any communication from the agents to these endpoints do not go via the outbound proxy. At a minimum, the CIDR range of the services in the cluster should be specified as value for this parameter. For example, let's say `kubectl get svc -A` returns a list of services where all the services have ClusterIP values in the range `10.0.0.0/16`. Then the value to specify for `--proxy-skip-range` is `10.0.0.0/16,kubernetes.default.svc,.svc.cluster.local,.svc`.
+> * `--proxy-http`, `--proxy-https`, and `--proxy-skip-range` are expected for most outbound proxy environments. `--proxy-cert` is *only* required if you need to inject trusted certificates expected by proxy into the trusted certificate store of agent pods.
+> * The outbound proxy has to be configured to allow websocket connections.
 
 ### [Azure PowerShell](#tab/azure-powershell)
 
-If your cluster is behind an outbound proxy server, Azure PowerShell and the Azure Arc-enabled Kubernetes agents need to route their requests via the outbound proxy server.
-
 1. Set the environment variables needed for Azure PowerShell to use the outbound proxy server:
 
     ```powershell
@@ -281,9 +293,7 @@ If your cluster is behind an outbound proxy server, Azure PowerShell and the Azu
     New-AzConnectedKubernetes -ClusterName <cluster-name> -ResourceGroupName <resource-group> -Location eastus -Proxy 'https://<proxy-server-ip-address>:<port>'
     ```
 
----
-
-## 5. Verify cluster connection
+## Verify cluster connection
 
 Run the following command:
 
@@ -294,11 +304,12 @@ az connectedk8s list --resource-group AzureArcTest --output table
 ```
 
 Output:
-<pre>
+
+```
 Name           Location    ResourceGroup
 -------------  ----------  ---------------
 AzureArcTest1  eastus      AzureArcTest
-</pre>
+```
 
 ### [Azure PowerShell](#tab/azure-powershell)
 
@@ -307,32 +318,31 @@ Get-AzConnectedKubernetes -ResourceGroupName AzureArcTest
 ```
 
 Output:
-<pre>
+
+```
 Location Name          Type
 -------- ----          ----
 eastus   AzureArcTest1 microsoft.kubernetes/connectedclusters
-</pre>
-
----
+```
 
 > [!NOTE]
 > After onboarding the cluster, it takes around 5 to 10 minutes for the cluster metadata (cluster version, agent version, number of nodes, etc.) to surface on the overview page of the Azure Arc-enabled Kubernetes resource in Azure portal.
 
 ## 6. View Azure Arc agents for Kubernetes
 
-Azure Arc-enabled Kubernetes deploys a few operators into the `azure-arc` namespace.
+Azure Arc-enabled Kubernetes deploys a few agents into the `azure-arc` namespace.
 
 1. View these deployments and pods using:
 
-    ```console
-    kubectl get deployments,pods -n azure-arc
-    ```
+  ```
+  kubectl get deployments,pods -n azure-arc
+  ```
 
 1. Verify all pods are in a `Running` state.
 
-    Output:
-    <pre>
+  Output:
 
+  ```
     NAME                                        READY   UP-TO-DATE   AVAILABLE   AGE
     deployment.apps/cluster-metadata-operator   1/1     1            1           13d
     deployment.apps/clusterconnect-agent        1/1     1            1           13d
@@ -356,11 +366,11 @@ Azure Arc-enabled Kubernetes deploys a few operators into the `azure-arc` namesp
     pod/kube-aad-proxy-67b87b9f55-bthqv             2/2     Running   0          13d
     pod/metrics-agent-575c565fd9-k5j2t              2/2     Running   0          13d
     pod/resource-sync-agent-6bbd8bcd86-x5bk5        2/2     Running   0          13d
-    </pre>
+  ```
 
-A conceptual overview of these agents is available [here](conceptual-agent-overview.md).
+For more information about these agents, see [Azure Arc-enabled Kubernetes agent overview](conceptual-agent-overview.md).
 
-## 7. Clean up resources
+## Clean up resources
 
 ### [Azure CLI](#tab/azure-cli)
 
@@ -371,7 +381,7 @@ az connectedk8s delete --name AzureArcTest1 --resource-group AzureArcTest
 ```
 
 >[!NOTE]
-> Deleting the Azure Arc-enabled Kubernetes resource using Azure portal removes any associated configuration resources, but *does not* remove any agents running on the cluster. Best practice is to delete the Azure Arc-enabled Kubernetes resource using `az connectedk8s delete` instead of Azure portal.
+> Deleting the Azure Arc-enabled Kubernetes resource using the Azure portal removes any associated configuration resources, but *does not* remove any agents running on the cluster. Best practice is to delete the Azure Arc-enabled Kubernetes resource using `az connectedk8s delete` rather than deleting the resource in the Azure portal.
 
 ### [Azure PowerShell](#tab/azure-powershell)
 
@@ -382,9 +392,7 @@ Remove-AzConnectedKubernetes -ClusterName AzureArcTest1 -ResourceGroupName Azure
 ```
 
 >[!NOTE]
-> Deleting the Azure Arc-enabled Kubernetes resource using Azure portal removes any associated configuration resources, but *does not* remove any agents running on the cluster. Best practice is to delete the Azure Arc-enabled Kubernetes resource using `Remove-AzConnectedKubernetes` instead of Azure portal.
-
----
+> Deleting the Azure Arc-enabled Kubernetes resource using the Azure portal removes any associated configuration resources, but *does not* remove any agents running on the cluster. Best practice is to delete the Azure Arc-enabled Kubernetes resource using `Remove-AzConnectedKubernetes` rather than deleting the resource in the Azure portal.
 
 ## Next steps
 
