1
=== added file 'doc/azure-provider.txt'
2
--- doc/azure-provider.txt	1970-01-01 00:00:00 +0000
3
+++ doc/azure-provider.txt	2014-04-08 03:24:31 +0000
4
@@ -0,0 +1,160 @@
5
1
Introduction
6
2
============
7
3
8
4
This document describes how the Azure provider works; how Azure concepts are
9
5
mapped, and some high-level descriptions of how the provider is implemented.
10
6
11
7
12
8
References
13
9
==========
14
10
15
11
Service Management REST API Reference
16
12
http://msdn.microsoft.com/library/azure/ee460799.aspx
17
13
18
14
"What is a cloud service?" (This is out of date, but still somewhat useful.)
19
15
http://azure.microsoft.com/en-us/documentation/articles/cloud-services-what-is/
20
16
21
17
Cloud Services, Virtual Machines and Virtual Network SLA
22
18
https://www.microsoft.com/windowsazure/sla/
23
19
24
20
25
21
Azure Concepts
26
22
==============
27
23
28
24
Affinity Group
29
25
30
26
    An Affinity Group is used to group VMs, storage, etc. within a location.
31
27
    It is possible to simply associate each of the entities with the same
32
28
    location, however it is recommended to use an Affinity Group. Azure may
33
29
    then locate entities as close to each other as possible within a data-
34
30
    centre, as opposed to just being in the same data-centre.
35
31
36
32
    We create an Affinty Group per environment called "juju-<envname>-ag".
37
33
38
34
Cloud Service
39
35
40
36
    (AKA "Hosted Service" in API)
41
37
42
38
    A Cloud Service is a container for VMs, and is the publicly-addressable
43
39
    entity for Azure's compute service. Each Cloud Service must have a
44
40
    globally-unique name, which is used to derive its domain name. A Cloud-
45
41
    Service has only one domain name and public IP address.
46
42
47
43
    We currently prefix Cloud Services that we create with "juju-<envname>-",
48
44
    and randomly generate the remainder of the name.
49
45
50
46
Deployment
51
47
52
48
    A Cloud Service may have up to two deployments: Production and Staging.
53
49
    The deployments may be swapped at runtime, so that a Staging deployment
54
50
    can be upgraded whilst maintaining a Production deployment that can be
55
51
    swapped back to should the upgrade go wrong.
56
52
57
53
    We currently only ever create a Production deployment.
58
54
59
55
Role
60
56
61
57
    For our purposes, a Role describes a Virtual Machine (VM). The description
62
58
    includes the hostname, initial username and password, attached disk(s),
63
59
    network configuration, and which Availability Set (if any) the role belongs
64
60
    to.
65
61
66
62
    A role may have multiple instances (Role Instance), however we only ever
67
63
    have one per role. The Juju "Instance" implementation for the Azure
68
64
    provider maps to a Role Instance, although the implementation details
69
65
    differ between the current and the original implementation.
70
66
71
67
    A role/instance has only Virtual IPs (VIPs), i.e. internal addresses. The
72
68
    role may expose "endpoints", i.e. TCP/UDP ports. Each port may be exposed
73
69
    by at most one role in a Cloud Service, unless that port is part of a load-
74
70
    balancing set. When a client connects to the containing Cloud Service's
75
71
    address + the endpoint port, the traffic will be routed to the role
76
72
    instance(s) that expose that endpoint.
77
73
78
74
Availability Set
79
75
80
76
    Each Cloud Service has zero or more Availability Sets within it; a Role
81
77
    can be assigned to at most one of them. As long as there are at least two
82
78
    Roles in the same Availability Set, then Azure will guarantee at least
83
79
    99.95% availability under the Azure Service Level Agreement (SLA).
84
80
85
81
    We create a single Availability Set for each Cloud Service, and all roles
86
82
    are added to it. Thus, all Juju-deployed services are, by default, covered
87
83
    by the Azure SLA.
88
84
89
85
90
86
Azure provider implementation
91
87
=============================
92
88
93
89
Bootstrapping
94
90
95
91
    Before the Azure provider can bootstrap an environment, it expects one and
96
92
    only one thing to be pre-existing: a storage account; this storage account
97
93
    is used for the environment's Storage() implementation. When the
