knife-azure plugin source.
Pull request Compare This branch is 1233 commits behind chef:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Knife Azure

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

Generating the Management Certifcate (PEM)

The Management Certificate is required for secure communication with the Windows Azure Platform via the REST APIs. Follow these steps to generate the certificate

  1. Download the settings file from

  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,

base64.exe -d cert.pfx -> cert_decoded.pfx
  1. 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 (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 :


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:

gem install chef

This plugin is distributed as a Ruby Gem. To install it, with missing dependencies run:

bundle install

If you make any changes to the knife plugin code and want to re-install the plugin:

rake install

Depending on your system’s configuration, you may need to run this command with root privileges.

Requirements for Bootstrapping Windows:

knife-azure depends on knife-windows: to bootstrap Windows machines via winrm(Basic, NTLM and Kerberos) or ssh.

The distro/template to be used for the same is:

Windows source images should have the WinRM service enabled and the authentication should be set accordingly(Basic, NTLM and Kerberos).


Most configuration options can be specified either in your knife.rb file or as command line parameters.

Options common and necessary for all subcommands: option :azure_subscription_id,

:short => "-S ID",
:long => "--azure-subscription-id ID",
:description => "Your Azure subscription ID",

option :azure_mgmt_cert,

:short => "-p FILENAME",
:long => "--azure-mgmt-cert FILENAME",
:description => "Your Azure Management Certificate File",

option :azure_host_name,

:short => "-H HOSTNAME",
:long => "--azure_host_name HOSTNAME",
:description => "Your Azure host name",

option :verify_ssl_cert,

:long => "--verify-ssl-cert",
:description => "Verify SSL Certificates for communication over HTTPS",
:boolean => true,
:default => false

Options used with the Create subcommand: option :chef_node_name,

:short => "-N NAME",
:long => "--node-name NAME",
:description => "The Chef node name for your new node"

option :ssh_user,

:short => "-x USERNAME",
:long => "--ssh-user USERNAME",
:description => "The ssh username"

option :ssh_password,

:short => "-P PASSWORD",
:long => "--ssh-password PASSWORD",
:description => "The ssh password"

option :identity_file,

:short => "-i IDENTITY_FILE",
:long => "--identity-file IDENTITY_FILE",
:description => "The SSH identity file used for authentication"

option :prerelease,

:long => "--prerelease",
:description => "Install the pre-release chef gems"

option :bootstrap_version,

:long => "--bootstrap-version VERSION",
:description => "The version of Chef to install",
:proc => { |v| Chef::Config[:knife][:bootstrap_version] = v }

option :distro,

:short => "-d DISTRO",
:long => "--distro DISTRO",
:description => "Bootstrap a distro using a template",
:proc => { |d| Chef::Config[:knife][:distro] = d },
:default => "chef-full"

option :template_file,

:long => "--template-file TEMPLATE",
:description => "Full path to location of template to use",
:proc => { |t| Chef::Config[:knife][:template_file] = t },
:default => false

option :run_list,

:short => "-r RUN_LIST",
:long => "--run-list RUN_LIST",
:description => "Comma separated list of roles/recipes to apply",
:proc => lambda { |o| o.split(/[\s,]+/) },
:default => []

option :host_key_verify,

:long => "--[no-]host-key-verify",
:description => "Verify host key, enabled by default.",
:boolean => true,
:default => true

option :hosted_service_name,

:short => "-s NAME",
:long => "--hosted-service-name NAME",
:description => "specifies the name for the hosted service"

option :hosted_service_description,

:short => "-D DESCRIPTION",
:long => "--hosted_service_description DESCRIPTION",
:description => "Description for the hosted service"

option :storage_account,

:short => "-a NAME",
:long => "--storage-account NAME",
:description => "specifies the name for the hosted service"

option :role_name,

:short => "-R name",
:long => "--role-name NAME",
:description => "specifies the name for the virtual machine"

option :host_name,

:long => "--host-name NAME",
:description => "specifies the host name for the virtual machine"

option :service_location,

:short => "-m LOCATION",
:long => "--service-location LOCATION",
:description => "specify the Geographic location for the virtual machine and services"

option :os_disk_name,

:short => "-o DISKNAME",
:long => "--os-disk-name DISKNAME",
:description => "unique name for specifying os disk (optional)"

option :source_image,

:short => "-I IMAGE",
:long => "--source-image IMAGE",
:description => "disk image name to use to create virtual machine"

option :role_size,

:short => "-z SIZE",
:long => "--role-size SIZE",
:description => "size of virtual machine (ExtraSmall, Small, Medium, Large, ExtraLarge)"

option :tcp_endpoints,

:short => "-t PORT_LIST",
:long => "--tcp-endpoints PORT_LIST",
:description => "Comma separated list of TCP local and public ports to open i.e. '80:80,433:5000'"

option :udp_endpoints,

:short => "-u PORT_LIST",
:long => "--udp-endpoints PORT_LIST",
:description => "Comma separated list of UDP local and public ports to open i.e. '80:80,433:5000'"

Options for Bootstrapping Windows nodes

option :bootstrap_protocol,

:long => "--bootstrap-protocol protocol",
:description => "Protocol to bootstrap windows servers. options: winrm/ssh",
:default => "winrm"

option :winrm_password

:short => "-P PASSWORD",
:long => "--winrm-password PASSWORD",
:description => "The WinRM password",

option :winrm_port,

:short => "-p PORT",
:long => "--winrm-port PORT",
:description => "The WinRM port, by default this is 5985",
:default => "5985",

option :identity_file,

:short => "-i IDENTITY_FILE",
:long => "--identity-file IDENTITY_FILE",
:description => "The SSH identity file used for authentication"

option :winrm_transport,

:short => "-t TRANSPORT",
:long => "--winrm-transport TRANSPORT",
:description => "The WinRM transport type.  valid choices are [ssl, plaintext]",
:default => 'plaintext',

option :kerberos_keytab_file,

:short => "-i KEYTAB_FILE",
:long => "--keytab-file KEYTAB_FILE",
:description => "The Kerberos keytab file used for authentication",

option :kerberos_realm,

:short => "-R KERBEROS_REALM",
:long => "--kerberos-realm KERBEROS_REALM",
:description => "The Kerberos realm used for authentication",

option :kerberos_service,

:short => "-S KERBEROS_SERVICE",
:long => "--kerberos-service KERBEROS_SERVICE",
:description => "The Kerberos service used for authentication",

option :ca_trust_file,

:short => "-f CA_TRUST_FILE",
:long => "--ca-trust-file CA_TRUST_FILE",
:description => "The Certificate Authority (CA) trust file used for SSL transport",

Here are some lines with example values in a knife.rb file:

knife = “155a9851-88a8-49b4-98e4-58055f08f412”

knife = “ManagementCertificate.pem”

knife = “”

knife = 'West US'











# To use the CentOS image, the following lines are necessary

# note that the role_size must be Medium or larger



# Alternatively, at the present time you could use a SUSE image

# note that you can use Small or ExtraSmall for the role_size



Sample knife.rb for bootstrapping Windows Node with Basic Authentication

knife = 'winrm'

knife = 'mgcvTuvV2Rh'

knife = 'plaintext'

knife = '5985'

knife = 'windows-chef-client-msi'



This plugin provides the following Knife subcommands. Specific command options can be found by invoking the subcommand with a –help flag

knife azure server create

Provisions a new server in Azure and then perform a Chef bootstrap (using the SSH protocol). The goal of the bootstrap is to get Chef installed on the target system so it can run Chef Client with a Chef Server. The main assumption is a baseline OS installation exists (provided by the provisioning). It is primarily intended for Chef Client systems that talk to a Chef server. By default the server is bootstrapped using the ubuntu10.04-gems template. This can be overridden using the -d or –template-file command options. (*** Note that at the current time only CentOS is supported for bootstrapping and required the :distro to be set to centos5-gems. ***)

knife azure server delete [role_name_to_delete]

Deletes an existing server(role) in the currently configured Azure account. PLEASE NOTE - By default, this does not delete the associated node and client objects from the Chef server. To do so, add the –purge flag.

knife azure server list

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 describe [role_name_to_describe]

Outputs detail about a specific role, including all the ports that it has open

knife azure image list

Outputs a list of all linux images that are available to use for provisioning. You should choose one of these to use for the :source_image parameter to the server create command.

knife azure server describe

Output additional information about the provisioned Virtual Machine

Understanding Azure

Azure implements the following hierarchy - subscription=>hosted service=>deployment=>role (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 anamolies 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.