78 lines
5.4 KiB
Markdown
78 lines
5.4 KiB
Markdown
# Concelier Apple Security Update Connector Operations
|
||
|
||
This runbook covers staging and production rollout for the Apple security updates connector (`source:vndr-apple:*`), including observability checks and fixture maintenance.
|
||
|
||
## 1. Prerequisites
|
||
|
||
- Network egress (or mirrored cache) for `https://gdmf.apple.com/v2/pmv` and the Apple Support domain (`https://support.apple.com/`).
|
||
- Optional: corporate proxy exclusions for the Apple hosts if outbound traffic is normally filtered.
|
||
- Updated configuration (environment variables or `concelier.yaml`) with an `apple` section. Example baseline:
|
||
|
||
```yaml
|
||
concelier:
|
||
sources:
|
||
apple:
|
||
softwareLookupUri: "https://gdmf.apple.com/v2/pmv"
|
||
advisoryBaseUri: "https://support.apple.com/"
|
||
localeSegment: "en-us"
|
||
maxAdvisoriesPerFetch: 25
|
||
initialBackfill: "120.00:00:00"
|
||
modifiedTolerance: "02:00:00"
|
||
failureBackoff: "00:05:00"
|
||
```
|
||
|
||
> ℹ️ `softwareLookupUri` and `advisoryBaseUri` must stay absolute and aligned with the HTTP allow-list; Concelier automatically adds both hosts to the connector HttpClient.
|
||
|
||
## 2. Staging Smoke Test
|
||
|
||
1. Deploy the configuration and restart the Concelier workers to ensure the Apple connector options are bound.
|
||
2. Trigger a full connector cycle:
|
||
- CLI: `stella db jobs run source:vndr-apple:fetch --and-then source:vndr-apple:parse --and-then source:vndr-apple:map`
|
||
- REST: `POST /jobs/run { "kind": "source:vndr-apple:fetch", "chain": ["source:vndr-apple:parse", "source:vndr-apple:map"] }`
|
||
3. Validate metrics exported under meter `StellaOps.Concelier.Connector.Vndr.Apple`:
|
||
- `apple.fetch.items` (documents fetched)
|
||
- `apple.fetch.failures`
|
||
- `apple.fetch.unchanged`
|
||
- `apple.parse.failures`
|
||
- `apple.map.affected.count` (histogram of affected package counts)
|
||
4. Cross-check the shared HTTP counters:
|
||
- `concelier.source.http.requests_total{concelier_source="vndr-apple"}` should increase for both index and detail phases.
|
||
- `concelier.source.http.failures_total{concelier_source="vndr-apple"}` should remain flat (0) during a healthy run.
|
||
5. Inspect the info logs:
|
||
- `Apple software index fetch … processed=X newDocuments=Y`
|
||
- `Apple advisory parse complete … aliases=… affected=…`
|
||
- `Mapped Apple advisory … pendingMappings=0`
|
||
6. Confirm MongoDB state:
|
||
- `raw_documents` store contains the HT article HTML with metadata (`apple.articleId`, `apple.postingDate`).
|
||
- `dtos` store has `schemaVersion="apple.security.update.v1"`.
|
||
- `advisories` collection includes keys `HTxxxxxx` with normalized SemVer rules.
|
||
- `source_states` entry for `apple` shows a recent `cursor.lastPosted`.
|
||
|
||
## 3. Production Monitoring
|
||
|
||
- **Dashboards** – Add the following expressions to your Concelier Grafana board (OTLP/Prometheus naming assumed):
|
||
- `rate(apple_fetch_items_total[15m])` vs `rate(concelier_source_http_requests_total{concelier_source="vndr-apple"}[15m])`
|
||
- `rate(apple_fetch_failures_total[5m])` for error spikes (`severity=warning` at `>0`)
|
||
- `histogram_quantile(0.95, rate(apple_map_affected_count_bucket[1h]))` to watch affected-package fan-out
|
||
- `increase(apple_parse_failures_total[6h])` to catch parser drift (alerts at `>0`)
|
||
- **Alerts** – Page if `rate(apple_fetch_items_total[2h]) == 0` during business hours while other connectors are active. This often indicates lookup feed failures or misconfigured allow-lists.
|
||
- **Logs** – Surface warnings `Apple document {DocumentId} missing GridFS payload` or `Apple parse failed`—repeated hits imply storage issues or HTML regressions.
|
||
- **Telemetry pipeline** – `StellaOps.Concelier.WebService` now exports `StellaOps.Concelier.Connector.Vndr.Apple` alongside existing Concelier meters; ensure your OTEL collector or Prometheus scraper includes it.
|
||
|
||
## 4. Fixture Maintenance
|
||
|
||
Regression fixtures live under `src/StellaOps.Concelier.Connector.Vndr.Apple.Tests/Apple/Fixtures`. Refresh them whenever Apple reshapes the HT layout or when new platforms appear.
|
||
|
||
1. Run the helper script matching your platform:
|
||
- Bash: `./scripts/update-apple-fixtures.sh`
|
||
- PowerShell: `./scripts/update-apple-fixtures.ps1`
|
||
2. Each script exports `UPDATE_APPLE_FIXTURES=1`, updates the `WSLENV` passthrough, and touches `.update-apple-fixtures` so WSL+VS Code test runs observe the flag. The subsequent test execution fetches the live HT articles listed in `AppleFixtureManager`, sanitises the HTML, and rewrites the `.expected.json` DTO snapshots.
|
||
3. Review the diff for localisation or nav noise. Once satisfied, re-run the tests without the env var (`dotnet test src/StellaOps.Concelier.Connector.Vndr.Apple.Tests/StellaOps.Concelier.Connector.Vndr.Apple.Tests.csproj`) to verify determinism.
|
||
4. Commit fixture updates together with any parser/mapping changes that motivated them.
|
||
|
||
## 5. Known Issues & Follow-up Tasks
|
||
|
||
- Apple occasionally throttles anonymous requests after bursts. The connector backs off automatically, but persistent `apple.fetch.failures` spikes might require mirroring the HT content or scheduling wider fetch windows.
|
||
- Rapid Security Responses may appear before the general patch notes surface in the lookup JSON. When that happens, the fetch run will log `detailFailures>0`. Collect sample HTML and refresh fixtures to confirm parser coverage.
|
||
- Multi-locale content is still under regression sweep (`src/StellaOps.Concelier.Connector.Vndr.Apple/TASKS.md`). Capture non-`en-us` snapshots once the fixture tooling stabilises.
|