Intégration d’un service en Go avec systemd: activation par socket

Vincent Bernat

Dans un ar­ticle pré­cé­dent, j’ai sou­li­gné cer­taines fonc­tion­na­li­tés utiles de sys­temd pour écrire un ser­vice en Go, no­tam­ment pour in­di­quer la dis­po­ni­bi­lité et prou­ver la vi­va­cité. Un autre point in­té­res­sant est l’ac­ti­va­tion par so­cket1 : sys­temd écoute pour le compte de l’ap­pli­ca­tion et, lors de la pre­mière re­quête, dé­marre le ser­vice avec une co­pie de la so­cket en écoute. Len­nart Poet­te­ring dé­taille dans un article :

Si un ser­vice meurt, sa so­cket d’écoute reste en place, sans perdre un seul mes­sage. Après un re­dé­mar­rage du ser­vice suite à une panne, il peut conti­nuer là où il s’est ar­rêté. Si un ser­vice est mis à ni­veau, nous pou­vons re­dé­mar­rer le ser­vice tout en conser­vant ses so­ckets, as­su­rant ainsi que le ser­vice est conti­nuel­le­ment dis­po­nible. Au­cune connexion n’est per­due pen­dant la mise à niveau.

Il s’agit d’une so­lu­tion pour ob­te­nir un dé­ploie­ment sans im­pact d’une ap­pli­ca­tion. Un autre avan­tage est la pos­si­bi­lité d’exé­cu­ter un dé­mon avec moins de pri­vi­lèges : perdre des droits est une tâche ar­due avec Go2.

La base#

Re­pre­nons notre sym­pa­thique ser­veur de pages 404 :

package main

import (
    "log"
    "net"
    "net/http"
)

func main() {
    listener, err := net.Listen("tcp", ":8081")
    if err != nil {
        log.Panicf("cannot listen: %s", err)
    }
    http.Serve(listener, nil)
}

Voici la ver­sion uti­li­sant l’ac­ti­va­tion par so­cket, à l’aide de go-systemd :

package main

import (
    "log"
    "net/http"

    "github.com/coreos/go-systemd/activation"
)

func main() {
    listeners, err := activation.Listeners(true) // ❶
    if err != nil {
        log.Panicf("cannot retrieve listeners: %s", err)
    }
    if len(listeners) != 1 {
        log.Panicf("unexpected number of socket activation (%d != 1)",
            len(listeners))
    }
    http.Serve(listeners[0], nil) // ❷
}

En ❶, nous ré­cu­pé­rons les so­ckets en écoute four­nies par sys­temd. En ❷, nous uti­li­sons la pre­mière d’entre elles pour ser­vir les re­quêtes HTTP. Tes­tons le ré­sul­tat avec systemd-socket-activate3 :

$ go build 404.go
$ systemd-socket-activate -l 8000 ./404
Listening on [::]:8000 as 3.

Dans un autre ter­mi­nal, ef­fec­tuons quelques requêtes :

$ curl '[::1]':8000
404 page not found
$ curl '[::1]':8000
404 page not found

Deux fi­chiers sont né­ces­saires pour com­plé­ter l’in­té­gra­tion avec systemd :

  • un fi­chier .socket dé­cri­vant la socket ;
  • un fi­chier .service dé­cri­vant le ser­vice associé.

Voici le contenu du fi­chier 404.socket :

[Socket]
ListenStream = 8000
BindIPv6Only = both

[Install]
WantedBy = sockets.target

La page de ma­nuel systemd.​socket(5) dé­crit les op­tions dis­po­nibles. BindIPv6Only = both est ex­pli­ci­te­ment uti­lisé car sa va­leur par dé­faut dé­pend de la dis­tri­bu­tion. Voici en­suite le contenu du fi­chier 404.​service :

[Unit]
Description = 404 micro-service

[Service]
ExecStart = /usr/bin/404

sys­temd sait que les deux fi­chiers sont liés car ils par­tagent un même pré­fixe. Pla­cez-les dans /etc/​systemd/​system et exé­cu­tez systemctl daemon-reload et systemctl start 404.​socket. Votre ser­vice est dé­sor­mais prêt à ac­cep­ter des connexions !

Gestion des connexions existantes#

