salt/doc/topics/cloud/azure.rst

==========================
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.

More information about Azure is located at `http://www.windowsazure.com/
<http://www.windowsazure.com/>`_.


Dependencies
============
* `Microsoft Azure SDK for Python <https://pypi.org/project/azure/1.0.2>`_ >= 1.0.2
* The python-requests library, for Python < 2.7.9.
* 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:
      driver: 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

      # 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 creating these files, the .cer file will need to be uploaded to
Azure via the "Upload a Management Certificate" action of the "Management Certificates"
tab within the "Settings" section of the management portal.

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

.. note::
    .. versionchanged:: 2015.8.0

    The ``provider`` parameter in cloud provider definitions was renamed to ``driver``. This
    change was made to avoid confusion with the ``provider`` parameter that is used in cloud profile
    definitions. Cloud provider definitions now use ``driver`` to refer to the Salt cloud module that
    provides the underlying functionality to connect to a cloud host, while cloud profiles continue
    to use ``provider`` to refer to provider configurations that you define.

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'
      virtual_network_name: azure-virtual-network
      subnet_name: azure-subnet

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 newinstance test.version


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

affinity_group
--------------
The name of the affinity group to create a VM in. Either a ``location`` or an
``affinity_group`` may be specified, but not both. See Affinity Groups below.

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

service_name
------------
The name of the service in which to create the VM. If this is not specified,
then a service will be created with the same name as the VM.

virtual_network_name
--------------------
Optional. The name of the virtual network for the VM to join. If this is not
specified, then no virtual network will be joined.

subnet_name
------------
Optional. The name of the subnet in the virtual network for the VM to join.
Requires that a ``virtual_network_name`` is specified.


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


Destroying VMs
==============
There are certain options which can be specified in the global cloud
configuration file (usually ``/etc/salt/cloud``) which affect Salt Cloud's
behavior when a VM is destroyed.

cleanup_disks
-------------
.. versionadded:: 2015.8.0

Default is ``False``. When set to ``True``, Salt Cloud will wait for the VM to
be destroyed, then attempt to destroy the main disk that is associated with the
VM.

cleanup_vhds
------------
.. versionadded:: 2015.8.0

Default is ``False``. Requires ``cleanup_disks`` to be set to ``True``. When
also set to ``True``, Salt Cloud will ask Azure to delete the VHD associated
with the disk that is also destroyed.

cleanup_services
----------------
.. versionadded:: 2015.8.0

Default is ``False``. Requires ``cleanup_disks`` to be set to ``True``. When
also set to ``True``, Salt Cloud will wait for the disk to be destroyed, then
attempt to remove the service that is associated with the VM. Because the disk
belongs to the service, the disk must be destroyed before the service can be.


Managing Hosted Services
========================
.. versionadded:: 2015.8.0

An account can have one or more hosted services. A hosted service is required
in order to create a VM. However, as mentioned above, if a hosted service is not
specified when a VM is created, then one will automatically be created with the
name of the name. The following functions are also available.

create_service
--------------
Create a hosted service. The following options are available.

name
~~~~
Required. The name of the hosted service to create.

label
~~~~~
Required. A label to apply to the hosted service.

description
~~~~~~~~~~~
Optional. A longer description of the hosted service.

location
~~~~~~~~
Required, if ``affinity_group`` is not set. The location in which to create the
hosted service. Either the ``location`` or the ``affinity_group`` must be set,
but not both.

affinity_group
~~~~~~~~~~~~~~
Required, if ``location`` is not set. The affinity group in which to create the
hosted service. Either the ``location`` or the ``affinity_group`` must be set,
but not both.

extended_properties
~~~~~~~~~~~~~~~~~~~
Optional. Dictionary containing name/value pairs of hosted service properties.
You can have a maximum of 50 extended property name/value pairs. The maximum
length of the Name element is 64 characters, only alphanumeric characters and
underscores are valid in the Name, and the name must start with a letter.
The value has a maximum length of 255 characters.

