Merge lp:~jason-hobbs/maas/ucs-xml-api into lp:~maas-committers/maas/trunk

[Jason Hobbs]

Add support for managing nodes via Cisco UCS Manager's HTTP-XML API.

This adds a new probe and enlist API method and a new power control template for UCS managed nodes.

This adds probe/enlist and power control support for Cisco's UCS HTTP-XML API. I'm still in the final stages of testing it, but it's ready for review now. It's big commit; it wasn't clear to me how to make it smaller but still make it useful.

The power template here is kind of pointless, since the power control is pure python, but it wasn't trivial to work around it. I think we need to consider moving away from always using templates for power control, and make it an option to use a python method directly.

I also think there is room for some common code in handling probe and enlist. The basic pattern is build a list of new nodes and then add them to MAAS. How we deal with existing nodes could be common across all types of enlistments, and having a common interface for the methods could maybe make it easier to build a web UI interface at some point too.

[Julian Edwards (julian-edwards)]

1 === added file 'etc/maas/templates/power/ucsm.template'
2 --- etc/maas/templates/power/ucsm.template 1970-01-01 00:00:00 +0000
3 +++ etc/maas/templates/power/ucsm.template 2014-04-29 13:55:35 +0000
4 @@ -0,0 +1,8 @@
5 +# -*- mode: shell-script -*-
6 +#
7 +# Control a system via Cisco UCS Manager XML API.
8 +
9 +python - << END
10 +from provisioningserver.custom_hardware.ucsm import power_control_ucsm
11 +power_control_ucsm('{{power_address}}', '{{power_user}}', '{{power_pass}}', '{{uuid}}', '{{power_change}}')
12 +END

This is "hope quoting" (as Gavin calls it) and ripe for abuse with unchecked inputs. See the conversation in https://code.launchpad.net/~blake-rouse/maas/virsh-probe-and-enlist/+merge/216632

[Gavin Panella (allenap)]

This is half a review. I have to go out, and I'll finish it later.

As for splitting it up, for one you could have added an empty add_ucsm()
function to NodeGroup, building the API calls around it, and writing
tests in which you mock the behaviour of add_ucsm().

[1]

Hope-quoting, as Julian has mentioned.

[2]

+    def add_ucsm(self, url, username, password):

This isn't a great name for this method. However, I see that it's
consistent with what's gone before.

[3]

+        children = map(Element, children_tags)
+        request_data = make_request_data('foo', fields, children)

Bear in mind that map() is lazy in Python 3. Will make_request_data()
deal with that? If not, make it explicit with a list comprehension.

[4]

+        self.assertEqual(set(children_tags), set([e.tag for e in root[:]]))

The list-comprehension is not needed:

        self.assertEqual(set(children_tags), set(e.tag for e in root[:]))

Not sure the slice is either?

        self.assertEqual(set(children_tags), set(e.tag for e in root))

Having said that, assertItemsEqual() is useful here:

        self.assertItemsEqual(children_tags, (e.tag for e in root))

[5]

+        self.assertRaises(UCSM_XML_API_Error, lambda: parse_response(xml))

assertRaises() allows arguments, so you can write this as:

        self.assertRaises(UCSM_XML_API_Error, parse_response, xml)

[6]

+    def make_test_api(self, url='http://url', user='u', password='p',
+                      cookie='foo', mock_call=True):
+
+        api = make_test_api(url, user, password, cookie)
+
+        if mock_call:
+            mock = self.patch(api, '_call')
+        else:
+            mock = None
+
+        return api, mock

Boolean arguments are a bit smelly, as is returning irrelevant
things. Can you split this into two methods?

    def make_test_api(
            self, url='http://url', user='u', password='p', cookie='foo'):
        return make_test_api(url, user, password, cookie)

    def make_test_api(
            self, url='http://url', user='u', password='p', cookie='foo'):
        api = make_test_api(url, user, password, cookie)
        return api, self.patch(api, '_call')

To be continued...

[Jeroen T. Vermeulen (jtv)]

There's lots of good stuff here, well-factored, and with a very nice breakdown into coherent, low-complexity functions. But there's just so much of it that I can't complete this review all in one go!

I'll give you the notes I have now. I reviewed up to UCSM_XML_API, moving from the top of the diff downwards, except I skipped its tests for now.

.

The docstring for probe_and_enlist_hardware needs updating, and probe_and_enlist_ucsm should probably be a bit more specific about the hardware types it supports.

.

Typo: Cicso.

.

The test case for make_request_data is called TestGetRequestData — uncompleted change of name?

.

In TestUCSMXMLAPIError, I appreciate the sentiment of raising the exception and catching it before testing its properties, but I don't see it buying us anything: it basically tests that “raise” and assertRaises pass on the exception they received.

(Also, “raise” is a keyword, not a function — no parentheses needed when using it.)

.

In TestParseResponse.test_error:

        self.assertRaises(UCSM_XML_API_Error, lambda: parse_response(xml))

No need for the lambda. You can just pass additional arguments for the callable (as well as keyword arguments) to assertRaises:

        self.assertRaises(UCSM_XML_API_Error, parse_response, xml)

.

Unless you're in the process of adding more methods to APITestCase, I'd just drop it as a base class. Using inheritance to add features seems like a small thing, but consider how many test-case classes are suddenly tied together in a vague relationship! And once in place, these relationships tend to grow.

What to do with APITestCase.make_test_api? You could just pass the test-case object to the global make_test_api, and maybe skip the patching if testcase is None.

Actually, I'd probably just leave out the option to suppress the patching, and accept a slightly special case in the one call site where you use that option. This kind of boolean argument is almost always a constant, which means you've really got two similar-but-different functions, and the caller already knows exactly which one they want. You're almost always better off writing the two forms as separate functions. Often, one can call the other, or you can extract meaningful parts that will be called by both.

.

UCSM_XML_API is quite a test for naming conventions! The underscores are unusual in a class name for us, but these are unusual circumstances so you won't hear me complain. :)

I do wish I had a clearer understanding of the “children” that are being mentioned throughout. I understand that it's a domain term, so I'd probably need to read up on the UCSM API in order to understand. A very brief note might make it easier to deal with though. Setting the right expectations often helps prevents disasters.

[Jeroen T. Vermeulen (jtv)]

Looks like you're getting multiple reviews. One of the risks of large branches! Reviewers' ability to spot problems drops off sharply after the first few hundred lines, so it's probably for the best. (The “sweet spot” for reviews seems to lie around 200 lines).

Some more notes:

.

Could you document what RO_KEYS and strip_ro_keys mean? I see how they fit together, but I lack context about the wider problem it solves.

.

In get_power_command, there's an if/elif without a final ‘else.’ So an unknown power state will just result in a None, which could produce failures that are hard to diagnose. You could avoid that hazard by adding an “else: raise AssertionError(...)” at the end.

.

Some identifiers have abbreviations whose meanings are a complete mystery to me, such as dn and bp. Long, verbose names can be unpleasant, but names with unknown meanings can be a positive menace!

.

In power_control_ucsm, you do:

        servers = get_servers(api, uuid)
        server = servers[0]

Why server[0]? Are you taking an arbitrary one? The latest? Something else? Would be worth a comment.

Or, if you are absolutely 100% totally completely certainly positive that there is exactly one item in that list, pattern-matching lets you write the assignment as:

        [server] = get_servers(api, uuid)

.

You document power_control_ucsm as “Power control template handler.” I think I sort of understand all of that, except the “template.” How does that word fit in? It may help to summarise what the function does in the imperative.

.

Similarly, probe_and_enlist_ucsm is documented as “Probe and enlist request handler.” I *think* this fails to state what the function does in the imperative, but I'm not sure. It's ambiguous: there is a request handler, and this function probes and enlists it? Or is the function a “Probe-and-enlist request handler”? If so, where does the request come in?

.

For the addition to src/provisioningserver/power_schema.py, might I suggest "double quotes" around free-form text? I'm not saying that “URL for XML API” should be changed to “XML API's URL” for example, but if anyone tried, the apostrophe would break the strings quoting!

.

In TestAddUCSM, a disadvantage of passing highly predictable fixed strings like “username” and “password” is that the test doesn't rule out silly bugs like “always passes ‘username’ instead of the actual user name.” Not saying that that is terribly likely in any given instance, but if we build the right habits, we won't need to make the mistake at all. These mistakes can happen in TDD when you try to write the simplest stub that will satisfy a test.

