Configuration Management în Go cu Koanf

Radu Baciu
Engineer @ ING Hubs România

În ecosistemul Go, lipsa unei soluții încorporate pentru gestionarea configurațiilor forțează developerii să apeleze la implementări personalizate, ducând la cod redundant și mult boilerplate. Parcurgerea întregului ciclu de viață al configurațiilor aplicației (încărcare, validare, mapare, override) necesită implementarea manuală a unor aspecte și a multor pași repetitivi, la care se adaugă complexitatea testării unitare și de integrare.

De asemenea, integrarea ulterioară cu sisteme de management pentru secrets (Vault), servicii de configurare distribuită (Consul etc.) sau reîncărcări dinamice de configurație impune rescrierea sau extinderea codului existent, fără un model clar de extensibilitate.

Cerințele unei librării ideale

O soluție robustă pentru Go trebuie să ofere următoarele capabilități: o încărcare ușoară din mai multe surse: files (YAML, JSON, TOML), env variables, CLI, o prioritizare clară și predictibilă a surselor de configurații pentru override ușor de urmărit, delimitator configurabil pentru cheile de configurare, API unificat, tipizat și intuitiv (GetInt, GetString, GetBool, Exists). De asemenea, sunt importante și maparea directă în structuri Go cu tags (`koanf`), extensibilitatea pentru provideri și parsere personalizate și suport pentru valori implicite și validare automată.

Koanf - How to?

Instalare și inițializare

Pentru instalare e suficient:

go get github.com/knadh/koanf

,iar pentru a putea utiliza funcționalitățile Koanf, trebuie inițializată instanța cum vedem aici:

import "github.com/knadh/koanf"

// Creare instanță de koanf cu 
// delimitator ".", această 
// instanță fiind baza pentru orice 
// operațiuni am avea de făcut cu 
// acele configurații:

k := koanf.NewWithConf(
    koanf.Conf{
        Delim: ".",
    },
)

Încărcare fișier comun (application.yaml)

Fișierul `application.yaml` conține valorile de bază pentru toate mediile. Koanf suportă parsarea fișierelor YAML prin parserul dedicat.

import (
  "github.com/knadh/koanf/" +
    "providers/file"
  "github.com/knadh/koanf/" +
    "parsers/yaml"
)

if err := k.Load(
  file.Provider(
    "config/application.yaml",
  ),
  yaml.Parser(),
); err != nil {
  log.Fatalf(
    "error loading common " +
      "config: %v",

    err,
  )
}

Încărcare fișier specific per environment

Pentru fiecare environment (ex: TST, ACC, Prod) se poate defini un fișier specializat cu valorile ce suprascriu cele generale/comune.

if err := k.Load(
  file.Provider("config/application-tst.yaml"),
  yaml.Parser(),
); err != nil {
  log.Fatalf("error loading TST config: %v", err)
}

Override cu variabile de mediu

În medii cloud-native, valorile sensibile și configurările specifice containerelor sunt setate adesea prin environment variables. Koanf oferă un provider simplu pentru aceasta.

import (
  "github.com/knadh/koanf/" +
    "providers/env"
  "strings"
)

envProvider := env.Provider(
  "OP_", ".", func(s string) string {
    // OP_DB_URL devine db.url
    return strings.Replace(
      strings.ToLower(
        strings.TrimPrefix(s, "OP_"),
      ),
      "_", ".", -1,
    )
  },
)

if err := k.Load(
  envProvider, nil,
); err != nil {
  log.Fatalf(
    "error loading env vars: %v",
    err,
  )
}

Koanf poate face merge și override la configurațiile din toate aceste surse.

Citirea și validarea valorilor

Codul poate obține valori tipizate și valida existența cheilor/configurațiilor necesare.

port := k.Int("server.port")      // default 8080

dbURL := k.String("db.url")       // url bază date
debug := k.Bool("server.debug")   // debug on/off

// Verificare existență cheie
if !k.Exists("cache.enabled") {
  log.Println(
    "Warn: cache.enabled not set, " +
      "using default",
  )
}

