docs: Update platform documentation

- Prefix platform documentation with 'platform-'
- Add/Correct links from top-level README.md
- Tweak the Azure documentation
- Move the vsudd README to platform-hyperkit.md
- Add a dummy document for qemu/kvm

Signed-off-by: Rolf Neugebauer <rolf.neugebauer@docker.com>

README.md

@@ -40,9 +40,11 @@ This will use a suitable backend for your platform or you can choose one, for ex
 See `linuxkit run --help`.
 
 Additional, platform specific information is available for:
-- [macOS](docs/mac.md)
-- [Google Cloud](docs/gcp.md)
-- [Azure](docs/azure.md)
+- [macOS/HyperKit](docs/platform-hyperkit.md)
+- [qemu/kvm](docs/platform-qemu.md)
+- [Amazon Web Services](docs/platform-aws.md)
+- [Google Cloud](docs/platform-gcp.md)
+- [Microsoft Azure](docs/platform-azure.md)
 
 We'll add more detailed docs for other platforms in the future.
 

docs/platform-aws.md

@@ -17,7 +17,7 @@ Finally, you must set the `AWS_REGION` environment variable as this is used by t
 export AWS_REGION=eu-west-1
 ```
 
-## Build an image
+## Build an image
 
 AWS requires a `RAW` image. To create one:
 

docs/platform-azure.md

@@ -1,51 +1,41 @@
 # Using LinuxKit on Azure
 
-This is a quick guide to running VMs based on LinuxKit images on Azure. Please note that since we are building very minimal operating systems, without adding the [Azure Linux Agent](https://github.com/Azure/WALinuxAgent), after creating the VM, the portal will report that the creation failed. If you created the VHD properly, you will still be able to SSH into the machine.
+This is a quick guide to running VMs based on LinuxKit images on Azure. Please note that these images currently do not include the [Azure Linux Agent](https://github.com/Azure/WALinuxAgent). As a result, after creating the VM, the portal will report that the creation failed. If you created the VHD properly, you will still be able to SSH into the machine.
 
 When running `linuxkit run azure`, the image you created using `moby build` will be uploaded to Azure in a resource group, and a VM will be created, along with the necessary resources (virtual network, subnet, storage account, network security group, public IP address).
 
 Since Azure does not offer access to the serial output of the VM, you need to have SSH access to the machine in order to attach to it. Please see the example below.
 
+
 ## Setup
 
-First of all, you need to authenticate LinuxKit with your Azure subscription. For this, you need to set the following environment variables in your bash sesssion:
+You need to authenticate LinuxKit with your Azure subscription. You need to set up the following environment variables:
 
-```
-// AZURE_TENANT_ID: contains your Azure Active Directory tenant ID or domain
-// AZURE_SUBSCRIPTION_ID: contains your Azure Subscription ID
-// AZURE_CLIENT_ID: contains your Azure Active Directory Application Client ID
-// AZURE_CLIENT_SECRET: contains your Azure Active Directory Application Secret
-```
-
-- you can [get the Azure tenant ID following the instructions here](https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-create-service-principal-portal#get-tenant-id)
-- to get the subscription ID, log in to the Azure portal, then go to Subscriptions
-- then, you need to [create an Azure Active Directory application and retrieve its ID and secret following the instructions here](https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-create-service-principal-portal#create-an-azure-active-directory-application)
+- `AZURE_TENANT_ID`: The Azure Active Directory tenant ID or domain. You can retrieve this information following [these instructions](https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-create-service-principal-portal#get-tenant-id).
+- `AZURE_SUBSCRIPTION_ID`: Your Azure Subscription ID. To retrieve it, log in to the Azure portal. The create a [create an Azure Active Directory application and retrieve
+its ID and secret following the instructions
+here](https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-create-service-principal-portal#create-an-azure-active-directory-application).
+- `AZURE_CLIENT_ID`: Your Azure Active Directory Application Client ID.
+- `AZURE_CLIENT_SECRET`: Your Azure Active Directory Application Secret
 
 [Additional information and required steps for creating a service principal for Azure can be found here](https://docs.docker.com/docker-for-azure/#configuration)
 
-Then, set the environment variables:
-
-```
-export AZURE_TENANT_ID=<your_tenant_id>
-export AZURE_SUBSCRIPTION_ID=<your_subscription_id>
-export AZURE_CLIENT_ID=<your_client_id>
-export AZURE_CLIENT_SECRET=<your_client_secret>
-```
-
-Now you should be ready to deploy resources using the LinuxKit command line.
 
 ## Build an image
 
 Create a new `azure.yml` file [based on the Azure example](../examples/azure.yml), generate a new SSH key and add it in the `yml`, then `moby build -output vhd azure.yml`.
 
 
-This will output a `azure.vhd` image that you will deploy on Azure using `linuxkit`.
+This will output a `azure.vhd` image.
+
 
 ## Create a new Azure VM based on the image
 
-Now that we have a `azure.vhd` image, we can deploy a new VM to Azure based on it.
+To deploy the `azure.vhd` image on Azure, invoke the following command:
 
-`linuxkit run azure --resourceGroupName <resource-goup-name> --accountName <storageaccountname> --location westeurope <path-to-your-azure.vhd>`
+```
+linuxkit run azure --resourceGroupName <resource-goup-name> --accountName <storageaccountname> --location westeurope <path-to-your-azure.vhd>
+```
 
 Sample output of the command:
 
@@ -80,6 +70,7 @@ After around 50 seconds, try to SSH into the machine (if you added the SSHD serv
 
 ## Limitations, workarounds and work in progress
 
-- as stated before, since this image does not contain the Azure Linux Agent, the Azure Portal will report the creation as failed
-- the main workaround is the way the VHD is uploaded, specifically by using a Docker container based on [Azure VHD Utils](https://github.com/Microsoft/azure-vhd-utils). This is mainly because the tool manages fast and efficient uploads, leveraging parallelism
-- there is work in progress to specify what ports to open on the VM (more specifically on a network security group)
+- Since the image currently does not contain the Azure Linux Agent, the Azure Portal will report the creation as failed.
+- The main workaround is the way the VHD is uploaded, specifically by using a Docker container based on [Azure VHD Utils](https://github.com/Microsoft/azure-vhd-utils). This is mainly because the tool manages fast and efficient uploads, leveraging parallelism
+- There is work in progress to specify what ports to open on the VM (more specifically on a network security group)
+- The [metadata package](../pkg/metadata) does not yet support the Azure metadata.

docs/platform-hyperkit.md

@@ -65,3 +65,28 @@ and then:
 docker build -t socat .
 docker run --rm -t -d -p 6379:6379 socat tcp-listen:6379,reuseaddr,fork tcp:<IP address of VM>:6379
 ```
