=Knife Azure

Description: This plugin supports listing, creating, and deleting Azure instances bootstrapped with chef client.

==Configuration:
Most configuration options can be specified either in your knife.rb file or as command line parameters. The CLI parameters override the knife.rb parameters.

Use --help option to read more about each subcommand. Eg:
      knife azure server create --help

Options common and necessary for all subcommands:
      option :azure_publish_settings_file       Path to your .publishsettings file
OR
      option :azure_subscription_id             Your Azure subscription ID
      option :azure_mgmt_cert                   Management certificate in PEM format
      option :azure_api_host_name               Your Azure API host name

==Management Certifcate
The management certificate is required for secure communication with the Windows Azure Platform via the REST APIs. These can be obtained from the publishsettings file. You need to download the .publishsettings file from the link given below. You can either provide the path to the .publishsettings file OR you can generate the management certificate yourself from the .publishsettings file.

===Management Certificate using the .publishsettings file
Download the .publishsettings file from https://manage.windowsazure.com/publishsettings/index?client=xplat

Set the option :azure_publish_settings_file by specifying the path to the downloaded .publishsettings file. The plugin provides this easy option and will save you the complexity of the second approach listed next.

===Management Certificate in the PEM format
Follow these steps to generate the certificate in the PEM format

1. Download the settings file from https://manage.windowsazure.com/publishsettings/index?client=xplat
2. Extract the data from the ManagementCertificate field into a separate file named - cert.pfx
3. Decode the certificate file :

===== On Linux/Mac(Homebrew)
 base64 -d cert.pfx > cert_decoded.pfx

===== On Windows
You can decode and extract the PFX file using powershell or a free windows base 64 decoder such as http://www.fourmilab.ch/webtools/base64/base64.zip,

 base64.exe -d cert.pfx -> cert_decoded.pfx

4. Convert the decoded PFX file to a PEM file

===== On Linux/Mac(Homebrew)
 openssl pkcs12 -in cert_decoded.pfx -out managementCertificate.pem -nodes

===== On Windows
 Use powershell & run following command. If openssl.exe not already installed it can be downloaded from http://www.openssl.org/related/binaries.html (Note: openssl dependents on Microsoft Visual C++ Redistributable package (x86) which must be installed for openssl to function properly).

 openssl base64 -d -A -in cert_decoded.pfx -out cert_decode.der

 openssl pkcs12 -in cert_decoded.der -out managementCertificate.pem -nodes

You might be asked to enter a password which is usually blank.
You might be also asked to enter a passphrase. Please enter the phrase of your choice.

It is possible to generate your own certificates and upload them. More Detailed Documentation about the Management Certificates is available : https://www.windowsazure.com/en-us/manage/linux/common-tasks/manage-certificates/

==Installation:
The plugin relies on SSL for communication and hence requires the SSL certifcate is setup. The Environment variable SSL_CERT_FILE should point to the full path of the SSL Certificate file.(optional)

Be sure you are running the latest version Chef. Versions earlier than 0.10.0 don’t support plugins.

Run the following command to install knife-azure plugin:
  gem install knife-azure


==Requirements for Bootstrapping Windows:
knife-azure depends on knife-windows: https://github.com/opscode/knife-windows to bootstrap Windows machines via winrm(Basic, NTLM and Kerberos) or ssh.

The distro/template to be used for the same is: https://github.com/opscode/knife-windows/blob/master/lib/chef/knife/bootstrap/windows-chef-client-msi.erb

Windows source images should have the WinRM service enabled and the authentication should be set accordingly(Basic, NTLM and Kerberos). Firewall rules should be added accordingly to the source images. Refer to the link to configure this:
https://github.com/opscode/knife-windows#nodes


==Azure Server Create subcommand
This subcommand provisions a new server in Azure and then performs a Chef bootstrap. The goal of the bootstrap is to get Chef installed on the target system so it can run Chef Client with a Chef Server.

