doc draft completed along with mod code

docs/templates.rst

@@ -1,7 +1,10 @@
 Deploying Azure Virtual Machine in Simple Azure ARM Mode
 ===============================================================================
 
-Simpla Azure deploys a Ubuntu 16.04 VM using `the sample template <https://github.com/Azure-Samples/resource-manager-python-template-deployment/blob/master/templates/template.json>`_ from `Azure-Samples <https://github.com/Azure-Samples/resource-manager-python-template-deployment/>`_.
+Simpla Azure deploys a Ubuntu 16.04 VM using `the sample template
+<https://github.com/Azure-Samples/resource-manager-python-template-deployment/blob/master/templates/template.json>`_
+from `Azure-Samples
+<https://github.com/Azure-Samples/resource-manager-python-template-deployment/>`_ like this:
 
 ::
 
@@ -11,11 +14,10 @@ Simpla Azure deploys a Ubuntu 16.04 VM using `the sample template <https://githu
   >> arm.deploy(template = url, param = { "sshKeyData": "ssh-rsa AAAB3Nza..." })
 
 
-A new deployment is completed on a resource group like::
+A new deployment is completed in a resource group like:
 
 .. image:: images/sampleazure.png
 
-
 Deleting a deployment is::
 
   >> a.terminate_deployment()
@@ -24,6 +26,10 @@ Or removing a resource group is::
 
   >> a.remove_resource_group()
 
+
+.. tips:: ``>>`` indicates Python interactive shell and ``$`` indicates bash
+        shell in this document.
+
 Overview
 -------------------------------------------------------------------------------
 
@@ -36,12 +42,12 @@ information of resoures to be deployed e.g.  Virtual Machine and Virtual
 Network with Resource Groups. Simple Azure is able to load custom templates
 from a file or a web and use the official community templates
 `Azure-QuickStart-Templates
-<https://github.com/Azure/azure-quickstart-templates/>_`.
+<https://github.com/Azure/azure-quickstart-templates/>`_.
 
 
 .. note:: ARM does not support the classic version of virtual machines and
         cloud services which are only available via ServiceManagementAPI.
-        VMs launched via ASM do not appear on ASM listing and vice versa.
+        VMs launched via ARM do not appear on ASM listing and vice versa.
 
 
 ARM JSON Template
@@ -61,22 +67,23 @@ resources and outputs. For example, the blank template looks like::
   https://portal.azure.com/#create/Microsoft.MyGallery
 
 - ``resources`` contains definition of azure services to be deployed e.g.
-  Virtual Machine. Also, this ``resources`` entity is mandatory.
+  Virtual Machine. Also, this entity is mandatory.
 - ``parameters`` contains input values which allow you to provide when template
   is deployed.
 
+.. note:: For more information about data structure of resources and
+        parameters, see the 'authoring templates' here:
+        https://azure.microsoft.com/en-us/documentation/articles/resource-group-authoring-templates/
+
 In addition, there are variables and outputs which are recommended to add
 according to `the official templates
 <https://github.com/Azure/azure-quickstart-templates>`_.
 
-.. note:: For more information about templates including credential
-        configuration, please see the Azure Resource Manager page here
-        :ref:`ref-arm`
+.. note:: Need to setup credentials for ARM? see the Azure Resource Manager
+        page here :ref:`ref-arm`
 
-.. note:: official document of writing templates is here:
-        https://azure.microsoft.com/en-us/documentation/articles/resource-group-authoring-templates/
 
-Starting a VM with Simple Azure
+Starting a VM with Simple Azure (step-by-step)
 -------------------------------------------------------------------------------
 
 ``arm`` sub package is added under ``simpleazure``. Try::
@@ -96,17 +103,19 @@ for ARM.
 - tenant id             (equal to env name ``AZURE_TENANT_ID``)
 - client secret key     (equal to env name ``AZURE_CLIENT_SECRET``)
 
-For more detail about credentials, see the ARM page here :ref:`ref-arm`
+You may not be familiar with client id and client secret key, see the page here
+':ref:`ref-arm`'. Client id and secret key can be obtained via Azure CLI or the
+new portal.
 
