Maintaining Service Catalogs with Machine-Derived Declarations

The Problem with Manual Service Documentation

The core issue addressed is the silent failure mode of manual documentation. The author illustrates this with a Go binary versioning example where a misconfigured build flag leads to incorrect version reporting without any build or test failures. This scenario directly mirrors how manually updated service catalogs can become stale and misleading, providing incorrect information without any immediate feedback mechanism to flag the divergence from reality. This can lead to critical operational issues and misinformed architectural decisions.

Cost of Drift and Data Inconsistency

Solution: One Declaration, Machine-Derived Catalog

The proposed solution centers on establishing a single, machine-readable declaration as the source of truth for a service. This declaration, often a manifest file within the service's repository, defines its core components (daemons, resources, dependencies). The service catalog then becomes a _rendering_ of this manifest and other code artifacts, rather than a manually maintained table. This approach ensures that any change in the service's definition in the manifest or code automatically updates its representation in the catalog, with CI/CD checks catching any inconsistencies or drifts.

service:
  name: <service>
  version: 0.1.0
  daemons:
  - name: server
    handlers: [grpc]
  - name: worker
    handlers: [scheduler]
  infra:
    postgres:
    - name: main
      migrations: false

• Daemons and their role: Synchronous handlers, background processing.
• Resources: Databases, queues, schedules, migrations, all defined in the manifest.
• Environment variables: Generated catalog, with drift checks integrated into the build process.
• Default metrics and snapshots: What the service exposes by default, derived from its code.
• Owner and team: A field within the declaration, changed via a commit.
• Incoming links: Determined from actual traffic/call graphs, not self-reported.
• Declared commitments: Service Level Objectives (SLOs) and Service Level Indicators (SLIs), defined as part of the declaration.

This pattern significantly reduces the operational overhead of maintaining accurate service documentation and provides a reliable source of truth for understanding complex microservice architectures. It enforces discipline by making architectural decisions explicit in code and configurations, and leveraging automation to prevent informational entropy.