BaseHarbor v0.4.8

BaseHarbor v0.4.8

v0.4.8 turns the capability platform into something applications can use not only at deployment time, but also while they are running.

The release combines four related steps:

1. continuous repository-to-contract reconciliation;
2. secure application-time resource operations, with S3 as the first real dynamic resource;
3. provider-neutral metrics collection with Prometheus as the first Compose reference provider;
4. explicit directional cross-application connectivity without weakening application isolation.

The application contract stays product-neutral throughout. BaseHarbor adds more infrastructure behavior without requiring applications to become BaseHarbor-specific.

Continuous application evolution

BaseHarbor now treats application intent as evolving desired state rather than a one-time setup questionnaire.

Repository inspection can distinguish capabilities that are already satisfied from new, ambiguous or stale evidence. Newly detected requirements remain suggestions until explicitly accepted; failure to rediscover an existing capability never authorizes BaseHarbor to remove it.

Runtime-operation evidence is also separated from authorization. Detecting code that may create an S3 bucket or register a metrics source does not grant that operation automatically.

This gives BaseHarbor one path from initial adoption through later application growth without regenerating or replacing the application's contract.

Runtime Resource API

v0.4.8 completes the first real application-time resource path.

A running application can use the per-application Runtime Resource API for explicitly authorized capability operations. Mutations are asynchronous and idempotent, with persistent operation state that survives broker restart.

The security boundary remains strict:

• the per-application broker has no Docker/Podman socket;
• provider-global administrator credentials never enter the application workload or broker;
• authorization is service-scoped rather than application-wide;
• runtime resources remain application-owned;
• cross-application read/bind/delete is denied;
• secret-bearing bindings are returned only through the authenticated binding path;
• operation metadata remains free of credentials.

Development brokers also expose the embedded OpenAPI 3.1 documentation on a loopback-only port. Interactive API documentation is on by default for development and remains off by default for test/staging/production.

Dynamic S3 resources

object-storage.s3/v1 is the first capability wired through the Runtime Resource API.

An authorized application service can create, inspect and delete an S3 bucket at runtime. BaseHarbor executes the provider mutation through the shared mTLS Runtime Provider Executor rather than giving the application provider-global credentials.

SeaweedFS remains the first reference provider. Runtime-created buckets receive scoped credentials and can be consumed through the normal S3 API with authenticated Put/Get verification.

The same application-facing capability remains suitable for future Ceph RGW, AWS S3 or other conforming providers.

Provider-neutral metrics

Applications can declare a normal OpenMetrics-compatible endpoint:

workload:
  compose: compose.yaml
  services:
    - api

metrics:
  sources:
    - name: application
      service: api
      port: 8080
      path: /metrics

That source is represented by metrics/v1. There is no prometheus: true field and no Prometheus target configuration in baseharbor.yaml.

Prometheus 3.14.0 is the first Compose reference provider.

BaseHarbor:

• detects conventional OpenMetrics//metrics repository evidence;
• generates file-discovery targets automatically;
• labels series with application/environment/service/source identity;
• requires a real successful scrape visible as up=1;
• supports both statically declared and explicitly authorized runtime-created metrics sources;
• does not start Grafana, Loki or Tempo as a side effect.

Generic provider placement

During the metrics implementation, v0.4.8 closes a broader architecture gap.

Provider placement is now an explicit generic BaseHarbor domain:

Capability
  -> Provider
  -> Placement
       - application
       - shared
           - optional sharing boundary
       - external
  -> Runtime realization of the selected placement

The normal developer path remains simple. BaseHarbor chooses safe defaults unless an operator deliberately asks for more control.

For Prometheus the current Compose implementation supports:

• shared — the safe default;
• shared with a named sharing boundary;
• application — a dedicated application-scoped Prometheus instance.

The generic model supports external, but the Prometheus reference provider does not advertise external placement in v0.4.8 because an external metrics collection adapter is not implemented yet. Such a request fails before mutation instead of being silently downgraded.

Advanced Compose operators can currently override Prometheus placement through deployment state:

BASEHARBOR_PROVIDER_PROMETHEUS_SCOPE=shared|application
BASEHARBOR_PROVIDER_PROMETHEUS_SHARING_BOUNDARY=<name>

This follows BaseHarbor's UX rule:

Convention by default, configuration by choice.

Provider placement remains outside portable application intent.

The placement scopes now have strict provider-instance meaning:

• application is a dedicated provider instance for exactly one application/environment; Compose realizes it with dedicated provider runtime state;
• shared is lazy BaseHarbor Platform/Core Runtime infrastructure and remains shared even when only one application currently consumes it;
• external remains outside BaseHarbor lifecycle ownership.

Explicit cross-application connectivity

v0.4.8 also adds a minimal platform-level connectivity policy for cases where isolated applications must communicate:

app-a/api -> app-b/sql

The rule is written once. It is not duplicated in both application contracts and it is independent from provider sharing.

BaseHarbor resolves the concrete environment, runtime service, target network and target TCP port from runtime state. Explicit environment or port qualification is required only when resolution is ambiguous.

Compose preserves the direction technically. Source and target are not placed on one common bridge network. BaseHarbor creates a connection-specific source link and a hardened relay from the version-matched BaseHarbor Runtime image. Only the source and relay join that link; the relay additionally joins one target network and forwards only to the resolved target service/port. The target never joins the source link.

The relay has no host-published port or Docker/Podman socket, runs non-root with a read-only root filesystem, drops Linux capabilities and enables no-new-privileges.

Connectivity policy survives app down; relay runtime is suspended and reconciled on later app up/apply. Application/global destroy fails closed while connectivity policy still references managed applications.

Zero-Trust metrics isolation

Shared does not mean flat access.

Every participating application receives its own isolated metrics network. Shared Prometheus is attached only to the application networks explicitly registered for its placement boundary.

This means five applications can safely use different shapes on one BaseHarbor installation, for example:

App A + B -> shared/default
App C     -> application-scoped
App D + E -> shared/team-x

without exposing D/E's provider trust boundary to A/B.

Runtime metrics registration is service-scoped. A service can register only itself, and the runtime API accepts target port/path semantics rather than arbitrary hosts or URLs. BaseHarbor derives the actual scrape identity server-side.

Target state contains no application credentials or provider-global secrets.

Placement changes are lifecycle-safe

Provider placement is persisted in the protected provider registry.

Lifecycle cleanup therefore uses the registered/current placement rather than assuming that today's environment override still matches the placement used during the previous apply.

When placement changes, BaseHarbor converges and verifies the new metrics path first, then removes the previous provider target/trust-edge state, and only afterward reconciles the provider registry.

Runtime-only metrics permissions also receive protected provider-registry state even when no static metrics.sources entry exists.

Collection policy

Metrics collection remains separate from provider placement.

Compose defaults:

• dev / development: enabled;
• test / staging / production: disabled;
• BASEHARBOR_METRICS_ENABLED=true|false: explicit operator override.

An application can keep metrics/v1 intent while collection is disabled for a deployment. In that case BaseHarbor does not resolve or provision a metrics provider.

Global and application lifecycle

Application destroy removes only the application's metrics state according to the registered placement:

• shared placement removes that application's targets and trust-edge registration;
• application placement removes the dedicated Prometheus instance;
• external providers remain externally lifecycle-owned.

Global baha destroy --yes enumerates and removes every BaseHarbor-owned shared Prometheus instance, including named sharing boundaries.

Shared provider lifetime remains independent from a single application. Global baha down stops existing shared Platform/Core Runtime provider containers without deleting their networks, volumes or provider state; baha up resumes those providers and reconciles persisted cross-application connections. Application-scoped provider runtimes remain owned by their application lifecycle.

Compatibility and upgrade impact

Manifest version remains 1.

Existing applications without metrics intent remain unchanged. An unused Prometheus deployment override does not affect applications that do not use metrics/v1.

Existing OTLP applications remain unchanged. telemetry.otlp/v1 and metrics/v1 are deliberately separate:

• OTLP describes application telemetry export transport;
• metrics/v1 describes an application-provided metrics source.

The provider-registry format remains backward-compatible; the new sharing-boundary field is additive.

Kubernetes and OpenShift are not implemented by v0.4.8. The placement model is deliberately independent from Compose networks/projects so later Kubernetes namespaces/clusters, OpenShift projects, Helm releases and Operators can implement the same semantics without changing application intent.

Security

The Prometheus provider:

• has no Docker/Podman socket;
• uses a read-only root filesystem;
• drops Linux capabilities;
• enables no-new-privileges;
• publishes its HTTP API on host loopback only;
• consumes target state read-only;
• receives no application credentials through target discovery.

The Runtime Resource API and provider executor continue to use application/workload identity, mTLS and least-privilege authorization.

Intentionally deferred

v0.4.8 does not add:

• an external Prometheus collection adapter;
• Grafana dashboards;
• Loki log storage;
• Tempo trace storage;
• alert routing/rule management;
• VictoriaMetrics/Mimir implementations;
• automatic routing of OTLP metrics into Prometheus storage;
• Kubernetes/OpenShift ServiceMonitor realization;
• Kubernetes/OpenShift/Helm/Operator runtime implementation;
• provider-selection Web UI.

These remain later provider/runtime tracks. The v0.4.8 goal is to establish the safe, replaceable contracts they can build on without rewriting applications.