stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity
Files
7b5bdcf4d3bee4e6f398d0226ba8cd3c2754e07a
git.stella-ops.org/docs/modules/devops/migrations/semver-style.md
master 7b5bdcf4d3 feat(docs): Add comprehensive documentation for Vexer, Vulnerability Explorer, and Zastava modules 
- Introduced AGENTS.md, README.md, TASKS.md, and implementation_plan.md for Vexer, detailing mission, responsibilities, key components, and operational notes.
- Established similar documentation structure for Vulnerability Explorer and Zastava modules, including their respective workflows, integrations, and observability notes.
- Created risk scoring profiles documentation outlining the core workflow, factor model, governance, and deliverables.
- Ensured all modules adhere to the Aggregation-Only Contract and maintain determinism and provenance in outputs.
2025-10-30 00:09:39 +02:00

2.3 KiB
Raw Blame History

SemVer Style Backfill Runbook

Last updated: 2025-10-11

Overview

The SemVer style migration populates the new normalizedVersions field on advisory documents and ensures provenance decisionReason values are preserved during future reads. The migration is idempotent and only runs when the feature flag concelier:storage:enableSemVerStyle is enabled.

Preconditions

  1. Review configuration – set concelier.storage.enableSemVerStyle to true on all Concelier services.
  2. Confirm batch size – adjust concelier.storage.backfillBatchSize if you need smaller batches for older deployments (default: 250).
  3. Back up – capture a fresh snapshot of the advisory collection or a full MongoDB backup.
  4. Staging dry-run – enable the flag in a staging environment and observe the migration output before rolling to production.

Execution

No manual command is required. After deploying the configuration change, restart the Concelier WebService or any component that hosts the Mongo migration runner. During startup you will see log entries similar to:

Applying Mongo migration 20251011-semver-style-backfill: Populate advisory.normalizedVersions for existing documents when SemVer style storage is enabled.
Mongo migration 20251011-semver-style-backfill applied

The migration reads advisories in batches (concelier.storage.backfillBatchSize) and writes flattened normalizedVersions arrays. Existing documents without SemVer ranges remain untouched.

Post-checks

  1. Verify the new indexes exist: 
    db.advisory.getIndexes()
    You should see advisory_normalizedVersions_pkg_scheme_type and advisory_normalizedVersions_value.
  2. Spot check a few advisories to confirm the top-level normalizedVersions array exists and matches the embedded package data.
  3. Run dotnet test for StellaOps.Concelier.Storage.Mongo.Tests (optional but recommended) in CI to confirm the storage suite passes with the feature flag enabled.

Rollback

Set concelier.storage.enableSemVerStyle back to false and redeploy. The migration will be skipped on subsequent startups. You can leave the populated normalizedVersions arrays in place; they are ignored when the feature flag is off. If you must remove them entirely, restore from the backup captured during preparation.