Merge pull request #115704 from mlearned/mdl-arc-k8s-round2-post-build

new edits per Tami's feedback

Author: v-shmck

articles/azure-arc/kubernetes/connect-cluster.md

@@ -65,7 +65,7 @@ az provider show -n Microsoft.Kubernetes -o table
 az provider show -n Microsoft.KubernetesConfiguration -o table
 ```
 
-## Install CLI extensions
+## Install Azure CLI extensions
 
 Install the `connectedk8s` extension, which helps you connect Kubernetes clusters to Azure:
 
@@ -199,7 +199,7 @@ Azure Arc enabled Kubernetes consists of a few agents (operators) that run in yo
 
 ## Delete a connected cluster
 
-You can delete a `Microsoft.Kubernetes/connectedcluster` resource using the CLI or Azure portal.
+You can delete a `Microsoft.Kubernetes/connectedcluster` resource using the Azure CLI or Azure portal.
 
 The Azure CLI command `az connectedk8s delete` removes the `Microsoft.Kubernetes/connectedCluster` resource in Azure. The Azure CLI deletes any associated `sourcecontrolconfiguration` resources in Azure. The Azure CLI uses helm uninstall to remove the agents in the cluster.
 

articles/azure-arc/kubernetes/create-onboarding-service-principal.md

@@ -15,12 +15,12 @@ keywords: "Kubernetes, Arc, Azure, containers"
 
 ## Overview
 
-When a cluster is onboarded to Azure, the agents running in your cluster must authenticate to Azure Resource Manager as part of registration. The `connectedk8s` CLI extension has automated Service Principal creation. However, there may be a few scenarios where the CLI automation does not work:
+When a cluster is onboarded to Azure, the agents running in your cluster must authenticate to Azure Resource Manager as part of registration. The `connectedk8s` Azure CLI extension has automated Service Principal creation. However, there may be a few scenarios where the CLI automation does not work:
 
 * Your organization generally restricts the creation of Service Principals
 * The user onboarding the cluster does not have sufficient permissions to create Service Principals
 
-Instead, let's create the Service Principal out of band, and then pass the principal to the CLI extension.
+Instead, let's create the Service Principal out of band, and then pass the principal to the Azure CLI extension.
 
 ## Create a new Service Principal
 
@@ -77,7 +77,7 @@ az role assignment create \
 }
 ```
 
-## Use Service Principal with CLI
+## Use Service Principal with the Azure CLI
 
 Reference the newly created Service Principal:
 

articles/azure-arc/kubernetes/deploy-azure-iot-edge-workloads.md

@@ -18,7 +18,7 @@ keywords: "Kubernetes, Arc, Azure, K8s, containers"
 
 Azure Arc and Azure IoT Edge complement each other's capabilities quite well. Azure Arc provides mechanisms for cluster operators to the configure the foundational components of a cluster as well as apply and enforce cluster policies. And IoT Edge allows application operators to remotely deploy and manage the workloads at scale with convenient cloud ingestion and bi-directional communication primitives. The diagram below illustrates this:
 
-![](./media/edge-arc.png)
+![IoT Arc configuration](./media/edge-arc.png)
 
 ## Pre-requisites
 