CLI Example
~~~~~~~~~~~
The following example illustrates creating a hosted service.

.. code-block:: bash

    salt-cloud -f create_service my-azure name=my-service label=my-service location='West US'

show_service
------------
Return details about a specific hosted service. Can also be called with
``get_service``.

.. code-block:: bash

    salt-cloud -f show_storage my-azure name=my-service

list_services
-------------
List all hosted services associates with the subscription.

.. code-block:: bash

    salt-cloud -f list_services my-azure-config


delete_service
--------------
Delete a specific hosted service.

.. code-block:: bash

    salt-cloud -f delete_service my-azure name=my-service


Managing Storage Accounts
=========================
.. versionadded:: 2015.8.0

Salt Cloud can manage storage accounts associated with the account. The
following functions are available. Deprecated marked as deprecated are marked
as such as per the SDK documentation, but are still included for completeness
with the SDK.

create_storage
--------------
Create a storage account. The following options are supported.

name
~~~~
Required. The name of the storage account to create.

label
~~~~~
Required. A label to apply to the storage account.

description
~~~~~~~~~~~
Optional. A longer description of the storage account.

location
~~~~~~~~
Required, if ``affinity_group`` is not set. The location in which to create the
storage account. Either the ``location`` or the ``affinity_group`` must be set,
but not both.

affinity_group
~~~~~~~~~~~~~~
Required, if ``location`` is not set. The affinity group in which to create the
storage account. Either the ``location`` or the ``affinity_group`` must be set,
but not both.

extended_properties
~~~~~~~~~~~~~~~~~~~
Optional. Dictionary containing name/value pairs of storage account properties.
You can have a maximum of 50 extended property name/value pairs. The maximum
length of the Name element is 64 characters, only alphanumeric characters and
underscores are valid in the Name, and the name must start with a letter. The
value has a maximum length of 255 characters.

geo_replication_enabled
~~~~~~~~~~~~~~~~~~~~~~~
Deprecated. Replaced by the account_type parameter.

account_type
~~~~~~~~~~~~
Specifies whether the account supports locally-redundant storage, geo-redundant
storage, zone-redundant storage, or read access geo-redundant storage. Possible
values are:

- Standard_LRS
- Standard_ZRS
- Standard_GRS
- Standard_RAGRS

CLI Example
~~~~~~~~~~~
The following example illustrates creating a storage account.

.. code-block:: bash

    salt-cloud -f create_storage my-azure name=my-storage label=my-storage location='West US'

list_storage
------------
List all storage accounts associates with the subscription.

.. code-block:: bash

    salt-cloud -f list_storage my-azure-config

show_storage
------------
Return details about a specific storage account. Can also be called with
``get_storage``.

.. code-block:: bash

    salt-cloud -f show_storage my-azure name=my-storage

update_storage
--------------
Update details concerning a storage account. Any of the options available in
``create_storage`` can be used, but the name cannot be changed.

.. code-block:: bash

    salt-cloud -f update_storage my-azure name=my-storage label=my-storage

delete_storage
--------------
Delete a specific storage account.

.. code-block:: bash

    salt-cloud -f delete_storage my-azure name=my-storage

show_storage_keys
-----------------
Returns the primary and secondary access keys for the specified storage account.

.. code-block:: bash

    salt-cloud -f show_storage_keys my-azure name=my-storage

regenerate_storage_keys
-----------------------
Regenerate storage account keys. Requires a key_type ("primary" or "secondary")
to be specified.

.. code-block:: bash

    salt-cloud -f regenerate_storage_keys my-azure name=my-storage key_type=primary


Managing Disks
==============
.. versionadded:: 2015.8.0

When a VM is created, a disk will also be created for it. The following
functions are available for managing disks. Deprecated marked as deprecated are
marked as such as per the SDK documentation, but are still included for
completeness with the SDK.

show_disk
---------
Return details about a specific disk. Can also be called with ``get_disk``.