===Azure specific options
      :azure_dns_name                   Required. The DNS prefix name that can be used to access the cloud
                                        service which is unique within Windows Azure. If you want to add
                                        new VM to an existing service/deployment, specify an exiting
                                        dns-name, along with --connect-to-existing-dns option. Otherwise
                                        a new deployment is created.
      :azure_service_location           Required. Specifies the geographic location - the name of data
                                        center location that is valid for your subscription.
                                        Eg: West US, East US, East Asia, Southeast Asia, North Europe, West Europe
      :azure_source_image               Required. Specifies the name of the disk image to use to create
                                        the virtual machine. Do a "knife azure image list" to see a
                                        list of available images.
      :azure_storage_account            A name for the storage account that is unique within Windows Azure.
                                        Storage account names must be between 3 and 24 characters in
                                        length and use numbers and lower-case letters only. This name is
                                        the DNS prefix name and can be used to access blobs, queues, and
                                        tables in the storage account.
      :azure_vm_name                    Specifies the name for the virtual machine. The name must
                                        be unique within the deployment.
      :azure_os_disk_name               Optional. Specifies the friendly name of the disk containing
                                        the guest OS image in the image repository.
      :azure_vm_size                    Size of virtual machine. Default is Small.
                                        (ExtraSmall, Small, Medium, Large, ExtraLarge)
      :azure_connect_to_existing_dns    Set this flag to add the new VM to an existing
                                        deployment/service. Must give the name of the existing
                                        DNS correctly in the --azure-dns-name option

===Azure VM Quick Create
You can create a server with minimal configuration. On the Azure Management Portal, this corresponds to a "Quick Create - VM". Sample command for quick create (for an ubuntu instance):
      knife azure server create
                --azure-publish-settings-file '/path/to/your/cert.publishsettingsfile'
                --azure-dns-name 'myservice'
                --azure-service-location 'West US'
                --azure-source-image 'source-image-name'
                --ssh-user 'jetstream'
                --ssh-password 'jetstream@123'

As mentioned, you can set these options from knife.rb. A typical knife.rb will look as below:
  knife[:azure_publish_settings_file] = '/path/to/your/cert.publishsettingsfile'
  knife[:azure_dns_name] = 'myservice'
  knife[:azure_service_location] = 'West US'
  knife[:azure_source_image] = 'source-image-name'
  knife[:ssh_user] = 'jetstream'
  knife[:ssh_password] = 'jetstream@123'

===Azure VM Advanced Create
You can set various other options in the advanced create.
  Eg: If you want to set the Azure VM Name different from that of the Azure DNS Name, set the option :azure_vm_name.
  Eg: If you want to specify a Storage Account Name, set the option :azure_storage_account

To connect to an existing DNS/service, you can use a command as below:
      knife azure server create
                --azure-subscription-id 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
                --azure-mgmt-cert '/path/to/your/mgmtCert.pem'
                --azure-api-host-name 'management.core.windows.net'
                --connect-to-existing-dns
                --azure-dns-name 'myservice'
                --azure-vm-name 'myvm02'
                --azure-service-location 'West US'
                --azure-source-image 'source-image-name'
                --ssh-user 'jetstream'
                --ssh-password 'jetstream@123'

As mentioned, you can set these options from knife.rb. A typical knife.rb will look as below:
  knife[:azure_subscription_id] = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
  knife[:azure_mgmt_cert] = '/path/to/your/mgmtCert.pem'
  knife[:azure_api_host_name] = 'management.core.windows.net'
  knife[:azure_service_location] = 'West US'
  knife[:azure_dns_name]='myservice'
  knife[:azure_vm_name]='myvm02'
  knife[:ssh_user]='jetstream'
  knife[:identity_file]='/path/to/RSA/private/key'
  knife[:azure_storage_account]='auxpreview104'
  knife[:azure_os_disk_name]='disk107'
  knife[:tcp_endpoints]='66'
  knife[:udp_endpoints]='77,88,99'

