redis

Overview ¶

Package redis provides an instrumented Redis client that implements app.Component.

The client wraps go-redis and supports single-node, Sentinel, and Cluster topologies through a unified Config. OpenTelemetry tracing and Prometheus metrics are applied as hooks at construction time and require no changes to call sites.

Use Client.Redis to obtain the underlying goredis.UniversalClient for executing commands.

Basic usage ¶

client, err := redis.NewWithConfig(&redis.Config{
    Addrs: []string{"localhost:6379"},
})
if err != nil { log.Fatal(err) }

a.Register(client)
if err := a.Start(ctx); err != nil { log.Fatal(err) }
defer a.Shutdown(ctx) //nolint:errcheck

val, err := client.Redis().Get(ctx, "my-key").Result()

With tracing and metrics ¶

client, err := redis.NewWithConfig(&redis.Config{
    Addrs:      []string{"localhost:6379"},
    Tracer:     a.Tracer(),
    Registerer: a.Metrics().Registerer(),
})

Every command automatically receives an OpenTelemetry span and is counted in Prometheus histograms.

Sentinel (high-availability) ¶

client, err := redis.NewWithConfig(&redis.Config{
    Addrs:      []string{"sentinel1:26379", "sentinel2:26379"},
    MasterName: "mymaster",
})

In security-hardened deployments Sentinel processes require their own credentials, distinct from the Redis data-tier credentials:

client, err := redis.NewWithConfig(&redis.Config{
    Addrs:            []string{"sentinel1:26379", "sentinel2:26379"},
    MasterName:       "mymaster",
    SentinelUsername: "sentinel-user",
    SentinelPassword: "sentinel-secret",
    Password:         "redis-secret",
})

Cluster ¶

client, err := redis.NewWithConfig(&redis.Config{
    Addrs: []string{"node1:6379", "node2:6379", "node3:6379"},
})

Reading configuration from Kubernetes ¶

In Kubernetes deployments, New reads the Redis connection parameters from the infrastructure configuration mounted by the platform (typically via infrastructure.DefaultConfig). Authentication credentials and TLS material are resolved from infrastructure.Config.Secrets and infrastructure.Config.TLSSecrets. Secrets are looked up under the "redis/" prefix.

The format field on infrapb.Redis.SecretRef controls how credential keys are mapped inside the referenced Kubernetes Secret:

• REDIS_FORMAT_VALKEY — uses a fixed preset that matches the Secret produced by the valkey/valkey Helm chart. Only the password is read, from the key `default-password`, for the `default` ACL user. Username and Sentinel credentials are ignored.
• REDIS_FORMAT_CUSTOM — reads the key names from infrapb.RedisSecret.Projection. Each non-nil field in the projection names the Secret key for that credential (username, password, sentinel_username, sentinel_password).

For REDIS_FORMAT_CUSTOM, leaving a projection field nil means that credential is not read from the Secret. A nil password or sentinel_password means the connection is unauthenticated but we want to read the username and/or the sentinel_username field. A non-nil field that points to a key absent from the Secret returns an error.

TLS material is read from the fixed keys regardless of the projection:

• redis/tls.crt — client TLS certificate (PEM)
• redis/tls.key — client TLS private key (PEM)
• redis/ca.crt — CA certificate for server verification (PEM)

Any secret.Provider that resolves these slash-separated keys serves them, such as the secret.FileProvider the infrastructure package roots at the mounted TLS secrets directory.

client, err := redis.New(ctx)
if errors.Is(err, infrastructure.ErrNotConfigured) {
    // Redis is not configured in this environment; skip or use a default.
}

Overriding configuration when reading from Kubernetes ¶

New accepts functional options that let callers override specific aspects of the configuration derived from the infrastructure config. Authentication and topology fields (Addrs, MasterName, SentinelUsername, SentinelPassword, Username, Password, DB, TLSConfig) are always sourced from the infrastructure config and its secret providers; they cannot be overridden via WithClientConfig.

Use WithClientConfig to override connection-pool, timeout, retry, and naming fields:

client, err := redis.New(ctx,
    redis.WithClientConfig(&redis.Config{
        DialTimeout:     500 * time.Millisecond,
        ReadTimeout:     1 * time.Second,
        WriteTimeout:    1 * time.Second,
        PoolSize:        20,
        MinIdleConns:    5,
        MaxIdleConns:    10,
        PoolTimeout:     2 * time.Second,
        ConnMaxIdleTime: 5 * time.Minute,
        ConnMaxLifetime: 30 * time.Minute,
        MaxRetries:      3,
        MinRetryBackoff: 8 * time.Millisecond,
        MaxRetryBackoff: 512 * time.Millisecond,
        Name:            "cache",
        Namespace:       "myservice",
        Subsystem:       "redis",
    }),
)

Use WithLogger, WithRegisterer, and WithTracer to attach observability dependencies sourced from the application's app.App:

client, err := redis.New(ctx,
    redis.WithLogger(a.Logger()),
    redis.WithRegisterer(a.Metrics().Registerer()),
    redis.WithTracer(a.Tracer()),
)

Connection parameters for another client library ¶

The rules above, which Secret keys the secret_ref format maps each credential to, addresses read from the contract or from the Secret, inline values winning over the Secret, and the TLS configuration assembled from the mounted files, live in this package. A service that keeps its own client library, for example rueidis for pub/sub and transactions, would otherwise have to reimplement them. ConnectionParams applies the same rules New does and returns the resolved Params without constructing a client:

infra, err := infrastructure.DefaultConfig()
if err != nil {
	log.Fatal(err)
}

params, err := redis.ConnectionParams(ctx, infra)
if err != nil {
	log.Fatal(err)
}

// params.Addrs, params.MasterName, params.Username, params.Password,
// params.SentinelUsername, params.SentinelPassword, params.DB and
// params.TLSConfig feed the service's own client.

Params.Password and Params.SentinelPassword are secret.Secret values and redact themselves when printed.