<commit_before>Introduction
============

This document describes how the Azure provider works; how Azure concepts are
mapped, and some high-level descriptions of how the provider is implemented.


References
==========

Service Management REST API Reference
http://msdn.microsoft.com/library/azure/ee460799.aspx

"What is a cloud service?" (This is out of date, but still somewhat useful.)
http://azure.microsoft.com/en-us/documentation/articles/cloud-services-what-is/

Cloud Services, Virtual Machines and Virtual Network SLA
https://www.microsoft.com/windowsazure/sla/


Azure Concepts
==============

Affinity Group

    An Affinity Group is used to group VMs, storage, etc. within a location.
    It is possible to simply associate each of the entities with the same
    location, however it is recommended to use an Affinity Group. Azure may
    then locate entities as close to each other as possible within a data-
    centre, as opposed to just being in the same data-centre.

    We create an Affinty Group per environment called "juju-<envname>-ag".

Cloud Service

    (AKA "Hosted Service" in API)

    A Cloud Service is a container for VMs, and is the publicly-addressable
    entity for Azure's compute service. Each Cloud Service must have a
    globally-unique name, which is used to derive its domain name. A Cloud-
    Service has only one domain name and public IP address.

    We currently prefix Cloud Services that we create with "juju-<envname>-",
    and randomly generate the remainder of the name.

Deployment

    A Cloud Service may have up to two deployments: Production and Staging.
    The deployments may be swapped at runtime, so that a Staging deployment
    can be upgraded whilst maintaining a Production deployment that can be
    swapped back to should the upgrade go wrong.

    We currently only ever create a Production deployment.

Role

    For our purposes, a Role describes a Virtual Machine (VM). The description
    includes the hostname, initial username and password, attached disk(s),
    network configuration, and which Availability Set (if any) the role belongs
    to.

    A role may have multiple instances (Role Instance), however we only ever
    have one per role. The Juju "Instance" implementation for the Azure
    provider maps to a Role Instance, although the implementation details
    differ between the current and the original implementation.

    A role/instance has only Virtual IPs (VIPs), i.e. internal addresses. The
    role may expose "endpoints", i.e. TCP/UDP ports. Each port may be exposed
    by at most one role in a Cloud Service, unless that port is part of a load-
    balancing set. When a client connects to the containing Cloud Service's
    address + the endpoint port, the traffic will be routed to the role
    instance(s) that expose that endpoint.

Availability Set

    Each Cloud Service has zero or more Availability Sets within it; a Role
    can be assigned to at most one of them. As long as there are at least two
    Roles in the same Availability Set, then Azure will guarantee at least
    99.95% availability under the Azure Service Level Agreement (SLA).

    We create a single Availability Set for each Cloud Service, and all roles
    are added to it. Thus, all Juju-deployed services are, by default, covered
    by the Azure SLA.


Azure provider implementation
=============================

Bootstrapping

    Before the Azure provider can bootstrap an environment, it expects one and
    only one thing to be pre-existing: a storage account; this storage account
    is used for the environment's Storage() implementation. When the
    environment is bootstrapped, the provider creates an affinity group and a
    virtual network.

    The Azure provider now has two modes in which it can operate, configured at
    bootstrap time with the "availability-sets-enabled" boolean attribute. If it
    is true (henceforth "azure-mode"), then support for multiple Roles per Cloud-
    Service is enabled; otherwise there is a single Role per Cloud Service. By
    default, we set availability-sets-enabled=true for new environments.

Starting instances

    When *not* in azure-mode, the provider will simply create a new Cloud-
    Service, Deployment, and Role. The user may use placement directives and
    add machines like in any other provider, but they will not have any
    availability guarantees provided by Azure.<commit_msg>Update doc per fwereade's comments<commit_after>Introduction
============

This document describes how the Azure provider works; how Azure concepts are
mapped, and some high-level descriptions of how the provider is implemented.


References
==========

Service Management REST API Reference
http://msdn.microsoft.com/library/azure/ee460799.aspx