Notre ser­veur de pages 404 a un dé­faut ma­jeur : les connexions exis­tantes sont sau­va­ge­ment tuées lorsque le dé­mon est ar­rêté ou re­dé­marré. Cor­ri­geons cela !

Attendre quelques secondes les connexions existantes#

Nous pou­vons in­clure une courte pé­riode de to­lé­rance pour ter­mi­ner les connexions en cours. À l’is­sue de celles-ci, les connexions res­tantes sont tuées :

// À la réception du signal, ferme en douceur le serveur et
// attend 5 secondes la fin des connexions en cours.
done := make(chan struct{})
quit := make(chan os.Signal, 1)
server := &http.Server{}
signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)

go func() {
    <-quit
    log.Println("server is shutting down")
    ctx, cancel := context.WithTimeout(context.Background(),
        5*time.Second)
    defer cancel()
    server.SetKeepAlivesEnabled(false)
    if err := server.Shutdown(ctx); err != nil {
        log.Panicf("cannot gracefully shut down the server: %s", err)
    }
    close(done)
}()

// Accepte de nouvelles connexions.
server.Serve(listeners[0])

// Attend la fin des connexions en cours avant de sortir.
<-done

À la ré­cep­tion du si­gnal de ter­mi­nai­son, la go­rou­tine re­prend et pla­ni­fie l’ar­rêt du service :

Shutdown() ferme en dou­ceur le ser­veur sans in­ter­rompre les connexions ac­tives. Shutdown() fonc­tionne en fer­mant d’abord les so­ckets en écoute puis en fer­mant toutes les connexions in­ac­tives et en­fin en at­ten­dant in­dé­fi­ni­ment que les connexions re­tombent au re­pos et s’arrêtent.

Du­rant le re­dé­mar­rage, les nou­velles connexions ne sont pas ac­cep­tées : elles res­tent dans la file d’at­tente as­so­ciée à la so­cket. La taille de celle-ci est li­mi­tée et peut être confi­gu­rée avec la di­rec­tive Backlog. Sa va­leur par dé­faut est 128. Vous pou­vez conser­ver cette va­leur même si votre ser­vice s’at­tend à re­ce­voir de nom­breuses connexions par se­conde. Lorsque cette va­leur est dé­pas­sée, les connexions en­trantes sont igno­rées. Le client ré­es­saye au­to­ma­ti­que­ment de se connec­ter. Sous Li­nux, par dé­faut, un client tente 5 fois (tcp_​syn_​retries) en 3 mi­nutes en­vi­ron. C’est un bon moyen d’évi­ter l’ef­fet de trou­peau qui se ma­ni­fes­te­rait au re­dé­mar­rage si la taille de la file d’at­tente était aug­men­tée à une va­leur plus élevée.

Attendre plus longtemps les connexions existantes#

Si vous vou­lez at­tendre la fin des connexions exis­tantes pen­dant une longue pé­riode, vous avez be­soin d’une ap­proche al­ter­na­tive pour évi­ter d’igno­rer les nou­velles connexions pen­dant plu­sieurs mi­nutes. Il y a une as­tuce très simple : de­man­der à sys­temd de ne tuer au­cun pro­ces­sus. Avec KillMode = none, seule la com­mande d’ar­rêt est exé­cu­tée et tous les pro­ces­sus exis­tants ne sont pas perturbés :

[Unit]
Description = slow 404 micro-service

[Service]
ExecStart = /usr/bin/404
ExecStop  = /bin/kill $MAINPID
KillMode  = none

Si vous re­dé­mar­rez le ser­vice, le pro­ces­sus en cours prend le temps né­ces­saire pour s’ar­rê­ter et sys­temd lance im­mé­dia­te­ment une nou­velle ins­tance, prête à ré­pondre aux re­quêtes avec sa propre co­pie de la so­cket d’écoute. Tou­te­fois, nous per­dons la ca­pa­cité d’at­tendre que le ser­vice s’ar­rête com­plè­te­ment, soit par lui-même, soit de force après un temps li­mite avec SIGKILL.

Mise à jour (01.2021)

