stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity
Files
55464f84984ae579eca18456874ba5ccac6ccf29
git.stella-ops.org/docs/ui/downloads.md
root 68da90a11a
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
Restructure solution layout by module
2025-10-28 15:10:40 +02:00

14 KiB
Raw Blame History

StellaOps Console - Downloads Manager

Audience: DevOps guild, Console engineers, enablement writers, and operators who promote releases or maintain offline mirrors.
Scope: /console/downloads workspace covering artifact catalog, signed manifest plumbing, export status handling, CLI parity, automation hooks, and offline guidance (Sprint 23).

The Downloads workspace centralises every artefact required to deploy or validate StellaOps in connected and air-gapped environments. It keeps Console operators aligned with release engineering by surfacing the signed downloads manifest, live export jobs, parity checks against Offline Kit bundles, and automation hooks that mirror the CLI experience.

1 - Access and prerequisites

  • Route: /console/downloads (list) with detail drawer /console/downloads/:artifactId.
  • Scopes: downloads.read (baseline) and downloads.manage for cancelling or expiring stale exports. Evidence bundles inherit the originating scope (runs.read, findings.read, etc.).
  • Dependencies: Web gateway /console/downloads API (WEB-CONSOLE-23-005), DevOps manifest pipeline (deploy/downloads/manifest.json), Offline Kit metadata (manifest/offline-manifest.json), and export orchestrator /console/exports.
  • Feature flags: downloads.workspace.enabled, downloads.exportQueue, downloads.offlineParity.
  • Tenancy: Artefacts are tenant-agnostic except evidence bundles, which are tagged with originating tenant and require matching Authority scopes.

2 - Workspace layout

+---------------------------------------------------------------+
| Header: Snapshot timestamp - Manifest signature status        |
+---------------------------------------------------------------+
| Cards: Latest release - Offline kit parity - Export queue     |
+---------------------------------------------------------------+
| Tabs: Artefacts | Exports | Offline Kits | Webhooks           |
+---------------------------------------------------------------+
| Filter bar: Channel - Kind - Architecture - Scope tags        |
+---------------------------------------------------------------+
| Table (virtualised): Artifact | Channel | Digest | Status     |
| Detail drawer: Metadata | Commands | Provenance | History     |
+---------------------------------------------------------------+
  • Snapshot banner: shows manifest.version, generatedAt, and cosign verification state. If verification fails, the banner turns red and links to troubleshooting guidance.
  • Quick actions: Copy manifest URL, download attestation bundle, trigger parity check, open CLI parity doc (/docs/cli-vs-ui-parity.md).
  • Filters: allow narrowing by channel (edge, stable, airgap), artefact kind (container.image, helm.chart, compose.bundle, offline.bundle, export.bundle), architecture (linux/amd64, linux/arm64), and scope tags (console, scheduler, authority).

3 - Artefact catalogue

Category Artefacts surfaced Source Notes
Core containers stellaops/web-ui, stellaops/web, stellaops/concelier, stellaops/excititor, stellaops/scanner-*, stellaops/authority, stellaops/attestor, stellaops/scheduler-* deploy/downloads/manifest.json (artifacts[].kind = "container.image") Digest-only pulls with copy-to-clipboard docker pull and oras copy commands; badges show arch availability.
Helm charts deploy/helm/stellaops-*.tgz plus values files Manifest entries where kind = "helm.chart" Commands reference helm repo add (online) and helm install --values (offline). UI links to values matrix in /docs/install/helm-prod.md when available.
Compose bundles deploy/compose/docker-compose.*.yaml, .env seeds kind = "compose.bundle" Inline diff viewer highlights digest changes vs previous snapshot; docker compose pull command copies digest pins.
Offline kit stella-ops-offline-kit-<ver>-<channel>.tar.gz + signatures and manifest Offline Kit metadata (manifest/offline-manifest.json) merged into downloads view Drawer shows bundle size, signed manifest digest, cosign verification command (mirrors /docs/24_OFFLINE_KIT.md).
Evidence exports Completed jobs from /console/exports (findings delta, policy explain, run evidence) Export orchestrator job queue Entries expire after retention window; UI exposes stella runs export and stella findings export parity buttons.
Webhooks & parity /downloads/hooks/subscribe configs, CI parity reports Manifest extras (kind = "webhook.config", kind = "parity.report") Operators can download webhook payload templates and review the latest CLI parity check report generated by docs CI.

4 - Manifest structure

