platformdeploy

package
v0.42.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 24, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Overview

Package platformdeploy contains the StackKit boundary for PaaS delivery. OpenTofu owns platform installation; StackKit-owned/default L3 applications are PaaS-intended, while customer-installed applications outside the manifest are state-unmanaged by StackKit.

Index

Constants

View Source 
const (
	// AppManagementManaged means StackKit observed a PaaS deployment identity.
	AppManagementManaged = "managed"
	// AppManagementHandoff means StackKit recorded customer app handoff metadata only.
	AppManagementHandoff = "handoff"
	// AppManagementUnmanaged means StackKit has manifest metadata but no PaaS identity.
	AppManagementUnmanaged = "unmanaged"
	// AppManagementFallback means StackKit deployed the app through the explicit
	// standalone Compose fallback instead of a PaaS adapter.
	AppManagementFallback = "fallback"

	// AppOwnershipStackKit means StackKit owns the app lifecycle and must
	// prefer delivery through the selected PaaS adapter when configured.
	AppOwnershipStackKit = "stackkit"
	// AppOwnershipCustomer means StackKit records handoff metadata only; the
	// selected PaaS/Admin product owns deployment and lifecycle.
	AppOwnershipCustomer = "customer"

	// SetupPolicyManual keeps first-run setup in the application UI.
	SetupPolicyManual = "manual"
	// SetupPolicyOnDemand allows StackKit to run setup drops only after an explicit request.
	SetupPolicyOnDemand = "on_demand"
	// SetupPolicyAutomatic allows StackKit to run setup drops during rollout.
	SetupPolicyAutomatic = "automatic"
)

Variables

This section is empty.

Functions

func GenerateKomodoStackResource 

func GenerateKomodoStackResource(manifest AppManifest) ([]byte, error)

GenerateKomodoStackResource creates the bounded PoC artifact for Komodo Resource Sync. It intentionally does not make Komodo the default adapter.

func IsDegraded 

func IsDegraded(err error) bool

func IsStackKitOwnedApp 

func IsStackKitOwnedApp(app AppManifest) bool

IsStackKitOwnedApp reports whether this L3 app belongs to the StackKit-owned product surface. If no PaaS adapter is configured, callers may record it as unmanaged state rather than deploying it.

func RequiresBootstrapEvidence 

func RequiresBootstrapEvidence(platform string) bool

func ValidateBootstrapEvidence 

func ValidateBootstrapEvidence(platform string, evidence BootstrapEvidence) error

Types

type Adapter 

type Adapter interface {
	ApplyCompose(ctx context.Context, manifest AppManifest) (DeploymentRef, error)
}

Adapter is implemented by concrete platform API clients.

type AppManifest 

type AppManifest struct {
	ServiceKey  string              `json:"serviceKey,omitempty"`
	Name        string              `json:"name"`
	Kind        string              `json:"kind,omitempty"`
	Ownership   string              `json:"ownership,omitempty"`
	Platform    string              `json:"platform"`
	ManagedBy   string              `json:"managedBy"`
	Image       string              `json:"image,omitempty"`
	Port        int                 `json:"port,omitempty"`
	Host        string              `json:"host,omitempty"`
	URL         string              `json:"url,omitempty"`
	RouteURL    string              `json:"routeUrl,omitempty"`
	Auth        string              `json:"auth,omitempty"`
	HealthPath  string              `json:"healthPath,omitempty"`
	ComposePath string              `json:"composePath"`
	ComposeYAML string              `json:"composeYAML,omitempty"`
	Env         map[string]string   `json:"env,omitempty"`
	Secrets     map[string]string   `json:"secrets,omitempty"`
	SetupPolicy string              `json:"setupPolicy,omitempty"`
	SetupDrops  []SetupDropManifest `json:"setupDrops,omitempty"`
}

AppManifest describes one generated compose bundle for PaaS delivery or customer-app handoff.

func (*AppManifest) UnmarshalJSON 

func (m *AppManifest) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts Terraform jsonencode output where object type coercion can stringify numeric ports inside mixed concat(...) app manifest lists.

type BootstrapCapability 

type BootstrapCapability string
const (
	BootstrapCapabilityProxyRouting   BootstrapCapability = "proxy-routing"
	BootstrapCapabilityAPIAccess      BootstrapCapability = "api-access"
	BootstrapCapabilityTeamManagement BootstrapCapability = "team-management"
	BootstrapCapabilityBackups        BootstrapCapability = "backups"
	BootstrapCapabilitySecrets        BootstrapCapability = "secrets"
	BootstrapCapabilityHealthchecks   BootstrapCapability = "healthchecks"
	BootstrapCapabilityServiceHandoff BootstrapCapability = "service-handoff"
)

