release orchestrator pivot, architecture and planning
This commit is contained in:
412
docs/modules/release-orchestrator/integrations/overview.md
Normal file
412
docs/modules/release-orchestrator/integrations/overview.md
Normal file
@@ -0,0 +1,412 @@
|
||||
# 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
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
```typescript
|
||||
// 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
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
```http
|
||||
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
|
||||
|
||||
```http
|
||||
POST /api/v1/integrations/{id}/test
|
||||
```
|
||||
|
||||
Response:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"connectivityTest": { "status": "passed", "latencyMs": 45 },
|
||||
"authenticationTest": { "status": "passed", "latencyMs": 120 },
|
||||
"functionalityTest": { "status": "passed", "latencyMs": 230 }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Discover Resources
|
||||
|
||||
```http
|
||||
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
|
||||
|
||||
```typescript
|
||||
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
|
||||
};
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
- [Connectors](connectors.md)
|
||||
- [Webhooks](webhooks.md)
|
||||
- [CI/CD Integration](ci-cd.md)
|
||||
- [Integration Hub Module](../modules/integration-hub.md)
|
||||
Reference in New Issue
Block a user