stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

docs consolidation work

Browse Source
This commit is contained in:
StellaOps Bot
2025-12-25 10:53:53 +02:00
parent b9f71fc7e9
commit deb82b4f03
117 changed files with 852 additions and 847 deletions
Download Patch File Download Diff File Expand all files Collapse all files

76
docs/modules/export-center/mirror-bundles.md
View File

@@ -92,11 +92,11 @@ delta/
manifest.diff.json # summary of counts, hashes, base export metadata
```
- **Base lookup:** The worker verifies that the base export is reachable (download path or OCI reference). If missing, the run fails with `ERR_EXPORT_BASE_MISSING`.
- **Change detection:** Uses deterministic hashing of normalized records to compute additions/updates. Indexes are regenerated only for affected subjects.
- **Application order:** Consumers apply deltas sequentially. A `resetBaseline=true` flag instructs them to drop cached state and apply the bundle as a full refresh.
- **Tombstones required:** Every removal must emit a tombstone entry plus the `removed` list; deltas without tombstones fail verification (`verify-export-kit.sh`).
- **Integrity headers:** Each delta bundle exports `Digest`, `X-Stella-Signature`, and `X-Stella-Immutability` derived from the OCI annotation `io.stellaops.export.manifest-digest`. Consumers must validate before applying.
- **Base lookup:** The worker verifies that the base export is reachable (download path or OCI reference). If missing, the run fails with `ERR_EXPORT_BASE_MISSING`.
- **Change detection:** Uses deterministic hashing of normalized records to compute additions/updates. Indexes are regenerated only for affected subjects.
- **Application order:** Consumers apply deltas sequentially. A `resetBaseline=true` flag instructs them to drop cached state and apply the bundle as a full refresh.
- **Tombstones required:** Every removal must emit a tombstone entry plus the `removed` list; deltas without tombstones fail verification (`verify-export-kit.sh`).
- **Integrity headers:** Each delta bundle exports `Digest`, `X-Stella-Signature`, and `X-Stella-Immutability` derived from the OCI annotation `io.stellaops.export.manifest-digest`. Consumers must validate before applying.
Example `manifest.diff.json` (delta):
@@ -182,40 +182,40 @@ sequenceDiagram
3. Re-run integrity checks (`mirror verify <path>`).
- **Audit logging:** Export Center logs `mirror.bundle.created`, `mirror.delta.applied`, and `mirror.encryption.enabled` events. Consume them in the central observability pipeline.
## 7. Validation checklist (Trivy / mirror bundles)
- Download and verify:
- `stella export download <exportId> --format mirror`
- `stella export verify <exportId>`
- Delta ordering:
- Ensure `manifest.diff.json.baseExportId` exists locally before applying delta.
- Track applied order in `appliedExportIds.log`.
- Trivy adapter (if enabled):
- `stella export trivy-validate --bundle mirror-YYYYMMDD.tar.zst --policy ./policies/export-center.rego`
- Dry-run import:
- `stella export mirror-validate --bundle mirror-YYYYMMDD.tar.zst --dry-run`
- Post-import checks:
- Recompute SHA256 for `manifest.yaml` and a sample data file; compare to manifest.
- Run `mirror verify` (Offline Kit) and confirm zero mismatches.
- Confirm OCI annotations `io.stellaops.export.profile/run/manifest-digest/provenance-ref` match the bundle being applied.
## 8. Troubleshooting
| Symptom | Meaning | Action |
|---------|---------|--------|
| `ERR_EXPORT_BASE_MISSING` | Base export not available | Republish base bundle or rebuild as full export. |
| Delta applies but mirror misses entries | Deltas applied out of order | Rebuild from last full bundle and reapply in sequence. |
## 7. Validation checklist (Trivy / mirror bundles)
- Download and verify:
- `stella export download <exportId> --format mirror`
- `stella export verify <exportId>`
- Delta ordering:
- Ensure `manifest.diff.json.baseExportId` exists locally before applying delta.
- Track applied order in `appliedExportIds.log`.
- Trivy adapter (if enabled):
- `stella export trivy-validate --bundle mirror-YYYYMMDD.tar.zst --policy ./policies/export-center.rego`
- Dry-run import:
- `stella export mirror-validate --bundle mirror-YYYYMMDD.tar.zst --dry-run`
- Post-import checks:
- Recompute SHA256 for `manifest.yaml` and a sample data file; compare to manifest.
- Run `mirror verify` (Offline Kit) and confirm zero mismatches.
- Confirm OCI annotations `io.stellaops.export.profile/run/manifest-digest/provenance-ref` match the bundle being applied.
## 8. Troubleshooting
| Symptom | Meaning | Action |
|---------|---------|--------|
| `ERR_EXPORT_BASE_MISSING` | Base export not available | Republish base bundle or rebuild as full export. |
| Delta applies but mirror misses entries | Deltas applied out of order | Rebuild from last full bundle and reapply in sequence. |
| Decryption fails | Recipient key mismatch or corrupted bundle | Confirm key distribution and re-download bundle. |
| Verification errors | Signature mismatch | Do not import; regenerate bundle and investigate signing pipeline. |
| Manifest hash mismatch | Files changed after extraction | Re-extract bundle and re-run verification; check storage tampering. |
## 9. References
- [Export Center Overview](overview.md)
- [Export Center Architecture](architecture.md)
- [Export Center API reference](api.md)
- [Export Center CLI Guide](cli.md)
| Verification errors | Signature mismatch | Do not import; regenerate bundle and investigate signing pipeline. |
| Manifest hash mismatch | Files changed after extraction | Re-extract bundle and re-run verification; check storage tampering. |
## 9. References
- [Export Center Overview](overview.md)
- [Export Center Architecture](architecture.md)
- [Export Center API reference](api.md)
- [Export Center CLI Guide](cli.md)
- [Concelier mirror runbook](../concelier/operations/mirror.md)
- [Aggregation-Only Contract reference](../../ingestion/aggregation-only-contract.md)
- [Aggregation-Only Contract reference](../../aoc/aggregation-only-contract.md)
> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.