type BootstrapCapabilityEvidence 

type BootstrapCapabilityEvidence struct {
	Capability BootstrapCapability `json:"capability"`
	Status     string              `json:"status"`
	Evidence   []string            `json:"evidence,omitempty"`
}

type BootstrapCapabilityProvider 

type BootstrapCapabilityProvider interface {
	BootstrapProviderName() string
	BootstrapCapabilities() []BootstrapCapability
}

BootstrapCapabilityProvider declares the platform-specific first-run areas the adapter must harden before it can be treated as beta-supported.

type BootstrapEvidence 

type BootstrapEvidence struct {
	Provider     string                        `json:"provider,omitempty"`
	Mode         string                        `json:"mode,omitempty"`
	Capabilities []BootstrapCapabilityEvidence `json:"capabilities,omitempty"`
}

BootstrapEvidence is written by generated platform bootstraps to make the selected PaaS setup auditable by release gates and scenario evidence.

type BootstrapManifest 

type BootstrapManifest struct {
	Mode          string                `json:"mode,omitempty"`
	DemoData      DemoDataManifest      `json:"demoData,omitempty"`
	SetupPolicies SetupPoliciesManifest `json:"setupPolicies,omitempty"`
}

BootstrapManifest records the generated first-run setup contract for the selected platform and StackKit-owned default apps.

type BundleManifest 

type BundleManifest struct {
	Version    string              `json:"version"`
	Platform   string              `json:"platform"`
	Fallback   FallbackManifest    `json:"fallback,omitempty"`
	Bootstrap  BootstrapManifest   `json:"bootstrap,omitempty"`
	SystemApps []SystemAppManifest `json:"systemApps,omitempty"`
	Apps       []AppManifest       `json:"apps"`
}

BundleManifest is the generated handoff from StackKit generation to the selected PaaS.

func LoadBundleManifest 

func LoadBundleManifest(path string) (BundleManifest, error)

func StandaloneFallbackBundle 

func StandaloneFallbackBundle(bundle BundleManifest, failures []ComponentFailure) BundleManifest

StandaloneFallbackBundle selects only components that have no committed platform identity. It is safe to execute after a preferred adapter failed.

type BundleResult 

type BundleResult struct {
	Refs     []DeploymentRef    `json:"refs,omitempty" yaml:"refs,omitempty"`
	Failures []ComponentFailure `json:"failures,omitempty" yaml:"failures,omitempty"`
}

BundleResult preserves every successful deployment reference alongside application-scoped failures. Callers can finish the independent graph, persist a degraded state, and retry only components that still need work.

func ApplyBundleResilient 

func ApplyBundleResilient(ctx context.Context, adapter Adapter, bundle BundleManifest) (BundleResult, error)

ApplyBundleResilient executes every independent StackKit-owned application and preserves partial success. Adapter/application failures become component results; cancellation remains a fatal orchestration boundary.

func (BundleResult) Degraded 

func (r BundleResult) Degraded() bool

type ComponentFailure 

type ComponentFailure struct {
	AppName           string `json:"appName" yaml:"appName"`
	Platform          string `json:"platform" yaml:"platform"`
	Stage             string `json:"stage" yaml:"stage"`
	Message           string `json:"message" yaml:"message"`
	IdentityCommitted bool   `json:"identityCommitted" yaml:"identityCommitted"`
	Retryable         bool   `json:"retryable" yaml:"retryable"`
}

ComponentFailure records one application-scoped rollout failure. A failure with IdentityCommitted=false may be retried through another registered adapter without risking two platform-owned deployment identities.

type CoolifyAdapter 

type CoolifyAdapter struct {
	// contains filtered or unexported fields
}

CoolifyAdapter deploys generated compose bundles through Coolify's API. Coolify authenticates with bearer tokens.

func NewCoolifyAdapter 

func NewCoolifyAdapter(cfg HTTPConfig) *CoolifyAdapter

func (*CoolifyAdapter) ApplyCompose 

func (a *CoolifyAdapter) ApplyCompose(ctx context.Context, manifest AppManifest) (DeploymentRef, error)

func (*CoolifyAdapter) BootstrapCapabilities 