.. code-block:: bash

    salt-cloud -f show_disk my-azure name=my-disk

list_disks
----------
List all disks associates with the account.

.. code-block:: bash

    salt-cloud -f list_disks my-azure

update_disk
-----------
Update details for a disk. The following options are available.

name
~~~~
Required. The name of the disk to update.

has_operating_system
~~~~~~~~~~~~~~~~~~~~
Deprecated.

label
~~~~~
Required. The label for the disk.

media_link
~~~~~~~~~~
Deprecated. The location of the disk in the account, including the storage
container that it is in. This should not need to be changed.

new_name
~~~~~~~~
Deprecated. If renaming the disk, the new name.

os
~~~
Deprecated.

CLI Example
~~~~~~~~~~~
The following example illustrates updating a disk.

.. code-block:: bash

    salt-cloud -f update_disk my-azure name=my-disk label=my-disk

delete_disk
-----------
Delete a specific disk.

.. code-block:: bash

    salt-cloud -f delete_disk my-azure name=my-disk


Managing Service Certificates
=============================
.. versionadded:: 2015.8.0

Stored at the cloud service level, these certificates are used by your deployed
services. For more information on service certificates, see the following link:

* `Manage Certificates`__

.. __: https://docs.microsoft.com/en-us/azure/cloud-services/cloud-services-certs-create

The following functions are available.

list_service_certificates
-------------------------
List service certificates associated with the account.

.. code-block:: bash

    salt-cloud -f list_service_certificates my-azure

show_service_certificate
------------------------
Show the data for a specific service certificate associated with the account.
The ``name``, ``thumbprint``, and ``thumbalgorithm`` can be obtained from
``list_service_certificates``. Can also be called with
``get_service_certificate``.

.. code-block:: bash

    salt-cloud -f show_service_certificate my-azure name=my_service_certificate \
        thumbalgorithm=sha1 thumbprint=0123456789ABCDEF

add_service_certificate
-----------------------
Add a service certificate to the account. This requires that a certificate
already exists, which is then added to the account. For more information on
creating the certificate itself, see:

* `Create a Service Certificate for Azure`__

.. __: https://msdn.microsoft.com/en-us/library/azure/gg432987.aspx

The following options are available.

name
~~~~
Required. The name of the hosted service that the certificate will belong to.

data
~~~~
Required. The base-64 encoded form of the pfx file.

certificate_format
~~~~~~~~~~~~~~~~~~
Required. The service certificate format. The only supported value is pfx.

password
~~~~~~~~
The certificate password.

.. code-block:: bash

    salt-cloud -f add_service_certificate my-azure name=my-cert \
        data='...CERT_DATA...' certificate_format=pfx password=verybadpass

delete_service_certificate
--------------------------
Delete a service certificate from the account. The ``name``, ``thumbprint``,
and ``thumbalgorithm`` can be obtained from ``list_service_certificates``.

.. code-block:: bash

    salt-cloud -f delete_service_certificate my-azure \
        name=my_service_certificate \
        thumbalgorithm=sha1 thumbprint=0123456789ABCDEF


Managing Management Certificates
================================
.. versionadded:: 2015.8.0

A Azure management certificate is an X.509 v3 certificate used to authenticate
an agent, such as Visual Studio Tools for Windows Azure or a client application
that uses the Service Management API, acting on behalf of the subscription owner
to manage subscription resources. Azure management certificates are uploaded to
Azure and stored at the subscription level. The management certificate store can
hold up to 100 certificates per subscription. These certificates are used to
authenticate your Windows Azure deployment.

For more information on management certificates, see the following link.

* `Manage Certificates`__

.. __: https://msdn.microsoft.com/en-us/library/azure/gg981929.aspx

The following functions are available.

list_management_certificates
----------------------------
List management certificates associated with the account.

.. code-block:: bash

    salt-cloud -f list_management_certificates my-azure