[Jeroen T. Vermeulen (jtv)]

By the way, we deviate from PEP-8 in formatting. When linebreaking (except in def/class definitions) we only indent by 4 columns. We don't align to the opening brace/bracket/parenthesis.

So, where you wrote

        self.assertThat(mock, MockCalledOnceWith('configResolveClass', fields,
                                                 ANY))

...we might write:

        self.assertThat(
            mock, MockCalledOnceWith('configResolveClass', fields, ANY))

When we need to line-break an arguments list, we do make it a rule to start the first argument on a fresh line.

.

In further bikeshedding, method names “login” and “logout” look a bit strange for me — we generally prefer our function names to start with verbs, but these are the nouns.

.

At this point I'm a bit stuck. I'd like to review the tests in more detail, but it might not be much use because of my limited understanding of the API code's higher-level meaning. It would be nice to have that little bit more explanation!

[Gavin Panella (allenap)]

Neat, nice stuff. My comments are almost all about style, not approach.
I think my only real problems with this branch are [1] and the lack of
commentary about how things work. If it's biting me now, it'll bite you
in 3 months when you've long moved on from this.

[7]

+        self.assertEqual([filter_element], in_filters[0][:])

What's the [:] slice for?

[8]

+    def test_parameters(self):
...
+        in_configs = mock.call_args[0][2]
+        self.assertEqual(config_items, in_configs[0][:])

I don't know what this is demonstrating. Can you add a comment, or
perhaps make it more intrinsically clear. There's a mock.ANY object
which you can use when you don't care what an argument is (e.g. so you
can use one of the Mock* matchers but only test one argument of
several), which may or may not be useful here.

[9]

+        self.assertThat(mock_make_request_data,
+                        MockCalledOnceWith(name, fields, children))

Fwiw, and it's a minor thing, the MAAS core team (former Red Squad) long
ago chose to not indent after braces like this. For one, it gets silly
when the function name is long and all the arguments get smashed against
the right margin. Prefer starting a new line:

        self.assertThat(
            mock_make_request_data,
            MockCalledOnceWith(name, fields, children))

For functions, it might be worth indenting twice:

    def this_is_a_function(
            with_a_long, argument_list, foo, bar):
        do_something(...)

or using a docstring or comment to delineate arguments from body:

    def this_is_a_function(
        with_a_long, argument_list, foo, bar):
        """Docstring, oh docstring, where art thou o docstring?"""
        do_something(...)

I'm definitely not going to block on this though.

[10]

+    def test_uses_uuid(self):
+        uuid = factory.getRandomUUID()
+        api = make_test_api()
+        mock = self.patch(api, 'config_resolve_class')
+        get_servers(api, uuid)
+        filters = mock.call_args[0][1]
+        attrib = {'class': 'computeItem', 'property': 'uuid', 'value': uuid}
+        self.assertEqual(attrib, filters[0].attrib)

There could have been multiple calls to config_resolve_class. Consider
using MockCalledOnceWith() and mock.ANY here, and elsewhere, to tighten
up the test, and make the test clearer and more concise.

[11]

+    def login(self):
...
+        UCS Manager allows a limited number of active cookies at any
+        point in time, so it's important to free the cookie up when
+        finished by logging out via the ``logout`` method.

Consider making UCSM_XML_API a context manager, where __enter__ logs-in,
and __exit__ logs-out.

[12]

+    def config_resolve_class(self, class_id, filters=None):
+        """Issue a configResolveClass request."""

What does configResolveClass do? Either comment here, or provide a
(stable, preferably) link to the UCS API documentation. Extra beer for
both. The same goes for most of the other methods, if not all.

[13]

+def get_servers(api, uuid=None):
+    """Retrieve a list of servers from the UCS Manager."""
+    if uuid:
+        attrs = {'class': 'computeItem', 'property': 'uuid', 'value': uuid}
+        fil...

review: Needs Fixing

[Jason Hobbs (jason-hobbs)]

I've addressed what I think are the critical feedback items, along with some others. There is time sensitivity in getting this in, so I want to repost for review again before all of the feedback items are addressed. I will post a summary of what is left to address, after I get my laptop on a charger!

[Jason Hobbs (jason-hobbs)]

Here's the review comments I haven't addressed yet.

From Jeroen:
In TestUCSMXMLAPIError, I appreciate the sentiment of raising the exception and catching it before testing its properties, but I don't see it buying us anything: it basically tests that “raise” and assertRaises pass on the exception they received.

In TestAddUCSM, a disadvantage of passing highly predictable fixed strings like “username” and “password” is that the test doesn't rule out silly bugs like “always passes ‘username’ instead of the actual user name.” Not saying that that is terribly likely in any given instance, but if we build the right habits, we won't need to make the mistake at all. These mistakes can happen in TDD when you try to write the simplest stub that will satisfy a test.

By the way, we deviate from PEP-8 in formatting. When linebreaking (except in def/class definitions) we only indent by 4 columns. We don't align to the opening brace/bracket/parenthesis.

In further bikeshedding, method names “login” and “logout” look a bit strange for me — we generally prefer our function names to start with verbs, but these are the nouns.

From Gavin:
[8], [9], [10], [11], [13], [14]

[Jeroen T. Vermeulen (jtv)]

Great, thanks. I see no reason why this shouldn't be allowed in at this point. I think the remaining things are pretty much all non-essential cleanups that will just happen organically if they bother us again.

review: Approve

[MAAS Lander (maas-lander)]

The attempt to merge lp:~jason-hobbs/maas/ucs-xml-api into lp:maas failed. Below is the output from the failed tests.

Ign http://security.ubuntu.com trusty-security InRelease
Get:1 http://security.ubuntu.com trusty-security Release.gpg [933 B]
Get:2 http://security.ubuntu.com trusty-security Release [58.5 kB]
Ign http://nova.clouds.archive.ubuntu.com trusty InRelease
Ign http://nova.clouds.archive.ubuntu.com trusty-updates InRelease
Hit http://nova.clouds.archive.ubuntu.com trusty Release.gpg
Get:3 http://nova.clouds.archive.ubuntu.com trusty-updates Release.gpg [933 B]
Hit http://nova.clouds.archive.ubuntu.com trusty Release
Get:4 http://nova.clouds.archive.ubuntu.com trusty-updates Release [58.5 kB]
Get:5 http://security.ubuntu.com trusty-security/main Sources [11.3 kB]
Hit http://nova.clouds.archive.ubuntu.com trusty/main Sources
Get:6 http://security.ubuntu.com trusty-security/universe Sources [1,785 B]
Hit http://nova.clouds.archive.ubuntu.com trusty/universe Sources
Get:7 http://security.ubuntu.com trusty-security/main amd64 Packages [36.5 kB]
Hit http://nova.clouds.archive.ubuntu.com trusty/main amd64 Packages
Hit http://nova.clouds.archive.ubuntu.com trusty/universe amd64 Packages
Hit http://nova.clouds.archive.ubuntu.com trusty/main Translation-en
Get:8 http://security.ubuntu.com trusty-security/universe amd64 Packages [9,525 B]
Hit http://nova.clouds.archive.ubuntu.com trusty/universe Translation-en
Get:9 http://security.ubuntu.com trusty-security/main Translation-en [16.2 kB]
Get:10 http://security.ubuntu.com trusty-security/universe Translation-en [5,005 B]
Ign http://nova.clouds.archive.ubuntu.com trusty/main Translation-en_US
Ign http://security.ubuntu.com trusty-security/main Translation-en_US
Ign http://nova.clouds.archive.ubuntu.com trusty/universe Translation-en_US
Ign http://security.ubuntu.com trusty-security/universe Translation-en_US
Get:11 http://nova.clouds.archive.ubuntu.com trusty-updates/main Sources [19.4 kB]
Get:12 http://nova.clouds.archive.ubuntu.com trusty-updates/universe Sources [9,282 B]
Get:13 http://nova.clouds.archive.ubuntu.com trusty-updates/main amd64 Packages [55.4 kB]
Get:14 http://nova.clouds.archive.ubuntu.com trusty-updates/universe amd64 Packages [26.2 kB]
Get:15 http://nova.clouds.archive.ubuntu.com trusty-updates/main Translation-en [25.3 kB]
Get:16 http://nova.clouds.archive.ubuntu.com trusty-updates/universe Translation-en [13.1 kB]
Ign http://nova.clouds.archive.ubuntu.com trusty-updates/main Translation-en_US
Ign http://nova.clouds.archive.ubuntu.com trusty-updates/universe Translation-en_US
Fetched 348 kB in 1s (285 kB/s)
Reading package lists...
sudo DEBIAN_FRONTEND=noninteractive apt-get -y \
     --no-install-recommends install apache2 bind9 bind9utils build-essential bzr-builddeb curl daemontools debhelper dh-apport distro-info dnsutils firefox freeipmi-tools ipython isc-dhcp-common libjs-raphael libjs-yui3-full libjs-yui3-min libpq-dev make postgresql python-amqplib python-bzrlib python-celery python-convoy python-crochet python-cssselect python-curtin python-dev python-distro-info python-django python-django-piston python-django-south python-djorm-ext-pgarray python-docutils python-...

