428 lines
12 KiB
YAML
428 lines
12 KiB
YAML
openapi: 3.1.0
|
|
info:
|
|
title: TheCr3w Deployment Control API
|
|
version: 1.0.0
|
|
description: >
|
|
Centralne API zarządzania wdrożeniami kontenerów Docker (po niezmiennych digestach Forgejo OCI Registry)
|
|
oraz wdrożeniami zewnętrznymi (SFTP / FTPS z walidacją host key i certyfikatów TLS).
|
|
servers:
|
|
- url: https://app.thecr3wnet.com/control
|
|
description: Serwer Produkcyjny (przez Caddy)
|
|
- url: http://localhost:5001
|
|
description: Środowisko Lokalne
|
|
|
|
paths:
|
|
/health:
|
|
get:
|
|
summary: Health check
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
|
|
/api/v1/deployments/manifests:
|
|
post:
|
|
summary: Zgłoszenie nowego manifestu wdrożeniowego (np. z Forgejo CI/CD)
|
|
security:
|
|
- KeycloakOIDC: ['thecr3w:deployer', 'thecr3w:admin']
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/DeploymentManifestInput'
|
|
responses:
|
|
'201':
|
|
description: Manifest poprawnie zwalidowany, podpis Ed25519 zweryfikowany
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ManifestResponse'
|
|
'400':
|
|
description: Błąd walidacji schematu lub nieprawidłowy podpis Ed25519
|
|
|
|
get:
|
|
summary: Lista zgłoszonych manifestów
|
|
security:
|
|
- KeycloakOIDC: ['thecr3w:viewer', 'thecr3w:deployer', 'thecr3w:admin']
|
|
responses:
|
|
'200':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ManifestResponse'
|
|
|
|
/api/v1/deployments/approvals:
|
|
post:
|
|
summary: Zatwierdzenie wdrożenia produkcyjnego powiązane ze ścisłym SHA256 manifestu
|
|
security:
|
|
- KeycloakOIDC: ['thecr3w:approver', 'thecr3w:admin']
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [manifest_id, manifest_sha256, decision, comment]
|
|
properties:
|
|
manifest_id:
|
|
type: string
|
|
format: uuid
|
|
manifest_sha256:
|
|
type: string
|
|
pattern: '^[a-f0-9]{64}$'
|
|
decision:
|
|
type: string
|
|
enum: [approved, rejected]
|
|
comment:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Decyzja zatwierdzenia zarejestrowana i podpisana audytowo
|
|
'409':
|
|
description: Niezgodność SHA256 manifestu (unieważnienie wcześniejszej akceptacji)
|
|
|
|
/api/v1/deployments/execute/{manifest_id}:
|
|
post:
|
|
summary: Zlecenie wykonania wdrożenia kontrolowanemu Deployment Agentowi
|
|
security:
|
|
- KeycloakOIDC: ['thecr3w:deployer', 'thecr3w:admin']
|
|
parameters:
|
|
- name: manifest_id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
responses:
|
|
'202':
|
|
description: Wdrożenie przyjęte do wykonania
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/DeploymentExecutionResponse'
|
|
'412':
|
|
description: Brak wymaganej akceptacji dla środowiska produkcyjnego
|
|
|
|
/api/v1/deployments/{deployment_id}/status:
|
|
get:
|
|
summary: Pobranie aktualnego stanu wdrożenia, kroków i logów healthcheck
|
|
security:
|
|
- KeycloakOIDC: ['thecr3w:viewer', 'thecr3w:deployer', 'thecr3w:admin']
|
|
parameters:
|
|
- name: deployment_id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
responses:
|
|
'200':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/DeploymentStatusResponse'
|
|
|
|
/api/v1/deployments/{deployment_id}/rollback:
|
|
post:
|
|
summary: Wymuszenie natychmiastowego rollbacku do poprzedniego immutable digest
|
|
security:
|
|
- KeycloakOIDC: ['thecr3w:admin']
|
|
parameters:
|
|
- name: deployment_id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [reason]
|
|
properties:
|
|
reason:
|
|
type: string
|
|
responses:
|
|
'202':
|
|
description: Rollback zainicjalizowany
|
|
|
|
/api/v1/external-deployments/servers:
|
|
get:
|
|
summary: Lista profili serwerów zewnętrznych (bez ujawniania haseł i kluczy)
|
|
security:
|
|
- KeycloakOIDC: ['thecr3w:viewer', 'thecr3w:admin']
|
|
responses:
|
|
'200':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ExternalServerDto'
|
|
|
|
post:
|
|
summary: Utworzenie lub aktualizacja profilu serwera zewnętrznego (SFTP / FTPS)
|
|
security:
|
|
- KeycloakOIDC: ['thecr3w:admin']
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CreateExternalServerRequest'
|
|
responses:
|
|
'201':
|
|
description: Profil serwera zapisany z przypięciem klucza hosta lub certyfikatu
|
|
|
|
/api/v1/external-deployments/sync/preview:
|
|
post:
|
|
summary: Podgląd zmian i porównanie sum kontrolnych plików przed synchronizacją na serwer zewnętrzny
|
|
security:
|
|
- KeycloakOIDC: ['thecr3w:deployer', 'thecr3w:admin']
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [server_id, local_manifest_hash]
|
|
properties:
|
|
server_id:
|
|
type: string
|
|
format: uuid
|
|
local_manifest_hash:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SyncPreviewResponse'
|
|
|
|
/api/v1/audit/logs:
|
|
get:
|
|
summary: Wyszukiwanie niezmiennych zdarzeń audytowych
|
|
security:
|
|
- KeycloakOIDC: ['thecr3w:admin']
|
|
parameters:
|
|
- name: resource_type
|
|
in: query
|
|
schema:
|
|
type: string
|
|
- name: from_timestamp
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date-time
|
|
- name: to_timestamp
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date-time
|
|
responses:
|
|
'200':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/AuditEventDto'
|
|
|
|
components:
|
|
securitySchemes:
|
|
KeycloakOIDC:
|
|
type: oauth2
|
|
flows:
|
|
authorizationCode:
|
|
authorizationUrl: https://login.thecr3wnet.com/realms/master/protocol/openid-connect/auth
|
|
tokenUrl: https://login.thecr3wnet.com/realms/master/protocol/openid-connect/token
|
|
scopes:
|
|
thecr3w:admin: Administrator całego ekosystemu
|
|
thecr3w:approver: Zatwierdzanie wdrożeń produkcyjnych
|
|
thecr3w:deployer: Wdrażanie i synchronizacja
|
|
thecr3w:viewer: Odczyt stanu wdrożeń i logów
|
|
|
|
schemas:
|
|
DeploymentManifestInput:
|
|
type: object
|
|
required: [project, environment, service_name, image, immutable_digest, config_hash, healthcheck, rollback_strategy, signature_ed25519]
|
|
properties:
|
|
project:
|
|
type: string
|
|
environment:
|
|
type: string
|
|
enum: [development, staging, production]
|
|
service_name:
|
|
type: string
|
|
image:
|
|
type: string
|
|
immutable_digest:
|
|
type: string
|
|
example: sha256:7a59d8134bb8df389a9f24255198ec51787c9dc08269d7b420f1885b0d0ce0bf
|
|
config_hash:
|
|
type: string
|
|
secrets_references:
|
|
type: array
|
|
items:
|
|
type: string
|
|
required_migrations:
|
|
type: array
|
|
items:
|
|
type: string
|
|
healthcheck:
|
|
type: object
|
|
rollback_strategy:
|
|
type: object
|
|
signature_ed25519:
|
|
type: string
|
|
|
|
ManifestResponse:
|
|
type: object
|
|
properties:
|
|
manifest_id:
|
|
type: string
|
|
format: uuid
|
|
manifest_sha256:
|
|
type: string
|
|
project:
|
|
type: string
|
|
environment:
|
|
type: string
|
|
status:
|
|
type: string
|
|
enum: [pending_approval, approved, rejected, executing, completed, failed, rolled_back]
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
|
|
DeploymentExecutionResponse:
|
|
type: object
|
|
properties:
|
|
deployment_id:
|
|
type: string
|
|
format: uuid
|
|
manifest_id:
|
|
type: string
|
|
format: uuid
|
|
status:
|
|
type: string
|
|
started_at:
|
|
type: string
|
|
format: date-time
|
|
|
|
DeploymentStatusResponse:
|
|
type: object
|
|
properties:
|
|
deployment_id:
|
|
type: string
|
|
format: uuid
|
|
status:
|
|
type: string
|
|
healthcheck_passed:
|
|
type: boolean
|
|
steps:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
step_name:
|
|
type: string
|
|
status:
|
|
type: string
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
details:
|
|
type: string
|
|
|
|
ExternalServerDto:
|
|
type: object
|
|
properties:
|
|
server_id:
|
|
type: string
|
|
format: uuid
|
|
name:
|
|
type: string
|
|
protocol:
|
|
type: string
|
|
enum: [sftp, ftps, ftp]
|
|
host:
|
|
type: string
|
|
port:
|
|
type: integer
|
|
remote_root_path:
|
|
type: string
|
|
host_key_fingerprint:
|
|
type: string
|
|
last_sync_at:
|
|
type: string
|
|
format: date-time
|
|
|
|
CreateExternalServerRequest:
|
|
type: object
|
|
required: [name, protocol, host, port, remote_root_path]
|
|
properties:
|
|
name:
|
|
type: string
|
|
protocol:
|
|
type: string
|
|
enum: [sftp, ftps, ftp]
|
|
host:
|
|
type: string
|
|
port:
|
|
type: integer
|
|
remote_root_path:
|
|
type: string
|
|
host_key_fingerprint:
|
|
type: string
|
|
tls_certificate_thumbprint:
|
|
type: string
|
|
|
|
SyncPreviewResponse:
|
|
type: object
|
|
properties:
|
|
files_to_upload:
|
|
type: integer
|
|
files_to_delete:
|
|
type: integer
|
|
total_transfer_bytes:
|
|
type: integer
|
|
diff_details:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
path:
|
|
type: string
|
|
action:
|
|
type: string
|
|
enum: [add, update, delete]
|
|
|
|
AuditEventDto:
|
|
type: object
|
|
properties:
|
|
event_id:
|
|
type: string
|
|
format: uuid
|
|
actor:
|
|
type: string
|
|
action:
|
|
type: string
|
|
resource_type:
|
|
type: string
|
|
resource_id:
|
|
type: string
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
ip_address:
|
|
type: string
|
|
success:
|
|
type: boolean
|
|
correlation_id:
|
|
type: string
|
|
|