From db6d3d7ed297f8ed8802eeaa92f826bd9f83daee Mon Sep 17 00:00:00 2001 From: Rolf Neugebauer Date: Tue, 25 Apr 2017 12:00:26 +0100 Subject: [PATCH] docs: Consolidate mac tips & tricks in ./docs/mac.md We had serveral files with instructions, in particular for networking, for macOS/Docker for Mac. Let's have just one place. Signed-off-by: Rolf Neugebauer --- README.md | 6 ++- docs/mac.md | 55 ++++++++++++++++++++++ examples/sshd.md | 41 ---------------- projects/demo/dockerfiles/Dockerfile.socat | 8 ---- 4 files changed, 59 insertions(+), 51 deletions(-) create mode 100644 docs/mac.md delete mode 100644 examples/sshd.md delete mode 100644 projects/demo/dockerfiles/Dockerfile.socat diff --git a/README.md b/README.md index 0fccdc1ea..70e211e8a 100644 --- a/README.md +++ b/README.md @@ -41,9 +41,11 @@ See `linuxkit run --help`. `make test` or `make test-hyperkit` will run the test suite -There are also docs for booting on [Google Cloud](docs/gcp.md). +Additional, platform specific information is available for: +- [macOS](docs/mac.md) +- [Google Cloud](docs/gcp.md) -More detailed docs will be available shortly, for running both single hosts and clusters. +We'll add more detailed docs for other platforms in the future. ## Building your own customised image diff --git a/docs/mac.md b/docs/mac.md new file mode 100644 index 000000000..a33555768 --- /dev/null +++ b/docs/mac.md @@ -0,0 +1,55 @@ +# LinuxKit on a Mac + +We recommend using LinuxKit in conjunction with +[Docker for Mac](https://docs.docker.com/docker-for-mac/install/). For +the time being it's best to be on the latest edge release. `linuxkit +run` uses [HyperKit](https://github.com/moby/hyperkit) and +[VPNKit](https://github.com/moby/vpnkit) and the edge release ships +with updated versions of both. + +## Networking + +By default, `linuxkit run` creates a VM with a single network +interface which, logically, is attached to a L2 bridge, which also has +the VM used by Docker for Mac attached to it. This means that the LinuxKit +VMs can be accessed from containers running on Docker for Mac. + +The LinuxKit VMs have IP addresses on the `192.168.65.0/24` subnet +assigned by a DHCP server part of VPNKit. `192.168.65.1` is reserved +for VPNKit as the default gateway and `192.168.65.2` is used by the +Docker for Mac VM. + +By default, LinuxKit VMs get incrementally increasing IP addresses, but you can assign a fixed IP address with `linuxkit run -ip`. It's best to choose an IP address from the DHCP address range above, but care must be taking to avoid clashes of IP address. + +### Accessing services + +The simplest way to access networking services exposed by a LinuxKit VM is to use a Docker for Mac container. + +For example, to access an ssh server in a LinuxKit VM, create a ssh client container from: +``` +FROM alpine:edge +RUN apk add --no-cache openssh-client +``` +and then run +``` +docker build -t ssh . +docker run --rm -ti -v ~/.ssh:/root/.ssh ssh ssh +``` + + +### Forwarding ports to the host + +While VPNKit has the general tooling to expose any VMs port on the +localhost (just like it does with containers in Docker for Mac), we +are unlikely to expose this as a general feature in `linuxkit run` as +it is very specific to the macOS. However, you can use a `socat` container to proxy between LinuxKit VMs ports and localhost. For example, to expose the redis port from the [RedisOS example](../examples/redis-os.yml), use this Dockerfile: +``` +FROM alpine:edge +RUN apk add --no-cache socat +ENTRYPOINT [ "/usr/bin/socat" ] +``` +and then: +``` +docker build -t socat . +docker run --rm -t -d -p 6379:6379 socat tcp-listen:6379,reuseaddr,fork tcp::6379 +``` diff --git a/examples/sshd.md b/examples/sshd.md deleted file mode 100644 index 24dd144e2..000000000 --- a/examples/sshd.md +++ /dev/null @@ -1,41 +0,0 @@ -# SSH example - -The LinuxKit [sshd example](./sshd.yml) defines an image running a SSH -daemon. You can build it as usual (though you should add your public -key to the `contents` field in the `files` section). - -On some platforms you can then just ssh into the system once it is running, but on some platforms additional steps are required. - - -## HyperKit/Docker for Mac - -If you use the HyperKit backend with Docker for Mac, the VM created with `moby run ...` is placed on the same network as the Docker for Mac VM (via VPNKit). -The VMs network is not directly accessible from the host, but is accessible from within containers run with Docker for Mac. - -So, to ssh into the VM created via `moby run sshd` it's best to do this via a container from within a container. - -You can build a small container with an ssh client with this Dockerfile: -``` -FROM alpine:edge -RUN apk add --no-cache openssh-client -``` -Then: -``` -docker build -t ssh . -``` - -And now: -``` -docker run --rm -ti -v ~/.ssh:/root/.ssh ssh ssh -``` - -The HyperKit backend for `moby run` also allows you to set the IP address of the VM, like: -``` -moby run -ip 192.168.65.101 sshd -``` - - -## Qemu/Linux - -TBD - diff --git a/projects/demo/dockerfiles/Dockerfile.socat b/projects/demo/dockerfiles/Dockerfile.socat deleted file mode 100644 index 8f1c78731..000000000 --- a/projects/demo/dockerfiles/Dockerfile.socat +++ /dev/null @@ -1,8 +0,0 @@ -# A dockerfile to build a socat container -# -# It sets the environment to talk to the local cluster -FROM alpine:edge - -RUN apk add --no-cache socat - -ENTRYPOINT [ "/usr/bin/socat" ]