func (a *CoolifyAdapter) BootstrapCapabilities() []BootstrapCapability

func (*CoolifyAdapter) BootstrapProviderName 

func (a *CoolifyAdapter) BootstrapProviderName() string

func (*CoolifyAdapter) Delete 

func (a *CoolifyAdapter) Delete(ctx context.Context, ref DeploymentRef) error

func (*CoolifyAdapter) Deploy 

func (a *CoolifyAdapter) Deploy(ctx context.Context, ref DeploymentRef) (string, error)

func (*CoolifyAdapter) ObserveDeployment 

func (a *CoolifyAdapter) ObserveDeployment(ctx context.Context, ref DeploymentRef) (DeploymentRef, error)

func (*CoolifyAdapter) ObserveDeployments 

func (a *CoolifyAdapter) ObserveDeployments(ctx context.Context, refs []DeploymentRef) ([]DeploymentRef, error)

func (*CoolifyAdapter) Status 

func (a *CoolifyAdapter) Status(ctx context.Context, ref DeploymentRef) error

func (*CoolifyAdapter) UpsertCompose 

func (a *CoolifyAdapter) UpsertCompose(ctx context.Context, manifest AppManifest) (DeploymentRef, error)

func (*CoolifyAdapter) WaitReady 

func (a *CoolifyAdapter) WaitReady(ctx context.Context) error

type DefaultSSHRunner 

type DefaultSSHRunner struct{}

func (DefaultSSHRunner) Run 

func (DefaultSSHRunner) Run(ctx context.Context, target SSHBootstrap, script string) ([]byte, error)

type DegradedError 

type DegradedError struct {
	Failures []ComponentFailure
}

DegradedError is a terminal, usable rollout result rather than a lost deployment. It deliberately carries component failures without discarding successful references.

func (*DegradedError) Error 

func (e *DegradedError) Error() string

type DemoDataManifest 

type DemoDataManifest struct {
	Enabled bool `json:"enabled,omitempty"`
}

type DeploymentBatchObserver 

type DeploymentBatchObserver interface {
	ObserveDeployments(ctx context.Context, refs []DeploymentRef) ([]DeploymentRef, error)
}

DeploymentBatchObserver is implemented by adapters that can observe several started deployments under one shared time budget.

type DeploymentObserver 

type DeploymentObserver interface {
	ObserveDeployment(ctx context.Context, ref DeploymentRef) (DeploymentRef, error)
}

DeploymentObserver is implemented by adapters that can verify platform-side start state after the deploy API accepted a compose bundle.

type DeploymentRef 

type DeploymentRef struct {
	Platform       string    `json:"platform" yaml:"platform"`
	AppName        string    `json:"appName" yaml:"appName"`
	ExternalID     string    `json:"externalId" yaml:"externalId"`
	DeploymentID   string    `json:"deploymentId,omitempty" yaml:"deploymentId,omitempty"`
	ObservedStatus string    `json:"observedStatus,omitempty" yaml:"observedStatus,omitempty"`
	ObservedAt     time.Time `json:"observedAt,omitempty" yaml:"observedAt,omitempty"`
	LastDeployed   time.Time `json:"lastDeployed,omitempty" yaml:"lastDeployed,omitempty"`
	ServiceNames   []string  `json:"-" yaml:"-"`
	ComposeYAML    string    `json:"-" yaml:"-"`
	ComposePath    string    `json:"-" yaml:"-"`
}

DeploymentRef records the external platform identity for a StackKit app.

func ApplyBundle 

func ApplyBundle(ctx context.Context, adapter Adapter, bundle BundleManifest) ([]DeploymentRef, error)

ApplyBundle applies StackKit-owned systemApps and StackKit-owned/default L3 apps through the supplied PaaS adapter. Customer-owned apps in Apps are handoff metadata and are intentionally not deployed by StackKit.

type DokployAdapter 

type DokployAdapter struct {
	// contains filtered or unexported fields
}

DokployAdapter deploys generated compose bundles through Dokploy's Compose API. Dokploy authenticates with the x-api-key header.

func NewDokployAdapter 

func NewDokployAdapter(cfg HTTPConfig) *DokployAdapter

func (*DokployAdapter) ApplyCompose 

func (a *DokployAdapter) ApplyCompose(ctx context.Context, manifest AppManifest) (DeploymentRef, error)

func (*DokployAdapter) BootstrapCapabilities 

