Deploy updates and roll back

Use this guide after you have deployed an application with 1ctl. It focuses on changing the rollout strategy and moving between application releases.

Before you start

Confirm that you are signed in and set your application name:

1ctl auth status
export APP="my-app"
1ctl app status "$APP"

Replace my-app with the name in the [app] section of your satusky.toml.

Configure a rolling update

Add or update the [deploy] section in satusky.toml:

[deploy]
replicas = 1
strategy = "rolling"
rolling_max_surge = "1"
rolling_max_unavailable = "0"

This configuration means:

• rolling_max_surge = 1 allows one additional replica while an update is in progress.
• rolling_max_unavailable = 0 keeps the existing replica available until its replacement is ready.

The selected machine must have enough spare capacity for the temporary surge replica. If it does not, the update waits until capacity becomes available. For higher-traffic production applications, increase replicas when your available capacity supports it.

Deploy the configuration:

1ctl deploy --wait
1ctl app status "$APP"

The status output should show:

Strategy: rolling (maxSurge=1, maxUnavailable=0)

--wait waits for the workload to become healthy. For a public application, the default threshold is stricter: it waits for current reconciliation, an available workload, and verified application readiness. A ready replica count or a printed URL by itself is not application verification.

Configure an application health endpoint when the backend does not already provide a verified readiness probe:

[checks]
health_path = "/health"

An explicit health_path (or 1ctl deploy --health-path /health) can satisfy the application check only after the public route is available and the HTTP request succeeds. It is not a generic URL/reachability check.

1ctl deploy --wait --wait-mode workload is an explicit compatibility mode. It succeeds after reconciliation is current and the workload is available, prints a warning, and does not verify the application. Do not use it as a release-health gate.

Inspect the live conditions with 1ctl app status "$APP". Its table reports Application readiness: <state> (<basis>); JSON includes status.readiness. The additive readiness object separates these conditions:

Condition	Phase 3 meaning
Reconciliation	current, progressing, or failing, with desired and observed generation fields.
Workload	available, progressing, failing, or unknown, with desired, ready, available, and updated replica counts.
Application	verified, failing, unconfigured, or unknown; basis is readiness_probe, no_readiness_probe, or primary_application_unknown.
Route	Present as a not_observed/unknown placeholder; it is not a Phase 3 external route observation.
DNS	status.readiness retains a not_observed/unknown placeholder. The live authoritative DNS result is separate at domain_status.dns.condition.
Public reachability	Present as a not_observed/unknown placeholder; it is not a Phase 3 public-reachability observation.

Older backends can omit this object. The CLI treats missing or unknown live readiness conservatively, so default --wait cannot succeed from a legacy running status alone. READINESS_UNVERIFIED means configure or repair the readiness signal (or use a successful explicit health path), inspect status and logs, then retry. READINESS_FAILED means a reported reconciliation, workload, or application condition is failing; inspect status and logs, correct that condition, and retry.

For a public hostname, inspect DNS condition in the same status output. Its JSON path is domain_status.dns.condition in 1ctl -o json app status "$APP". Only verified proves DNS resolves to the reserved target. pending, nxdomain, wrong_target, and error do not make DNS, the public route, or application readiness successful; route attachment and application readiness must still be evaluated independently.

Inspect the release history

List the releases recorded for the application:

1ctl app releases "$APP"

The first deployment is version 1 with an active status.

Deploy a new version

Change your application code, then deploy from the directory containing satusky.toml:

1ctl deploy --wait
1ctl app releases "$APP"
1ctl app status "$APP"

The release list now shows a new active version. The previous version is superseded.

If your deployment uses an explicit health path, the successful default wait already verified that path after a public HTTP response. Route, DNS, and public reachability fields in status.readiness are Phase 3 placeholders, not a claim that those observations are currently collected. Use the separate domain_status.dns.condition result when DNS verification is required.

Roll back

Choose a version from 1ctl app releases, then initiate the rollback:

export TARGET_VERSION=1
1ctl app rollback "$APP" --version "$TARGET_VERSION" --yes

Rollback is asynchronous. Check status until the workload is available and application readiness is verified with the target image:

1ctl app status "$APP"
1ctl app releases "$APP"

The rollback creates a new active release that points to the selected version’s image. It does not erase release history.

If the application exposes a health path, rerun the deploy or status workflow with the same readiness configuration to verify the recovered release.

Clean up a test application

Delete the application through the supported lifecycle:

1ctl app delete "$APP" --yes
1ctl app list

The delete command waits for the platform to report a terminal result. It can report retained storage separately; preserve that report for recovery. A missing status response is not proof that deletion completed.