98
94
    environment is bootstrapped, the provider creates an affinity group and a
99
95
    virtual network.
100
96
101
97
    The Azure provider now has two modes in which it can operate, configured at
102
98
    bootstrap time with the "availability-sets-enabled" boolean attribute. If it
103
99
    is true (henceforth "azure-mode"), then support for multiple Roles per Cloud-
104
100
    Service is enabled; otherwise there is a single Role per Cloud Service. By
105
101
    default, we set availability-sets-enabled=true for new environments.
106
102
107
103
    Note: by setting availability-sets-enabled=false, you will gain the abililty
108
104
    to place units on any machine at the cost of losing Azure's SLA guarantees.
109
105
    See "Starting instances" below for more details on what is prevented by
110
106
    azure-mode.
111
107
112
108
Starting instances
113
109
114
110
    When *not* in azure-mode, the provider will simply create a new Cloud-
115
111
    Service, Deployment, and Role. The user may use placement directives and
116
112
    add machines like in any other provider, but they will not have any
117
113
    availability guarantees provided by Azure.
118
114
119
115
    When in azure-mode, the provider must impose several restrictions to
120
116
    achieve availability guarantees:
121
117
        - placement (i.e. --to <machine>) is disallowed,
122
118
        - "juju add-machine" is disallowed.
123
119
    Thus, an instance can only be created in response to adding a unit to a
124
120
    service, and an instance can contain only units of a single service type.
125
121
126
122
    Instances are deployed to the same Cloud Service as the other instances
127
123
    of its "Distribution Group" (a new Juju provisioning concept introduced
128
124
    to support azure-mode, Availability Zones, etc.), or a new Cloud Service
129
125
    if the group is empty. For a state server, the Distribution Group is the
130
126
    set of instances that contain other state server instances; for any other
131
127
    instance, the Distribution Group is the set of instances that contain units
132
128
    of the same service that the instance is being provisioned for.  All new
133
129
    instances are added to the same Availability Set within the Cloud Service.
134
130
135
131
Instance mapping
136
132
137
133
    In the Azure provider, we map instance IDs to a Role within a Cloud-
138
134
    Service. The instance-id format is servicename-rolename, where servicename
139
135
    is the name of the Cloud Service and rolename is the name of the Role. We
140
136
    only ever have one Deployment in a Cloud Service, so it is inferred.
141
137
142
138
    Originally the provider was written such that instance IDs mapped only to
143
139
    Cloud Services, as originally there was a one-to-one correspondence between
144
140
    Juju-deployed Cloud Services and Roles. This has had to change to cater for
145
141
    Azure's recommended high availability practices. We maintain backwards
146
142
    compatability with old deployments; existing Cloud Services are assumed
147
143
    to have a single role within.
148
144
149
145
Exposing Services
150
146
151
147
    Because a Cloud Service has a single public IP, and instances within do
152
148
    not have their own, exposed services will have their ports load balanced
153
149
    across each instance whose unit opens the port. Load balancing only takes
154
150
    effect when connecting to the public (Cloud Service) address.
155
151
156
152
    In azure-mode, the state server and API server ports are automatically
157
153
    load-balanced. When HA Juju is enabled, this means that API client
158
154
    connections will be load balanced automatically by Azure.
159
155
160
156
    In azure-mode, the SSH port is also load-balanced so that port 22 may be
161
157
    used uniformly across providers. To ensure that "juju ssh" connects to
162
158
    the correct instance, we connect to the instance's internal address by
163
159
    first proxying through the API server.
164
160
Status:	Merged
Approved by:	Andrew Wilkins on 2014-04-08
Approved revision:	no longer in the source branch.
Merged at revision:	2581
Proposed branch:	lp:~axwalk/juju-core/azure-provider-doc
Merge into:	lp:~go-bot/juju-core/trunk
Diff against target:	164 lines (+160/-0) 1 file modified doc/azure-provider.txt (+160/-0)
To merge this branch:	bzr merge lp:~axwalk/juju-core/azure-provider-doc
Related bugs:	Link a bug report
Reviewer	Review Type	Date Requested	Status
Juju Engineering		2014-04-07	Pending
Review via email: mp+214478@code.launchpad.net