Skip to content

BaseHarbor v0.4.21

Status: Work in progress

Release umbrella: #569

Highlights

v0.4.21 closes the remaining application-consumption, credential/access and availability semantics before the v0.5 contract freeze.

Logical application-to-application consumption

Applications can declare that one logical component consumes an interface exposed by another logical component without embedding Docker, Podman, Kubernetes, OpenShift, namespace, Pod, container or node identity into portable intent.

Same-application and cross-application consumption use the same logical contract. Runtime placement, replica count, rescheduling, rolling replacement and failover do not change the producer/consumer relationship.

One explicit credential ownership model

BaseHarbor distinguishes three credential classes consistently:

  • human / management identity;
  • application-service credentials;
  • BaseHarbor-internal machine identity.

Application business users, groups and roles remain application-owned. BaseHarbor does not introduce a parallel business-user or business-RBAC model.

Standards-first management access

Managed human-facing surfaces expose an explicit authentication integration class:

  • native OIDC/OAuth2;
  • an existing standards-based authentication adapter;
  • provider-native credentials;
  • unsupported.

The small admin, edit, view, audit role profile applies only to BaseHarbor-managed infrastructure surfaces. Providers report limited or unsupported mappings instead of pretending to enforce finer authorization.

Safer secret ownership, projection and rotation

BaseHarbor distinguishes authoritative secret state from runtime projections.

Secret-bearing canonical state remains protected. Runtime-readable files are separate read-only projections where required, while environment variables remain a compatibility delivery mechanism rather than the preferred secret transport.

Interactive secret replacement requires matching hidden confirmation before mutation. Credential and PKI changes use an explicit prepare/reconcile/verify/ retire lifecycle where the selected provider/runtime supports continuity.

Portable availability and HA intent

The normal HA decision is intentionally small:

ha: true

Optional sparse overrides can change HA for a specific logical component/capability or request a fixed instance count.

Runtime and capability-provider availability are negotiated independently. If the selected realization cannot satisfy a requested guarantee, BaseHarbor fails before mutation rather than silently downgrading.

Availability is part of the existing Application, Runtime Provider and Capability Provider model; v0.4.21 does not introduce a second HA lifecycle.

Provider-native HA and stable endpoints

For managed providers whose v0.4.21 realization is verified, ha: true uses the provider's established availability mechanism rather than duplicating a single-process topology.

Verified provider/runtime work in this release includes:

  • Valkey with a multi-member topology, Sentinel and a stable access endpoint;
  • MongoDB with a replica set behind the stable logical database binding;
  • RabbitMQ with a multi-member cluster, quorum-aware messaging semantics and stable management access;
  • SeaweedFS with a distributed object-storage realization and stable S3/admin access;
  • managed Keycloak with multiple application members, HA PostgreSQL backing, stable issuer/discovery/JWKS/Admin surfaces and credential/signing/admin rotation continuity;
  • OpenTelemetry Collector HA transport;
  • Prometheus HA realization;
  • Loki HA ingestion/query continuity behind a stable access endpoint;
  • Tempo HA ingestion/query continuity across query frontend, distributor and replicated Redpanda-backed ingestion components;
  • the local exposure/developer gateway preserving stable canonical HTTPS routing across backend replacement and configuration/TLS reload.

PostgreSQL/OpenBao control-plane HA remains part of the release acceptance and must be complete before the release is finalized.

Honest failure domains

On single-host Docker/Podman, provider HA protects the failure modes the local runtime can honestly survive, such as member/process loss and rolling maintenance inside that runtime host.

It does not claim runtime-host failure tolerance.

The local development/exposure gateway also has one loopback host-port owner. BaseHarbor therefore reports stable routing/hot-reload continuity there without labelling the ingress path as redundant host-level HA.

Identity and management continuity

Managed Keycloak keeps one stable issuer/discovery/JWKS contract and stable Admin surface while individual members fail and recover.

The v0.4.21 identity work also verifies client-secret rotation, signing-key rotation and replacement of the managed administrative credential without changing the logical application identity contract.

Observability continuity

The shipped observability stack now has explicit HA realization and runtime verification for OpenTelemetry Collector, Prometheus, Loki and Tempo where the selected local runtime/provider combination supports it.

Ingestion/query endpoints remain logical/stable application-facing contracts; member topology remains provider/runtime realization state.

Truthful status and evidence

Availability negotiation is surfaced through the same shared semantics used by status, doctor, JSON/MCP and lifecycle evidence.

BaseHarbor distinguishes:

  • requested guarantees;
  • resolved provider/runtime guarantees;
  • satisfied versus unsupported guarantees;
  • explicit non-HA exceptions;
  • failure-domain limits.

A process being RUNNING is never treated as proof that an HA guarantee is satisfied.

Upgrade notes

BaseHarbor is still pre-v1 and the v0.5 compatibility freeze has not happened yet. v0.4.21 intentionally replaces incorrect pre-freeze assumptions instead of carrying compatibility shims for behavior that has not been frozen.

Applications should keep portable intent sparse and provider-neutral. Runtime member names, replica identities and provider-native clustering details do not belong in baseharbor.yaml.