show_management_certificate
---------------------------
Show the data for a specific management certificate associated with the account.
The ``name``, ``thumbprint``, and ``thumbalgorithm`` can be obtained from
``list_management_certificates``. Can also be called with
``get_management_certificate``.

.. code-block:: bash

    salt-cloud -f show_management_certificate my-azure name=my_management_certificate \
        thumbalgorithm=sha1 thumbprint=0123456789ABCDEF

add_management_certificate
--------------------------
Management certificates must have a key length of at least 2048 bits and should
reside in the Personal certificate store. When the certificate is installed on
the client, it should contain the private key of the certificate. To upload to
the certificate to the Microsoft Azure Management Portal, you must export it as
a .cer format file that does not contain the private key. For more information
on creating management certificates, see the following link:

* `Create and Upload a Management Certificate for Azure`__

.. __: https://docs.microsoft.com/en-us/azure/cloud-services/cloud-services-certs-create

The following options are available.

public_key
~~~~~~~~~~
A base64 representation of the management certificate public key.

thumbprint
~~~~~~~~~~
The thumb print that uniquely identifies the management certificate.

data
~~~~
The certificate's raw data in base-64 encoded .cer format.

.. code-block:: bash

    salt-cloud -f add_management_certificate my-azure public_key='...PUBKEY...' \
        thumbprint=0123456789ABCDEF data='...CERT_DATA...'

delete_management_certificate
-----------------------------
Delete a management certificate from the account. The ``thumbprint`` can be
obtained from ``list_management_certificates``.

.. code-block:: bash

    salt-cloud -f delete_management_certificate my-azure thumbprint=0123456789ABCDEF


Virtual Network Management
==========================
.. versionadded:: 2015.8.0

The following are functions for managing virtual networks.

list_virtual_networks
---------------------
List input endpoints associated with the deployment.

.. code-block:: bash

    salt-cloud -f list_virtual_networks my-azure service=myservice deployment=mydeployment


Managing Input Endpoints
========================
.. versionadded:: 2015.8.0

Input endpoints are used to manage port access for roles. Because endpoints
cannot be managed by the Azure Python SDK, Salt Cloud uses the API directly.
With versions of Python before 2.7.9, the ``requests-python`` package needs to
be installed in order for this to work. Additionally, the following needs to be
set in the master's configuration file:

.. code-block:: bash

    backend: requests

The following functions are available.

list_input_endpoints
--------------------
List input endpoints associated with the deployment

.. code-block:: bash

    salt-cloud -f list_input_endpoints my-azure service=myservice deployment=mydeployment

show_input_endpoint
-------------------
Show an input endpoint associated with the deployment

.. code-block:: bash

    salt-cloud -f show_input_endpoint my-azure service=myservice \
        deployment=mydeployment name=SSH

add_input_endpoint
------------------
Add an input endpoint to the deployment. Please note that there may be a delay
before the changes show up. The following options are available.

service
~~~~~~~
Required. The name of the hosted service which the VM belongs to.

deployment
~~~~~~~~~~
Required. The name of the deployment that the VM belongs to. If the VM was
created with Salt Cloud, the deployment name probably matches the VM name.

role
~~~~
Required. The name of the role that the VM belongs to. If the VM was created
with Salt Cloud, the role name probably matches the VM name.

name
~~~~
Required. The name of the input endpoint. This typically matches the port that
the endpoint is set to. For instance, port 22 would be called SSH.

port
~~~~
Required. The public (Internet-facing) port that is used for the endpoint.

local_port
~~~~~~~~~~
Optional. The private port on the VM itself that will be matched with the port.
This is typically the same as the ``port``. If this value is not specified, it
will be copied from ``port``.

protocol
~~~~~~~~
Required. Either ``tcp`` or ``udp``.

enable_direct_server_return
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Optional. If an internal load balancer exists in the account, it can be used
with a direct server return. The default value is ``False``. Please see the
following article for an explanation of this option.

* `Load Balancing for Azure Infrastructure Services`__