@@ -34,7 +34,7 @@ Azure Arc and Azure IoT Edge complement each other's capabilities quite well. Az
     $ kubectl create secret generic dcs --from-file=fully-qualified-path-to-values.yaml --namespace iotedge
     ```
 
-    >You can also set this up remotely using the [cluster config example](./use-gitops-connected-cluster.md).
+    You can also set this up remotely using the [cluster config example](./use-gitops-connected-cluster.md).
 
 ## Connect a cluster
 

articles/azure-arc/kubernetes/deploy-azure-monitor-for-containers.md

@@ -17,7 +17,7 @@ Onboard [Azure Monitor enabled containers](https://docs.microsoft.com/azure/azur
 
 ## Before you begin
 
-* Kubernetes versions: https://docs.microsoft.com/azure/aks/supported-kubernetes-versions
+* [Kubernetes versions](https://docs.microsoft.com/azure/aks/supported-kubernetes-versions)
 * Linux distros for the cluster (master & worker) nodes – Ubuntu (18.04 LTS and 16.04 LTS)
 * Minimum Contributor RBAC role permission on the Azure subscription of the Azure Arc enabled Kubernetes cluster
 * Fully Qualified Azure Resource ID of the Azure Arc enabled Kubernetes cluster
@@ -91,11 +91,11 @@ Refer to https://docs.microsoft.com/azure/azure-monitor/insights/container-insig
 
 ## User interface
 
-Navigate to  https://aka.ms/azmon-containers-azurearc to view the Onboarded Cluster
+Navigate to  https://aka.ms/azmon-containers-azurearc to view the Onboarded Cluster.
 
 ## Disable Monitoring
 
-If you would like to disable monitoring due to some reason, you can just simply delete the Azure Monitor for containers HELM chart to stop collecting and ingesting  monitoring  data to Azure Monitor for containers backend
+If you would like to disable monitoring due to some reason, you can just simply delete the Azure Monitor for containers HELM chart to stop collecting and ingesting  monitoring  data to Azure Monitor for containers backend.
 
 	```console
 	helm del azmon-containers-release-1

articles/azure-arc/kubernetes/media/edge-arc.png

@@ -13,9 +13,11 @@ keywords: "Kubernetes, Arc, Azure, containers"
 
 # Azure Arc enabled Kubernetes troubleshooting (Preview)
 
+This document provides some common troubleshooting scenarios with connectivity, permissions, and agents.
+
 ## General troubleshooting
 
-### az CLI setup
+### Azure CLI set up
 Before using az connectedk8s or az k8sconfiguration CLI commands, assure that az is set to work against the correct Azure subscription.
 
 ```console
@@ -65,7 +67,7 @@ Connecting clusters to Azure requires access to both an Azure subscription and `
 
 ### Insufficient cluster permissions
 
-If the provided kubeconfig file does not have sufficient permissions to install the Azure Arc agents, the CLI command will return an error attempting to call the Kubernetes API.
+If the provided kubeconfig file does not have sufficient permissions to install the Azure Arc agents, the Azure CLI command will return an error attempting to call the Kubernetes API.
 
 ```console
 $ az connectedk8s connect --resource-group AzureArc --name AzureArcCluster
@@ -80,7 +82,7 @@ Cluster owner should use a Kubernetes user with cluster administrator permission
 
 ### Installation timeouts
 
-Azure Arc agent installation requires running a set of containers on the target cluster. If the cluster is running over a slow internet connection the container image pull may take longer than the CLI timeouts.
+Azure Arc agent installation requires running a set of containers on the target cluster. If the cluster is running over a slow internet connection the container image pull may take longer than the Azure CLI timeouts.
 
 ```console
 $ az connectedk8s connect --resource-group AzureArc --name AzureArcCluster
