Putting aside the oft-quoted figures about growth, and number of images downloaded, 2017 was quite a year for Docker.  It culminated in the DockerCon Europe announcement in Copenhagen that the platform would natively support Kubernetes, and we are now starting to see the fruits of this shift in the Docker support for Kubernetes Beta.  Prior to that, however, a couple of 'multi-centric' features were released that started to lower the already negligible barrier to entry & transform how people use Docker.

Multi-Stage Builds

This was the earlier of the two features of interest. It started to emerge during March ahead of general availability during June.  Not wishing to cover this in any great detail here, this change replaced the earlier 'Builder Pattern' which existed in order to facilitate production of smaller images for particular types of applications.  For a first-class discussion of how multi-stage build superseded the builder pattern head over to Alex Ellis' blog.

Multi-Architecture Images

During September Docker announced multi-platform support of their official images and as someone who runs Docker on ARM32v6, ARM32v7 and x86_64 this news was of particular interest.

Why?

Quite simply, it removes complexity.  In the pre-multi-arch world it would typically be the case that multiple Docker hub repo's would need to be visited, namespaces determined, or tags forensically interrogated in order to create bespoke Dockerfiles for each platform being targeted by the application.  For example, consider a golang application being developed to run on each of the hardware platforms described earlier; 3 separate Dockerfiles could be required:

• Dockerfile

FROM golang:1.8.5
....

• Dockerfile.arm32v6

FROM arm32v6/golang:1.8.5
...

• Dockerfile.arm32v7

FROM arm32v7/golang:1.8.5
...

The remainder of the Dockerfiles' content would likely remain the same, and users would need to invoke the build command against the Dockerfile relevant to their environment.

• Dockerfile: docker build .
• Dockerfile.arm32v6 docker build . -f Dockerfile.arm32v6
• Dockerfile.arm32v7 docker build . -f Dockerfile.arm32v7

Note the -f option which needs to be supplied if a non-standard Dockerfile name is used.

With the multi-arch approach the responsibility for finding the appropriate base image has been delegated to the docker client, which greatly improves the UX.  Revisiting the earlier example the three Dockerfiles can be condensed into one:

• Dockerfile

FROM golang:1.8.5
....

Consequently the build command is the same regardless of the users' environment, simply: docker build .

How?

Something called manifest lists make this possible.  In (much) earlier versions of Docker the client/server conversation resulting from an invocation of docker pull / docker run would be very brief.  Latterly an intermediate step has been introduced to the conversation, during which the client can, where available, receive a list of supported platforms for the requested image.  The client subsequently requests an image appropriate for the hardware platform upon which it's running.

In order to get a taste of how these manifest lists look, try exploring the work that Docker Captain Phil Estes has done in this area and in particular his mquery tool.  As you might expect this has also been made available as a docker image:

$ docker run mplatform/mquery <imageName>
  Image: <imageName>
   * Manifest List: Yes
   * Supported platforms:
     - linux/amd64
     - linux/arm/v7
     - linux/386
     - linux/ppc64le
     - linux/s390x
     - windows/amd64:10.0.14393.2007
     - windows/amd64:10.0.16299.192

Practical Implications

Looking beyond the build phase. Prior to multi-arch, with applications where stacks might be in use, standard practice would be to assemble separate compose files for each supported hardware platform.  For example, a docker-compose.yml for use on x86 with the relevant x86 images specified, and a docker-compose.armhf.yml which would target 32-bit ARM hardware, and so would detail the respective ARM images.  With multi-arch images, the same stack can be deployed on each supported hardware platform from a single compose file; the client will invisibly select the relevant image during deployment.

Create your own Manifest List / Multi-Arch

At the time of writing, the CLI feature to create  manifest lists is still experimental, so the edge channel version of Docker is required. With 18.02 installed ensure that the following is added to the config.json file

{
"experimental":"enabled"
}

That will enable access to the command in the CLI:

$ docker manifest

Usage:  docker manifest COMMAND

Manage Docker image manifests and manifest lists

Options:

Commands:
  annotate    Add additional information to a local image manifest
  create      Create a local manifest list for annotating and pushing to a registry
  inspect     Display an image manifest, or manifest list
  push        Push a manifest list to a repository

Run 'docker manifest COMMAND --help' for more information on a command.

Create would seem like the obvious place to start.  The first argument specifies the name of the manifest - effectively the image name that will be used to access the hardware specific images - and the subsequent arguments specify those images.  Here a manifest containing two images is created, x86 linux image and an ARM32v7 equivalent.

$ docker manifest create rgee0/of-mquery:1.0 \
    rgee0/mquery-x86:1.0 \ 
      rgee0/mquery-arm32v7:1.0

Created manifest list docker.io/rgee0/of-mquery:1.0

Once created, the manifest can be annotated to add additional information.  It's this information that is extracted by the docker run mplatform/mquery command demonstrated above.

$ docker manifest annotate rgee0/of-mquery:1.0 \
    rgee0/mquery-x86:1.0 --os linux --arch amd64

$ docker manifest annotate rgee0/of-mquery:1.0 \
    rgee0/mquery-arm32v7:1.0 --os linux --arch arm --variant v7

The OS and arch combinations should align with those available from the golang environment options. Notice the --variant option supplied to the ARM annotation; as an example, this is useful in situations where distinct images are available for each of ARM32v6 & ARM32v7.

The final step, which should be familiar from working with images, is to push the manifest:

$ docker manifest push rgee0/of-mquery:1.0

To review the changes, the CLI makes an inspect option available, and of course the earlier mquery command could be provided with the manifest name chosen during create:

$ docker run mplatform/mquery rgee0/of-mquery:1.0
  Image: rgee0/of-mquery:1.0
   * Manifest List: Yes
   * Supported platforms:
     - linux/arm/v7
     - linux/amd64

Now, running docker pull rgee0/of-mquery:1.0 on a mac, or a Raspberry Pi 3 will see the relevant hardware specific image pulled from Docker hub.

mquery as a function

Why not try mquery as a function?  By adapting Phil's code very slightly it's possible to make it compatible with the OpenFaaS framework and present mquery as a serverless function.  OpenFaaS functions take input via stdin so a small change to swap out os.Args and the addition of a helper function to tidy up stdin prepares the program for use with OpenFaaS.  Finally, the addition of multi-stage Dockerfiles produce a small function image ready for deployment.  Find the OpenFaaS-ready code over on github.

Since the images were built and pushed during the manifest creation section, those with access to an OpenFaaS instance can dive straight in to deploying the function.  Those who haven't, head over to the guides and work through the deployment guide for your preferred orchestrator.

Deployment

One of the core tenets pervading OpenFaaS is that of choice, and deployment activity is no different. Here are two of the deployment options.

CLI

Grab the CLI and use deploy against a yaml file:

provider:
  name: faas
  gateway: http://127.0.0.1:8080

functions:
  mquery:
    lang: Dockerfile
    handler: ./mquery
    image: rgee0/of-mquery:1.0

Then run the deploy command:

$ faas-cli deploy -f ./mquery.yml

or, more succinctly, name the yaml file stack.yml and use the CLI alias:

$ faas deploy

The function can then be invoked via the CLI:

$ echo 'rgee0/of-mquery:1.0' | faas invoke mquery

  Manifest List: Yes 
  Supported platforms:
   - linux/arm/v7
   - linux/amd64

Function Store

By far the easiest way to deploy to OpenFaaS is via the OpenFaaS Function Store. The Function Store is a community curated index of OpenFaaS functions and deployment is as simple as clicking through the desired function.
The function created through this article has been accepted into the OpenFaaS Function Store which means it can be used in just 2 clicks:

Once initialised the function can be invoked through the UI by adding an image name and tag (rgee0/of-mquery:1.0) into the request body and selecting invoke.

Credits

Title Photo by Anthony DELANOIX on Unsplash

In the previous article we looked at how I had become involved in an open source community project which centred around making available a Golang equivalent of Pimoroni's Python library.  In this post I wanted to demonstrate use of the Golang library by porting one of the Pimoroni examples.

Solid Colours

One of the simplest examples in the Python examples is solid_colours.py.  This example cycles the Blinkt through red, green and blue at predetermined intervals. Lets take a look.

Python

The python code to do this is really quite straight-forward, which makes it a really good example to start with if you're new to Golang. It allows you to focus on how to make Golang do the same without getting bogged down in complexity of the implementation.

while True:
    if step == 0:
        set_all(128,0,0)
    if step == 1:
        set_all(0,128,0)
    if step == 2:
        set_all(0,0,128)

    step+=1
    step%=3
    show()
    time.sleep(0.5)

A simple loop incrementing a counter which uses a modulo function to choose which colour to display.  A half second delay is placed within the loop so that we give our eyes long enough to perceive the change of colour.

Golang

So, we've seen our starting point, but the reason we're here is that we want to build this out in Golang.  Lets start with the scaffolding - the bits we'll need regardless of the example:

