openstf/ambassador repository overview

⁠Warning

⁠This project along with other ones in OpenSTF⁠ organisation is provided as is for community, without active development.

⁠You can check any other forks that may be actively developed and offer new/different features here⁠.

⁠Active development has been moved to DeviceFarmer⁠ organisation.

⁠docker-ambassador

This docker image is a mashup of ctlc/ambassador⁠ and suutari/ambassador⁠. It was made for the OpenSTF⁠ example deployment when we realized that ctlc/ambassador was pretty much completely broken.

While there are practically endless existing ambassador images out there, having our own ambassador image allows us more flexibility.

1. No one will suddenly decide to change the image in a way that breaks it.
2. It's way, way smaller (~6.5MB vs ctlc/ambassador's ~185MB) while still being an automated build.
3. Doesn't do stupid things like watch ls or top to keep the background jobs alive. The wait shell built-in is perfect and doesn't waste resources.
4. Unlike most other ambassador implementations, dies if the underlying socat dies, allowing your supervisor of choice (e.g. systemd⁠) to take over and possibly restart the socket. Make sure to read Caveats⁠, though.
5. Attempts to shut down cleanly.

Also, note that we are NOT claiming that this old-school ambassador pattern is the best way to go today. It's simply one way to do things.

⁠Usage

The "Link via an ambassador container⁠" article on the Docker website explains the ambassador pattern and potential usage quite clearly. Just replace svendowideit/ambassador with openstf/ambassador where required.

⁠Caveats

If the internal socat somehow manages to die, it won't get restarted. Instead, the container dies with it. We recommend using a proper systemd Service unit⁠ for automatically restarting it.

However, if your ambassador handles more than one link, then even if all links except one die, the ambassador will happily stay alive waiting for the last link to die too, which means that systemd won't notice a thing and has no chance to restart the unit to reopen sockets. Most if not all traditional ambassador pattern implementations suffer from this problem as well, many of them even if you're only using a single link.

⁠License

See LICENSE⁠.

Copyright © Simo Kinnunen. All Rights Reserved.