feat(contrib/azure): clean up Azure docs and scripts

Author: carmstrong

.gitignore

@@ -34,6 +34,7 @@ builder/image/bin/yaml2json-procfile
 cache/image/bin
 client/dist/
 client/makeself/
+contrib/azure/azure-user-data
 contrib/bumpver/bumpver
 deisctl/deisctl
 deisctl/dist/

contrib/azure/azure-coreos-cluster

@@ -85,7 +85,10 @@ if not args.ssh_cert and not args.ssh_thumb:
 # Setup custom data
 if args.custom_data:
     with open(args.custom_data, 'r') as f:
-        cloud_init = f.read()
+      if not os.path.exists(args.custom_data):
+        print "Couldn't find the user-data file. Did you remember to run `create-azure-user-data`?"
+        sys.exit(1)
+      cloud_init = f.read()
     f.closed
 else:
     if args.discovery_service_url:
@@ -101,7 +104,7 @@ with open(args.ssh_cert) as f:
     service_cert_file_data = base64.b64encode(f.read())
 f.closed
 
-def wait_for_async(request_id, operation_name, timeout):
+def wait_for_async(request_id, timeout):
     count = 0
     result = sms.get_operation_status(request_id)
     while result.status == 'InProgress':
@@ -110,14 +113,13 @@ def wait_for_async(request_id, operation_name, timeout):
             print('Timed out waiting for async operation to complete.')
             return
         time.sleep(5)
-        print('.')
+        print('.'),
+        sys.stdout.flush()
         result = sms.get_operation_status(request_id)
-        print(vars(result))
         if result.error:
             print(result.error.code)
             print(vars(result.error))
