Merge lp:~julian-edwards/gwacl/licence-readme-etc into lp:gwacl

Proposed by Julian Edwards on 2013-08-01
Status: Merged
Approved by: Julian Edwards on 2013-08-01
Approved revision: 212
Merged at revision: 209
Proposed branch: lp:~julian-edwards/gwacl/licence-readme-etc
Merge into: lp:gwacl
Diff against target: 202 lines (+148/-24)
3 files modified
HACKING.txt (+102/-2)
LICENSE (+16/-0)
README (+30/-22)
To merge this branch: bzr merge lp:~julian-edwards/gwacl/licence-readme-etc
Reviewer Review Type Date Requested Status
Jeroen T. Vermeulen (community) 2013-08-01 Approve on 2013-08-01
Review via email: mp+177989@code.launchpad.net

Commit message

Clean up of licence info and add a lot more info to HACKING and README.

To post a comment you must log in.
Jeroen T. Vermeulen (jtv) wrote :
Download full text (4.1 KiB)

Oh, this is very nice. Just the overview people will need.

A few odds and ends:

37 +Role instances are virtual machine resources. Many instances may exist in a
38 +deployment (and hence hosted service) but if there is more than one they are
39 +intended to be running the same load balanced application via the service;
40 +they must all share the same DNS entry and open endpoints.

Calling them virtual machine "resources" seems confusingly vague. Isn't a role instance essentially a virtual machine?

Also, is it really true that multiple VMs are meant to run the same application in a load-balanced configuration? My understanding was that you might just as well have different components of the same application (e.g. database, application process, httpd) running on different VMs in the same service. The wording here seems to rule that out.

Might it be more accurate to say that a hosted service exposes one application on the internet, and it may comprise multiple virtual machines for load-balancing and/or different components of the application?

Also, I wouldn't say they "must" all share the same DNS entry — they all share the same DNS entry and the same IP address, and there's no way around it. As for endpoints, they can of course have their own port mappings on that same IP address (and possibly load-balanced shared endpoints, but I never read the documentation for that part).

42 +For this reason, if you want several separate resources, you must create a
43 +separate service, deployment and role instance for each.

"Resources" again is very vague. If there are resources I want to share and ones I don't want to share, this sentence leaves me completely in the dark about what to do.

48 +Each service can only see as much of each other service as any public observer
49 +does. It's possible to place them in a private network so they are
50 +effectively on a share LAN segment with no firewall.

I think these two sentences would fit together more clearly with a "However." The second sentence is a way to escape the limitations laid out by the first, so there's a clear contrast. It's not a case where the second sentence follows naturally on the first.

52 +In Azure this is called a "virtual network". The virtual network must be
53 +defined before any services are created, and then supplied at service creation
54 +time. The virtual network can be assigned any valid networking range which
55 +becomes private to all the virtual instances defined to use it.

The "before any services are created" is a bit ambiguous, to the extent that "any services" here means "any services that will use the virtual network." How about "You can define a virtual network, and supply it when you create a service. This will attach the service to the virtual network for the service's entire lifetime." Some people dislike addressing the reader directly, but it beats having most of the text in passive voice.

Another thing that may puzzle the unschooled reader is "any valid network range which becomes private to all the virtual instances defined to use it." (Where "virtual instances" should probably be "virtual machines"). It reads as if something happens t...

Read more...

review: Approve
212. By Julian Edwards on 2013-08-01

tweaks as per review

Julian Edwards (julian-edwards) wrote :

Ok I've tweaked things. Not always exactly as you want because you like dangling prepositions and they are generally considered bad form :)

Thanks for the review!

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file 'HACKING.txt'
2--- HACKING.txt 2013-07-19 14:44:21 +0000
3+++ HACKING.txt 2013-08-01 07:52:29 +0000
4@@ -20,8 +20,108 @@
5 .. _Bazaar: http://bazaar.canonical.com/
6
7
8-API philosophy
9---------------
10+Overview of Azure
11+-----------------
12+
13+Computing services
14+^^^^^^^^^^^^^^^^^^
15+
16+Azure was originally designed as SaaS for Microsoft Windows and later amended
17+to allow individual virtual machines to run up with Linux distributions.
18+Some remnants of this SaaS architecture remain today, and understanding them
19+is crucial to understanding how GWACL works when spinning up virtual
20+instances.
21+
22+There are three main components to any virtual instance:
23+
24+ * A hosted service
25+ * A deployment
26+ * A role instance
27+
28+Hosted services are the "top level" of a virtual resource. Each one
29+contains up to two deployments, and has its own DNS entry and firewall
30+settings (known as "endpoints" in Azure). The name of the service forms the
31+DNS entry as "<name>.cloudapp.net".
32+
33+Deployments are Azure's abstraction of whether something is running on its
34+staging or production environment. They are only exposed in the API and not
35+the web management UI. Deployments contain one or more role instances.
36+
37+Role instances are virtual machines. Many instances may exist in a deployment
38+(and hence hosted service) but if there is more than one they are intended to
39+be running components from the same application and they will all share the
40+same DNS entry and open endpoints. Thus, a hosted service exposes a single
41+application on the internet and may be composed of multiple role instances
42+for load balancing and differing components.
43+
44+For this reason, if you want several separate applications, you must create a
45+separate service, deployment and role instance for each.
46+
47+Networking across hosted services
48+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
49+
50+Each service can only see as much of each other service as any public observer
51+does, however it's possible to place them in a private network so they are
52+effectively on a share LAN segment with no firewall.
53+
54+In Azure this is called a "virtual network". The virtual network must be
55+defined before any services that use it are created, and then associated at
56+service creation time. The virtual network can be assigned any valid
57+networking range which is then private to all the virtual instances defined to
58+use it.
59+
60+Storage services
61+^^^^^^^^^^^^^^^^
62+
63+Azure supports data storage which is accessed separately to role instances
64+and hosted services. This is organised into several components:
65+
66+ * A storage account
67+ * Containers within an account
68+ * Blobs inside containers
69+
70+A storage account can be created via the web management UI or API. Its name
71+forms the DNS entry for that storage as "<name>.blob.core.windows.net".
72+
73+A container forms the next, and only, level of indirection under the account.
74+You cannot have a container under a container. Containers control the
75+default privacy of files therein.
76+
77+Blobs are the actual files in the storage. They can be of two main types:
78+
79+ * Block blobs
80+ * Page blobs
81+
82+Block blobs are used for sequential access and are optimised for streaming.
83+Page blobs are used for random access and allow access to ranges of bytes in a
84+blob.
85+
86+The full URL to a file in a storage account looks like:
87+
88+ https://<accountname>.blob.core.windows.net/<containername>/<blobname>
89+
90+
91+RESTful API access
92+------------------
93+
94+There are two API endpoints for Azure, the management API and the storage API.
95+Each also uses its own authentication method:
96+
97+ * x509 certificates for the management API
98+ * HMAC signed request for the storage API
99+
100+The GWACL code hides most of this complexity from you, it just requires the
101+cerificate data for the management API access, and the storage key for storage
102+API access.
103+
104+The storage key can be fetched either from the management UI, or management
105+API call.
106+
107+Generating x509 certificates is explained in the :doc:`README <README>`
108+
109+
110+GWACL's API philosophy
111+----------------------
112
113 API functions in the library should take a single struct parameter, which
114 itself contains one or more parameters. Existing functions that do not follow
115
116=== added file 'LICENSE'
117--- LICENSE 1970-01-01 00:00:00 +0000
118+++ LICENSE 2013-08-01 07:52:29 +0000
119@@ -0,0 +1,16 @@
120+GWACL - Go API for talking to Windows Azure.
121+
122+Copyright 2012-2013, Canonical Ltd.
123+
124+Except where explicitly noted, all files herein are part of GWACL.
125+
126+GWACL is free software: you can redistribute it and/or modify it under the
127+terms of the GNU Lesser General Public License as published by the Free
128+Software Foundation, either version 3 of the License, or (at your option) any
129+later version.
130+
131+This program is distributed in the hope that it will be useful, but WITHOUT ANY
132+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
133+PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
134+
135+See COPYING for the full terms of the GNU Lesser General Public License.
136
137=== modified file 'README'
138--- README 2013-07-22 14:14:42 +0000
139+++ README 2013-08-01 07:52:29 +0000
140@@ -3,11 +3,8 @@
141 ===========================================
142
143
144-(Work In Progress)
145-
146-
147-Generate an x509 key to talk to Azure
148--------------------------------------
149+How to generate an x509 key to talk to Azure
150+--------------------------------------------
151
152 Azure requires that API clients use an x509 certificate to authenticate to the
153 management API. Create the certificate with::
154@@ -27,20 +24,31 @@
155 You can now upload ``azure.cer`` to Azure as a management certificate.
156
157
158-Licensing
159----------
160-
161-Except where explicitly noted, all files herein are part of GWACL.
162-
163-GWACL is free software: you can redistribute it and/or modify it under
164-the terms of the GNU Lesser General Public License as published by the
165-Free Software Foundation, either version 3 of the License, or (at your
166-option) any later version.
167-
168-GWACL is distributed in the hope that it will be useful, but WITHOUT ANY
169-WARRANTY; without even the implied warranty of MERCHANTABILITY or
170-FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
171-License for more details.
172-
173-You should have received a copy of the GNU Lesser General Public License
174-along with GWACL. If not, see <http://www.gnu.org/licenses/>.
175+Using the key in GWACL
176+----------------------
177+
178+GWACL requires the key in the .pem file, so make sure you keep that file
179+around. The .cer file can be deleted as you won't need it again, and it's easy
180+to regenerate if you want to re-upload it.
181+
182+
183+Example programs
184+----------------
185+
186+Storage
187+^^^^^^^
188+
189+The storage example is a stand-alone tool which allows the user to manipulate
190+a storage account::
191+
192+ go run example/storage/run.go --help
193+
194+Management
195+^^^^^^^^^^
196+
197+The management example is a piece of code that starts up a new role instance,
198+optionally pauses so you can play with it, and then shuts everything down
199+again. It is intended to be useful for testing the library itself, but also
200+serves as an example of how to use the GWACL API::
201+
202+ go run example/management/run.go -cert <your pem file> -subscriptionid <your Azure subscription ID> [-wait]

Subscribers

People subscribed via source and target branches

to all changes: