Files

master d509c44411 release orchestrator pivot, architecture and planning

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

15 KiB

Raw Permalink Blame History

Integrations Overview

Purpose

The Integration Hub (INTHUB) provides a unified interface for connecting Release Orchestrator to external systems including container registries, CI/CD pipelines, notification services, secret stores, and metrics providers.

Integration Architecture

              INTEGRATION HUB ARCHITECTURE

  ┌─────────────────────────────────────────────────────────────────────────────┐
  │                          INTEGRATION HUB                                     │
  │                                                                             │
  │  ┌─────────────────────────────────────────────────────────────────────┐   │
  │  │                     INTEGRATION MANAGER                              │   │
  │  │                                                                      │   │
  │  │  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐   │   │
  │  │  │ Type       │  │ Instance   │  │ Health     │  │ Discovery  │   │   │
  │  │  │ Registry   │  │ Manager    │  │ Monitor    │  │ Service    │   │   │
  │  │  └────────────┘  └────────────┘  └────────────┘  └────────────┘   │   │
  │  │                                                                      │   │
  │  └─────────────────────────────────────────────────────────────────────┘   │
  │                                    │                                        │
  │                                    ▼                                        │
  │  ┌─────────────────────────────────────────────────────────────────────┐   │
  │  │                     CONNECTOR RUNTIME                                │   │
  │  │                                                                      │   │
  │  │  ┌──────────────────────────────────────────────────────────────┐   │   │
  │  │  │                  CONNECTOR POOL                               │   │   │
  │  │  │                                                               │   │   │
  │  │  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │   │   │
  │  │  │  │ Docker   │ │ GitLab   │ │ Slack    │ │ Vault    │       │   │   │
  │  │  │  │ Registry │ │ CI       │ │          │ │          │       │   │   │
  │  │  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘       │   │   │
  │  │  │                                                               │   │   │
  │  │  └──────────────────────────────────────────────────────────────┘   │   │
  │  │                                                                      │   │
  │  └─────────────────────────────────────────────────────────────────────┘   │
  │                                                                             │
  └─────────────────────────────────────────────────────────────────────────────┘
                                       │
       ┌─────────────┬─────────────────┼─────────────────┬─────────────┐
       │             │                 │                 │             │
       ▼             ▼                 ▼                 ▼             ▼
  ┌─────────┐  ┌─────────┐       ┌─────────┐       ┌─────────┐  ┌─────────┐
  │Container│  │ CI/CD   │       │ Notifi- │       │ Secret  │  │ Metrics │
  │Registry │  │ Systems │       │ cations │       │ Stores  │  │ Systems │
  └─────────┘  └─────────┘       └─────────┘       └─────────┘  └─────────┘

Integration Types

Container Registries

Type ID	Description	Discovery Support
`docker-registry`	Docker Registry v2 API	Yes
`docker-hub`	Docker Hub	Yes
`gcr`	Google Container Registry	Yes
`ecr`	AWS Elastic Container Registry	Yes
`acr`	Azure Container Registry	Yes
`ghcr`	GitHub Container Registry	Yes
`harbor`	Harbor Registry	Yes
`jfrog`	JFrog Artifactory	Yes
`nexus`	Sonatype Nexus	Yes
`quay`	Quay.io	Yes

CI/CD Systems

Type ID	Description	Trigger Support
`gitlab-ci`	GitLab CI/CD	Yes
`github-actions`	GitHub Actions	Yes
`jenkins`	Jenkins	Yes
`azure-devops`	Azure DevOps Pipelines	Yes
`circleci`	CircleCI	Yes
`teamcity`	TeamCity	Yes
`drone`	Drone CI	Yes

Notification Services

Type ID	Description	Features
`slack`	Slack	Channels, threads, reactions
`teams`	Microsoft Teams	Channels, cards
`email`	Email (SMTP)	Templates, attachments
`webhook`	Generic Webhook	JSON payloads
`pagerduty`	PagerDuty	Incidents, alerts
`opsgenie`	OpsGenie	Alerts, on-call

Secret Stores

Type ID	Description	Features
`hashicorp-vault`	HashiCorp Vault	KV, Transit, PKI
`aws-secrets-manager`	AWS Secrets Manager	Rotation, versioning
`azure-key-vault`	Azure Key Vault	Keys, secrets, certs
`gcp-secret-manager`	GCP Secret Manager	Versions, labels

Metrics & Monitoring

Type ID	Description	Use Case
`prometheus`	Prometheus	Canary metrics
`datadog`	Datadog	APM, logs, metrics
`newrelic`	New Relic	APM, infra monitoring
`dynatrace`	Dynatrace	Full-stack monitoring

Integration Configuration

Integration Entity

interface Integration {
  id: UUID;
  tenantId: UUID;
  typeId: string;           // e.g., "docker-registry"
  name: string;             // Display name
  description?: string;

  // Connection configuration
  config: IntegrationConfig;

  // Credential reference (stored in vault)
  credentialRef: string;

  // Health tracking
  healthStatus: "healthy" | "degraded" | "unhealthy" | "unknown";
  lastHealthCheck?: DateTime;

  // Metadata
  labels: Record<string, string>;
  createdAt: DateTime;
  updatedAt: DateTime;
}

interface IntegrationConfig {
  // Common fields
  url?: string;
  timeout?: number;
  retries?: number;

  // Type-specific fields
  [key: string]: any;
}

Type-Specific Configuration

// Docker Registry
interface DockerRegistryConfig extends IntegrationConfig {
  url: string;                    // https://registry.example.com
  repository?: string;            // Optional default repository
  insecureSkipVerify?: boolean;   // Skip TLS verification
}

// GitLab CI
interface GitLabCIConfig extends IntegrationConfig {
  url: string;                    // https://gitlab.example.com
  projectId: string;              // Project ID or path
  defaultBranch?: string;         // Default ref for triggers
}

