Merge lp:~dimitern/juju-core/381-state-machine-nics into lp:~go-bot/juju-core/trunk

[Dimiter Naydenov]

state: Add machine networks and interfaces

Added a couple of entities (and related methods) in state:
 * Network - holds a name, CIDR and VLAN tag; used to
   describe actual configured networks that machines
   need to be on.
 * NetworkInterface - linked to a machine id and network
   name, holds the network interface name to MAC address
   mapping in state (MAC address as key for uniqueness);
   machines support adding one or more NICs.

Renamed machine.Network() and st.networks to RequestedNetworks()
and st.requestedNetworks (in code only, schema remains the same).
This helps avoid confusion between the requested networks
(to include/exclude on a machine, coming from the service; they
are now called "requested networks"), and actually configured
networks on a running machine (just "networks").

For now networks are immutable, can't be removed and NICs can be
added to them only if their machine is not provisioned yet.
NICs are only removed when the machine itself is removed.

Provisioner API change: renamed Networks() to RequestedNetworks()
which is fine, because Networks() was added recently and not
released yet.

We'll use the added machine NICs to show enabled networks
in juju status later on, and they will be set at StartInstance()
time inside the provisioner. Internally, MaaS provider changes
will be needed to get NIC-to-MAC mapping for an acquired node
and the list of networks for it.

https://codereview.appspot.com/83070047/

R=fwereade

state: Add machine networks and interfaces

Added a couple of entities (and related methods) in state:
 * Network - holds a name, CIDR and VLAN tag; used to
   describe actual configured networks that machines
   need to be on.
 * NetworkInterface - linked to a machine id and network
   name, holds the network interface name to MAC address
   mapping in state (MAC address as key for uniqueness);
   machines support adding one or more NICs.

Renamed machine.Network() and st.networks to RequestedNetworks()
and st.requestedNetworks (in code only, schema remains the same).
This helps avoid confusion between the requested networks
(to include/exclude on a machine, coming from the service; they
are now called "requested networks"), and actually configured
networks on a running machine (just "networks").

For now networks are immutable, can't be removed and NICs can be
added to them only if their machine is not provisioned yet.
NICs are only removed when the machine itself is removed.

Provisioner API change: renamed Networks() to RequestedNetworks()
which is fine, because Networks() was added recently and not
released yet.

We'll use the added machine NICs to show enabled networks
in juju status later on, and they will be set at StartInstance()
time inside the provisioner. Internally, MaaS provider changes
will be needed to get NIC-to-MAC mapping for an acquired node
and the list of networks for it.

https://codereview.appspot.com/83070047/

[Dimiter Naydenov (dimitern)]

Reviewers: mp+213796_code.launchpad.net,

Message:
Please take a look.

Description:
state: Add machine.(Set)NetworkInterfaces

Added two new methods and a field on the machine document:
  * machineDoc.NetworkInterfaces []state.NetworkInterface
    (contains configured NICs for the machine with their
    name, CIDR, VLAN tag and MAC address);
  * machine.NetworkInterfaces() returns previously set NICs;
  * machine.SetNetworkInterfaces() will be called by the
    provisioner at StartInstance() time set discovered network
    interfaces (from the provider) when include/excludeNetworks
    is specified.

This is needed to show actual network interfaces and their linked
networks in juju status, as well as to prepare the parameters
needed by cloudinit scripts to set up the NICs at boot time
(only when networks are present).

https://code.launchpad.net/~dimitern/juju-core/381-state-machine-nics/+merge/213796

Requires:
https://code.launchpad.net/~dimitern/juju-core/380-provisioner-honors-networks/+merge/213647

(do not edit description out of merge proposal)

Please review this at https://codereview.appspot.com/83070047/

Affected files (+1986, -1111 lines):
   A [revision details]
   M agent/agent.go
   M agent/agent_test.go
   M agent/bootstrap.go
   M agent/bootstrap_test.go
   M agent/mongo/mongo.go
   M agent/mongo/mongo_test.go
   M cmd/cmd.go
   M cmd/envcmd/environmentcommand.go
   M cmd/envcmd/environmentcommand_test.go
   M cmd/envcmd/export_test.go
   M cmd/juju/addmachine.go
   M cmd/juju/addrelation.go
   M cmd/juju/addunit.go
   A cmd/juju/adduser.go
   A cmd/juju/adduser_test.go
   M cmd/juju/authorisedkeys_add.go
   M cmd/juju/authorisedkeys_delete.go
   M cmd/juju/authorisedkeys_import.go
   M cmd/juju/authorisedkeys_list.go
   M cmd/juju/bootstrap.go
   M cmd/juju/bootstrap_test.go
   M cmd/juju/cmd_test.go
   M cmd/juju/constraints.go
   M cmd/juju/debuglog_test.go
   M cmd/juju/deploy.go
   M cmd/juju/destroymachine.go
   M cmd/juju/destroyrelation.go
   M cmd/juju/destroyservice.go
   M cmd/juju/destroyunit.go
   M cmd/juju/endpoint.go
   M cmd/juju/ensureavailability.go
   M cmd/juju/environment.go
   M cmd/juju/expose.go
   M cmd/juju/get.go
   M cmd/juju/plugin.go
   M cmd/juju/publish.go
   M cmd/juju/publish_test.go
   A cmd/juju/removeuser.go
   A cmd/juju/removeuser_test.go
   M cmd/juju/resolved.go
   M cmd/juju/retryprovisioning.go
   M cmd/juju/run.go
   M cmd/juju/run_test.go
   M cmd/juju/scp_test.go
   M cmd/juju/set.go
   M cmd/juju/ssh.go
   M cmd/juju/ssh_test.go
   M cmd/juju/status.go
   M cmd/juju/status_test.go
   M cmd/juju/switch.go
   M cmd/juju/switch_test.go
   M cmd/juju/synctools.go
   M cmd/juju/unexpose.go
   M cmd/juju/unset.go
   M cmd/juju/upgradecharm.go
   M cmd/juju/upgradejuju.go
   M cmd/jujud/bootstrap.go
   M cmd/jujud/bootstrap_test.go
   M cmd/jujud/machine_test.go
   M cmd/jujud/run_test.go
   M cmd/plugins/juju-metadata/imagemetadata.go
   M cmd/plugins/juju-metadata/toolsmetadata.go
   M cmd/plugins/juju-metadata/validateimagemetadata.go
   M cmd/plugins/juju-metadata/validatetoolsmetadata.go
   M cmd/plugins/juju-restore/restore.go
   M cmd/supercommand.go
   M dependencies.tsv
   M...

[Dimiter Naydenov (dimitern)]

Please take a look.

https://codereview.appspot.com/83070047/

[William Reade (fwereade)]

Couple of tweaks please.

https://codereview.appspot.com/83070047/diff/20001/state/machine.go
File state/machine.go (right):

https://codereview.appspot.com/83070047/diff/20001/state/machine.go#newcode915
state/machine.go:915: Update: bson.D{{"$set",
bson.D{{"networkinterfaces", ifaces}}}},
I get really nervous when we use the same struct in the interface and in
the actual data storage -- it's just too easy for changes to break
stuff.

And... can we put it on a separate doc please? It's just the usual
read/write/watch usage patterns issue.

https://codereview.appspot.com/83070047/

[Dimiter Naydenov (dimitern)]

Please take a look.

https://codereview.appspot.com/83070047/diff/20001/state/machine.go
File state/machine.go (right):

https://codereview.appspot.com/83070047/diff/20001/state/machine.go#newcode915
state/machine.go:915: Update: bson.D{{"$set",
bson.D{{"networkinterfaces", ifaces}}}},
On 2014/04/02 10:18:45, fwereade wrote:
> I get really nervous when we use the same struct in the interface and
in the
> actual data storage -- it's just too easy for changes to break stuff.

> And... can we put it on a separate doc please? It's just the usual
> read/write/watch usage patterns issue.

Changed as discussed - separate docs for networks and NICs, linked to a
machine.

https://codereview.appspot.com/83070047/

[William Reade (fwereade)]

Some naming quibbles; and quite a lot of freakouts wrt races. Most can
be eliminated by dropping Remove methods, I think.

https://codereview.appspot.com/83070047/diff/40001/juju/conn_test.go
File juju/conn_test.go (right):

https://codereview.appspot.com/83070047/diff/40001/juju/conn_test.go#newcode406
juju/conn_test.go:406: include, exclude, err := machine.LinkedNetworks()
Can we call this RequestedNetworks or something? "Linked" doesn't fit my
brain here.

https://codereview.appspot.com/83070047/diff/40001/state/addmachine.go
File state/addmachine.go (right):

https://codereview.appspot.com/83070047/diff/40001/state/addmachine.go#newcode425
state/addmachine.go:425: createLinkedNetworksOp(st,
machineGlobalKey(mdoc.Id),
can we have a TODO and bug for the lack of sanity-checking here? ideally
we'd be checking names against actual networks.

https://codereview.appspot.com/83070047/diff/40001/state/cleanup.go
File state/cleanup.go (right):

https://codereview.appspot.com/83070047/diff/40001/state/cleanup.go#newcode140
state/cleanup.go:140: // depend upon the supplied machine, and removes
the machine from state. It's
whoops, please s/removes the machine from state/sets the machine to
Dead/

https://codereview.appspot.com/83070047/diff/40001/state/cleanup.go#newcode157
state/cleanup.go:157: if err :=
st.cleanupLinkedNetworks(machineGlobalKey(machineId)); err != nil {
Sorry I missed this before, but I don't see the point of this code. All
it does is leave an extant machine doc without linked networks -- not
fatal, sure, but not very useful either.

We should just run the appropriate ops when we remove a service/machine,
and leave cleanup out of it.

https://codereview.appspot.com/83070047/diff/40001/state/machine.go
File state/machine.go (right):

https://codereview.appspot.com/83070047/diff/40001/state/machine.go#newcode890
state/machine.go:890: }
Possibly this is something more like a NetworkSpecification?

https://codereview.appspot.com/83070047/diff/40001/state/machine.go#newcode893
state/machine.go:893: func (m *Machine) MachineNetworks()
([]*MachineNetwork, error) {
and I think this is more like just Networks()

https://codereview.appspot.com/83070047/diff/40001/state/machine.go#newcode939
state/machine.go:939: Name: name,
InterfaceName?

https://codereview.appspot.com/83070047/diff/40001/state/machine.go#newcode952
state/machine.go:952: }}
I think we need an assert that the machine is alive. IIRC machines can't
fast-forward from alive to removed, so that should be sufficient to
maintain integrity in the face of remove-all-interfaces ops called at
machine-Remove time.

