add release orchestrator docs and sprints gaps fills
This commit is contained in:
289
docs/modules/release-orchestrator/api/environments.md
Normal file
289
docs/modules/release-orchestrator/api/environments.md
Normal file
@@ -0,0 +1,289 @@
|
||||
# Environment Management APIs
|
||||
|
||||
> API endpoints for managing environments, targets, agents, freeze windows, and inventory.
|
||||
|
||||
**Status:** Planned (not yet implemented)
|
||||
**Source:** [Architecture Advisory Section 6.3.2](../../../product/advisories/09-Jan-2026%20-%20Stella%20Ops%20Orchestrator%20Architecture.md)
|
||||
**Related Modules:** [Environment Manager](../modules/environment-manager.md), [Agents](../modules/agents.md)
|
||||
|
||||
## Overview
|
||||
|
||||
The Environment Management API provides CRUD operations for environments, target groups, deployment targets, agents, freeze windows, and inventory synchronization. All endpoints require authentication and respect tenant isolation via Row-Level Security.
|
||||
|
||||
---
|
||||
|
||||
## Environment Endpoints
|
||||
|
||||
### Create Environment
|
||||
|
||||
**Endpoint:** `POST /api/v1/environments`
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"name": "production",
|
||||
"displayName": "Production",
|
||||
"orderIndex": 3,
|
||||
"config": {
|
||||
"deploymentTimeout": 600,
|
||||
"healthCheckInterval": 30
|
||||
},
|
||||
"requiredApprovals": 2,
|
||||
"requireSod": true,
|
||||
"promotionPolicy": "default"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:** `201 Created`
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "production",
|
||||
"displayName": "Production",
|
||||
"orderIndex": 3,
|
||||
"isProduction": true,
|
||||
"requiredApprovals": 2,
|
||||
"requireSeparationOfDuties": true,
|
||||
"createdAt": "2026-01-10T14:23:45Z"
|
||||
}
|
||||
```
|
||||
|
||||
### List Environments
|
||||
|
||||
**Endpoint:** `GET /api/v1/environments`
|
||||
|
||||
**Query Parameters:**
|
||||
- `includeState` (boolean): Include current release state
|
||||
|
||||
**Response:** `200 OK`
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "development",
|
||||
"displayName": "Development",
|
||||
"orderIndex": 1,
|
||||
"currentRelease": {
|
||||
"id": "release-uuid",
|
||||
"name": "myapp-v2.3.1",
|
||||
"deployedAt": "2026-01-09T10:00:00Z"
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Get Environment
|
||||
|
||||
**Endpoint:** `GET /api/v1/environments/{id}`
|
||||
|
||||
**Response:** `200 OK` - Full environment details
|
||||
|
||||
### Update Environment
|
||||
|
||||
**Endpoint:** `PUT /api/v1/environments/{id}`
|
||||
|
||||
**Request:** Partial environment object
|
||||
|
||||
**Response:** `200 OK` - Updated environment
|
||||
|
||||
### Delete Environment
|
||||
|
||||
**Endpoint:** `DELETE /api/v1/environments/{id}`
|
||||
|
||||
**Response:** `200 OK`
|
||||
```json
|
||||
{ "deleted": true }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Freeze Window Endpoints
|
||||
|
||||
### Create Freeze Window
|
||||
|
||||
**Endpoint:** `POST /api/v1/environments/{envId}/freeze-windows`
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"start": "2026-01-15T00:00:00Z",
|
||||
"end": "2026-01-20T00:00:00Z",
|
||||
"reason": "Holiday freeze",
|
||||
"exceptions": ["user-uuid-1", "user-uuid-2"]
|
||||
}
|
||||
```
|
||||
|
||||
**Response:** `201 Created`
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"environmentId": "env-uuid",
|
||||
"start": "2026-01-15T00:00:00Z",
|
||||
"end": "2026-01-20T00:00:00Z",
|
||||
"reason": "Holiday freeze",
|
||||
"createdBy": "user-uuid"
|
||||
}
|
||||
```
|
||||
|
||||
### List Freeze Windows
|
||||
|
||||
**Endpoint:** `GET /api/v1/environments/{envId}/freeze-windows`
|
||||
|
||||
**Query Parameters:**
|
||||
- `active` (boolean): Filter to active freeze windows only
|
||||
|
||||
**Response:** `200 OK` - Array of freeze windows
|
||||
|
||||
### Delete Freeze Window
|
||||
|
||||
**Endpoint:** `DELETE /api/v1/environments/{envId}/freeze-windows/{windowId}`
|
||||
|
||||
**Response:** `200 OK`
|
||||
```json
|
||||
{ "deleted": true }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Target Group Endpoints
|
||||
|
||||
### Create Target Group
|
||||
|
||||
**Endpoint:** `POST /api/v1/environments/{envId}/target-groups`
|
||||
|
||||
### List Target Groups
|
||||
|
||||
**Endpoint:** `GET /api/v1/environments/{envId}/target-groups`
|
||||
|
||||
### Get Target Group
|
||||
|
||||
**Endpoint:** `GET /api/v1/target-groups/{id}`
|
||||
|
||||
### Update Target Group
|
||||
|
||||
**Endpoint:** `PUT /api/v1/target-groups/{id}`
|
||||
|
||||
### Delete Target Group
|
||||
|
||||
**Endpoint:** `DELETE /api/v1/target-groups/{id}`
|
||||
|
||||
---
|
||||
|
||||
## Target Endpoints
|
||||
|
||||
### Create Target
|
||||
|
||||
**Endpoint:** `POST /api/v1/targets`
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"environmentId": "env-uuid",
|
||||
"targetGroupId": "group-uuid",
|
||||
"name": "prod-web-01",
|
||||
"targetType": "docker_host",
|
||||
"connection": {
|
||||
"host": "192.168.1.100",
|
||||
"port": 2375,
|
||||
"tlsEnabled": true
|
||||
},
|
||||
"labels": {
|
||||
"role": "web",
|
||||
"datacenter": "us-east-1"
|
||||
},
|
||||
"deploymentDirectory": "/opt/deployments"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:** `201 Created`
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "prod-web-01",
|
||||
"targetType": "docker_host",
|
||||
"healthStatus": "unknown",
|
||||
"createdAt": "2026-01-10T14:23:45Z"
|
||||
}
|
||||
```
|
||||
|
||||
### List Targets
|
||||
|
||||
**Endpoint:** `GET /api/v1/targets`
|
||||
|
||||
**Query Parameters:**
|
||||
- `environmentId` (UUID): Filter by environment
|
||||
- `targetType` (string): Filter by type (`docker_host`, `compose_host`, `ecs_service`, `nomad_job`)
|
||||
- `labels` (JSON): Filter by labels
|
||||
- `healthStatus` (string): Filter by health status
|
||||
|
||||
**Response:** `200 OK` - Array of targets
|
||||
|
||||
### Get Target
|
||||
|
||||
**Endpoint:** `GET /api/v1/targets/{id}`
|
||||
|
||||
### Update Target
|
||||
|
||||
**Endpoint:** `PUT /api/v1/targets/{id}`
|
||||
|
||||
### Delete Target
|
||||
|
||||
**Endpoint:** `DELETE /api/v1/targets/{id}`
|
||||
|
||||
### Trigger Health Check
|
||||
|
||||
**Endpoint:** `POST /api/v1/targets/{id}/health-check`
|
||||
|
||||
**Response:** `200 OK`
|
||||
```json
|
||||
{
|
||||
"status": "healthy",
|
||||
"message": "Docker daemon responding",
|
||||
"checkedAt": "2026-01-10T14:23:45Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Get Version Sticker
|
||||
|
||||
**Endpoint:** `GET /api/v1/targets/{id}/sticker`
|
||||
|
||||
**Response:** `200 OK`
|
||||
```json
|
||||
{
|
||||
"releaseId": "uuid",
|
||||
"releaseName": "myapp-v2.3.1",
|
||||
"components": [
|
||||
{
|
||||
"componentId": "uuid",
|
||||
"componentName": "api",
|
||||
"digest": "sha256:abc123..."
|
||||
}
|
||||
],
|
||||
"deployedAt": "2026-01-09T10:00:00Z",
|
||||
"deployedBy": "user-uuid"
|
||||
}
|
||||
```
|
||||
|
||||
### Check Drift
|
||||
|
||||
**Endpoint:** `GET /api/v1/targets/{id}/drift`
|
||||
|
||||
**Response:** `200 OK`
|
||||
```json
|
||||
{
|
||||
"hasDrift": true,
|
||||
"expected": { "releaseId": "uuid", "digest": "sha256:abc..." },
|
||||
"actual": { "digest": "sha256:def..." },
|
||||
"differences": [
|
||||
{ "component": "api", "expected": "sha256:abc...", "actual": "sha256:def..." }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Agents API](agents.md)
|
||||
- [Environment Manager Module](../modules/environment-manager.md)
|
||||
- [Agent Security](../security/agent-security.md)
|
||||
Reference in New Issue
Block a user