What this proposes:

Add a tempo-cli migrate config command that takes a Tempo 2.x configuration file and outputs a valid 3.0 configuration. This eliminates the most error-prone step of the migration — manually editing config files.

Usage:

tempo-cli migrate config [--kafka-address=<addr>] [--kafka-topic=<topic>] <2.x-config.yaml>

Outputs to stdout. The user reviews, saves, and deploys.

What it does:

1. Parse input YAML into a generic map (not Tempo structs — preserves unknown fields, passes through env vars like ${VAR} as-is).

2. Detect deployment mode from target field. Monolithic if target: all or absent (default). Accept --mode flag to override.

3. Delete 2.x-only blocks:

   • ingester
   • ingester_client
   • compactor

4. Add 3.0 blocks (microservices only):

   • ingest.kafka.address and ingest.kafka.topic from flags
   • Error if --kafka-address isn't provided in microservices mode

5. Modify overrides for parallel operation:

   • Set overrides.defaults.compaction.compaction_disabled: true
   • Walk every tenant key under overrides:, set compaction.compaction_disabled: true on each
   • If the config references an external per-tenant file (overrides.per_tenant_override_config), warn: "External overrides file at needs compaction_disabled added manually for each tenant"

6. Clean up metrics-generator:

   • Remove local_blocks processor config (any level — defaults and per-tenant)
   • Warn if it was present: "local-blocks processor removed — block building is handled by the block-builder component"

7. Monolithic-specific: skip step 4, don't add ingest or block_builder blocks.

8. Validate output through Tempo's 3.0 config validation. Report errors.

9. Print to stdout with a comment header:

   # Generated by tempo-cli migrate config
   # Review before deploying. Remove compaction_disabled after decommissioning 2.x.

What it deliberately doesn't do:

• Doesn't touch storage:, server:, distributor:, query_frontend:, memberlist: — those carry over unchanged
• Doesn't set partition count or block-builder replicas — those are deployment concerns, not config
• Doesn't handle legacy overrides format — detects it and errors with "run tempo-cli migrate overrides-config first"

Example output:

$ tempo-cli migrate config --kafka-address=kafka:9092 --kafka-topic=tempo-traces old-config.yaml > new-config.yaml

WARN: local_blocks processor removed from metrics_generator config
WARN: External per-tenant overrides file /etc/tempo/overrides.yaml needs compaction_disabled added for each tenant

Implementation notes:

Working at the map[string]interface{} level loses YAML comments and key ordering from the original file. That's acceptable since the output is a starting point, not a final config. Working at the YAML AST node level would preserve structure but adds complexity for marginal benefit.

Related:

• Migration guide: [DOC] Migration guide for Tempo 3.x #6814
• Existing command: tempo-cli migrate overrides-config