deployconfig

package
v0.7.0 Latest Latest
Warning

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

Go to latest
Published: Aug 26, 2026 License: MIT Imports: 43 Imported by: 0

Documentation

Overview

Package deployconfig compiles the sole operator-edited SecondBox deployment manifest into explicit process environment artifacts.

Index

Constants

View Source
const DefaultComposeProjectName = "secondbox"

DefaultComposeProjectName is the Compose project a manifest that states no deployment.compose_project_name deploys under.

Variables

This section is empty.

Functions

func ApplyStandardResources

func ApplyStandardResources(ctx context.Context, resolved ResolvedDeployment, httpClient *http.Client) (resourceapply.Report, error)

ApplyStandardResources uses the same engine as the CLI after Compose has reported the control plane ready.

func ComposeDiagnosticArguments added in v0.4.0

func ComposeDiagnosticArguments(manifestPath string, command ...string) ([]string, error)

ComposeDiagnosticArguments returns the exact existing deployment transport for bounded read-only Docker Compose inspection without rerendering it.

func ComposeDiagnosticArgumentsForAcceptedInstaller added in v0.4.4

func ComposeDiagnosticArgumentsForAcceptedInstaller(manifestPath string, command ...string) ([]string, error)

func ComposeDiagnosticArgumentsForRecordedInstaller added in v0.6.0

func ComposeDiagnosticArgumentsForRecordedInstaller(manifestPath, expectedSubject string, command ...string) ([]string, error)

ComposeDiagnosticArgumentsForRecordedInstaller resolves only the immutable Compose transport identity recorded in an accepted installer manifest. The caller must already have verified the manifest against the accepted operation and its public source release. In particular, this path does not regenerate historical standard Profile lineage with the running target binary's policy.

func EncodeComposeEnvironment

func EncodeComposeEnvironment(environment map[string]string) ([]byte, error)

func EncodeSystemdEnvironment

func EncodeSystemdEnvironment(environment map[string]string) ([]byte, error)

func InitDevelopment

func InitDevelopment(directory string) (string, error)

InitDevelopment creates one complete reviewed loopback deployment. It never replaces an existing path or artifact.

func InitProduction

func InitProduction(directory string) (string, error)

InitProduction writes an annotated, intentionally incomplete shape and reports all unresolved decision groups in one error.

func InitProductionFromManifest

func InitProductionFromManifest(sourcePath, directory string) (string, error)

InitProductionFromManifest is the non-interactive automation path. It validates a complete production input and materializes a create-only manifest whose local source references are absolute, so moving it into the protected deployment directory cannot change their meaning.

func InitProductionFromRelease

func InitProductionFromRelease(sourcePath, directory string, release releasecontract.ArtifactManifest, releaseBytes []byte) (string, error)

InitProductionFromRelease binds immutable software facts from a verified release while preserving every operator-owned authority and placement input.

func Inspect

func Inspect(manifestPath string) ([]byte, error)

func PublishSingleHostUpdate added in v0.6.0

func PublishSingleHostUpdate(plan install.InstallPlan, staged StagedSingleHostUpdate) error

func PurgeComposeVolumes added in v0.4.0

func PurgeComposeVolumes(ctx context.Context, manifestPath string, executor ComposeExecutor) error

PurgeComposeVolumes removes the exact validated deployment's containers, networks, and named volumes. It is intentionally separate from ordinary Compose down because uninstall preserves the bundled database and object while the typed permanent-purge workflow must remove it.

func PurgeComposeVolumesForAcceptedInstaller added in v0.4.4

func PurgeComposeVolumesForAcceptedInstaller(ctx context.Context, manifestPath string, executor ComposeExecutor) error

func RecordedInstallerComposeSubject added in v0.6.0

func RecordedInstallerComposeSubject(manifestPath, environmentPath string) (string, error)

RecordedInstallerComposeSubject binds the generated environment and selected Compose files without regenerating them with the running binary. A non-empty environmentPath is used to authenticate a canonical source-binary render.

func RunCompose added in v0.4.0

func RunCompose(ctx context.Context, manifestPath, action string, executor ComposeExecutor, httpClient *http.Client) error

RunCompose renders the validated deployment and delegates one exact Compose action through a narrow executor. Resource application remains the existing idempotent engine and runs only after Compose startup succeeds.

func RunComposeForAcceptedInstaller added in v0.4.4

func RunComposeForAcceptedInstaller(ctx context.Context, manifestPath, action string, executor ComposeExecutor, httpClient *http.Client) error

RunComposeForAcceptedInstaller uses the accepted installer's independently revalidated root-host evidence while retaining all ordinary manifest checks.

func RunExistingComposeForAcceptedInstaller added in v0.6.0

func RunExistingComposeForAcceptedInstaller(ctx context.Context, manifestPath, action, expectedSubject string, executor ComposeExecutor) error

RunExistingComposeForAcceptedInstaller fences, shuts down, or restores the source deployment through its already-materialized environment and Compose assets. It deliberately does not render target-binary embedded assets.

func RunnerInit

func RunnerInit(manifestPath, runnerID, target string) error

func RunnerInitOrValidate added in v0.4.0

func RunnerInitOrValidate(manifestPath, runnerID, target string) error

RunnerInitOrValidate closes the receipt-persistence crash window for the guided installer. A missing target is created once; an existing target is accepted only when every file still proves the exact declared Runner identity, CA, private key, and rendered environment.

func RunnerTemplate added in v0.2.0

func RunnerTemplate() []byte

RunnerTemplate returns the inert, complete Runner declaration scaffold.

func SecretFingerprint

func SecretFingerprint(value string) string

SecretFingerprint returns redacted identity evidence for inspect output.

func ValidatePublishedSingleHostUpdate added in v0.6.0

func ValidatePublishedSingleHostUpdate(plan install.InstallPlan, update install.UpdateRecord, verified releaseverify.VerifiedRelease, artifact install.VerifiedArtifact) (map[string]string, error)

ValidatePublishedSingleHostUpdate proves that every release-derived active file still matches the verified target before the installer journals its final content identities. It returns those expected identities without deriving trust from the active files themselves.

func ValidateSingleHostUpdateSource added in v0.6.0

func ValidateSingleHostUpdateSource(plan install.InstallPlan, release releasecontract.ArtifactManifest, releaseBytes []byte, artifact install.VerifiedArtifact) error

func WriteRunnerTemplate added in v0.2.0

func WriteRunnerTemplate(path string) error

WriteRunnerTemplate creates one Runner declaration scaffold without replacing an existing file.

Types

type Applications

type Applications struct {
	PlatformTokenFile string `toml:"platform_token_file"`
}

type ComposeExecutor added in v0.4.0

type ComposeExecutor interface {
	Run(context.Context, []string) error
}

type Database

type Database struct {
	Mode          string `toml:"mode"`
	URLFile       string `toml:"url_file"`
	BindIP        string `toml:"bind_ip"`
	PublishedPort *int64 `toml:"published_port"`
	Name          string `toml:"name"`
	User          string `toml:"user"`
	PasswordFile  string `toml:"password_file"`
}

type Deployment

type Deployment struct {
	Mode                   string `toml:"mode"`
	ComposeProjectName     string `toml:"compose_project_name"`
	ComposeBackendCIDR     string `toml:"compose_backend_cidr,omitempty"`
	PublicBaseURL          string `toml:"public_base_url"`
	TLSTermination         string `toml:"tls_termination"`
	ControlPlaneImage      string `toml:"control_plane_image"`
	RunnerImage            string `toml:"runner_image"`
	PostgresImage          string `toml:"postgres_image"`
	APIBindIP              string `toml:"api_bind_ip"`
	APIPublishedPort       *int64 `toml:"api_published_port"`
	ListenAddress          string `toml:"listen_address"`
	RunnerBindIP           string `toml:"runner_bind_ip"`
	RunnerPublishedPort    *int64 `toml:"runner_published_port"`
	RunnerListenAddress    string `toml:"runner_listen_address"`
	LogPath                string `toml:"log_path"`
	AssetCatalog           string `toml:"signed_asset_catalog"`
	AssetCatalogPath       string `toml:"signed_asset_catalog_path"`
	DevelopmentWaitSeconds *int64 `toml:"development_prepare_wait_timeout_seconds"`
}

