Not yet released. This guide describes implemented changes awaiting rollout. Availability requires the corresponding backend and dashboard release.
Goal
Prepare a worker with explicit connections and verify both its replacement and source retirement.Prerequisites
- These corrections are implemented locally and unreleased. Require migration 574 before the matching API and worker, updated node agents, and a rebuilt Node builder image before relying on the complete contract.
- The GitHub archive analysis and direct development-preload checks require their matching API and worker releases. A local test pass does not establish production rollout.
Workflow
1
For an existing application, use Add workloads or the worker handoff in project review. Select the application explicitly, review its default destination, and save the worker.
2
Add runtime and build settings in the correct stages. Explicitly connect PostgreSQL, Redis, ClickHouse, or another private dependency in Connections before releasing. Sibling secrets are not copied.
3
Keep each private consumer and dependency on the same node. Placement edits and release preparation reject unsupported combinations. Application defaults do not overwrite intentional per-service placement.
4
Create a new release after changing connections, placement, source, or environment. Retrying a sealed operation does not capture edits; a revoked or changed private connection requires a new release.
5
For a running worker moving across nodes, record concurrent_workers and acknowledged_jobs in its existing workload scaling safety contract; schedulers also require singleton_schedules. Otherwise stop the current worker before moving. Persistent volumes require a verified storage migration.
6
After promotion, check source_cleanup_state. Pending means the prior worker may still run. Completed requires a fenced acknowledgement from its source node; an offline source retains the exact retirement obligation.
Certificates and independent databases
Explicit CLICKHOUSE_CA_CERT, client-wide trust settings, and unrelated external database URLs retain their meaning. A PEM value is never converted into a filename. TLS verification remains enabled. Managed binding URLs carry verified TLS parameters. Platform-owned STACKSHIFT_DATABASE_CA_CERT_FILE, STACKSHIFT_POSTGRES_CA_CERT_FILE, STACKSHIFT_MYSQL_CA_CERT_FILE, STACKSHIFT_MARIADB_CA_CERT_FILE, STACKSHIFT_CLICKHOUSE_CA_CERT_FILE, and STACKSHIFT_REDIS_CA_CERT_FILE identify mounted trust files when the corresponding managed CA is available. Clients that expect certificate contents must read the indicated file explicitly. Clients that accept a file path can use it directly. The platform does not infer a library-specific meaning for CLICKHOUSE_CA_CERT or replace an external database trust file. If your application relied on a legacy implicitly injected client-specific CA alias, configure the appropriate STACKSHIFT_*_CA_CERT_FILE explicitly. Node managed PostgreSQL bindings use the mounted Node trust bundle when no explicit NODE_EXTRA_CA_CERTS setting exists; explicit client-wide trust settings remain yours to configure. Multiple managed databases retain their explicit binding variable names. Ambiguous convenience aliases are omitted rather than choosing one database by iteration order. Existing explicit aliases are preserved.Reconciliation and failure evidence
Attachment commits membership, internal service synchronization, and the route-reconciliation task atomically. Retrying attachment to the same application is safe after a lost response; attaching to a different application is refused. Private visibility is requested configuration until route reconciliation finishes at actual runtime locations, including the source node. Pending tasks retain a retryable error when a node is unavailable. An owned candidate that exits after preparation is an application startup failure. Sanitized startup evidence survives rollback. Foreign workload identity remains protected. Agent responses record compensation errors separately from the primary startup error. Source retirement deletes only exact captured runtime identities. Persistent data and sibling runtimes are retained. Historical abandoned workloads without a recorded retirement obligation still require verified operator reconciliation; this change is not a blanket deletion backfill.Source, packaging, and deadlines
Every Git build requires a resolved full commit SHA before queueing and a verified detached checkout. Failed source resolution never queues moving HEAD. The final Node package validates supported literal entrypoints, package-script startup commands, and startup preloads after production dependency pruning. JavaScript entrypoints receive a bounded syntax check without executing application code. Dynamic shell commands, unrecognized options, and arbitrary indirect imports remain outside this static check. Log persistence is bounded by the active build deadline and a five-second storage-call limit. Cancellation also closes command output pipes so inherited descriptors cannot keep the log drain alive. Lease and attempt fences remain enforced. Physical qualification of the representative PostgreSQL/Redis/ClickHouse worker and interrupted two-node moves is deferred to the operator after deployment because isolated test nodes are unavailable. Unit and database tests alone do not establish provider behavior or rollout.Expected result
Accepted configuration remains explicit, unavailable private connections fail clearly, and deployment success does not hide pending source cleanup.