@@ -195,9 +197,3 @@ metadata:
   resourceVersion: ""
   selfLink: ""
 ```
-
-### Source control configurations remain on my cluster
-
-## Next steps
-
-* [Use Azure Policy to govern cluster configuration](./use-azure-policy.md)

articles/azure-arc/kubernetes/troubleshooting.md

@@ -29,7 +29,7 @@ If you are using multiple Git repos as the sources of truth for each cluster (fo
 6. In the **Policy rule** edit box, copy/paste the contents of this [example policy definition](https://raw.githubusercontent.com/Azure/arc-k8s-demo/master/policy/Ensure-GitOps-configuration-for-Kubernetes-cluster.json).
 7. **Save**.
 
-Note that this step of creating a custom policy definition will not be needed once the work is completed to make this a built-in policy.
+This step for creating a custom policy definition will not be needed once the work is completed to make this a built-in policy.
 
 ## Create a policy assignment
 
@@ -40,12 +40,12 @@ Note that this step of creating a custom policy definition will not be needed on
 5. If you want to exclude any resources from the policy scope, then set **Exclusions**.
 6. Give the policy assignment a **Name** and **Description** that you can use to identify it easily.
 7. Ensure that **Policy enforcement** is set to *Enabled*.
-8. Click **Next**.
+8. Select **Next**.
 9. Set parameter values that will be used during the creation of the `sourceControlConfiguration`.
-10. Click **Next**.
+10. Select **Next**.
 11. Enable **Create a remediation task**.
 12. Assure that **Create a managed identity** is checked, and that the identity will have **Contributor** permissions.  See [this doc](https://docs.microsoft.com/azure/governance/policy/assign-policy-portal) and [the comment in this doc](https://docs.microsoft.com/azure/governance/policy/how-to/remediate-resources) for more information on the permissions you need.
-13. **Review + create**
+13. Select **Review + create**.
 
 After the policy assignment is created, for any new `connectedCluster` resource (or `managedCluster` resource with the GitOps agents installed) that is located within the scope of the assignment, the `sourceControlConfiguration` will be applied.  For existing clusters, you will need to manually run a remediation task.  It typically takes from 10-20 minutes for the policy assignment to take effect.
 

articles/azure-arc/kubernetes/use-azure-policy.md

@@ -13,8 +13,6 @@ keywords: "GitOps, Kubernetes, K8s, Azure, Arc, Azure Kubernetes Service, contai
 
 # Use GitOps for an Azure Arc-enabled  configuration (Preview)
 
-## Overview
-
 This architecture uses a GitOps workflow to configure the cluster and deploy applications. The configuration is described declaratively in .yaml files and stored in Git. An agent watches the Git repo for changes and applies them.  The same agent also periodically assures that the cluster state matches the state declared in the Git repo and returns the cluster to the desired state if any unmanaged changes have occurred.
 
 The connection between your cluster and one or more Git repositories is tracked in Azure Resource Manager as a `sourceControlConfiguration` extension resource. The `sourceControlConfiguration` resource properties represent where and how Kubernetes resources should flow from Git to your cluster. The `sourceControlConfiguration` data is stored encrypted at rest in a CosmosDb database to ensure data confidentiality.
@@ -33,14 +31,12 @@ This getting started guide will walk you through applying a set of configuration
 
 The example repository is structured around the persona of a cluster operator who would like to provision a few namespaces, deploy a common workload, and provide some team-specific configuration. Using this repository creates the following resources on your cluster:
 
-* **Namespaces:** `cluster-config`, `team-a`, `team-b`
-* **Deployment:** `cluster-config/azure-vote`
-* **ConfigMap:** `team-a/endpoints`
-
-### Notes
+**Namespaces:** `cluster-config`, `team-a`, `team-b`
+**Deployment:** `cluster-config/azure-vote`
+**ConfigMap:** `team-a/endpoints`
 
-* The `config-agent` polls Azure for new or updated `sourceControlConfiguration` every 30 seconds.  This is the maximum time it will take for the `config-agent` to pick up a new or updated configuration.
-* If you are associating a private repository, assure that you also complete the steps in [Apply configuration from a private git repository](https://github.com/Azure/azure-arc-kubernetes-preview/blob/master/docs/use-gitops-in-connected-cluster.md#apply-configuration-from-a-private-git-repository)
+The `config-agent` polls Azure for new or updated `sourceControlConfiguration` every 30 seconds.  This is the maximum time it will take for the `config-agent` to pick up a new or updated configuration.
+If you are associating a private repository, assure that you also complete the steps in [Apply configuration from a private git repository](https://github.com/Azure/azure-arc-kubernetes-preview/blob/master/docs/use-gitops-in-connected-cluster.md#apply-configuration-from-a-private-git-repository)
 
 ### Using Azure CLI
 
@@ -102,13 +98,13 @@ Here are the supported scenarios for the value of --repository-url parameter.
 | Scenario | Format | Description |
 | ------------- | ------------- | ------------- |
 | Private GitHub repo - SSH | [email protected]:username/repo | SSH keypair generated by Flux.  User must add the public key to the GitHub account as Deploy Key. |
-| Public GitHub repo | http://github.com/username/repo or git://github.com/username/repo   | Public Git repo  |
+| Public GitHub repo | `http://github.com/username/repo` or git://github.com/username/repo   | Public Git repo  |
 
 These scenarios are supported by Flux but not by sourceControlConfiguration yet. 
 
 | Scenario | Format | Description |
 | ------------- | ------------- | ------------- |