[Gavin Panella (allenap)]

I haven't gone through the changes but Jeroen has, and I doubt I can add much.

review: Abstain

=== added file 'etc/maas/templates/power/ucsm.template'
--- etc/maas/templates/power/ucsm.template	1970-01-01 00:00:00 +0000
+++ etc/maas/templates/power/ucsm.template	2014-05-06 13:49:30 +0000
@@ -0,0 +1,15 @@
+# -*- mode: shell-script -*-
+#
+# Control a system via Cisco UCS Manager XML API.
+
+{{py: from provisioningserver.utils import escape_py_literal}}
+python - << END
+from provisioningserver.custom_hardware.ucsm import power_control_ucsm
+power_control_ucsm(
+    {{escape_py_literal(power_address) | safe}},
+    {{escape_py_literal(power_user) | safe}},
+    {{escape_py_literal(power_pass) | safe}},
+    {{escape_py_literal(uuid) | safe}},
+    {{escape_py_literal(power_change) | safe}},
+)
+END

=== modified file 'src/maasserver/api.py'
--- src/maasserver/api.py	2014-05-01 05:38:03 +0000
+++ src/maasserver/api.py	2014-05-06 13:49:30 +0000
@@ -1728,6 +1728,29 @@
 
         return HttpResponse(status=httplib.OK)
 
+    @admin_method
+    @operation(idempotent=False)
+    def probe_and_enlist_ucsm(self, request, uuid):
+        """Add the nodes from a Cisco UCS Manager.
+
+        :param : The URL of the UCS Manager API.
+        :type url: unicode
+        :param username: The username for the API.
+        :type username: unicode
+        :param password: The password for the API.
+        :type password: unicode
+
+        """
+        nodegroup = get_object_or_404(NodeGroup, uuid=uuid)
+
+        url = get_mandatory_param(request.data, 'url')
+        username = get_mandatory_param(request.data, 'username')
+        password = get_mandatory_param(request.data, 'password')
+
+        nodegroup.enlist_nodes_from_ucsm(url, username, password)
+
+        return HttpResponse(status=httplib.OK)
+
 DISPLAYED_NODEGROUPINTERFACE_FIELDS = (
     'ip', 'management', 'interface', 'subnet_mask',
     'broadcast_ip', 'ip_range_low', 'ip_range_high')

=== modified file 'src/maasserver/models/nodegroup.py'
--- src/maasserver/models/nodegroup.py	2014-04-01 06:50:01 +0000
+++ src/maasserver/models/nodegroup.py	2014-05-06 13:49:30 +0000
@@ -41,6 +41,7 @@
 from provisioningserver.tasks import (
     add_new_dhcp_host_map,
     add_seamicro15k,
+    enlist_nodes_from_ucsm,
     import_boot_images,
     report_boot_images,
     )
@@ -286,6 +287,16 @@
         args = (mac, username, password, power_control)
         add_seamicro15k.apply_async(queue=self.uuid, args=args)
 
+    def enlist_nodes_from_ucsm(self, url, username, password):
+        """ Add the servers from a Cicso UCS Manager.
+
+        :param URL: URL of the Cisco UCS Manager HTTP-XML API.
+        :param username: username for UCS Manager.
+        :param password: password for UCS Manager.
+        """
+        args = (url, username, password)
+        enlist_nodes_from_ucsm.apply_async(queue=self.uuid, args=args)
+
     def add_dhcp_host_maps(self, new_leases):
         if len(new_leases) > 0 and len(self.get_managed_interfaces()) > 0:
             # XXX JeroenVermeulen 2012-08-21, bug=1039362: the DHCP

=== modified file 'src/maasserver/tests/test_api_nodegroup.py'
--- src/maasserver/tests/test_api_nodegroup.py	2014-04-22 15:10:32 +0000
+++ src/maasserver/tests/test_api_nodegroup.py	2014-05-06 13:49:30 +0000
@@ -52,6 +52,7 @@
 from maasserver.testing.testcase import MAASServerTestCase
 from maastesting.celery import CeleryFixture
 from maastesting.fakemethod import FakeMethod
+from maastesting.matchers import MockCalledOnceWith
 from metadataserver.fields import Bin
 from metadataserver.models import (
     commissioningscript,
@@ -431,6 +432,32 @@
             httplib.BAD_REQUEST, response.status_code,
             explain_unexpected_response(httplib.BAD_REQUEST, response))
 
+    def test_probe_and_enlist_ucsm_adds_ucsm(self):
+        nodegroup = factory.make_node_group()
+        url = 'http://url'
+        username = factory.make_name('user')
+        password = factory.make_name('password')
+        self.become_admin()
+
+        mock = self.patch(nodegroup_module, 'enlist_nodes_from_ucsm')
+
+        response = self.client.post(
+            reverse('nodegroup_handler', args=[nodegroup.uuid]),
+            {
+                'op': 'probe_and_enlist_ucsm',
+                'url': url,
+                'username': username,
+                'password': password,
+            })
+
+        self.assertEqual(
+            httplib.OK, response.status_code,
+            explain_unexpected_response(httplib.OK, response))
+
+        args = (url, username, password)
+        matcher = MockCalledOnceWith(queue=nodegroup.uuid, args=args)
+        self.assertThat(mock.apply_async, matcher)
+
 
 class TestNodeGroupAPIAuth(MAASServerTestCase):
     """Authorization tests for nodegroup API."""