-Deliver credential values as parameters like::
+You can deliver credential values as parameters in Python Shell like::
 
   >> sid = "5s3ag2s5-2aa1-4828-xxxx-9g8sw72w5w5g"
   >> cid = "5c5a3ea3-ap34-4pd0-xxxx-2p38ac00aap1"
   >> secret = "xxxxxxxxxxxxxxxxx"
   >> tid = "5e39a20e-c55a-53de-xxxx-2503a55et6ta"
   >> arm.set_credential(subscription = sid, client_id = cid, secret = secret, tenant = tid)
 
-It is actually recommended to use environment variables like::
+It is actually recommended to use environment variables. Create a file for credentials like::
 
         $ cat <<EOF > ~/.saz/cred
         export AZURE_SUBSCRIPTION_ID=5s3ag2s5-2aa1-4828-xxxx-9g8sw72w5w5g
@@ -115,38 +124,106 @@ It is actually recommended to use environment variables like::
         export AZURE_CLIENT_SECRET=xxxx
         EOF
 
-And then source it like:
+And then source it before running Python like:
 
 ::
 
         $ source ~/.saz/cred
 
-With the environment variables, no parameters are necessary::
+Now. no parameters are necessary. Simple Azure loads credentials from environment variables::
 
   >> arm.set_credential()
 
 Load Template
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-- URL
-- FILE
+We want to use `101-vm-sshkey
+<https://github.com/Azure/azure-quickstart-templates/tree/master/101-vm-sshkey>`_
+template from the *azure-quickstart-templates* which deploys a Ubuntu
+14.04.4-LTS Virtual Machine with a SSH key injection. ``deploy()`` accepts template
+from URL or a local file as long as it is a JSON format.
+
+From URL::
+
+        >> template_url = 'https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/101-vm-sshkey/azuredeploy.json'
+        >> arm.set_template(template_url)
+
+From FILE::
+
+        >> template_path = "~/101-vm-sshkey/azuredeploy.json"
+        >> arm.set_template(template_path)
 
 Set Parameters
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-- SSH Pub Key
-- TBD
+``101-vm-sshkey`` template requires ssh public key parameter to deploy a VM.
+Simple Azure loads a public key string from the base ssh directory ($HOME/.ssh).
+
+We assume that you already have a SSH key pair generated with a default filename
+(``~/.ssh/id_rsa.pub`` and ``id_rsa``) in your home directory. ``sshkey``
+object contains public key string like:
+
+
+::
+        
+        >> arm.sshkey.pubkey
+        ssh-rsa AAAAB3... hrlee@quickstart
+
+
+We provide this as a parameter like:
+
+::
+
+        >> arm.set_parameter({"sshKeyData": arm.sshkey.pubkey})
+
+.. note:: sshKeyData is a parameter name defined in the template
 
 Deployment
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+The ``101-vm-sshkey`` template contains six (6) resources: 1 Compute, 4 Network
+and 1 Storage to deploy a Ubuntu VM on Azure. Exact resource names are:
+
+- Microsoft.Compute/virtualMachines   
+- Microsoft.Network/networkInterfaces       
+- Microsoft.Network/networkSecurityGroups
+- Microsoft.Network/publicIPAddresses
+- Microsoft.Network/virtualNetworks          
+- Microsoft.Storage/storageAccounts
+
+The relations of these services are visualized via armvis.io `here
+<http://armviz.io/#/?load=https%3A%2F%2Fraw.githubusercontent.com%2FAzure%2Fazure-quickstart-templates%2Fmaster%2F101-vm-sshkey%2Fazuredeploy.json>`_
+
+In Simple Azure, ``deploy()`` function creates a new deployment for these six
+resources by::
+
+        >> arm.deploy()
+
+You can directly call ``deploy()`` function without setting template
+(set_template()) and parameters (set_parameter()) but sending them as function
+parameters like (Both ways work same):
+
 ::
 
-  >> arm.deploy(url, parameters)
+  >> arm.deploy(template_url, parameters)
+
+The status of a deployment is visible on the Azure Portal like:
+
+.. image:: images/sampleazure.png
+
+It may take several minutes to get the VM ready to access via SSH your your
+key.
 
 Termination
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+When Simple Azure terminates VMs in a classic mode (which is using
+ServiceManagement API), each service needs to be deleted seperately, e.g.
+storage, cloud services and virtual machines. In ARM mode, however, a simple
+function call deletes resources in a same unit (a sample resource group or
+deployment).
+
+
 Deleting a deployment is::
 
   >> arm.terminate_deployment()