package main

import . "github.com/alexellis/blinkt_go"

Nice and simple, we declare this package as main and import the Raspberry Pi Golang library that we looked at in the previous article.  You'll notice that we are using dot notation in the import - this is not ideal, and is only really advised for testing code.

As this example is of limited complexity there are no functions required outside of main, so lets head straight into the body of the program.  First we need to construct a new Blinkt object.  Every program will need one of these as its the means by which you access the functions to manipulate the hardware.

blinkt := NewBlinkt()

In the current version of the library initialising Blinkt! with a brightness value is optional. If we wanted to do this we would pass a value between 0.0 and 1.0 into the NewBlinkt() method:

initialBrightness := 0.5
blinkt := NewBlinkt(initialBrightness)

Next we need to think about the type of program we are creating, is it one that we wish to run and exit leaving the Blinkt! set to a desired state, or do we want to Blinkt! to reset on exit?  Well, this particular example runs an infinite loop, which we'll have to break using CTRL+C, and at the point in which it breaks we want the Blinkt! to go dark.  To do this we need to set SetClearOnExit() to true.

blinkt.SetClearOnExit(true)
blinkt.Setup()
Delay(100)

Once we've set the Blinkt initialisation options we can call Setup() to initialise GPIO via the lower level WiringPi library.  There's a little delay in there to allow time for Setup() to complete.

Lights On

Right, so we've successfully initialised a Blinkt object in Golang but nothing will happen until we tell the pixels what we want them to do.  this is where the program starts to look similar to the earlier Python version.

step := 0

for {

	step = step % 3
	switch step {
	case 0:
		blinkt.SetAll(128, 0, 0)
	case 1:
		blinkt.SetAll(0, 128, 0)
	case 2:
		blinkt.SetAll(0, 0, 128)
	}

	step++
	blinkt.Show()
	Delay(500)

	}
}

Here we can see the SetAll() function that I talked about in the previous article being put to use.  We have created three states, one for Red, one for Green and one for Blue, and we use an incremental counter with modulo arithmetic to carry us from state to state with a half second delay between states.  It's important that Show() is called to apply the values set in SetAll() to the hardware.

Bringing it Together

We've now got a viable Golang program through which was can manipulate the Blinkt! hardware via GPIO.

package main

import . "github.com/alexellis/blinkt_go"

func main() {

	brightness := 0.5
	blinkt := NewBlinkt(brightness)

	blinkt.SetClearOnExit(true)
	blinkt.Setup()
	Delay(100)

	step := 0

	for {

		step = step % 3
		switch step {
		case 0:
			blinkt.SetAll(128, 0, 0)
		case 1:
			blinkt.SetAll(0, 128, 0)
		case 2:
			blinkt.SetAll(0, 0, 128)
		}

		step++
		blinkt.Show()
		Delay(500)

	}

}

Other methods

To help you achieve different an more impressive effects the library makes a number of of other methods available:

blinkt.Clear() - Pretty self-explanitory this one.  It will set all the pixels to 0

blinkt.SetAll(r int, g int, b int) - As we've already seen this will set all the pixels to the RGB values passed in to the function.

blinkt.SetBrightness(brightness float64) - One of the newer functions this sets the brightness of all the pixels enabling dynamic manipulation during runtime.

blinkt.SetPixel(p int, r int, g int, b int) - Set the colour value of a single pixel. The pixels are zero indexed.

blinkt.SetPixelBrightness(p int, brightness float64) - Set the brightness of a single pixel. The pixels are zero indexed.

The nice feature here is that the final four each return a Blinkt object, which means we can chain the methods to set the colours and brightness in one hit.  We could even add Show to the end:

switch step {
	case 0:
		blinkt.SetAll(128, 0, 0).SetBrightness(0.5)
	case 1:	
		blinkt.SetBrightness(0.1).SetAll(0, 128, 0)
	case 2:
		blinkt.SetAll(0, 0, 128).SetBrightness(0.9).Show()
		}

Through this more granular control we are able to create all manner of intricate effects.  Here's an example of blinkt.SetAll(128, 0, 0).SetBrightness() looping through different brightness values:

It's alive! Needs cleaning up but well on my way to fixing brightness @alexellisuk #blinkt #raspberrypi #golang pic.twitter.com/3MyF63Bz3e— Richard Gee (@rgee0) March 5, 2017

Docker