=== added file 'src/provisioningserver/custom_hardware/tests/test_ucsm.py'
--- src/provisioningserver/custom_hardware/tests/test_ucsm.py	1970-01-01 00:00:00 +0000
+++ src/provisioningserver/custom_hardware/tests/test_ucsm.py	2014-05-06 13:49:30 +0000
@@ -0,0 +1,638 @@
+# Copyright 2014 Canonical Ltd.  This software is licensed under the
+# GNU Affero General Public License version 3 (see the file LICENSE).
+
+"""Tests for ``provisioningserver.custom_hardware.ucsm``."""
+
+from __future__ import (
+    absolute_import,
+    print_function,
+    unicode_literals,
+    )
+
+str = None
+
+__metaclass__ = type
+__all__ = []
+
+from itertools import permutations
+import random
+from StringIO import StringIO
+import urllib2
+
+from lxml.etree import (
+    Element,
+    SubElement,
+    XML,
+    )
+from maastesting.factory import factory
+from maastesting.matchers import (
+    MockCalledOnceWith,
+    MockCallsMatch,
+    MockNotCalled,
+    )
+from maastesting.testcase import MAASTestCase
+from mock import (
+    ANY,
+    call,
+    Mock,
+    )
+from provisioningserver.custom_hardware import (
+    ucsm,
+    utils,
+    )
+from provisioningserver.custom_hardware.ucsm import (
+    get_children,
+    get_first_booter,
+    get_macs,
+    get_power_command,
+    get_server_power_control,
+    get_servers,
+    get_service_profile,
+    logged_in,
+    make_policy_change,
+    make_request_data,
+    parse_response,
+    power_control_ucsm,
+    probe_and_enlist_ucsm,
+    probe_servers,
+    RO_KEYS,
+    set_lan_boot_default,
+    set_server_power_control,
+    strip_ro_keys,
+    UCSM_XML_API,
+    UCSM_XML_API_Error,
+    )
+
+
+def make_api(url='http://url', user='u', password='p',
+             cookie='foo', mock_call=True):
+    api = UCSM_XML_API(url, user, password)
+    api.cookie = cookie
+    return api
+
+
+def make_api_patch_call(testcase, *args, **kwargs):
+    api = make_api(*args, **kwargs)
+    mock = testcase.patch(api, '_call')
+    return api, mock
+
+
+def make_fake_result(root_class, child_tag, container='outConfigs'):
+    fake_result = Element(root_class)
+    outConfigs = SubElement(fake_result, container)
+    outConfigs.append(Element(child_tag))
+    return outConfigs
+
+
+def make_class():
+    return factory.make_name('class')
+
+
+def make_dn():
+    return factory.make_name('dn')
+
+
+def make_server():
+    return factory.make_name('server')
+
+
+class TestUCSMXMLAPIError(MAASTestCase):
+    """Tests for ``UCSM_XML_API_Error``."""
+
+    def test_includes_code_and_msg(self):
+        def raise_error():
+            raise UCSM_XML_API_Error('bad', 4224)
+
+        error = self.assertRaises(UCSM_XML_API_Error, raise_error)
+
+        self.assertEqual('bad', error.args[0])
+        self.assertEqual(4224, error.code)
+
+
+class TestMakeRequestData(MAASTestCase):
+    """Tests for ``make_request_data``."""
+
+    def test_no_children(self):
+        fields = {'hello': 'there'}
+        request_data = make_request_data('foo', fields)
+        root = XML(request_data)
+        self.assertEqual('foo', root.tag)
+        self.assertEqual('there', root.get('hello'))
+
+    def test_with_children(self):
+        fields = {'hello': 'there'}
+        children_tags = ['bar', 'baz']
+        children = [Element(child_tag) for child_tag in children_tags]
+        request_data = make_request_data('foo', fields, children)
+        root = XML(request_data)
+        self.assertEqual('foo', root.tag)
+        self.assertItemsEqual(children_tags, (e.tag for e in root))
+
+    def test_no_fields(self):
+        request_data = make_request_data('foo')
+        root = XML(request_data)
+        self.assertEqual('foo', root.tag)
+
+
+class TestParseResonse(MAASTestCase):
+    """Tests for ``parse_response``."""
+
+    def test_no_error(self):
+        xml = '<foo/>'
+        response = parse_response(xml)
+        self.assertEqual('foo', response.tag)
+
+    def test_error(self):
+        xml = '<foo errorCode="123" errorDescr="mayday!"/>'
+        self.assertRaises(UCSM_XML_API_Error, parse_response, xml)
+
+
+class TestLogin(MAASTestCase):
+    """"Tests for ``UCSM_XML_API.login``."""
+
+    def test_login_assigns_cookie(self):
+        cookie = 'chocolate chip'
+        api, mock = make_api_patch_call(self)
+        mock.return_value = Element('aaaLogin', {'outCookie': cookie})
+        api.login()
+        self.assertEqual(cookie, api.cookie)
+
+    def test_login_call_parameters(self):
+        user = 'user'
+        password = 'pass'
+        api, mock = make_api_patch_call(self, user=user, password=password)
+        api.login()
+        fields = {'inName': user, 'inPassword': password}
+        self.assertThat(mock, MockCalledOnceWith('aaaLogin', fields))
+
+
+class TestLogout(MAASTestCase):
+    """"Tests for ``UCSM_XML_API.logout``."""
+
+    def test_logout_clears_cookie(self):
+        api = make_api()
+        self.patch(api, '_call')
+        api.logout()
+        self.assertIsNone(api.cookie)
+
+    def test_logout_uses_cookie(self):
+        api, mock = make_api_patch_call(self)
+        cookie = api.cookie
+        api.logout()
+        fields = {'inCookie': cookie}
+        self.assertThat(mock, MockCalledOnceWith('aaaLogout', fields))
+
+
+class TestConfigResolveClass(MAASTestCase):
+    """"Tests for ``UCSM_XML_API.config_resolve_class``."""
+
+    def test_no_filters(self):
+        class_id = make_class()
+        api, mock = make_api_patch_call(self)
+        api.config_resolve_class(class_id)
+        fields = {'cookie': api.cookie, 'classId': class_id}
+        self.assertThat(mock, MockCalledOnceWith('configResolveClass', fields,
+                                                 ANY))
+
+    def test_with_filters(self):
+        class_id = make_class()
+        filter_element = Element('hi')
+        api, mock = make_api_patch_call(self)
+        api.config_resolve_class(class_id, [filter_element])
+        in_filters = mock.call_args[0][2]
+        self.assertEqual([filter_element], in_filters[0][:])
+
+    def test_return_response(self):
+        api, mock = make_api_patch_call(self)
+        mock.return_value = Element('test')
+        result = api.config_resolve_class('c')
+        self.assertEqual(mock.return_value, result)
+
+
+class TestConfigResolveChildren(MAASTestCase):
+    """"Tests for ``UCSM_XML_API.config_resolve_children``."""
+
+    def test_parameters(self):
+        dn = make_dn()
+        class_id = make_class()
+        api, mock = make_api_patch_call(self)
+        api.config_resolve_children(dn, class_id)
+        fields = {'inDn': dn, 'classId': class_id, 'cookie': api.cookie}
+        self.assertThat(mock,
+                        MockCalledOnceWith('configResolveChildren', fields))
+
+    def test_no_class_id(self):
+        dn = make_dn()
+        api, mock = make_api_patch_call(self)
+        api.config_resolve_children(dn)
+        fields = {'inDn': dn, 'cookie': api.cookie}
+        self.assertThat(mock,
+                        MockCalledOnceWith('configResolveChildren', fields))
+
+    def test_return_response(self):
+        api, mock = make_api_patch_call(self)
+        mock.return_value = Element('test')
+        result = api.config_resolve_children('d', 'c')
+        self.assertEqual(mock.return_value, result)
+
+
+class TestConfigConfMo(MAASTestCase):
+    """"Tests for ``UCSM_XML_API.config_conf_mo``."""
+
+    def test_parameters(self):
+        dn = make_dn()
+        config_items = [Element('hi')]
+        api, mock = make_api_patch_call(self)
+        api.config_conf_mo(dn, config_items)
+        fields = {'dn': dn, 'cookie': api.cookie}
+        self.assertThat(mock, MockCalledOnceWith('configConfMo', fields, ANY))
+        in_configs = mock.call_args[0][2]
+        self.assertEqual(config_items, in_configs[0][:])
+
+
+class TestCall(MAASTestCase):
+    """"Tests for ``UCSM_XML_API._call``."""
+
+    def test_call(self):
+        name = 'method'
+        fields = {1: 2}
+        children = [3, 4]
+        request = '<yes/>'
+        response = Element('good')
+        api = make_api()
+
+        mock_make_request_data = self.patch(ucsm, 'make_request_data')
+        mock_make_request_data.return_value = request
+
+        mock_send_request = self.patch(api, '_send_request')
+        mock_send_request.return_value = response
+
+        api._call(name, fields, children)
+        self.assertThat(mock_make_request_data,
+                        MockCalledOnceWith(name, fields, children))
+        self.assertThat(mock_send_request, MockCalledOnceWith(request))
+
+
+class TestSendRequest(MAASTestCase):
+    """"Tests for ``UCSM_XML_API._send_request``."""
+
+    def test_send_request(self):
+        request_data = 'foo'
+        api = make_api()
+        self.patch(api, '_call')
+        stream = StringIO('<hi/>')
+        mock = self.patch(urllib2, 'urlopen')
+        mock.return_value = stream
+        response = api._send_request(request_data)
+        self.assertEqual('hi', response.tag)
+        urllib_request = mock.call_args[0][0]
+        self.assertEqual(request_data, urllib_request.data)
+
+
+class TestConfigResolveDn(MAASTestCase):
+    """Tests for ``UCSM_XML_API.config_resolve_dn``."""
+
+    def test_parameters(self):
+        api, mock = make_api_patch_call(self)
+        test_dn = make_dn()
+        fields = {'cookie': api.cookie, 'dn': test_dn}
+        api.config_resolve_dn(test_dn)
+        self.assertThat(mock,
+                        MockCalledOnceWith('configResolveDn', fields))
+
+
+class TestGetServers(MAASTestCase):
+    """Tests for ``get_servers``."""
+
+    def test_uses_uuid(self):
+        uuid = factory.getRandomUUID()
+        api = make_api()
+        mock = self.patch(api, 'config_resolve_class')
+        get_servers(api, uuid)
+        filters = mock.call_args[0][1]
+        attrib = {'class': 'computeItem', 'property': 'uuid', 'value': uuid}
+        self.assertEqual(attrib, filters[0].attrib)
+
+    def test_returns_result(self):
+        uuid = factory.getRandomUUID()
+        api = make_api()
+        fake_result = make_fake_result('configResolveClass', 'found')
+        self.patch(api, 'config_resolve_class').return_value = fake_result
+        result = get_servers(api, uuid)
+        self.assertEqual('found', result[0].tag)
+
+    def test_class_id(self):
+        uuid = factory.getRandomUUID()
+        api = make_api()
+        mock = self.patch(api, 'config_resolve_class')
+        get_servers(api, uuid)
+        self.assertThat(mock, MockCalledOnceWith('computeItem', ANY))
+
+
+class TestGetChildren(MAASTestCase):
+    """Tests for ``get_children``."""
+
+    def test_returns_result(self):
+        search_class = make_class()
+        api = make_api()
+        fake_result = make_fake_result('configResolveChildren', search_class)
+        self.patch(api, 'config_resolve_children').return_value = fake_result
+        in_element = Element('test', {'dn': make_dn()})
+        class_id = search_class
+        result = get_children(api, in_element, class_id)
+        self.assertEqual(search_class, result[0].tag)
+
+    def test_parameters(self):
+        search_class = make_class()
+        parent_dn = make_dn()
+        api = make_api()
+        mock = self.patch(api, 'config_resolve_children')
+        in_element = Element('test', {'dn': parent_dn})
+        class_id = search_class
+        get_children(api, in_element, class_id)
+        self.assertThat(mock, MockCalledOnceWith(parent_dn, search_class))
+
+
+class TestGetMacs(MAASTestCase):
+    """Tests for ``get_macs``."""
+
+    def test_gets_adaptors(self):
+        adaptor = 'adaptor'
+        server = make_server()
+        mac = 'xx'
+        api = make_api()
+        mock = self.patch(ucsm, 'get_children')
+
+        def fake_get_children(api, element, class_id):
+            if class_id == 'adaptorUnit':
+                return [adaptor]
+            elif class_id == 'adaptorHostEthIf':
+                return [Element('ethif', {'mac': mac})]
+
+        mock.side_effect = fake_get_children
+        macs = get_macs(api, server)
+        self.assertThat(mock, MockCallsMatch(
+                        call(api, server, 'adaptorUnit'),
+                        call(api, adaptor, 'adaptorHostEthIf')))
+        self.assertEqual([mac], macs)
+
+
+class TestProbeServers(MAASTestCase):
+    """Tests for ``probe_servers``."""
+
+    def test_uses_api(self):
+        api = make_api()
+        mock = self.patch(ucsm, 'get_servers')
+        probe_servers(api)
+        self.assertThat(mock, MockCalledOnceWith(api))
+
+    def test_returns_results(self):
+        servers = [{'uuid': factory.getRandomUUID()}]
+        mac = 'mac'
+        api = make_api()
+        self.patch(ucsm, 'get_servers').return_value = servers
+        self.patch(ucsm, 'get_macs').return_value = [mac]
+        server_list = probe_servers(api)
+        self.assertEqual([(servers[0], [mac])], server_list)
+
+
+class TestGetServerPowerControl(MAASTestCase):
+    """Tests for ``get_server_power_control``."""
+
+    def test_get_server_power_control(self):
+        api = make_api()
+        mock = self.patch(api, 'config_resolve_children')
+        fake_result = make_fake_result('configResolveChildren', 'lsPower')
+        mock.return_value = fake_result
+        dn = make_dn()
+        server = Element('computeItem', {'assignedToDn': dn})
+        power_control = get_server_power_control(api, server)
+        self.assertThat(mock, MockCalledOnceWith(dn, 'lsPower'))
+        self.assertEqual('lsPower', power_control.tag)
+
+
+class TestSetServerPowerControl(MAASTestCase):
+    """Tests for ``set_server_power_control``."""
+
+    def test_set_server_power_control(self):
+        api = make_api()
+        power_dn = make_dn()
+        power_control = Element('lsPower', {'dn': power_dn})
+        config_conf_mo_mock = self.patch(api, 'config_conf_mo')
+        state = 'state'
+        set_server_power_control(api, power_control, state)
+        self.assertThat(config_conf_mo_mock, MockCalledOnceWith(power_dn, ANY))
+        power_change = config_conf_mo_mock.call_args[0][1][0]
+        self.assertEqual(power_change.tag, 'lsPower')
+        self.assertEqual({'state': state, 'dn': power_dn}, power_change.attrib)
+
+
+class TestLoggedIn(MAASTestCase):
+    """Tests for ``logged_in``."""
+
+    def test_logged_in(self):
+        mock = self.patch(ucsm, 'UCSM_XML_API')
+        url = 'url'
+        username = 'username'
+        password = 'password'
+        mock.return_value = Mock()
+
+        with logged_in(url, username, password) as api:
+            self.assertEqual(mock.return_value, api)
+            self.assertThat(api.login, MockCalledOnceWith())
+
+        self.assertThat(mock.return_value.logout, MockCalledOnceWith())
+
+
+class TestValidGetPowerCommand(MAASTestCase):
+    scenarios = [
+        ('Power On', dict(
+            power_mode='on', current_state='down', command='admin-up')),
+        ('Power On', dict(
+            power_mode='on', current_state='up', command='cycle-immediate')),
+        ('Power Off', dict(
+            power_mode='off', current_state='up', command='admin-down')),
+    ]
+
+    def test_get_power_command(self):
+        command = get_power_command(self.power_mode, self.current_state)
+        self.assertEqual(self.command, command)
+
+
+class TestInvalidGetPowerCommand(MAASTestCase):
+
+    def test_get_power_command_raises_assertion_error_on_bad_power_mode(self):
+        bad_power_mode = factory.make_name('unlikely')
+        error = self.assertRaises(AssertionError, get_power_command,
+                                  bad_power_mode, None)
+        self.assertIn(bad_power_mode, error.args[0])
+
+
+class TestPowerControlUCSM(MAASTestCase):
+    """Tests for ``power_control_ucsm``."""
+
+    def test_power_control_ucsm(self):
+        uuid = factory.getRandomUUID()
+        api = Mock()
+        self.patch(ucsm, 'UCSM_XML_API').return_value = api
+        get_servers_mock = self.patch(ucsm, 'get_servers')
+        server = make_server()
+        state = 'admin-down'
+        power_control = Element('lsPower', {'state': state})
+        get_servers_mock.return_value = [server]
+        get_server_power_control_mock = self.patch(ucsm,
+                                                   'get_server_power_control')
+        get_server_power_control_mock.return_value = power_control
+        set_server_power_control_mock = self.patch(ucsm,
+                                                   'set_server_power_control')
+        power_control_ucsm('url', 'username', 'password', uuid,
+                           'off')
+        self.assertThat(get_servers_mock, MockCalledOnceWith(api, uuid))
+        self.assertThat(set_server_power_control_mock,
+                        MockCalledOnceWith(api, power_control, state))
+
+
+class TestProbeAndEnlistUCSM(MAASTestCase):
+    """Tests for ``probe_and_enlist_ucsm``."""
+
+    def test_probe_and_enlist(self):
+        url = 'url'
+        username = 'username'
+        password = 'password'
+        api = Mock()
+        self.patch(ucsm, 'UCSM_XML_API').return_value = api
+        server_element = {'uuid': 'uuid'}
+        server = (server_element, ['mac'],)
+        probe_servers_mock = self.patch(ucsm, 'probe_servers')
+        probe_servers_mock.return_value = [server]
+        set_lan_boot_default_mock = self.patch(ucsm, 'set_lan_boot_default')
+        create_node_mock = self.patch(utils, 'create_node')
+        probe_and_enlist_ucsm(url, username, password)
+        self.assertThat(set_lan_boot_default_mock,
+                        MockCalledOnceWith(api, server_element))
+        self.assertThat(probe_servers_mock, MockCalledOnceWith(api))
+        params = {
+            'power_address': url,
+            'power_user': username,
+            'power_pass': password,
+            'uuid': server[0]['uuid']
+        }
+        self.assertThat(create_node_mock,
+                        MockCalledOnceWith(server[1], 'amd64', 'ucsm', params))
+
+
+class TestGetServiceProfile(MAASTestCase):
+    """Tests for ``get_service_profile.``"""
+
+    def test_get_service_profile(self):
+        test_dn = make_dn()
+        server = Element('computeBlade', {'assignedToDn': test_dn})
+        api = make_api()
+        mock = self.patch(api, 'config_resolve_dn')
+        mock.return_value = make_fake_result('configResolveDn', 'lsServer',
+                                             'outConfig')
+        service_profile = get_service_profile(api, server)
+        self.assertThat(mock, MockCalledOnceWith(test_dn))
+        self.assertEqual(mock.return_value[0], service_profile)
+
+
+def make_boot_order_scenarios(size):
+    minimum = random.randint(0, 500)
+    ordinals = xrange(minimum, minimum + size)
+
+    elements = [
+        Element('Entry%d' % i, {'order': '%d' % i})
+        for i in ordinals
+    ]
+
+    orders = permutations(elements)
+    orders = [{'order': order} for order in orders]
+
+    scenarios = [('%d' % i, order) for i, order in enumerate(orders)]
+    return scenarios, minimum
+
+
+class TestGetFirstBooter(MAASTestCase):
+    """Tests for ``get_first_booter.``"""
+
+    scenarios, minimum = make_boot_order_scenarios(3)
+
+    def test_first_booter(self):
+        root = Element('outConfigs')
+        root.extend(self.order)
+        picked = get_first_booter(root)
+        self.assertEqual(picked.tag, 'Entry%d' % self.minimum)
+
+
+class TestsForStripRoKeys(MAASTestCase):
+    """Tests for ``strip_ro_keys.``"""
+
+    def test_strip_ro_keys(self):
+        attributes = {key: 'DC' for key in RO_KEYS}
+
+        elements = [
+            Element('Element%d' % i, attributes)
+            for i in xrange(random.randint(0, 10))
+        ]
+
+        strip_ro_keys(elements)
+
+        for key in RO_KEYS:
+            values = [element.get(key) for element in elements]
+            for value in values:
+                self.assertIsNone(value)
+
+
+class TestMakePolicyChange(MAASTestCase):
+    """Tests for ``make_policy_change``."""
+
+    def test_lan_already_top_priority(self):
+        boot_profile_response = make_fake_result('configResolveChildren',
+                                                 'lsbootLan')
+        mock = self.patch(ucsm, 'get_first_booter')
+        mock.return_value = boot_profile_response[0]
+        change = make_policy_change(boot_profile_response)
+        self.assertIsNone(change)
+        self.assertThat(mock, MockCalledOnceWith(boot_profile_response))
+
+    def test_change_lan_to_top_priority(self):
+        boot_profile_response = Element('outConfigs')
+        lan_boot = Element('lsbootLan', {'order': 'second'})
+        storage_boot = Element('lsbootStorage', {'order': 'first'})
+        boot_profile_response.extend([lan_boot, storage_boot])
+        self.patch(ucsm, 'get_first_booter').return_value = storage_boot
+        self.patch(ucsm, 'strip_ro_keys')
+        change = make_policy_change(boot_profile_response)
+        lan_boot_order = change.xpath('//lsbootPolicy/lsbootLan/@order')
+        storage_boot_order = \
+            change.xpath('//lsbootPolicy/lsbootStorage/@order')
+        self.assertEqual(['first'], lan_boot_order)
+        self.assertEqual(['second'], storage_boot_order)
+
+
+class TestSetLanBootDefault(MAASTestCase):
+    """Tets for ``set_lan_boot_default.``"""
+
+    def test_no_change(self):
+        api = make_api()
+        server = make_server()
+        self.patch(ucsm, 'get_service_profile')
+        self.patch(api, 'config_resolve_children')
+        self.patch(ucsm, 'make_policy_change').return_value = None
+        config_conf_mo = self.patch(api, 'config_conf_mo')
+        set_lan_boot_default(api, server)
+        self.assertThat(config_conf_mo, MockNotCalled())
+
+    def test_with_change(self):
+        api = make_api()
+        server = make_server()
+        test_dn = make_dn()
+        test_change = 'change'
+        service_profile = Element('test', {'operBootPolicyName': test_dn})
+        self.patch(ucsm, 'get_service_profile').return_value = service_profile
+        self.patch(api, 'config_resolve_children')
+        self.patch(ucsm, 'make_policy_change').return_value = test_change
+        config_conf_mo = self.patch(api, 'config_conf_mo')
+        set_lan_boot_default(api, server)
+        self.assertThat(config_conf_mo,
+                        MockCalledOnceWith(test_dn, [test_change]))

