Skip to content

Getting started

By the end of this you will have a shared Vault client, and you will know the one thing about it that bites long-running processes.

go get gitlab.com/phpboyscout/go/vaultclient

1. Build a source

package main

import (
    "context"
    "fmt"

    "gitlab.com/phpboyscout/go/vaultclient"
)

func main() {
    src := vaultclient.Ambient()

    fmt.Println("source built; nothing contacted yet")

    client, err := src.VaultClient(context.Background())
    if err != nil {
        panic(err)
    }

    fmt.Println("address:", client.Address())
}

With nothing set in the environment:

source built; nothing contacted yet
address: https://127.0.0.1:8200

That address is Vault's own documented default, not one this module invented.

2. Point it somewhere real

export VAULT_ADDR=https://vault.example.com:8200
export VAULT_TOKEN=hvs.…

Or in code, without touching the environment:

src := vaultclient.Ambient(
    vaultclient.WithAddress("https://vault.example.com:8200"),
    vaultclient.WithNamespace("team-a"),
)

3. The error the SDK makes easy to miss

vaultapi.DefaultConfig() reports failure by populating an Error field on the config it returns, rather than by returning an error. A caller who does not look gets a config that appears fine and fails at the first request, far from the cause.

Every rung here checks that field, so the failure surfaces at construction where it belongs.

Ask for an address that was never configured and you get a sentinel rather than a mystery:

no Vault address configured; set Address on the config, pass WithAddress, or set VAULT_ADDR

4. Know what you are holding

    client, _ := src.VaultClient(ctx)

That client carries the token that VAULT_TOKEN held at the moment it was built. Nothing re-reads the environment, and nothing renews the lease.

For a command that runs and exits, this is fine. For a process that runs for hours, it is the thing that will fail — and it will fail permanently rather than transiently. Read the token does not renew itself before you ship one.

Next