-    print(result.status)
-    print(operation_name + ' took:' + str(count*5) + 's')
+    print result.status + ' in ' + str(count*5) + 's'
 
 def linux_config(hostname, args):
     pk = PublicKey(args.ssh_thumb,
@@ -163,15 +165,24 @@ def data_hd(target_container_url, target_blob_name, target_lun, target_disk_size
 sms = ServiceManagementService(args.subscription, args.azure_cert)
 
 #Create the cloud service
-sms.create_hosted_service(
-    args.cloud_service_name, label=args.cloud_service_name, location=args.location)
-print('created service ' + args.cloud_service_name)
-time.sleep(2)
+try:
+  print 'Creating the hosted service...',
+  sys.stdout.flush()
+  sms.create_hosted_service(
+      args.cloud_service_name, label=args.cloud_service_name, location=args.location)
+  print('Successfully created hosted service ' + args.cloud_service_name)
+  sys.stdout.flush()
+  time.sleep(2)
+except WindowsAzureConflictError:
+  print "Hosted service {} already exists. Delete it or try again with a different name.".format(args.cloud_service_name)
+  sys.exit(1)
 
 #upload ssh cert to cloud-service
+print 'Uploading SSH certificate...',
+sys.stdout.flush()
 result = sms.add_service_certificate(args.cloud_service_name,
                                      service_cert_file_data, SERVICE_CERT_FORMAT, '')
-wait_for_async(result.request_id, 'upload cert', 15)
+wait_for_async(result.request_id, 15)
 
 def get_vm_name(args, i):
     return args.cloud_service_name + '-' + args.vm_name_prefix + '-' + str(i)
@@ -199,19 +210,31 @@ for i in range(args.num_nodes):
     else:
         data_disks = None
 
-    if i == 0:
-        result = sms.create_virtual_machine_deployment(
-                    args.cloud_service_name, deployment_name=args.cloud_service_name,
-                    deployment_slot='production', label=vm_name,
-                    role_name=vm_name, system_config=system, os_virtual_hard_disk=os_hd,
-                    role_size=args.vm_size, network_config=network, data_virtual_hard_disks=data_disks)
-    else:
-        result = sms.add_role(
-                    args.cloud_service_name, deployment_name=args.cloud_service_name,
-                    role_name=vm_name,
-                    system_config=system, os_virtual_hard_disk=os_hd,
-                    role_size=args.vm_size, network_config=network, data_virtual_hard_disks=data_disks)
-    wait_for_async(result.request_id, 'create VM' + vm_name, 30)
+    try:
+      if i == 0:
+          result = sms.create_virtual_machine_deployment(
+                      args.cloud_service_name, deployment_name=args.cloud_service_name,
+                      deployment_slot='production', label=vm_name,
+                      role_name=vm_name, system_config=system, os_virtual_hard_disk=os_hd,
+                      role_size=args.vm_size, network_config=network, data_virtual_hard_disks=data_disks)
+      else:
+          result = sms.add_role(
+                      args.cloud_service_name, deployment_name=args.cloud_service_name,
+                      role_name=vm_name,
+                      system_config=system, os_virtual_hard_disk=os_hd,
+                      role_size=args.vm_size, network_config=network, data_virtual_hard_disks=data_disks)
+    except WindowsAzureError as e:
+      if "Forbidden" in str(e):
+        print "Unable to use this CoreOS image. This usually means a newer image has been published."
+        print "See https://coreos.com/docs/running-coreos/cloud-providers/azure/ for the latest stable image,"
+        print "and supply it to this script with --coreos-image. If it works, please open a pull request to update this script."
+        sys.exit(1)
+      else:
+        pass
+
+    print 'Creating VM ' + vm_name + '...',
+    sys.stdout.flush()
+    wait_for_async(result.request_id, 30)
     vms.append({'name':vm_name,
                 'host':args.cloud_service_name + '.cloudapp.net',
                 'port':ssh_port,
@@ -229,18 +252,30 @@ def get_ips(service_name, deployment_name):
 if args.pip:
     ips = []
     ips = get_ips(args.cloud_service_name, args.cloud_service_name)
-    print 'dns file ----'
+    print ''
+    print '-------'
+    print "You'll need to configure DNS records for a domain you wish to use with your Deis cluster."
+    print 'For convenience, the public IP addresses are printed below, along with sane DNS timeouts.'
+    print ''
     for ip in ips:
         print '@ 10800 IN A ' + ip
     print '* 10800 IN CNAME @'
-    print 'end dns file ----'
+    print '-------'
+    print 'For more information, see: http://docs.deis.io/en/latest/managing_deis/configure-dns/'
+    print ''
 
 #print ~/.ssh/config
-print '~/.ssh/config ----'
+print ''
+print '-------'
+print "Instances on Azure don't use typical SSH ports. It is recommended to configure ~/.ssh/config"
+print 'so the instances can easily be referenced when logging in via SSH. For convenience, the config'
+print 'directives for your instances are below:'
+print ''
 for vm in vms:
     print 'Host ' + vm['name']
     print '    HostName ' + vm['host']
     print '    Port ' + str(vm['port'])
     print '    User ' + vm['user']
     print '    IdentityFile ' + vm['identity']
-print 'end ~/.ssh/config ----'
+print '-------'
+print ''

docs/installing_deis/azure.rst

@@ -8,36 +8,29 @@ Microsoft Azure
 
 This section will show you how to create a 3-node Deis cluster on Microsoft Azure.
 
-Before you start, :ref:`get the Deis source <get_the_source>` and change directory into `contrib/azure`_ while following this documentation.
+Before you start, :ref:`get the Deis source <get_the_source>` and change directory into `contrib/azure`_
+while following this documentation.
 
 
 Install Python and Azure SDK for Python
 ---------------------------------------
 
-The cluster creation tool uses Python and the Python Azure library to create a CoreOS cluster. If you haven't already, install these on your development machine:
+The cluster creation tool uses Python and the Python Azure library to create a CoreOS cluster.
+If you haven't already, install these on your development machine:
 
 .. code-block:: console
 
     $ brew install python
-    ...
-
-    $ sudo pip install azure
-    ...
-
-
-And check to make sure they are configured correctly:
-
-.. code-block:: console
-
-    $ python -c "import azure; print(azure.__version__)"
-    0.9.0  <-- everything working ok!
+    $ sudo pip install azure pyyaml
 
 Generate Certificates
 ---------------------
 
-The azure-coreos-cluster creation tool uses the Azure management REST API to create the CoreOS cluster which uses a management certificate to authenticate.
+The azure-coreos-cluster creation tool uses the Azure management REST API to create the CoreOS
+cluster which uses a management certificate to authenticate.
 
-If you don't have a management certificate already configured, the script generate-mgmt-cert.sh can create this certificate for you. Otherwise, you can skip to the next section.
+If you don't have a management certificate already configured, the script generate-mgmt-cert.sh can
+create this certificate for you. Otherwise, you can skip to the next section.
 
 If you need to create a certificate, edit cert.conf in contrib/azure with your company's details and then run:
 
@@ -48,48 +41,58 @@ If you need to create a certificate, edit cert.conf in contrib/azure with your c
 Upload Management Cert
 ----------------------
 
-If you haven't uploaded your management certificate to Azure (azure-cert.cer if you used the script in the previous section), do that now using the `management certificates tab`_ of the Azure portal's Settings.
+If you haven't uploaded your management certificate to Azure (azure-cert.cer if you used the script
+in the previous section), do that now using the `management certificates tab`_ of the
+Azure portal's Settings.
 
 Also copy the Azure subscription id from this table and save it for the cluster creation script below.
 
 Create Cluster Cloud Config
 ---------------------------
 
-Before we can create a cluster, we need to create a cloud config for it. The script create-azure-user-data does this for you. This script takes the stock cluster instance config in ../coreos/user-data.example and customizes it for Azure and inserts a unique cluster discovery url:
+Before we can create a cluster, we need to create a cloud config for it. The script
+``create-azure-user-data`` does this for you. This script takes the stock cluster instance config
+in ``../coreos/user-data.example``, customizes it for Azure, and inserts a unique cluster discovery
+endpoint:
 
 .. code-block:: console
 
     $ ./create-azure-user-data $(curl -s https://discovery.etcd.io/new)
 
-This will create a azure-user-data cloud config file. We'll use this with the script in the next section during cluster creation.
+This will create a azure-user-data cloud config file. We'll use this with the script in the next
+section during cluster creation.
 
 Create CoreOS Cluster
 ---------------------
 
 With the management certificate and cloud config in place, we are ready to create our cluster.
 
-* Create a container called 'vhds' within a storage account in the same region as your cluster using the Azure portal. Note the URL of the container for the cluster creation script below.
+* Create a container called ``vhds`` within a storage account in the same region as your cluster using the Azure portal. Note the URL of the container for the cluster creation script below.
 * Choose a cloud service name for your Deis cluster for the script below. The script will automatically create this cloud service for you.
+* Choose an Azure `region`_ to use. Supply it in quotes with the ``--location`` parameter. The default is "West US".
 
 With that, let's run the azure-coreos-cluster script which will create the CoreOS cluster. Fill in the bracketed values with the values for your deployment you created above.
 
 .. code-block:: console
 
     $ ./azure-coreos-cluster [cloud service name]
          --subscription [subscription id]
-         --azure-cert azure-cert.pem 
+         --azure-cert azure-cert.pem
          --num-nodes 3
-         --location "West US"    
-         --vm-size Large  
+         --location "[location]"
+         --vm-size Large
          --pip
          --deis
          --blob-container-url https://[blob container].blob.core.windows.net/vhds/
          --data-disk
          --custom-data azure-user-data
 
-This script will by default provision a 3 node cluster but you can increase this with the --num-nodes parameter. Likewise, you can increase the vm size using the --vm-size. It is not recommended that you use smaller than Large (A3) sized instances.
+This script will by default provision a 3 node cluster but you can increase this with the
+``--num-nodes`` parameter. Likewise, you can increase the VM size using ``--vm-size``.
+It is not recommended that you use smaller than Large (A3) sized instances.
 
-Note that for scheduling to work properly, clusters must consist of at least 3 nodes and always have an odd number of members. For more information, see `optimal etcd cluster size`_.
+Note that for scheduling to work properly, clusters must consist of at least 3 nodes and always
+have an odd number of members. For more information, see `etcd disaster recovery`_.
 
 
 Configure DNS
@@ -104,13 +107,8 @@ Install Deis Platform
 Now that you've finished provisioning a cluster, please refer to :ref:`install_deis_platform` to
 start installing the platform.
 
-IMPORTANT NOTE: Once you have installed deisctl, you will need to use a customized deis-builder component for Azure since Azure uses routable IP addresses for each instance. Configure this using the following command before you run 'deisctl install platform': 
-
-.. code-block:: console
-
-    $ deisctl config builder set image=deis/builder:v1.1.1-azure
-
 .. _`management certificates tab`: https://manage.windowsazure.com/#Workspaces/AdminTasks/ListManagementCertificates
 .. _`contrib/azure`: https://github.com/deis/deis/tree/master/contrib/azure
 .. _`etcd`: https://github.com/coreos/etcd
-.. _`optimal etcd cluster size`: https://github.com/coreos/etcd/blob/master/Documentation/optimal-cluster-size.md
+.. _`etcd disaster recovery`: https://github.com/coreos/etcd/blob/master/Documentation/admin_guide.md#disaster-recovery
+.. _`region`: http://azure.microsoft.com/en-us/regions/