=== added file 'src/provisioningserver/custom_hardware/ucsm.py'
--- src/provisioningserver/custom_hardware/ucsm.py	1970-01-01 00:00:00 +0000
+++ src/provisioningserver/custom_hardware/ucsm.py	2014-05-06 13:49:30 +0000
@@ -0,0 +1,435 @@
+# Copyright 2014 Canonical Ltd.  This software is licensed under the
+# GNU Affero General Public License version 3 (see the file LICENSE).
+
+"""Support for managing nodes via Cisco UCS Manager's HTTP-XML API.
+
+It's useful to have a cursory understanding of how UCS Manager XML API
+works. Cisco has a proprietary document that describes all of this in
+more detail, and I would suggest you get a copy of that if you want more
+information than is provided here.
+
+The Cisco DevNet website for UCS Manager has a link to the document,
+which is behind a login wall, and links to example UCS queries:
+
+https://developer.cisco.com/web/unifiedcomputing/home
+
+UCS Manager is a tool for managing servers. It provides an XML API for
+external applications to use to interact with UCS Manager to manage
+servers. The API is available via HTTP, and requests and responses are
+made of XML strings. MAAS's code for interacting with a UCS Manager is
+concerned with building these requests, sending them to UCS Manager, and
+processing the responses.
+
+UCS Manager stores information in a hierarchical structure known as the
+management information tree. This structure is exposed via the XML API,
+where we can manipulate objects in the tree by finding them, reading
+them, and writing them.
+
+Some definitions for terms that are used in this code:
+
+Boot Policy - Controls the boot order for a server. Each service profile
+is associated with a boot policy.
+
+Distinguished Name (DN) - Each object in UCS has a unique DN, which
+describes its position in the tree. This is like a fully qualified path,
+and provides a way for objects to reference other objects at other
+places in the tree, or for API users to look up specific objects in the
+tree.
+
+Class - Classes define the properties and states of objects. An object's
+class is given in its tag name.
+
+Managed Object (MO) - An object in the management information tree.
+Objects are recursive, and may have children of multiple types. With the
+exception of the root object, all objects have parents. In the XML API,
+objects are represented as XML elements.
+
+Method - Actions performed by the API on managed objects. These can
+change state, or read the current state, or both.
+
+Server - A physical server managed by UCS Manager. Servers must be
+associated with service profiles in order to be used.
+
+Service Profile - A set of configuration options for a server. Service
+profiles define the server's personality, and can be migrated from
+server to server. Service profiles describe boot policy, MAC addresses,
+network connectivity, IPMI configuration, and more. MAAS requires
+servers to be associated with service profiles.
+
+UUID - The UUID for a server. MAAS persists the UUID of each UCS managed
+server it enlists, and uses it as a key for looking the server up later.
+"""
+
+from __future__ import (
+    absolute_import,
+    print_function,
+    unicode_literals,
+    )
+
+import contextlib
+import urllib2
+import urlparse
+
+from lxml.etree import (
+    Element,
+    tostring,
+    XML,
+    )
+import provisioningserver.custom_hardware.utils as utils
+
+
+str = None
+
+__metaclass__ = type
+__all__ = [
+    'power_control_ucsm',
+    'probe_and_enlist_ucsm',
+]
+
+
+class UCSM_XML_API_Error(Exception):
+    """Failure talking to a Cisco UCS Manager."""
+
+    def __init__(self, msg, code):
+        super(UCSM_XML_API_Error, self).__init__(msg)
+        self.code = code
+
+
+def make_request_data(name, fields=None, children=None):
+    """Build a request string for an API method."""
+    root = Element(name, fields)
+    if children is not None:
+        root.extend(children)
+    return tostring(root)
+
+
+def parse_response(response_string):
+    """Parse the response from an API method."""
+    doc = XML(response_string)
+
+    error_code = doc.get('errorCode')
+    if error_code is not None:
+        raise UCSM_XML_API_Error(doc.get('errorDescr'), error_code)
+
+    return doc
+
+
+class UCSM_XML_API(object):
+    """Provides access to a Cisco UCS Manager's XML API. Public methods
+    on this class correspond to UCS Manager XML API methods.
+
+    Each request uses a new connection. The server supports keep-alive,
+    so this client could be optimized to use it too.
+    """
+
+    def __init__(self, url, username, password):
+        self.url = url
+        self.api_url = urlparse.urljoin(self.url, 'nuova')
+        self.username = username
+        self.password = password
+        self.cookie = None
+
+    def _send_request(self, request_data):
+        """Issue a request via HTTP and parse the response."""
+        request = urllib2.Request(self.api_url, request_data)
+        response = urllib2.urlopen(request)
+        response_text = response.read()
+        response_doc = parse_response(response_text)
+        return response_doc
+
+    def _call(self, name, fields=None, children=None):
+        request_data = make_request_data(name, fields, children)
+        response = self._send_request(request_data)
+        return response
+
+    def login(self):
+        """Login to the API and get a cookie.
+
+        Logging into the API gives a new cookie in response. The cookie
+        will become inactive after it has been inactive for some amount
+        of time (10 minutes is the default.)
+
+        UCS Manager allows a limited number of active cookies at any
+        point in time, so it's important to free the cookie up when
+        finished by logging out via the ``logout`` method.
+        """
+        fields = {'inName': self.username, 'inPassword': self.password}
+        response = self._call('aaaLogin', fields)
+        self.cookie = response.get('outCookie')
+
+    def logout(self):
+        """Logout from the API and free the cookie."""
+        fields = {'inCookie': self.cookie}
+        self._call('aaaLogout', fields)
+        self.cookie = None
+
+    def config_resolve_class(self, class_id, filters=None):
+        """Issue a configResolveClass request.
+
+        This returns all of the objects of class ``class_id`` from the
+        UCS Manager.
+
+        Filters provide a way of limiting the classes returned according
+        to their attributes. There are a number of filters available -
+        Cisco's XML API documentation has a full chapter on filters.
+        All we care about here is that filters are described with XML
+        elements.
+        """
+        fields = {'cookie': self.cookie, 'classId': class_id}
+
+        in_filters = Element('inFilter')
+        if filters:
+            in_filters.extend(filters)
+
+        return self._call('configResolveClass', fields, [in_filters])
+
+    def config_resolve_children(self, dn, class_id=None):
+        """Issue a configResolveChildren request.
+
+        This returns all of the children of the object named by ``dn``,
+        or if ``class_id`` is not None, all of the children of type
+        ``class_id``.
+        """
+        fields = {'cookie': self.cookie, 'inDn': dn}
+        if class_id is not None:
+            fields['classId'] = class_id
+        return self._call('configResolveChildren', fields)
+
+    def config_resolve_dn(self, dn):
+        """Retrieve a single object by name.
+
+        This returns the object named by ``dn``, but not its children.
+        """
+        fields = {'cookie': self.cookie, 'dn': dn}
+        return self._call('configResolveDn', fields)
+
+    def config_conf_mo(self, dn, config_items):
+        """Issue a configConfMo request.
+
+        This makes a configuration change on an object (MO).
+        """
+        fields = {'cookie': self.cookie, 'dn': dn}
+
+        in_configs = Element('inConfig')
+        in_configs.extend(config_items)
+
+        self._call('configConfMo', fields, [in_configs])
+
+
+def get_servers(api, uuid=None):
+    """Retrieve a list of servers from the UCS Manager."""
+    if uuid:
+        attrs = {'class': 'computeItem', 'property': 'uuid', 'value': uuid}
+        filters = [Element('eq', attrs)]
+    else:
+        filters = None
+
+    resolved = api.config_resolve_class('computeItem', filters)
+    return resolved.xpath('//outConfigs/*')
+
+
+def get_children(api, element, class_id):
+    """Retrieve a list of child elements from the UCS Manager."""
+    resolved = api.config_resolve_children(element.get('dn'), class_id)
+    return resolved.xpath('//outConfigs/%s' % class_id)
+
+
+def get_macs(api, server):
+    """Retrieve the list of MAC addresses assigned to a server.
+
+    Network interfaces are represented by 'adaptorUnit' objects, and
+    are stored as children of servers.
+    """
+    adaptors = get_children(api, server, 'adaptorUnit')
+
+    macs = []
+    for adaptor in adaptors:
+        host_eth_ifs = get_children(api, adaptor, 'adaptorHostEthIf')
+        macs.extend([h.get('mac') for h in host_eth_ifs])
+
+    return macs
+
+
+def probe_servers(api):
+    """Retrieve the UUID and MAC addresses for servers from the UCS Manager."""
+    servers = get_servers(api)
+    server_list = [(s, get_macs(api, s)) for s in servers]
+    return server_list
+
+
+def get_server_power_control(api, server):
+    """Retrieve the power control object for a server."""
+    service_profile_dn = server.get('assignedToDn')
+    resolved = api.config_resolve_children(service_profile_dn, 'lsPower')
+    power_controls = resolved.xpath('//outConfigs/lsPower')
+    return power_controls[0]
+
+
+def set_server_power_control(api, power_control, command):
+    """Issue a power command to a server's power control."""
+    attrs = {'state': command, 'dn': power_control.get('dn')}
+    power_change = Element('lsPower', attrs)
+    api.config_conf_mo(power_control.get('dn'), [power_change])
+
+
+def get_service_profile(api, server):
+    """Get the server's assigned service profile."""
+    service_profile_dn = server.get('assignedToDn')
+    result = api.config_resolve_dn(service_profile_dn)
+    service_profile = result.xpath('//outConfig/lsServer')[0]
+    return service_profile
+
+
+def get_first_booter(boot_profile_response):
+    """Find the device currently set to boot by default."""
+    ordinals = boot_profile_response.xpath('//outConfigs/*/@order')
+    top_boot_order = min(ordinals)
+    first_query = '//outConfigs/*[@order=%s]' % top_boot_order
+    current_first = boot_profile_response.xpath(first_query)[0]
+    return current_first
+
+
+RO_KEYS = ['access', 'type']
+
+
+def strip_ro_keys(elements):
+    """Remove read-only keys from configuration elements.
+
+    These are keys for attributes that aren't allowed to be changed via
+    configConfMo request. They are included in MO's that we read from the
+    API; stripping these attributes lets us reuse the elements for those
+    MO's rather than building new ones from scratch.
+    """
+    for ro_key in RO_KEYS:
+        for element in elements:
+            del(element.attrib[ro_key])
+
+
+def make_policy_change(boot_profile_response):
+    """Build the policy change tree required to make LAN boot first
+    priority.
+
+    The original top priority will be swapped with LAN boot's original
+    priority.
+    """
+    current_first = get_first_booter(boot_profile_response)
+    lan_boot = boot_profile_response.xpath('//outConfigs/lsbootLan')[0]
+
+    if current_first == lan_boot:
+        return
+
+    top_boot_order = current_first.get('order')
+    current_first.set('order', lan_boot.get('order'))
+    lan_boot.set('order', top_boot_order)
+
+    elements = [current_first, lan_boot]
+    strip_ro_keys(elements)
+    policy_change = Element('lsbootPolicy')
+    policy_change.extend(elements)
+    return policy_change
+
+
+def set_lan_boot_default(api, server):
+    """Set a server to boot via LAN by default.
+
+    If LAN boot is already the top priority, no change will
+    be made.
+
+    This command changes the server's boot profile, which will affect
+    any other servers also using that boot profile. This is ok, because
+    probe and enlist enlists all the servers in the chassis.
+    """
+    service_profile = get_service_profile(api, server)
+    boot_profile_dn = service_profile.get('operBootPolicyName')
+    response = api.config_resolve_children(boot_profile_dn)
+    policy_change = make_policy_change(response)
+    if policy_change is None:
+        return
+    api.config_conf_mo(boot_profile_dn, [policy_change])
+
+
[e-mail]
+def logged_in(url, username, password):
+    """Context manager that ensures the logout from the API occurs."""
+    api = UCSM_XML_API(url, username, password)
+    api.login()
+    try:
+        yield api
+    finally:
+        api.logout()
+
+
+def get_power_command(maas_power_mode, current_state):
+    """Translate a MAAS on/off state into a UCSM power command.
+
+    If the node is up already and receives a request to power on, power
+    cycle the node.
+    """
+    if maas_power_mode == 'on':
+        if current_state == 'up':
+            return 'cycle-immediate'
+        return 'admin-up'
+    elif maas_power_mode == 'off':
+        return 'admin-down'
+    else:
+        message = 'Unexpected maas power mode: %s' % (maas_power_mode)
+        raise AssertionError(message)
+
+
+def power_control_ucsm(url, username, password, uuid, maas_power_mode):
+    """Handle calls from the power template for nodes with a power type
+    of 'ucsm'.
+    """
+    with logged_in(url, username, password) as api:
+        # UUIDs are unique per server, so we get either one or zero
+        # servers for a given UUID.
+        [server] = get_servers(api, uuid)
+        power_control = get_server_power_control(api, server)
+        command = get_power_command(maas_power_mode,
+                                    power_control.get('state'))
+        set_server_power_control(api, power_control, command)
+
+
+def probe_and_enlist_ucsm(url, username, password):
+    """Probe a UCS Manager and enlist all its servers.
+
+    Here's what happens here: 1. Get a list of servers from the UCS
+    Manager, along with their MAC addresses.
+
+    2. Configure each server to boot from LAN first.
+
+    3. Add each server to MAAS as a new node, with a power control
+    method of 'ucsm'. The URL and credentials supplied are persisted
+    with each node so MAAS knows how to access UCSM to manage the node
+    in the future.
+
+    This code expects each server in the system to have already been
+    associated with a service profile. The servers must have networking
+    configured, and their boot profiles must include a boot from LAN
+    option. During enlistment, the boot profile for each service profile
+    used by a server will be modified to move LAN boot to the highest
+    priority boot option.
+
+    Also, if any node fails to enlist, this enlistment process will
+    stop and won't attempt to enlist any additional nodes. If a node is
+    already known to MAAS, it will fail to enlist, so all nodes must be
+    added at once.
+
+    There is also room for optimization during enlistment. While our
+    client deals with a single server at a time, the API is capable
+    of reading/writing the settings of multiple servers in the same
+    request.
+    """
+    with logged_in(url, username, password) as api:
+        servers = probe_servers(api)
+        for server, _ in servers:
+            set_lan_boot_default(api, server)
+
+    for server, macs in servers:
+        params = {
+            'power_address': url,
+            'power_user': username,
+            'power_pass': password,
+            'uuid': server.get('uuid'),
+        }
+        utils.create_node(macs, 'amd64', 'ucsm', params)