"What is a cloud service?" (This is out of date, but still somewhat useful.)
http://azure.microsoft.com/en-us/documentation/articles/cloud-services-what-is/

Cloud Services, Virtual Machines and Virtual Network SLA
https://www.microsoft.com/windowsazure/sla/


Azure Concepts
==============

Affinity Group

    An Affinity Group is used to group VMs, storage, etc. within a location.
    It is possible to simply associate each of the entities with the same
    location, however it is recommended to use an Affinity Group. Azure may
    then locate entities as close to each other as possible within a data-
    centre, as opposed to just being in the same data-centre.

    We create an Affinty Group per environment called "juju-<envname>-ag".

Cloud Service

    (AKA "Hosted Service" in API)

    A Cloud Service is a container for VMs, and is the publicly-addressable
    entity for Azure's compute service. Each Cloud Service must have a
    globally-unique name, which is used to derive its domain name. A Cloud-
    Service has only one domain name and public IP address.

    We currently prefix Cloud Services that we create with "juju-<envname>-",
    and randomly generate the remainder of the name.

Deployment

    A Cloud Service may have up to two deployments: Production and Staging.
    The deployments may be swapped at runtime, so that a Staging deployment
    can be upgraded whilst maintaining a Production deployment that can be
    swapped back to should the upgrade go wrong.

    We currently only ever create a Production deployment.

Role

    For our purposes, a Role describes a Virtual Machine (VM). The description
    includes the hostname, initial username and password, attached disk(s),
    network configuration, and which Availability Set (if any) the role belongs
    to.

    A role may have multiple instances (Role Instance), however we only ever
    have one per role. The Juju "Instance" implementation for the Azure
    provider maps to a Role Instance, although the implementation details
    differ between the current and the original implementation.

    A role/instance has only Virtual IPs (VIPs), i.e. internal addresses. The
    role may expose "endpoints", i.e. TCP/UDP ports. Each port may be exposed
    by at most one role in a Cloud Service, unless that port is part of a load-
    balancing set. When a client connects to the containing Cloud Service's
    address + the endpoint port, the traffic will be routed to the role
    instance(s) that expose that endpoint.

Availability Set

    Each Cloud Service has zero or more Availability Sets within it; a Role
    can be assigned to at most one of them. As long as there are at least two
    Roles in the same Availability Set, then Azure will guarantee at least
    99.95% availability under the Azure Service Level Agreement (SLA).

    We create a single Availability Set for each Cloud Service, and all roles
    are added to it. Thus, all Juju-deployed services are, by default, covered
    by the Azure SLA.


Azure provider implementation
=============================

Bootstrapping

    Before the Azure provider can bootstrap an environment, it expects one and
    only one thing to be pre-existing: a storage account; this storage account
    is used for the environment's Storage() implementation. When the
    environment is bootstrapped, the provider creates an affinity group and a
    virtual network.

    The Azure provider now has two modes in which it can operate, configured at
    bootstrap time with the "availability-sets-enabled" boolean attribute. If it
    is true (henceforth "azure-mode"), then support for multiple Roles per Cloud-
    Service is enabled; otherwise there is a single Role per Cloud Service. By
    default, we set availability-sets-enabled=true for new environments.

    Note: by setting availability-sets-enabled=false, you will gain the abililty
    to place units on any machine at the cost of losing Azure's SLA guarantees.
    See "Starting instances" below for more details on what is prevented by
    azure-mode.

Starting instances

    When *not* in azure-mode, the provider will simply create a new Cloud-
    Service, Deployment, and Role. The user may use placement directives and
    add machines like in any other provider, but they will not have any
    availability guarantees provided by Azure.
{'fraction_non_alphanumeric': 0.05651936715766503, 'fraction_numerical': 0.002182214948172395, 'mean_word_length': 3.6222894604135147, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 2, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1034623', 'n_tokens_mistral': 2281, 'n_tokens_neox': 2168, 'n_words': 1285}