Reformatted documentation and moved migration guide towards bottom
diff --git a/README.md b/README.md
index 983013d..873887f 100644
--- a/README.md
+++ b/README.md
@@ -9,31 +9,34 @@
Based on the old Cloudstack provider in Kubernetes that will be removed soon.
-## Migration
+## Deployment
-There are several notable differences to the old Kubernetes CloudStack cloud provider that need to be taken into
-account when migrating to the standalone controller.
+### Kubernetes
-### Load Balancer
+Prebuilt containers are posted on [Docker Hub](https://hub.docker.com/r/swisstxt/cloudstack-cloud-controller-manager).
-Load balancer rule names now include the protocol in addition to the LB name and service port.
-This was added to distinguish tcp, udp and tcp-proxy services operating on the same port.
-Without this change, it would not be possible to map a service that runs on both TCP and UDP port 8000, for example.
+The cloud controller is intended to be deployed as a daemon set, with on instance running on each node.
-:warning: **If you have existing rules, remove them before the migration, and add them back afterwards.**
+Please see [deployment.yaml](/deployment.yaml) for an example deployment.
-If you don't do this, you will end up with duplicate rules for the same service, which won't work.
+The comments explain how to configure Cloudstack API access.
+You need an access token that is allowed to fetch VM information and deploy load balancers in the project or domain where the nodes reside.
-### Metadata
+### Protocols
-When kubelet still contained cloud provider code, node metadata was fetched from the DHCP
-server running on the Virtual Router.
+This CCM supports TCP, UDP and [TCP-Proxy](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) LoadBalancer deployments.
-This is no longer possible with the standalone cloud controller, so all metadata now comes from
-the Cloudstack API. Some metadata may be missing or wrong, please file bugs when this happens to you.
+For UDP and Proxy Protocol support, CloudStack 4.6 or later is required.
+
+Since kube-proxy does not support the Proxy Protocol or UDP, you should connect this directly to pods, for example by deploying a DaemonSet and setting `hostNetwork: true`.
+The service running in the pod must support the protocol.
+
+See [service.yaml](/service.yaml) for an example Service deployment and part of a suitable configuration for an ingress controller.
### Node Labels
+:warning: **The node name must match the host name, so the controller can fetch and assign metadata from CloudStack.**
+
It is recommended to launch `kubelet` with the following parameter:
```
@@ -54,7 +57,30 @@
kubectl taint nodes <my-node-without-labels> node.cloudprovider.kubernetes.io/uninitialized=true:NoSchedule
```
-## Build
+## Migration Guide
+
+There are several notable differences to the old Kubernetes CloudStack cloud provider that need to be taken into
+account when migrating from the old cloud provider to the standalone controller.
+
+### Load Balancer
+
+Load balancer rule names now include the protocol in addition to the LB name and service port.
+This was added to distinguish tcp, udp and tcp-proxy services operating on the same port.
+Without this change, it would not be possible to map a service that runs on both TCP and UDP port 8000, for example.
+
+:warning: **If you have existing rules, remove them before the migration, and add them back afterwards.**
+
+If you don't do this, you will end up with duplicate rules for the same service, which won't work.
+
+### Metadata
+
+Since the controller is now intended to be run inside a pod and not on the node, it will not be able to fetch metadata from the Virtual Router's DHCP server.
+
+Instead, it first obtains the name of the node from Kubernetes, then fetches information from the CloudStack API.
+
+## Development
+
+### Building
All dependencies are vendored.
You need GNU make, git and Go 1.11 to build cloudstack-ccm.
@@ -74,28 +100,7 @@
docker build . -t swisstxt/cloudstack-cloud-controller-manager:latest
```
-## Use
-
-Prebuilt containers are posted on [Docker Hub](https://hub.docker.com/r/swisstxt/cloudstack-cloud-controller-manager).
-
-### Kubernetes
-
-If you intend to deploy the CCM in a Kubernetes cluster, please see [deployment.yaml](/deployment.yaml) for an example configuration. The comments explain how to configure Cloudstack API access.
-
-### Protocols
-
-This CCM supports TCP, UDP and [TCP-Proxy](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt)
-LoadBalancer deployments.
-
-For UDP and Proxy Protocol support, CloudStack 4.6 or later is required.
-
-Since kube-proxy does not support the Proxy Protocol or UDP, you should connect this
-directly to containers, for example by deploying a DaemonSet and setting `hostNetwork: true`.
-
-See [service.yaml](/service.yaml) for an example Service deployment and part
-of a suitable configuration for an ingress controller.
-
-### Development
+### Testing
You need a local instance of the CloudStack Management Server or a 'real' one to connect to.
The CCM supports the same cloudstack.ini configuration file format used by [the cs tool](https://github.com/exoscale/cs),