=== modified file 'src/provisioningserver/power/tests/test_poweraction.py'
--- src/provisioningserver/power/tests/test_poweraction.py	2014-02-27 02:33:54 +0000
+++ src/provisioningserver/power/tests/test_poweraction.py	2014-05-06 13:49:30 +0000
@@ -223,3 +223,14 @@
             power_pass='me', power_hwaddress='me', ipmitool='echo')
         output = action.run_shell(script)
         self.assertIn("Got unknown power state from ipmipower", output)
+
+    def test_ucsm_renders_template(self):
+        # I'd like to assert that escape_py_literal is being used here,
+        # but it's not obvious how to mock things in the template
+        # rendering namespace so I passed on that.
+        action = PowerAction('ucsm')
+        script = action.render_template(
+            action.get_template(), power_address='foo',
+            power_user='bar', power_pass='baz',
+            uuid=factory.getRandomUUID(), power_change='on')
+        self.assertIn('power_control_ucsm', script)

=== modified file 'src/provisioningserver/power_schema.py'
--- src/provisioningserver/power_schema.py	2014-04-23 14:21:03 +0000
+++ src/provisioningserver/power_schema.py	2014-05-06 13:49:30 +0000
@@ -242,4 +242,14 @@
             make_json_field('power_pass', "Power password"),
         ],
     },
