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

feat: Add guild charters and task boards for various components
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details

Browse Source 
- Introduced guild charters for Scanner Deno, PHP, Ruby, Native, WebService, Java, Surface.Env, Surface.FS, Surface.Secrets, Surface.Validation, UI, Zastava Observer, Zastava Webhook, Zastava Core, and Plugin Platform.
- Each charter outlines the mission, scope, required reading, and working agreements for the respective guilds.
- Created task boards for Surface.Env, Surface.FS, Surface.Secrets, Surface.Validation, and Zastava components to track progress and dependencies.
- Ensured all documents emphasize determinism, offline readiness, security, and integration with shared Surface libraries.
This commit is contained in:
master
2025-11-01 02:21:46 +02:00
parent e5629454cf
commit 66cb6c4b8a
227 changed files with 9913 additions and 6210 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
docs/modules/devops/AGENTS.md
View File

@@ -1,22 +1,34 @@
# DevOps agent guide
## Mission
The DevOps module captures release, deployment, and migration playbooks that keep StellaOps deterministic across environments.
## Key docs
- [Module README](./README.md)
- [Architecture](./architecture.md)
- [Implementation plan](./implementation_plan.md)
- [Task board](./TASKS.md)
## How to get started
1. Open ../../implplan/SPRINTS.md and locate the stories referencing this module.
2. Review ./TASKS.md for local follow-ups and confirm status transitions (TODO → DOING → DONE/BLOCKED).
3. Read the architecture and README for domain context before editing code or docs.
4. Coordinate cross-module changes in the main /AGENTS.md description and through the sprint plan.
## Guardrails
- Honour the Aggregation-Only Contract where applicable (see ../../ingestion/aggregation-only-contract.md).
- Preserve determinism: sort outputs, normalise timestamps (UTC ISO-8601), and avoid machine-specific artefacts.
- Keep Offline Kit parity in mind—document air-gapped workflows for any new feature.
- Update runbooks/observability assets when operational characteristics change.
# DevOps agent guide
## Mission
The DevOps module captures release, deployment, and migration playbooks that keep StellaOps deterministic across environments.
## Key docs
- [Module README](./README.md)
- [Architecture](./architecture.md)
- [Implementation plan](./implementation_plan.md)
- [Task board](./TASKS.md)
## How to get started
1. Open ../../implplan/SPRINTS.md and locate the stories referencing this module.
2. Review ./TASKS.md for local follow-ups and confirm status transitions (TODO → DOING → DONE/BLOCKED).
3. Read the architecture and README for domain context before editing code or docs.
4. Coordinate cross-module changes in the main /AGENTS.md description and through the sprint plan.
## Guardrails
- Honour the Aggregation-Only Contract where applicable (see ../../ingestion/aggregation-only-contract.md).
- Preserve determinism: sort outputs, normalise timestamps (UTC ISO-8601), and avoid machine-specific artefacts.
- Keep Offline Kit parity in mind—document air-gapped workflows for any new feature.
- Update runbooks/observability assets when operational characteristics change.
## Required Reading
- `docs/modules/devops/README.md`
- `docs/modules/devops/architecture.md`
- `docs/modules/devops/implementation_plan.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

2
docs/modules/devops/runbooks/launch-readiness.md
View File

@@ -13,7 +13,7 @@ This document captures production launch sign-offs, deployment readiness checkpo
| Attestor | Attestor Guild | `ATTESTOR-API-11-201` / `ATTESTOR-VERIFY-11-202` / `ATTESTOR-OBS-11-203` (DONE 2025-10-19) | READY | 2025-10-26T14:10Z | Rekor submission/verification pipeline green; telemetry pack published. |
| Scanner Web + Worker | Scanner WebService Guild | `SCANNER-WEB-09-10x`, `SCANNER-RUNTIME-12-30x` (DONE 2025-10-18 -> 2025-10-24) | READY* | 2025-10-26T14:20Z | Orchestrator envelope work (`SCANNER-EVENTS-16-301/302`) still open; see gaps. |
| Concelier Core & Connectors | Concelier Core / Ops Guild | Ops runbook sign-off in `docs/modules/concelier/operations/conflict-resolution.md` (2025-10-16) | READY | 2025-10-26T14:25Z | Conflict resolution & connector coverage accepted; Mongo schema hardening pending (see gaps). |
| Excititor API | Excititor Core Guild | Wave 0 connector ingest sign-offs (EXECPLAN.Section Wave 0) | READY | 2025-10-26T14:28Z | VEX linkset publishing complete for launch datasets. |
| Excititor API | Excititor Core Guild | Wave 0 connector ingest sign-offs (Sprint backlog reference) | READY | 2025-10-26T14:28Z | VEX linkset publishing complete for launch datasets. |
| Notify Web (legacy) | Notify Guild | Existing stack carried forward; Notifier program tracked separately (Sprint 38-40) | PENDING | 2025-10-26T14:32Z | Legacy notify web remains operational; migration to Notifier blocked on `SCANNER-EVENTS-16-301`. |
| Web UI | UI Guild | Stable build `registry.stella-ops.org/.../web-ui@sha256:10d9248...` deployed in stage and smoke-tested | READY | 2025-10-26T14:35Z | Policy editor GA items (Sprint 20) outside launch scope. |
| DevOps / Release | DevOps Guild | `deploy/tools/validate-profiles.sh` run (2025-10-26) covering dev/stage/prod/airgap/mirror | READY | 2025-10-26T15:02Z | Compose/Helm lint + docker compose config validated; see Section 2 for details. |

49
docs/modules/devops/runbooks/zastava-deployment.md Normal file
View File

@@ -0,0 +1,49 @@
# Zastava Deployment Runbook
> **Audience:** DevOps, Zastava Guild
>
> **Purpose:** Provide steps for deploying Zastava Observer + Webhook in connected and air-gapped clusters.
## 1. Prerequisites
- Kubernetes 1.26+ with admission registration permissions.
- Access to StellaOps Container Registry or offline bundle with Zastava images.
- Authority scopes and certificates configured for Zastava identities.
- Surface.FS cache endpoint (RustFS/S3) reachable from nodes.
## 2. Installation Steps
1. **Prepare namespace & secrets**
- Create Kubernetes namespace (default `stellaops-runtime`).
- Provision secrets (`zastava-mtls`, `zastava-op-token`, `surface-secrets`).
2. **Deploy Observer**
- Apply Helm chart `helm/zastava` with values aligning to Surface.Env settings.
- Confirm DaemonSet pods schedule on all nodes; check `/healthz` endpoints.
3. **Deploy Webhook**
- Install ValidatingWebhookConfiguration with CA bundle and service reference.
- Enable dry-run mode first, monitor logs, then switch `enforce=true` once validations pass.
4. **Configure policies**
- Populate admission policies in Policy Engine; ensure tokens contain `runtime:read` scopes.
- Update CLI/Console settings for runtime posture view.
5. **Observability**
- Scrape metrics (`zastava_observer_*`, `zastava_webhook_*`).
- Stream logs to central collector.
## 3. Air-Gapped Deployment Notes
- Use Offline Kit bundle (`offline/zastava/`) to load images and configuration.
- Validate Surface.FS bundles before enabling enforcement.
- Replace webhook CA with offline authority; document rotation schedule.
## 4. Validation
- Run `stella runtime policy test` against sample workloads.
- Trigger deployment denial for unsigned images; verify Notifier emits alerts.
- Check timeline events for observer telemetry.
## 5. References
- `docs/modules/zastava/architecture.md`
- `docs/modules/scanner/architecture.md`
- `docs/airgap/airgap-mode.md`
- `docs/forensics/timeline.md`