L’uti­li­sa­tion de KillMode=​none est dé­sor­mais dé­cou­ra­gée. En plus de l’al­ter­na­tive pro­po­sée ci-des­sous, il est pos­sible de trans­mettre les connexions ac­tives à sys­temd à l’aide de la fonc­tion sd_​pid_​notify_​with_​fds(). En­suite, le nou­veau pro­ces­sus doit être ca­pable de les gé­rer, ce qui n’est pas fa­cile car cela né­ces­site de four­nir éga­le­ment l’état as­so­cié à chaque connexion. De plus, cette fonc­tion n’est pas en­core pré­sente dans go-systemd.

Attendre plus longtemps les connexions existantes (alternative)#

Une al­ter­na­tive à la so­lu­tion pré­cé­dente consiste à faire croire à sys­temd que le ser­vice est mort️ pen­dant le re­dé­marrage.

done := make(chan struct{})
quit := make(chan os.Signal, 1)
server := &http.Server{}
signal.Notify(quit,
    // redémarrage:
    syscall.SIGHUP,
    // arrêt:
    syscall.SIGINT, syscall.SIGTERM)
go func() {
    sig := <-quit
    switch sig {
    case syscall.SIGINT, syscall.SIGTERM:
        // Arrêt avec limite de temps.
        log.Println("server is shutting down")
        ctx, cancel := context.WithTimeout(context.Background(),
            15*time.Second)
        defer cancel()
        server.SetKeepAlivesEnabled(false)
        if err := server.Shutdown(ctx); err != nil {
            log.Panicf("cannot gracefully shut down the server: %s", err)
        }
    case syscall.SIGHUP: // ❶
        // Exécute un processus éphémère et demande à systemd de
        // le suivre au lieu de nous.
        log.Println("server is reloading")
        pid := detachedSleep()
        daemon.SdNotify(false, fmt.Sprintf("MAINPID=%d", pid))
        time.Sleep(time.Second)

        // Attend sans limite de temps la fin des connexions en cours.
        server.SetKeepAlivesEnabled(false)
        if err := server.Shutdown(context.Background()); err != nil {
            log.Panicf("cannot gracefully shut down the server: %s", err)
        }
    }
    close(done)
}()

// Sert lentement les requêtes.
server.Handler = http.HandlerFunc(
    func(w http.ResponseWriter, r *http.Request) {
        time.Sleep(10 * time.Second)
        http.Error(w, "404 not found", http.StatusNotFound)
    })
server.Serve(listeners[0])

// Attend que toutes les connexions se terminent.
<-done
log.Println("server terminated")

La prin­ci­pale dif­fé­rence est le trai­te­ment du si­gnal SIGHUP en ❶ : un pro­ces­sus leurre de courte du­rée est exé­cuté et sys­temd est in­vité à le suivre. Quand il meurt, sys­temd lan­cera une nou­velle ins­tance du ser­vice. Cette mé­thode né­ces­site quelques bri­co­lages : sys­temd a be­soin que le leurre soit son fils mais Go ne peut pas fa­ci­le­ment se mettre en ar­rière plan seul. Par consé­quent, nous uti­li­sons un court script Py­thon in­clus dans la fonc­tion detachedSleep()4 :

// detachedSleep exécute un processus dormant une seconde
// en arrière plan et retourne son PID.
func detachedSleep() uint64 {
    py := `
import os
import time

pid = os.fork()
if pid == 0:
    for fd in {0, 1, 2}:
        os.close(fd)
    time.sleep(1)
else:
    print(pid)
`
    cmd := exec.Command("/usr/bin/python3", "-c", py)
    out, err := cmd.Output()
    if err != nil {
        log.Panicf("cannot execute sleep command: %s", err)
    }
    pid, err := strconv.ParseUint(strings.TrimSpace(string(out)), 10, 64)
    if err != nil {
        log.Panicf("cannot parse PID of sleep command: %s", err)
    }
    return pid
}