@@ -155,7 +232,13 @@ Removing a resource group is ::
 
   >> arm.remove_resource_group()
 
-Virtual Machine
+Deployment name or resource group name can be specified as a parameter, if you
+want to clean up other resources as well.
+
+The following sections are for further readings about defining resources in a
+template.
+
+Further Reading: Virtual Machine in Resources
 -------------------------------------------------------------------------------
 
 Starting a new virtual machine (*"Microsoft.Compute/virtualMachines"*)

simpleazure/arm.py

@@ -18,7 +18,7 @@
 from azure.mgmt.resource.resources.models import DeploymentMode as dm
 from . import config
 from . import utils
-
+from template.template import Template
 
 class ARM(object):
     """Constructs a :class:`ARM <ARM>`.
@@ -35,11 +35,12 @@ class ARM(object):
     resource_group = config.DEFAULT_RESOURCE_GROUP
     deployment = config.DEFAULT_DEPLOYMENT
     template = None
-    parameters = None
+    parameters = {}
 
     def __init__(self, subscription=None, client_id=None, secret=None, tenant=None):
         self.sshkey = SSHKey()
         self.get_credential(subscription, client_id, secret, tenant)
+        self.template = Template()
 
     def get_credential(self, subscription=None, client_id=None, secret=None, tenant=None):
         sid = os.getenv('AZURE_SUBSCRIPTION_ID', subscription)
@@ -54,7 +55,7 @@ def get_group_or_create(self):
         self.resource_group = new_name
 
     def deploy(self, template=None, param=None):
-        self.set_sshkey()
+        self.sshkey.set_pubkey()
         self.set_template(template)
         self.set_parameters(param)
         self.set_deployment_properties()
@@ -101,26 +102,22 @@ def set_deployment_properties(self):
                 'template': self.template,
                 'parameters': self.parameters }
 
-    def set_parameters(self, dictv):
-        if self.parameters and dictv is None:
+    def set_parameter(self, param):
+        """Set a single parameter"""
+        param_with_value = self._get_parameters_with_value(param)
+        self.parameters.update(param_with_value)
+        return self.parameters
+
+    def set_parameters(self, params):
+        if self.parameters and params is None:
             return self.parameters
 
-        self.parameters = self._get_parameters_with_value(dictv)
+        self.parameters = self._get_parameters_with_value(params)
 
-    def _get_parameters_with_value(self, dictv):
-        parameters = {k: {'value': v} for k, v in dictv.items()}
+    def _get_parameters_with_value(self, params):
+        parameters = {k: {'value': v} for k, v in params.items()}
         return parameters
-
-    def set_sshkey(self, path=None):
-        try:
-            with open(os.path.expanduser(path or config.DEFAULT_SSH_KEY), "r") as f:
-                self.sshkey.pubkey = f.read()
-                return True
-        except Exception as e:
-            # debug / log 
-            # print (e)
-            return False
-
+
     def set_template(self, path_or_uri=None):
         if self.template and path_or_uri is None:
             return self.template
@@ -130,7 +127,7 @@ def set_template(self, path_or_uri=None):
         else:
             with open(path_or_uri, "r") as temp:
                 template = temp.read()
-        self.template = template
+        self.template['azuredeploy'] = template
 
     def from_github(self, repo):
         # find repo
@@ -159,8 +156,34 @@ def view_info(self):
 # deleted. The default mode is Incremental. 
 # source: https://github.com/dx-ted-emea/Azure-Resource-Manager-Documentation/blob/master/ARM/Templates/Template_Deploy.md
 
+#extra
 class SSHKey(object):
 
     pvkey = None
     pubkey = None
-    path = None
+    pubkey_path = None
+    pvkey_path = None
+
+    default_path = { 
+            'pvkey': "~/.ssh/id_rsa",
+            'pubkey': "~/.ssh/id_rsa.pub" 
+            }
+
+    def __init__(self, path=None):
+        self.set_pubkey(path)
+
+    def set_pubkey(self, path=None):
+        try:
+            path = os.path.expanduser(path or self.default_path['pubkey'])
+            with open(path, "r") as f:
+                self.pubkey = f.read()
+                f.close()
+                self.pubkey_path = path
+                return True
+        except Exception as e:
+            # debug / log 
+            # print (e)
+            return False
+
+
+