Mapare într-un struct Go cu tags

Structurile Go pot fi adnotate cu taguri `koanf` pentru mapare directă, astfel evitând apelurile manuale la Get*().

type Config struct {
  Server struct {
    Port  int  `koanf:"port"`
    Debug bool `koanf:"debug"`
  } `koanf:"server"`
  DB struct {
    URL string `koanf:"url"`
  } `koanf:"db"`
}

var cfg Config
if err := k.Unmarshal("", &cfg); err != nil {
  log.Fatalf("error unmarshaling config: %v", err)
}

Diagrama fluxului de încărcare din surse multiple

+------------------------+     +-----------------------------+     +-------------------------------+
| application.yaml       |     | application-acc.yaml        |     | Env variables         |
| (common)               | --> | (specific environ.)         | --> | (override)                    |
+------------------------+     +-----------------------------+     +-------------------------------+
           \_______________________________________________________________↑

Use cases și scenarii complexe

Koanf este ideal pentru microservicii ce rulează în containere Docker, Kubernetes sau serverless, unde configurațiile sunt externalizate. Printre scenarii comune se numără configurare multi-tenant cu reload dinamic la schimbarea fișierelor, integrare cu Vault pentru secrets management în prod, dar și suport pentru feature flags prin provider custom și, nu în ultimul rând, încărcarea configurațiilor de la un serviciu centralizat (Consul).

Intern, Koanf implementează caching pentru provideri, evitând re-readurile inutile. Încărcarea inițială este rapidă, unde fișiere de câteva sute de KB sunt parsate în milisecunde.

Pentru valori sensibile, se recomandă utilizarea unui provider dedicat (ex: Vault). Cheile pot fi încărcate din Vault și combinate cu providerii locali.

Reload dinamic al configurațiilor

Pentru aplicațiile cu instanțe ce rulează continuu, Koanf poate observa modificările fișierelor și poate reîncărca setările automat fără repornire.

import "github.com/knadh/koanf/" +
  "providers/file"

import "github.com/radovskyb/" +
  "watcher"

w := watcher.New()

w.Add("config/application.yaml")

go func() {
  for {
    <-w.Event
    k.Load(
      file.Provider(
        "config/application.yaml",
      ),
      yaml.Parser(),
    )
    log.Println("Config reloaded")
  }
}()

w.Start(time.Millisecond * 500)

Comparație cu alte librării de management al configurațiilor

Avem și alte alternative pentru Koanf în Go. Unul ar fi Viper care bogat în funcționalități, dar mai greu de configurat și cu dependențe multiple. Pe de altă parte, avem Envconfig care este simplu, dar limitat la env variables. Nu în ultimul rând, avem Go-Config care are suport extensiv, dar fără parsare nativă YAML/TOML.

Best practices extinse

Ca recomandări pentru un workflow eficient este important să amintim definirea valorilor implicite direct în cod înainte de încărcare, o actualizare periodică și auditul fișierelor de configurații, dar și documentarea configurațiilor în README-ul proiectului. Alte aspecte importante sunt testarea automată a scenariilor de configurare (unit tests, integration tests) și un audit de securitate pentru directoarele ce conțin fișiere sensibile.

Concluzie

Managementul configurațiilor este o componentă esențială în dezvoltarea de software. Flexibilitatea joacă un rol important în procesul de inițializare al configurațiilor. O librărie care suportă diferite formate ca sursă și oferă posibilitatea unei secvențe de încărcare personalizate acoperă în general majoritatea scenariilor de utilizare. Dacă îți dorești o soluție solidă pentru încărcarea configurațiilor, Koanf este o alegere pe care ți-o recomand cu drag.

Koanf oferă un model clar și extensibil pentru managementul configurațiilor în Go, permițând dezvoltatorilor, chiar și celor la început de drum, să adopte rapid cele mai bune practici, cu un minim de cod suplimentar și efort de mentenanță.