+    {
+        'name': 'ucsm',
+        'description': "Cisco UCS Manager",
+        'fields': [
+            make_json_field('uuid', "Server UUID"),
+            make_json_field('power_address', "URL for XML API"),
+            make_json_field('power_user', "API user"),
+            make_json_field('power_pass', "API password"),
+        ],
+    },
 ]

=== modified file 'src/provisioningserver/tasks.py'
--- src/provisioningserver/tasks.py	2014-04-22 15:10:32 +0000
+++ src/provisioningserver/tasks.py	2014-05-06 13:49:30 +0000
@@ -45,6 +45,7 @@
 from provisioningserver.custom_hardware.seamicro import (
     probe_seamicro15k_and_enlist,
     )
+from provisioningserver.custom_hardware.ucsm import probe_and_enlist_ucsm
 from provisioningserver.dhcp import (
     config,
     detect,
@@ -477,3 +478,10 @@
             power_control=power_control)
     else:
         logger.warning("Couldn't find IP address for MAC %s" % mac)
+
+
+@task
+@log_exception_text
+def enlist_nodes_from_ucsm(url, username, password):
+    """ See `maasserver.api.NodeGroupsHandler.enlist_nodes_from_ucsm`. """
+    probe_and_enlist_ucsm(url, username, password)