Now we've written our program to drive our Blinkt! why not make future invocations easy for ourselves by building a Docker image which we can then run as a container?  We can then push the image up to the Docker hub, making it available to pull down and run on any device where Docker is available to us.  The really nice part here is that Docker now supports multistage builds so with a little thought we can create smaller images containing only what we need at run time - the build stage components can be discarded post-build.  For more on multistage builds see Docker Captain Alex Ellis' excellent article - so informative was this article that Docker use it within their documentation.

FROM resin/rpi-raspbian AS buildpart

RUN apt-get update && \
    apt-get install -qy build-essential wiringpi git curl ca-certificates && \
    curl -sSLO https://storage.googleapis.com/golang/go1.7.5.linux-armv6l.tar.gz && \
	mkdir -p /usr/local/go && \
	tar -xvf go1.7.5.linux-armv6l.tar.gz -C /usr/local/go/ --strip-components=1

ENV PATH=$PATH:/usr/local/go/bin/
ENV GOPATH=/go/

RUN mkdir -p /go/src/github.com/rgee0/blinkt_go_examples/app
WORKDIR /go/src/github.com/rgee0/blinkt_go_examples/app

COPY app.go	.
RUN go get -d -v
RUN go build -o ./app

########End of build part########

FROM resin/rpi-raspbian 
RUN apt-get update &&  apt-get install -qy wiringpi --no-install-recommends && rm -rf /var/lib/apt/lists
COPY --from=buildpart /go/src/github.com/rgee0/blinkt_go_examples/app/app /
CMD ["./app"] 

We can then build this using:

docker build --tag rgee0/rpi_blinkt_go:solid_colours . 

The result will be a Docker image of 129MB, which is over 400MB smaller than the 550MB image we would typically have seen prior to multistage builds being supported.  Much smaller then for when we want to push the image up to the Docker hub:

docker push rgee0/rpi_blinkt_go:solid_colours

All that remains is to try running it.  As we've already seen solid_colours lets run random_blink instead:

docker run -ti --privileged rgee0/rpi_blinkt_go:random_blink

The Blinkt! by Pimoroni is a relatively inexpensive 8 LED display which gently introduces GPIO programming concepts.  Pimoroni provide their own library and examples based on Python.  There are various library ports available on github and this article will focus on the Golang library created by Alex Ellis.

As Alex's Blinkt! go examples repo welcomes pull requests I thought it an ideal opportunity to get hands on with Golang and port some of the Pimoroni Python examples. Ultimately this led to the base library also being enhanced, bringing it close to the API offered by the Pimoroni Python Library.

Why?

The simple answer is that I wanted to get hands on with Golang and from my perspective porting existing code from one language to another offers a means by which to focus more on the target language syntax and semantics than the program's algorithm; this can often remain similar to the source program.

It has to be said that Alex was also extremely helpful in reviewing code and providing guidance.
He even blogged around one of the pull requests to demonstrate squashing and merging.

How?

Initially my approach was to use the library as was and start porting the simpler examples.  This to me was logical because using the library to build the examples meant my understanding of the library naturally increased.  By the time the features offered by the library were no longer sufficient to port the next example, my understanding of Golang and the library had increased enough for me to start making changes to the library. I took a bit of a leap here because the library repo wasn't explicit on whether PRs were welcome or not.

What changed?

New function

The very first change was to introduce a function to set all the pixels to the same values:

func (bl Blinkt) SetAll(r int, g int, b int) {
 	for i, _ := range bl.pixels {
 		bl.SetPixel(i, r, g, b)
 	}
 }

This had a couple of effects: not only would the public function be directly accessible from the examples, but existing library functions could be refactored to call this rather than employing their own loops to do the same.

Qualifiers

The next change was one that Alex suggested.  There was repetition in the examples around clearing the pixels when the program exited & introducing time delays during execution.  Given the repetition the obvious next step was to move these into the library and make them public.  I learnt a lot here about aliasing imports as the package was using dot notation on the single package it imported and we had reused the name of a function (Delay) used in a lower level package meaning leading to some odd behaviour.  For example:

import . "github.com/alexellis/rpi"

Meant that calls to exposed functions could be made without fully referencing the package:

