Skip to main content

Deployment - API Specification

Version: v0.2.0 | Status: Active | Last Updated: March 2026

Introduction​

The Deployment module provides tools for managing application deployments, including various deployment strategies (canary, blue-green, rolling), a high-level manager, and GitOps synchronization capabilities.

Endpoints / Functions / Interfaces​

Class: DeploymentManager​

  • Description: Central manager for deployment operations.
  • Constructor:
    • config (dict, optional): Deployment configuration.
  • Methods:

deploy(service_name: str, version: str, strategy: DeploymentStrategy | None = None, targets: list[DeploymentTarget] | None = None) -> DeploymentResult​

  • Description: Deploy a new version of a service.
  • Parameters:
    • service_name (str): Name of the service to deploy.
    • version (str): Version to deploy.
    • strategy (DeploymentStrategy, optional): Strategy to use. Defaults to RollingDeployment.
    • targets (list[DeploymentTarget], optional): List of targets. Defaults to three local deployment targets if None.
  • Returns:
    • DeploymentResult: Outcome of the deployment.

rollback(service_name: str, previous_version: str, strategy: DeploymentStrategy | None = None, targets: list[DeploymentTarget] | None = None) -> DeploymentResult​

  • Description: Rollback to a previous version.
  • Parameters:
    • service_name (str): Service name.
    • previous_version (str): Version to rollback to.
    • strategy (DeploymentStrategy, optional): Strategy to use.
    • targets (list[DeploymentTarget], optional): List of targets.
  • Returns:
    • DeploymentResult: Outcome of the rollback.

get_active_version(service_name: str) -> str | None​

  • Description: Get the currently active version for a service.
  • Returns:
    • str | None: Active version or None.

Class: DeploymentStrategy (Abstract)​

  • Methods:
    • deploy(targets: list[DeploymentTarget], version: str, deploy_fn: Callable) -> DeploymentResult: Execute deployment.
    • rollback(targets: list[DeploymentTarget], previous_version: str, deploy_fn: Callable) -> DeploymentResult: Execute rollback.

Class: RollingDeployment​

  • Constructor:
    • batch_size (int): Number of targets per batch. Default: 1.
    • delay_seconds (float): Delay between batches. Default: 0.0.
    • health_check (Callable, optional): Health check function.

Class: BlueGreenDeployment​

  • Constructor:
    • switch_fn (Callable, optional): Function to switch traffic.
    • health_check (Callable, optional): Health check function.

Class: CanaryDeployment​

  • Constructor:
    • stages (list[float], optional): Traffic percentages per stage. Default: [10, 25, 50, 100].
    • stage_duration_seconds (float): Delay between stages. Default: 0.0.
    • health_check (Callable, optional): Health check function.
    • success_threshold (float): Success rate required to proceed. Default: 0.95.

Class: GitOpsSynchronizer​

  • Constructor:
    • repo_url (str): Git repository URL.
    • local_path (str): Local path for the repository.
  • Methods:
    • sync(branch: str = "main") -> bool: Synchronize with the remote repository.
    • get_version() -> str | None: Get the current commit SHA.
    • checkout(revision: str) -> bool: Checkout a specific revision.
    • is_dirty() -> bool: Check for uncommitted local changes.

Data Models​

Model: DeploymentTarget​

  • id (str): Unique target identifier.
  • name (str): Human-readable name.
  • address (str): Network address.
  • healthy (bool): Current health status.
  • version (str | None): Currently deployed version.
  • metadata (dict): Additional metadata.

Model: DeploymentResult​

  • success (bool): Whether the operation succeeded.
  • targets_updated (int): Number of targets successfully updated.
  • targets_failed (int): Number of targets that failed update.
  • duration_ms (float): Duration of the operation in milliseconds.
  • state (DeploymentState): Final state (COMPLETED, FAILED, ROLLED_BACK).
  • errors (list[str]): List of error messages.
  • metadata (dict): Additional operation metadata.