The DevOps pipeline publishes a deterministic manifest at deploy/downloads/manifest.json, signed with the release Cosign key (DOWNLOADS-CONSOLE-23-001). The Console fetches it on workspace load and caches it with If-None-Match headers to avoid redundant pulls. The manifest schema:

  • version - monotonically increasing integer tied to pipeline run.
  • generatedAt - ISO-8601 UTC timestamp.
  • signature - URL to detached Cosign signature (manifest.json.sig).
  • artifacts[] - ordered list keyed by id.

Each artefact contains:

Field Description
id Stable identifier (<type>:<name>:<version>).
kind One of container.image, helm.chart, compose.bundle, offline.bundle, export.bundle, webhook.config, parity.report.
channel edge, stable, or airgap.
version Semantic or calendar version (for containers, matches release manifest).
architectures Array of supported platforms (empty for arch-agnostic artefacts).
digest SHA-256 for immutable artefacts; Compose bundles include file hash.
sizeBytes File size (optional for export bundles that stream).
downloadUrl HTTPS endpoint (registry, object store, or mirror).
signatureUrl Detached signature (Cosign, DSSE, or attestation) if available.
sbomUrl Optional SBOM pointer (CycloneDX JSON).
attestationUrl Optional in-toto/SLSA attestation.
docs Array of documentation links (e.g., /docs/install/docker.md).
tags Free-form tags (e.g., ["console","ui","offline"]).

4.1 Example excerpt

{
  "version": 42,
  "generatedAt": "2025-10-27T04:00:00Z",
  "signature": "https://downloads.stella-ops.org/manifest/manifest.json.sig",
  "artifacts": [
    {
      "id": "container.image:web-ui:2025.10.0-edge",
      "kind": "container.image",
      "channel": "edge",
      "version": "2025.10.0-edge",
      "architectures": ["linux/amd64", "linux/arm64"],
      "digest": "sha256:38b225fa7767a5b94ebae4dae8696044126aac429415e93de514d5dd95748dcf",
      "sizeBytes": 187563210,
      "downloadUrl": "https://registry.stella-ops.org/v2/stellaops/web-ui/manifests/sha256:38b225fa7767a5b94ebae4dae8696044126aac429415e93de514d5dd95748dcf",
      "signatureUrl": "https://downloads.stella-ops.org/signatures/web-ui-2025.10.0-edge.cosign.sig",
      "sbomUrl": "https://downloads.stella-ops.org/sbom/web-ui-2025.10.0-edge.cdx.json",
      "attestationUrl": "https://downloads.stella-ops.org/attestations/web-ui-2025.10.0-edge.intoto.jsonl",
      "docs": ["/docs/install/docker.md", "/docs/security/console-security.md"],
      "tags": ["console", "ui"]
    },
    {
      "id": "offline.bundle:ouk:2025.10.0-edge",
      "kind": "offline.bundle",
      "channel": "edge",
      "version": "2025.10.0-edge",
      "digest": "sha256:4f7d2f7a8d0cf4b5f3af689f6c74cd213f4c1b3a1d76d24f6f9f3d9075e51f90",
      "downloadUrl": "https://downloads.stella-ops.org/offline/stella-ops-offline-kit-2025.10.0-edge.tar.gz",
      "signatureUrl": "https://downloads.stella-ops.org/offline/stella-ops-offline-kit-2025.10.0-edge.tar.gz.sig",
      "sbomUrl": "https://downloads.stella-ops.org/offline/offline-manifest-2025.10.0-edge.json",
      "docs": ["/docs/24_OFFLINE_KIT.md"],
      "tags": ["offline", "airgap"]
    }
  ]
}

Console caches the manifest hash and surfaces differences when a new version lands, helping operators confirm digests drift only when expected.

5 - Download workflows and statuses

Status Applies to Behaviour
Ready Immutable artefacts (images, Helm/Compose bundles, offline kit) Commands available immediately. Digest, size, and last verification timestamp display in the table.
Pending export Async exports queued via /console/exports Shows job owner, scope, and estimated completion time. UI polls every 15 s and updates progress bar.
Processing Long-running export (evidence bundle, large SBOM) Drawer shows current stage (collecting, compressing, signing). Operators can cancel if they own the request and hold downloads.manage.
Delivered Completed export within retention window Provides download links, resume token, and parity snippet for CLI.
Expired Export past retention or manually expired Row grays out; clicking opens housekeeping guidance with CLI command to regenerate (stella runs export --run <id>).

Exports inherit retention defaults defined in policy (downloads.retentionDays, min 3, max 30). Operators can override per tenant if they have the appropriate scope.

