Merge lp:~evilnick/clouddocs/maas-tags into lp:~jujudocs/clouddocs/trunk

[Nick Veitch]

added tags, zones and cli to MAAS

=== modified file 'Installing-MAAS.md'
--- Installing-MAAS.md	2014-03-31 16:15:07 +0000
+++ Installing-MAAS.md	2014-04-02 23:25:26 +0000
@@ -58,13 +58,13 @@
 
 The configuration for the MAAS controller will automatically run and pop up this config screen:
 
-![](https://www.filepicker.io/api/file/_images/install_cluster-config.png)
+![]( install_cluster-config.png)
 
 Here you will need to enter the hostname for where the region controller can be contacted. In many scenarios, you may be running the region controller (i.e. the web and API interface) from a different network address, for example where a server has several network interfaces.
 
 Once the configuration scripts have run you should see this message telling you that the system is ready to use:
 
-![](https://www.filepicker.io/api/file/_images/install_controller-config.png)
+![]( install_controller-config.png)
 
 The web server is started last, so you have to accept this message before the service is run and you can access the Web interface. Then there are just a few more setup steps [_Post-Install tasks_](https://www.filepicker.io/api/file/WMGTttJT6aaLnQrEkAPv?signature=a86d0c3b4e25dba2d34633bbdc6873d9d8e6ae3cecc4672f2219fa81ee478502&policy=eyJoYW5kbGUiOiJXTUdUdHRKVDZhYUxuUXJFa0FQdiIsImV4cGlyeSI6MTM5NTE3NDE2MSwiY2FsbCI6WyJyZWFkIl19#post-install)
 
@@ -84,7 +84,7 @@
 
 If you now use a web browser to connect to the region controller, you should see that MAAS is running, but there will also be some errors on the screen:
 
-![](https://www.filepicker.io/api/file/_images/install_web-init.png)
+![]( install_web-init.png)
 
 The on screen messages will tell you that there are no boot images present, and that you can't login because there is no admin user.
 
@@ -92,9 +92,9 @@
 
 Once MAAS is installed, you'll need to create an administrator account:
 
-'''
+```
 sudo maas createadmin --username=root --email=[e-mail]
-'''
+```
 
 Substitute your own email address in the command above. You may also use a different username for your administrator account, but "root" is a common convention and easy to remember. The command will prompt for a password to assign to the new user.
 
@@ -104,9 +104,9 @@
 
 MAAS will check for and download new Ubuntu images once a week. However, you'll need to download them manually the first time. To do this you will need to connect to the MAAS API using the maas-cli tool. (see for details). Then you need to run the command:
 
-'''
+```
 maas-cli maas node-groups import-boot-images
-'''
+```
 
 (substitute in a different profile name for 'maas' if you have called yours something else) This will initiate downloading the required image files. Note that this may take some time depending on your network connection.
 
@@ -115,7 +115,7 @@
 
 To check that everything is working properly, you should try and login to the server now. Both the error messages should have gone (it can take a few minutes for the boot image files to register) and you can see that there are currently 0 nodes attached to this controller.
 
-![](https://www.filepicker.io/api/file/_images/install-login.png)
+![]( install-login.png)
 ## Configure switches on the network
 
 Some switches use Spanning-Tree Protocol (STP) to negotiate a loop-free path through a root bridge. While scanning, it can make each port wait up to 50 seconds before data is allowed to be sent on the port. This delay in turn can cause problems with some applications/protocols such as PXE, DHCP and DNS, of which MAAS makes extensive use.
@@ -145,7 +145,7 @@
 When you install your first cluster controller on the same system as the region controller, it will be automatically accepted by default (but not yet configured, see below). Any other cluster controllers you set up will show up in the user interface as “pending,” until you manually accept them into the MAAS.
 
 To accept a cluster controller, click on the settings “cog” icon at the top right to visit the settings page:
-![]
+![]settings.png
 You can either click on “Accept all” or click on the edit icon to edit the cluster. After clicking on the edit icon, you will see this page:
 
 ![]cluster-edit.png
@@ -154,10 +154,46 @@
 Now that the cluster controller is accepted, you can configure one or more of its network interfaces to be managed by MAAS. This will enable the cluster controller to manage nodes attached to those networks. The next section explains how to do this and what choices are to be made.
 
 ### Configuration
+MAAS automatically recognises the network interfaces on each cluster controller. Some of these will be connected to networks where you want to manage nodes. We recommend letting your cluster controller act as a DHCP server for these networks, by configuring those interfaces in the MAAS user interface.
+
+As an example, we will configure the cluster controller to manage a network on interface eth0. Click on the edit icon for eth0, which takes us to this page:
+
+![]cluster-interface-edit.png
+Here you can select to what extent you want the cluster controller to manage the network:
+
+DHCP only - this will run a DHCP server on your cluster
+DHCP and DNS - this will run a DHCP server on the cluster and configure the DNS server included with the region controller so that it can be used to look up hosts on this network by name.
+Note
+You cannot have DNS management without DHCP management because MAAS relies on its own DHCP server’s leases file to work out the IP address of nodes in the cluster.
+If you set the interface to be managed, you now need to provide all of the usual DHCP details in the input fields below. Once done, click “Save interface”. The cluster controller will now be able to boot nodes on this network.
+
+!!! note:There is also an option to leave the network unmanaged. Use this for networks where you don’t want to manage any nodes. Or, if you do want to manage nodes but don’t want the cluster controller to serve DHCP, you may be able to get by without it. This is explained in Manual DHCP configuration.
+
+!!! note: A single cluster controller can manage more than one network, each from a different network interface on the cluster-controller server. This may help you scale your cluster to larger numbers of nodes, or it may be a requirement of your network architecture.
 
 ## Enlisting nodes
 
-## Optional - Tagging nodes
+Now that the MAAS controller is running, we need to make the nodes aware of MAAS and vice-versa. With MAAS controlling DHCP and nodes capable of PXE booting, this is straightforward
+
+Automatic Discovery
+With nodes set to boot from a PXE image, they will start, look for a DHCP server, receive the PXE boot details, boot the image, contact the MAAS server and shut down.
+
+During this process, the MAAS server will be passed information about the node, including the architecture, MAC address and other details which will be stored in the database of nodes. You can accept and comission the nodes via the web interface. When the nodes have been accepted the selected series of Ubuntu will be installed.
+
+To save time, you can also accept and commission all nodes from the commandline. This requires that you first login with the API key [1], which you can retrieve from the web interface:
+
+```
+maas-cli maas nodes accept-all
+```
+
+### Manually adding nodes
+
+If your nodes are not capable of booting from PXE images, they can be manually registered with MAAS. On the Nodes screen:
+![]add-node.png
+
+Select 'Add node' and manually enter details about the node, including its MAC address. This is used to identify the node when it contacts the DHCP server.
+
+
 
 ## Preparing MAAS for Juju using Simplestreams
 
@@ -322,4 +358,110 @@
 
 The same comments apply. Run the validation tool without parameters to use details from the Juju environment, or override values as required on the command line. See `juju help metadata validate-tools` for more details.
 
+##Appendix I - Using Tags
+##Appendix II - Using the MAAS CLI
+As well as the web interface, many tasks can be performed by accessing the MAAS API directly through the maas-cli command. This section details how to login with this tool and perform some common operations.
+
+###Logging in
+Before the API will accept any commands from maas-cli, you must first login. To do this, you need the API key which can be found in the user interface.
+
+Login to the web interface on your MAAS. Click on the username in the top right corner and select ‘Preferences’ from the menu which appears.
+
+![]maascli-prefs.png
+A new page will load...
+
+![]maascli-key.png
+The very first item is a list of MAAS keys. One will have already been generated when the system was installed. It’s easiest to just select all the text, copy the key (it’s quite long!) and then paste it into the commandline. The format of the login command is:
+
+```
+ maas-cli login <profile-name> <hostname> <key>
+```
+
+The profile created is an easy way of associating your credentials with any subsequent call to the API. So an example login might look like this:
+
+```
+maas-cli login maas http://10.98.0.13/MAAS/api/1.0
+AWSCRMzqMNy:jjk...5e1FenoP82Qm5te2
+```
+which creates the profile ‘maas’ and registers it with the given key at the specified API endpoint. If you omit the credentials, they will be prompted for in the console. It is also possible to use a hyphen, ‘-‘ in place of the credentials. In this case a single line will be read from stdin, stripped of any whitespace and used as the credentials, which can be useful if you are devolping scripts for specific tasks. If an empty string is passed instead of the credentials, the profile will be logged in anonymously (and consequently some of the API calls will not be available)
+
+### maas-cli commands
+The maas-cli command exposes the whole API, so you can do anything you actually can do with MAAS using this command. This leaves us with a vast number of options, which are more fully expressed in the complete [2][MAAS Documentation]
+
+list:
+    lists the details [name url auth-key] of all the currently logged-in profiles.
+
+login <profile> <url> <key>:
+    Logs in to the MAAS controller API at the given URL, using the key provided and
+    associates this connection with the given profile name.
+
+logout <profile>:
+    Logs out from the given profile, flushing the stored credentials.
+
+refresh:
+    Refreshes the API descriptions of all the current logged in profiles. This may become necessary for example when upgrading the maas packages to ensure the command-line options match with the API.
+
+### Useful examples
+
+Displays current status of nodes in the commissioning phase:
+```
+maas cli maas nodes check-commissioning
+```
+
+Accept and commission all discovered nodes:
+```
+maas-cli maas nodes accept-all
+```
+
+List all known nodes:
+```
+maas-cli maas nodes list
+```
+
+Filter the list using specific key/value pairs:
+```
+maas-cli maas nodes list architecture="i386/generic"
+```
+
+Set the power parameters for an ipmi enabled node:
+```
+maas-cli maas node update <system_id> \
+  power_type="ipmi" \
+  power_parameters_power_address=192.168.22.33 \
+  power_parameters_power_user=root \
+  power_parameters_power_pass=ubuntu;
+```
+## Appendix III - Physical Zones
+
+To help you maximise fault-tolerance and performance of the services you deploy, MAAS administrators can define _physical zones_ (or just _zones_ for short), and assign nodes to them. When a user requests a node, they can ask for one that is in a specific zone, or one that is not in a specific zone.
+
+It's up to you as an administrator to decide what a physical zone should represent: it could be a server rack, a room, a data centre, machines attached to the same UPS, or a portion of your network. Zones are most useful when they represent portions of your infrastructure. But you could also use them simply to keep track of where your systems are located.
+
+Each node is in one and only one physical zone. Each MAAS instance ships with a default zone to which nodes are attached by default. If you do not need this feature, you can simply pretend it does not exist.
+
+### Applications
+
+Since you run your own MAAS, its physical zones give you more flexibility than those of a third-party hosted cloud service. That means that you get to design your zones and define what they mean. Below are some examples of how physical zones can help you get the most out of your MAAS.
+
+### Creating a Zone
+
+Only administrators can create and manage zones. To create a physical zone in the web user interface, log in as an administrator and browse to the "Zones" section in the top bar. This will takes you to the zones listing page. At the bottom of the page is a button for creating a new zone:
+
+![]add-zone.png
+
+Or to do it in the [_region-controller API_][#region-controller-api], POST your zone definition to the _"zones"_ endpoint.
+
+### Assigning Nodes to a Zone
+
+Once you have created one or more physical zones, you can set nodes' zones from the nodes listing page in the UI. Select the nodes for which you wish to set a zone, and choose "Set physical zone" from the "Bulk action" dropdown list near the top. A second dropdown list will appear, to let you select which zone you wish to set. Leave it blank to clear nodes' physical zones. Clicking "Go" will apply the change to the selected nodes.
+
+You can also set an individual node's zone on its "Edit node" page. Both ways are available in the API as well: edit an individual node through a request to the node's URI, or set the zone on multiple nodes at once by calling the operation on the endpoint.
+
+### Allocating a Node in a Zone
+
+To deploy in a particular zone, call the method in the [_region-controller API_][#region-controller-api] as before, but pass the parameter with the name of the zone. The method will allocate a node in that zone, or fail with an HTTP 409 ("conflict") error if the zone has no nodes available that match your request.
+
+Alternatively, you may want to request a node that is _not_ in a particular zone, or one that is not in any of several zones. To do that, specify the parameter to . This parameter takes a list of zone names; the allocated node will not be in any of them. Again, if that leaves no nodes available that match your request, the call will return a "conflict" error.
+
+It is possible, though not usually useful, to combine the and parameters. If your choice for is also present in , no node will ever match your request. Or if it's not, then the values will not affect the result of the call at all.