===Options for Bootstrapping a Windows Node in Azure

    :bootstrap_protocol           Default is winrm for a windows image
    :winrm_password               The WinRM password
    :winrm_port                   The WinRM port, by default this is 5985
    :winrm_transport              The WinRM transport type.  valid choices are [ssl, plaintext]
    :kerberos_keytab_file         The Kerberos keytab file used for authentication
    :kerberos_realm               The Kerberos realm used for authentication
    :kerberos_service             The Kerberos service used for authentication
    :ca_trust_file                The Certificate Authority (CA) trust file used for SSL transport

===Azure Windows Node Create
The quick create option requires just following options for a windows instance:
      knife azure server create
                --azure-publish-settings-file '/path/to/your/cert.publishsettingsfile'
                --azure-dns-name 'myservice'
                --azure-service-location 'West US'
                --azure-source-image 'windows-image-name'
                --winrm-user 'jetstream'
                --winrm-password 'jetstream@123'
                --template-file 'windows-chef-client-msi.erb'

Sample knife.rb for bootstrapping Windows Node with basic authentication

  knife[:bootstrap_protocol] = 'winrm'
  knife[:winrm_password] = 'mgcvTuvV2Rh'
  knife[:winrm_transport] = 'plaintext'
  knife[:winrm_port] = '5985'
  knife[:distro] = 'windows-chef-client-msi'
  knife[:azure_source_image]='w2k12Basic.vhd'

==Other Subcommands
The plugin also provides the following Knife subcommands. Specific command options can be found by invoking the subcommand with a --help flag

===Azure Server Delete subcommand
Deletes an existing server(role) in the currently configured Azure account. By default, this does not delete the associated node and client objects from the Chef server. To do so, add the --purge flag. Also by default, the DNS / hosted service is deleted if you are deleting the last VM from that service. By default, the OS disk is also deleted. If you want to retain them add the --preserve flag as shown below. To delete the storage account, add the --delete-azure-storage-account flag as by default the storage account is not deleted.
      knife azure server delete "myvm01"
      knife azure server delete "myvm01" --purge  #purge chef node
      knife azure server delete "myvm01" --preserve-azure-os-disk
      knife azure server delete "myvm01" --preserve-azure-dns-name
      knife azure server delete "myvm01" --delete-azure-storage-account
Since the VM name can be same across deployments, you can specify the deployment name also to delete the VM. Sample command to delete a VM from a specific deployment:
      knife azure server delete "myvm01" --azure-dns-name "myservice"
      knife azure server delete "myvm01" "myvm02" --azure-dns-name "myservice"

===Azure Server List subcommand
Outputs a list of all servers in the currently configured Azure account. PLEASE NOTE - this shows all instances associated with the account, some of which may not be currently managed by the Chef server.
      knife azure server list

===Azure Image List subcommand
Outputs a list of all linux images that are available to use for provisioning. You should choose one of these to use for the :azure_source_image parameter to the server create command. You can use the filter option to see a detailed image list.
      knife azure image list


== Understanding Azure
Azure implements the following hierarchy - subscription=>hosted service(dns)=>deployment=>role/VM (and the guest operating system has a hostname as well, which uses the role as its container)

These are generally a one to many relationship from top to bottom, however there are two anomalies relating to the deployment
1) a hosted service can have more than one deployment, but that seems to be an artifact of the PAAS origins of Azure. PAAS allows there to be one staging and one production deployment per hosted service. It is my understanding (and how the code works) that there should be only one deployment per hosted service. Some initial internal code I examined used the technique of looking at the "production" deployment slot to iterate for existing roles. If a create request occurs and a deployment does not exist, it is created and given the same name as the hosted service and the deployment slot is marked as "production".
2) Azure enforces that a deployment must include the initial role when it is created. It also will not allow you to delete a role if it is the last remaining role in a deployment; in that case you are required to delete the deployment.