==========================
Getting Started With Azure
==========================

.. versionadded:: 2014.1.0

Azure is a cloud service by Microsoft providing virtual machines, SQL services,
media services, and more. This document describes how to use Salt Cloud to
create a virtual machine on Azure, with Salt installed.

You can find more information about Azure at `http://www.windowsazure.com/ 
<http://www.windowsazure.com/>`_.


Dependencies
============
* The `Azure <https://pypi.python.org/pypi/azure>`_ Python SDK.
* A Microsoft Azure account
* OpenSSL (to generate the certificates)
* `Salt <https://github.com/saltstack/salt>`_


Configuration
=============

Set up the provider config at ``/etc/salt/cloud.providers.d/azure.conf``:

.. code-block:: yaml

    # Note: This example is for /etc/salt/cloud.providers.d/azure.conf

    my-azure-config:
      provider: azure
      subscription_id: 3287abc8-f98a-c678-3bde-326766fd3617
      certificate_path: /etc/salt/azure.pem

      # Set up the location of the salt master
      #
      minion:
        master: saltmaster.example.com

      provider: azure

      # Optional
      management_host: management.core.windows.net

The certificate used must be generated by the user. OpenSSL can be used to
create the management certificates. Two certificates are needed: a .cer file,
which is uploaded to Azure, and a .pem file, which is stored locally.

To create the .pem file, execute the following command:

.. code-block:: bash

    openssl req -x509 -nodes -days 365 -newkey rsa:1024 -keyout /etc/salt/azure.pem -out /etc/salt/azure.pem

To create the .cer file, execute the following command:

.. code-block:: bash

    openssl x509 -inform pem -in /etc/salt/azure.pem -outform der -out /etc/salt/azure.cer

After you creating these files, the .cer file will need to be uploaded to
Azure via the "Upload" action of the "Settings" tab of the management portal.

Optionally, a ``management_host`` may be configured, if necessary for your
region.


Cloud Profiles
==============
Set up an initial profile at ``/etc/salt/cloud.profiles``:

.. code-block:: yaml

    azure-ubuntu:
      provider: my-azure-config
      image: 'b39f27a8b8c64d52b05eac6a62ebad85__Ubuntu-12_04_3-LTS-amd64-server-20131003-en-us-30GB'
      size: Small
      location: 'East US'
      ssh_username: azureuser
      ssh_password: verybadpass
      slot: production
      media_link: 'http://portalvhdabcdefghijklmn.blob.core.windows.net/vhds'

These options are described in more detail below. Once configured, the profile
can be realized with a salt command:

.. code-block:: bash

    salt-cloud -p azure-ubuntu newinstance

This will create an salt minion instance named ``newinstance`` in Azure. If
the command was executed on the salt-master, its Salt key will automatically
be signed on the master.

Once the instance has been created with salt-minion installed, connectivity to
it can be verified with Salt:

.. code-block:: bash

    salt newminion test.ping


Profile Options
===============
The following options are currently available for Azure.

provider
--------
The name of the provider as configured in
`/etc/salt/cloud.providers.d/azure.conf`.

image
-----
The name of the image to use to create a VM. Available images can be viewed
using the following command:

.. code-block:: bash

    salt-cloud --list-images my-azure-config

size
----
The name of the size to use to create a VM. Available sizes can be viewed using
the following command:

.. code-block:: bash

    salt-cloud --list-sizes my-azure-config

location
--------
The name of the location to create a VM in. Available locations can be viewed
using the following command:

.. code-block:: bash

    salt-cloud --list-locations my-azure-config

ssh_username
------------
The user to use to log into the newly-created VM to install Salt.

ssh_password
------------
The password to use to log into the newly-created VM to install Salt.

slot
----
The environment to which the hosted service is deployed. Valid values are
`staging` or `production`. When set to `production`, the resulting URL of the
new VM will be `<vm_name>.cloudapp.net`. When set to `staging`, the resulting
URL will contain a generated hash instead.

media_link
----------
This is the URL of the container that will store the disk that this VM uses.
Currently, this container must already exist. If a VM has previously been
created in the associated account, a container should already exist. In the web
interface, go into the Storage area and click one of the available storage
selections. Click the Containers link, and then copy the URL from the container
that will be used. It generally looks like:

.. code-block:: yaml

    http://portalvhdabcdefghijklmn.blob.core.windows.net/vhds


Show Instance
=============
This action is a thin wrapper around ``--full-query``, which displays details on
a single instance only. In an environment with several machines, this will save
a user from having to sort through all instance data, just to examine a single
instance.

.. code-block:: bash

    salt-cloud -a show_instance myinstance