.. __: https://docs.microsoft.com/en-us/azure/load-balancer/load-balancer-overview

timeout_for_tcp_idle_connection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Optional. The default value is ``4``. Please see the following article for an
explanation of this option.

* `Configurable Idle Timeout for Azure Load Balancer`__

.. __: https://azure.microsoft.com/en-us/blog/new-configurable-idle-timeout-for-azure-load-balancer/

CLI Example
~~~~~~~~~~~
The following example illustrates adding an input endpoint.

.. code-block:: bash

    salt-cloud -f add_input_endpoint my-azure service=myservice \
        deployment=mydeployment role=myrole name=HTTP local_port=80 \
        port=80 protocol=tcp enable_direct_server_return=False \
        timeout_for_tcp_idle_connection=4

update_input_endpoint
---------------------
Updates the details for a specific input endpoint. All options from
``add_input_endpoint`` are supported.

.. code-block:: bash

    salt-cloud -f update_input_endpoint my-azure service=myservice \
        deployment=mydeployment role=myrole name=HTTP local_port=80 \
        port=80 protocol=tcp enable_direct_server_return=False \
        timeout_for_tcp_idle_connection=4

delete_input_endpoint
---------------------
Delete an input endpoint from the deployment. Please note that there may be a
delay before the changes show up.  The following items are required.

CLI Example
~~~~~~~~~~~
The following example illustrates deleting an input endpoint.

service
~~~~~~~
The name of the hosted service which the VM belongs to.

deployment
~~~~~~~~~~
The name of the deployment that the VM belongs to. If the VM was created with
Salt Cloud, the deployment name probably matches the VM name.

role
~~~~
The name of the role that the VM belongs to. If the VM was created with Salt
Cloud, the role name probably matches the VM name.

name
~~~~
The name of the input endpoint. This typically matches the port that the
endpoint is set to. For instance, port 22 would be called SSH.

.. code-block:: bash

    salt-cloud -f delete_input_endpoint my-azure service=myservice \
        deployment=mydeployment role=myrole name=HTTP


Managing Affinity Groups
========================
.. versionadded:: 2015.8.0

Affinity groups allow you to group your Azure services to optimize performance.
All services and VMs within an affinity group will be located in the same
region. For more information on Affinity groups, see the following link:

* `Create an Affinity Group in the Management Portal`__

.. __: https://msdn.microsoft.com/en-us/library/azure/jj156209.aspx

The following functions are available.

list_affinity_groups
--------------------
List input endpoints associated with the account

.. code-block:: bash

    salt-cloud -f list_affinity_groups my-azure

show_affinity_group
-------------------
Show an affinity group associated with the account

.. code-block:: bash

    salt-cloud -f show_affinity_group my-azure service=myservice \
        deployment=mydeployment name=SSH

create_affinity_group
---------------------
Create a new affinity group. The following options are supported.

name
~~~~
Required. The name of the new affinity group.

location
~~~~~~~~
Required. The region in which the affinity group lives.

label
~~~~~
Required. A label describing the new affinity group.

description
~~~~~~~~~~~
Optional. A longer description of the affinity group.

.. code-block:: bash

    salt-cloud -f create_affinity_group my-azure name=my_affinity_group \
       label=my-affinity-group location='West US'

update_affinity_group
---------------------
Update an affinity group's properties

.. code-block:: bash

    salt-cloud -f update_affinity_group my-azure name=my_group label=my_group

delete_affinity_group
---------------------
Delete a specific affinity group associated with the account

.. code-block:: bash

    salt-cloud -f delete_affinity_group my-azure name=my_affinity_group


Managing Blob Storage
=====================
.. versionadded:: 2015.8.0

Azure storage containers and their contents can be managed with Salt Cloud. This
is not as elegant as using one of the other available clients in Windows, but it
benefits Linux and Unix users, as there are fewer options available on those
platforms.

