diff --git a/Documentation/api-v1.md b/Documentation/api-v1.md
index 996acdfd2..0b5b235d9 100644
--- a/Documentation/api-v1.md
+++ b/Documentation/api-v1.md
@@ -1,279 +1,305 @@
-# fleet API v1
-
-The fleet API allows you to manage the state of the cluster using JSON over HTTP.
-
-## Managing Units
-
-Create and modify Unit entities to communicate to fleet the desired state of the cluster.
-This simply declares what *should* be happening; the backend system still has to react to the changes in this desired state.
-The actual state of the system is communicated with UnitState entities.
-
-### Unit Entity
-
-- **name**: (readonly) unique identifier of entity
-- **options**: list of UnitOption entities
-- **desiredState**: state the user wishes the Unit to be in ("inactive", "loaded", or "launched")
-- **currentState**: (readonly) state the Unit is currently in (same possible values as desiredState)
-- **machineID**: ID of machine to which the Unit is scheduled
-
-A UnitOption represents a single option in a systemd unit file.
-
-- **section**: name of section that contains the option (e.g. "Unit", "Service", "Socket")
-- **name**: name of option (e.g. "BindsTo", "After", "ExecStart")
-- **value**: value of option (e.g. "/usr/bin/docker run busybox /bin/sleep 1000")
-
-### Create a Unit
-
-#### Request
-
-Create a Unit by passing a partial Unit entity to the /units resource.
-The options and desiredState fields are required, and all other Unit fields will be ignored.
-
-The base request looks like this:
-
-```
-PUT /units/<name> HTTP/1.1
-
-{"desiredState": <state>, "options": [<option>, ...]}
-```
-
-For example, creating and launching a new unit "foo.service" could be done like so:
-
-```
-PUT /units/foo.service HTTP/1.1
-
-{
-  "desiredState": "launched",
-  "options": [{"section": "Service", "name": "ExecStart", "value": "/usr/bin/sleep 3000"}]
-}
-```
-
-**Note:** If the unit's name field is set in the request body, it must match the
-name in the PUT /units/<name> request.
-
-#### Response
-
-A success is indicated by a `201 Created` status code, but no response body.
-
-Attempting to create an entity without options will return a `409 Conflict` status code.
-
-Attempting to create an invalid entity will result in a `400 Bad Request` response.
-
-### Modify a Unit's desiredState
-
-#### Request
-
-
-Modify the desired state of an existing Unit by providing a partial entity.
-The only required field is desiredState:
-
-```
-PUT /units/<name> HTTP/1.1
-
-{"desiredState": <state>}
-```
-
-For example, unloading an existing Unit called "bar.service" could look like this:
-
-```
-PUT /units/bar.service HTTP/1.1
-
-{
-  "desiredState": "inactive"
-}
-```
-
-If the Unit's name field is set in the request body, it must match the name in the URL.
-
-#### Response
-
-A success is indicated by a `204 No Content`.
-
-Attempting to modify a Unit with an invalid entity will result in a `400 Bad Request` response.
-
-### List Units
-
-Explore a paginated collection of Unit entities.
-
-#### Request
-
-```
-GET /units HTTP/1.1
-```
-
-The request must not have a body.
-
-#### Response
-
-A successful response will have a `200 OK` status code and body containing a single page of zero or more Unit entities.
-
-### Get a Unit
-
-View a particular Unit entity.
-
-#### Request
-
-```
-GET /units/<name> HTTP/1.1
-```
-
-The request must not have a body.
-
-#### Response
-
-A successful response will have a `200 OK` status code and body containing a single Unit entity.
-
-If the requested Unit does not exist, a `404 Not Found` will be returned.
-
-### Destroy a Unit
-
-Completely remove a Unit from fleet.
-
-#### Request
-
-```
-DELETE /units/<name> HTTP/1.1
-```
-
-#### Response
-
-A successful response is indicated by a `204 No Content`.
-
-If the indicated Unit does not exist, a `404 Not Found` will be returned.
-
-## Current Unit State
-
-Whereas Unit entities represent the desired state of units known by fleet, UnitStates represent the current states of units actually running in the cluster.
-The information reported by UnitStates will not always align perfectly with the Units, as there is a delay between the declaration of desired state and the backend system making all of the necessary changes.
-
-### UnitState Entity
-
-- **name**: unique identifier of entity
-- **hash**: SHA1 hash of underlying unit file
-- **machineID**: ID of machine from which this state originated
-- **systemdLoadState**: load state as reported by systemd
-- **systemdActiveState**: active state as reported by systemd
-- **systemdSubState**: sub state as reported by systemd
-
-### List Unit State
-
-Explore a paginated collection of UnitState entities.
-
-#### Request
-
-```
-GET /state HTTP/1.1
-```
-
-The request must not have a body.
-
-The request may be filtered using two query parameters:
-- **machineID**: filter all UnitState objects to those originating from a specific machine
-- **unitName**: filter all UnitState objects to those related to a specific unit
-
-#### Response
-
-A successful response will contain a single page of zero or more UnitState entities.
-
-## Machines
-
-### Machine Entity
-
-A Machine represents a host in the cluster.
-It uses the host's [machine-id][systemd-machine-id] as a unique identifier.
-
-[systemd-machine-id]: http://www.freedesktop.org/software/systemd/man/machine-id.html
-
-- **id**: unique identifier of Machine entity
-- **primaryIP**: IP address that should be used to communicate with this host
-- **metadata**: dictionary of key-value data published by the machine
-
-### List Machines
-
-Explore a paginated collection of Machine entities.
-
-#### Request
-
-```
-GET /machines HTTP/1.1
-```
-
-The request must not have a body.
-
-#### Response
-
-A successful response will contain a page of zero or more Machine entities.
-
-## Capability Discovery
-
-The v1 fleet API is described by a [discovery document][disco]. Users should generate their client bindings from this document using the appropriate language generator.
-This document is available in the [fleet source][schema] and served directly from the API itself, at the `/discovery` endpoint.
-Note that this discovery document intentionally ships with an unusable `rootUrl`; clients *must* initialize this as appropriate.
-
-An extremely simplified example client can be found [here][example].
-
-[disco]: https://developers.google.com/discovery/v1/reference/apis
-[schema]: ../schema/v1.json
-[example]: ../Documentation/examples/api.py
-
-## Media Types
-
-All API requests and responses use the `application/json` media type.
-New media types may be introduced in the future.
-
-## Pagination
-
-If a collection is large enough to warrant a paginated response, it will return a `nextPageToken` field in its response body.
-To retrieve the next page of entities, a client must make a subsequent HTTP request with a single `nextPageToken` query parameter set to the value received in a response body.
-If a paginated response does not contain a `nextPageToken` field, a client may safely assume no more entities are available.
-
-### Pagination Example
-
-The following series of HTTP request/response pairs demonstrates how pagination works against a fictional resource:
-
-```
-GET /cats HTTP/1.1
-
-
-HTTP/1.1 200 OK
-
-{"cats": [{"id": "baxter"}, {"id": "charlie"}], "nextPageToken": "8fefec2c"}
-```
-
-```
-GET /cats?nextPageToken=8fefec2c HTTP/1.1
-
-
-HTTP/1.1 200 OK
-
-{"cats": [{"id": "michael"}, {"id": "prescott"}], "nextPageToken": "cbb06916"}
-```
-
-```
-GET /cats?nextPageToken=cbb06916 HTTP/1.1
-
-
-HTTP/1.1 200 OK
-
-{"cats": [{"id":"timothy"}]}
-```
-
-## Error Communication
-
-400- and 500-level API responses may return JSON-encoded error entities.
-The response will have an `application/json` Content-Type header.
-An error entity has the following fields:
-
-- **error**
-  - **code**: The HTTP status code of the response
-  - **message**: A human-readable error message explaining the failure
-
-For example, if an invalid value is passed for a `nextPageToken`, the following HTTP response could be sent:
-
-```
-HTTP/1.1 400 Bad Request
-Content-Type: application/json
-Content-Length: 80
-
-{"error:{"code":400,"message":"invalid value of nextPageToken query parameter"}}
-```
+# fleet API v1
+
+The fleet API allows you to manage the state of the cluster using JSON over HTTP.
+
+## Managing Units
+
+Create and modify Unit entities to communicate to fleet the desired state of the cluster.
+This simply declares what *should* be happening; the backend system still has to react to the changes in this desired state.
+The actual state of the system is communicated with UnitState entities.
+
+### Unit Entity
+
+- **name**: (readonly) unique identifier of entity
+- **options**: list of UnitOption entities
+- **desiredState**: state the user wishes the Unit to be in ("inactive", "loaded", or "launched")
+- **currentState**: (readonly) state the Unit is currently in (same possible values as desiredState)
+- **machineID**: ID of machine to which the Unit is scheduled
+
+A UnitOption represents a single option in a systemd unit file.
+
+- **section**: name of section that contains the option (e.g. "Unit", "Service", "Socket")
+- **name**: name of option (e.g. "BindsTo", "After", "ExecStart")
+- **value**: value of option (e.g. "/usr/bin/docker run busybox /bin/sleep 1000")
+
+### Create a Unit
+
+#### Request
+
+Create a Unit by passing a partial Unit entity to the /units resource.
+The options and desiredState fields are required, and all other Unit fields will be ignored.
+
+The base request looks like this:
+
+```
+PUT /units/<name> HTTP/1.1
+
+{"desiredState": <state>, "options": [<option>, ...]}
+```
+
+For example, creating and launching a new unit "foo.service" could be done like so:
+
+```
+PUT /units/foo.service HTTP/1.1
+
+{
+  "desiredState": "launched",
+  "options": [{"section": "Service", "name": "ExecStart", "value": "/usr/bin/sleep 3000"}]
+}
+```
+
+**Note:** If the unit's name field is set in the request body, it must match the
+name in the PUT /units/<name> request.
+
+#### Response
+
+A success is indicated by a `201 Created` status code, but no response body.
+
+Attempting to create an entity without options will return a `409 Conflict` status code.
+
+Attempting to create an invalid entity will result in a `400 Bad Request` response.
+
+### Modify a Unit's desiredState
+
+#### Request
+
+
+Modify the desired state of an existing Unit by providing a partial entity.
+The only required field is desiredState:
+
+```
+PUT /units/<name> HTTP/1.1
+
+{"desiredState": <state>}
+```
+
+For example, unloading an existing Unit called "bar.service" could look like this:
+
+```
+PUT /units/bar.service HTTP/1.1
+
+{
+  "desiredState": "inactive"
+}
+```
+
+If the Unit's name field is set in the request body, it must match the name in the URL.
+
+#### Response
+
+A success is indicated by a `204 No Content`.
+
+Attempting to modify a Unit with an invalid entity will result in a `400 Bad Request` response.
+
+### List Units
+
+Explore a paginated collection of Unit entities.
+
+#### Request
+
+```
+GET /units HTTP/1.1
+```
+
+The request must not have a body.
+
+#### Response
+
+A successful response will have a `200 OK` status code and body containing a single page of zero or more Unit entities.
+
+### Get a Unit
+
+View a particular Unit entity.
+
+#### Request
+
+```
+GET /units/<name> HTTP/1.1
+```
+
+The request must not have a body.
+
+#### Response
+
+A successful response will have a `200 OK` status code and body containing a single Unit entity.
+
+If the requested Unit does not exist, a `404 Not Found` will be returned.
+
+### Destroy a Unit
+
+Completely remove a Unit from fleet.
+
+#### Request
+
+```
+DELETE /units/<name> HTTP/1.1
+```
+
+#### Response
+
+A successful response is indicated by a `204 No Content`.
+
+If the indicated Unit does not exist, a `404 Not Found` will be returned.
+
+## Current Unit State
+
+Whereas Unit entities represent the desired state of units known by fleet, UnitStates represent the current states of units actually running in the cluster.
+The information reported by UnitStates will not always align perfectly with the Units, as there is a delay between the declaration of desired state and the backend system making all of the necessary changes.
+
+### UnitState Entity
+
+- **name**: unique identifier of entity
+- **hash**: SHA1 hash of underlying unit file
+- **machineID**: ID of machine from which this state originated
+- **systemdLoadState**: load state as reported by systemd
+- **systemdActiveState**: active state as reported by systemd
+- **systemdSubState**: sub state as reported by systemd
+
+### List Unit State
+
+Explore a paginated collection of UnitState entities.
+
+#### Request
+
+```
+GET /state HTTP/1.1
+```
+
+The request must not have a body.
+
+The request may be filtered using two query parameters:
+- **machineID**: filter all UnitState objects to those originating from a specific machine
+- **unitName**: filter all UnitState objects to those related to a specific unit
+
+#### Response
+
+A successful response will contain a single page of zero or more UnitState entities.
+
+## Machines
+
+### Machine Entity
+
+A Machine represents a host in the cluster.
+It uses the host's [machine-id][systemd-machine-id] as a unique identifier.
+
+[systemd-machine-id]: http://www.freedesktop.org/software/systemd/man/machine-id.html
+
+- **id**: unique identifier of Machine entity
+- **primaryIP**: IP address that should be used to communicate with this host
+- **metadata**: dictionary of key-value data published by the machine
+
+### List Machines
+
+Explore a paginated collection of Machine entities.
+
+#### Request
+
+```
+GET /machines HTTP/1.1
+```
+
+The request must not have a body.
+
+#### Response
+
+A successful response will contain a page of zero or more Machine entities.
+
+### Edit Machine Metadata
+
+Add, change, or remove metadata from one or more machines.
+
+#### Request
+
+```
+PATCH /machines HTTP/1.1
+
+[
+  { "op": "add", "path": "/<machine_id>/metadata/<name>", "value": <new value> },
+  { "op": "modify", "path": "/<machine_id>/metadata/<name>", "value": <new value> },
+  { "op": "delete", "path": "/<machine_id>/metadata/<name>" }
+]
+
+```
+
+The request body must contain a JSON document in [JSONPatch](http://jsonpatch.com) format. Supported operations are "add", "remove" and "replace". Any number of operations for any number of machines, including machines not currently registered with the cluster, may be included in a single request. All operations will be processed in-order, top to bottom after validation. Modified metadata will persist across a machine leaving and rejoining the cluster.
+
+
+#### Response
+
+A success in indicated by a `204 No Content`.
+Invalid operations, missing values, or improperly formatted paths will result in a `400 Bad Request`.
+
+
+## Capability Discovery
+
+The v1 fleet API is described by a [discovery document][disco]. Users should generate their client bindings from this document using the appropriate language generator.
+This document is available in the [fleet source][schema] and served directly from the API itself, at the `/discovery` endpoint.
+Note that this discovery document intentionally ships with an unusable `rootUrl`; clients *must* initialize this as appropriate.
+
+An extremely simplified example client can be found [here][example].
+
+[disco]: https://developers.google.com/discovery/v1/reference/apis
+[schema]: ../schema/v1.json
+[example]: ../Documentation/examples/api.py
+
+## Media Types
+
+All API requests and responses use the `application/json` media type.
+New media types may be introduced in the future.
+
+## Pagination
+
+If a collection is large enough to warrant a paginated response, it will return a `nextPageToken` field in its response body.
+To retrieve the next page of entities, a client must make a subsequent HTTP request with a single `nextPageToken` query parameter set to the value received in a response body.
+If a paginated response does not contain a `nextPageToken` field, a client may safely assume no more entities are available.
+
+### Pagination Example
+
+The following series of HTTP request/response pairs demonstrates how pagination works against a fictional resource:
+
+```
+GET /cats HTTP/1.1
+
+
+HTTP/1.1 200 OK
+
+{"cats": [{"id": "baxter"}, {"id": "charlie"}], "nextPageToken": "8fefec2c"}
+```
+
+```
+GET /cats?nextPageToken=8fefec2c HTTP/1.1
+
+
+HTTP/1.1 200 OK
+
+{"cats": [{"id": "michael"}, {"id": "prescott"}], "nextPageToken": "cbb06916"}
+```
+
+```
+GET /cats?nextPageToken=cbb06916 HTTP/1.1
+
+
+HTTP/1.1 200 OK
+
+{"cats": [{"id":"timothy"}]}
+```
+
+## Error Communication
+
+400- and 500-level API responses may return JSON-encoded error entities.
+The response will have an `application/json` Content-Type header.
+An error entity has the following fields:
+
+- **error**
+  - **code**: The HTTP status code of the response
+  - **message**: A human-readable error message explaining the failure
+
+For example, if an invalid value is passed for a `nextPageToken`, the following HTTP response could be sent:
+
+```
+HTTP/1.1 400 Bad Request
+Content-Type: application/json
+Content-Length: 80
+
+{"error:{"code":400,"message":"invalid value of nextPageToken query parameter"}}
+```
diff --git a/Documentation/unit-files-and-scheduling.md b/Documentation/unit-files-and-scheduling.md
index c181643e2..c9c031dd7 100644
--- a/Documentation/unit-files-and-scheduling.md
+++ b/Documentation/unit-files-and-scheduling.md
@@ -1,160 +1,160 @@
-# Unit Files
-
-Unit files are the primary means of interacting with fleet. They define what you want to do, and how fleet should do it.
-
-fleet will schedule any valid service, socket, path or timer systemd unit to a machine in the cluster, taking into account a few special properties in the `[X-Fleet]` section. If you're new to using systemd unit files, check out the [Getting Started with systemd guide](https://coreos.com/docs/launching-containers/launching/getting-started-with-systemd).
-
-## Unit Requirements
-
-The unit name must be of the form `string.suffix` or `string@instance.suffix`, where:
-
-* `string` must not be an empty string and can only contain alphanumeric characters and any of `:_.@-`. Formally, it must match the regular expression `[a-zA-Z0-9:_.@-]+`
-* `instance` can be empty, and can only contain the same characters as are valid for `string`. Formally, it must match the regular expression `[a-zA-Z0-9:_.@-]*`
-* `suffix` must be one of the following unit types: `service`, `socket`, `device`, `mount`, `automount`, `timer`, `path`
-
-Note that these requirements are derived directly from systemd, with the only exception that the unit types are a subset of those supported by systemd.
-
-## fleet-specific Options
-
-| Option Name | Description |
-|-------------|-------------|
-| `MachineID` | Require the unit be scheduled to the machine identified by the given string. |
-| `MachineOf` | Limit eligible machines to the one that hosts a specific unit. |
-| `MachineMetadata` | Limit eligible machines to those with this specific metadata. |
-| `Conflicts` | Prevent a unit from being collocated with other units using glob-matching on the other unit names. |
-| `Global` | Schedule this unit on all agents in the cluster. A unit is considered invalid if options other than `MachineMetadata` are provided alongside `Global=true`. |
-
-See [more information](#unit-scheduling) on these parameters and how they impact scheduling decisions.
-
-In versions of fleet <= 0.8.0, the following options are available. They are deprecated and should be migrated to the new options as soon as possible.
-
-| Option Name | Description |
-|-------------|-------------|
-| `X-ConditionMachineID` | _Deprecated in v0.8.0 in favor of `MachineID`_ |
-| `X-ConditionMachineOf` | _Deprecated in v0.8.0 in favor of `MachineOf`_ |
-| `X-ConditionMachineMetadata` | _Deprecated in v0.8.0 in favor of `MachineMetadata`_ |
-| `X-Conflicts` | _Deprecated in v0.8.0 in favor of `Conflicts`_ |
-
-Take the following as an example of how your `[X-Fleet]` section could be written:
-
-```
-[Unit]
-Description=Some Monitoring Service
-
-[Service]
-ExecStart=/bin/monitorme
-
-[X-Fleet]
-MachineMetadata=location=chicago
-Conflicts=monitor*
-```
-
-## Template unit files
-
-fleet provides support for using systemd's [instances][systemd instances] feature to dynamically create _instance_ units from a common _template_ unit file. This allows you to have a single unit configuration and easily and dynamically create new instances of the unit as necessary.
-
-To use instance units, simply create a unit file whose name matches the `<name>@.<suffix>` format - for example, `hello@.service` - and submit it to fleet. You can then instantiate units by creating new units that match the instance pattern `<name>@<instance>.<suffix>` - in this case, for example, `hello@world.service` or `hello@1.service` - and fleet will automatically utilize the relevant template unit. For a detailed example, see the [example deployment].
-
-When working with instance units, it is strongly recommended that all units be _entirely homogenous_. This means that any unit created as, say, `foo@1.service`, should be created only from the unit named `foo@.service`. This homogeneity will be enforced by the fleet API in future.
-
-[example deployment]: https://github.com/coreos/fleet/blob/master/Documentation/examples/example-deployment.md#service-files
-
-## systemd specifiers
-
-When evaluating the `[X-Fleet]` section, fleet supports a subset of systemd's [specifiers][systemd specifiers] to perform variable substitution. The following specifiers are currently supported:
-
-
-| Specifier   | Description              |
-|-------------|--------------------------|
-|    `%n`     | Full unit name           |
-|    `%N`     | Unescaped full unit name |
-|    `%p`     | Unescaped prefix name    |
-|    `%i`     | Instance name            |
-
-
-For more information, refer to the official [systemd documentation][systemd specifiers].
-
-[systemd instances]: http://0pointer.de/blog/projects/instances.html
-[systemd specifiers]: http://www.freedesktop.org/software/systemd/man/systemd.unit.html#Specifiers
-
-
-# Unit Scheduling
-
-When working with units, fleet distinguishes between two types of units: _non-global_ (the default) and _global_. (A global unit is one with `Global=true` in its `X-Fleet` section, as mentioned above).
-
-Non-global units are scheduled by the fleet engine - the engine is responsible for deciding where they should be placed in the cluster. 
-
-Global units can run on every possible machine in the fleet cluster.
-While global units are not scheduled through the engine, fleet agents still check the `MachineMetadata` option before starting them.
-Other options are ignored.
-
-For more details on the specific behavior of the engine, read more about [fleet's architecture and data model](https://github.com/coreos/fleet/blob/master/Documentation/architecture.md).
-
-## User-Defined Requirements
-
-For non-global units, several different directives are available to control the engine's scheduling decision.
-
-##### Schedule unit to specific machine
-
-The `MachineID` option of a unit file causes the system to schedule a unit to a machine identified by the option's value.
-
-The ID of each machine is currently published in the `MACHINE` column in the output of `fleetctl list-machines -l`.
-One must use the entire ID when setting `MachineID` - the shortened ID returned by `fleetctl list-machines` without the `-l` flag is not acceptable.
-
-fleet depends on its host to generate an identifier at `/etc/machine-id`, which is handled today by systemd.
-Read more about machine IDs in the [official systemd documentation][machine-id].
-
-[machine-id]: http://www.freedesktop.org/software/systemd/man/machine-id.html
-
-##### Schedule unit to machine with specific metadata
-
-The `MachineMetadata` option of a unit file allows you to set conditional metadata required for a machine to be elegible.
-
-```
-[X-Fleet]
-MachineMetadata="region=us-east-1" "diskType=SSD"
-```
-
-This requires an eligible machine to have at least the `region` and `diskType` keys set accordingly. A single key may also be defined multiple times, in which case only one of the conditions needs to be met:
-
-```
-[X-Fleet]
-MachineMetadata=region=us-east-1
-MachineMetadata=region=us-west-1
-```
-
-This would allow a machine to match just one of the provided values to be considered eligible to run.
-
-A machine is not automatically configured with metadata.
-A deployer may define machine metadata using the `metadata` [config option](https://github.com/coreos/fleet/blob/master/Documentation/deployment-and-configuration.md#metadata).
-
-##### Schedule unit next to another unit
-
-In order for a unit to be scheduled to the same machine as another unit, a unit file can define `MachineOf`.
-The value of this option is the exact name of another unit in the system, which we'll call the target unit.
-
-If the target unit is not found in the system, the follower unit will be considered unschedulable. 
-Once the target unit is scheduled somewhere, the follower unit will be scheduled there as well.
-
-Follower units will reschedule themselves around the cluster to ensure their `MachineOf` options are always fulfilled.
-
-Note that currently `MachineOf` _cannot_ be a bidirectional dependency: i.e., if unit `foo.service` has `MachineOf=bar.service`, then `bar.service` must not have a `MachineOf=foo.service`, or fleet will be unable to schedule the units.
-
-##### Schedule unit away from other unit(s)
-
-The value of the `Conflicts` option is a [glob pattern](http://golang.org/pkg/path/#Match) defining which other units next to which a given unit must not be scheduled. A unit may have multiple `Conflicts` options.
-
-If a unit is scheduled to the system without an `Conflicts` option, other units' conflicts still take effect and prevent the new unit from being scheduled to machines where conflicts exist.
-
-##### Dynamic requirements
-
-fleet supports several [systemd specifiers](#systemd-specifiers) to allow requirements to be dynamically determined based on a Unit's name. This means that the same unit can be used for multiple Units and the requirements are dynamically substituted when the Unit is scheduled.
-
-For example, a Unit by the name `foo.service`, whose unit contains the following snippet:
-
-```
-[X-Fleet]
-MachineOf=%p.socket
-```
-
-would result in an effective `MachineOf` of `foo.socket`. Using the same unit snippet with a Unit called `bar.service`, on the other hand, would result in an effective `MachineOf` of `bar.socket`.
+# Unit Files
+
+Unit files are the primary means of interacting with fleet. They define what you want to do, and how fleet should do it.
+
+fleet will schedule any valid service, socket, path or timer systemd unit to a machine in the cluster, taking into account a few special properties in the `[X-Fleet]` section. If you're new to using systemd unit files, check out the [Getting Started with systemd guide](https://coreos.com/docs/launching-containers/launching/getting-started-with-systemd).
+
+## Unit Requirements
+
+The unit name must be of the form `string.suffix` or `string@instance.suffix`, where:
+
+* `string` must not be an empty string and can only contain alphanumeric characters and any of `:_.@-`. Formally, it must match the regular expression `[a-zA-Z0-9:_.@-]+`
+* `instance` can be empty, and can only contain the same characters as are valid for `string`. Formally, it must match the regular expression `[a-zA-Z0-9:_.@-]*`
+* `suffix` must be one of the following unit types: `service`, `socket`, `device`, `mount`, `automount`, `timer`, `path`
+
+Note that these requirements are derived directly from systemd, with the only exception that the unit types are a subset of those supported by systemd.
+
+## fleet-specific Options
+
+| Option Name | Description |
+|-------------|-------------|
+| `MachineID` | Require the unit be scheduled to the machine identified by the given string. |
+| `MachineOf` | Limit eligible machines to the one that hosts a specific unit. |
+| `MachineMetadata` | Limit eligible machines to those with this specific metadata. |
+| `Conflicts` | Prevent a unit from being collocated with other units using glob-matching on the other unit names. |
+| `Global` | Schedule this unit on all agents in the cluster. A unit is considered invalid if options other than `MachineMetadata` are provided alongside `Global=true`. |
+
+See [more information](#unit-scheduling) on these parameters and how they impact scheduling decisions.
+
+In versions of fleet <= 0.8.0, the following options are available. They are deprecated and should be migrated to the new options as soon as possible.
+
+| Option Name | Description |
+|-------------|-------------|
+| `X-ConditionMachineID` | _Deprecated in v0.8.0 in favor of `MachineID`_ |
+| `X-ConditionMachineOf` | _Deprecated in v0.8.0 in favor of `MachineOf`_ |
+| `X-ConditionMachineMetadata` | _Deprecated in v0.8.0 in favor of `MachineMetadata`_ |
+| `X-Conflicts` | _Deprecated in v0.8.0 in favor of `Conflicts`_ |
+
+Take the following as an example of how your `[X-Fleet]` section could be written:
+
+```
+[Unit]
+Description=Some Monitoring Service
+
+[Service]
+ExecStart=/bin/monitorme
+
+[X-Fleet]
+MachineMetadata=location=chicago
+Conflicts=monitor*
+```
+
+## Template unit files
+
+fleet provides support for using systemd's [instances][systemd instances] feature to dynamically create _instance_ units from a common _template_ unit file. This allows you to have a single unit configuration and easily and dynamically create new instances of the unit as necessary.
+
+To use instance units, simply create a unit file whose name matches the `<name>@.<suffix>` format - for example, `hello@.service` - and submit it to fleet. You can then instantiate units by creating new units that match the instance pattern `<name>@<instance>.<suffix>` - in this case, for example, `hello@world.service` or `hello@1.service` - and fleet will automatically utilize the relevant template unit. For a detailed example, see the [example deployment].
+
+When working with instance units, it is strongly recommended that all units be _entirely homogenous_. This means that any unit created as, say, `foo@1.service`, should be created only from the unit named `foo@.service`. This homogeneity will be enforced by the fleet API in future.
+
+[example deployment]: https://github.com/coreos/fleet/blob/master/Documentation/examples/example-deployment.md#service-files
+
+## systemd specifiers
+
+When evaluating the `[X-Fleet]` section, fleet supports a subset of systemd's [specifiers][systemd specifiers] to perform variable substitution. The following specifiers are currently supported:
+
+
+| Specifier   | Description              |
+|-------------|--------------------------|
+|    `%n`     | Full unit name           |
+|    `%N`     | Unescaped full unit name |
+|    `%p`     | Unescaped prefix name    |
+|    `%i`     | Instance name            |
+
+
+For more information, refer to the official [systemd documentation][systemd specifiers].
+
+[systemd instances]: http://0pointer.de/blog/projects/instances.html
+[systemd specifiers]: http://www.freedesktop.org/software/systemd/man/systemd.unit.html#Specifiers
+
+
+# Unit Scheduling
+
+When working with units, fleet distinguishes between two types of units: _non-global_ (the default) and _global_. (A global unit is one with `Global=true` in its `X-Fleet` section, as mentioned above).
+
+Non-global units are scheduled by the fleet engine - the engine is responsible for deciding where they should be placed in the cluster. 
+
+Global units can run on every possible machine in the fleet cluster.
+While global units are not scheduled through the engine, fleet agents still check the `MachineMetadata` option before starting them.
+Other options are ignored.
+
+For more details on the specific behavior of the engine, read more about [fleet's architecture and data model](https://github.com/coreos/fleet/blob/master/Documentation/architecture.md).
+
+## User-Defined Requirements
+
+For non-global units, several different directives are available to control the engine's scheduling decision.
+
+##### Schedule unit to specific machine
+
+The `MachineID` option of a unit file causes the system to schedule a unit to a machine identified by the option's value.
+
+The ID of each machine is currently published in the `MACHINE` column in the output of `fleetctl list-machines -l`.
+One must use the entire ID when setting `MachineID` - the shortened ID returned by `fleetctl list-machines` without the `-l` flag is not acceptable.
+
+fleet depends on its host to generate an identifier at `/etc/machine-id`, which is handled today by systemd.
+Read more about machine IDs in the [official systemd documentation][machine-id].
+
+[machine-id]: http://www.freedesktop.org/software/systemd/man/machine-id.html
+
+##### Schedule unit to machine with specific metadata
+
+The `MachineMetadata` option of a unit file allows you to set conditional metadata required for a machine to be elegible.
+
+```
+[X-Fleet]
+MachineMetadata="region=us-east-1" "diskType=SSD"
+```
+
+This requires an eligible machine to have at least the `region` and `diskType` keys set accordingly. A single key may also be defined multiple times, in which case only one of the conditions needs to be met:
+
+```
+[X-Fleet]
+MachineMetadata=region=us-east-1
+MachineMetadata=region=us-west-1
+```
+
+This would allow a machine to match just one of the provided values to be considered eligible to run. If the metadata of a machine is modified in such a way that the unit is no longer eligible, the scheduler will shut it down and attempt to restart it on an eligible machine. If no eligible machines are available, the unit will remain in an inactive state until a suitable machine is available.
+
+A machine is not automatically configured with metadata.
+A deployer may define machine metadata using the `metadata` [config option](https://github.com/coreos/fleet/blob/master/Documentation/deployment-and-configuration.md#metadata) or via the [HTTP api](api-v1.md#edit-machine-metadata).
+
+##### Schedule unit next to another unit
+
+In order for a unit to be scheduled to the same machine as another unit, a unit file can define `MachineOf`.
+The value of this option is the exact name of another unit in the system, which we'll call the target unit.
+
+If the target unit is not found in the system, the follower unit will be considered unschedulable. 
+Once the target unit is scheduled somewhere, the follower unit will be scheduled there as well.
+
+Follower units will reschedule themselves around the cluster to ensure their `MachineOf` options are always fulfilled.
+
+Note that currently `MachineOf` _cannot_ be a bidirectional dependency: i.e., if unit `foo.service` has `MachineOf=bar.service`, then `bar.service` must not have a `MachineOf=foo.service`, or fleet will be unable to schedule the units.
+
+##### Schedule unit away from other unit(s)
+
+The value of the `Conflicts` option is a [glob pattern](http://golang.org/pkg/path/#Match) defining which other units next to which a given unit must not be scheduled. A unit may have multiple `Conflicts` options.
+
+If a unit is scheduled to the system without an `Conflicts` option, other units' conflicts still take effect and prevent the new unit from being scheduled to machines where conflicts exist.
+
+##### Dynamic requirements
+
+fleet supports several [systemd specifiers](#systemd-specifiers) to allow requirements to be dynamically determined based on a Unit's name. This means that the same unit can be used for multiple Units and the requirements are dynamically substituted when the Unit is scheduled.
+
+For example, a Unit by the name `foo.service`, whose unit contains the following snippet:
+
+```
+[X-Fleet]
+MachineOf=%p.socket
+```
+
+would result in an effective `MachineOf` of `foo.socket`. Using the same unit snippet with a Unit called `bar.service`, on the other hand, would result in an effective `MachineOf` of `bar.socket`.
diff --git a/agent/reconcile.go b/agent/reconcile.go
index a81803418..07fd9cd65 100644
--- a/agent/reconcile.go
+++ b/agent/reconcile.go
@@ -127,7 +127,13 @@ func desiredAgentState(a *Agent, reg registry.Registry) (*AgentState, error) {
 		return nil, err
 	}
 
-	ms := a.Machine.State()
+	// fetch full machine state from registry instead of
+	// using the local version to allow for dynamic metadata
+	ms, err := reg.MachineState(a.Machine.State().ID)
+	if err != nil {
+		log.Errorf("Failed fetching machine state from Registry: %v", err)
+		return nil, err
+	}
 	as := AgentState{
 		MState: &ms,
 		Units:  make(map[string]*job.Unit),
diff --git a/agent/reconcile_test.go b/agent/reconcile_test.go
index 159bf08d7..efdaf8b82 100644
--- a/agent/reconcile_test.go
+++ b/agent/reconcile_test.go
@@ -254,6 +254,7 @@ MachineMetadata=dog=woof`),
 		reg := registry.NewFakeRegistry()
 		reg.SetJobs(tt.regJobs)
 		a := makeAgentWithMetadata(tt.metadata)
+		reg.SetMachines([]machine.MachineState{a.Machine.State()})
 		as, err := desiredAgentState(a, reg)
 		if err != nil {
 			t.Errorf("case %d: unexpected error: %v", i, err)
diff --git a/api/machines.go b/api/machines.go
index 990d7d80c..2beff4aa3 100644
--- a/api/machines.go
+++ b/api/machines.go
@@ -15,9 +15,11 @@
 package api
 
 import (
-	"fmt"
+	"encoding/json"
+	"errors"
 	"net/http"
 	"path"
+	"regexp"
 
 	"github.com/coreos/fleet/client"
 	"github.com/coreos/fleet/log"
@@ -25,6 +27,10 @@ import (
 	"github.com/coreos/fleet/schema"
 )
 
+var (
+	metadataPathRegex = regexp.MustCompile("^/([^/]+)/metadata/([A-Za-z0-9_.-]+$)")
+)
+
 func wireUpMachinesResource(mux *http.ServeMux, prefix string, cAPI client.API) {
 	res := path.Join(prefix, "machines")
 	mr := machinesResource{cAPI}
@@ -35,12 +41,24 @@ type machinesResource struct {
 	cAPI client.API
 }
 
+type machineMetadataOp struct {
+	Operation string `json:"op"`
+	Path      string
+	Value     string
+}
+
 func (mr *machinesResource) ServeHTTP(rw http.ResponseWriter, req *http.Request) {
-	if req.Method != "GET" {
-		sendError(rw, http.StatusBadRequest, fmt.Errorf("only HTTP GET supported against this resource"))
-		return
+	switch req.Method {
+	case "GET":
+		mr.list(rw, req)
+	case "PATCH":
+		mr.patch(rw, req)
+	default:
+		sendError(rw, http.StatusMethodNotAllowed, errors.New("only GET and PATCH supported against this resource"))
 	}
+}
 
+func (mr *machinesResource) list(rw http.ResponseWriter, req *http.Request) {
 	token, err := findNextPageToken(req.URL)
 	if err != nil {
 		sendError(rw, http.StatusBadRequest, err)
@@ -62,6 +80,54 @@ func (mr *machinesResource) ServeHTTP(rw http.ResponseWriter, req *http.Request)
 	sendResponse(rw, http.StatusOK, page)
 }
 
+func (mr *machinesResource) patch(rw http.ResponseWriter, req *http.Request) {
+	var ops []machineMetadataOp
+	dec := json.NewDecoder(req.Body)
+	if err := dec.Decode(&ops); err != nil {
+		sendError(rw, http.StatusBadRequest, err)
+		return
+	}
+
+	for _, op := range ops {
+		if op.Operation != "add" && op.Operation != "remove" && op.Operation != "replace" {
+			sendError(rw, http.StatusBadRequest, errors.New("invalid op: expect add, remove, or replace"))
+			return
+		}
+
+		if metadataPathRegex.FindStringSubmatch(op.Path) == nil {
+			sendError(rw, http.StatusBadRequest, errors.New("machine metadata path invalid"))
+			return
+		}
+
+		if op.Operation != "remove" && len(op.Value) == 0 {
+			sendError(rw, http.StatusBadRequest, errors.New("invalid value: add and replace require a value"))
+			return
+		}
+	}
+
+	for _, op := range ops {
+		// regex already validated above
+		s := metadataPathRegex.FindStringSubmatch(op.Path)
+		machID := s[1]
+		key := s[2]
+
+		if op.Operation == "remove" {
+			err := mr.cAPI.DeleteMachineMetadata(machID, key)
+			if err != nil {
+				sendError(rw, http.StatusInternalServerError, err)
+				return
+			}
+		} else {
+			err := mr.cAPI.SetMachineMetadata(machID, key, op.Value)
+			if err != nil {
+				sendError(rw, http.StatusInternalServerError, err)
+				return
+			}
+		}
+	}
+	sendResponse(rw, http.StatusNoContent, nil)
+}
+
 func getMachinePage(cAPI client.API, tok PageToken) (*schema.MachinePage, error) {
 	all, err := cAPI.Machines()
 	if err != nil {
diff --git a/api/machines_test.go b/api/machines_test.go
index 969b5c590..674680371 100644
--- a/api/machines_test.go
+++ b/api/machines_test.go
@@ -19,6 +19,7 @@ import (
 	"net/http/httptest"
 	"reflect"
 	"strconv"
+	"strings"
 	"testing"
 
 	"github.com/coreos/fleet/client"
@@ -26,16 +27,22 @@ import (
 	"github.com/coreos/fleet/registry"
 )
 
-func TestMachinesList(t *testing.T) {
+func fakeMachinesSetup() (*machinesResource, *httptest.ResponseRecorder) {
 	fr := registry.NewFakeRegistry()
 	fr.SetMachines([]machine.MachineState{
-		{ID: "XXX", PublicIP: "", Metadata: nil},
+		{ID: "XXX", PublicIP: "", Metadata: map[string]string{}},
 		{ID: "YYY", PublicIP: "1.2.3.4", Metadata: map[string]string{"ping": "pong"}},
 	})
 	fAPI := &client.RegistryClient{Registry: fr}
 	resource := &machinesResource{cAPI: fAPI}
 	rw := httptest.NewRecorder()
-	req, err := http.NewRequest("GET", "http://example.com", nil)
+
+	return resource, rw
+}
+
+func TestMachinesList(t *testing.T) {
+	resource, rw := fakeMachinesSetup()
+	req, err := http.NewRequest("GET", "http://example.com/machines", nil)
 	if err != nil {
 		t.Fatalf("Failed creating http.Request: %v", err)
 	}
@@ -63,11 +70,23 @@ func TestMachinesList(t *testing.T) {
 	}
 }
 
+func TestMachinesListBadMethod(t *testing.T) {
+	resource, rw := fakeMachinesSetup()
+	req, err := http.NewRequest("POST", "http://example.com/machines", nil)
+	if err != nil {
+		t.Fatalf("Failed creating http.Request: %v", err)
+	}
+
+	resource.ServeHTTP(rw, req)
+
+	err = assertErrorResponse(rw, http.StatusMethodNotAllowed)
+	if err != nil {
+		t.Error(err.Error())
+	}
+}
+
 func TestMachinesListBadNextPageToken(t *testing.T) {
-	fr := registry.NewFakeRegistry()
-	fAPI := &client.RegistryClient{Registry: fr}
-	resource := &machinesResource{fAPI}
-	rw := httptest.NewRecorder()
+	resource, rw := fakeMachinesSetup()
 	req, err := http.NewRequest("GET", "http://example.com/machines?nextPageToken=EwBMLg==", nil)
 	if err != nil {
 		t.Fatalf("Failed creating http.Request: %v", err)
@@ -136,3 +155,126 @@ func TestExtractMachinePage(t *testing.T) {
 		}
 	}
 }
+
+func TestMachinesPatchAddModify(t *testing.T) {
+	reqBody := `
+	[{"op": "add", "path": "/XXX/metadata/foo", "value": "bar"},
+	 {"op": "replace", "path": "/YYY/metadata/ping", "value": "splat"}]
+	`
+
+	resource, rw := fakeMachinesSetup()
+	req, err := http.NewRequest("PATCH", "http://example.com/machines", strings.NewReader(reqBody))
+	if err != nil {
+		t.Fatalf("Failed creating http.Request: %v", err)
+	}
+
+	resource.ServeHTTP(rw, req)
+	if rw.Code != http.StatusNoContent {
+		t.Errorf("Expected 204, got %d", rw.Code)
+	}
+
+	// fetch machine to make sure data has been added
+	req, err = http.NewRequest("GET", "http://example.com/machines", nil)
+	if err != nil {
+		t.Fatalf("Failed creating http.Request: %v", err)
+	}
+	rw.Body.Reset()
+	resource.ServeHTTP(rw, req)
+
+	if rw.Body == nil {
+		t.Error("Received nil response body")
+	} else {
+		body := rw.Body.String()
+		expected := `{"machines":[{"id":"XXX","metadata":{"foo":"bar"}},{"id":"YYY","metadata":{"ping":"splat"},"primaryIP":"1.2.3.4"}]}`
+		if body != expected {
+			t.Errorf("Expected body:\n%s\n\nReceived body:\n%s\n", expected, body)
+		}
+	}
+}
+
+func TestMachinesPatchDelete(t *testing.T) {
+	reqBody := `
+	[{"op": "remove", "path": "/XXX/metadata/foo"},
+	 {"op": "remove", "path": "/YYY/metadata/ping"}]
+	`
+
+	resource, rw := fakeMachinesSetup()
+	req, err := http.NewRequest("PATCH", "http://example.com/machines", strings.NewReader(reqBody))
+	if err != nil {
+		t.Fatalf("Failed creating http.Request: %v", err)
+	}
+
+	resource.ServeHTTP(rw, req)
+	if rw.Code != http.StatusNoContent {
+		t.Errorf("Expected 204, got %d", rw.Code)
+	}
+
+	// fetch machine to make sure data has been added
+	req, err = http.NewRequest("GET", "http://example.com/machines", nil)
+	if err != nil {
+		t.Fatalf("Failed creating http.Request: %v", err)
+	}
+	rw.Body.Reset()
+	resource.ServeHTTP(rw, req)
+
+	if rw.Body == nil {
+		t.Error("Received nil response body")
+	} else {
+		body := rw.Body.String()
+		expected := `{"machines":[{"id":"XXX"},{"id":"YYY","primaryIP":"1.2.3.4"}]}`
+		if body != expected {
+			t.Errorf("Expected body:\n%s\n\nReceived body:\n%s\n", expected, body)
+		}
+	}
+}
+
+func TestMachinesPatchBadOp(t *testing.T) {
+	reqBody := `
+	[{"op": "noop", "path": "/XXX/metadata/foo", "value": "bar"}]
+	`
+
+	resource, rw := fakeMachinesSetup()
+	req, err := http.NewRequest("PATCH", "http://example.com/machines", strings.NewReader(reqBody))
+	if err != nil {
+		t.Fatalf("Failed creating http.Request: %v", err)
+	}
+
+	resource.ServeHTTP(rw, req)
+	if rw.Code != http.StatusBadRequest {
+		t.Errorf("Expected 400, got %d", rw.Code)
+	}
+}
+
+func TestMachinesPatchBadPath(t *testing.T) {
+	reqBody := `
+	[{"op": "add", "path": "/XXX/foo", "value": "bar"}]
+	`
+
+	resource, rw := fakeMachinesSetup()
+	req, err := http.NewRequest("PATCH", "http://example.com/machines", strings.NewReader(reqBody))
+	if err != nil {
+		t.Fatalf("Failed creating http.Request: %v", err)
+	}
+
+	resource.ServeHTTP(rw, req)
+	if rw.Code != http.StatusBadRequest {
+		t.Errorf("Expected 400, got %d", rw.Code)
+	}
+}
+
+func TestMachinesPatchBadValue(t *testing.T) {
+	reqBody := `
+	[{"op": "add", "path": "/XXX/foo"}]
+	`
+
+	resource, rw := fakeMachinesSetup()
+	req, err := http.NewRequest("PATCH", "http://example.com/machines", strings.NewReader(reqBody))
+	if err != nil {
+		t.Fatalf("Failed creating http.Request: %v", err)
+	}
+
+	resource.ServeHTTP(rw, req)
+	if rw.Code != http.StatusBadRequest {
+		t.Errorf("Expected 400, got %d", rw.Code)
+	}
+}
diff --git a/client/api.go b/client/api.go
index 470007dfe..10a146e1d 100644
--- a/client/api.go
+++ b/client/api.go
@@ -21,6 +21,8 @@ import (
 
 type API interface {
 	Machines() ([]machine.MachineState, error)
+	SetMachineMetadata(machID, key, value string) error
+	DeleteMachineMetadata(machID, key string) error
 
 	Unit(string) (*schema.Unit, error)
 	Units() ([]*schema.Unit, error)
diff --git a/registry/fake.go b/registry/fake.go
index 2a6c8bc5a..e99d7b0d4 100644
--- a/registry/fake.go
+++ b/registry/fake.go
@@ -279,6 +279,37 @@ func (f *FakeRegistry) UnitHeartbeat(name, machID string, ttl time.Duration) err
 
 func (f *FakeRegistry) ClearUnitHeartbeat(string) {}
 
+func (f *FakeRegistry) SetMachineMetadata(machID string, key string, value string) error {
+	for _, mach := range f.machines {
+		if mach.ID == machID {
+			mach.Metadata[key] = value
+		}
+	}
+	return nil
+}
+
+func (f *FakeRegistry) DeleteMachineMetadata(machID string, key string) error {
+	for _, mach := range f.machines {
+		if mach.ID == machID {
+			delete(mach.Metadata, key)
+		}
+	}
+	return nil
+}
+
+func (f *FakeRegistry) MachineState(machID string) (machine.MachineState, error) {
+	f.RLock()
+	defer f.RUnlock()
+
+	for _, mach := range f.machines {
+		if mach.ID == machID {
+			return mach, nil
+		}
+	}
+
+	return machine.MachineState{}, errors.New("Machine state not found")
+}
+
 func NewFakeClusterRegistry(dVersion *semver.Version, eVersion int) *FakeClusterRegistry {
 	return &FakeClusterRegistry{
 		dVersion: dVersion,
diff --git a/registry/interface.go b/registry/interface.go
index 270a2ef9d..2224b4d69 100644
--- a/registry/interface.go
+++ b/registry/interface.go
@@ -36,7 +36,10 @@ type Registry interface {
 	ScheduleUnit(name, machID string) error
 	SetUnitTargetState(name string, state job.JobState) error
 	SetMachineState(ms machine.MachineState, ttl time.Duration) (uint64, error)
+	MachineState(machID string) (machine.MachineState, error)
 	UnscheduleUnit(name, machID string) error
+	SetMachineMetadata(machID, key, value string) error
+	DeleteMachineMetadata(machID, key string) error
 
 	UnitRegistry
 }
diff --git a/registry/machine.go b/registry/machine.go
index 3ed8a1812..cb307a210 100644
--- a/registry/machine.go
+++ b/registry/machine.go
@@ -43,17 +43,13 @@ func (r *EtcdRegistry) Machines() (machines []machine.MachineState, err error) {
 	}
 
 	for _, node := range resp.Node.Nodes {
-		for _, obj := range node.Nodes {
-			if !strings.HasSuffix(obj.Key, "/object") {
-				continue
-			}
-
-			var mach machine.MachineState
-			err = unmarshal(obj.Value, &mach)
-			if err != nil {
-				return
-			}
+		var mach machine.MachineState
+		mach, err = readMachineState(&node)
+		if err != nil {
+			return
+		}
 
+		if mach.ID != "" {
 			machines = append(machines, mach)
 		}
 	}
@@ -94,6 +90,38 @@ func (r *EtcdRegistry) SetMachineState(ms machine.MachineState, ttl time.Duratio
 	return resp.Node.ModifiedIndex, nil
 }
 
+func (r *EtcdRegistry) MachineState(machID string) (machine.MachineState, error) {
+	req := etcd.Get{
+		Key:       path.Join(r.keyPrefix, machinePrefix, machID),
+		Sorted:    true,
+		Recursive: true,
+	}
+
+	resp, err := r.etcd.Do(&req)
+	if err != nil {
+		return machine.MachineState{}, err
+	}
+
+	return readMachineState(resp.Node)
+}
+
+func (r *EtcdRegistry) SetMachineMetadata(machID string, key string, value string) error {
+	update := etcd.Set{
+		Key:   path.Join(r.keyPrefix, machinePrefix, machID, "metadata", key),
+		Value: value,
+	}
+
+	_, err := r.etcd.Do(&update)
+	return err
+}
+
+func (r *EtcdRegistry) DeleteMachineMetadata(machID string, key string) error {
+	// Deleting a key sets its value to "" to allow for intelligent merging
+	// between the machine-defined metadata and the dynamic metadata.
+	// See mergeMetadata for more detail.
+	return r.SetMachineMetadata(machID, key, "")
+}
+
 func (r *EtcdRegistry) RemoveMachineState(machID string) error {
 	req := etcd.Delete{
 		Key: path.Join(r.keyPrefix, machinePrefix, machID, "object"),
@@ -104,3 +132,51 @@ func (r *EtcdRegistry) RemoveMachineState(machID string) error {
 	}
 	return err
 }
+
+// mergeMetadata merges the machine-set metadata with the dynamic metadata to better facilitate
+// machines leaving and rejoining a cluster.
+// Merging metadata uses the following rules:
+// - Any keys that are only in one collection are added as-is
+// - Any keys that exist in both, the dynamic value takes precence
+// - Any keys that have a zero-value string in the dynamic metadata are considered deleted
+//   and are not included in the final collection
+func mergeMetadata(machineMetadata, dynamicMetadata map[string]string) map[string]string {
+	if dynamicMetadata == nil {
+		return machineMetadata
+	}
+	finalMetadata := make(map[string]string, len(dynamicMetadata))
+	for k, v := range machineMetadata {
+		finalMetadata[k] = v
+	}
+	for k, v := range dynamicMetadata {
+		if v == "" {
+			delete(finalMetadata, k)
+		} else {
+			finalMetadata[k] = v
+		}
+	}
+	return finalMetadata
+}
+
+// readMachineState reads machine state from an etcd node
+func readMachineState(node *etcd.Node) (mach machine.MachineState, err error) {
+	var metadata map[string]string
+
+	for _, obj := range node.Nodes {
+		if strings.HasSuffix(obj.Key, "/object") {
+			err = unmarshal(obj.Value, &mach)
+			if err != nil {
+				return
+			}
+		} else if strings.HasSuffix(obj.Key, "/metadata") {
+			// Load metadata into a separate map to avoid stepping on it when deserializing the object key
+			metadata = make(map[string]string, len(obj.Nodes))
+			for _, mdnode := range obj.Nodes {
+				metadata[path.Base(mdnode.Key)] = mdnode.Value
+			}
+		}
+	}
+
+	mach.Metadata = mergeMetadata(mach.Metadata, metadata)
+	return
+}