# 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)