From 09750ce3525129a676dec4f579aea3ad2eca1b19 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Mon, 9 Jan 2023 11:09:14 +0000 Subject: Add instances implementation (still needs testing) Signed-off-by: Laurent Bercot --- doc/instances.html | 121 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 121 insertions(+) create mode 100644 doc/instances.html (limited to 'doc/instances.html') diff --git a/doc/instances.html b/doc/instances.html new file mode 100644 index 0000000..0586fdb --- /dev/null +++ b/doc/instances.html @@ -0,0 +1,121 @@ + + + + + + s6: dynamic instantiation + + + + + + +

+s6
+Software
+skarnet.org +

+ +

Dynamic instantiation under s6

+ +

+ A instanced service is a parameterized service that you want to +run several copies of, with only the parameter changing. Each copy of the +service is called an instance. +

+ +

+ With s6, a service directory can only +handle one process at a time. So, if we want instanced services, there +will have to be one service directory per instance, always. +

+ +

+ Static instantiation means that the set of possible instances +is finite and known in advance. With s6, it means that all the service +directories for all possible instances are created, typically by a +preprocessor, and instances are treated like regular services. +

+ +

+ Dynamic instantiation means that instances are created +on demand instead of preallocated. Starting with version 2.11.2.0, s6 +provides a few tools to help users set up and manage dynamically +instanced services. +

+ +

How to make a dynamically instanced service under s6

+ +

Write a template for a service directory that would run under +s6-supervise. +The run script should take the name of the instance as its +first argument; the finish script should take the name of the +instance as its third argument.
Call the s6-instance-maker program +with this template as first argument, and a path dir as second +argument. s6-instance-maker will create +a service directory in dir. This is an offline tool: it does not +interact with any currently active services or supervision trees.
Supervise dir by adding it to your regular +scan directory. This will be your instanced +service, but it's not running any instances yet. It is, instead, a nested +supervision tree - the instanced service is an +s6-svscan process that will supervise all the +instances.
Create and delete instances at will with the +s6-instance-create and +s6-instance-delete programs. Instances +are regular supervised processes; you can control them with +s6-instance-control. These tools are +online: they work with live service directories (i.e. that are +being supervised by s6-supervise). They +are really syntactic sugar around the +s6-svlink, +s6-svunlink and +s6-svc programs; they provide you with the +same functionality but allow you to address individual instances via the +instanced service name (the service directory running the nested +supervision tree) and the instance name.

+ +

Internal workings

+ +

+This section is not normative; users should not rely on it. It is only +here for informational purposes. +

+ +

The service directory created by s6-instance-maker +has two specifics subdirectories in it: instance and instances. They +are initially empty, except that the template service directory is stored in +instances/.template.
When the service is active, there is an s6-svscan +process running on instance.
s6-instance-create makes a copy of +instances/.template into instances/name/tt>, and +s6-svlinks instances/name/tt> to +instance. When it returns, there is an s6-supervise +process running on instance/name, and the instance may be up +or not depending on the given options.

+ s6-instance-control is syntactic sugar +around s6-svc on instance/name. + s6-instance-delete is syntactic sugar +around s6-svunlink on instance/name. +

+ + Notes + + + This implementation of dynamic instances may seem expensive: it +creates one s6-svscan process per +instanced service, and one s6-supervise +process per instance. However, remember that these processes use very +little private memory, so having additional copies of them is far less +expensive than it looks. It's really a convenient way to implement the +feature by reusing existing code. + + + + -- cgit v1.2.3