https://codereview.appspot.com/83070047/diff/40001/state/machine_test.go
File state/machine_test.go (right):

https://codereview.appspot.com/83070047/diff/40001/state/machine_test.go#newcode394
state/machine_test.go:394: net, err := st.AddMachineNetwork(networkName,
cidr, vlanTag)
I don't think this is really a MachineNetwork, is it? it feels like it's
the heart of the actual network model in juju and deserves the name
Network...

https://codereview.appspot.com/83070047/diff/40001/state/machine_test.go#newcode396
state/machine_test.go:396: iface, err :=
machine.AddNetw...

[Dimiter Naydenov (dimitern)]

Please take a look.

https://codereview.appspot.com/83070047/diff/40001/juju/conn_test.go
File juju/conn_test.go (right):

https://codereview.appspot.com/83070047/diff/40001/juju/conn_test.go#newcode406
juju/conn_test.go:406: include, exclude, err := machine.LinkedNetworks()
On 2014/04/03 16:37:09, fwereade wrote:
> Can we call this RequestedNetworks or something? "Linked" doesn't fit
my brain
> here.

Done.

https://codereview.appspot.com/83070047/diff/40001/state/addmachine.go
File state/addmachine.go (right):

https://codereview.appspot.com/83070047/diff/40001/state/addmachine.go#newcode425
state/addmachine.go:425: createLinkedNetworksOp(st,
machineGlobalKey(mdoc.Id),
On 2014/04/03 16:37:09, fwereade wrote:
> can we have a TODO and bug for the lack of sanity-checking here?
ideally we'd be
> checking names against actual networks.

Done.

https://codereview.appspot.com/83070047/diff/40001/state/cleanup.go
File state/cleanup.go (right):

https://codereview.appspot.com/83070047/diff/40001/state/cleanup.go#newcode140
state/cleanup.go:140: // depend upon the supplied machine, and removes
the machine from state. It's
On 2014/04/03 16:37:09, fwereade wrote:
> whoops, please s/removes the machine from state/sets the machine to
Dead/

Done.

https://codereview.appspot.com/83070047/diff/40001/state/cleanup.go#newcode157
state/cleanup.go:157: if err :=
st.cleanupLinkedNetworks(machineGlobalKey(machineId)); err != nil {
On 2014/04/03 16:37:09, fwereade wrote:
> Sorry I missed this before, but I don't see the point of this code.
All it does
> is leave an extant machine doc without linked networks -- not fatal,
sure, but
> not very useful either.

> We should just run the appropriate ops when we remove a
service/machine, and
> leave cleanup out of it.

Removed.

https://codereview.appspot.com/83070047/diff/40001/state/machine.go
File state/machine.go (right):

https://codereview.appspot.com/83070047/diff/40001/state/machine.go#newcode890
state/machine.go:890: }
On 2014/04/03 16:37:09, fwereade wrote:
> Possibly this is something more like a NetworkSpecification?

Do you mean rename the method or something else? I thought you suggested
to rename it to RequestedNetworks earlier.

https://codereview.appspot.com/83070047/diff/40001/state/machine.go#newcode893
state/machine.go:893: func (m *Machine) MachineNetworks()
([]*MachineNetwork, error) {
On 2014/04/03 16:37:09, fwereade wrote:
> and I think this is more like just Networks()

So, let's call this Networks() and the former RequestedNetworks() or
even maybe ServiceNetworks()?

https://codereview.appspot.com/83070047/diff/40001/state/machine.go#newcode939
state/machine.go:939: Name: name,
On 2014/04/03 16:37:09, fwereade wrote:
> InterfaceName?

Done.

https://codereview.appspot.com/83070047/diff/40001/state/machine.go#newcode952
state/machine.go:952: }}
On 2014/04/03 16:37:09, fwereade wrote:
> I think we need an assert that the machine is alive. IIRC machines
can't
> fast-forward from alive to removed, so that should be sufficient to
maintain
> integrity in the face of remove-all-interfaces ops called at
machine-Remove
> time.

Done.

https://codereview.appspot.com/83070047/diff/40001/state/mach...

[William Reade (fwereade)]

LGTM with relatively trivial fixes:

https://codereview.appspot.com/83070047/diff/40001/state/machine_test.go
File state/machine_test.go (right):

https://codereview.appspot.com/83070047/diff/40001/state/machine_test.go#newcode394
state/machine_test.go:394: net, err := st.AddMachineNetwork(networkName,
cidr, vlanTag)
On 2014/04/04 09:14:43, dimitern wrote:
> On 2014/04/03 16:37:09, fwereade wrote:
> > I don't think this is really a MachineNetwork, is it? it feels like
it's the
> > heart of the actual network model in juju and deserves the name
Network...

> Done, although arguably this specific definition of network concerns
only
> machines (i.e. NICs and the networks they're on are a property of a
machine).

I'm pretty sure netName/cidr/vlanTag defines a network -- and
ifceName/MAC/machine/network defines an interface. Am I ludicrously
wrong about something?

https://codereview.appspot.com/83070047/diff/40001/state/machine_test.go#newcode396
state/machine_test.go:396: iface, err :=
machine.AddNetworkInterface(mac, ifaceName, networkName)
On 2014/04/04 09:14:43, dimitern wrote:
> On 2014/04/03 16:37:09, fwereade wrote:
> > wondering if this should be net.AddMachine? just a thought, open to
> > counterarguments

> That's a fair point, I'm not sure. Networks (as of now) are created
when you
> need to add a NIC to a machine, but they stay past the lifetime of the
initial
> machine. On another hand, the machine comes first in the sequence of
things
> created in state (although this might change in the future).

I don't think we need to get this perfect now, because (yay!) this bit
of state at least is properly isolated.

https://codereview.appspot.com/83070047/diff/40001/state/networkinterfaces.go
File state/networkinterfaces.go (right):

https://codereview.appspot.com/83070047/diff/40001/state/networkinterfaces.go#newcode69
state/networkinterfaces.go:69: func removeNetworkInterfacesOps(st
*State, machineId string) []txn.Op {
On 2014/04/04 09:14:43, dimitern wrote:
> On 2014/04/03 16:37:09, fwereade wrote:
> > This is racy in isolation -- if we move it into the machine's Remove
method,
> > though, I think we're good. (with the check-machine-alive assert in
> > AddNetworkInterface, anyway)

> I don't quite follow - removeNetworkInterfacesOps() is called in
> machine.Remove() and run with the other []txn.Op already. Adding an
assert on
> machine.Life is only needed to keep dying or dead machines from having
NICs
> added (which can't happen right now as NICs are immutable and only
changed after
> provisioning), but if NICs can change at run-time (as can
> HardwareCharacteristics btw), that sounds exactly like a job for the
Networker
> worker we'll have after MVP.

I'd quite like that assert-alive-on-add to be in place anyway, because
it'll be way too easy to forget when we make this dynamic.

And this method in particular will be too easy to just call when we add
Remove -- but if we move it onto Machine and include a dead-check at the
start we at least put a little roadblock in the way of thoughtless later
refactoring.

> As with MachineNetworks, I think dropping Remove() entirely here, for
this CL is
> perhaps what we need.

+1 to that. But please...

[Dimiter Naydenov (dimitern)]

Please take a look.

https://codereview.appspot.com/83070047/diff/40001/state/networkinterfaces.go
File state/networkinterfaces.go (right):

https://codereview.appspot.com/83070047/diff/40001/state/networkinterfaces.go#newcode69
state/networkinterfaces.go:69: func removeNetworkInterfacesOps(st
*State, machineId string) []txn.Op {
On 2014/04/04 09:56:22, fwereade wrote:
> On 2014/04/04 09:14:43, dimitern wrote:
> > On 2014/04/03 16:37:09, fwereade wrote:
> > > This is racy in isolation -- if we move it into the machine's
Remove method,
> > > though, I think we're good. (with the check-machine-alive assert
in
> > > AddNetworkInterface, anyway)
> >
> > I don't quite follow - removeNetworkInterfacesOps() is called in
> > machine.Remove() and run with the other []txn.Op already. Adding an
assert on
> > machine.Life is only needed to keep dying or dead machines from
having NICs
> > added (which can't happen right now as NICs are immutable and only
changed
> after
> > provisioning), but if NICs can change at run-time (as can
> > HardwareCharacteristics btw), that sounds exactly like a job for the
Networker
> > worker we'll have after MVP.

> I'd quite like that assert-alive-on-add to be in place anyway, because
it'll be
> way too easy to forget when we make this dynamic.

> And this method in particular will be too easy to just call when we
add Remove
> -- but if we move it onto Machine and include a dead-check at the
start we at
> least put a little roadblock in the way of thoughtless later
refactoring.

> > As with MachineNetworks, I think dropping Remove() entirely here,
for this CL
> is
> > perhaps what we need.

> +1 to that. But please make this func a Machine method, and add the
alive
> assert.

Alive assert is already in place, moving this to a machine method.

https://codereview.appspot.com/83070047/diff/60001/state/addmachine.go
File state/addmachine.go (right):

https://codereview.appspot.com/83070047/diff/60001/state/addmachine.go#newcode425
state/addmachine.go:425: // TODO(dimitern) Once we can add networks
independently
On 2014/04/04 09:56:23, fwereade wrote:
> and a bug please :)

