From 61b72ba14a6d1f2d793403f2e3aee94fdc094366 Mon Sep 17 00:00:00 2001
From: Justin Chadwell <me@jedevc.com>
Date: Tue, 10 May 2022 11:09:35 +0100
Subject: [PATCH] Fix feedback for remote driver guide

Signed-off-by: Justin Chadwell <me@jedevc.com>
---
 docs/guides/remote-builder.md | 30 ++++++++++++++++++------------
 1 file changed, 18 insertions(+), 12 deletions(-)

diff --git a/docs/guides/remote-builder.md b/docs/guides/remote-builder.md
index 3e3893e897a4..5700a2352aa7 100644
--- a/docs/guides/remote-builder.md
+++ b/docs/guides/remote-builder.md
@@ -30,11 +30,16 @@ Then launch an instance of buildkitd:
 $ sudo ./buildkitd --group $(id -gn) --addr unix://$HOME/buildkitd.sock
 ```
 
-This will setup a socket in your home directory that you have read-write
-permissions to. 
+In this example, we run buildkitd as the root user, however, in the real world,
+you should prefer [rootless mode](https://github.com/moby/buildkit/blob/master/docs/rootless.md)
+where possible. You may also choose to configure [systemd to start and manage buildkit](https://github.com/moby/buildkit/tree/master/examples/systemd)
+for you.
+
+You should now have a unix socket accessible to your user, that is available to
+connect to:
 
 ```console
-$ ls -lh
+$ ls -lh /home/user/buildkitd.sock
 srw-rw---- 1 root user 0 May  5 11:04 /home/user/buildkitd.sock
 ```
 
@@ -73,11 +78,12 @@ driver, to load the build result into the docker daemon)
 In this scenario, we'll create a similar setup to the `docker-container`
 driver, by manually booting a buildkit docker container and connecting to it
 using the buildx remote driver. In most cases you'd probably just use the
-`docker-container` driver directly, but imagine that for some reason you want
-to manually manage the container instead of having buildx manage it for you.
+`docker-container` driver that connects to buildkit through the Docker daemon,
+but in this case we manually create a container and access it via it's exposed
+port.
 
 First, we need to generate certificates for buildkit - you can use the 
-[create-certs.sh](https://github.com/moby/buildkit/blob/master/examples/kubernetes/create-certs.sh)
+[create-certs.sh](https://github.com/moby/buildkit/v0.10.3/master/examples/kubernetes/create-certs.sh)
 script as a starting point. Note, that while it is *possible* to expose
 buildkit over TCP without using TLS, it is **not recommended**, since this will
 allow arbitrary access to buildkit without credentials.
@@ -89,12 +95,12 @@ $ docker run -d --rm \
   --name=remote-buildkitd \
   --privileged \
   -p 1234:1234 \
-  -v $PWD/.certs:/certs \
+  -v $PWD/.certs:/etc/buildkit/certs \
   moby/buildkit:latest \
   --addr tcp://0.0.0.0:1234 \
-  --tlscacert /certs/ca.pem \
-  --tlscert /certs/daemon-cert.pem \
-  --tlskey /certs/daemon-key.pem
+  --tlscacert /etc/buildkit/certs/ca.pem \
+  --tlscert /etc/buildkit/certs/daemon-cert.pem \
+  --tlskey /etc/buildkit/certs/daemon-key.pem
 ```
 
 The above command starts a buildkit container and exposes the daemon's port
@@ -104,7 +110,7 @@ We can now connect to this running container using buildx:
 
 ```console
 $ docker buildx create \
-  --name remote-kubernetes \
+  --name remote-container \
   --driver remote \
   --driver-opt cacert=.certs/ca.pem,cert=.certs/client-cert.pem,key=.certs/client-key.pem,servername=... \
   tcp://buildkitd.default.svc:1234
@@ -122,7 +128,7 @@ between them.
 Firstly, we can create a kubernetes deployment of buildkitd, as per the
 instructions [here](https://github.com/moby/buildkit/tree/master/examples/kubernetes).
 Following the guide, we setup certificates for the buildkit daemon and client
-(as above using [create-certs.sh](https://github.com/moby/buildkit/blob/master/examples/kubernetes/create-certs.sh))
+(as above using [create-certs.sh](https://github.com/moby/buildkit/blob/v0.10.3/examples/kubernetes/create-certs.sh))
 and create a `Deployment` of buildkit pods with a service that connects to
 them.