type InspectedOverride

type InspectedOverride struct {
	Name        string `json:"name"`
	Environment string `json:"environment"`
	Default     string `json:"codeDefault"`
	Selected    bool   `json:"selected"`
	Value       string `json:"value,omitempty"`
	Help        string `json:"help"`
}

type InspectedPolicy

type InspectedPolicy struct {
	Name        string `json:"name"`
	Environment string `json:"environment"`
	Value       string `json:"value"`
	Help        string `json:"help"`
}

type InspectedStandardProfile

type InspectedStandardProfile struct {
	Name       string `json:"name"`
	Revision   int64  `json:"revision"`
	SpecDigest string `json:"specDigest"`
}

type Inspection

type Inspection struct {
	SchemaVersion          int                        `json:"schemaVersion"`
	Mode                   string                     `json:"mode"`
	DevelopmentWaitSeconds int64                      `json:"developmentWaitSeconds,omitempty"`
	ComposeFiles           []string                   `json:"composeFiles"`
	Environment            map[string]string          `json:"environment"`
	Policy                 []InspectedPolicy          `json:"policy"`
	Overrides              []InspectedOverride        `json:"overrides"`
	RemoteRunners          []string                   `json:"remoteRunners"`
	StandardBundles        []string                   `json:"standardBundles"`
	StandardProfiles       []InspectedStandardProfile `json:"standardProfiles"`
}

type ManifestV1

type ManifestV1 struct {
	SchemaVersion     int               `toml:"schema_version"`
	Deployment        Deployment        `toml:"deployment"`
	Database          Database          `toml:"database"`
	RunnerTrust       RunnerTrust       `toml:"runner_trust"`
	Runners           []Runner          `toml:"runners"`
	Applications      Applications      `toml:"applications"`
	Policy            Policy            `toml:"policy"`
	StandardResources StandardResources `toml:"standard_resources"`
	Overrides         TuningOverrides   `toml:"overrides"`
}

ManifestV1 is the strict schema_version=1 deployment source.

func ReadManifest

func ReadManifest(path string) (ManifestV1, error)

type OverrideDefinition

type OverrideDefinition struct {
	TOMLName    string
	Environment string
	Default     string
	Help        string
	AllowZero   bool
	// contains filtered or unexported fields
}

func OverrideRegistry

func OverrideRegistry() []OverrideDefinition

OverrideRegistry is the single discoverability and mapping registry for all optional control-plane tuning values.

type Policy

type Policy struct {
	DataPlaneRetentionSeconds             *int64 `toml:"data_plane_retention_seconds"`
	DataPlanePollIntervalMilliseconds     *int64 `toml:"data_plane_poll_interval_milliseconds"`
	RunnerCommandPollIntervalMilliseconds *int64 `toml:"runner_command_poll_interval_milliseconds"`
	RunnerEnabledFeatures                 string `toml:"runner_enabled_features"`
	DefaultSubjectMaxSandboxes            *int64 `toml:"default_subject_max_sandboxes"`
	DefaultSubjectMaxActiveInstances      *int64 `toml:"default_subject_max_active_instances"`
	DefaultSubjectMaxVCPUCount            *int64 `toml:"default_subject_max_vcpu_count"`
	DefaultSubjectMaxMemoryBytes          *int64 `toml:"default_subject_max_memory_bytes"`
	DefaultSubjectMaxSnapshots            *int64 `toml:"default_subject_max_snapshots"`
	DefaultSubjectMaxPortSessions         *int64 `toml:"default_subject_max_port_sessions"`
	DefaultSubjectMaxConcurrentOperations *int64 `toml:"default_subject_max_concurrent_operations"`
}

type ResolvedDeployment

type ResolvedDeployment struct {
	Manifest                ManifestV1
	Environment             map[string]string
	RemoteRunnerEnvironment map[string]map[string]string
	ComposeFiles            []string
	SecretPaths             map[string]string
	ResourceDocument        resourceapply.Document
}

ResolvedDeployment is the typed, validated result. Environment is the Compose transport; RemoteRunnerEnvironment contains isolated systemd maps.

func Render

func Render(manifestPath, environmentPath string) (ResolvedDeployment, error)

Render resolves the manifest and atomically replaces generated environment artifacts. The manifest and its referenced secret files remain authoritative.

func Resolve

func Resolve(path string) (ResolvedDeployment, error)

Resolve validates and resolves a manifest without consulting ambient process environment. Relative source references are anchored to the manifest.

func ResolveForAcceptedInstaller added in v0.4.4

func ResolveForAcceptedInstaller(path string) (ResolvedDeployment, error)

ResolveForAcceptedInstaller resolves an installer-owned manifest after the private host-apply helper has revalidated the accepted plan and its recorded root-owned paths. It retains every manifest, secret, trust, and environment check while avoiding a second unprivileged traversal of those root-only paths.

func (ResolvedDeployment) ComposeProject added in v0.3.1

func (r ResolvedDeployment) ComposeProject() string

ComposeProject is the Compose project this deployment owns. Compose derives every container, volume, and network name from it, so two deployments that share one Docker daemon must not share it: the second would bind the first's volumes and recreate its containers rather than fail.

type Runner

type Runner struct {
	RunnerID                      string `toml:"runner_id"`
	Placement                     string `toml:"placement"`
	PoolID                        string `toml:"pool_id"`
	SoftwareVersion               string `toml:"software_version"`
	ControlPlaneAddress           string `toml:"control_plane_address"`
	ControlPlaneServerName        string `toml:"control_plane_server_name"`
	IdentityDirectory             string `toml:"identity_directory"`
	IdentityHostDirectory         string `toml:"identity_host_directory"`
	ArtifactHostDirectory         string `toml:"artifact_host_directory"`
	StateHostDirectory            string `toml:"state_host_directory"`
	WorkspaceHostDirectory        string `toml:"workspace_host_directory"`
	LogPath                       string `toml:"log_path"`
	LogDirectory                  string `toml:"log_directory"`
	FirecrackerPath               string `toml:"firecracker_path"`
	FirecrackerJailerPath         string `toml:"firecracker_jailer_path"`
	FirecrackerJailRoot           string `toml:"firecracker_jail_root"`
	FirecrackerJailerUIDStart     *int64 `toml:"firecracker_jailer_uid_start"`
	FirecrackerJailerUIDCount     *int64 `toml:"firecracker_jailer_uid_count"`
	FirecrackerJailerUIDAllowLow  *bool  `toml:"firecracker_jailer_uid_allow_below_1000"`
	FirecrackerJailerGID          *int64 `toml:"firecracker_jailer_gid"`
	FirecrackerCgroupVersion      *int64 `toml:"firecracker_cgroup_version"`
	FirecrackerCgroupParent       string `toml:"firecracker_cgroup_parent"`
	FirecrackerKernelPath         string `toml:"firecracker_kernel_path"`
	FirecrackerRootFSPath         string `toml:"firecracker_rootfs_path"`
	FirecrackerSharedImagePath    string `toml:"firecracker_shared_image_path"`
	FirecrackerKernelArgs         string `toml:"firecracker_kernel_args"`
	FirecrackerCPUTemplate        string `toml:"firecracker_cpu_template"`
	FirecrackerRunDirectory       string `toml:"firecracker_run_directory"`
	FirecrackerLogDirectory       string `toml:"firecracker_log_directory"`
	FirecrackerAllowUnjailed      *bool  `toml:"firecracker_allow_unjailed"`
	SnapshotTemplateCacheRoot     string `toml:"snapshot_template_cache_root"`
	ArtifactPublicKey             string `toml:"artifact_public_key"`
	ArtifactPublicKeySHA256       string `toml:"artifact_public_key_sha256"`
	WorkspaceRoot                 string `toml:"workspace_root"`
	StorageRecoveryPercent        *int64 `toml:"storage_pressure_recovery_percent"`
	StorageWarningPercent         *int64 `toml:"storage_pressure_warning_percent"`
	StorageAdmissionDenyPercent   *int64 `toml:"storage_pressure_admission_deny_percent"`
	SandboxMaxVCPUs               *int64 `toml:"sandbox_max_vcpus"`
	SandboxMaxMemoryMiB           *int64 `toml:"sandbox_max_memory_mib"`
	SandboxMaxDiskMiB             *int64 `toml:"sandbox_max_disk_mib"`
	SandboxMemoryBudgetMiB        *int64 `toml:"sandbox_memory_budget_mib"`
	SandboxGuestIP                string `toml:"sandbox_guest_ip"`
	SandboxBridgeName             string `toml:"sandbox_bridge_name"`
	SandboxBridgeCIDR             string `toml:"sandbox_bridge_cidr"`
	SandboxGuestCIDR              string `toml:"sandbox_guest_cidr"`
	SandboxTapPrefix              string `toml:"sandbox_tap_prefix"`
	SandboxNetworkStateDir        string `toml:"sandbox_network_state_directory"`
	SandboxDeleteBridge           *bool  `toml:"sandbox_delete_bridge"`
	NetworkPolicyNFTPath          string `toml:"network_policy_nft_path"`
	NetworkPolicyMaxDNSPins       *int64 `toml:"network_policy_max_dns_pins"`
	NetworkPolicyMaxDNSTTL        string `toml:"network_policy_max_dns_ttl"`
	NetworkPolicyRunnerAddresses  string `toml:"network_policy_runner_addresses"`
	NetworkPolicyManagementCIDRs  string `toml:"network_policy_management_cidrs"`
	NetworkPolicyRunnerGateways   string `toml:"network_policy_runner_gateways"`
	NetworkPolicyDNSUpstream      string `toml:"network_policy_dns_upstream"`
	MaxConcurrentPerSandbox       *int64 `toml:"max_concurrent_per_sandbox"`
	MaxConcurrentGlobal           *int64 `toml:"max_concurrent_global"`
	MaxConcurrentStarts           *int64 `toml:"max_concurrent_starts"`
	MaxConcurrentWorkspaceCreates *int64 `toml:"max_concurrent_workspace_creates"`
	MaxConcurrentOperationsGlobal *int64 `toml:"max_concurrent_operations_global"`
	FileTransferMaxBytes          *int64 `toml:"file_transfer_max_bytes"`
	GuestControlVSockPort         *int64 `toml:"guest_control_vsock_port"`
	GuestProtocolVSockPort        *int64 `toml:"guest_protocol_vsock_port"`
	GuestHeartbeatInterval        string `toml:"guest_heartbeat_interval"`
	DataPlaneListenAddress        string `toml:"data_plane_listen_address"`
	DataPlaneAdvertisedAddress    string `toml:"data_plane_advertised_address"`
}