+
+## `vsudd` unix domain socket forwarding
+
+The [`vsudd` package](/pkg/vsudd) provides a daemon that exposes unix
+domain socket inside the VM to the host via virtio or Hyper-V sockets.
+With HyperKit, the virtio sockets can be exposed as unix domain
+sockets on the host, enabling access to other daemons, like
+`containerd` and `dockerd`, from the host.  An example configuration
+file is available in [examples/vsudd.yml](/examples/vsudd.yml).
+
+After building the example, run it with `linuxkit run hyperkit
+-vsock-ports 2374 vsudd`. This will create a unix domain socket in the state
+directory that maps to the `containerd` control socket. The socket is called
+`guest.00000946`.
+
+If you install the `ctr` tool on the host you should be able to access the
+`containerd` running in the VM:
+
+```
+$ go get -u -ldflags -s github.com/containerd/containerd/cmd/ctr
+...
+$ ctr -a vsudd-state/guest.00000946 list
+ID        IMAGE     PID       STATUS
+vsudd               466       RUNNING
+```

docs/platform-qemu.md

@@ -0,0 +1,7 @@
+# LinuxKit and qemu
+
+TBD
+
+## Networking
+
+TBD

pkg/vsudd/README.md

@@ -1,23 +0,0 @@
-#### Vsudd
-
-Vsudd is a daemon that forwards unix domain socket traffic from the host to the
-guest VM via VSOCK. It can be used to control other daemons, like `containerd`
-and `dockerd`, from the host.  An example configuration file is available in
-[examples/vsudd.yml](/examples/vsudd.yml).
-
-After building the example, run the example with `linuxkit run hyperkit
--vsock-ports 2374 vsudd`. This will create a unix domain socket in the state
-directory that map to the `containerd` control socket. The socket is called
-`guest.00000946`.
-
-If you install the `ctr` tool on the host you should be able to access the
-`containerd` running in the VM:
-
-```
-$ go get -u -ldflags -s github.com/containerd/containerd/cmd/ctr
-...
-$ ctr -a vsudd-state/guest.00000946 list
-ID        IMAGE     PID       STATUS
-vsudd               466       RUNNING
-```
-