Done.

https://codereview.appspot.com/83070047/diff/60001/state/machine.go
File state/machine.go (right):

https://codereview.appspot.com/83070047/diff/60001/state/machine.go#newcode567
state/machine.go:567: // Remove sets the machine to Dead. It will fail
if the machine is not
On 2014/04/04 09:56:23, fwereade wrote:
> Nah, this one removes it from state (and requires that it's already
dead before
> it's called).

Done.

https://codereview.appspot.com/83070047/diff/60001/state/machine.go#newcode897
state/machine.go:897: func (m *Machine) Networks() ([]*Network, error) {
On 2014/04/04 09:56:23, fwereade wrote:
> Mildly forward-looking quibble, doesn't need to be done now: do we
need this? I
> presume it's being done for use in status; but should we not perhaps
actually be
> showing the machine's addresses *annotated* with what network that
address is
> on? ie we will want to combine the info from NetworkInterfaces with
that from
> Addresses and show that, and have a separate top-level section in
status for
> Networks?

For now we can't really link IP address...

[Dimiter Naydenov (dimitern)]

Please take a look.

https://codereview.appspot.com/83070047/

[William Reade (fwereade)]

LGTM, one last quibble

https://codereview.appspot.com/83070047/diff/60001/state/machine.go
File state/machine.go (right):

https://codereview.appspot.com/83070047/diff/60001/state/machine.go#newcode941
state/machine.go:941: aliveAndNotProvisioned := append(isAliveDoc,
bson.D{{"nonce", ""}}...)
On 2014/04/04 11:12:19, dimitern wrote:
> On 2014/04/04 09:56:23, fwereade wrote:
> > I think this is fine, assuming we have the provisioner pass the
interfaces
> into
> > SetProvisioned, and inside the APi server call AddNetworkInterface
before
> > SetProvisioned?

> I was thinking of having AddNetworkInterface on the Provisioner API
later and
> call it as needed before calling SetProvisioned (and changing machine
state to
> error if it happens, like we do after StartInstance errors).

> Is there a particular reason you want NICs passed to SetProvisioned?

(1) chatty APIs suck (2) the quicker we can get all the instance info
away from the provisioner and into the api server the better.

...in fact ...I'm almost tempted to say that this functionality should
be of a transaction with the SetProvisioned method in state *anyway* --
consider what happens if a machine has a NIC set up but then the process
fails before SetProvisioned.

That can be a minor refactoring when you hook up the provisioner,
though.

https://codereview.appspot.com/83070047/diff/80001/state/machine.go
File state/machine.go (right):

https://codereview.appspot.com/83070047/diff/80001/state/machine.go#newcode567
state/machine.go:567: func (m *Machine) removeNetworkInterfacesOps()
([]txn.Op, error) {
just add a quick pedantic check that the machine really is Dead in here
too

https://codereview.appspot.com/83070047/

[Dimiter Naydenov (dimitern)]

Please take a look.

https://codereview.appspot.com/83070047/diff/60001/state/machine.go
File state/machine.go (right):

https://codereview.appspot.com/83070047/diff/60001/state/machine.go#newcode941
state/machine.go:941: aliveAndNotProvisioned := append(isAliveDoc,
bson.D{{"nonce", ""}}...)
On 2014/04/04 12:10:03, fwereade wrote:
> On 2014/04/04 11:12:19, dimitern wrote:
> > On 2014/04/04 09:56:23, fwereade wrote:
> > > I think this is fine, assuming we have the provisioner pass the
interfaces
> > into
> > > SetProvisioned, and inside the APi server call AddNetworkInterface
before
> > > SetProvisioned?
> >
> > I was thinking of having AddNetworkInterface on the Provisioner API
later and
> > call it as needed before calling SetProvisioned (and changing
machine state to
> > error if it happens, like we do after StartInstance errors).
> >
> > Is there a particular reason you want NICs passed to SetProvisioned?

> (1) chatty APIs suck (2) the quicker we can get all the instance info
away from
> the provisioner and into the api server the better.

> ...in fact ...I'm almost tempted to say that this functionality should
be of a
> transaction with the SetProvisioned method in state *anyway* --
consider what
> happens if a machine has a NIC set up but then the process fails
before
> SetProvisioned.

> That can be a minor refactoring when you hook up the provisioner,
though.

Yes, I agree provisioning should be atomic, but it's not right now
because of StartInstance and SetProvisioned getting called in sequence
(and adding a couple of extra API calls will make it only a bit worse).
I'm in favor of fixing it in general, but this is out of scope for now.

https://codereview.appspot.com/83070047/diff/80001/state/machine.go
File state/machine.go (right):

https://codereview.appspot.com/83070047/diff/80001/state/machine.go#newcode567
state/machine.go:567: func (m *Machine) removeNetworkInterfacesOps()
([]txn.Op, error) {
On 2014/04/04 12:10:03, fwereade wrote:
> just add a quick pedantic check that the machine really is Dead in
here too

Done inside machine.Remove().

https://codereview.appspot.com/83070047/

=== modified file 'juju/conn_test.go'
--- juju/conn_test.go	2014-03-26 10:41:38 +0000
+++ juju/conn_test.go	2014-04-04 13:09:14 +0000
@@ -398,12 +398,12 @@
 	c.Assert(sch.Revision(), gc.Equals, rev+1)
 }
 
-func (s *ConnSuite) assertAssignedMachineNetworks(c *gc.C, unit *state.Unit, expectInclude, expectExclude []string) {
+func (s *ConnSuite) assertAssignedMachineRequestedNetworks(c *gc.C, unit *state.Unit, expectInclude, expectExclude []string) {
 	machineId, err := unit.AssignedMachineId()
 	c.Assert(err, gc.IsNil)
 	machine, err := s.conn.State.Machine(machineId)
 	c.Assert(err, gc.IsNil)
-	include, exclude, err := machine.Networks()
+	include, exclude, err := machine.RequestedNetworks()
 	c.Assert(err, gc.IsNil)
 	c.Assert(include, jc.DeepEquals, expectInclude)
 	c.Assert(exclude, jc.DeepEquals, expectExclude)
@@ -420,8 +420,8 @@
 	units, err := juju.AddUnits(s.conn.State, svc, 2, "")
 	c.Assert(err, gc.IsNil)
 	c.Assert(units, gc.HasLen, 2)
-	s.assertAssignedMachineNetworks(c, units[0], withNets, withoutNets)
-	s.assertAssignedMachineNetworks(c, units[1], withNets, withoutNets)
+	s.assertAssignedMachineRequestedNetworks(c, units[0], withNets, withoutNets)
+	s.assertAssignedMachineRequestedNetworks(c, units[1], withNets, withoutNets)
 
 	id0, err := units[0].AssignedMachineId()
 	c.Assert(err, gc.IsNil)
@@ -434,19 +434,19 @@
 
 	units, err = juju.AddUnits(s.conn.State, svc, 1, "0")
 	c.Assert(err, gc.IsNil)
-	s.assertAssignedMachineNetworks(c, units[0], withNets, withoutNets)
+	s.assertAssignedMachineRequestedNetworks(c, units[0], withNets, withoutNets)
 	id2, err := units[0].AssignedMachineId()
 	c.Assert(id2, gc.Equals, id0)
 
 	units, err = juju.AddUnits(s.conn.State, svc, 1, "lxc:0")
 	c.Assert(err, gc.IsNil)
-	s.assertAssignedMachineNetworks(c, units[0], withNets, withoutNets)
+	s.assertAssignedMachineRequestedNetworks(c, units[0], withNets, withoutNets)
 	id3, err := units[0].AssignedMachineId()
 	c.Assert(id3, gc.Equals, id0+"/lxc/0")
 
 	units, err = juju.AddUnits(s.conn.State, svc, 1, "lxc:"+id3)
 	c.Assert(err, gc.IsNil)
-	s.assertAssignedMachineNetworks(c, units[0], withNets, withoutNets)
+	s.assertAssignedMachineRequestedNetworks(c, units[0], withNets, withoutNets)
 	id4, err := units[0].AssignedMachineId()
 	c.Assert(id4, gc.Equals, id0+"/lxc/0/lxc/0")
 

=== modified file 'state/addmachine.go'
--- state/addmachine.go	2014-04-03 10:09:20 +0000
+++ state/addmachine.go	2014-04-04 13:09:14 +0000
@@ -422,7 +422,11 @@
 		createStatusOp(st, machineGlobalKey(mdoc.Id), statusDoc{
 			Status: params.StatusPending,
 		}),
-		createNetworksOp(st, machineGlobalKey(mdoc.Id),
+		// TODO(dimitern) 2014-04-04 bug #1302498
+		// Once we can add networks independently of machine
+		// provisioning, we should check the given networks are valid
+		// and known before setting them.
+		createRequestedNetworksOp(st, machineGlobalKey(mdoc.Id),
 			template.IncludeNetworks,
 			template.ExcludeNetworks,
 		),

=== modified file 'state/api/provisioner/machine.go'
--- state/api/provisioner/machine.go	2014-04-03 02:57:11 +0000
+++ state/api/provisioner/machine.go	2014-04-04 13:09:14 +0000
@@ -55,12 +55,12 @@
 	return nil
 }
 
-// Networks returns a pair of lists of networks to enable/disable on
-// the machine.
-func (m *Machine) Networks() (includeNetworks, excludeNetworks []string, err error) {
+// RequestedNetworks returns a pair of lists of networks to
+// enable/disable on the machine.
+func (m *Machine) RequestedNetworks() (includeNetworks, excludeNetworks []string, err error) {
 	var results params.NetworksResults
 	args := params.Entities{Entities: []params.Entity{{m.tag}}}
-	err = m.st.call("Networks", args, &results)
+	err = m.st.call("RequestedNetworks", args, &results)
 	if err != nil {
 		return nil, nil, err
 	}

=== modified file 'state/api/provisioner/provisioner_test.go'
--- state/api/provisioner/provisioner_test.go	2014-04-03 02:57:11 +0000
+++ state/api/provisioner/provisioner_test.go	2014-04-04 13:09:14 +0000
@@ -329,7 +329,7 @@
 
 	apiMachine, err := s.provisioner.Machine(netsMachine.Tag())
 	c.Assert(err, gc.IsNil)
-	includeNetworks, excludeNetworks, err := apiMachine.Networks()
+	includeNetworks, excludeNetworks, err := apiMachine.RequestedNetworks()
 	c.Assert(err, gc.IsNil)
 	c.Assert(includeNetworks, gc.DeepEquals, template.IncludeNetworks)
 	c.Assert(excludeNetworks, gc.DeepEquals, template.ExcludeNetworks)
@@ -337,7 +337,7 @@
 	// Now try machine 0.
 	apiMachine, err = s.provisioner.Machine(s.machine.Tag())
 	c.Assert(err, gc.IsNil)
-	includeNetworks, excludeNetworks, err = apiMachine.Networks()
+	includeNetworks, excludeNetworks, err = apiMachine.RequestedNetworks()
 	c.Assert(err, gc.IsNil)
 	c.Assert(includeNetworks, gc.HasLen, 0)
 	c.Assert(excludeNetworks, gc.HasLen, 0)

=== modified file 'state/apiserver/provisioner/provisioner.go'
--- state/apiserver/provisioner/provisioner.go	2014-04-03 02:57:11 +0000
+++ state/apiserver/provisioner/provisioner.go	2014-04-04 13:09:14 +0000
@@ -407,8 +407,8 @@
 	return result, nil
 }
 
-// Networks returns the networks for each given machine entity.
-func (p *ProvisionerAPI) Networks(args params.Entities) (params.NetworksResults, error) {
+// RequestedNetworks returns the requested networks for each given machine entity.
+func (p *ProvisionerAPI) RequestedNetworks(args params.Entities) (params.NetworksResults, error) {
 	result := params.NetworksResults{
 		Results: make([]params.NetworkResult, len(args.Entities)),
 	}
@@ -421,7 +421,7 @@
 		if err == nil {
 			var includeNetworks []string
 			var excludeNetworks []string
-			includeNetworks, excludeNetworks, err = machine.Networks()
+			includeNetworks, excludeNetworks, err = machine.RequestedNetworks()
 			if err == nil {
 				result.Results[i].IncludeNetworks = includeNetworks
 				result.Results[i].ExcludeNetworks = excludeNetworks

=== modified file 'state/apiserver/provisioner/provisioner_test.go'
--- state/apiserver/provisioner/provisioner_test.go	2014-04-03 02:57:11 +0000
+++ state/apiserver/provisioner/provisioner_test.go	2014-04-04 13:09:14 +0000
@@ -769,7 +769,7 @@
 	netsMachine, err := s.State.AddOneMachine(template)
 	c.Assert(err, gc.IsNil)
 
-	includeNetsMachine0, excludeNetsMachine0, err := s.machines[0].Networks()
+	includeNetsMachine0, excludeNetsMachine0, err := s.machines[0].RequestedNetworks()
 	c.Assert(err, gc.IsNil)
 
 	args := params.Entities{Entities: []params.Entity{
@@ -779,7 +779,7 @@
 		{Tag: "unit-foo-0"},
 		{Tag: "service-bar"},
 	}}
-	result, err := s.provisioner.Networks(args)
+	result, err := s.provisioner.RequestedNetworks(args)
 	c.Assert(err, gc.IsNil)
 	c.Assert(result, gc.DeepEquals, params.NetworksResults{
 		Results: []params.NetworkResult{

=== modified file 'state/assign_test.go'
--- state/assign_test.go	2014-03-26 10:41:38 +0000
+++ state/assign_test.go	2014-04-04 13:09:14 +0000
@@ -329,7 +329,7 @@
 	// Check that the principal is set on the machine.
 	machine, err := s.State.Machine(machineId)
 	c.Assert(err, gc.IsNil)
-	include, exclude, err := machine.Networks()
+	include, exclude, err := machine.RequestedNetworks()
 	c.Assert(err, gc.IsNil)
 	c.Assert(include, gc.DeepEquals, includeNetworks)
 	c.Assert(exclude, gc.DeepEquals, excludeNetworks)

=== modified file 'state/cleanup.go'
--- state/cleanup.go	2014-03-24 13:37:25 +0000
+++ state/cleanup.go	2014-04-04 13:09:14 +0000
@@ -154,9 +154,6 @@
 	if err := st.cleanupContainers(machine); err != nil {
 		return err
 	}
-	if err := st.cleanupNetworks(machineGlobalKey(machineId)); err != nil {
-		return err
-	}
 	for _, unitName := range machine.doc.Principals {
 		if err := st.obliterateUnit(unitName); err != nil {
 			return err
@@ -209,16 +206,6 @@
 	return nil
 }
 
-// cleanupNetworks removes associated networks for a machine or
-// service, given by its global key.
-func (st *State) cleanupNetworks(globalKey string) error {
-	op := removeNetworksOp(st, globalKey)
-	if err := st.runTransaction([]txn.Op{op}); err != nil {
-		logger.Warningf("cannot remove networks document for %q: %v", globalKey, err)
-	}
-	return nil
-}
-
 // obliterateUnit removes a unit from state completely. It is not safe or
 // sane to obliterate any unit in isolation; its only reasonable use is in
 // the context of machine obliteration, in which we can be sure that unclean

=== modified file 'state/compat_test.go'
--- state/compat_test.go	2014-03-25 16:12:23 +0000
+++ state/compat_test.go	2014-04-04 13:09:14 +0000
@@ -75,9 +75,9 @@
 	service, err := s.state.AddService("mysql", "user-admin", charm, nil, nil)
 	c.Assert(err, gc.IsNil)
 	// In 1.17.7+ all services have associated document in the
-	// networks collection. We remove it here to test backwards
-	// compatibility.
-	ops := []txn.Op{removeNetworksOp(s.state, service.globalKey())}
+	// requested networks collection. We remove it here to test
+	// backwards compatibility.
+	ops := []txn.Op{removeRequestedNetworksOp(s.state, service.globalKey())}
 	err = s.state.runTransaction(ops)
 	c.Assert(err, gc.IsNil)
 
@@ -88,18 +88,18 @@
 	c.Assert(exclude, gc.HasLen, 0)
 }
 
-func (s *compatSuite) TestGetMachineWithoutNetworksIsOK(c *gc.C) {
+func (s *compatSuite) TestGetMachineWithoutRequestedNetworksIsOK(c *gc.C) {
 	machine, err := s.state.AddMachine("quantal", JobHostUnits)
 	c.Assert(err, gc.IsNil)
 	// In 1.17.7+ all machines have associated document in the
-	// networks collection. We remove it here to test backwards
-	// compatibility.
-	ops := []txn.Op{removeNetworksOp(s.state, machine.globalKey())}
+	// requested networks collection. We remove it here to test
+	// backwards compatibility.
+	ops := []txn.Op{removeRequestedNetworksOp(s.state, machine.globalKey())}
 	err = s.state.runTransaction(ops)
 	c.Assert(err, gc.IsNil)
 
 	// Now check the trying to fetch machine's networks is OK.
-	include, exclude, err := machine.Networks()
+	include, exclude, err := machine.RequestedNetworks()
 	c.Assert(err, gc.IsNil)
 	c.Assert(include, gc.HasLen, 0)
 	c.Assert(exclude, gc.HasLen, 0)

=== modified file 'state/machine.go'
--- state/machine.go	2014-04-04 00:12:12 +0000
+++ state/machine.go	2014-04-04 13:09:14 +0000
@@ -5,6 +5,7 @@
 
 import (
 	"fmt"
+	"net"
 	"strings"
 	"time"
 
@@ -563,8 +564,28 @@
 	return fmt.Errorf("machine %s cannot advance lifecycle: %v", m, ErrExcessiveContention)
 }
 
-// Remove removes the machine from state. It will fail if the machine is not
-// Dead.
+func (m *Machine) removeNetworkInterfacesOps() ([]txn.Op, error) {
+	var doc struct {
+		MACAddress string `bson:"_id"`
+	}
+	ops := []txn.Op{}
+	sel := bson.D{{"machineid", m.doc.Id}}
+	iter := m.st.networkInterfaces.Find(sel).Select(bson.D{{"_id", 1}}).Iter()
+	for iter.Next(&doc) {
+		ops = append(ops, txn.Op{
+			C:      m.st.networkInterfaces.Name,
+			Id:     doc.MACAddress,
+			Remove: true,
+		})
+	}
+	if err := iter.Err(); err != nil {
+		return nil, err
+	}
+	return ops, nil
+}
+
+// Remove removes the machine from state. It will fail if the machine
+// is not Dead.
 func (m *Machine) Remove() (err error) {
 	defer utils.ErrorContextf(&err, "cannot remove machine %s", m.doc.Id)
 	if m.doc.Life != Dead {
@@ -578,15 +599,25 @@
 			Remove: true,
 		},
 		{
+			C:      m.st.machines.Name,
+			Id:     m.doc.Id,
+			Assert: isDeadDoc,
+		},
+		{
 			C:      m.st.instanceData.Name,
 			Id:     m.doc.Id,
 			Remove: true,
 		},
 		removeStatusOp(m.st, m.globalKey()),
 		removeConstraintsOp(m.st, m.globalKey()),
-		removeNetworksOp(m.st, m.globalKey()),
+		removeRequestedNetworksOp(m.st, m.globalKey()),
 		annotationRemoveOp(m.st, m.globalKey()),
 	}
+	ifacesOps, err := m.removeNetworkInterfacesOps()
+	if err != nil {
+		return err
+	}
+	ops = append(ops, ifacesOps...)
 	ops = append(ops, removeContainerRefOps(m.st, m.Id())...)
 	// The only abort conditions in play indicate that the machine has already
 	// been removed.
@@ -886,10 +917,105 @@
 	return nil
 }
 
-// Networks returns the list of networks the machine should be on
-// (includeNetworks) or not (excludeNetworks).
-func (m *Machine) Networks() (includeNetworks, excludeNetworks []string, err error) {
-	return readNetworks(m.st, m.globalKey())
+// RequestedNetworks returns the list of networks the machine should
+// be on (includeNetworks) or not (excludeNetworks).
+func (m *Machine) RequestedNetworks() (includeNetworks, excludeNetworks []string, err error) {
+	return readRequestedNetworks(m.st, m.globalKey())
+}
+
+// Networks returns the list of configured networks on the machine.
+func (m *Machine) Networks() ([]*Network, error) {
+	includeNetworks, _, err := m.RequestedNetworks()
+	if err != nil {
+		return nil, err
+	}
+	docs := []networkDoc{}
+	sel := bson.D{{"_id", bson.D{{"$in", includeNetworks}}}}
+	err = m.st.networks.Find(sel).All(&docs)
+	if err != nil {
+		return nil, err
+	}
+	networks := make([]*Network, len(docs))
+	for i, doc := range docs {
+		networks[i] = newNetwork(m.st, &doc)
+	}
+	return networks, nil
+}
+
+// NetworkInterfaces returns the list of configured network interfaces
+// of the machine.
+func (m *Machine) NetworkInterfaces() ([]*NetworkInterface, error) {
+	docs := []networkInterfaceDoc{}
+	err := m.st.networkInterfaces.Find(bson.D{{"machineid", m.doc.Id}}).All(&docs)
+	if err != nil {
+		return nil, err
+	}
+	ifaces := make([]*NetworkInterface, len(docs))
+	for i, doc := range docs {
+		ifaces[i] = newNetworkInterface(m.st, &doc)
+	}
+	return ifaces, nil
+}
+
+// AddNetworkInterface creates a new network interface on the given
+// network for the machine. The machine must be alive and not yet
+// provisioned, and there must be no other interface with the same MAC
+// address for this to succeed.
+func (m *Machine) AddNetworkInterface(macAddress, name, networkName string) (iface *NetworkInterface, err error) {
+	defer utils.ErrorContextf(&err, "cannot add network interface to machine %s", m.doc.Id)
+
+	if _, err := net.ParseMAC(macAddress); err != nil {
+		return nil, err
+	}
+	if name == "" {
+		return nil, fmt.Errorf("interface name must be not empty")
+	}
+	aliveAndNotProvisioned := append(isAliveDoc, bson.D{{"nonce", ""}}...)
+	doc := &networkInterfaceDoc{
+		MACAddress:    macAddress,
+		InterfaceName: name,
+		NetworkName:   networkName,
+		MachineId:     m.doc.Id,
+	}
+	ops := []txn.Op{{
+		C:      m.st.networks.Name,
+		Id:     networkName,
+		Assert: txn.DocExists,
+	}, {
+		C:      m.st.machines.Name,
+		Id:     m.doc.Id,
+		Assert: aliveAndNotProvisioned,
+	}, {
+		C:      m.st.networkInterfaces.Name,
+		Id:     macAddress,
+		Assert: txn.DocMissing,
+		Insert: doc,
+	}}
+
+	for i := 0; i < 5; i++ {
+		err = m.st.runTransaction(ops)
+		switch err {
+		case txn.ErrAborted:
+			_, err = m.st.Network(networkName)
+			if err != nil {
+				return nil, err
+			}
+			if err = m.Refresh(); err != nil {
+				return nil, err
+			} else if m.doc.Life != Alive {
+				return nil, fmt.Errorf("machine is not alive")
+			} else if m.doc.Nonce != "" {
+				return nil, fmt.Errorf("machine already provisioned: dynamic network interfaces not currently supported")
+			}
+			// Network and machine both OK, so the other assert must have failed.
+			return nil, fmt.Errorf("interface with MAC address %q already exists", macAddress)
+		case nil:
+			return newNetworkInterface(m.st, doc), nil
+		default:
+			return nil, err
+		}
+	}
+	return nil, ErrExcessiveContention
 }
 
 // CheckProvisioned returns true if the machine was provisioned with the given nonce.

=== modified file 'state/machine_test.go'
--- state/machine_test.go	2014-04-01 23:56:19 +0000
+++ state/machine_test.go	2014-04-04 13:09:14 +0000
@@ -4,6 +4,7 @@
 package state_test
 
 import (
+	"fmt"
 	"sort"
 
 	jc "github.com/juju/testing/checkers"
@@ -223,10 +224,13 @@
 	c.Assert(err, jc.Satisfies, errors.IsNotFoundError)
 	_, err = s.machine.Containers()
 	c.Assert(err, jc.Satisfies, errors.IsNotFoundError)
-	include, exclude, err := s.machine.Networks()
+	include, exclude, err := s.machine.RequestedNetworks()
 	c.Assert(err, gc.IsNil)
 	c.Assert(include, gc.HasLen, 0)
 	c.Assert(exclude, gc.HasLen, 0)
+	ifaces, err := s.machine.NetworkInterfaces()
+	c.Assert(err, gc.IsNil)
+	c.Assert(ifaces, gc.HasLen, 0)
 	err = s.machine.Remove()
 	c.Assert(err, gc.IsNil)
 }
@@ -352,10 +356,10 @@
 	c.Assert(alive, gc.Equals, false)
 }
 
-func (s *MachineSuite) TestMachineNetworks(c *gc.C) {
-	// s.machine is created without networks, so check
+func (s *MachineSuite) TestRequestedNetworks(c *gc.C) {
+	// s.machine is created without requested networks, so check
 	// they're empty when we read them.
-	include, exclude, err := s.machine.Networks()
+	include, exclude, err := s.machine.RequestedNetworks()
 	c.Assert(err, gc.IsNil)
 	c.Assert(include, gc.HasLen, 0)
 	c.Assert(exclude, gc.HasLen, 0)
@@ -368,7 +372,7 @@
 		ExcludeNetworks: []string{"private-net", "logging"},
 	})
 	c.Assert(err, gc.IsNil)
-	include, exclude, err = machine.Networks()
+	include, exclude, err = machine.RequestedNetworks()
 	c.Assert(err, gc.IsNil)
 	c.Assert(include, jc.DeepEquals, []string{"net1", "mynet"})
 	c.Assert(exclude, jc.DeepEquals, []string{"private-net", "logging"})
@@ -378,12 +382,146 @@
 	c.Assert(err, gc.IsNil)
 	err = machine.Remove()
 	c.Assert(err, gc.IsNil)
-	include, exclude, err = machine.Networks()
+	include, exclude, err = machine.RequestedNetworks()
 	c.Assert(err, gc.IsNil)
 	c.Assert(include, gc.HasLen, 0)
 	c.Assert(exclude, gc.HasLen, 0)
 }
 
+func addNetworkAndInterface(c *gc.C, st *state.State, machine *state.Machine,
+	networkName, cidr string, vlanTag int,
+	mac, ifaceName string) (*state.Network, *state.NetworkInterface) {
+	net, err := st.AddNetwork(networkName, cidr, vlanTag)
+	c.Assert(err, gc.IsNil)
+	iface, err := machine.AddNetworkInterface(mac, ifaceName, networkName)
+	c.Assert(err, gc.IsNil)
+	return net, iface
+}
+
+func (s *MachineSuite) TestNetworks(c *gc.C) {
+	// s.machine is created without networks, so check
+	// they're empty when we read them.
+	nets, err := s.machine.Networks()
+	c.Assert(err, gc.IsNil)
+	c.Assert(nets, gc.HasLen, 0)
+
+	// Now create a testing machine with requested networks, because
+	// Networks() uses them to determine which networks are bound to
+	// the machine.
+	machine, err := s.State.AddOneMachine(state.MachineTemplate{
+		Series:          "quantal",
+		Jobs:            []state.MachineJob{state.JobHostUnits},
+		IncludeNetworks: []string{"net1", "net2"},
+		ExcludeNetworks: []string{"net3", "net4"},
+	})
+	c.Assert(err, gc.IsNil)
+
+	net1, _ := addNetworkAndInterface(
+		c, s.State, machine,
+		"net1", "0.1.2.0/24", 0,
+		"aa:bb:cc:dd:ee:f0", "eth0")
+	net2, _ := addNetworkAndInterface(
+		c, s.State, machine,
+		"net2", "0.2.2.0/24", 0,
+		"aa:bb:cc:dd:ee:f1", "eth1")
+
+	nets, err = machine.Networks()
+	c.Assert(err, gc.IsNil)
+	c.Assert(nets, jc.DeepEquals, []*state.Network{net1, net2})
+}
+
+func (s *MachineSuite) TestMachineNetworkInterfaces(c *gc.C) {
+	// s.machine is created without network interfaces, so check
+	// they're empty when we read them.
+	ifaces, err := s.machine.NetworkInterfaces()
+	c.Assert(err, gc.IsNil)
+	c.Assert(ifaces, gc.HasLen, 0)
+
+	machine, err := s.State.AddOneMachine(state.MachineTemplate{
+		Series:          "quantal",
+		Jobs:            []state.MachineJob{state.JobHostUnits},
+		IncludeNetworks: []string{"net1", "vlan42", "net2"},
+	})
+	c.Assert(err, gc.IsNil)
+
+	// And a few networks and NICs.
+	_, iface0 := addNetworkAndInterface(
+		c, s.State, machine,
+		"net1", "0.1.2.0/24", 0,
+		"aa:bb:cc:dd:ee:f0", "eth0")
+	_, iface1 := addNetworkAndInterface(
+		c, s.State, machine,
+		"vlan42", "0.1.2.0/30", 42,
+		"aa:bb:cc:dd:ee:f1", "eth0.42")
+	_, iface2 := addNetworkAndInterface(
+		c, s.State, machine,
+		"net2", "0.2.2.0/24", 0,
+		"aa:bb:cc:dd:ee:f2", "eth1")
+
+	ifaces, err = machine.NetworkInterfaces()
+	c.Assert(err, gc.IsNil)
+	c.Assert(ifaces, jc.DeepEquals, []*state.NetworkInterface{
+		iface0, iface1, iface2,
+	})
+
+	// Make sure interfaces get removed with the machine.
+	err = machine.EnsureDead()
+	c.Assert(err, gc.IsNil)
+	err = machine.Remove()
+	c.Assert(err, gc.IsNil)
+	ifaces, err = machine.NetworkInterfaces()
+	c.Assert(err, gc.IsNil)
+	c.Assert(ifaces, gc.HasLen, 0)
+}
+
+func (s *MachineSuite) TestAddNetworkInterfaceErrors(c *gc.C) {
+	machine, err := s.State.AddOneMachine(state.MachineTemplate{
+		Series:          "quantal",
+		Jobs:            []state.MachineJob{state.JobHostUnits},
+		IncludeNetworks: []string{"net1"},
+	})
+	c.Assert(err, gc.IsNil)
+	addNetworkAndInterface(
+		c, s.State, machine,
+		"net1", "0.1.2.0/24", 0,
+		"aa:bb:cc:dd:ee:f0", "eth0")
+
+	errorPrefix := fmt.Sprintf("cannot add network interface to machine %s: ", machine.Id())
+	_, err = machine.AddNetworkInterface("invalid", "eth0", "net1")
+	expectErr := errorPrefix + "invalid MAC address: invalid"
+	c.Assert(err, gc.ErrorMatches, expectErr)
+
+	_, err = machine.AddNetworkInterface("aa:bb:cc:dd:ee:ff", "", "net1")
+	expectErr = errorPrefix + "interface name must be not empty"
+	c.Assert(err, gc.ErrorMatches, expectErr)
+
+	_, err = machine.AddNetworkInterface("aa:bb:cc:dd:ee:f0", "eth2", "net1")
+	expectErr = errorPrefix + `interface with MAC address "aa:bb:cc:dd:ee:f0" already exists`
+	c.Assert(err, gc.ErrorMatches, expectErr)
+
+	_, err = machine.AddNetworkInterface("aa:bb:cc:dd:ee:f0", "eth2", "invalid")
+	expectErr = errorPrefix + `network "invalid" not found`
+	c.Assert(err, gc.ErrorMatches, expectErr)
+
+	err = machine.SetProvisioned("i-am", "fake_nonce", nil)
+	c.Assert(err, gc.IsNil)
+	_, err = machine.AddNetworkInterface("aa:bb:cc:dd:ee:ff", "eth2", "net1")
+	expectErr = errorPrefix + "machine already provisioned: dynamic network interfaces not currently supported"
+	c.Assert(err, gc.ErrorMatches, expectErr)
+
+	err = machine.EnsureDead()
+	c.Assert(err, gc.IsNil)
+	_, err = machine.AddNetworkInterface("aa:bb:cc:dd:ee:ff", "eth2", "net1")
+	expectErr = errorPrefix + "machine is not alive"
+	c.Assert(err, gc.ErrorMatches, expectErr)
+
+	err = machine.Remove()
+	c.Assert(err, gc.IsNil)
+	_, err = machine.AddNetworkInterface("aa:bb:cc:dd:ee:ff", "eth2", "net1")
+	expectErr = errorPrefix + fmt.Sprintf("machine %s not found", machine.Id())
+	c.Assert(err, gc.ErrorMatches, expectErr)
+}
+
 func (s *MachineSuite) TestMachineInstanceId(c *gc.C) {
 	machine, err := s.State.AddMachine("quantal", state.JobHostUnits)
 	c.Assert(err, gc.IsNil)

=== added file 'state/networkinterfaces.go'
--- state/networkinterfaces.go	1970-01-01 00:00:00 +0000
+++ state/networkinterfaces.go	2014-04-04 13:09:14 +0000
@@ -0,0 +1,45 @@
+// Copyright 2014 Canonical Ltd.
+// Licensed under the AGPLv3, see LICENCE file for details.
+
+package state
+
+// NetworkInterface represents the state of a machine network
+// interface.
+type NetworkInterface struct {
+	st  *State
+	doc networkInterfaceDoc
+}
+
+// networkInterfaceDoc represents a network interface for a machine on
+// a given network.
+type networkInterfaceDoc struct {
+	MACAddress string `bson:"_id"`
+	// InterfaceName is the network interface name (e.g. "eth0").
+	InterfaceName string
+	NetworkName   string
+	MachineId     string
+}
+
+func newNetworkInterface(st *State, doc *networkInterfaceDoc) *NetworkInterface {
+	return &NetworkInterface{st, *doc}
+}
+
+// MACAddress returns the MAC address of the interface.
+func (ni *NetworkInterface) MACAddress() string {
+	return ni.doc.MACAddress
+}
+
+// InterfaceName returns the name of the interface.
+func (ni *NetworkInterface) InterfaceName() string {
+	return ni.doc.InterfaceName
+}
+
+// NetworkName returns the machine network name of the interface.
+func (ni *NetworkInterface) NetworkName() string {
+	return ni.doc.NetworkName
+}
+
+// MachineId returns the machine id of the interface.
+func (ni *NetworkInterface) MachineId() string {
+	return ni.doc.MachineId
+}

=== added file 'state/networkinterfaces_test.go'
--- state/networkinterfaces_test.go	1970-01-01 00:00:00 +0000
+++ state/networkinterfaces_test.go	2014-04-04 13:09:14 +0000
@@ -0,0 +1,37 @@
+// Copyright 2014 Canonical Ltd.
+// Licensed under the AGPLv3, see LICENCE file for details.
+
+package state_test
+
+import (
+	gc "launchpad.net/gocheck"
+
+	"launchpad.net/juju-core/state"
+)
+
+type NetworkInterfaceSuite struct {
+	ConnSuite
+	machine *state.Machine
+	network *state.Network
+	iface   *state.NetworkInterface
+}
+
+var _ = gc.Suite(&NetworkInterfaceSuite{})
+
+func (s *NetworkInterfaceSuite) SetUpTest(c *gc.C) {
+	s.ConnSuite.SetUpTest(c)
+	var err error
+	s.machine, err = s.State.AddMachine("quantal", state.JobHostUnits)
+	c.Assert(err, gc.IsNil)
+	s.network, err = s.State.AddNetwork("net1", "0.1.2.3/24", 42)
+	c.Assert(err, gc.IsNil)
+	s.iface, err = s.machine.AddNetworkInterface("aa:bb:cc:dd:ee:ff", "eth0", "net1")
+	c.Assert(err, gc.IsNil)
+}
+
+func (s *NetworkInterfaceSuite) TestGetterMethods(c *gc.C) {
+	c.Assert(s.iface.MACAddress(), gc.Equals, "aa:bb:cc:dd:ee:ff")
+	c.Assert(s.iface.InterfaceName(), gc.Equals, "eth0")
+	c.Assert(s.iface.NetworkName(), gc.Equals, s.network.Name())
+	c.Assert(s.iface.MachineId(), gc.Equals, s.machine.Id())
+}

=== added file 'state/networks.go'
--- state/networks.go	1970-01-01 00:00:00 +0000
+++ state/networks.go	2014-04-04 13:09:14 +0000
@@ -0,0 +1,68 @@
+// Copyright 2014 Canonical Ltd.
+// Licensed under the AGPLv3, see LICENCE file for details.
+
+package state
+
+import (
+	"labix.org/v2/mgo/bson"
+)
+
+// Network represents the state of a network.
+type Network struct {
+	st  *State
+	doc networkDoc
+}
+
+// networkDoc represents a configured network that a machine can be a
+// part of.
+type networkDoc struct {
+	// Name is the network's name. It should be one of the machine's
+	// included networks.
+	Name string `bson:"_id"`
+	// CIDR holds the network CIDR in the form 192.168.100.0/24.
+	CIDR string
+	// VLANTag needs to be between 1 and 4094 for VLANs and 0 for
+	// normal networks.
+	VLANTag int
+}
+
+func newNetwork(st *State, doc *networkDoc) *Network {
+	return &Network{st, *doc}
+}
+
+// Name returns the network name.
+func (n *Network) Name() string {
+	return n.doc.Name
+}
+
+// CIDR returns the network CIDR (e.g. 192.168.50.0/24).
+func (n *Network) CIDR() string {
+	return n.doc.CIDR
+}
+
+// VLANTag returns the network VLAN tag. Its a number between 1 and
+// 4094 for VLANs and 0 if the network is not a VLAN.
+func (n *Network) VLANTag() int {
+	return n.doc.VLANTag
+}
+
+// IsVLAN returns whether the network is a VLAN (has tag > 0) or a
+// normal network.
+func (n *Network) IsVLAN() bool {
+	return n.doc.VLANTag > 0
+}
+
+// Interfaces returns all network interfaces on the network.
+func (n *Network) Interfaces() ([]*NetworkInterface, error) {
+	docs := []networkInterfaceDoc{}
+	sel := bson.D{{"networkname", n.doc.Name}}
+	err := n.st.networkInterfaces.Find(sel).All(&docs)
+	if err != nil {
+		return nil, err
+	}
+	ifaces := make([]*NetworkInterface, len(docs))
+	for i, doc := range docs {
+		ifaces[i] = newNetworkInterface(n.st, &doc)
+	}
+	return ifaces, nil
+}

=== added file 'state/networks_test.go'
--- state/networks_test.go	1970-01-01 00:00:00 +0000
+++ state/networks_test.go	2014-04-04 13:09:14 +0000
@@ -0,0 +1,56 @@
+// Copyright 2014 Canonical Ltd.
+// Licensed under the AGPLv3, see LICENCE file for details.
+
+package state_test
+
+import (
+	jc "github.com/juju/testing/checkers"
+	gc "launchpad.net/gocheck"
+
+	"launchpad.net/juju-core/state"
+)
+
+type NetworkSuite struct {
+	ConnSuite
+	machine *state.Machine
+	network *state.Network
+	vlan    *state.Network
+}
+
+var _ = gc.Suite(&NetworkSuite{})
+
+func (s *NetworkSuite) SetUpTest(c *gc.C) {
+	s.ConnSuite.SetUpTest(c)
+	var err error
+	s.machine, err = s.State.AddMachine("quantal", state.JobHostUnits)
+	c.Assert(err, gc.IsNil)
+	s.network, err = s.State.AddNetwork("net1", "0.1.2.3/24", 0)
+	c.Assert(err, gc.IsNil)
+	s.vlan, err = s.State.AddNetwork("vlan", "0.1.2.3/30", 42)
+	c.Assert(err, gc.IsNil)
+}
+
+func (s *NetworkSuite) TestGetterMethods(c *gc.C) {
+	c.Assert(s.network.Name(), gc.Equals, "net1")
+	c.Assert(s.network.CIDR(), gc.Equals, "0.1.2.3/24")
+	c.Assert(s.network.VLANTag(), gc.Equals, 0)
+	c.Assert(s.vlan.VLANTag(), gc.Equals, 42)
+	c.Assert(s.network.IsVLAN(), jc.IsFalse)
+	c.Assert(s.vlan.IsVLAN(), jc.IsTrue)
+}
+
+func (s *NetworkSuite) TestInterfaces(c *gc.C) {
+	ifaces, err := s.network.Interfaces()
+	c.Assert(err, gc.IsNil)
+	c.Assert(ifaces, gc.HasLen, 0)
+
+	iface0, err := s.machine.AddNetworkInterface("aa:bb:cc:dd:ee:f0", "eth0", "net1")
+	c.Assert(err, gc.IsNil)
+	iface1, err := s.machine.AddNetworkInterface("aa:bb:cc:dd:ee:f1", "eth1", "net1")
+	c.Assert(err, gc.IsNil)
+
+	ifaces, err = s.network.Interfaces()
+	c.Assert(err, gc.IsNil)
+	c.Assert(ifaces, gc.HasLen, 2)
+	c.Assert(ifaces, jc.DeepEquals, []*state.NetworkInterface{iface0, iface1})
+}

=== modified file 'state/open.go'
--- state/open.go	2014-03-26 18:36:39 +0000
+++ state/open.go	2014-04-04 13:09:14 +0000
@@ -191,6 +191,8 @@
 	{"units", []string{"principal"}},
 	{"units", []string{"machineid"}},
 	{"users", []string{"name"}},
+	{"networkinterfaces", []string{"networkname"}},
+	{"networkinterfaces", []string{"machineid"}},
 }
 
 // The capped collection used for transaction logs defaults to 10MB.
@@ -245,29 +247,31 @@
 		}
 	}
 	st := &State{
-		info:           info,
-		policy:         policy,
-		db:             db,
-		environments:   db.C("environments"),
-		charms:         db.C("charms"),
-		machines:       db.C("machines"),
-		containerRefs:  db.C("containerRefs"),
-		instanceData:   db.C("instanceData"),
-		relations:      db.C("relations"),
-		relationScopes: db.C("relationscopes"),
-		services:       db.C("services"),
-		networks:       db.C("linkednetworks"),
-		minUnits:       db.C("minunits"),
-		settings:       db.C("settings"),
-		settingsrefs:   db.C("settingsrefs"),
-		constraints:    db.C("constraints"),
-		units:          db.C("units"),
-		users:          db.C("users"),
-		presence:       pdb.C("presence"),
-		cleanups:       db.C("cleanups"),
-		annotations:    db.C("annotations"),
-		statuses:       db.C("statuses"),
-		stateServers:   db.C("stateServers"),
+		info:              info,
+		policy:            policy,
+		db:                db,
+		environments:      db.C("environments"),
+		charms:            db.C("charms"),
+		machines:          db.C("machines"),
+		containerRefs:     db.C("containerRefs"),
+		instanceData:      db.C("instanceData"),
+		relations:         db.C("relations"),
+		relationScopes:    db.C("relationscopes"),
+		services:          db.C("services"),
+		requestedNetworks: db.C("linkednetworks"),
+		networks:          db.C("networks"),
+		networkInterfaces: db.C("networkinterfaces"),
+		minUnits:          db.C("minunits"),
+		settings:          db.C("settings"),
+		settingsrefs:      db.C("settingsrefs"),
+		constraints:       db.C("constraints"),
+		units:             db.C("units"),
+		users:             db.C("users"),
+		presence:          pdb.C("presence"),
+		cleanups:          db.C("cleanups"),
+		annotations:       db.C("annotations"),
+		statuses:          db.C("statuses"),
+		stateServers:      db.C("stateServers"),
 	}
 	log := db.C("txns.log")
 	logInfo := mgo.CollectionInfo{Capped: true, MaxBytes: logSize}

=== renamed file 'state/networks.go' => 'state/requestednetworks.go'
--- state/networks.go	2014-03-25 09:15:00 +0000
+++ state/requestednetworks.go	2014-04-04 13:09:14 +0000
@@ -8,45 +8,48 @@
 	"labix.org/v2/mgo/txn"
 )
 
-// networksDoc represents the network restrictions for a service or machine.
-// The document ID field is the globalKey of a service or a machine.
-type networksDoc struct {
+// requestedNetworksDoc represents the network restrictions for a
+// service or machine. The document ID field is the globalKey of a
+// service or a machine.
+type requestedNetworksDoc struct {
+	Id              string   `bson:"_id"`
 	IncludeNetworks []string `bson:"include"`
 	ExcludeNetworks []string `bson:"exclude"`
 }
 
-func newNetworksDoc(includeNetworks, excludeNetworks []string) *networksDoc {
-	return &networksDoc{
+func newRequestedNetworksDoc(includeNetworks, excludeNetworks []string) *requestedNetworksDoc {
+	return &requestedNetworksDoc{
 		IncludeNetworks: includeNetworks,
 		ExcludeNetworks: excludeNetworks,
 	}
 }
 
-func createNetworksOp(st *State, id string, includeNetworks, excludeNetworks []string) txn.Op {
+func createRequestedNetworksOp(st *State, id string, includeNetworks, excludeNetworks []string) txn.Op {
 	return txn.Op{
-		C:      st.networks.Name,
+		C:      st.requestedNetworks.Name,
 		Id:     id,
 		Assert: txn.DocMissing,
-		Insert: newNetworksDoc(includeNetworks, excludeNetworks),
+		Insert: newRequestedNetworksDoc(includeNetworks, excludeNetworks),
 	}
 }
 
 // While networks are immutable, there is no setNetworksOp function.
 
-func removeNetworksOp(st *State, id string) txn.Op {
+func removeRequestedNetworksOp(st *State, id string) txn.Op {
 	return txn.Op{
-		C:      st.networks.Name,
+		C:      st.requestedNetworks.Name,
 		Id:     id,
 		Remove: true,
 	}
 }
 
-func readNetworks(st *State, id string) (includeNetworks, excludeNetworks []string, err error) {
-	doc := networksDoc{}
-	if err = st.networks.FindId(id).One(&doc); err == mgo.ErrNotFound {
-		// In 1.17.7+ we always create a networksDoc for each service or
-		// machine we create, but in legacy databases this is not the
-		// case. We ignore the error here for backwards-compatibility.
+func readRequestedNetworks(st *State, id string) (includeNetworks, excludeNetworks []string, err error) {
+	doc := requestedNetworksDoc{}
+	if err = st.requestedNetworks.FindId(id).One(&doc); err == mgo.ErrNotFound {
+		// In 1.17.7+ we always create a requestedNetworksDoc for each
+		// service or machine we create, but in legacy databases this
+		// is not the case. We ignore the error here for
+		// backwards-compatibility.
 		err = nil
 	} else if err == nil {
 		includeNetworks = doc.IncludeNetworks

=== modified file 'state/service.go'
--- state/service.go	2014-03-25 09:15:00 +0000
+++ state/service.go	2014-04-04 13:09:14 +0000
@@ -224,7 +224,7 @@
 		Id:     s.settingsKey(),
 		Remove: true,
 	}}
-	ops = append(ops, removeNetworksOp(s.st, s.globalKey()))
+	ops = append(ops, removeRequestedNetworksOp(s.st, s.globalKey()))
 	ops = append(ops, removeConstraintsOp(s.st, s.globalKey()))
 	return append(ops, annotationRemoveOp(s.st, s.globalKey()))
 }
@@ -824,7 +824,7 @@
 
 // Networks returns the networks a service is associated with.
 func (s *Service) Networks() (includeNetworks, excludeNetworks []string, err error) {
-	return readNetworks(s.st, s.globalKey())
+	return readRequestedNetworks(s.st, s.globalKey())
 }
 
 // settingsIncRefOp returns an operation that increments the ref count

=== modified file 'state/state.go'
--- state/state.go	2014-04-03 02:57:11 +0000
+++ state/state.go	2014-04-04 13:09:14 +0000
@@ -8,6 +8,7 @@
 
 import (
 	"fmt"
+	"net"
 	"net/url"
 	"regexp"
 	"sort"
@@ -44,33 +45,35 @@
 // State represents the state of an environment
 // managed by juju.
 type State struct {
-	info             *Info
-	policy           Policy
-	db               *mgo.Database
-	environments     *mgo.Collection
-	charms           *mgo.Collection
-	machines         *mgo.Collection
-	instanceData     *mgo.Collection
-	containerRefs    *mgo.Collection
-	relations        *mgo.Collection
-	relationScopes   *mgo.Collection
-	services         *mgo.Collection
-	networks         *mgo.Collection
-	minUnits         *mgo.Collection
-	settings         *mgo.Collection
-	settingsrefs     *mgo.Collection
-	constraints      *mgo.Collection
-	units            *mgo.Collection
-	users            *mgo.Collection
-	presence         *mgo.Collection
-	cleanups         *mgo.Collection
-	annotations      *mgo.Collection
-	statuses         *mgo.Collection
-	stateServers     *mgo.Collection
-	runner           *txn.Runner
-	transactionHooks chan ([]transactionHook)
-	watcher          *watcher.Watcher
-	pwatcher         *presence.Watcher
+	info              *Info
+	policy            Policy
+	db                *mgo.Database
+	environments      *mgo.Collection
+	charms            *mgo.Collection
+	machines          *mgo.Collection
+	instanceData      *mgo.Collection
+	containerRefs     *mgo.Collection
+	relations         *mgo.Collection
+	relationScopes    *mgo.Collection
+	services          *mgo.Collection
+	requestedNetworks *mgo.Collection
+	networks          *mgo.Collection
+	networkInterfaces *mgo.Collection
+	minUnits          *mgo.Collection
+	settings          *mgo.Collection
+	settingsrefs      *mgo.Collection
+	constraints       *mgo.Collection
+	units             *mgo.Collection
+	users             *mgo.Collection
+	presence          *mgo.Collection
+	cleanups          *mgo.Collection
+	annotations       *mgo.Collection
+	statuses          *mgo.Collection
+	stateServers      *mgo.Collection
+	runner            *txn.Runner
+	transactionHooks  chan ([]transactionHook)
+	watcher           *watcher.Watcher
+	pwatcher          *presence.Watcher
 	// mu guards allManager.
 	mu         sync.Mutex
 	allManager *multiwatcher.StoreManager
@@ -952,7 +955,11 @@
 	ops := []txn.Op{
 		env.assertAliveOp(),
 		createConstraintsOp(st, svc.globalKey(), constraints.Value{}),
-		createNetworksOp(st, svc.globalKey(), includeNetworks, excludeNetworks),
+		// TODO(dimitern) 2014-04-04 bug #1302498
+		// Once we can add networks independently of machine
+		// provisioning, we should check the given networks are valid
+		// and known before setting them.
+		createRequestedNetworksOp(st, svc.globalKey(), includeNetworks, excludeNetworks),
 		createSettingsOp(st, svc.settingsKey(), nil),
 		{
 			C:      st.users.Name,
@@ -1003,6 +1010,52 @@
 	return svc, nil
 }
 
+// AddNetwork creates a new network with the given name, CIDR and VLAN tag.
+func (st *State) AddNetwork(name, cidr string, vlanTag int) (n *Network, err error) {
+	defer utils.ErrorContextf(&err, "cannot add network %q", name)
+	if cidr != "" {
+		_, _, err := net.ParseCIDR(cidr)
+		if err != nil {
+			return nil, err
+		}
+	}
+	if name == "" {
+		return nil, fmt.Errorf("name must be not empty")
+	}
+	if vlanTag < 0 || vlanTag > 4094 {
+		return nil, fmt.Errorf("invalid VLAN tag %d: must be between 0 and 4094", vlanTag)
+	}
+	doc := &networkDoc{
+		Name:    name,
+		CIDR:    cidr,
+		VLANTag: vlanTag,
+	}
+	ops := []txn.Op{{
+		C:      st.networks.Name,
+		Id:     name,
+		Assert: txn.DocMissing,
+		Insert: doc,
+	}}
+	err = onAbort(st.runTransaction(ops), fmt.Errorf("already exists"))
+	if err != nil {
+		return nil, err
+	}
+	return newNetwork(st, doc), nil
+}
+
+// Network returns the network with the given name.
+func (st *State) Network(name string) (*Network, error) {
+	doc := &networkDoc{}
+	err := st.networks.FindId(name).One(doc)
+	if err == mgo.ErrNotFound {
+		return nil, errors.NotFoundf("network %q", name)
+	}
+	if err != nil {
+		return nil, fmt.Errorf("cannot get network %q: %v", name, err)
+	}
+	return newNetwork(st, doc), nil
+}
+
 // Service returns a service state by name.
 func (st *State) Service(name string) (service *Service, err error) {
 	if !names.IsService(name) {

=== modified file 'state/state_test.go'
--- state/state_test.go	2014-04-03 02:57:11 +0000
+++ state/state_test.go	2014-04-04 13:09:14 +0000
@@ -962,6 +962,44 @@
 	}
 }
 
+func (s *StateSuite) TestAddAndGetNetwork(c *gc.C) {
+	machine, err := s.State.AddOneMachine(state.MachineTemplate{
+		Series:          "quantal",
+		Jobs:            []state.MachineJob{state.JobHostUnits},
+		IncludeNetworks: []string{"net1", "net2"},
+		ExcludeNetworks: []string{"net3", "net4"},
+	})
+	c.Assert(err, gc.IsNil)
+
+	net1, _ := addNetworkAndInterface(
+		c, s.State, machine,
+		"net1", "0.1.2.0/24", 0,
+		"aa:bb:cc:dd:ee:f0", "eth0")
+
+	net, err := s.State.Network("net1")
+	c.Assert(err, gc.IsNil)
+	c.Assert(net, gc.DeepEquals, net1)
+	_, err = s.State.Network("missing")
+	c.Assert(err, jc.Satisfies, errors.IsNotFoundError)
+	c.Assert(err, gc.ErrorMatches, `network "missing" not found`)
+
+	_, err = s.State.AddNetwork("", "0.3.1.0/24", 0)
+	expectErr := `cannot add network "": name must be not empty`
+	c.Assert(err, gc.ErrorMatches, expectErr)
+	_, err = s.State.AddNetwork("net42", "invalid", 0)
+	expectErr = `cannot add network "net42": invalid CIDR address: invalid`
+	c.Assert(err, gc.ErrorMatches, expectErr)
+	_, err = s.State.AddNetwork("net69", "0.3.1.0/30", -1)
+	expectErr = `cannot add network "net69": invalid VLAN tag -1: must be between 0 and 4094`
+	c.Assert(err, gc.ErrorMatches, expectErr)
+	_, err = s.State.AddNetwork("net69", "0.3.1.0/30", 9999)
+	expectErr = `cannot add network "net69": invalid VLAN tag 9999: must be between 0 and 4094`
+	c.Assert(err, gc.ErrorMatches, expectErr)
+	_, err = s.State.AddNetwork("net1", "0.1.2.0/24", 0)
+	expectErr = `cannot add network "net1": already exists`
+	c.Assert(err, gc.ErrorMatches, expectErr)
+}
+
 func (s *StateSuite) TestAddService(c *gc.C) {
 	charm := s.AddTestingCharm(c, "dummy")
 	_, err := s.State.AddService("haha/borken", "user-admin", charm, nil, nil)

=== modified file 'state/statecmd/machineconfig.go'
--- state/statecmd/machineconfig.go	2014-04-01 16:27:22 +0000
+++ state/statecmd/machineconfig.go	2014-04-04 13:09:14 +0000
@@ -74,8 +74,8 @@
 		return nil, err
 	}
 
-	// Find networks.
-	includeNetworks, excludeNetworks, err := machine.Networks()
+	// Find requested networks.
+	includeNetworks, excludeNetworks, err := machine.RequestedNetworks()
 	if err != nil {
 		return nil, err
 	}

=== modified file 'worker/provisioner/provisioner_task.go'
--- worker/provisioner/provisioner_task.go	2014-04-03 02:57:11 +0000
+++ worker/provisioner/provisioner_task.go	2014-04-04 13:09:14 +0000
@@ -491,7 +491,7 @@
 	if err != nil {
 		return nil, err
 	}
-	includeNetworks, excludeNetworks, err := machine.Networks()
+	includeNetworks, excludeNetworks, err := machine.RequestedNetworks()
 	if err != nil {
 		return nil, err
 	}

=== modified file 'worker/provisioner/provisioner_test.go'
--- worker/provisioner/provisioner_test.go	2014-04-03 04:46:51 +0000
+++ worker/provisioner/provisioner_test.go	2014-04-04 13:09:14 +0000
@@ -344,10 +344,10 @@
 }
 
 func (s *CommonProvisionerSuite) addMachine() (*state.Machine, error) {
-	return s.addMachineWithNetworks(nil, nil)
+	return s.addMachineWithRequestedNetworks(nil, nil)
 }
 
-func (s *CommonProvisionerSuite) addMachineWithNetworks(includeNetworks, excludeNetworks []string) (*state.Machine, error) {
+func (s *CommonProvisionerSuite) addMachineWithRequestedNetworks(includeNetworks, excludeNetworks []string) (*state.Machine, error) {
 	return s.BackingState.AddOneMachine(state.MachineTemplate{
 		Series:          coretesting.FakeDefaultSeries,
 		Jobs:            []state.MachineJob{state.JobHostUnits},
@@ -459,14 +459,14 @@
 	s.waitRemoved(c, m)
 }
 
-func (s *ProvisionerSuite) TestProvisioningMachinesWithNetworks(c *gc.C) {
+func (s *ProvisionerSuite) TestProvisioningMachinesWithRequestedNetworks(c *gc.C) {
 	p := s.newEnvironProvisioner(c)
 	defer stop(c, p)
 
 	// Add and provision a machine with networks specified.
 	includeNetworks := []string{"net1", "net2"}
 	excludeNetworks := []string{"net3", "net4"}
-	m, err := s.addMachineWithNetworks(includeNetworks, excludeNetworks)
+	m, err := s.addMachineWithRequestedNetworks(includeNetworks, excludeNetworks)
 	c.Assert(err, gc.IsNil)
 	inst := s.checkStartInstanceCustom(c, m, "pork", s.defaultConstraints, includeNetworks, excludeNetworks)