consolidation of some of the modules, localization fixes, product advisories work, qa work

2026-03-05 03:54:22 +02:00
parent 7bafcc3eef
commit 8e1cb9448d
3878 changed files with 72600 additions and 46861 deletions
--- a/docs-archived/modules/issuer-directory/operations/deployment.md
+++ b/docs-archived/modules/issuer-directory/operations/deployment.md
@@ -0,0 +1,107 @@
+# Issuer Directory Deployment Guide
+
+## Scope
+- **Applies to:** Issuer Directory WebService (`stellaops/issuer-directory-web`) running via the provided Docker Compose bundles (`devops/compose/docker-compose.*.yaml`) or the Helm chart (`devops/helm/stellaops`).
+- **Covers:** Environment prerequisites, secret handling, Compose + Helm rollout steps, and post-deploy verification.
+- **Audience:** Platform/DevOps engineers responsible for Identity & Signing sprint deliverables.
+
+## 1 · Prerequisites
+- Authority must be running and reachable at the issuer URL you configure (default Compose host: `https://authority:8440`).
+- PostgreSQL 16+ with credentials for the `issuer_directory` database (Compose defaults to the user defined in `.env`).
+- Network access to Authority, PostgreSQL, and (optionally) Prometheus if you scrape metrics.
+- Issuer Directory configuration file `etc/issuer-directory.yaml` checked and customised for your environment (tenant header, audiences, telemetry level, CSAF seed path).
+
+> **Secrets:** Use `etc/secrets/issuer-directory.postgres.secret.example` as a template. Store the real connection string in an untracked file or secrets manager and reference it via environment variables (`ISSUER_DIRECTORY_POSTGRES_CONNECTION_STRING`) rather than committing credentials.
+
+## 2 · Deploy with Docker Compose
+1. **Prepare environment variables**
+   ```bash
+   cp devops/compose/env/dev.env.example dev.env
+   cp etc/secrets/issuer-directory.postgres.secret.example issuer-directory.postgres.env
+   # Edit dev.env and issuer-directory.postgres.env with production-ready secrets.
+   ```
+
+2. **Inspect the merged configuration**
+   ```bash
+   docker compose \
+     --env-file dev.env \
+     --env-file issuer-directory.postgres.env \
+     -f devops/compose/docker-compose.dev.yaml config
+   ```
+   The command confirms the new `issuer-directory` service resolves the port (`${ISSUER_DIRECTORY_PORT:-8447}`) and the PostgreSQL connection string is in place.
+
+3. **Launch the stack**
+   ```bash
+   docker compose \
+     --env-file dev.env \
+     --env-file issuer-directory.postgres.env \
+     -f devops/compose/docker-compose.dev.yaml up -d issuer-directory
+   ```
+   Compose automatically mounts `../../etc/issuer-directory.yaml` into the container at `/etc/issuer-directory.yaml`, seeds CSAF publishers, and exposes the API on `https://localhost:8447`.
+
+### Compose environment variables
+| Variable | Purpose | Default |
+| --- | --- | --- |
+| `ISSUER_DIRECTORY_PORT` | Host port that maps to container port `8080`. | `8447` |
+| `ISSUER_DIRECTORY_POSTGRES_CONNECTION_STRING` | Injected into `ISSUERDIRECTORY__POSTGRES__CONNECTIONSTRING`; should contain credentials. | `Host=postgres;Port=5432;Database=issuer_directory;Username=${POSTGRES_USER};Password=${POSTGRES_PASSWORD}` |
+| `ISSUER_DIRECTORY_SEED_CSAF` | Toggles CSAF bootstrap on startup. Set to `false` after the first production import if you manage issuers manually. | `true` |
+
+4. **Smoke test**
+   ```bash
+   curl -k https://localhost:8447/health/live
+   stellaops-cli issuer-directory issuers list \
+     --base-url https://localhost:8447 \
+     --tenant demo \
+     --access-token "$(stellaops-cli auth token issue --scope issuer-directory:read)"
+   ```
+
+5. **Upgrade & rollback**
+   - Update Compose images to the desired release manifest (`deploy/releases/*.yaml`), re-run `docker compose config`, then `docker compose up -d`.
+   - Rollbacks follow the same steps with the previous manifest. PostgreSQL schemas are backwards compatible within `2025.10.x`.
+
+## 3 · Deploy with Helm
+1. **Create or update the secret**
+   ```bash
+   kubectl create secret generic issuer-directory-secrets \
+     --from-literal=ISSUERDIRECTORY__POSTGRES__CONNECTIONSTRING='Host=stellaops-postgres;Port=5432;Database=issuer_directory;Username=stellaops;Password=<password>' \
+     --dry-run=client -o yaml | kubectl apply -f -
+   ```
+   Add optional overrides (e.g. `ISSUERDIRECTORY__AUTHORITY__ISSUER`) if your Authority issuer differs from the default.
+
+2. **Template for validation**
+   ```bash
+   helm template issuer-directory devops/helm/stellaops \
+     -f devops/helm/stellaops/values-prod.yaml \
+     --set services.issuer-directory.env.ISSUERDIRECTORY__AUTHORITY__ISSUER=https://authority.prod.stella-ops.org \
+     > /tmp/issuer-directory.yaml
+   ```
+
+3. **Install / upgrade**
+   ```bash
+   helm upgrade --install stellaops devops/helm/stellaops \
+     -f devops/helm/stellaops/values-prod.yaml \
+     --set services.issuer-directory.env.ISSUERDIRECTORY__AUTHORITY__ISSUER=https://authority.prod.stella-ops.org
+   ```
+   The chart provisions:
+   - ConfigMap `stellaops-issuer-directory-config` with `IssuerDirectory` settings.
+   - Deployment `stellaops-issuer-directory` with readiness/liveness probes on `/health/live`.
+   - Service on port `8080` (ClusterIP by default).
+
+4. **Expose for operators (optional)**
+   - Use an Ingress/HTTPRoute to publish `https://issuer-directory.<env>.stella-ops.org`.
+   - Ensure the upstream includes DPoP headers if proxied through an API gateway.
+
+5. **Post-deploy validation**
+   ```bash
+   kubectl exec deploy/stellaops-issuer-directory -- \
+     curl -sf http://127.0.0.1:8080/health/live
+   kubectl logs deploy/stellaops-issuer-directory | grep 'IssuerDirectory PostgreSQL connected'
+   ```
+   Prometheus should begin scraping `issuer_directory_changes_total` and related metrics (labels: `tenant`, `issuer`, `action`).
+
+## 4 · Operational checklist
+- **Secrets:** Connection strings live in `issuer-directory-secrets` (Helm) or an `.env` file stored in your secrets vault (Compose). Rotate credentials via secret update + pod restart.
+- **Audit streams:** Confirm `issuer_directory_audit` collection receives entries when CRUD operations run; export logs for compliance.
+- **Tenants:** The service enforces the `X-StellaOps-Tenant` header. For multi-tenant staging, configure the reverse proxy to inject the correct tenant or issue scoped tokens.
+- **CSAF seeds:** `ISSUER_DIRECTORY_SEED_CSAF=true` replays `data/csaf-publishers.json` on startup. Set to `false` once production tenants are fully managed, or override `csafSeedPath` with a curated bundle.
+- **Release alignment:** Before promotion, run `deploy/tools/validate-profiles.sh` to lint Compose/Helm bundles, then verify the new `issuer-directory-web` entry in `deploy/releases/2025.10-edge.yaml` (or the relevant manifest) matches the channel you intend to ship.