style(azure-acs): you-ectomy

Author: slack

src/quickstart/provider/azure-acs/boot.md

@@ -2,16 +2,16 @@
 
 ## Prerequisites
 
-1. Azure Account - If you do not already have a Azure Cloud account, you can start a trial with $200 of free credit [here](https://azure.microsoft.com/en-us/free/). After completing sign up, you must add your billing information.
+1. Azure Account - An active Azure Cloud account is required for this quick start. Start a trial with $200 of free credit [here](https://azure.microsoft.com/en-us/free/). After completing trial sign up, a credit card for billing must be added, but will not be charged.
 2. Some form of *nix-based terminal - MacOS, Ubuntu, CentOS, Bash on Windows, etc
 <br>Where the following is present:
-3. Azure CLI - The Azure CLI (2.0) provides the `az` command and allows you to interact with Azure through the command line. Install the CLI by following the instructions on [GitHub for the Azure CLI](https://github.com/Azure/azure-cli).
+3. Azure CLI - The Azure CLI (2.0) provides the `az` command which drives Azure through the command line. Install the CLI by following the instructions on [GitHub for the Azure CLI](https://github.com/Azure/azure-cli).
 4. SSH Key - This is used to deploy the cluster. [This URL helps to create SSH keys compatible with Linux VMs on Azure](https://docs.microsoft.com/azure/virtual-machines/virtual-machines-linux-mac-create-ssh-keys)
 5. jq - to parse the JSON responses from the CLI. [jq download page](https://stedolan.github.io/jq/)
 
 ## Configure the Azure CLI
 
-After installing the CLI, log in to your Azure Account by typing `az login` and output would look similar to this:
+After installing the CLI, log in to an Azure Account by typing `az login`:
 ```
 $ az login
 To sign in, use a web browser to open the page https://aka.ms/devicelogin and enter the code F7DLMNOPE to authenticate.
@@ -31,15 +31,15 @@ To sign in, use a web browser to open the page https://aka.ms/devicelogin and en
 ]
 ```
 
-Replace the value of SUBSCRIPTION_ID with the desired subscription id where you want to deploy from the previous step.  We also set the active subscription to deploy to.
+The `id` field from the `az login` command is the Azure Subscription Id. This id will be used throughout the guide. As a matter of convenience, set an environment variable named `SUBSCRIPTION_ID` with the value of the id (e.g. 57849302-a9f0-4908-b300-31337a0fb205). Check the configuration by setting the active subscription with `az account set`:
 ```
-SUBSCRIPTION_ID=57849302-a9f0-4908-b300-31337a0fb205
+$ export SUBSCRIPTION_ID=57849302-a9f0-4908-b300-31337a0fb205
 $ az account set --subscription="${SUBSCRIPTION_ID}"
 ```
 
 ## Create an Azure Service Principle
 
-Next, create an Azure Service Principle that will be used to provision the ACS Kubernetes Cluster. Service Principles are entities that have permission to create resources on your behalf. New Service Principles must be given a unique name, a role, and an Azure subscription that the Service Principle may modify.
+Next, create an Azure Service Principle that will be used to provision the ACS Kubernetes Cluster. Service Principles are entities that have permission to create resources in an Azure Subscription. New Service Principles must be given a unique name, a role, and an Azure subscription that the Service Principle may modify.
 
 ```
 $ export SP_JSON=`az ad sp create-for-rbac -n="http://acsk8sdeis" --role="Contributor" --scopes="/subscriptions/${SUBSCRIPTION_ID}"`
@@ -59,20 +59,42 @@ This should display an output similar to this. `jq` has also automatically extra
 }
 ```
 
-## Create Your ACS Kubernetes Cluster
+## Create an ACS Kubernetes Cluster
 
-You can build the Kubernetes cluster on ACS using primarily the Azure Web Portal (UI) or entirely using the Azure command line (CLI).  Choose one of the two paths:
+Azure supports two methods to build an ACS Kubernetes cluster, through the Azure Web Portal (UI) or using the Azure command line (CLI).  Choose one of the two paths:
 
 ### Path 1: Azure 'az' CLI
 
-1. Create an empty Azure resource group to deploy your cluster. The location of the resource group value can be changed to any datacenter.  `az account list-locations` gives the name of all locations.
+Create an empty Azure resource group to hold the ACS Kubernetes cluster. The location of the resource group can be set to any available Azure datacenter. To see the possible locations use `az account list-locations`. Remember to reference the location by the `name` attribute:
+
+```
+  {
+    "displayName": "West Central US",
+    "id": "/subscriptions/57ac26cf-a9f0-4908-b300-9a4e9a0fb205/locations/westcentralus",
+    "latitude": "40.890",
+    "longitude": "-110.234",
+    "name": "westcentralus",
+    "subscriptionId": null
+  },
+  {
+    "displayName": "West US 2",
+    "id": "/subscriptions/57ac26cf-a9f0-4908-b300-9a4e9a0fb205/locations/westus2",
+    "latitude": "47.233",
+    "longitude": "-119.852",
+    "name": "westus2",
+    "subscriptionId": null
+  }
+]
+```
+
+Create an environment variable to hold the resource group name:
 
 ```
 $ export RG_NAME=myresourcegroup
 $ az resource group create --name "${RG_NAME}" --location southcentralus
 ```
 
-2. Execute the command to deploy the cluster. The dns-prefix and ssh-key-value must be replaced with your own values.
+Execute the command to deploy the cluster. The `dns-prefix` and `ssh-key-value` must be replaced with your own values.
 
 ```
 $ az acs create --resource-group="${RG_NAME}" --location="southcentralus" \
@@ -85,12 +107,11 @@ $ az acs create --resource-group="${RG_NAME}" --location="southcentralus" \
   --ssh-key-value @/home/myusername/.ssh/id_rsa.pub
 ```
 
-> Note: When this is successfully executed, you'll only see this to start: `waiting for AAD role to propogate.done`.  It will take a few minutes for the cluster to complete creation.
+> Note: When `az acs create` starts the only output will be `waiting for AAD role to propogate.done`. The provisioning process is running in the background, in a few minutes the `az` command should return with information about the deployment created behind the scenes.
 
-Finally you should see something like this:
 ```
 {
-  "id": "/subscriptions/ed7cedf5-fcd8-4a5d-9980-96d838f65ab8/resourceGroups/ascdeis/providers/Microsoft.Resources/deployments/azurecli1481240849.890798",
+  "id": "/subscriptions/ed7cedf5-fcd8-4a5d-9980-96d838f65ab8/resourceGroups/myresourcegroup/providers/Microsoft.Resources/deployments/azurecli1481240849.890798",
   "name": "azurecli1481240849.890798",
   "properties": {
     "correlationId": "61be22d1-28d8-466c-a2ba-7bc11c2a3578",
@@ -106,7 +127,7 @@ Finally you should see something like this:
         "namespace": "Microsoft.ContainerService",
  ...
   },
-  "resourceGroup": "ascdeis"
+  "resourceGroup": "myresourcegroup"
 }
 ```
 
@@ -120,15 +141,15 @@ Select "Resource Manager" for the deployment model:
 
 ![](images/step2.png)
 
-Provide basic settings for your Kubernetes cluster.
+Provide basic settings for the new ACS Kubernetes cluster.
 
 * User name: this is the unix user name that will be added to all master and worker nodes
 * SSH public key: provide a public key that will be associated with the user name specified above
-* Subscription: choose the Azure Subscription that will be charged for your compute resources
+* Subscription: choose the Azure Subscription that will be charged for the compute resources
 * Resource group: create a new resource group and give the group a unique name
-* Location: choose an Azure location for your cluster
+* Location: choose an Azure location for the cluster
 
-When you have filled out the information, click "Ok".
+When the required information is filled out, click "Ok".
 
 ![](images/step3.png)
 
@@ -139,15 +160,15 @@ The next step takes the Service Principle name and password generated using the
 
 ![](images/step4.png)
 
-Next, configure the number of worker nodes, the node size, and DNS prefix for your cluster.
+Next, configure the number of worker nodes, the node size, and DNS prefix for the cluster.
 
 Worker nodes should have at least 7GB of available RAM.
 
 Click "Ok" to continue.
 
 ![](images/step5.png)
 
-Review the cluster configuration and click "Ok". After clicking "Purchase" on the next screen you will be returned to the Azure Portal dashboard.
+Review the cluster configuration and click "Ok". After clicking "Purchase" on the next screen the browser will be returned to the Azure Portal dashboard.
 
 ![](images/step6.png)
 
@@ -157,7 +178,7 @@ The Kubernetes cluster will take a few minutes to complete provisioning and conf
 
 ![](images/step9.png)
 
-## Connect to your Kubernetes Cluster
+## Connect to the ACS Kubernetes Cluster
 
 Find the fully qualified domain name (FQDN) for the Kubernetes master:
 
@@ -171,7 +192,7 @@ $ az acs list
     },
 ```
 
-Download the Kubeconfig from the master to your local machine, make sure to use the right SSH identity and master FQDN:
+Download the Kubeconfig from the master to the local machine, make sure to use the right SSH identity and master FQDN:
 
 ```
 $ scp -i ~/.ssh/id_rsa k8sadmin@mydnsprefix.myregion.cloudapp.azure.com:.kube/config ~/.kube/k8sanddeis.config
@@ -187,7 +208,7 @@ Point `kubectl` at the kubernetes configuration file by setting the `KUBECONFIG`
 export KUBECONFIG=~/.kube/k8sanddeis.config
 ```
 
-Verify you can connect to your Kubernetes cluster by running `kubectl cluster-info`
+Verify connectivity to the new ACS Kubernetes cluster by running `kubectl cluster-info`
 
 ```
 $ kubectl cluster-info