Blob Storage Configuration
--------------------------
Blob storage must be configured differently than the standard Azure
configuration. Both a ``storage_account`` and a ``storage_key`` must be
specified either through the Azure provider configuration (in addition to the
other Azure configuration) or via the command line.

.. code-block:: yaml

    storage_account: mystorage
    storage_key: ffhj334fDSGFEGDFGFDewr34fwfsFSDFwe==

storage_account
~~~~~~~~~~~~~~~
This is one of the storage accounts that is available via the ``list_storage``
function.

storage_key
~~~~~~~~~~~
Both a primary and a secondary ``storage_key`` can be obtained by running the
``show_storage_keys`` function. Either key may be used.


Blob Functions
--------------
The following functions are made available through Salt Cloud for managing
blog storage.

make_blob_url
~~~~~~~~~~~~~
Creates the URL to access a blob

.. code-block:: bash

    salt-cloud -f make_blob_url my-azure container=mycontainer blob=myblob

container
`````````
Name of the container.

blob
````
Name of the blob.

account
```````
Name of the storage account. If not specified, derives the host base
from the provider configuration.

protocol
````````
Protocol to use: 'http' or 'https'. If not specified, derives the host
base from the provider configuration.

host_base
`````````
Live host base URL.  If not specified, derives the host base from the
provider configuration.


list_storage_containers
~~~~~~~~~~~~~~~~~~~~~~~
List containers associated with the storage account

.. code-block:: bash

    salt-cloud -f list_storage_containers my-azure


create_storage_container
~~~~~~~~~~~~~~~~~~~~~~~~
Create a storage container

.. code-block:: bash

    salt-cloud -f create_storage_container my-azure name=mycontainer

name
````
Name of container to create.

meta_name_values
````````````````
Optional. A dict with name_value pairs to associate with the
container as metadata. Example:{'Category':'test'}

blob_public_access
``````````````````
Optional. Possible values include: container, blob

fail_on_exist
`````````````
Specify whether to throw an exception when the container exists.


show_storage_container
~~~~~~~~~~~~~~~~~~~~~~
Show a container associated with the storage account

.. code-block:: bash

    salt-cloud -f show_storage_container my-azure name=myservice

name
````
Name of container to show.


show_storage_container_metadata
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Show a storage container's metadata

.. code-block:: bash

    salt-cloud -f show_storage_container_metadata my-azure name=myservice

name
````
Name of container to show.

lease_id
````````
If specified, show_storage_container_metadata only succeeds if the
container's lease is active and matches this ID.


set_storage_container_metadata
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Set a storage container's metadata

.. code-block:: bash

    salt-cloud -f set_storage_container my-azure name=mycontainer \
        x_ms_meta_name_values='{"my_name": "my_value"}'

name
````
Name of existing container.
meta_name_values
````````````````
A dict containing name, value for metadata.
Example: {'category':'test'}
lease_id
````````
If specified, set_storage_container_metadata only succeeds if the
container's lease is active and matches this ID.


show_storage_container_acl
~~~~~~~~~~~~~~~~~~~~~~~~~~
Show a storage container's acl

.. code-block:: bash

    salt-cloud -f show_storage_container_acl my-azure name=myservice

name
````
Name of existing container.

lease_id
````````
If specified, show_storage_container_acl only succeeds if the
container's lease is active and matches this ID.


set_storage_container_acl
~~~~~~~~~~~~~~~~~~~~~~~~~
Set a storage container's acl

.. code-block:: bash

    salt-cloud -f set_storage_container my-azure name=mycontainer

name
````
Name of existing container.

signed_identifiers
``````````````````
SignedIdentifers instance

blob_public_access
``````````````````
Optional. Possible values include: container, blob

lease_id
````````
If specified, set_storage_container_acl only succeeds if the
container's lease is active and matches this ID.


delete_storage_container
~~~~~~~~~~~~~~~~~~~~~~~~
Delete a container associated with the storage account

.. code-block:: bash

    salt-cloud -f delete_storage_container my-azure name=mycontainer