=== modified file 'src/provisioningserver/tests/test_tasks.py'
--- src/provisioningserver/tests/test_tasks.py	2014-04-22 15:10:32 +0000
+++ src/provisioningserver/tests/test_tasks.py	2014-05-06 13:49:30 +0000
@@ -72,6 +72,7 @@
 from provisioningserver.tags import MissingCredentials
 from provisioningserver.tasks import (
     add_new_dhcp_host_map,
+    enlist_nodes_from_ucsm,
     import_boot_images,
     Omshell,
     power_off,
@@ -676,3 +677,14 @@
         mock_callback = Mock()
         import_boot_images(callback=mock_callback)
         self.assertThat(mock_callback.delay, MockCalledOnceWith())
+
+
+class TestAddUCSM(PservTestCase):
+
+    def test_enlist_nodes_from_ucsm(self):
+        url = 'url'
+        username = 'username'
+        password = 'password'
+        mock = self.patch(tasks, 'probe_and_enlist_ucsm')
+        enlist_nodes_from_ucsm(url, username, password)
+        self.assertThat(mock, MockCalledOnceWith(url, username, password))

=== modified file 'src/provisioningserver/utils/__init__.py'
--- src/provisioningserver/utils/__init__.py	2014-04-21 23:20:49 +0000
+++ src/provisioningserver/utils/__init__.py	2014-05-06 13:49:30 +0000
@@ -512,6 +512,11 @@
             self.__class__.__name__, self.value)
 
 
+def escape_py_literal(string):
+    """Escape and quote a string for use as a python literal."""
+    return repr(string).decode('ascii')
+
+
 class ShellTemplate(tempita.Template):
     """A Tempita template specialised for writing shell scripts.
 

=== modified file 'src/provisioningserver/utils/tests/test_utils.py'
--- src/provisioningserver/utils/tests/test_utils.py	2014-04-24 08:51:41 +0000
+++ src/provisioningserver/utils/tests/test_utils.py	2014-05-06 13:49:30 +0000
@@ -82,6 +82,7 @@
     MainScript,
     parse_key_value_file,
     pick_new_mtime,
+    escape_py_literal,
     read_text_file,
     Safe,
     ShellTemplate,
@@ -1393,3 +1394,22 @@
         # modification. The arguments passed back match those passed in
         # from do_stuff_in_thread().
         self.assertEqual(((3, 4), {"five": 5}), result)
+
+
+class TestQuotePyLiteral(MAASTestCase):
+    def test_uses_repr(self):
+        string = factory.make_name('string')
+        repr_mock = self.patch(provisioningserver.utils, 'repr')
+        escape_py_literal(string)
+        self.assertThat(repr_mock, MockCalledOnceWith(string))
+
+    def test_decodes_ascii(self):
+        string = factory.make_name('string')
+        output = factory.make_name('output')
+        repr_mock = self.patch(provisioningserver.utils, 'repr')
+        ascii_value = Mock()
+        ascii_value.decode = Mock(return_value=output)
+        repr_mock.return_value = ascii_value
+        value = escape_py_literal(string)
+        self.assertThat(ascii_value.decode, MockCalledOnceWith('ascii'))
+        self.assertEqual(value, output)