Configuration in Go Should Be Typed: Introducing confkit

Every Go application eventually needs configuration.

At the beginning, it is usually innocent:

port := os.Getenv("PORT")

Then the application grows.

You add a database URL. Then a Redis address. Then timeouts. Then feature flags. Then a YAML file for local development. Then environment variables for production. Then CLI flags for internal tools. Then Kubernetes secrets. Then maybe Vault, AWS Secrets Manager, or another infrastructure-specific source.

At some point, configuration stops being a few environment variables.

It becomes part of your application architecture.

And if you are not careful, it becomes a pile of string parsing, default values, manual validation, unclear precedence rules, and startup errors that only make sense to the person who originally wrote the code.

That is the problem I wanted to solve with confkit.

confkit is a typed configuration loading library for Go. It lets you define application configuration as a regular Go struct, load it from multiple sources, apply defaults, validate fields, and safely redact secrets from logs and error messages.

The short version:

type Config struct {
    Port     int    `env:"PORT" default:"8080" validate:"min=1,max=65535"`
    Database string `env:"DATABASE_URL" validate:"required" secret:"true"`
}

cfg, err := confkit.Load[Config](
    confkit.FromEnv(),
    confkit.FromYAML("config.yaml"),
)
if err != nil {
    log.Fatal(confkit.Explain(err))
}

No maps.

No manual parsing.

No hidden stringly-typed configuration layer.

No accidental secret leaks in startup logs.

Why configuration deserves more attention

Configuration code is rarely the most exciting part of a project.

Nobody starts a new backend service thinking:

I can't wait to write a robust configuration layer today.

Usually, we just want to get to the actual application logic.

But configuration is one of the first things your application touches when it starts. If it is wrong, everything else becomes unreliable.

Bad configuration handling can lead to:

services starting with empty required values
invalid ports, timeouts, or limits
production secrets accidentally printed to logs
unclear source priority between files, env vars, and flags
duplicated parsing logic across services
late runtime failures instead of fast startup failures
CI pipelines that cannot validate config before deployment

In Go, this often ends up as a mix of os.Getenv, helper functions, YAML unmarshalling, manual validation, and a few comments explaining which value overrides which.

That works for small projects. It gets painful when the project grows.

I wanted configuration to feel more like a contract:

This is the shape of the config.
These fields are required.
These defaults are safe.
These values are secrets.
These validation rules must pass before the application starts.

In confkit, that contract is a Go struct.

The struct is the contract

Here is a slightly more complete example:

package main

import (
    "log"
    "time"

    "github.com/MimoJanra/confkit"
)

type Config struct {
    Host    string        `env:"HOST" default:"localhost"`
    Port    int           `env:"PORT" default:"8080" validate:"min=1,max=65535"`
    Timeout time.Duration `env:"TIMEOUT" default:"30s"`

    DB struct {
        DSN      string `env:"DSN" validate:"required" secret:"true"`
        MaxConns int    `env:"MAX_CONNS" default:"10" validate:"min=1,max=100"`
    } `prefix:"DB_"`
}

func main() {
    cfg, err := confkit.Load[Config](
        confkit.FromFlags(nil),
        confkit.FromEnv(),
        confkit.FromYAML("config.yaml"),
    )
    if err != nil {
        log.Fatal(confkit.Explain(err))
    }

    log.Printf("listening on %s:%d", cfg.Host, cfg.Port)
}

This struct describes quite a lot:

HOST has a default value
PORT has a default value and must be between 1 and 65535
TIMEOUT is parsed as time.Duration
DB_DSN is required
DB_DSN is also marked as secret
DB_MAX_CONNS has a default and a validation range
nested config fields can use a prefix

The application code receives a typed Config.

That means the rest of the app does not need to know where configuration came from. It does not care if a value came from YAML, an environment variable, a CLI flag, or a secret manager.

It just receives a normal Go value.

Explicit source priority

One thing I wanted to avoid is magical source precedence.

Configuration priority should be visible in code.

With confkit, sources are checked in the order you pass them:

cfg, err := confkit.Load[Config](
    confkit.FromFlags(nil),          // highest priority
    confkit.FromEnv(),               // overrides files
    confkit.FromYAML("config.yaml"), // fallback
)

This makes the priority easy to reason about:

flags -> environment variables -> config.yaml -> defaults

This is useful for common deployment patterns:

local development uses config.yaml
production overrides values through environment variables
CLI tools override specific values through flags
defaults keep non-critical fields simple

There is no need to hide this behavior in documentation or in a custom helper function. The order is visible where the config is loaded.

Clear validation errors

A configuration library should fail early.

If a required value is missing, the application should not start and then fail later when some database client, HTTP server, or queue consumer receives an empty string.

For example:

type Config struct {
    DatabaseURL string `env:"DATABASE_URL" validate:"required" secret:"true"`
}

If DATABASE_URL is missing, confkit gives a readable error:

Invalid configuration:

  DatabaseURL
    error: field is required
    source: env (DATABASE_URL)

That is the kind of error I want during startup.

