Merge pull request #820 from mboersma/update-azure-docs

docs(quickstart): update Azure ACS installation steps

Author: mboersma

.gitignore

@@ -20,3 +20,5 @@ bower_components
 venv/
 
 _build/
+
+.DS_Store

mkdocs.yml

@@ -13,14 +13,14 @@ pages:
       - Boot: quickstart/provider/aws/boot.md
       - DNS: quickstart/provider/aws/dns.md
       - Install Workflow: quickstart/provider/aws/install-aws.md
-    - GKE:
-      - Boot: quickstart/provider/gke/boot.md
-      - DNS: quickstart/provider/gke/dns.md
-      - Install Workflow: quickstart/provider/gke/install-gke.md
     - Azure:
       - Boot: quickstart/provider/azure-acs/boot.md
       - DNS: quickstart/provider/azure-acs/dns.md
       - Install Workflow: quickstart/provider/azure-acs/install-azure-acs.md
+    - GKE:
+      - Boot: quickstart/provider/gke/boot.md
+      - DNS: quickstart/provider/gke/dns.md
+      - Install Workflow: quickstart/provider/gke/install-gke.md
     - Minikube:
       - Boot: quickstart/provider/minikube/boot.md
       - DNS: quickstart/provider/minikube/dns.md

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

@@ -1,64 +1,55 @@
-# Booting Azure Container Service
+# Booting Kubernetes on Azure Container Service
 
-## Prerequisites
+Azure Container Service (ACS) is an optimized container hosting solution that works
+with all the open source tools you know. Azure is great for Kubernetes and Deis Workflow.
 
-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.
+If you don't yet have a Microsoft Azure account, start a trial with $200 of free credit
+[here](https://azure.microsoft.com/en-us/free/).
 
-2. Some form of *nix-based terminal - MacOS, Ubuntu, CentOS, Bash on Windows, etc
-<br>Where the following is present:
+## Prerequisites
 
-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).
+1. You should be able to run the `az` command, which is used to provision resources in the Azure
+cloud. Either [install Azure CLI to your computer][] or open a [Cloud Shell][] by clicking
+this icon near the upper right of the [Azure Portal][]: ![Cloud Shell](images/cloudshell.png)
 
-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)
+1. You need an SSH key to deploy the Kubernetes cluster. For help, see Microsoft's documentation
+about [creating SSH key pairs][] for Linux VMs on Azure.
 
 ## Configure the Azure CLI
 
