add release orchestrator docs and sprints gaps fills
This commit is contained in:
224
docs/modules/release-orchestrator/appendices/config.md
Normal file
224
docs/modules/release-orchestrator/appendices/config.md
Normal file
@@ -0,0 +1,224 @@
|
||||
# Configuration Reference
|
||||
|
||||
> Environment variables and OPA policy examples for the Release Orchestrator.
|
||||
|
||||
**Status:** Planned (not yet implemented)
|
||||
**Source:** [Architecture Advisory Section 15.2](../../../product/advisories/09-Jan-2026%20-%20Stella%20Ops%20Orchestrator%20Architecture.md)
|
||||
**Related Modules:** [Security Overview](../security/overview.md), [Promotion Manager](../modules/promotion-manager.md)
|
||||
**Sprint:** [101_001 Foundation](../../../../implplan/SPRINT_20260110_101_001_DB_schema_core_tables.md)
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides the configuration reference for the Release Orchestrator, including environment variables and OPA policy examples.
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
### Core Configuration
|
||||
|
||||
```bash
|
||||
# Database
|
||||
STELLA_DATABASE_URL=postgresql://user:pass@host:5432/stella
|
||||
STELLA_REDIS_URL=redis://host:6379
|
||||
STELLA_SECRET_KEY=base64-encoded-32-bytes
|
||||
STELLA_LOG_LEVEL=info
|
||||
STELLA_LOG_FORMAT=json
|
||||
```
|
||||
|
||||
### Authentication (Authority)
|
||||
|
||||
```bash
|
||||
# OAuth/OIDC
|
||||
STELLA_OAUTH_ISSUER=https://auth.example.com
|
||||
STELLA_OAUTH_CLIENT_ID=stella-app
|
||||
STELLA_OAUTH_CLIENT_SECRET=secret
|
||||
```
|
||||
|
||||
### Agents
|
||||
|
||||
```bash
|
||||
# Agent TLS
|
||||
STELLA_AGENT_LISTEN_PORT=8443
|
||||
STELLA_AGENT_TLS_CERT=/path/to/cert.pem
|
||||
STELLA_AGENT_TLS_KEY=/path/to/key.pem
|
||||
STELLA_AGENT_CA_CERT=/path/to/ca.pem
|
||||
```
|
||||
|
||||
### Plugins
|
||||
|
||||
```bash
|
||||
# Plugin configuration
|
||||
STELLA_PLUGIN_DIR=/var/stella/plugins
|
||||
STELLA_PLUGIN_SANDBOX_MEMORY=512m
|
||||
STELLA_PLUGIN_SANDBOX_CPU=1
|
||||
```
|
||||
|
||||
### Integrations
|
||||
|
||||
```bash
|
||||
# Vault integration
|
||||
STELLA_VAULT_ADDR=https://vault.example.com
|
||||
STELLA_VAULT_TOKEN=hvs.xxx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Full Configuration File
|
||||
|
||||
```yaml
|
||||
# stella-config.yaml
|
||||
|
||||
database:
|
||||
url: postgresql://user:pass@host:5432/stella
|
||||
pool_size: 20
|
||||
ssl_mode: require
|
||||
|
||||
redis:
|
||||
url: redis://host:6379
|
||||
prefix: stella
|
||||
|
||||
auth:
|
||||
issuer: https://auth.example.com
|
||||
client_id: stella-app
|
||||
client_secret_ref: vault://secrets/oauth-client-secret
|
||||
|
||||
agents:
|
||||
listen_port: 8443
|
||||
tls:
|
||||
cert_path: /etc/stella/agent.crt
|
||||
key_path: /etc/stella/agent.key
|
||||
ca_path: /etc/stella/ca.crt
|
||||
heartbeat_interval: 30
|
||||
task_timeout: 600
|
||||
|
||||
plugins:
|
||||
directory: /var/stella/plugins
|
||||
sandbox:
|
||||
memory: 512m
|
||||
cpu: 1
|
||||
network: restricted
|
||||
|
||||
evidence:
|
||||
storage_path: /var/stella/evidence
|
||||
signing_key_ref: vault://secrets/evidence-signing-key
|
||||
retention_days: 2555 # 7 years
|
||||
|
||||
logging:
|
||||
level: info
|
||||
format: json
|
||||
output: stdout
|
||||
|
||||
telemetry:
|
||||
enabled: true
|
||||
otlp_endpoint: otel-collector:4317
|
||||
service_name: stella-release-orchestrator
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## OPA Policy Examples
|
||||
|
||||
### Security Gate Policy
|
||||
|
||||
```rego
|
||||
# security_gate.rego
|
||||
package stella.gates.security
|
||||
|
||||
default allow = false
|
||||
|
||||
allow {
|
||||
input.release.components[_].security.reachable_critical == 0
|
||||
input.release.components[_].security.reachable_high == 0
|
||||
}
|
||||
|
||||
deny[msg] {
|
||||
component := input.release.components[_]
|
||||
component.security.reachable_critical > 0
|
||||
msg := sprintf("Component %s has %d reachable critical vulnerabilities",
|
||||
[component.name, component.security.reachable_critical])
|
||||
}
|
||||
```
|
||||
|
||||
### Approval Gate Policy
|
||||
|
||||
```rego
|
||||
# approval_gate.rego
|
||||
package stella.gates.approval
|
||||
|
||||
default allow = false
|
||||
|
||||
allow {
|
||||
count(input.approvals) >= input.environment.required_approvals
|
||||
separation_of_duties_met
|
||||
}
|
||||
|
||||
separation_of_duties_met {
|
||||
not input.environment.require_sod
|
||||
}
|
||||
|
||||
separation_of_duties_met {
|
||||
input.environment.require_sod
|
||||
approver_ids := {a.approver_id | a := input.approvals[_]; a.action == "approved"}
|
||||
not input.promotion.requested_by in approver_ids
|
||||
}
|
||||
```
|
||||
|
||||
### Freeze Window Gate Policy
|
||||
|
||||
```rego
|
||||
# freeze_window_gate.rego
|
||||
package stella.gates.freeze
|
||||
|
||||
default allow = true
|
||||
|
||||
allow = false {
|
||||
window := input.environment.freeze_windows[_]
|
||||
time.now_ns() >= time.parse_rfc3339_ns(window.start)
|
||||
time.now_ns() <= time.parse_rfc3339_ns(window.end)
|
||||
not input.promotion.requested_by in window.exceptions
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API Error Codes
|
||||
|
||||
| Code | HTTP Status | Description |
|
||||
|------|-------------|-------------|
|
||||
| `RELEASE_NOT_FOUND` | 404 | Release with specified ID does not exist |
|
||||
| `ENVIRONMENT_NOT_FOUND` | 404 | Environment with specified ID does not exist |
|
||||
| `PROMOTION_BLOCKED` | 403 | Promotion blocked by policy gates |
|
||||
| `APPROVAL_REQUIRED` | 403 | Additional approvals required |
|
||||
| `FREEZE_WINDOW_ACTIVE` | 403 | Environment is in freeze window |
|
||||
| `DIGEST_MISMATCH` | 400 | Image digest does not match expected |
|
||||
| `AGENT_OFFLINE` | 503 | Required agent is offline |
|
||||
| `WORKFLOW_FAILED` | 500 | Workflow execution failed |
|
||||
| `PLUGIN_ERROR` | 500 | Plugin returned an error |
|
||||
| `QUOTA_EXCEEDED` | 429 | Digest analysis quota exceeded |
|
||||
| `VALIDATION_ERROR` | 400 | Request validation failed |
|
||||
| `UNAUTHORIZED` | 401 | Authentication required |
|
||||
| `FORBIDDEN` | 403 | Insufficient permissions |
|
||||
|
||||
---
|
||||
|
||||
## Default Values
|
||||
|
||||
| Setting | Default | Description |
|
||||
|---------|---------|-------------|
|
||||
| Agent heartbeat interval | 30s | Frequency of agent heartbeats |
|
||||
| Task timeout | 600s | Maximum time for agent task |
|
||||
| Deployment batch size | 25% | Percentage of targets per batch |
|
||||
| Health check timeout | 60s | Timeout for health checks |
|
||||
| Evidence retention | 7 years | Audit compliance requirement |
|
||||
| Max workflow steps | 50 | Maximum steps per workflow |
|
||||
| Max parallel tasks | 10 | Per-agent concurrent tasks |
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Security Overview](../security/overview.md)
|
||||
- [Promotion Manager](../modules/promotion-manager.md)
|
||||
- [Database Schema](../data-model/schema.md)
|
||||
- [Glossary](glossary.md)
|
||||
Reference in New Issue
Block a user