It tells me:

which field failed
what went wrong
where the value was expected to come from

The goal is not just to return an error. The goal is to return an error that is useful when the service fails to start and someone needs to fix the deployment quickly.

Defaults without extra files

Defaults live next to the fields:

type Config struct {
    Host     string        `env:"HOST" default:"localhost"`
    Port     int           `env:"PORT" default:"8080" validate:"min=1,max=65535"`
    LogLevel string        `env:"LOG_LEVEL" default:"info" validate:"oneof=debug info warn error"`
    Timeout  time.Duration `env:"TIMEOUT" default:"30s"`
}

For me, this is much easier to maintain than scattering defaults across startup code.

The struct tells the full story:

field name
environment variable name
default value
validation rule
secret status, if needed

This makes configuration review easier too. You can look at the struct and understand what the application expects.

Secret redaction by default

Configuration often contains sensitive values:

type Config struct {
    APIKey   string `env:"API_KEY" validate:"required" secret:"true"`
    Password string `env:"DB_PASSWORD" secret:"true"`
}

If a field is marked with secret:"true", confkit redacts it in formatted errors and config dumps.

This matters because startup errors are often logged everywhere:

local terminal output
Docker logs
Kubernetes logs
CI/CD output
Slack alerts
monitoring systems
screenshots in support threads

A configuration library should make the safe behavior the easy behavior.

The developer should not have to remember to manually hide every token before logging an error.

Loading from files

confkit supports common file-based configuration formats:

cfg, err := confkit.Load[Config](
    confkit.FromYAML("config.yaml"),
)

There are also JSON and TOML sources:

cfg, err := confkit.Load[Config](
    confkit.FromJSON("config.json"),
    confkit.FromTOML("config.toml"),
)

A typical local config.yaml might look like this:

host: localhost
port: 8080
timeout: 30s

db:
  dsn: postgres://user:password@localhost:5432/app
  max_conns: 10

And the Go struct can still be the main contract:

type Config struct {
    Host    string        `yaml:"host" env:"HOST" default:"localhost"`
    Port    int           `yaml:"port" env:"PORT" default:"8080" validate:"min=1,max=65535"`
    Timeout time.Duration `yaml:"timeout" env:"TIMEOUT" default:"30s"`

    DB struct {
        DSN      string `yaml:"dsn" env:"DSN" validate:"required" secret:"true"`
        MaxConns int    `yaml:"max_conns" env:"MAX_CONNS" default:"10"`
    } `yaml:"db" prefix:"DB_"`
}

This gives you a nice local workflow without giving up production-friendly environment variable overrides.

Environment variables for production

Environment variables are still one of the most common ways to configure services in production.

confkit keeps this simple:

type Config struct {
    Host string `env:"HOST" default:"localhost"`
    Port int    `env:"PORT" default:"8080"`
}

Then:

HOST=0.0.0.0 PORT=3000 ./app

For nested structs, prefixes help avoid awkward names:

type Config struct {
    Database struct {
        Host string `env:"HOST" default:"localhost"`
        Port int    `env:"PORT" default:"5432"`
    } `prefix:"DB_"`
}

This maps to:

DB_HOST
DB_PORT

I like this pattern because nested structs are natural in Go, while environment variables are naturally flat. Prefixes connect the two without making the code weird.

CLI flags for tools

Configuration is not only for web services.

CLI tools often need a mix of files, environment variables, and flags.

Example:

type Config struct {
    Input   string `flag:"input" validate:"required"`
    Output  string `flag:"output" default:"out.json"`
    Verbose bool   `flag:"verbose" default:"false"`
}

cfg, err := confkit.Load[Config](
    confkit.FromFlags(nil),
    confkit.FromEnv(),
)
if err != nil {
    log.Fatal(confkit.Explain(err))
}

Now the CLI can be configured through flags, while still allowing environment variable fallback if you want it.

That gives you one config model instead of separate parsing logic for each source.

Safe config dumps

Sometimes you need to see the final configuration after all sources, defaults, and overrides were applied.

This is useful for debugging:

log.Println(confkit.DumpString(cfg))

If the config contains secret fields, they are redacted by default.

Example:

type Config struct {
    Host     string `env:"HOST" default:"localhost"`
    Password string `env:"PASSWORD" secret:"true"`
}

A safe dump should not print the real password.

That sounds obvious, but it is very easy to get wrong when every service has its own custom config logging code.

confkit gives you dump helpers for JSON and YAML output, with secret redaction enabled by default.

Validate configuration in CI

One feature I find especially useful is ValidateOnly.

The idea is simple: run the full loading and validation pipeline without triggering side effects such as hooks, audit logging, or reload-related behavior.

That makes it useful for CI checks.

For example:

_, err := confkit.ValidateOnly[Config](
    context.Background(),
    confkit.WithSource(confkit.FromYAML("config.prod.yaml")),
)
if err != nil {
    log.Fatal(confkit.Explain(err))
}

This lets you validate configuration before deployment.