func (a *DokployAdapter) BootstrapCapabilities() []BootstrapCapability

func (*DokployAdapter) BootstrapProviderName 

func (a *DokployAdapter) BootstrapProviderName() string

func (*DokployAdapter) Delete 

func (a *DokployAdapter) Delete(ctx context.Context, ref DeploymentRef, deleteVolumes bool) error

func (*DokployAdapter) Deploy 

func (a *DokployAdapter) Deploy(ctx context.Context, ref DeploymentRef) error

func (*DokployAdapter) Status 

func (a *DokployAdapter) Status(ctx context.Context, ref DeploymentRef) error

func (*DokployAdapter) UpsertCompose 

func (a *DokployAdapter) UpsertCompose(ctx context.Context, manifest AppManifest) (DeploymentRef, error)

type FallbackManifest 

type FallbackManifest struct {
	Enabled bool   `json:"enabled,omitempty"`
	Mode    string `json:"mode,omitempty"`
}

FallbackManifest records whether the generated bundle is intentionally targeting the standalone Compose fallback instead of a PaaS API.

type HTTPConfig 

type HTTPConfig struct {
	BaseURL string
	Token   string
	APIKey  string
	Secret  string
	Client  *http.Client

	// Optional platform-specific placement values. Dokploy needs EnvironmentID
	// to create compose apps; Coolify usually needs project/server/environment or
	// destination identifiers. Komodo uses ServerID to attach compose stacks.
	EnvironmentID               string
	ServerID                    string
	ProjectUUID                 string
	EnvironmentUUID             string
	DestinationUUID             string
	LegacyDockerComposeAPI      bool
	DisableDockerRuntimeObserve bool
	DockerEnv                   []string
	WaitForReadiness            bool
}

HTTPConfig configures HTTP-backed platform adapters.

func LoadOwnerKomodoConfig 

func LoadOwnerKomodoConfig(workspace string) (HTTPConfig, error)

LoadOwnerKomodoConfig reads the exact owner-custodied platform configuration through a held workspace root. It is intended for mutation boundaries that must not fall back to environment or generated configuration.

type KomodoAdapter 

type KomodoAdapter struct {
	// contains filtered or unexported fields
}

KomodoAdapter deploys generated compose bundles through Komodo's Stack API. Komodo authenticates with x-api-key and x-api-secret headers.

func NewKomodoAdapter 

func NewKomodoAdapter(cfg HTTPConfig) *KomodoAdapter

func (*KomodoAdapter) ApplyCompose 

func (a *KomodoAdapter) ApplyCompose(ctx context.Context, manifest AppManifest) (DeploymentRef, error)

func (*KomodoAdapter) BootstrapCapabilities 

func (a *KomodoAdapter) BootstrapCapabilities() []BootstrapCapability

func (*KomodoAdapter) BootstrapProviderName 

func (a *KomodoAdapter) BootstrapProviderName() string

func (*KomodoAdapter) ControlStack 

func (a *KomodoAdapter) ControlStack(ctx context.Context, ref DeploymentRef, action string, services []string) (KomodoStackControlResult, error)

ControlStack dispatches one bounded service action through Komodo's Stack authority and waits for the returned update to complete.

func (*KomodoAdapter) Deploy 

func (a *KomodoAdapter) Deploy(ctx context.Context, ref DeploymentRef) (string, error)

func (*KomodoAdapter) ObserveDeployment 

func (a *KomodoAdapter) ObserveDeployment(ctx context.Context, ref DeploymentRef) (DeploymentRef, error)

func (*KomodoAdapter) ReadStackLogs 

func (a *KomodoAdapter) ReadStackLogs(ctx context.Context, ref DeploymentRef, services []string, tail int) ([]byte, error)

ReadStackLogs retrieves one bounded, non-following log tail. Redaction and durable evidence remain the caller's owner-bound responsibility.

func (*KomodoAdapter) Status 

func (a *KomodoAdapter) Status(ctx context.Context, ref DeploymentRef) error

func (*KomodoAdapter) UpsertStack 

func (a *KomodoAdapter) UpsertStack(ctx context.Context, manifest AppManifest) (DeploymentRef, error)

type KomodoStackControlResult 

type KomodoStackControlResult struct {
	UpdateID      string
	ObservedState string
}

type LocalComposeAdapter 

type LocalComposeAdapter struct {
	// contains filtered or unexported fields
}

LocalComposeAdapter deploys generated compose bundles directly on the node.

