Documentation
¶
Overview ¶
Package deployconfig compiles the sole operator-edited SecondBox deployment manifest into explicit process environment artifacts.
Index ¶
- Constants
- func ApplyStandardResources(ctx context.Context, resolved ResolvedDeployment, httpClient *http.Client) (resourceapply.Report, error)
- func ComposeDiagnosticArguments(manifestPath string, command ...string) ([]string, error)
- func ComposeDiagnosticArgumentsForAcceptedInstaller(manifestPath string, command ...string) ([]string, error)
- func EncodeComposeEnvironment(environment map[string]string) ([]byte, error)
- func EncodeSystemdEnvironment(environment map[string]string) ([]byte, error)
- func InitDevelopment(directory string) (string, error)
- func InitProduction(directory string) (string, error)
- func InitProductionFromManifest(sourcePath, directory string) (string, error)
- func InitProductionFromRelease(sourcePath, directory string, release releasecontract.ArtifactManifest, ...) (string, error)
- func Inspect(manifestPath string) ([]byte, error)
- func PurgeComposeVolumes(ctx context.Context, manifestPath string, executor ComposeExecutor) error
- func PurgeComposeVolumesForAcceptedInstaller(ctx context.Context, manifestPath string, executor ComposeExecutor) error
- func RunCompose(ctx context.Context, manifestPath, action string, executor ComposeExecutor, ...) error
- func RunComposeForAcceptedInstaller(ctx context.Context, manifestPath, action string, executor ComposeExecutor, ...) error
- func RunnerInit(manifestPath, runnerID, target string) error
- func RunnerInitOrValidate(manifestPath, runnerID, target string) error
- func RunnerTemplate() []byte
- func SecretFingerprint(value string) string
- func WriteRunnerTemplate(path string) error
- type Applications
- type ComposeExecutor
- type Database
- type Deployment
- type InspectedOverride
- type InspectedPolicy
- type InspectedStandardProfile
- type Inspection
- type ManifestV1
- type OverrideDefinition
- type Policy
- type ResolvedDeployment
- type Runner
- type RunnerTrust
- type SingleHostInstallResult
- type StandardResources
- type StandardRunnerPool
- type SystemComposeExecutor
- type TuningOverrides
Constants ¶
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
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 InitDevelopment ¶
InitDevelopment creates one complete reviewed loopback deployment. It never replaces an existing path or artifact.
func InitProduction ¶
InitProduction writes an annotated, intentionally incomplete shape and reports all unresolved decision groups in one error.
func InitProductionFromManifest ¶
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 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 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 RunnerInit ¶
func RunnerInitOrValidate ¶ added in v0.4.0
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 ¶
SecretFingerprint returns redacted identity evidence for inspect output.
func WriteRunnerTemplate ¶ added in v0.2.0
WriteRunnerTemplate creates one Runner declaration scaffold without replacing an existing file.
Types ¶
type Applications ¶
type ComposeExecutor ¶ added in v0.4.0
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"`
SignedAssetCatalog string `toml:"signed_asset_catalog"`
SignedAssetCatalogPath string `toml:"signed_asset_catalog_path"`
DevelopmentWaitSeconds *int64 `toml:"development_prepare_wait_timeout_seconds"`
}
type InspectedOverride ¶
type InspectedPolicy ¶
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"`
DefaultSubjectMaxCPUMillis *int64 `toml:"default_subject_max_cpu_millis"`
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"`
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 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"`
MaxCPUMillis *int64 `toml:"max_cpu_millis"`
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 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.