Pen­dant le re­char­ge­ment, il peut y avoir une courte pé­riode pen­dant la­quelle le nou­veau et l’an­cien pro­ces­sus ac­ceptent les re­quêtes en­trantes. Si vous ne le sou­hai­tez pas, vous pou­vez dé­pla­cer la créa­tion du pro­ces­sus leurre en de­hors de la go­rou­tine, après server.​Serve() ou im­plé­men­ter un mé­ca­nisme de syn­chro­ni­sa­tion. Il y a aussi un éven­tuel pro­blème de concur­rence lorsque nous di­sons à sys­temd de suivre un autre PID (voir PR #7816).

Le fi­chier 404.​service doit être mis à jour :

[Unit]
Description = slow 404 micro-service

[Service]
ExecStart    = /usr/bin/404
ExecReload   = /bin/kill -HUP $MAINPID
Restart      = always
NotifyAccess = main
KillMode     = process

Cha­cune des di­rec­tives sup­plé­men­taires a son im­portance :

  • ExecReload in­dique com­ment re­char­ger le pro­ces­sus (avec SIGHUP).
  • Restart in­dique de re­dé­mar­rer le pro­ces­sus s’il s’ar­rête de ma­nière « in­at­ten­due », no­tam­ment lors du re­char­gement5.
  • NotifyAccess pré­cise quels sont les pro­ces­sus au­to­ri­sés à en­voyer des no­ti­fi­ca­tions comme le chan­ge­ment de PID.
  • KillMode in­dique de ne tuer que le pro­ces­sus iden­ti­fié comme prin­ci­pal. Les autres sont lais­sés tran­quilles.

Déploiement sans impact ?#

Le dé­ploie­ment sans im­pact est une en­tre­prise dif­fi­cile sur Li­nux. Par exemple, HAProxy a eu une longue liste de ten­ta­tives jusqu’à ce qu’une so­lu­tion ap­pro­priée, mais com­plexe, soit im­plé­men­tée dans HAproxy 1.8. Com­ment se dé­brouille-t-on avec notre simple mise en œuvre ?

Du point de vue du noyau, il y a une seule so­cket avec une file d’at­tente unique. Cette so­cket est as­so­ciée à plu­sieurs des­crip­teurs de fi­chiers : un dans sys­temd et un dans le pro­ces­sus en cours. La chaus­sette reste en vie tant qu’il y a au moins un des­crip­teur de fi­chier. Une connexion en­trante est pla­cée par le noyau dans la file d’at­tente et peut être trai­tée à par­tir de n’im­porte quel des­crip­teur avec l’ap­pel sys­tème accept(). Par consé­quent, cette ap­proche per­met de réa­li­ser un dé­ploie­ment sans im­pact : au­cune connexion en­trante n’est rejetée.

En re­vanche, HAProxy uti­li­sait plu­sieurs so­ckets dif­fé­rentes pour écou­ter sur les mêmes adresses, grâce à l’op­tion SO_​REUSEPORT6. Chaque so­cket a sa propre file d’at­tente et le noyau ré­par­tit les connexions en­trantes entre cha­cune d’elles. Lorsqu’une so­cket se ferme, le contenu de sa file d’at­tente est perdu. Si une connexion en­trante se trou­vait ici, elle re­çoit une ré­ini­tia­li­sa­tion. Une mo­di­fi­ca­tion élé­gante pour Li­nux afin de si­gna­ler qu’une so­cket ne de­vrait plus re­ce­voir de nou­velles connexions a été re­je­tée. HAProxy 1.8 re­cycle dé­sor­mais les so­ckets exis­tantes vers les nou­veaux pro­ces­sus par le biais d’une so­cket Unix.

J’es­père que ce billet et le pré­cé­dent montrent com­bien sys­temd est un com­pa­gnon ap­pré­ciable pour un ser­vice en Go : dis­po­ni­bi­lité, vi­va­cité et ac­ti­va­tion par so­cket sont quelques-unes des fonc­tion­na­li­tés utiles pour construire une ap­pli­ca­tion plus fiable.

Annexe: leurre écrit en Go#

Mise à jour (03.2018)

Sur /r/golang, on m’a fait re­mar­quer que, dans la ver­sion où sys­temd suit un leurre, le script Py­thon peut être rem­placé par une in­vo­ca­tion de l’exé­cu­table prin­ci­pal qui se base sur un chan­ge­ment d’en­vi­ron­ne­ment pour prendre le rôle du leurre. Voici le code rem­pla­çant la fonc­tion detachedSleep() :

func init() {
    // Au plus tôt, vérifie si on doit jouer le rôle
    // du leurre.
    state := os.Getenv("__SLEEPY")
    os.Unsetenv("__SLEEPY")
    switch state {
    case "1":
        // Première étape, se réexécuter
        execPath := self()
        child, err := os.StartProcess(
            execPath,
            []string{execPath},
            &os.ProcAttr{
                Env: append(os.Environ(), "__SLEEPY=2"),
            })
        if err != nil {
            log.Panicf("cannot execute sleep command: %s", err)
        }

        // Publie le PID du fils et sort.
        fmt.Printf("%d", child.Pid)
        os.Exit(0)
    case "2":
        // Dort et sort.
        time.Sleep(time.Second)
        os.Exit(0)
    }
}

// self retourne le chemin absolu vers nous-même. Cela repose sur
// /proc/self/exe qui peut être un lien symbolique vers un fichier
// supprimé (durant une mise à jour par exemple).
func self() string {
    execPath, err := os.Readlink("/proc/self/exe")
    if err != nil {
        log.Panicf("cannot get self path: %s", err)
    }
    execPath = strings.TrimSuffix(execPath, " (deleted)")
    return execpath
}

// detachedSleep détache un processus qui dort une seconde et retourne
// son PID.
func detachedSleep() uint64 {
    cmd := exec.Command(self())
    cmd.Env = append(os.Environ(), "__SLEEPY=1")
    out, err := cmd.Output()
    if err != nil {
        log.Panicf("cannot execute sleep command: %s", err)
    }
    pid, err := strconv.ParseUint(strings.TrimSpace(string(out)), 10, 64)
    if err != nil {
        log.Panicf("cannot parse PID of sleep command: %s", err)
    }
    return pid
}

Annexe : nommage des sockets#

Pour un ser­vice donné, sys­temd peut four­nir plu­sieurs so­ckets. Pour les dif­fé­ren­cier, il est pos­sible de les nom­mer. Par exemple, sup­po­sons que nous vou­lions aussi re­tour­ner des codes d’er­reur 403 de­puis le même ser­vice mais sur un port dif­fé­rent. Nous ajou­tons une dé­fi­ni­tion de so­cket sup­plé­men­taire, 403.​socket, liée à la tâche 404.​service :

[Socket]
ListenStream = 8001
BindIPv6Only = both
Service      = 404.service

[Install]
WantedBy=sockets.target

À moins de le spé­ci­fier ex­pli­ci­te­ment avec la di­rec­tive FileDescriptorName, le nom de la so­cket est le nom de l’unité : 403.​socket. go-sys­temd four­nit la fonc­tion ListenersWithName() pour ré­cu­pé­rer une cor­res­pon­dance entre les noms et les sockets :

package main

import (
    "log"
    "net/http"
    "sync"

    "github.com/coreos/go-systemd/activation"
)

func main() {
    var wg sync.WaitGroup

    // Associe un nom de socket à une fonction de gestion.
    handlers := map[string]http.HandlerFunc{
        "404.socket": http.NotFound,
        "403.socket": func(w http.ResponseWriter, r *http.Request) {
            http.Error(w, "403 forbidden",
                http.StatusForbidden)
        },
    }

    // Récupère les sockets en écoute.
    listeners, err := activation.ListenersWithNames(true)
    if err != nil {
        log.Panicf("cannot retrieve listeners: %s", err)
    }

    // Pour chaque socket, invoque une goroutine en utilisant
    // la fonction de gestion adéquate.
    for name := range listeners {
        for idx := range listeners[name] {
            wg.Add(1)
            go func(name string, idx int) {
                defer wg.Done()
                http.Serve(
                    listeners[name][idx],
                    handlers[name])
            }(name, idx)
        }
    }

    // Attend que toutes les goroutines terminent.
    wg.Wait()
}

Com­pi­lons le ser­vice et lan­çons-le via systemd-socket-activate:

$ go build 404.go
$ systemd-socket-activate -l 8000 -l 8001 \
>                         --fdname=404.socket:403.socket \
>                         ./404
Listening on [::]:8000 as 3.
Listening on [::]:8001 as 4.

Dans une autre console, nous pou­vons tes­ter une re­quête sur cha­cune des deux adresses :

$ curl '[::1]':8000
404 page not found
$ curl '[::1]':8001
403 forbidden