mirror of
https://github.com/valitydev/salt.git
synced 2024-11-07 00:55:19 +00:00
1487 lines
40 KiB
ReStructuredText
1487 lines
40 KiB
ReStructuredText
==========================
|
|
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.python.org/pypi/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>`_
|
|
|
|
|
|
.. note::
|
|
|
|
The Azure driver is currently being updated to work with the new version of
|
|
the Python Azure SDK, 1.0.0. However until that process is complete, this
|
|
driver will not work with Azure 1.0.0. Please be sure you're running on a
|
|
minimum version of 0.10.2 and less than version 1.0.0.
|
|
|
|
See `Issue #27980`_ for more information.
|
|
|
|
.. _Issue #27980: https://github.com/saltstack/salt/issues/27980
|
|
|
|
|
|
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.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
|
|
|
|
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://msdn.microsoft.com/en-us/library/azure/gg981929.aspx
|
|
|
|
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://msdn.microsoft.com/en-us/library/azure/gg551722.aspx
|
|
|
|
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
|
|
|
|
requests_lib: True
|
|
|
|
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`__
|
|
|
|
.. __: http://azure.microsoft.com/en-us/documentation/articles/virtual-machines-load-balance/
|
|
|
|
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`__
|
|
|
|
.. __: http://azure.microsoft.com/blog/2014/08/14/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.
|