-After installing the CLI, log in to an Azure Account by typing `az login`. Take the code offered, enter it into the text box at [https://aka.ms/devicelogin](https://aka.ms/devicelogin), and login using an Azure account which has ownership or contributor permissions over at least one subscription.
+If you use [Cloud Shell][], the `az` client command is already configured.
 
-> Note: If the Azure subscription is configured for 2FA (not done by default), the Azure account used to login must have ownership credentials to create the service principal.
+If you installed `az` locally, log in to your Azure account by typing `az login` at a command
+prompt and complete the confirmation code process.
 
-```
-$ az login
-To sign in, use a web browser to open the page https://aka.ms/devicelogin and enter the code F7DLMNOPE to authenticate.
-[
-  {
-    "cloudName": "AzureCloud",
-    "id": "57849302-a9f0-4908-b300-31337a0fb205",
-    "isDefault": true,
-    "name": "Azure Subscription",
-    "state": "Enabled",
-    "tenantId": "591acccc-dddd-4620-8f21-dbbeeeefee21",
-    "user": {
-      "name": "jhansen@deis.com",
-      "type": "user"
-    }
-  }
-]
-```
+You can verify which account is active with the `az account show` command.
 
-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 `AZURE_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`:
-```
-$ export AZURE_SUBSCRIPTION_ID=57849302-a9f0-4908-b300-31337a0fb205
-$ az account set --subscription="${AZURE_SUBSCRIPTION_ID}"
-```
+!!! note
+    Your Azure account needs ownership or contributor permissions on an Azure subscription.
 
-## Create an ACS Kubernetes Cluster
+    If the subscription has 2FA enabled, your Azure account must have ownership credentials in
+    order to create the service principal.
 
-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:
+## Create an ACS Kubernetes Cluster
 
-### Path 1: Azure 'az' CLI
+Azure Container Service can create a Kubernetes cluster using either
+[the `az` command line](#option-1-command-line) or [the Azure web portal](#option-2-web-portal).
 
-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 run `az account list-locations --query [].name --output tsv`
+### Option 1: Command Line
 
-Create an environment variable to hold the resource group name:
+Create a group to contain the ACS Kubernetes cluster resources. Export the resource group's name
+and location to environment variables for use by later commands:
 
 ```
+$ # list worldwide datacenter locations so we can pick one
+$ az account list-locations --query [].name --output tsv
+$ export AZURE_DC_LOCATION=southcentralus  # for example
 $ export AZURE_RG_NAME=myresourcegroup
-$ export AZURE_DC_LOCATION=mylocation
 $ az group create --name "${AZURE_RG_NAME}" --location "${AZURE_DC_LOCATION}"
 ```
 
-Execute the command to deploy the cluster. The `dns-prefix` and `ssh-key-value` must be replaced with your own values.
+Run the `az acs create` command to create your Kubernetes cluster, replacing the `--dns-prefix`
+and `--ssh-key-value` arguments below with your values:
 
 ```
 $ export AZURE_SERVICE_NAME=myacs
@@ -71,92 +62,112 @@ $ az acs create --resource-group="${AZURE_RG_NAME}" --location="${AZURE_DC_LOCAT
   --ssh-key-value @$HOME/.ssh/id_rsa.pub
 ```
 
-> Note: When `az acs create` starts, the provisioning process runs in the background by first creating a service principal named ${AZURE_SERVICE_NAME} assigned appropriate permissions.  After a few minutes the `az` command should return with information about the deployment created as shown below.
+Azure Container Services immediately begins creating the Kubernetes cluster. After a few minutes,
+the command returns with information about the new deployment:
 
 ```
 {
-  "id": "/subscriptions/ed7cedf5-fcd8-4a5d-9980-96d838f65ab8/resourceGroups/myresourcegroup/providers/Microsoft.Resources/deployments/azurecli1481240849.890798",
-  "name": "azurecli1481240849.890798",
+  "id": "/subscriptions/a123b456-1234-1ab2-12ab-12345678abcd/resourceGroups/myresourcegroup/providers/Microsoft.Resources/deployments/azurecli1496357873.8344654",
+  "name": "azurecli1496357873.8344654",
   "properties": {
-    "correlationId": "61be22d1-28d8-466c-a2ba-7bc11c2a3578",
+    "correlationId": "eae284bc-4380-484c-9302-f355e278c651",
     "debugSetting": null,
     "dependencies": [],
     "mode": "Incremental",
     "outputs": null,
-    "parameters": null,
-    "parametersLink": null,
-    "providers": [
-      {
-        "id": null,
-        "namespace": "Microsoft.ContainerService",
- ...
+...
   },
   "resourceGroup": "myresourcegroup"
 }
 ```
 
-### Path 2: UI
+Your Kubernetes cluster on Azure is ready. Skip the next section and
+[connect to the ACS Kubernetes cluster](#connect-to-the-acs-kubernetes-cluster).
+
+### Option 2: Web Portal
 
-Sign into the [Azure Portal](https://portal.azure.com) and create a new Azure Container Service:
+Sign in to the [Azure Portal](https://portal.azure.com) and create a new Azure Container Service.
+Click on the **+ New** link, then the **Compute** link, then **Azure Container Service**.
 
 ![](images/step1.png)
 
-Select "Resource Manager" for the deployment model:
+Select **Resource Manager** as the deployment model:
 
 ![](images/step2.png)
 
-Provide basic settings for the new ACS Kubernetes cluster.
+Then click the **Create** button.
 
-* 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 the compute resources
-* Resource group: create a new resource group and give the group a unique name
-* Location: choose an Azure location for the cluster
+### Basics
 
-When the required information is filled out, click "Ok".
+Provide these *Basics* for a new Azure Kubernetes cluster:
+
+- Orchestrator: **Kubernetes**
+- Subscription: choose the Azure subscription to be charged for cloud resources
+- Resource group: "Create new" with a unique name
+- Location: choose one of Azure's worldwide datacenters
 
 ![](images/step3.png)
 
-Create a new service principal via [instructions at this link](https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-authenticate-service-principal-cli#create-service-principal-with-password) and put them into the UI.
+Then click the **OK** button to move on to [Master configuration](#master-configuration).
+
+### Master configuration
 
-* Service Principal Client ID: the name of the principal created in the example document after the `-n` parameter e.g. `exampleapp`
-* Service Principal Client Secret: the password specified after the `-p` parameter or auto-generated in the Azure CLI e.g. 349d4728-438a-52a5-ad25-a740aa0bd240
+First take a slight detour to [create a service principal][] to access resources. Then supply the
+**Master configuration** options for your Kubernetes cluster:
+
+- DNS name prefix: the first section of the cluster's hostname
+- User name: name of a unix user who will be added to all Kubernetes nodes
+- SSH public Key: a public key to authenticate the unix user specified above
+- Service principal client ID: the `appId` field of the service principal
+- Service principal client secret: the `password` field of the service principal
+- Master count: number of Kubernetes masters for the cluster
 
 ![](images/step4.png)
 
-Next, configure the number of worker nodes, the node size, and DNS prefix for the cluster.
+When you are satisfied with your choices, click **OK** to move on to
+[Agent Configuration](#agent-configuration).
+
+### Agent configuration
 
-Worker nodes should have at least 7GB of available RAM.
+Choose **Agent configuration** options for your Kubernetes cluster:
 
-Click "Ok" to continue.
+- Agent count: number of Kubernetes nodes to create
+- Agent virtual machine size: "Standard DS2" or better is recommended
+- Operating system: Linux
 
 ![](images/step5.png)
 
-Review the cluster configuration and click "Ok". After clicking "Purchase" on the next screen the browser will be returned to the Azure Portal dashboard.
+When you are satisfied with your choices, click **OK** to move on to [Summary](#summary).
 
-![](images/step6.png)
+### Summary
 
-The Kubernetes cluster will take a few minutes to complete provisioning and configure itself. To monitor the progress of the deployment select the "Resource Group" from the nav on the left, then select the cluster name:
+Confirm the **Summary** of configuration choices for your Kubernetes cluster:
+
+![](images/step6.png)
 
-![](images/step8.png)
+Click **OK** to tell Azure Container Services to start creating your new Kubernetes cluster. You
+can monitor the progress of the deployment on the Azure dashboard, or just wait for a
+notification that it has completed.
 
-![](images/step9.png)
+Your Kubernetes cluster on Azure is ready. Now make sure you can
+[connect to the ACS Kubernetes cluster](#connect-to-the-acs-kubernetes-cluster).
 
 ## Connect to the ACS Kubernetes Cluster
 
 `kubectl` is the Kubernetes command line client.  If you don't already have it installed, you can install it with:
 
-```console
+```
 az acs kubernetes install-cli
 ```
 
 Download the master kubernetes cluster configuration to the ~/.kube/config file by running the following command:
 
-```console
+```
 az acs kubernetes get-credentials --resource-group=$AZURE_RG_NAME --name=$AZURE_SERVICE_NAME
 ```
+
  > Note: If the cluster was provisioned using any other SSH key than `/home/myusername/.ssh/id_rsa` then the `--ssh-key-file` parameter must be used pointing to the SSH key utilized to provision the cluster.
- 
+
 Verify connectivity to the new ACS Kubernetes cluster by running `kubectl cluster-info`
 
 ```
@@ -168,3 +179,9 @@ kubernetes-dashboard is running at https://mydnsprefix.myregion.cloudapp.azure.c
 ```
 
 You are now ready to [install Deis Workflow](install-azure-acs.md)
+
+[Azure Portal]: https://portal.azure.com/
+[install Azure CLI to your computer]: https://docs.microsoft.com/en-us/cli/azure/install-azure-cli
+[Cloud Shell]: https://azure.microsoft.com/en-us/features/cloud-shell/
+[create a service principal]: https://docs.microsoft.com/en-us/azure/container-service/container-service-kubernetes-service-principal
+[creating SSH key pairs]: https://docs.microsoft.com/azure/virtual-machines/virtual-machines-linux-mac-create-ssh-keys