6 - CLI parity and copy-to-clipboard

  • Digest pulls: Each container entry exposes docker pull <image>@<digest> and oras copy <image>@<digest> --to-dir ./downloads buttons. Commands include architecture hints for multi-platform images.
  • Helm/Compose: Buttons output helm pull / helm install with the manifest URL and docker compose --env-file commands referencing the downloaded bundle.
  • Offline kit: Copy buttons produce the full verification sequence:
curl -LO https://downloads.stella-ops.org/offline/stella-ops-offline-kit-2025.10.0-edge.tar.gz
curl -LO https://downloads.stella-ops.org/offline/stella-ops-offline-kit-2025.10.0-edge.tar.gz.sig
cosign verify-blob \
  --key https://stella-ops.org/keys/cosign.pub \
  --signature stella-ops-offline-kit-2025.10.0-edge.tar.gz.sig \
  stella-ops-offline-kit-2025.10.0-edge.tar.gz
  • Exports: Drawer lists CLI equivalents (for example, stella findings export --run <id>). When the CLI supports resume tokens, the command includes --resume-token from the manifest entry.
  • Automation: Webhook tab copies curl snippets to subscribe to /downloads/hooks/subscribe?topic=<artifact> and includes payload schema for integration tests.

Parity buttons write commands to the clipboard and display a toast confirming scope hints (for example, Requires downloads.read + tenant scope). Accessibility shortcuts (Shift+D) trigger the primary copy action for keyboard users.

7 - Offline and air-gap workflow

  • Manifest sync: Offline users download manifest/offline-manifest.json plus detached JWS and import it via stella offline kit import. Console highlights if the offline manifest predates the online manifest by more than 7 days.
  • Artefact staging: The workspace enumerates removable media instructions (export to ./staging/<channel>/) and warns when artefacts exceed configured media size thresholds.
  • Mirrors: Buttons copy oras copy commands that mirror images to an internal registry (registry.<tenant>.internal). Operators can toggle --insecure-policy if the destination uses custom trust roots.
  • Parity checks: downloads.offlineParity flag surfaces the latest parity report verifying that Offline Kit contents match the downloads manifest digests. If diff detected, UI raises a banner linking to remediation steps.
  • Audit logging: Every download command triggered from the UI emits ui.download.commandCopied with artifact ID, digest, and tenant. Logs feed the evidence locker so air-gap imports can demonstrate provenance.

8 - Observability and quotas

Signal Source Description
ui_download_manifest_refresh_seconds Console metrics Measures time to fetch and verify manifest. Targets < 3 s.
ui_download_export_queue_depth /console/downloads API Number of pending exports (per tenant). Surfaces as card and Grafana panel.
ui_download_command_copied_total Console logs Count of copy actions by artifact type, used to gauge CLI parity adoption.
downloads.export.duration Export orchestrator Duration histograms for bundle generation; alerts if P95 > 60 s.
downloads.quota.remaining Authority quota service Anonymous users limited to 33 exports/day, verified users 333/day. Banner turns amber at 90 % usage as per platform policy.

Telemetry entries include correlation IDs that match backend manifest refresh logs and export job records to keep troubleshooting deterministic.

9 - References

  • /docs/ui/console-overview.md - primary shell, tenant controls, SSE ticker.
  • /docs/ui/navigation.md - route ownership and keyboard shortcuts.
  • /docs/ui/sbom-explorer.md - export flows feeding the downloads queue.
  • /docs/ui/runs.md - evidence bundle integration.
  • /docs/24_OFFLINE_KIT.md - offline kit packaging and verification.
  • /docs/security/console-security.md - scopes, CSP, and download token handling.
  • /docs/cli-vs-ui-parity.md - CLI equivalence checks (pending).
  • deploy/releases/*.yaml - source of container digests mirrored into the manifest.

10 - Compliance checklist

  • Manifest schema documented (fields, signature, caching) and sample kept current.
  • Artefact categories mapped to manifest entries and parity workflows.
  • Download statuses, retention, and cancellation rules explained.
  • CLI copy-to-clipboard commands mirror console actions with scope hints.
  • Offline/air-gap parity workflow, mirror commands, and audit logging captured.
  • Observability metrics and quota signalling documented.
  • References cross-linked to adjacent docs (navigation, exports, offline kit).
  • Accessibility shortcuts and copy-to-clipboard behaviour noted with compliance reminder.

Last updated: 2025-10-27 (Sprint 23).