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

Download the settings file from go.microsoft.com/fwlink/?LinkId=254432
Extract the data from the ManagementCertificate field into a separate file named - cert.pfx
Decode the certificate file :

base64 -d cert.pfx > cert_decoded.pfx

Convert the decoded PFX file to a PEM file

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

It is possible to generate your own certificates and upload them. More Detailed Documentation about the Management Certificates is available : 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:

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:

Due to a bug in mixlib-authentication, Chef node names must be 91 characters or shorter. Chef uses the host name by default, however the host names provided by Azure are very long.

You must use the ‘-N NODE_NAME’ flag with ‘knife azure’ to specify a node name to be used by Chef that is less than 91 characters.

For more information, see tickets.opscode.com/browse/CHEF-3095

Configuration:

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",
:default => "management.core.windows.net"

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",
:default => "root"

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",

option :distro,

:short => "-d DISTRO",
:long => "--distro DISTRO",
:description => "Bootstrap a distro using a template",
:default => "ubuntu10.04-gems"

option :template_file,

:long => "--template-file TEMPLATE",
:description => "Full path to location of template to use",
:default => false

option :run_list,

:short => "-r RUN_LIST",
:long => "--run-list RUN_LIST",
:description => "Comma separated list of roles/recipes to apply",
:default => []

option :no_host_key_verify,

:long => "--no-host-key-verify",
:description => "Disable host key verification",
:boolean => true,
:default => false

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 :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 :storage_account,

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

option :service_location,

:short => "-m LOCATION",
:long => "--service-location LOCATION",
:description => "specify the Geographic location for the virtual machine and services. eg. West US, East US, North Europe East Asia etc"

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'"

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

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

knife = “ManagementCertificate.pem”

knife = “management.core.windows.net”

knife = ‘West US’

knife=‘service001’

knife=‘role105’

knife=‘host105’

knife=‘jetstream’

knife=‘jetstream1!’

knife=‘auxpreview104’

knife=‘disk107’

knife=‘centos5-gems’

knife=‘66’

knife=‘77,88,99’

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

# note that the role_size must be Medium or larger

knife=‘OpenLogic__OpenLogic-CentOS-62-20120509-en-us-30GB.vhd’

knife=‘Medium’

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

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

knife=‘SUSE__OpenSUSE64121-03192012-en-us-15GB.vhd’

knife=‘Small’

Subcommands

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. There is a fix in the works from Christpher Brown in mixlib-authentication I believe that fixes an RSA encryption too long error that occurs for some hostnames during bootstrap. ***)

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.