name
````
Name of container to create.

fail_not_exist
``````````````
Specify whether to throw an exception when the container exists.

lease_id
````````
If specified, delete_storage_container only succeeds if the
container's lease is active and matches this ID.


lease_storage_container
~~~~~~~~~~~~~~~~~~~~~~~
Lease a container associated with the storage account

.. code-block:: bash

    salt-cloud -f lease_storage_container my-azure name=mycontainer

name
````
Name of container to create.

lease_action
````````````
Required. Possible values: acquire|renew|release|break|change

lease_id
````````
Required if the container has an active lease.

lease_duration
``````````````
Specifies the duration of the lease, in seconds, or negative one
(-1) for a lease that never expires. A non-infinite lease can be
between 15 and 60 seconds. A lease duration cannot be changed
using renew or change. For backwards compatibility, the default is
60, and the value is only used on an acquire operation.

lease_break_period
``````````````````
Optional. For a break operation, this is the proposed duration of
seconds that the lease should continue before it is broken, between
0 and 60 seconds. This break period is only used if it is shorter
than the time remaining on the lease. If longer, the time remaining
on the lease is used. A new lease will not be available before the
break period has expired, but the lease may be held for longer than
the break period. If this header does not appear with a break
operation, a fixed-duration lease breaks after the remaining lease
period elapses, and an infinite lease breaks immediately.

proposed_lease_id
`````````````````
Optional for acquire, required for change. Proposed lease ID, in a
GUID string format.


list_blobs
~~~~~~~~~~
List blobs associated with the container

.. code-block:: bash

    salt-cloud -f list_blobs my-azure container=mycontainer

container
`````````
The name of the storage container

prefix
``````
Optional. Filters the results to return only blobs whose names
begin with the specified prefix.

marker
``````
Optional. A string value that identifies the portion of the list
to be returned with the next list operation. The operation returns
a marker value within the response body if the list returned was
not complete. The marker value may then be used in a subsequent
call to request the next set of list items. The marker value is
opaque to the client.

maxresults
``````````
Optional. Specifies the maximum number of blobs to return,
including all BlobPrefix elements. If the request does not specify
maxresults or specifies a value greater than 5,000, the server will
return up to 5,000 items. Setting maxresults to a value less than
or equal to zero results in error response code 400 (Bad Request).

include
```````
Optional. Specifies one or more datasets to include in the
response. To specify more than one of these options on the URI,
you must separate each option with a comma. Valid values are::

    snapshots:
        Specifies that snapshots should be included in the
        enumeration. Snapshots are listed from oldest to newest in
        the response.
    metadata:
        Specifies that blob metadata be returned in the response.
    uncommittedblobs:
        Specifies that blobs for which blocks have been uploaded,
        but which have not been committed using Put Block List
        (REST API), be included in the response.
    copy:
        Version 2012-02-12 and newer. Specifies that metadata
        related to any current or previous Copy Blob operation
        should be included in the response.

delimiter
`````````
Optional. When the request includes this parameter, the operation
returns a BlobPrefix element in the response body that acts as a
placeholder for all blobs whose names begin with the same
substring up to the appearance of the delimiter character. The
delimiter may be a single character or a string.


show_blob_service_properties
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Show a blob's service properties

.. code-block:: bash

    salt-cloud -f show_blob_service_properties my-azure


set_blob_service_properties
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets the properties of a storage account's Blob service, including
Windows Azure Storage Analytics. You can also use this operation to
set the default request version for all incoming requests that do not
have a version specified.

.. code-block:: bash

    salt-cloud -f set_blob_service_properties my-azure

properties
``````````
a StorageServiceProperties object.

timeout
```````
Optional. The timeout parameter is expressed in seconds.


show_blob_properties
~~~~~~~~~~~~~~~~~~~~
Returns all user-defined metadata, standard HTTP properties, and
system properties for the blob.

.. code-block:: bash

    salt-cloud -f show_blob_properties my-azure container=mycontainer blob=myblob

container
`````````
Name of existing container.

