Documentation
¶
Index ¶
- Constants
- Variables
- func Prepare(ctx context.Context, application string, requests []Request) (*Execution, Result, error)
- func RequireIntegrationContract(descriptor IntegrationDescriptor) error
- func ValidateProviderPlacement(descriptor IntegrationDescriptor, placement ProviderPlacement) error
- type AuthorizationMetadata
- type Binding
- type CapabilitySpecification
- type ConformanceCheck
- type ConformanceReport
- type ConformanceStatus
- type CredentialReference
- type Diagnostic
- type Driver
- type DriverAdapter
- func (a *DriverAdapter) Bind(ctx context.Context, resource Resource, binding Binding) error
- func (a *DriverAdapter) Descriptor() Provider
- func (a *DriverAdapter) IntegrationDescriptor() IntegrationDescriptor
- func (a *DriverAdapter) Preflight(ctx context.Context, resource Resource, binding Binding) error
- func (a *DriverAdapter) Provision(ctx context.Context, resource Resource, binding Binding) error
- func (a *DriverAdapter) Verify(ctx context.Context, resource Resource, binding Binding) error
- type Execution
- type HTTPExposureBinding
- type IntegrationDescriptor
- type IntegrationDriver
- type Kind
- type LifecycleAction
- type LifecycleOperation
- type LogsBinding
- type MetricsBinding
- type OTLPTelemetryBinding
- type ObjectStorageS3Binding
- type ObservabilitySignalKind
- type OptionalLifecycleSupport
- type Phase
- type Plan
- type PlanItem
- type Provider
- type ProviderBinding
- type ProviderInstance
- type ProviderKind
- type ProviderObservability
- type ProviderObservabilitySignal
- type ProviderOperation
- type ProviderOperationObservation
- type ProviderOperationObserver
- type ProviderOwnership
- type ProviderPlacement
- type ProviderScope
- type ReconciliationDriver
- type ReconciliationResult
- type Registry
- func (r Registry) ApplicationLifecycle(application string, operation LifecycleOperation) ([]LifecycleAction, error)
- func (r *Registry) Bind(resource Resource, providerInstanceID string) error
- func (r *Registry) Register(instance ProviderInstance) error
- func (r *Registry) ReleaseApplication(application string)
- func (r *Registry) ReleaseManagedApplication(application string)
- func (r Registry) Resolve(provider ProviderKind, scope ProviderScope, application, externalID string) (ProviderInstance, error)
- func (r Registry) ResolvePlacement(provider ProviderKind, placement ProviderPlacement, application string) (ProviderInstance, error)
- func (r Registry) Validate() error
- type RegistryStore
- type Request
- type Requirement
- type Resource
- type Result
- type SecretReference
- type SecureBinding
- type SecurityLifecycleSupport
- type Severity
- type SpecificationID
- type SpecificationVersion
- type Status
- type StepResult
- type TrustMaterialReference
- type WorkloadIdentityBinding
Constants ¶
const ProviderProtocolV1 = "baseharbor.provider/v1"
const RegistryVersion = 1
Variables ¶
var ( PostgreSQL = Provider{Kind: ProviderPostgreSQL, Capabilities: []Kind{SQL}} Valkey = Provider{Kind: ProviderValkey, Capabilities: []Kind{KeyValue}} OpenBao = Provider{Kind: ProviderOpenBao, Capabilities: []Kind{Secrets}} Caddy = Provider{Kind: ProviderCaddy, Capabilities: []Kind{ExposureHTTP}} SeaweedFS = Provider{Kind: ProviderSeaweedFS, Capabilities: []Kind{ObjectStorageS3}} OTelCollector = Provider{Kind: ProviderOTelCollector, Capabilities: []Kind{TelemetryOTLP}} ExternalOTLP = Provider{Kind: ProviderExternalOTLP, Capabilities: []Kind{TelemetryOTLP}} Prometheus = Provider{Kind: ProviderPrometheus, Capabilities: []Kind{Metrics}} Loki = Provider{Kind: ProviderLoki, Capabilities: []Kind{Logs}} Tempo = Provider{Kind: ProviderTempo, Capabilities: []Kind{Traces}} )
Reference providers describe the capability products already used by the current Compose implementation. They are descriptors only: existing provisioning remains authoritative while the shared capability and provider registry layers describe portable intent, placement and ownership.
var ( PostgreSQLIntegration = IntegrationDescriptor{ Protocol: ProviderProtocolV1, Provider: PostgreSQL, Capabilities: []SpecificationID{SQLV1.ID}, SupportedScopes: []ProviderScope{ScopeApplication}, } ValkeyIntegration = IntegrationDescriptor{ Protocol: ProviderProtocolV1, Provider: Valkey, Capabilities: []SpecificationID{KeyValueV1.ID}, SupportedScopes: []ProviderScope{ScopeApplication}, } OpenBaoIntegration = IntegrationDescriptor{ Protocol: ProviderProtocolV1, Provider: OpenBao, Capabilities: []SpecificationID{SecretsV1.ID}, SupportedScopes: []ProviderScope{ScopeShared}, Optional: OptionalLifecycleSupport{Status: true, Update: true, Backup: true, Restore: true, Destroy: true}, } CaddyIntegration = IntegrationDescriptor{ Protocol: ProviderProtocolV1, Provider: Caddy, Capabilities: []SpecificationID{ExposureHTTPV1.ID}, SupportedScopes: []ProviderScope{ScopeApplication}, Optional: OptionalLifecycleSupport{Status: true, Update: true, Destroy: true}, } SeaweedFSIntegration = IntegrationDescriptor{ Protocol: ProviderProtocolV1, Provider: SeaweedFS, Capabilities: []SpecificationID{ObjectStorageS3V1.ID}, SupportedScopes: []ProviderScope{ScopeShared}, Optional: OptionalLifecycleSupport{Status: true, Update: true, Destroy: true}, } OTelCollectorIntegration = IntegrationDescriptor{ Protocol: ProviderProtocolV1, Provider: OTelCollector, Capabilities: []SpecificationID{TelemetryOTLPV1.ID}, SupportedScopes: []ProviderScope{ScopeShared}, Optional: OptionalLifecycleSupport{Status: true, Update: true, Destroy: true}, Observability: ProviderObservability{Signals: []ProviderObservabilitySignal{ {Name: "collector", Kind: ObservabilityMetrics, Protocol: "openmetrics", Port: 8888, Path: "/metrics"}, }}, } PrometheusIntegration = IntegrationDescriptor{ Protocol: ProviderProtocolV1, Provider: Prometheus, Capabilities: []SpecificationID{MetricsV1.ID}, SupportedScopes: []ProviderScope{ScopeShared, ScopeApplication}, Optional: OptionalLifecycleSupport{Status: true, Update: true, Destroy: true}, } LokiIntegration = IntegrationDescriptor{ Protocol: ProviderProtocolV1, Provider: Loki, Capabilities: []SpecificationID{LogsV1.ID}, SupportedScopes: []ProviderScope{ScopeShared, ScopeApplication}, Optional: OptionalLifecycleSupport{Status: true, Update: true, Destroy: true}, Observability: ProviderObservability{Signals: []ProviderObservabilitySignal{ {Name: "loki", Kind: ObservabilityMetrics, Protocol: "openmetrics", Port: 3100, Path: "/metrics"}, }}, } TempoIntegration = IntegrationDescriptor{ Protocol: ProviderProtocolV1, Provider: Tempo, Capabilities: []SpecificationID{TracesV1.ID}, SupportedScopes: []ProviderScope{ScopeShared}, Optional: OptionalLifecycleSupport{Status: true, Update: true, Destroy: true}, Observability: ProviderObservability{Signals: []ProviderObservabilitySignal{ {Name: "tempo", Kind: ObservabilityMetrics, Protocol: "openmetrics", Port: 3200, Path: "/metrics"}, }}, } ExternalOTLPIntegration = IntegrationDescriptor{ Protocol: ProviderProtocolV1, Provider: ExternalOTLP, Capabilities: []SpecificationID{TelemetryOTLPV1.ID}, SupportedScopes: []ProviderScope{ScopeExternal}, } )
var ( SQLV1 = CapabilitySpecification{ID: "database.sql/v1", Kind: SQL, Version: SpecificationV1} KeyValueV1 = CapabilitySpecification{ID: "cache.key-value/v1", Kind: KeyValue, Version: SpecificationV1} SecretsV1 = CapabilitySpecification{ID: "secrets/v1", Kind: Secrets, Version: SpecificationV1} ExposureHTTPV1 = CapabilitySpecification{ID: "exposure.http/v1", Kind: ExposureHTTP, Version: SpecificationV1} ObjectStorageS3V1 = CapabilitySpecification{ID: "object-storage.s3/v1", Kind: ObjectStorageS3, Version: SpecificationV1} TelemetryOTLPV1 = CapabilitySpecification{ID: "telemetry.otlp/v1", Kind: TelemetryOTLP, Version: SpecificationV1} MetricsV1 = CapabilitySpecification{ID: "metrics/v1", Kind: Metrics, Version: SpecificationV1} LogsV1 = CapabilitySpecification{ID: "logs/v1", Kind: Logs, Version: SpecificationV1} TracesV1 = CapabilitySpecification{ID: "traces/v1", Kind: Traces, Version: SpecificationV1} )
Functions ¶
func RequireIntegrationContract ¶ added in v0.4.3
func RequireIntegrationContract(descriptor IntegrationDescriptor) error
func ValidateProviderPlacement ¶ added in v0.4.8
func ValidateProviderPlacement(descriptor IntegrationDescriptor, placement ProviderPlacement) error
Types ¶
type AuthorizationMetadata ¶ added in v0.4.5
type Binding ¶
type Binding struct {
Resource Resource `json:"resource"`
Workload string `json:"workload"`
HTTPExposure *HTTPExposureBinding `json:"http_exposure,omitempty"`
ObjectStorageS3 *ObjectStorageS3Binding `json:"object_storage_s3,omitempty"`
TelemetryOTLP *OTLPTelemetryBinding `json:"telemetry_otlp,omitempty"`
Metrics *MetricsBinding `json:"metrics,omitempty"`
Logs *LogsBinding `json:"logs,omitempty"`
Security *SecureBinding `json:"security,omitempty"`
}
type CapabilitySpecification ¶ added in v0.4.3
type CapabilitySpecification struct {
ID SpecificationID `json:"id"`
Kind Kind `json:"kind"`
Version SpecificationVersion `json:"version"`
}
func ParseSpecificationID ¶ added in v0.4.3
func ParseSpecificationID(id SpecificationID) (CapabilitySpecification, error)
func SpecificationForKind ¶ added in v0.4.3
func SpecificationForKind(kind Kind) (CapabilitySpecification, error)
type ConformanceCheck ¶ added in v0.4.3
type ConformanceCheck struct {
Name string `json:"name"`
Status ConformanceStatus `json:"status"`
Message string `json:"message,omitempty"`
}
type ConformanceReport ¶ added in v0.4.3
type ConformanceReport struct {
Protocol string `json:"protocol"`
Provider ProviderKind `json:"provider"`
Status ConformanceStatus `json:"status"`
Checks []ConformanceCheck `json:"checks"`
}
func CheckIntegrationContract ¶ added in v0.4.3
func CheckIntegrationContract(descriptor IntegrationDescriptor) ConformanceReport
CheckIntegrationContract performs transport-independent static conformance. Runtime capability conformance remains provider/capability specific and will build on this report as reference providers are added.
type ConformanceStatus ¶ added in v0.4.3
type ConformanceStatus string
const ( ConformancePass ConformanceStatus = "pass" ConformanceFail ConformanceStatus = "fail" )
type CredentialReference ¶ added in v0.4.5
type Diagnostic ¶
type DriverAdapter ¶ added in v0.4.3
type DriverAdapter struct {
// contains filtered or unexported fields
}
DriverAdapter lets current built-in drivers participate in the integration contract without changing their implementation or introducing a second lifecycle engine.
func NewDriverAdapter ¶ added in v0.4.3
func NewDriverAdapter(driver Driver, descriptor IntegrationDescriptor) (*DriverAdapter, error)
func (*DriverAdapter) Descriptor ¶ added in v0.4.3
func (a *DriverAdapter) Descriptor() Provider
func (*DriverAdapter) IntegrationDescriptor ¶ added in v0.4.3
func (a *DriverAdapter) IntegrationDescriptor() IntegrationDescriptor
type Execution ¶ added in v0.4.4
type Execution struct {
// contains filtered or unexported fields
}
Execution is one prepared provider lifecycle. Prepare performs all resolution/preflight work without mutation. ProvisionAndBind and Verify can then be coordinated around runtime/workload convergence without duplicating provider lifecycle semantics.
func (*Execution) ProvisionAndBind ¶ added in v0.4.4
type HTTPExposureBinding ¶ added in v0.4.4
type IntegrationDescriptor ¶ added in v0.4.3
type IntegrationDescriptor struct {
Protocol string `json:"protocol"`
Provider Provider `json:"provider"`
Capabilities []SpecificationID `json:"capabilities"`
SupportedScopes []ProviderScope `json:"supported_scopes"`
Optional OptionalLifecycleSupport `json:"optional_lifecycle"`
Observability ProviderObservability `json:"observability,omitempty"`
}
func ReferenceIntegration ¶ added in v0.4.3
func ReferenceIntegration(provider ProviderKind) (IntegrationDescriptor, error)
func (IntegrationDescriptor) SupportsScope ¶ added in v0.4.8
func (d IntegrationDescriptor) SupportsScope(scope ProviderScope) bool
func (IntegrationDescriptor) Validate ¶ added in v0.4.3
func (d IntegrationDescriptor) Validate() error
type IntegrationDriver ¶ added in v0.4.3
type IntegrationDriver interface {
Driver
IntegrationDescriptor() IntegrationDescriptor
}
IntegrationDriver is the semantic boundary shared by built-in providers and future external provider adapters. The existing Driver lifecycle remains the required mutation path; this interface adds a versioned integration contract.
type Kind ¶
type Kind string
Kind identifies portable application behavior. It describes what an application needs, never which product or runtime satisfies that need.
type LifecycleAction ¶ added in v0.4.2
type LifecycleAction struct {
ProviderInstanceID string `json:"provider_instance_id"`
Scope ProviderScope `json:"scope"`
Ownership ProviderOwnership `json:"ownership"`
Operation LifecycleOperation `json:"operation"`
MutateProvider bool `json:"mutate_provider"`
RemoveBinding bool `json:"remove_binding"`
}
type LifecycleOperation ¶ added in v0.4.2
type LifecycleOperation string
const ( LifecycleUpdate LifecycleOperation = "update" LifecycleBackup LifecycleOperation = "backup" LifecycleDestroy LifecycleOperation = "destroy" )
type LogsBinding ¶ added in v0.4.9
type MetricsBinding ¶ added in v0.4.8
type OTLPTelemetryBinding ¶ added in v0.4.7
type ObjectStorageS3Binding ¶ added in v0.4.6
type ObjectStorageS3Binding struct {
Bucket string `json:"bucket"`
}
type ObservabilitySignalKind ¶ added in v0.4.10
type ObservabilitySignalKind string
const ( ObservabilityMetrics ObservabilitySignalKind = "metrics" ObservabilityLogs ObservabilitySignalKind = "logs" ObservabilityTraces ObservabilitySignalKind = "traces" )
type OptionalLifecycleSupport ¶ added in v0.4.3
type Provider ¶
type Provider struct {
Kind ProviderKind `json:"kind"`
Capabilities []Kind `json:"capabilities"`
}
Provider describes the capability surface of one provider implementation. Placement and ownership stay outside portable capability intent and are represented separately by the provider registry.
type ProviderBinding ¶ added in v0.4.2
type ProviderInstance ¶ added in v0.4.2
type ProviderInstance struct {
ID string `json:"id"`
Provider Provider `json:"provider"`
Scope ProviderScope `json:"scope"`
SharingBoundary string `json:"sharing_boundary,omitempty"`
Ownership ProviderOwnership `json:"ownership"`
OwnerApplication string `json:"owner_application,omitempty"`
Reference string `json:"reference,omitempty"`
}
type ProviderKind ¶
type ProviderKind string
ProviderKind identifies a capability implementation. Capability providers are independent from runtime providers such as Compose.
const ( ProviderPostgreSQL ProviderKind = "postgresql" ProviderValkey ProviderKind = "valkey" ProviderOpenBao ProviderKind = "openbao" ProviderCaddy ProviderKind = "caddy" ProviderSeaweedFS ProviderKind = "seaweedfs" ProviderOTelCollector ProviderKind = "opentelemetry-collector" ProviderExternalOTLP ProviderKind = "external-otlp" ProviderPrometheus ProviderKind = "prometheus" ProviderLoki ProviderKind = "loki" ProviderTempo ProviderKind = "tempo" )
type ProviderObservability ¶ added in v0.4.10
type ProviderObservability struct {
Signals []ProviderObservabilitySignal `json:"signals,omitempty"`
}
type ProviderObservabilitySignal ¶ added in v0.4.10
type ProviderObservabilitySignal struct {
Name string `json:"name"`
Kind ObservabilitySignalKind `json:"kind"`
Protocol string `json:"protocol"`
Port int `json:"port,omitempty"`
Path string `json:"path,omitempty"`
}
type ProviderOperation ¶ added in v0.4.3
type ProviderOperation string
const ( OperationDescribe ProviderOperation = "describe" OperationPreflight ProviderOperation = "preflight" OperationProvision ProviderOperation = "provision" OperationBind ProviderOperation = "bind" OperationVerify ProviderOperation = "verify" OperationStatus ProviderOperation = "status" OperationUpdate ProviderOperation = "update" OperationBackup ProviderOperation = "backup" OperationRestore ProviderOperation = "restore" OperationDestroy ProviderOperation = "destroy" )
type ProviderOperationObservation ¶ added in v0.4.7
type ProviderOperationObservation struct {
Phase Phase `json:"phase"`
Status Status `json:"status"`
Application string `json:"application"`
Capability Kind `json:"capability"`
Resource string `json:"resource"`
Provider ProviderKind `json:"provider"`
Duration time.Duration `json:"duration"`
}
ProviderOperationObservation is deliberately metadata-only. It gives observability adapters a stable hook without exposing workload bindings, credentials, endpoints or provider-specific configuration.
type ProviderOperationObserver ¶ added in v0.4.7
type ProviderOperationObserver interface {
ObserveProviderOperation(ProviderOperationObservation)
}
type ProviderOwnership ¶ added in v0.4.2
type ProviderOwnership string
const ( OwnershipBaseHarbor ProviderOwnership = "baseharbor" OwnershipExternal ProviderOwnership = "external" )
type ProviderPlacement ¶ added in v0.4.8
type ProviderPlacement struct {
Scope ProviderScope `json:"scope"`
SharingBoundary string `json:"sharing_boundary,omitempty"`
Ownership ProviderOwnership `json:"ownership"`
ExternalReference string `json:"external_reference,omitempty"`
}
ProviderPlacement describes deployment/operator intent for how a provider instance is placed. It is deliberately separate from portable application intent and from runtime-specific isolation/topology.
func (ProviderPlacement) Validate ¶ added in v0.4.8
func (p ProviderPlacement) Validate() error
type ProviderScope ¶ added in v0.4.2
type ProviderScope string
const ( ScopeApplication ProviderScope = "application" ScopeExternal ProviderScope = "external" )
type ReconciliationDriver ¶ added in v0.4.14
type ReconciliationResult ¶ added in v0.4.14
type ReconciliationResult struct {
Resource Resource `json:"resource"`
Result reconciliation.Result `json:"result"`
}
type Registry ¶ added in v0.4.2
type Registry struct {
Version int `json:"version"`
Instances []ProviderInstance `json:"instances,omitempty"`
Bindings []ProviderBinding `json:"bindings,omitempty"`
}
func NewRegistry ¶ added in v0.4.2
func NewRegistry() Registry
func (Registry) ApplicationLifecycle ¶ added in v0.4.2
func (r Registry) ApplicationLifecycle(application string, operation LifecycleOperation) ([]LifecycleAction, error)
func (*Registry) Register ¶ added in v0.4.2
func (r *Registry) Register(instance ProviderInstance) error
func (*Registry) ReleaseApplication ¶ added in v0.4.2
func (*Registry) ReleaseManagedApplication ¶ added in v0.4.2
func (Registry) Resolve ¶ added in v0.4.2
func (r Registry) Resolve(provider ProviderKind, scope ProviderScope, application, externalID string) (ProviderInstance, error)
func (Registry) ResolvePlacement ¶ added in v0.4.8
func (r Registry) ResolvePlacement(provider ProviderKind, placement ProviderPlacement, application string) (ProviderInstance, error)
type RegistryStore ¶ added in v0.4.2
type RegistryStore struct{ Path string }
func (RegistryStore) Load ¶ added in v0.4.2
func (s RegistryStore) Load() (Registry, error)
func (RegistryStore) Save ¶ added in v0.4.2
func (s RegistryStore) Save(registry Registry) error
type Request ¶
type Request struct {
Requirement Requirement
Workload string
HTTPExposure *HTTPExposureBinding
ObjectStorageS3 *ObjectStorageS3Binding
TelemetryOTLP *OTLPTelemetryBinding
Metrics *MetricsBinding
Logs *LogsBinding
Security *SecureBinding
Driver Driver
Observer ProviderOperationObserver
}
type Requirement ¶
Requirement is one application-owned logical capability request.
type Resource ¶
type Resource struct {
Application string `json:"application"`
Kind Kind `json:"kind"`
Name string `json:"name"`
Provider ProviderKind `json:"provider"`
}
Resource is the provider-backed representation of one stable logical application resource. Provider-specific object names, ports and credentials are intentionally absent.
type Result ¶
type Result struct {
Application string `json:"application"`
Status Status `json:"status"`
Plan Plan `json:"plan"`
Steps []StepResult `json:"steps"`
Reconciliation []ReconciliationResult `json:"reconciliation,omitempty"`
}
type SecretReference ¶ added in v0.4.5
type SecureBinding ¶ added in v0.4.5
type SecureBinding struct {
Identity *WorkloadIdentityBinding `json:"identity,omitempty"`
Credentials []CredentialReference `json:"credentials,omitempty"`
Trust []TrustMaterialReference `json:"trust,omitempty"`
Authorization []AuthorizationMetadata `json:"authorization,omitempty"`
Secrets []SecretReference `json:"secrets,omitempty"`
Lifecycle SecurityLifecycleSupport `json:"lifecycle"`
Diagnostics []Diagnostic `json:"diagnostics,omitempty"`
}
SecureBinding carries provider-neutral security metadata required to bind one logical capability resource to one workload. Secret material itself is never represented here; only stable references may cross this boundary.
func (SecureBinding) Validate ¶ added in v0.4.5
func (b SecureBinding) Validate() error
Validate rejects ambiguous or unsafe secure-binding metadata before provider mutation. It validates references and metadata shape, not referenced secret values, which are resolved only at the trusted provider/runtime boundary.
type SecurityLifecycleSupport ¶ added in v0.4.5
type SpecificationID ¶ added in v0.4.3
type SpecificationID string
type SpecificationVersion ¶ added in v0.4.3
type SpecificationVersion string
const SpecificationV1 SpecificationVersion = "v1"
type StepResult ¶
type StepResult struct {
Phase Phase `json:"phase"`
Status Status `json:"status"`
Resource Resource `json:"resource"`
Binding Binding `json:"binding"`
Diagnostics []Diagnostic `json:"diagnostics,omitempty"`
}