Bundle and Manifest Schema
Relevant source files
The following files were used as context for generating this wiki page:
The Bundle and Manifest Schema defines a uniform structure for troubleshooting data collected by the infrahub-collect tool. It ensures that diagnostic information, including logs, metrics, and service states, remains consistent across Docker Compose and Kubernetes deployments. The schema uses a bundle_information.json manifest as the authoritative record of collection outcomes.
Sources: dev/adr/0005-uniform-bundle-and-manifest.md, specs/archive/003-collect-tool/plan.md
Bundle Structure
The troubleshooting bundle is a compressed tar.gz archive. All collected data resides within a single top-level bundle/ directory. This layout ensures parity between different infrastructure backends.
The diagram shows the standard directory hierarchy within a troubleshooting archive.
Sources: specs/archive/003-collect-tool/contracts/bundle-layout.md:7-31
Directory Layout Details
| Directory | Content Description |
|---|---|
logs/ | Per-replica service logs. Kubernetes logs include .previous.log for restarts. |
database/ | Neo4j server logs (e.g., neo4j.log, debug.log). |
message-queue/ | RabbitMQ status, environment, and queue/exchange dumps. |
cache/ | Redis info, client lists, and masked configuration. |
server/ | Infrahub version, masked environment variables, and API schema. |
metrics/ | Resource usage data from docker stats or kubectl top. |
benchmark/ | Optional output from the --benchmark collector. |
Sources: specs/archive/003-collect-tool/contracts/bundle-layout.md:12-31
Manifest Schema
The bundle_information.json file resides at the root of the bundle. It provides metadata about the collection run and the status of individual collectors. The manifest uses a date-serial versioning format (e.g., 2026070200).
Sources: specs/archive/003-collect-tool/contracts/manifest.schema.json:10-23
Manifest Metadata Fields
| Field | Type | Description |
|---|---|---|
manifest_version | integer | Date-serial schema version. |
collect_id | string | UTC timestamp identifier (YYYYMMDD_HHMMSS). |
tool_version | string | Revision of the infrahub-collect binary. |
environment | string | Either docker or kubernetes. |
infrahub_version | string | Detected version of the Infrahub instance. |
log_lines | integer | The per-container log line limit applied to the run. |
Sources: specs/archive/003-collect-tool/contracts/manifest.schema.json:20-77
Collector Outcomes
The manifest tracks each diagnostic collector's result. If a collector fails or is skipped, the manifest must include a reason.
The relationship between the root manifest and individual collector results.
Sources: specs/archive/003-collect-tool/contracts/manifest.schema.json:78-112
Status Definitions
- success: The collector completed and wrote data to the bundle.
- failed: The collector encountered an error or timed out (standard timeout is 60s for dumps, 5m for transfers).
- skipped: The collector was not requested or its prerequisites (e.g., optional services) were missing.
Sources: specs/archive/003-collect-tool/contracts/manifest.schema.json:96-101, specs/archive/003-collect-tool/plan.md:31-36
Data Security and Masking
The collection framework includes a key-name secret masking mechanism. During the generation of the bundle, the tool identifies environment variables and configuration keys containing sensitive patterns (e.g., password, secret, token, key).
- Choke-point Masking: All environment and configuration dumps pass through a central masking function.
- Replacement: Sensitive values are replaced with
********before being written to the bundle. - Scope: Masking applies to server environment variables, Redis configuration, and RabbitMQ status/environment dumps.
Sources: specs/archive/003-collect-tool/plan.md:17-21, dev/adr/0004-key-name-secret-masking.md
Conclusion
The Bundle and Manifest Schema provides a predictable, cross-platform diagnostic format for Infrahub. By centralizing collection logic and using a versioned manifest, the system ensures that support engineers receive complete and auditable troubleshooting data regardless of the underlying deployment technology.