func pulse(pulses int) {
 	DigitalWrite(GpioToPin(DAT), 0)
...
```
However, removing the dot meant that references to functions provided by that package had to be qualified:
``` 
import "github.com/alexellis/rpi"

func pulse(pulses int) {
 	rpi.DigitalWrite(rpi.GpioToPin(DAT), 0)
...
```

The final merge was by far the largest change. The handling of brightness in library had been static after being set during instantiation. This was by far the biggest limitation to completing some of the elaborate examples. 

####Variadics
There had always been an ambition to align more closely with the mode of operation of the Pimoroni library, and that meant changing the supplied brightness value from an `int` to a `float` between 0.0 and 1.0.  It also meant that we needed to mirror the availability of a default brightness value, which presented a challenge as Golang doesn't accommodate optional parameters.  The closest mechanism to achieve a similar effect is through the use of Variadic parameters and testing the argument for length:

```
func NewBlinkt(brightness ...float64) Blinkt {

	brightnessInt := defaultBrightnessInt

	if len(brightness) > 0 {
		brightnessInt = convertBrightnessToInt(brightness[0])
	}
...
```
The brightness parameter here is a slice of floats, so we interrogate the slice to determine a non-zero length and take the first value we find.  It's worth pointing out at this stage that the supplied value is tested for validity within the `convertBrightnessToInt` function.

####Chaining

This again extended my learning as my initial approach to implementation was to refactor the existing functions to allow for the additional brightness value to be passed.  However, discussions in the open with Alex led me towards method chaining.  This was a great idea as it would limit the amount of refactoring existing users would have to undertake whilst still making dynamic brightness available to them.  To achieve this the existing methods needed to be adapted to return a Blinkt object which would act as an input into the subsequently chained method.

The existing methods such as `SetPixel` were changed from:
```
func (bl *Blinkt) SetPixel(p int, r int, g int, b int) {
```
to
```
func (bl *Blinkt) SetPixel(p int, r int, g int, b int) *Blinkt {
```
This means that at the time of setting a pixel colour we can also set the brightness, thus:
```
blinkt.SetAll(128, 0, 0).SetBrightness(0.5)
```
Furthermore, SetBrightness also returns a Blinkt object, so the two methods are interchangable:
```
blinkt.SetBrightness(0.5).SetAll(128, 0, 0).SetBrightness(0.5)
```
Here I am celebrating initial success: 

<blockquote class="twitter-tweet" data-lang="en"><p lang="en" dir="ltr">It&#39;s alive! Needs cleaning up but well on my way to fixing brightness <a href="https://twitter.com/alexellisuk">@alexellisuk</a> <a href="https://twitter.com/hashtag/blinkt?src=hash">#blinkt</a> <a href="https://twitter.com/hashtag/raspberrypi?src=hash">#raspberrypi</a> <a href="https://twitter.com/hashtag/golang?src=hash">#golang</a> <a href="https://t.co/3MyF63Bz3e">pic.twitter.com/3MyF63Bz3e</a></p>&mdash; Richard Gee (@rgee0) <a href="https://twitter.com/rgee0/status/838468781550747649">March 5, 2017</a></blockquote>
<script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script>

####Constants
At this point a decision was made to also implement some constant values to remove magic numbers and aid readability of the code:

```
for i, _ := range pixels {				
                  pixels[i][0] = 0
                  pixels[i][1] = 0
                  pixels[i][2] = 0
                  pixels[i][3] = brightness				
  	}
```
With the addition of constants became:
```
for p, _ := range pixels {
	              pixels[p][redIndex] = 0
	              pixels[p][greenIndex] = 0
	              pixels[p][blueIndex] = 0
	              pixels[p][brightnessIndex] = brightness
	}
```

##Closing thoughts
This was my first real venture into the open source community, and I like to consider it a genuine success.  Alex was a really big help with ideas, and thankfully was both understanding & patient with the git/repo aspects.

With the changes described it will be worth examining  a worked example, so look out for the [next part](http://blog.technologee.co.uk/blinkt-golang-port/) where I'll build a Blinkt! program to demonstrate the use of the library.  I'll also employ [Docker](http://www.docker.com) to build and run the program in a container, thus removing the need for a local Golang build environment.

The NATS website takes care of providing a simple description:

NATS Server is a simple, high performance open source messaging system for cloud native applications, IoT messaging, and microservices architectures.

The core of the product is written in golang with official and community clients available across a gamut of development languages.  As you might expect, the official site provides a number of resources to help introduce users new to the concept and product.  They also helpfully provide an official Docker image which expediates the setup, allowing us more time in the evaluation process.  No only does it negate many of the pre-requisites but it also means we can have a NATS server up and running through a single command:

$ docker run -d -p 4222:4222 -p 6222:6222 -p 8222:8222 --name nats-main nats

This will pull the image from the hub if you don't already have it locally and start a single server with the exposed ports mapped to the equivalent host ports.

Build a client

There are a number of client examples in the NATS GitHub repositories.  I chose Go since I have a ready made development environment, which means we can get going with a single command (Thanks to Alex Ellis for the steer).

go get github.com/nats-io/go-nats/

This will pull the go-nats repo, along with any dependencies into your go src location; in my case:

$GOPATH/src/github.com/nats-io/go-nats

Now with everything in place head over to the examples directory:

cd $GOPATH/src/github.com/nats-io/go-nats/examples

Subscribing is easy:

go run nats-sub.go <subject>

And to publish:

go run nats-pub.go <subject> <message>

In this, the simplest mode, there is importance to the order of events, as we will see shortly.

NATS Publish Subscribe

This is probably the simplest mode, described as a fire and forget mechanism.  It's analogous to an aural message in that subscribers who aren't listening when the message is broadcast won't receive the message.  However, everyone who is listening will get the same message - good for notifications, not so good for despatching distinct units of work.

Here we can see the publisher in the red window publishing messages on the subject of 'rgee0' and subsequently the messages being picked up by the three subscribers in the three light windows.

NATS Queuing

Sometimes it may be desirable to publish a message and have only one subscriber receive the message.  This is where queue groups can be used.  In queue groups a message is still published with a particular subject but message is removed once one subscriber belonging to a queue group has received the message.  The previous principle of subscribers needing to be listening is still extant, however.

Here we can see that the format of the published message is the same as the previous example but the subscribers have passed a second argument, a queue identifier, into nats-qsub.go.  Now when a message is published only one of the three queue subscribers receives that message.

Further concepts

We have only begun to scratch the surface of NATS here.  Clearly where units of work are being buffered, then delivery guarantees and a degree of persistence is required; this could be achieve through NATS Streaming. Similarly a degree of server-side fault tolerance and resilience might be desirable and clustering is available in this regard (also possible via Docker).  These are more detailed concepts which may be worthy of dedicated future articles.

Working, as I frequently do, on small projects on headless Raspberry Pis it can sometimes be a challenge to establish an efficient flow while developing. On one hand you could work locally in your favoured editor and benefit from the increased efficiency this provides, but this is soon offset with the transferral of code every time you wish to test it.  Alternatively you could develop remotely through a terminal connection using vi, vim, nano, etc and gradually come to terms with their idiosyncrasies.

Until recently I was managing to do both; I was working on Windows and would use WinSCP to connect to a Pi and then use the built in menu option within WinSCP to 'Edit with' to open the remote file locally in VS Code.  I could then make my changes, save, WinSCP would write the changes to the remote file and I could then run build/run the resulting code via an ssh connection.

I'm now working on a Mac and my initial approach was to run Samba on my Pis and mount the Pis as local drives.  This works but I've found it to be less reliable than my previous method, and so I started looking into other means.

VS Code has a remote extension

One of the strengths of VS Code is its extensibility and the community support thereof, so its perhaps of little surprise that the described problem has already been solved.  There is an extension in the market place called Remote VSCode

Installation is simple, either search for it through the extensions panel or open Go -> Go to File from the menu (⌘P) and type:

ext install remote-vscode

Once installed the server will need starting - ⇧⌘P and then look for:

Remote: Start Server

Configure the Pi

OK, so have got the extension enabled locally, but how does the Pi know about it?  Well, we need to do some configuration to enable this. When connecting to the Pi we can also take the opportunity to set up an ssh tunnel for the Pi to redirect the remote commands back into the server running within VS Code:

ssh -R 52698:127.0.0.1:52698 pi@<pi-ip-address>

Once connected we need to install one of the rmate options from the extension's homepage.  I chose the python version after the bash version failed to install:

sudo pip install rmate

Then with the server running locally within VS Code we can call rmate <file> on the Pi and the file will open within VS Code.

Further Refinement

Adding the ssh tunnel element to the command when initiating the connection may be cumbersome and become difficult to remember. Fortunately, through the use of a ~/.ssh/config file we can ensure that the tunnel is configured every time we create a connection to our Pi.

Host pi3
    HostName <pi-ip-address>
    User pi
    ForwardAgent yes
    RemoteForward 52698 127.0.0.1:52698

Now, once we have started the server within VS Code, all we need to run is ssh pi3 and the resulting connection will have our ssh tunnel automatically configured.

Limitations

Currently rmate supports only files, it doesn't yet support directory structures; so this is an approach only really for smaller projects.  If you're hacking about with a Blinkt!, or Mote then why not give it a go?  You can even run rmate with sudo allowing you to work on restricted files like wpa_supplicant.conf.