stella-ops.org/git.stella-ops.org

Fork 0

Files

master d509c44411 release orchestrator pivot, architecture and planning

2026-01-10 22:37:22 +02:00

15 KiB

Raw Blame History

Entity Definitions

This document describes the core entities in the Release Orchestrator data model.

Entity Relationship Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                          ENTITY RELATIONSHIPS                               │
│                                                                             │
│  ┌──────────┐       ┌──────────────┐       ┌────────────┐                  │
│  │ Tenant   │───────│ Environment  │───────│ Target     │                  │
│  └──────────┘       └──────────────┘       └────────────┘                  │
│       │                    │                     │                          │
│       │                    │                     │                          │
│       ▼                    ▼                     ▼                          │
│  ┌──────────┐       ┌──────────────┐       ┌────────────┐                  │
│  │ Component│       │ Approval     │       │ Agent      │                  │
│  └──────────┘       │ Policy       │       └────────────┘                  │
│       │             └──────────────┘             │                          │
│       │                    │                     │                          │
│       ▼                    │                     ▼                          │
│  ┌──────────┐              │              ┌─────────────┐                  │
│  │ Version  │              │              │ Deployment  │                  │
│  │ Map      │              │              │ Task        │                  │
│  └──────────┘              │              └─────────────┘                  │
│       │                    │                     │                          │
│       │                    │                     │                          │
│       ▼                    │                     ▼                          │
│  ┌─────────────────────────┼─────────────────────────────┐                 │
│  │                         │                             │                 │
│  │  ┌──────────┐     ┌─────▼─────┐     ┌─────────────┐  │                 │
│  │  │ Release  │─────│ Promotion │─────│ Deployment  │  │                 │
│  │  └──────────┘     └───────────┘     │ Job         │  │                 │
│  │       │                 │           └─────────────┘  │                 │
│  │       │                 │                 │          │                 │
│  │       │                 ▼                 │          │                 │
│  │       │           ┌───────────┐           │          │                 │
│  │       │           │ Approval  │           │          │                 │
│  │       │           └───────────┘           │          │                 │
│  │       │                 │                 │          │                 │
│  │       │                 ▼                 ▼          │                 │
│  │       │           ┌───────────┐     ┌───────────┐   │                 │
│  │       │           │ Decision  │     │ Generated │   │                 │
│  │       │           │ Record    │     │ Artifacts │   │                 │
│  │       │           └───────────┘     └───────────┘   │                 │
│  │       │                 │                 │          │                 │
│  │       │                 └────────┬────────┘          │                 │
│  │       │                          │                   │                 │
│  │       │                          ▼                   │                 │
│  │       │                    ┌───────────┐             │                 │
│  │       └───────────────────►│ Evidence  │◄────────────┘                 │
│  │                            │ Packet    │                                │
│  │                            └───────────┘                                │
│  │                                  │                                      │
│  │                                  ▼                                      │
│  │                            ┌───────────┐                                │
│  │                            │ Version   │                                │
│  │                            │ Sticker   │                                │
│  │                            └───────────┘                                │
│  │                                                                         │
│  └─────────────────────────────────────────────────────────────────────────┘
└─────────────────────────────────────────────────────────────────────────────┘

Core Entities

Environment

Represents a deployment target environment (dev, staging, production).

Field	Type	Description
`id`	UUID	Primary key
`tenant_id`	UUID	Tenant reference
`name`	string	Unique name (e.g., "prod")
`display_name`	string	Display name (e.g., "Production")
`order_index`	integer	Promotion order
`config`	JSONB	Environment configuration
`freeze_windows`	JSONB	Active freeze windows
`required_approvals`	integer	Approvals needed for promotion
`require_sod`	boolean	Require separation of duties
`created_at`	timestamp	Creation time

Target

Represents a deployment target (host, service).

Field	Type	Description
`id`	UUID	Primary key
`tenant_id`	UUID	Tenant reference
`environment_id`	UUID	Environment reference
`name`	string	Target name
`target_type`	string	Type (docker_host, compose_host, etc.)
`connection`	JSONB	Connection configuration
`labels`	JSONB	Target labels
`health_status`	string	Current health status
`current_digest`	string	Currently deployed digest

Agent

Represents a deployment agent.

Field	Type	Description
`id`	UUID	Primary key
`tenant_id`	UUID	Tenant reference
`name`	string	Agent name
`version`	string	Agent version
`capabilities`	JSONB	Agent capabilities
`status`	string	online/offline/degraded
`last_heartbeat`	timestamp	Last heartbeat time

Component

Represents a deployable component (maps to an image repository).

Field	Type	Description
`id`	UUID	Primary key
`tenant_id`	UUID	Tenant reference
`name`	string	Component name
`display_name`	string	Display name
`image_repository`	string	Image repository URL
`versioning_strategy`	JSONB	How versions are determined
`default_channel`	string	Default version channel

Version Map

Maps image tags to digests and semantic versions.

Field	Type	Description
`id`	UUID	Primary key
`component_id`	UUID	Component reference
`tag`	string	Image tag
`digest`	string	Image digest (sha256:...)
`semver`	string	Semantic version
`channel`	string	Version channel (stable, beta)

