Merge pull request #625 from squillace/master

updating documentation to highlight the major changes in 0.12

README.md

@@ -4,7 +4,12 @@
 
 [![Build Status](https://circleci.com/gh/Azure/draft.svg?style=svg)](https://circleci.com/gh/Azure/draft)
 
-_NOTE: Draft is experimental and does not have a stable release yet._
+## _NOTE: Draft is experimental and does not have a stable release yet._
+As an example, the 0.12 release moves the containment and deployment engine to your local machine. This changes quite a bit about how Draft works compared to prior releases; for details, see [the changelog](CHANGELOG.md).
+
+For previous users, this change means that you now have more control over where your container images are stored, and in the local minikube environment, you can skip pushing the images entirely, which speeds up the developer iteration speed dramatically. However, when you want to push your images to an image registry service like Docker hub (or ACR, GCR, Quay.io, and so on) you must inform draft which registry to use and your cluster must have access to the secrets for that registry. 
+
+## Overview
 
 [![asciicast](https://asciinema.org/a/WGVE7JNodpBEOautl105tdc97.png)](https://asciinema.org/a/WGVE7JNodpBEOautl105tdc97)
 
@@ -22,7 +27,7 @@ Once the developer is happy with changes made via Draft, they commit and push to
 
 ## Installation
 
-Review the [Installation Guide][Installation Guide] to configure and install Draft on to your Kubernetes cluster.
+Review the [Installation Guide][Installation Guide] to configure and install Draft on to your Kubernetes cluster. Do, however, take note of the major changes in the 0.12 release if you have already used or are using Draft now. It's different.
 
 ### Take Draft for a Spin
 

docs/install-advanced.md

@@ -1,7 +1,8 @@
 # Advanced Install Guide
 
-In certain situations, users are given a Kubernetes cluster with tighter security constraints such as
+In certain situations, users are given a Kubernetes cluster with security constraints such as
 
+- needing to push and pull container images to and from a remote or otherwise secured container registry
 - only being able to deploy applications to a certain namespace
 - running applications in an RBAC-enabled cluster
 
@@ -9,7 +10,19 @@ This document explains some of these situations as well as how it can be handled
 
 ## Drafting in the Cloud
 
-When using Draft with cloud-provided Kubernetes solutions like [Azure Container Service](https://azure.microsoft.com/en-us/services/container-service/), we need a way to distribute the built image across the cluster. A container registry allows all nodes in the Kubernetes cluster to pull the images we build using Draft, and we have a way for our local Docker daemon to distribute the built image.
+When using Draft with cloud-provided Kubernetes solutions like [Azure Container Service (AKS)](https://azure.microsoft.com/services/container-service/), we need a way to distribute the built image across the cluster. A container registry allows all nodes in the Kubernetes cluster to pull the images we build using Draft, and we have a way for our local Docker daemon to distribute the built image.
+
+For local use with Minikube, only the `eval $(minikube docker-env)` command is required to inform Draft to use the local registry for deployment, which skips the step of pushing the container image and enables the deployment to Minikube to pull from the local registry. This makes the local inner-loop experience very fast. 
+
+For cloud registry services, like ACR or Docker Hub, two things are needed. 
+1. You need to tell draft where the registry resides using the `draft config set registry` command, passing the registry's server URL (without the protocol scheme). 
+2. Unless there is a trust relationship between the cluster provider and the registry -- as there is with Azure Kubernetes Service (AKS) and the Azure Container Registry (ACR) -- you'll need to [add a container registry secret to your chart](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry) to pull the private image.
+
+## Drafting with ACR and AKS
+
+Let's use Azure Container Registry (ACR) as an example registry, and use AKS as our Kubernetes service for this example. 
+
+REMEMBER: Kubernetes services like Azure Kubernetes Service (AKS) are automatically authorized to pull from container registries in the same resource group. If this is not the case, then please reread the [Drafting in the Cloud](#drafting-in-the-cloud) section. 
 
 For this example, we want to push images to our registry sitting at `myregistry.azurecr.io`, and pull those images down to the Kubernetes cluster from that same registry. To do that, we run
 
@@ -25,7 +38,7 @@ We'll also need to log into the cluster to push images from our local docker dae
 $ az acr login -n myregistry -g myresourcegroup
 ```
 
-NOTE: Kubernetes distributions like Azure Container Service are automatically authorized to pull from container registries in the same resource group. If this is not the case, then you'll need to [add a container registry secret to your chart](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry) to pull the private image.
+
 
 ## Running Tiller with RBAC enabled
 

docs/install.md

@@ -6,6 +6,8 @@ Get started with Draft in three easy steps:
 1. Boot Minikube and install Tiller
 1. Deploy your first application
 
+Note: This document uses a local image repository with minikube. To use Draft directly with a container registry service like https://hub.docker.com or another registry service, see the configuration steps in [Drafting in the Cloud](install-advanced.md#drafting-in-the-cloud). 
+
 ## Dependencies
 
 In order to get started, you will need to have the following: