@@ -1,17 +1,23 @@
11{-# LANGUAGE Arrows #-}
22module Network.Azure.ServiceManagement
33 ( -- * Data types
4− HostedService(..)
5− , CloudService(..)
6− , VirtualMachine(..)
7− , Endpoint(..)
4+ CloudService
5+ , cloudServiceName
6+ , cloudServiceVMs
7+ , VirtualMachine
8+ , vmName
9+ , vmIpAddress
10+ , vmInputEndpoints
11+ , Endpoint
12+ , endpointName
13+ , endpointPort
14+ , endpointVip
815 -- * Pure functions
916 , vmSshEndpoint
1017 -- * Setup
1118 , AzureSetup(..)
1219 , azureSetup
1320 -- * High-level API
14− , hostedServices
1521 , cloudServices
1622 ) where
1723
@@ -62,11 +68,7 @@ import Text.XML.HXT.Core
6268 , IOSArrow
6369 , ArrowXml
6470 , getText
65−-- , writeDocumentToString
66−-- , withIndent
67−-- , yes
6871 )
69−-- import Control.Arrow.ArrowIO (arrIO)
7072import Text.XML.HXT.XPath (getXPathTrees)
7173
7274--------------------------------------------------------------------------------
@@ -77,20 +79,39 @@ data HostedService = HostedService {
7779 hostedServiceName :: String
7880 }
7981
82+-- | A cloud service is a bunch of virtual machines that are part of the same
83+-- network (i.e., can talk to each other directly using standard TCP
84+-- connections).
8085data CloudService = CloudService {
86+ -- | Name of the service.
8187 cloudServiceName :: String
88+ -- | Virtual machines that are part of this cloud service.
8289 , cloudServiceVMs :: [VirtualMachine]
8390 }
8491
92+-- | Virtual machine
8593data VirtualMachine = VirtualMachine {
94+ -- | Name of the virtual machine.
8695 vmName :: String
96+ -- | The /internal/ IP address of the virtual machine (that is, the
97+ -- IP address on the Cloud Service). For the globally accessible IP
98+ -- address see 'vmInputEndpoints'.
8799 , vmIpAddress :: String
100+ -- | Globally accessible endpoints to the virtual machine
88101 , vmInputEndpoints :: [Endpoint]
89102 }
90103
104+-- | Globally accessible endpoint for a virtual machine
91105data Endpoint = Endpoint {
106+ -- | Name of the endpoint (typical example: @SSH@)
92107 endpointName :: String
108+ -- | Port number (typical examples are 22 or high numbered ports such as 53749)
93109 , endpointPort :: String
110+ -- | Virtual IP address (that is, globally accessible IP address).
111+ --
112+ -- This corresponds to the IP address associated with the Cloud Service
113+ -- (i.e., that would be returned by a DNS lookup for @name.cloudapp.net@,
114+ -- where @name@ is the name of the Cloud Service).
94115 , endpointVip :: String
95116 }
96117
@@ -148,6 +169,7 @@ hang2 d1 = hang d1 2
148169-- Pure operations --
149170--------------------------------------------------------------------------------
150171
172+-- | Find the endpoint with name @SSH@.
151173vmSshEndpoint :: VirtualMachine -> Maybe Endpoint
152174vmSshEndpoint vm = listToMaybe
153175 [ ep
@@ -160,11 +182,21 @@ vmSshEndpoint vm = listToMaybe
160182--------------------------------------------------------------------------------
161183
162184-- | Azure setup
185+--
186+-- The documentation of "distributed-process-azure" explains in detail how
187+-- to obtain the SSL client certificate and the private key for your Azure
188+-- account.
189+--
190+-- See also 'azureSetup'.
163191data AzureSetup = AzureSetup
164− { subscriptionId :: String
165− , certificate :: X509
166− , privateKey :: PrivateKey
167− , baseUrl :: String
192+ { -- | Azure subscription ID
193+ subscriptionId :: String
194+ -- | SSL client certificate
195+ , certificate :: X509
196+ -- | RSA private key
197+ , privateKey :: PrivateKey
198+ -- | Base URL (generally <https://management.core.windows.net>)
199+ , baseUrl :: String
168200 }
169201
170202-- TODO: it's dubious to be transferring private keys, but we transfer them
@@ -221,7 +253,7 @@ azureSetup sid certPath pkeyPath = do
221253-- High-level API --
222254--------------------------------------------------------------------------------
223255
224−-- | Get a list of virtual machines
256+-- | Find available cloud services
225257cloudServices :: AzureSetup -> IO [CloudService]
226258cloudServices setup = azureExecute setup $ \exec -> do
227259 services <- exec hostedServicesRequest
@@ -240,10 +272,6 @@ cloudServices setup = azureExecute setup $ \exec -> do
240272 }
241273 return $ CloudService (hostedServiceName service) roles
242274
243−-- | Get list of available hosted services
244−hostedServices :: AzureSetup -> IO [HostedService]
245−hostedServices setup = azureExecute setup (\exec -> exec hostedServicesRequest)
246−
247275hostedServicesRequest :: AzureRequest HostedService
248276hostedServicesRequest = AzureRequest
249277 { relativeUrl = "/services/hostedservices"