Runner is one immutable runner_id and its typed, placement-local runtime contract. Host paths remain opaque strings for remote placement.

type RunnerTrust

type RunnerTrust struct {
	EnrollmentCredentialFile string `toml:"enrollment_credential_file"`
	CACertificateFile        string `toml:"ca_certificate_file"`
	CAPrivateKeyFile         string `toml:"ca_private_key_file"`
	ServerCertificateFile    string `toml:"server_certificate_file"`
	ServerPrivateKeyFile     string `toml:"server_private_key_file"`
	ServerName               string `toml:"server_name"`
	CertificateLifetimeDays  *int64 `toml:"certificate_lifetime_days"`
}

type SingleHostInstallResult added in v0.4.0

type SingleHostInstallResult struct {
	ManifestPath            string
	RunnerID                string
	RunnerIdentityDirectory string
	PlatformTokenPath       string
}

SingleHostInstallResult identifies the create-only deployment material that must be used by the later Runner enrollment and Compose stages.

func InitSingleHostFromRelease added in v0.4.0

func InitSingleHostFromRelease(plan install.InstallPlan, release releasecontract.ArtifactManifest, releaseBytes []byte, verified install.VerifiedArtifact) (SingleHostInstallResult, error)

InitSingleHostFromRelease materializes one explicit loopback-only development deployment from an accepted installer plan and an independently verified public release. The operation directory must already exist, while every file and child directory owned by this stage must not exist.