func NewLocalComposeAdapter 

func NewLocalComposeAdapter(workDir string, opts ...LocalComposeOption) *LocalComposeAdapter

NewLocalComposeAdapter returns an adapter for local, no-PaaS compose rollout.

func (*LocalComposeAdapter) ApplyCompose 

func (a *LocalComposeAdapter) ApplyCompose(ctx context.Context, manifest AppManifest) (DeploymentRef, error)

ApplyCompose runs docker compose up for one generated compose bundle.

func (*LocalComposeAdapter) ObserveDeployment 

func (a *LocalComposeAdapter) ObserveDeployment(ctx context.Context, ref DeploymentRef) (DeploymentRef, error)

ObserveDeployment verifies the generated Compose project instead of treating a successful `up -d` process exit as runtime evidence.

type LocalComposeOption 

type LocalComposeOption func(*LocalComposeAdapter)

LocalComposeOption configures the local Docker Compose adapter.

func WithLocalComposeEnv 

func WithLocalComposeEnv(env []string) LocalComposeOption

WithLocalComposeEnv binds Compose to the same target transport used by the resolved runtime (for example a remote DOCKER_HOST from an enrolled agent).

func WithLocalComposeRunner 

func WithLocalComposeRunner(runner localComposeRunner) LocalComposeOption

WithLocalComposeRunner injects the command runner used by tests.

type NodeBootstrap 

type NodeBootstrap struct {
	KomodoCoreAddress   string
	KomodoOnboardingKey string
	SSH                 *SSHBootstrap
}

type NodePlatformTarget 

type NodePlatformTarget struct {
	ServerID        string
	DestinationUUID string
	EnvironmentID   string
	ProjectUUID     string
	EnvironmentUUID string
}

type NodePrepareResult 

type NodePrepareResult struct {
	NodeName        string
	Role            string
	Platform        string
	Status          string
	Detail          string
	Services        []string
	ServerID        string
	DestinationUUID string
	EnvironmentID   string
	ProjectUUID     string
	EnvironmentUUID string
	PrivateKeyUUID  string
}

func PrepareSupplementalNodeTargets 

func PrepareSupplementalNodeTargets(ctx context.Context, platform string, nodes []SupplementalNodeTarget, cfg HTTPConfig, runner SSHRunner) ([]NodePrepareResult, error)

type ReadinessChecker 

type ReadinessChecker interface {
	WaitReady(ctx context.Context) error
}

ReadinessChecker is implemented by adapters whose API can be installed but not yet ready immediately after platform bootstrap.

type SSHBootstrap 

type SSHBootstrap struct {
	Host             string
	User             string
	Port             int
	KeyPath          string
	KeyPEM           string
	PrivateKey       string
	ClientPrivateKey string
	ProxyJump        string
}

type SSHRunner 

type SSHRunner interface {
	Run(ctx context.Context, target SSHBootstrap, script string) ([]byte, error)
}

type SetupDropManifest 

type SetupDropManifest struct {
	Name          string            `json:"name"`
	Version       string            `json:"version,omitempty"`
	Runner        string            `json:"runner,omitempty"`
	Description   string            `json:"description,omitempty"`
	RollbackNotes []string          `json:"rollbackNotes,omitempty"`
	Command       []string          `json:"command,omitempty"`
	Env           map[string]string `json:"env,omitempty"`
	Secrets       map[string]string `json:"secrets,omitempty"`
}

SetupDropManifest describes an initial-configuration unit that can be run separately from the application deployment.

type SetupPoliciesManifest 

type SetupPoliciesManifest struct {
	Platform           string `json:"platform,omitempty"`
	ApplicationDefault string `json:"applicationDefault,omitempty"`
}

type SupplementalNodeTarget 

type SupplementalNodeTarget struct {
	Name      string
	Role      string
	IP        string
	Host      string
	Services  []string
	Platform  NodePlatformTarget
	Bootstrap *NodeBootstrap
}

SupplementalNodeTarget describes an additional node that should be attached to the selected platform before StackKit-owned apps are deployed.

type SystemAppManifest 

type SystemAppManifest struct {
	AppManifest
	Role string `json:"role,omitempty"`
}

SystemAppManifest describes a StackKit-owned control-plane application that StackKit may deploy through the selected platform adapter.

func (*SystemAppManifest) UnmarshalJSON 

func (m *SystemAppManifest) UnmarshalJSON(data []byte) error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.