// Slack
interface SlackConfig extends IntegrationConfig {
  workspace?: string;             // Workspace identifier
  defaultChannel?: string;        // Default channel for notifications
  iconEmoji?: string;             // Bot icon
}

// HashiCorp Vault
interface VaultConfig extends IntegrationConfig {
  url: string;                    // https://vault.example.com
  namespace?: string;             // Vault namespace
  mountPath: string;              // Secret mount path
  authMethod: "token" | "approle" | "kubernetes";
}

Credential Management

Credentials are never stored in the Release Orchestrator database. Instead, references to external secret stores are used.

Credential Reference Format

vault://vault-integration-id/path/to/secret#key
       └─────────┬────────┘ └─────┬─────┘ └┬┘
              Vault ID       Secret path   Key

Credential Types

type CredentialType =
  | "basic"           // Username/password
  | "token"           // Bearer token
  | "api-key"         // API key
  | "oauth2"          // OAuth2 credentials
  | "service-account" // GCP/K8s service account
  | "certificate";    // Client certificate

interface CredentialReference {
  type: CredentialType;
  ref: string;        // Vault reference
}

// Examples
const dockerCreds: CredentialReference = {
  type: "basic",
  ref: "vault://vault-1/docker/registry.example.com#credentials"
};

const gitlabToken: CredentialReference = {
  type: "token",
  ref: "vault://vault-1/ci/gitlab#access_token"
};

Health Monitoring

Health Check Types

Check Type	Description	Frequency
`connectivity`	TCP/HTTP connectivity	1 min
`authentication`	Credential validity	5 min
`functionality`	Full operation test	15 min

Health Check Flow

interface HealthCheckResult {
  integrationId: UUID;
  checkType: string;
  status: "healthy" | "degraded" | "unhealthy";
  latencyMs: number;
  message?: string;
  checkedAt: DateTime;
}

class IntegrationHealthMonitor {
  async checkHealth(integration: Integration): Promise<HealthCheckResult> {
    const connector = this.connectorPool.get(integration.typeId);
    const startTime = Date.now();

    try {
      // Connectivity check
      await connector.ping(integration.config);

      // Authentication check
      const creds = await this.fetchCredentials(integration.credentialRef);
      await connector.authenticate(integration.config, creds);

      return {
        integrationId: integration.id,
        checkType: "full",
        status: "healthy",
        latencyMs: Date.now() - startTime,
        checkedAt: new Date()
      };
    } catch (error) {
      return {
        integrationId: integration.id,
        checkType: "full",
        status: this.classifyError(error),
        latencyMs: Date.now() - startTime,
        message: error.message,
        checkedAt: new Date()
      };
    }
  }
}

Discovery Service

Integrations can discover resources from connected systems.

Discovery Operations

interface DiscoveryService {
  // Discover available repositories
  discoverRepositories(integrationId: UUID): Promise<Repository[]>;

  // Discover tags/versions
  discoverTags(integrationId: UUID, repository: string): Promise<Tag[]>;

  // Discover pipelines
  discoverPipelines(integrationId: UUID): Promise<Pipeline[]>;

  // Discover notification channels
  discoverChannels(integrationId: UUID): Promise<Channel[]>;
}

// Example: Discover Docker repositories
const repos = await discoveryService.discoverRepositories(dockerIntegrationId);
// Returns: [{ name: "myapp", tags: ["latest", "v1.0.0", ...] }, ...]

Discovery Caching

interface DiscoveryCache {
  key: string;              // integration_id:resource_type
  data: any;
  discoveredAt: DateTime;
  ttlSeconds: number;
}

// Cache TTLs by resource type
const cacheTTLs = {
  repositories: 3600,     // 1 hour
  tags: 300,              // 5 minutes
  pipelines: 3600,        // 1 hour
  channels: 86400         // 24 hours
};

API Reference

Create Integration

POST /api/v1/integrations
Content-Type: application/json

{
  "typeId": "docker-registry",
  "name": "Production Registry",
  "config": {
    "url": "https://registry.example.com",
    "repository": "myorg"
  },
  "credentialRef": "vault://vault-1/docker/prod-registry#credentials",
  "labels": {
    "environment": "production"
  }
}

Test Integration

POST /api/v1/integrations/{id}/test

Response:

{
  "success": true,
  "data": {
    "connectivityTest": { "status": "passed", "latencyMs": 45 },
    "authenticationTest": { "status": "passed", "latencyMs": 120 },
    "functionalityTest": { "status": "passed", "latencyMs": 230 }
  }
}

Discover Resources

POST /api/v1/integrations/{id}/discover
Content-Type: application/json

{
  "resourceType": "repositories",
  "filter": {
    "namePattern": "myapp-*"
  }
}

Error Handling

Integration Errors

Error Code	Description	Retry Strategy
`INTEGRATION_NOT_FOUND`	Integration ID not found	No retry
`INTEGRATION_UNHEALTHY`	Integration health check failing	Backoff retry
`CREDENTIAL_FETCH_FAILED`	Cannot fetch credentials	Retry with backoff
`CONNECTION_REFUSED`	Cannot connect to endpoint	Retry with backoff
`AUTHENTICATION_FAILED`	Invalid credentials	No retry
`RATE_LIMITED`	Too many requests	Retry after delay

Circuit Breaker

interface CircuitBreakerConfig {
  failureThreshold: number;     // Failures before opening
  successThreshold: number;     // Successes to close
  timeout: number;              // Time in open state (ms)
}

// Default configuration
const defaultCircuitBreaker: CircuitBreakerConfig = {
  failureThreshold: 5,
  successThreshold: 3,
  timeout: 60000
};

15 KiB Raw Permalink Blame History