Document that clusters are not ACS resources (#1507)

* Clarify documentation - engine does not create ACS resource

* Fixed minor typos in Kubernetes deployment doc

docs/kubernetes/deploy.md

@@ -8,9 +8,11 @@ For installation instructions see [the Azure CLI GitHub repository](https://gith
 
 ## Overview
 
-`acs-engine` reads a cluster definition which describes the size, shape, and configuration of your cluster. This guide takes the default configuration of one master and two linux agents. If you would like to change the configuration, edit `examples/kubernetes.json` before continuing.
+`acs-engine` reads a cluster definition which describes the size, shape, and configuration of your cluster. This guide takes the default configuration of one master and two Linux agents. If you would like to change the configuration, edit `examples/kubernetes.json` before continuing.
 
-The `acs-engine deploy` command automates creation of a Service Principal, Resource Group and SSH key for your cluster. If operators need more control or are are intersted in the individual steps see the ["Long Way" section below](#the-long-way).
+The `acs-engine deploy` command automates creation of a Service Principal, Resource Group and SSH key for your cluster. If operators need more control or are intersted in the individual steps see the ["Long Way" section below](#the-long-way).
+
+**NOTE:** ACS Engine creates a _cluster_; it _doesn't_ create an Azure Container Service resource.  So clusters that you create using the `acs-engine` command (or ARM templates generated by the `acs-engine` command) won't show up as ACS resources, for example when you run `az acs list`.  Think of `acs-engine` as the, er, engine which ACS uses to create clusters: you can use the same engine yourself, but ACS won't know about the results.
 
 ## Gather Information
 
@@ -29,7 +31,7 @@ Contoso Subscription                             AzureCloud   51ac25de-afdg-9201
 
 For this example, the subscription id is `51ac25de-afdg-9201-d923-8d8e8e8e8e8e`, the DNS prefix is `contoso-apple`, and location is `westus2`.
 
-Run `acs-engine deploy` with the appropriate argumets:
+Run `acs-engine deploy` with the appropriate arguments:
 
 ```
 $ acs-engine deploy --subscription-id 51ac25de-afdg-9201-d923-8d8e8e8e8e8e \
@@ -48,9 +50,9 @@ INFO[0393] Finished ARM Deployment (contoso-apple-59769a59-1423145182).
 `acs-engine` will output Azure Resource Manager (ARM) templates, SSH keys, and a kubeconfig file in `_output/contoso-apple-59769a59` directory:
 
    * `_output/contoso-apple-59769a59/azureuser_rsa`
-   * `_output/contoso-apple-59769a59/kubeconfig/kubeconfig.uswest2.json`
+   * `_output/contoso-apple-59769a59/kubeconfig/kubeconfig.westus2.json`
 
-Acs-engine generates kubeconfig files for each possible region. Access the new cluster by using the kubeconfig generated for the cluster's location. This example used `uswest2`, so the kubeconfig is `_output/<clustername>/kubeconfig/kubeconfig.uswest2.json`:
+acs-engine generates kubeconfig files for each possible region. Access the new cluster by using the kubeconfig generated for the cluster's location. This example used `westus2`, so the kubeconfig is `_output/<clustername>/kubeconfig/kubeconfig.westus2.json`:
 
 ```
 $ KUBECONFIG=_output/contoso-apple-59769a59/kubeconfig/kubeconfig.westus2.json kubectl cluster-info
@@ -80,14 +82,14 @@ Kubernetes clusters have integrated support for various cloud providers as core
 
 ### Step 3: Edit your Cluster Definition
 
-ACS Engine consumes a cluster definition which outlines the desired shape, size, and configuration of Kubernetes. There are a number of features that can be enabled through the cluster definition, check the `examples` directory for a number of... examples.
+ACS Engine consumes a cluster definition which outlines the desired shape, size, and configuration of Kubernetes. There are a number of features that can be enabled through the cluster definition: check the `examples` directory for a number of... examples.
 
 Edit the [simple Kubernetes cluster definition](/examples/kubernetes.json) and fill out the required values:
 
-* `dnsPrefix`: must be a region-unique name and will form part of the hostname (e.g. myprod1, staging, leapinglama), be unique!
-* `keyData`: must contain the public portion of an SSH key, this will be associated with the `adminUsername` value found in the same section of the cluster definition (e.g. 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABA....')
-* `clientId`: this is the appId uuid or name from step 2
-* `secret`: this is the password or randomly-generated password from step 2
+* `dnsPrefix`: must be a region-unique name and will form part of the hostname (e.g. myprod1, staging, leapingllama) - be unique!
+* `keyData`: must contain the public portion of an SSH key - this will be associated with the `adminUsername` value found in the same section of the cluster definition (e.g. 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABA....')
+* `clientId`: this is the service principal's appId uuid or name from step 2
+* `secret`: this is the service principal's password or randomly-generated password from step 2
 
 ### Step 4: Generate the Templates
 
@@ -97,7 +99,7 @@ Run `acs-engine generate examples/kubernetes.json`
 
 ### Step 5: Submit your Templates to Azure Resource Manager (ARM)
 
-[deploy the output azuredeploy.json and azuredeploy.parameters.json](../acsengine.md#deployment-usage)
+[Deploy the output azuredeploy.json and azuredeploy.parameters.json](../acsengine.md#deployment-usage)
   * To enable the optional network policy enforcement using calico, you have to
     set the parameter during this step according to this [guide](../kubernetes.md#optional-enable-network-policy-enforcement-using-calico)