blob
````
Name of existing blob.

lease_id
````````
Required if the blob has an active lease.


set_blob_properties
~~~~~~~~~~~~~~~~~~~
Set a blob's properties

.. code-block:: bash

    salt-cloud -f set_blob_properties my-azure

container
`````````
Name of existing container.

blob
````
Name of existing blob.

blob_cache_control
``````````````````
Optional. Modifies the cache control string for the blob.

blob_content_type
`````````````````
Optional. Sets the blob's content type.

blob_content_md5
````````````````
Optional. Sets the blob's MD5 hash.

blob_content_encoding
`````````````````````
Optional. Sets the blob's content encoding.

blob_content_language
`````````````````````
Optional. Sets the blob's content language.

lease_id
````````
Required if the blob has an active lease.

blob_content_disposition
````````````````````````
Optional. Sets the blob's Content-Disposition header.
The Content-Disposition response header field conveys additional
information about how to process the response payload, and also can
be used to attach additional metadata. For example, if set to
attachment, it indicates that the user-agent should not display the
response, but instead show a Save As dialog with a filename other
than the blob name specified.


put_blob
~~~~~~~~
Upload a blob

.. code-block:: bash

    salt-cloud -f put_blob my-azure container=base name=top.sls blob_path=/srv/salt/top.sls
    salt-cloud -f put_blob my-azure container=base name=content.txt blob_content='Some content'

container
`````````
Name of existing container.

name
````
Name of existing blob.

blob_path
`````````
The path on the local machine of the file to upload as a blob. Either
this or blob_content must be specified.

blob_content
````````````
The actual content to be uploaded as a blob. Either this or blob_path
must me specified.

cache_control
`````````````
Optional. The Blob service stores this value but does not use or
modify it.

content_language
````````````````
Optional. Specifies the natural languages used by this resource.

content_md5
```````````
Optional. An MD5 hash of the blob content. This hash is used to
verify the integrity of the blob during transport. When this header
is specified, the storage service checks the hash that has arrived
with the one that was sent. If the two hashes do not match, the
operation will fail with error code 400 (Bad Request).

blob_content_type
`````````````````
Optional. Set the blob's content type.

blob_content_encoding
`````````````````````
Optional. Set the blob's content encoding.

blob_content_language
`````````````````````
Optional. Set the blob's content language.

blob_content_md5
````````````````
Optional. Set the blob's MD5 hash.

blob_cache_control
``````````````````
Optional. Sets the blob's cache control.

meta_name_values
````````````````
A dict containing name, value for metadata.

lease_id
````````
Required if the blob has an active lease.


get_blob
~~~~~~~~
Download a blob

.. code-block:: bash

    salt-cloud -f get_blob my-azure container=base name=top.sls local_path=/srv/salt/top.sls
    salt-cloud -f get_blob my-azure container=base name=content.txt return_content=True

container
`````````
Name of existing container.

name
````
Name of existing blob.

local_path
``````````
The path on the local machine to download the blob to. Either this or
return_content must be specified.

return_content
``````````````
Whether or not to return the content directly from the blob. If
specified, must be True or False. Either this or the local_path must
be specified.

snapshot
````````
Optional. The snapshot parameter is an opaque DateTime value that,
when present, specifies the blob snapshot to retrieve.

lease_id
````````
Required if the blob has an active lease.

progress_callback
`````````````````
callback for progress with signature function(current, total) where
current is the number of bytes transferred so far, and total is the
size of the blob.

max_connections
```````````````
Maximum number of parallel connections to use when the blob size
exceeds 64MB.
Set to 1 to download the blob chunks sequentially.
Set to 2 or more to download the blob chunks in parallel. This uses
more system resources but will download faster.

max_retries
```````````
Number of times to retry download of blob chunk if an error occurs.

retry_wait
``````````
Sleep time in secs between retries.