A broken YAML file, missing required value, or invalid timeout should be caught before the application reaches production.

Optional infrastructure integrations

Not every application needs Vault.

Not every CLI tool needs AWS.

Not every small service should pull Kubernetes dependencies into the binary.

That is why confkit keeps the core package focused and provides optional integrations separately.

The core package covers common local/runtime sources such as:

environment variables
CLI flags
YAML
JSON
TOML

Optional integrations can be used when needed, including:

Kubernetes
Vault
Consul
etcd
AWS SSM / Secrets Manager

This keeps the basic library lightweight while still allowing production systems to load configuration from real infrastructure.

Install the core package:

go get github.com/MimoJanra/confkit@latest

Install optional integrations only when you need them:

go get github.com/MimoJanra/confkit/vault@latest
go get github.com/MimoJanra/confkit/consul@latest
go get github.com/MimoJanra/confkit/etcd@latest
go get github.com/MimoJanra/confkit/aws@latest

Hot reload

Some applications need to react to configuration changes without restarting.

confkit supports file watching:

cfg, watcher, err := confkit.LoadWithWatcher[Config](
    "config.yaml",
    confkit.FromYAML("config.yaml"),
    confkit.FromEnv(),
)
if err != nil {
    log.Fatal(confkit.Explain(err))
}

watcher.AddListener(func(oldCfg, newCfg any, err error) {
    if err != nil {
        log.Printf("config reload failed: %v", err)
        return
    }

    log.Println("config reloaded")
})

watcher.Start()
defer watcher.Stop()

_ = cfg

This is useful for long-running services where some operational values can safely change at runtime.

Of course, not every config value should be hot-reloadable. Database credentials, server ports, and deeply structural settings often still require a restart.

But when you do need reload behavior, it is useful to have it integrated with the same configuration model.

Custom sources

Configuration backends are often company-specific.

Maybe your team has an internal configuration service. Maybe you load values from a platform API. Maybe secrets come from a custom encrypted file format.

confkit supports custom sources through a small interface:

type Source interface {
    Name() string
    Lookup(ctx context.Context, field *FieldInfo) (any, bool, error)
}

That means the built-in sources are not a closed world.

You can keep the same typed struct, validation rules, defaults, and redaction behavior while adding your own configuration backend.

Schema and documentation generation

One useful side effect of treating configuration as a struct contract is that the same struct can be used to generate documentation.

confkit includes schema-related functionality for generating references from config structs.

That can be useful when you want to document:

supported environment variables
default values
required fields
validation constraints
CLI options
config file structure

In other words, the config struct can become the source of truth not only for the application, but also for the documentation around that application.

Why not just use another config library?

There are already good Go configuration libraries.

You might use:

envconfig for environment variables
koanf for modular configuration composition
Viper for a broad and established configuration system

confkit is not trying to pretend those projects do not exist.

The design is focused on a specific style:

Go struct + tags + typed loading + defaults + validation + safe diagnostics

A rough rule of thumb:

Use envconfig if you only need environment variables.

Use koanf if you want a flexible toolkit and prefer composing behavior yourself.

Use Viper if you need a large, established configuration system with many built-in behaviors.

Use confkit if you want your configuration contract to be a Go struct, with validation and safe errors built in from the beginning.

API stability

Configuration loading sits very close to application startup.

If it breaks, the application may not start at all.

That is why API stability matters.

confkit has a v1 stability contract for the core public API. The intention is that v1.x releases can add functionality without breaking existing users, while breaking API changes require a future v2 release.

For a configuration library, this is important. The API should be boring in the best possible way: stable, predictable, and safe to update.

Complete minimal example

Here is a small working example:

package main

import (
    "log"

    "github.com/MimoJanra/confkit"
)

type Config struct {
    Host string `env:"HOST" default:"localhost"`
    Port int    `env:"PORT" default:"8080" validate:"min=1,max=65535"`

    DatabaseURL string `env:"DATABASE_URL" validate:"required" secret:"true"`
}

func main() {
    cfg, err := confkit.Load[Config](
        confkit.FromEnv(),
        confkit.FromYAML("config.yaml"),
    )
    if err != nil {
        log.Fatal(confkit.Explain(err))
    }

    log.Printf("starting server on %s:%d", cfg.Host, cfg.Port)
}

Example config.yaml:

host: localhost
port: 8080

Run with:

DATABASE_URL=postgres://user:pass@localhost:5432/app go run .

The application gets a typed config struct, while secrets remain protected in logs and errors.

Final thoughts

Configuration is not glamorous.

But it is one of the most important startup paths in any service.

It decides whether your application starts safely, fails clearly, validates its assumptions, and protects sensitive values.

confkit is my attempt to make that layer simple and explicit:

define config as a Go struct
load it from multiple sources
apply defaults
validate before startup
redact secrets automatically
explain errors clearly
support real production sources when needed

One struct.

Multiple sources.

Typed values.

Readable errors.

Safe logs.

That is the whole idea.

You can find the project here:

github.com/MimoJanra/confkit

推荐订阅源

DEV Community