[mauroservienti]

Some ServiceControl versions change RavenDB index definitions, which triggers a side-by-side index rebuild at the first start-up after the upgrade. Until now there was no general guidance on how to handle this, only version-specific notes.

Changes

• servicecontrol/upgrades/index.md: new "Upgrades that rebuild indexes" section that:
  • explains how side-by-side index replacement works and why ingestion slows the rebuild down, or can prevent the automatic swap
  • warns that the replacement index needs at least as much storage as the index it replaces until the swap
  • describes how to upgrade multiple audit instances one at a time: disable ingestion with ServiceControl.Audit/IngestAuditMessages, upgrade, wait for the rebuild and swap, enable ingestion, move on to the next instance
  • notes the queue build-up with split audit queues or a single audit instance, and the equivalent setting for error instances
• servicecontrol/upgrades/6.19to6.20.md: adds a warning at the top about the MessagesViewIndex rebuild, and links the audit index section to the new procedure.

Verification

Validated against the ServiceControl codebase that index deployment does not depend on the ingestion setting:

• RavenPersistenceLifecycleHostedService is always registered by the RavenDB persistence and runs DatabaseSetup.Execute, which calls CreateIndexes at every start-up.
• IngestAuditMessages only controls whether the AuditIngestion hosted service is registered, and whether the audit queues are created during setup.
• On the error instance, IngestErrorMessages similarly only gates error queue creation and ingestion.

Mixed versions between the primary error instance and audit instances during a one-at-a-time upgrade are covered by ServiceControl backward compatibility.