Release

A versioned bundle of component digests.

Field	Type	Description
`id`	UUID	Primary key
`tenant_id`	UUID	Tenant reference
`name`	string	Release name
`display_name`	string	Display name
`components`	JSONB	Component/digest mappings
`source_ref`	JSONB	Source code reference
`status`	string	draft/ready/deployed/deprecated
`created_by`	UUID	Creator user reference

Promotion

A request to promote a release to an environment.

Field	Type	Description
`id`	UUID	Primary key
`tenant_id`	UUID	Tenant reference
`release_id`	UUID	Release reference
`source_environment_id`	UUID	Source environment (nullable)
`target_environment_id`	UUID	Target environment
`status`	string	Promotion status
`decision_record`	JSONB	Gate evaluation results
`workflow_run_id`	UUID	Associated workflow run
`requested_by`	UUID	Requesting user
`requested_at`	timestamp	Request time

Approval

An approval or rejection of a promotion.

Field	Type	Description
`id`	UUID	Primary key
`promotion_id`	UUID	Promotion reference
`approver_id`	UUID	Approving user
`action`	string	approved/rejected
`comment`	string	Approval comment
`approved_at`	timestamp	Approval time

Deployment Job

A deployment execution job.

Field	Type	Description
`id`	UUID	Primary key
`promotion_id`	UUID	Promotion reference
`release_id`	UUID	Release reference
`environment_id`	UUID	Environment reference
`status`	string	Job status
`strategy`	string	Deployment strategy
`artifacts`	JSONB	Generated artifacts
`rollback_of`	UUID	If rollback, original job

Deployment Task

A task to deploy to a single target.

Field	Type	Description
`id`	UUID	Primary key
`job_id`	UUID	Job reference
`target_id`	UUID	Target reference
`digest`	string	Digest to deploy
`status`	string	Task status
`agent_id`	UUID	Assigned agent
`logs`	text	Execution logs
`previous_digest`	string	Previous digest (for rollback)

Evidence Packet

Immutable audit evidence for a promotion/deployment.

Field	Type	Description
`id`	UUID	Primary key
`promotion_id`	UUID	Promotion reference
`packet_type`	string	Type of evidence
`content`	JSONB	Evidence content
`content_hash`	string	SHA-256 of content
`signature`	string	Cryptographic signature
`signer_key_ref`	string	Signing key reference
`created_at`	timestamp	Creation time (no update)

Version Sticker

Version marker placed on deployment targets.

Field	Type	Description
`id`	UUID	Primary key
`target_id`	UUID	Target reference
`release_id`	UUID	Release reference
`promotion_id`	UUID	Promotion reference
`sticker_content`	JSONB	Sticker JSON content
`content_hash`	string	Content hash
`written_at`	timestamp	Write time
`drift_detected`	boolean	Drift detection flag

Workflow Entities

Workflow Template

A reusable workflow definition.

Field	Type	Description
`id`	UUID	Primary key
`tenant_id`	UUID	Tenant reference (null for builtin)
`name`	string	Template name
`version`	integer	Template version
`nodes`	JSONB	Step nodes
`edges`	JSONB	Step edges
`inputs`	JSONB	Input definitions
`outputs`	JSONB	Output definitions
`is_builtin`	boolean	Is built-in template

Workflow Run

An execution of a workflow template.

Field	Type	Description
`id`	UUID	Primary key
`template_id`	UUID	Template reference
`template_version`	integer	Template version at execution
`status`	string	Run status
`context`	JSONB	Execution context
`inputs`	JSONB	Input values
`outputs`	JSONB	Output values
`started_at`	timestamp	Start time
`completed_at`	timestamp	Completion time

Step Run

Execution of a single step within a workflow run.

Field	Type	Description
`id`	UUID	Primary key
`workflow_run_id`	UUID	Workflow run reference
`node_id`	string	Node ID from template
`status`	string	Step status
`inputs`	JSONB	Resolved inputs
`outputs`	JSONB	Produced outputs
`logs`	text	Execution logs
`attempt_number`	integer	Retry attempt number

Plugin Entities

Plugin

A registered plugin.

Field	Type	Description
`id`	UUID	Primary key
`plugin_id`	string	Unique plugin identifier
`version`	string	Plugin version
`vendor`	string	Plugin vendor
`manifest`	JSONB	Plugin manifest
`status`	string	Plugin status
`entrypoint`	string	Plugin entrypoint path

Plugin Instance

A tenant-specific plugin configuration.

Field	Type	Description
`id`	UUID	Primary key
`plugin_id`	UUID	Plugin reference
`tenant_id`	UUID	Tenant reference
`config`	JSONB	Tenant configuration
`enabled`	boolean	Is enabled for tenant

Integration Entities

Integration

A configured external integration.

Field	Type	Description
`id`	UUID	Primary key
`tenant_id`	UUID	Tenant reference
`type_id`	string	Integration type
`name`	string	Integration name
`config`	JSONB	Integration configuration
`credential_ref`	string	Vault credential reference
`health_status`	string	Connection health

15 KiB Raw Blame History