-| Private GitHub repo - HTTPS | https://github.com/username/repo | Flux does not generate SSH keypair.  [Instructions](https://docs.fluxcd.io/en/1.17.0/guides/use-git-https.html) |
+| Private GitHub repo - HTTPS | `https://github.com/username/repo` | Flux does not generate SSH keypair.  [Instructions](https://docs.fluxcd.io/en/1.17.0/guides/use-git-https.html) |
 | Private Git host | user@githost:path/to/repo | [Instructions](https://docs.fluxcd.io/en/1.18.0/guides/use-private-git-host.html) |
 | Private GitHub repo - SSH (bring your own key) | [email protected]:username/repo | [Use your own SSH keypair](https://docs.fluxcd.io/en/1.17.0/guides/provide-own-ssh-key.html) |
 
@@ -129,17 +125,17 @@ To customize the creation of configuration, here are a few additional parameters
 
 Options supported in  --operator-params
 
-| | Option | Description |
-| ------------- | ------------- | ------------- |
-| 1.  | --git-branch  | Branch of git repo to use for Kubernetes manifests. Default is 'master'. |
-| 2.  | --git-path  | Relative path within the Git repo for Flux to locate Kubernetes manifests. |
-| 3.  | --git-readonly | Git repo will be considered read-only; Flux will not attempt to write to it. |
-| 4.  | --manifest-generation  | If enabled, Flux will look for .flux.yaml and run Kustomize or other manifest generators. |
-| 5.  | --git-poll-interval  | Period at which to poll Git repo for new commits. Default is '5m' (5 minutes). |
-| 6.  | --sync-garbage-collection  | If enabled, Flux will delete resources that it created, but are no longer present in Git. |
-| 7.  | --git-label  | Label to keep track of sync progress, used to tag the Git branch.  Default is 'flux-sync'. |
-| 8.  | --git-user  | Username for git commit. |
-| 9.  | --git-email  | Email to use for git commit. |
+| Option | Description |
+| ------------- | ------------- |
+| --git-branch  | Branch of git repo to use for Kubernetes manifests. Default is 'master'. |
+| --git-path  | Relative path within the Git repo for Flux to locate Kubernetes manifests. |
+| --git-readonly | Git repo will be considered read-only; Flux will not attempt to write to it. |
+| --manifest-generation  | If enabled, Flux will look for .flux.yaml and run Kustomize or other manifest generators. |
+| --git-poll-interval  | Period at which to poll Git repo for new commits. Default is '5m' (5 minutes). |
+| --sync-garbage-collection  | If enabled, Flux will delete resources that it created, but are no longer present in Git. |
+| --git-label  | Label to keep track of sync progress, used to tag the Git branch.  Default is 'flux-sync'. |
+| --git-user  | Username for git commit. |
+| --git-email  | Email to use for git commit. |
 
 * If '--git-user' or '--git-email' are not set (which means that you don't want Flux to write to the repo), then --git-readonly will automatically be set (if you have not already set it).
 
@@ -292,7 +288,7 @@ kubectl -n itops get all
 
 ## Delete a configuration
 
-You can delete a `sourceControlConfiguration` using the CLI or Azure portal.  After you initiate the delete command, the `sourceControlConfiguration` resource will be deleted immediately in Azure, but it can take up to 1 hour for full deletion of the associated objects from the cluster (we have a backlog item to shorten this). If the `sourceControlConfiguration` was created with namespace scope, that namespace will not be deleted from the cluster (to avoid breaking any other resources that may have been created in that namespace).
+You can delete a `sourceControlConfiguration` using the Azure CLI or Azure portal.  After you initiate the delete command, the `sourceControlConfiguration` resource will be deleted immediately in Azure, but it can take up to 1 hour for full deletion of the associated objects from the cluster (we have a backlog item to shorten this). If the `sourceControlConfiguration` was created with namespace scope, that namespace will not be deleted from the cluster (to avoid breaking any other resources that may have been created in that namespace).
 
 Note that any changes to the cluster that were the result of deployments from the tracked git repo are not deleted when the `sourceControlConfiguration` is deleted.