func InitSingleHostFromReleaseOrValidate added in v0.4.0

func InitSingleHostFromReleaseOrValidate(plan install.InstallPlan, release releasecontract.ArtifactManifest, releaseBytes []byte, verified install.VerifiedArtifact) (SingleHostInstallResult, error)

InitSingleHostFromReleaseOrValidate makes the stage commit marker (the create-only manifest) resumable. A completed but not-yet-recorded materialization is adopted only when its deterministic manifest, release, signed-asset catalog, and resolved deployment all match the accepted plan.

type StagedSingleHostUpdate added in v0.6.0

type StagedSingleHostUpdate struct {
	ManifestPath            string
	SignedAssetCatalog      string
	ReleaseArtifactManifest string
}

func StageSingleHostUpdate added in v0.6.0

type StandardResources

type StandardResources struct {
	ArtifactManifest string               `toml:"artifact_manifest"`
	Bundles          []string             `toml:"bundles"`
	RunnerPools      []StandardRunnerPool `toml:"runner_pools"`
	ApplyWaitSeconds *int64               `toml:"apply_wait_seconds"`
}

StandardResources is an explicit release-bundle selection. It contains no authority.

type StandardRunnerPool

type StandardRunnerPool struct {
	Bundle         string   `toml:"bundle"`
	Name           string   `toml:"name"`
	Architectures  []string `toml:"architectures"`
	Capabilities   []string `toml:"capabilities"`
	State          string   `toml:"state"`
	MaxSandboxes   *int64   `toml:"max_sandboxes"`
	MaxVCPUCount   *int64   `toml:"max_vcpu_count"`
	MaxMemoryBytes *int64   `toml:"max_memory_bytes"`
}

StandardRunnerPool binds one standard bundle's fixed selector to deployment inventory.

type SystemComposeExecutor added in v0.4.0

type SystemComposeExecutor struct {
	Input      io.Reader
	Output     io.Writer
	Diagnostic io.Writer
}

func (SystemComposeExecutor) Run added in v0.4.0

func (executor SystemComposeExecutor) Run(ctx context.Context, arguments []string) error

type TuningOverrides

type TuningOverrides struct {
	HTTPTimeoutSeconds                          *int64 `toml:"http_timeout_seconds"`
	RunnerHeartbeatIntervalMilliseconds         *int64 `toml:"runner_heartbeat_interval_milliseconds"`
	RunnerHeartbeatTimeoutMilliseconds          *int64 `toml:"runner_heartbeat_timeout_milliseconds"`
	RunnerCommandDeliveryBatchSize              *int64 `toml:"runner_command_delivery_batch_size"`
	RunnerEventPersistenceBatchSize             *int64 `toml:"runner_event_persistence_batch_size"`
	RunnerEventPersistenceBatchWaitMilliseconds *int64 `toml:"runner_event_persistence_batch_wait_milliseconds"`
	DataPlaneMaximumSessionBytes                *int64 `toml:"data_plane_maximum_session_bytes"`
	IdempotencyRetentionSeconds                 *int64 `toml:"idempotency_retention_seconds"`
	LifecycleReconcileBatchSize                 *int64 `toml:"lifecycle_reconcile_batch_size"`
	LifecycleReconcilePollIntervalMilliseconds  *int64 `toml:"lifecycle_reconcile_poll_interval_milliseconds"`
	LifecycleReconcileClaimDurationMilliseconds *int64 `toml:"lifecycle_reconcile_claim_duration_milliseconds"`
	AssignmentClaimDurationMilliseconds         *int64 `toml:"assignment_claim_duration_milliseconds"`
	AssignmentDeadlineMilliseconds              *int64 `toml:"assignment_deadline_milliseconds"`
	AssignmentRetryLimit                        *int64 `toml:"assignment_retry_limit"`
	SchedulerSerializationRetryLimit            *int64 `toml:"scheduler_serialization_retry_limit"`
}

TuningOverrides owns the public TOML names for all Category C overrides.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL