deployconfig

package
v0.19.0 Latest Latest
Warning

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

Go to latest
Published: Sep 27, 2026 License: MIT Imports: 45 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 ComposeDiagnosticArgumentsForAcceptedInstaller added in v0.4.4

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

ComposeDiagnosticArgumentsForAcceptedInstaller returns existing deployment transport arguments for read-only inspection without rerendering assets.

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 PurgeComposeVolumesForAcceptedInstaller added in v0.4.4

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

PurgeComposeVolumesForAcceptedInstaller removes the accepted deployment's containers, networks, and named volumes. Ordinary uninstall preserves the bundled database; the typed permanent-purge workflow removes it.

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"`
	RunnerBindIP                  string `toml:"runner_bind_ip"`
	RunnerPublishedPort           *int64 `toml:"runner_published_port"`
	LogPath                       string `toml:"log_path"`
	ExecutionImagePublicKey       string `toml:"execution_image_public_key"`
	ExecutionImagePublicKeySHA256 string `toml:"execution_image_public_key_sha256"`
	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 InspectedRunner added in v0.8.0

type InspectedRunner struct {
	ID       string   `json:"id"`
	Contexts []string `json:"contexts"`
}

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"`
	Runners                []InspectedRunner          `json:"runners"`
	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"`
	RunnerEnabledFeatures     string `toml:"runner_enabled_features"`
}

type ResolvedDeployment

type ResolvedDeployment struct {
	Manifest                   ManifestV1
	Environment                map[string]string
	RemoteRunnerEnvironment    map[string]map[string]string
	RunnerEgressContextConfigs map[string][]byte
	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,omitempty"`
	IdentityHostDirectory                 string                `toml:"identity_host_directory"`
	ArtifactHostDirectory                 string                `toml:"artifact_host_directory"`
	StateHostDirectory                    string                `toml:"state_host_directory"`
	ExecutionImageRegistries              string                `toml:"execution_image_registries"`
	ExecutionImageRegistryConfigDirectory string                `toml:"execution_image_registry_config_directory"`
	ExecutionImagePublicKey               string                `toml:"execution_image_public_key,omitempty"`
	ExecutionImagePublicKeySHA256         string                `toml:"execution_image_public_key_sha256"`
	ExecutionImageMaxDownloadBytes        *int64                `toml:"execution_image_max_download_bytes"`
	ExecutionImageMaxExpandedBytes        *int64                `toml:"execution_image_max_expanded_bytes"`
	ExecutionImageMaxCacheBytes           *int64                `toml:"execution_image_max_cache_bytes"`
	LogPath                               string                `toml:"log_path,omitempty"`
	LogDirectory                          string                `toml:"log_directory,omitempty"`
	FirecrackerPath                       string                `toml:"firecracker_path,omitempty"`
	FirecrackerJailerPath                 string                `toml:"firecracker_jailer_path,omitempty"`
	FirecrackerJailRoot                   string                `toml:"firecracker_jail_root,omitempty"`
	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,omitempty"`
	FirecrackerRootFSPath                 string                `toml:"firecracker_rootfs_path,omitempty"`
	FirecrackerSharedImagePath            string                `toml:"firecracker_shared_image_path,omitempty"`
	FirecrackerKernelArgs                 string                `toml:"firecracker_kernel_args"`
	FirecrackerCPUTemplate                string                `toml:"firecracker_cpu_template"`
	FirecrackerRunDirectory               string                `toml:"firecracker_run_directory,omitempty"`
	FirecrackerLogDirectory               string                `toml:"firecracker_log_directory,omitempty"`
	SnapshotTemplateCacheRoot             string                `toml:"snapshot_template_cache_root,omitempty"`
	ArtifactPublicKey                     string                `toml:"artifact_public_key,omitempty"`
	ArtifactPublicKeySHA256               string                `toml:"artifact_public_key_sha256"`
	WorkspaceRoot                         string                `toml:"workspace_root,omitempty"`
	StorageRecoveryPercent                *int64                `toml:"storage_pressure_recovery_percent"`
	StorageWarningPercent                 *int64                `toml:"storage_pressure_warning_percent"`
	StorageAdmissionDenyPercent           *int64                `toml:"storage_pressure_admission_deny_percent"`
	StorageAdmissionMode                  string                `toml:"storage_admission_mode"`
	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,omitempty"`
	SandboxDeleteBridge                   *bool                 `toml:"sandbox_delete_bridge"`
	NetworkPolicyNFTPath                  string                `toml:"network_policy_nft_path,omitempty"`
	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"`
	EgressContextConfigPath               string                `toml:"egress_context_config_path,omitempty"`
	EgressContexts                        []RunnerEgressContext `toml:"egress_contexts"`
	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 RunnerEgressContext added in v0.8.0

type RunnerEgressContext struct {
	Name     string                 `toml:"name" json:"name"`
	Gateways []RunnerLogicalGateway `toml:"gateways" json:"gateways"`
}

RunnerEgressContext is one Runner-local routing authority.

type RunnerLogicalGateway added in v0.8.0

type RunnerLogicalGateway struct {
	LogicalName      string `toml:"logical_name" json:"logicalName"`
	Address          string `toml:"address" json:"address,omitempty"`
	AttributedSocket string `toml:"attributed_socket" json:"attributedSocket,omitempty"`
}

RunnerLogicalGateway binds a Profile destination to operator-owned local routes.

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
	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 {
	Name          string   `toml:"name"`
	Architectures []string `toml:"architectures"`
	Capabilities  []string `toml:"capabilities"`
	State         string   `toml:"state"`
}

StandardRunnerPool declares inventory once for all bundles using its name.

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 {
	DataPlanePollIntervalMilliseconds           *int64 `toml:"data_plane_poll_interval_milliseconds"`
	RunnerCommandPollIntervalMilliseconds       *int64 `toml:"runner_command_poll_interval_milliseconds"`
	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