Skip to content

FleetInventoryService

Target

This page describes intended behaviour or structure. No implementation is claimed unless a section is explicitly marked Current implementation or Evidence.

Bounded context BC-35 Fleet Inventory & SLOs
Platform / plane Product Fleet Operations / Execution
Deployment granularity module of host · host FleetOperationsHost
Status target · ConnectSoft.Factory.Fleet.Inventory
Built from connectsoft-microservice · libraries: connectsoft-extensions-saas-abstractions, connectsoft-extensions-messaging-model, connectsoft-extensions-persistence-model-nhibernate, connectsoft-extensions-diagnostics-health-checks
Decisions ADR-0018
Traceability FR-09 FUX-05 NFR-06 NFR-17 XL-10 XL-16

Purpose and responsibilities

FleetInventoryService keeps the operated product and its instances: for each customer tenant and environment, the release it runs, its region, state (provisioning, running, degraded, upgrading, suspended, off-boarding) and health observed every two minutes through the product gateway and the HealthChecks aggregator. It records which template, blueprint and agent releases generated the product, so a template upgrade knows which products it affects, and the managed edition (self-operated, managed, managed-plus) from the owner's subscription (D34), which sets the objective floors and the on-call commitment. Product objectives are defined here and registered with the Observability platform's SLO service, whose breaches mark instances degraded.

Context and boundaries

flowchart LR
    S["FleetInventoryService"]
    FleetRolloutService["FleetRolloutService"] -->|grpc| S
    FleetIncidentService["FleetIncidentService"] -->|grpc| S
    StudioBff["StudioBff"] -->|sync-http| S
    S -->|grpc| ReleaseService["ReleaseService"]
    S -->|grpc| RuntimeEnvironmentService["RuntimeEnvironmentService"]
    S -->|grpc| SloService["SloService"]
    S -->|grpc| FactoryCommercialService["FactoryCommercialService"]
    S -->|sync-http| ext_generated_products["ext-generated-products"]
    S -. "ProductOnboarded" .-> E_ProductOnboarded(("event"))
    S -. "ProductInstanceStateChanged" .-> E_ProductInstanceStateChanged(("event"))
    S -. "ProductObjectiveDefined" .-> E_ProductObjectiveDefined(("event"))
Hold "Alt" / "Option" to enable pan & zoom

Instances change release through promotions and rollouts, never by hand; version skew across a product's instances is a metric and is bounded by the rollout policy. A self-operated product is inventoried for upgrade offers but not operated.

Domain model

OperatedProduct — A generated product under fleet operation: its project, the generating template and blueprint releases, its product gateway (GW-07), its current product release, support edition and the customer tenants it serves. (catalog entry)

Field Type Required Description
productId string yes
tenantId string yes The Factory tenant that owns the product.
projectId string yes
name string yes
generatedBy json yes Template, blueprint and agent release ids.
currentReleaseId guid no
edition enum:ManagedEdition yes
gatewayRef string yes GW-07 endpoint reference.
instanceCount int yes
onboardedAt datetime yes

Invariants:

  • A product is operated only while its owner's subscription covers a managed edition; SelfOperated products are inventoried, not operated.
  • Instances inherit the product's release unless a rollout wave says otherwise; version skew across instances is visible and bounded by the rollout policy.

Events: ProductOnboarded, ProductInstanceStateChanged · Tables: OperatedProducts, ProductInstances · Repository: OperatedProductRepository

ProductObjective — An objective for a product (availability, latency, error rate, support response) per edition, defined here and measured by the Observability platform's SLO service with the product's instances as subjects. (catalog entry)

Field Type Required Description
objectiveId guid yes
tenantId string yes
productId string yes
kind string yes
target decimal yes
window string yes
sloId guid no Objective registered with SloService.
editionFloor enum:ManagedEdition yes

Invariants:

  • Edition floors cannot be loosened per product; a customer may buy a stricter edition, not a weaker objective.

Events: ProductObjectiveDefined · Tables: ProductObjectives · Repository: ProductObjectiveRepository

erDiagram
    OperatedProduct {
        string productId PK
        string tenantId
        string projectId
        string name
        json generatedBy
        guid currentReleaseId
        enum_ManagedEdition edition
        string gatewayRef
        int instanceCount
        datetime onboardedAt
    }
    ProductObjective {
        guid objectiveId PK
        string tenantId
        string productId
        string kind
        decimal target
        string window
        guid sloId
        enum_ManagedEdition editionFloor
    }
    ProductInstance {
        guid instanceId

        string customerTenantId

        string environmentId

        string region

        guid releaseId

        enum_InstanceState state

        string health

        datetime lastObservedAt

    }
    OperatedProduct ||--o{ ProductInstance : contains
Hold "Alt" / "Option" to enable pan & zoom

Entities and value objects

ProductInstance (entity, in OperatedProduct) — One running instance of the product for one customer tenant in one environment.

Field Type Required Description
instanceId guid yes
customerTenantId string yes
environmentId string yes
region string yes
releaseId guid yes
state enum:InstanceState yes
health string yes
lastObservedAt datetime yes

Data model and storage

Store Role Engine / profile Tables
Fleet operations store primary azure-sql / nhibernate-sqlserver OperatedProducts, ProductInstances, ProductObjectives
Table Owner Columns Indexes
dbo.OperatedProducts OperatedProduct 10 1
dbo.ProductInstances ProductInstance 10 3
dbo.ProductObjectives ProductObjective 8 1

Full DDL: appendix.

APIs

Method Path Operation Scope Side effects Idempotency Gateway Summary
GET /factory/fleet/products ListOperatedProducts factory.fleet.read read natural GW-03 Operated products with edition, current release, instance counts and health rollup.
GET /factory/fleet/products/{productId} GetOperatedProduct factory.fleet.read read natural GW-03 One product with instances per customer tenant and environment, releases, objectives and health.
POST /factory/fleet/products OnboardProduct factory.fleet.admin shared-write key-header GW-03 Onboard a generated product into fleet operation under a managed edition (subscription required; Workspace admin of the owning tenant).
GET /factory/fleet/products/{productId}/instances ListProductInstances factory.fleet.read read natural GW-03 Instances with state, release, region and health.
PUT /factory/fleet/products/{productId}/objectives/{kind} SetProductObjective factory.fleet.admin shared-write natural GW-03 Define or tighten a product objective (registered with SloService).
gRPC service Method Streaming Visibility Side effects Summary
Fleet GetInstance none internal read Resolve an instance for rollouts and incidents.

Messages

Event Topic Scope / v Aggregate Consumers Summary
ProductOnboarded fleet-inventory.products.v1.product-onboarded integration / 1 OperatedProduct StudioBff, AuditService, FactoryCommercialService, SloService A product is under fleet operation.
ProductInstanceStateChanged fleet-inventory.products.v1.product-instance-state-changed integration / 1 OperatedProduct FleetRolloutService, FleetIncidentService, StudioBff, DashboardService An instance changed state, release or health.
ProductObjectiveDefined fleet-inventory.objectives.v1.product-objective-defined integration / 1 ProductObjective SloService, StudioBff, AuditService A product objective exists or was tightened.

ProductOnboarded payload:

Field Type Required Description
productId string yes
tenantId string yes
projectId string yes
edition enum:ManagedEdition yes

ProductInstanceStateChanged payload:

Field Type Required Description
instanceId guid yes
productId string yes
tenantId string yes
customerTenantId string yes
environmentId string yes
fromState enum:InstanceState yes
toState enum:InstanceState yes
releaseId guid yes

ProductObjectiveDefined payload:

Field Type Required Description
objectiveId guid yes
tenantId string yes
productId string yes
kind string yes
target decimal yes
Command Handled by Result events Summary
OnboardProduct OperatedProduct ProductOnboarded
SetProductObjective ProductObjective ProductObjectiveDefined
Event Producer Handler Purpose
PromotionCompleted EnvironmentPromotionService UpdateInstanceRelease An instance runs a new release.
RollbackCompleted EnvironmentPromotionService UpdateInstanceRelease An instance was rolled back.
ObservedStateChanged RuntimeEnvironmentService UpdateInstanceHealth Health and staleness per instance.
SloBreached SloService MarkDegraded A product objective breached marks instances Degraded.
SloRecovered SloService MarkRecovered Back to Running.
SubscriptionChanged FactoryCommercialService ApplyEdition Managed edition follows the subscription.

Workers and jobs

Worker Trigger Output events Retry Idempotency key Summary
ProductHealthProbe schedule */2 * * * * ProductInstanceStateChanged fixed instanceId + window Calls each instance's health endpoint through its product gateway (GW-07) and the HealthChecks aggregator; updates health and staleness.

Actors and grains

None modelled

No grains are modelled for this item yet.

Sagas and long-running flows

None modelled

No sagas are modelled for this item yet.

stateDiagram-v2
    [*] --> Provisioning
    Provisioning --> Running: first healthy observation
    Running --> Degraded: objective breached or health failed
    Degraded --> Running: recovered
    Running --> Upgrading: rollout wave promoting
    Upgrading --> Running: promotion completed and baked
    Running --> Suspended: subscription lapsed or off-boarding handed over
    Suspended --> OffboardingRequested: off-boarding
    OffboardingRequested --> Offboarded: deletion completed
    Offboarded --> [*]
Hold "Alt" / "Option" to enable pan & zoom

Options and configuration

Section Key Type Default Reloadable Secret Summary
Fleet:Inventory EditionObjectiveFloors json { Managed: { availability: 0.995, supportResponseHours: 8 }, ManagedPlus: { availability: 0.999, supportResponseHours: 1 } } no no Objective floors per managed edition (D33, D34).

Metrics and observability

Metric Instrument Unit Dimensions Summary
connectsoft.factory.fleet.products updown {product} tenant, edition Operated products.
connectsoft.factory.fleet.instances updown {instance} productId, state, region Instances by state.
connectsoft.factory.fleet.version_skew gauge {release} productId Distinct releases running across a product's instances.

Security

Authentication client-credentials
Scopes factory.fleet.read (Read the fleet.); factory.fleet.admin (Onboard products and set objectives (Workspace admin of the owner, Platform admin).)
Roles Operator, WorkspaceAdmin, PlatformAdmin, Observer
Tenant isolation row-filter
Data classification confidential
Max side-effect class shared-write
Secrets —

Dependencies

Outbound

Target Kind Purpose Failure mode Required
ReleaseService grpc Release resolution. fail-fast yes
RuntimeEnvironmentService grpc Observed state per environment. degrade yes
SloService grpc Register product objectives. degrade yes
FactoryCommercialService grpc Managed edition from the subscription. fail-fast yes
ext-generated-products sync-http Health endpoints through GW-07. degrade yes

Inbound

Target Kind Purpose Failure mode Required
FleetRolloutService grpc Instances to roll out to. — yes
FleetIncidentService grpc Instance context for incidents. — yes
StudioBff sync-http Fleet views. — yes

Failure and recovery

Scenario Detection Recovery Data impact RTO (min)
Product health endpoint unreachable probe failures instance marked Degraded with staleness; incident opened by rule after the threshold none 10

NFR targets

Target Class value (pilot-projection) Override
latency_p95_ms 500 —
availability_pct 99.5 —
throughput_rps 100 —
rpo_minutes 15 —
rto_minutes 240 —
cost_class low —

Deployment

Granularity module of host · host FleetOperationsHost
Topologies saas-default, hybrid
Runtime —; replicas —–—
Ports —

Current implementation

Nothing beyond per-repository knowledge; the SaaS Tenants template holds the customer tenants of a generated product inside the product.

Later capabilities

Per-instance cost attribution from FinOps projections; customer-visible status pages; automatic objective suggestions from observed baselines.

Decisions and traceability

Family Ids
FR FR-09
FUX FUX-05
NFR NFR-06, NFR-17
XL XL-10, XL-16