feat(azure): skeleton for Azure Container Service quickstart

deis · Dec 8, 2016 · 19b9ec1 · 19b9ec1
1 parent 1a5b9cc
commit 19b9ec1
Show file tree

Hide file tree

Showing 4 changed files with 185 additions and 0 deletions.
diff --git a/src/quickstart/index.md b/src/quickstart/index.md
@@ -21,6 +21,7 @@ Cloud-based options:
 
 * [Google Container Engine](provider/gke/boot.md): provides a managed Kubernetes environment, available with a few clicks.
 * [Amazon Web Services](provider/aws/boot.md): uses Kubernetes upstream `kube-up.sh` to boot a cluster on AWS EC2.
+* [Azure Container Service](provider/azure-acs/boot.md): uses Azure Container Service to provision Kubernetes and install Workflow.
 
 If you would like to test on your local machine follow, our guide for [Vagrant](provider/vagrant/boot.md).
 

diff --git a/src/quickstart/provider/azure-acs/boot.md b/src/quickstart/provider/azure-acs/boot.md
@@ -0,0 +1,65 @@
+# Booting Azure Container Service
+
+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.
+
+## Install and configure the 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).
+
+After installing the CLI, log in to your Azure Account:
+```
+~ $ 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": "[email protected]",
+      "type": "user"
+    }
+  }
+]
+```
+
+TODO: handle multiple subscriptions?
+
+## 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.
+
+```
+$ az ad sp create-for-rbac --name="http://workflow-on-acs" --role="Contributor" --scopes="/subscriptions/<SUBSCRIPTION ID>"
+{
+  "appId": "58b21231-3dd7-4546-bd37-9df88812331f",
+  "name": "http://workflow-on-acs",
+  "password": "349d4728-438a-52a5-ad25-a740aa0bd240",
+  "tenant": "891a9ddc-477a-4620-8f21-db22ffd3ffea"
+}
+```
+
+## Create Your ACS Kubernetes Cluster
+
+Path 1: UI
+
+Path 2: ACS Engine
+
+## Connect to your Kubernetes Cluster
+
+1. Find hostname for the master
+2. SCP Kubeconfig from master into place
+3. Set KUBECONFIG environment value
+
+```
+$ kubectl cluster-info
+Kubernetes master is running at https://slack-acs-1mgmt.eastus.cloudapp.azure.com
+Heapster is running at https://slack-acs-1mgmt.eastus.cloudapp.azure.com/api/v1/proxy/namespaces/kube-system/services/heapster
+KubeDNS is running at https://slack-acs-1mgmt.eastus.cloudapp.azure.com/api/v1/proxy/namespaces/kube-system/services/kube-dns
+kubernetes-dashboard is running at https://slack-acs-1mgmt.eastus.cloudapp.azure.com/api/v1/proxy/namespaces/kube-system/services/kubernetes-dashboard
+```
+
+You are now ready to [install Deis Workflow](install-azure-acs.md)
diff --git a/src/quickstart/provider/azure-acs/dns.md b/src/quickstart/provider/azure-acs/dns.md
@@ -0,0 +1,49 @@
+## Find Your Load Balancer Address
+
+On Azure Container Engine, Deis Workflow will automatically provision and
+attach a Azure Load Balancer to the router component. This component is
+responsible for routing HTTP and HTTPS requests from the public internet to
+applications that are deployed and managed by Deis Workflow.
+
+By describing the `deis-router` service, you can see what IP address has been
+allocated by Azure Cloud for your Deis Workflow cluster:
+
+```
+$ kubectl --namespace=deis get service deis-router
+NAME          CLUSTER-IP    EXTERNAL-IP    PORT(S)                            AGE
+deis-router   10.0.60.172   13.82.148.57   80/TCP,443/TCP,2222/TCP,9090/TCP   54m
+```
+
+TODO: mention `<pending>` state
+
+## Prepare the Hostname
+
+Now that you have the ip address of your load balancer we can use the `nip.io`
+DNS service to route arbitrary hostnames to the Deis Workflow edge router. This
+lets us point the Workflow CLI at your cluster without having to either use
+your own domain or update DNS!
+
+To verify the Workflow API server and nip.io, construct your hostname by taking
+the ip address for your load balancer and adding `nip.io`. For our example
+above, the address would be: `13.82.148.57.nip.io`.
+
+Nip answers with the ip address no matter the hostname:
+```
+$ host 13.82.148.57.nip.io
+13.82.148.57.nip.io has address 13.82.148.57
+$ host something-random.13.82.148.57.nip.io
+something-random.13.82.148.57.nip.io has address 13.82.148.57
+```
+
+By default, any HTTP traffic for the hostname `deis` will be sent to the Workflow API service. To test that everything is connected properly you may validate connectivity using `curl`:
+
+```
+$ curl http://deis.13.82.148.57.nip.io/v2/ && echo
+{"detail":"Authentication credentials were not provided."}
+```
+
+You should see a failed request because we provided no credentials to the API server.
+
+Remember the hostname, we will use it in the next step.
+
+You are now ready to [register an admin user and deploy your first app](../../deploy-an-app.md).
diff --git a/src/quickstart/provider/azure-acs/install-azure-acs.md b/src/quickstart/provider/azure-acs/install-azure-acs.md
@@ -0,0 +1,70 @@
+# Install Deis Workflow on Azure Container Service
+
+## Check Your Setup
+
+First check that the `helm` command is available and the version is v2.0.0 or newer.
+
+```
+$ helm version
+Client: &version.Version{SemVer:"v2.0.0", GitCommit:"51bdad42756dfaf3234f53ef3d3cb6bcd94144c2", GitTreeState:"clean"}
+Server: &version.Version{SemVer:"v2.0.0", GitCommit:"51bdad42756dfaf3234f53ef3d3cb6bcd94144c2", GitTreeState:"clean"}
+```
+
+Ensure the `kubectl` client is installed and can connect to your Kubernetes cluster.
+
+## Add the Deis Chart Repository
+
+The Deis Chart Repository contains everything needed to install Deis Workflow onto a Kubernetes cluster, with a single `helm install deis/workflow --namespace deis` command.
+
+Add this repository to Helm:
+
+```
+$ helm repo add deis https://charts.deis.com/workflow
+```
+
+## Install Deis Workflow
+
+Now that Helm is installed and the repository has been added, install Workflow by running:
+
+```
+$ helm install deis/workflow --namespace deis --set controller.docker_tag=v2.9.0-acs,controller.org=kmala
+```
+
+Helm will install a variety of Kubernetes resources in the `deis` namespace.
+Wait for the pods that Helm launched to be ready. Monitor their status by running:
+
+```
+$ kubectl --namespace=deis get pods
+```
+
+If it's preferred to have `kubectl` automatically update as the pod states change, run (type Ctrl-C to stop the watch):
+
+```
+$ kubectl --namespace=deis get pods -w
+```
+
+Depending on the order in which the Workflow components initialize, some pods may restart. This is common during the
+installation: if a component's dependencies are not yet available, that component will exit and Kubernetes will
+automatically restart it.
+
+Here, it can be seen that the controller, builder and registry all took a few loops before they were able to start:
+
+```
+$ kubectl --namespace=deis get pods
+NAME                          READY     STATUS    RESTARTS   AGE
+deis-builder-hy3xv            1/1       Running   5          5m
+deis-controller-g3cu8         1/1       Running   5          5m
+deis-database-rad1o           1/1       Running   0          5m
+deis-logger-fluentd-1v8uk     1/1       Running   0          5m
+deis-logger-fluentd-esm60     1/1       Running   0          5m
+deis-logger-sm8b3             1/1       Running   0          5m
+deis-minio-4ww3t              1/1       Running   0          5m
+deis-registry-asozo           1/1       Running   1          5m
+deis-router-k1ond             1/1       Running   0          5m
+deis-workflow-manager-68nu6   1/1       Running   0          5m
+```
+
+Once all of the pods are in the `READY` state, Deis Workflow is up and running!
+
+Next, [configure dns](dns.md) so you can register your first user and deploy an application.
+