Configuration

You build a pattern with keyword arguments. You tune it in deployment with environment variables. No code change between the two.

Build with keyword arguments

Pass the name first, then the settings:

from grelmicro.coordination import Lock

lock = Lock("cart", lease_duration=60, retry_interval=0.1)

Patterns with variants use factory methods:

from grelmicro.resilience import RateLimiter

api = RateLimiter.sliding_window("api", limit=100, window=60)

That is the whole story for code. Every value lives next to the pattern, easy to read and easy to test.

Tune with environment variables

The deployment overrides any field without touching code. Set the environment variable for the field and grelmicro reads it at startup.

The variable name is built from the pattern and the instance name:

GREL_{PATTERN}_{NAME}_{FIELD}

A Lock("cart") reads its lease duration from GREL_LOCK_CART_LEASE_DURATION:

export GREL_LOCK_CART_LEASE_DURATION=120
export GREL_LOCK_CART_RETRY_INTERVAL=0.2

The instance name becomes the namespace. Names with hyphens, dots, slashes, or colons normalise into uppercase segments (payments-eu becomes PAYMENTS_EU, cart.v2 becomes CART_V2).

The default instance drops the name segment, so a Lock("default") reads the bare GREL_LOCK_LEASE_DURATION. Because the default instance owns the bare GREL_{PATTERN}_ namespace, name your other instances to avoid clashing with a field name (a Lock("lease") would share GREL_LOCK_LEASE_DURATION with the default instance). This is rare in practice.

A value passed in code wins over the environment. So a hard-coded Lock("cart", lease_duration=60) ignores GREL_LOCK_CART_LEASE_DURATION. Leave a field out of the constructor to let the deployment set it.

Prefix reference

Pattern	Prefix
Lock("default")	GREL_LOCK_
Lock("cart")	GREL_LOCK_CART_
TaskLock("etl")	GREL_TASKLOCK_ETL_
LeaderElection("svc")	GREL_LEADERELECTION_SVC_
RateLimitFilter()	GREL_RATELIMITFILTER_
RateLimitFilter(env_name="audit")	GREL_RATELIMITFILTER_AUDIT_
DuplicateFilter()	GREL_DUPLICATEFILTER_
DuplicateFilter(env_name="audit")	GREL_DUPLICATEFILTER_AUDIT_
HealthChecks()	GREL_HEALTH_
log.configure()	GREL_LOG_

Each pattern page lists its own fields and the exact variable names.

Defaults reference

The most important defaults for operators. All times are in seconds. Override any of them with the pattern prefix above plus the field name, uppercased.

Pattern	Field	Default
Lock	lease_duration	60
Lock	retry_interval	0.1
TaskLock	lease_duration	60
TaskLock	min_hold_duration	1
LeaderElection	lease_duration	15
LeaderElection	renew_deadline	10
LeaderElection	retry_interval	2
LeaderElection	backend_timeout	5
TTLCache	ttl	60
RateLimiter	fail_open	False
CircuitBreaker	error_threshold	5
CircuitBreaker	success_threshold	2
CircuitBreaker	reset_timeout	30
Retry	attempts	3
Retry	backoff.base_delay	0.1
Retry	backoff.max_delay	30
Bulkhead	max_concurrent	None (unbounded)
HealthChecks	timeout	5
HealthChecks	cache_ttl	1
Idempotency	ttl	86400 (1 day)

TTLCache and Idempotency set their ttl in code, not from the environment. Timeout.seconds, Fallback.when, and Fallback.default are required and have no default.

Advanced

The kwargs-and-env path covers most apps. When you need more, the Advanced configuration page covers:

• Building from a Pydantic config object with from_config.
• Composing settings under one pydantic-settings tree.
• Custom env prefixes with env_prefix= and disabling env reads with env_load=False.
• The full resolution order contract.

For live reload from a Kubernetes ConfigMap, see Live reconfiguration.