VoiceThere
Sign up

Rollout modes

Every deploy has to decide what happens to calls that are still running on the old version. VoiceThere gives you two answers, drain and force, and drain is the default.

Drain (default)

New calls go to the new version right away. Calls already in progress keep running on the previous version until they end on their own. A call that is still going after 9 minutes ends with the reason runner_shutdown. Nobody is cut off during a normal deploy, but a bad build can keep answering calls for up to 9 minutes after you ship the fix.

Force

New calls go to the new version, the same as with drain. Within 15 seconds of the new version being ready, every call still on an older version ends. That includes calls that are still finishing from an earlier drain deploy, so a forced fix also clears out a bad build you shipped a few minutes ago. Use force for urgent fixes, and expect callers on the old version to be disconnected.

What your app and callers see on force

The session ends with the end reason force_rollout. The sessions list and the metrics show it as Ended by a forced deploy. In @voicethere/client the caller gets a non-recoverable session_error with the code WEBRTC_CONNECTION_CLOSED, and the client does not reconnect. Your app should offer to start a new session, which reaches the new version. Billing stops when the call ends.

One deploy at a time

While an older version is still finishing calls, you cannot stack another deploy on top of it. A drain deploy in that situation is refused with the code PREVIOUS_VERSION_DRAININGand the message “The previous version is still finishing calls in progress. Deploy again once it has stopped (up to 9 minutes), or deploy with force to end those calls now.” The API answers with HTTP 409, and the CLI and the dashboard show the message.

There is one exception. A force deploy is allowed over a version that is still draining from an earlier drain deploy. Say version A is live, you drain-deploy B, and A is still finishing calls. A force deploy of C then ends the calls on both A and B, so the fix reaches everyone within 15 seconds.

After a force deploy, every deploy waits until the forced version is the only one left, which takes a few seconds. A deploy of either mode in that window is refused with the code FORCED_ROLLOUT_SHUTTING_DOWNand the message “A forced deploy is still shutting down older versions. Try again in a few seconds.” Deploy again once it has passed.

Refused deploys and forced deploys are recorded in the Audit log in the dashboard sidebar, as the actions deployment.blocked and deployment.force_end. The forced deploy entry also says how many running instances of older versions it ended. Every deploy also writes deployment.completed or deployment.failed when it ends.

When a deploy fails after it was accepted, the dashboard and the CLI say whether the cause is in your agent or on our side. See When a deploy fails. Before a new version takes calls, the deploy also loads your agent once to check that it starts; see How a deploy checks your agent.

Choose a mode

  • Dashboard: Project → Cloud rollout → Rollout mode → Deploy to cloud. The hint under the selector repeats what the chosen mode does.
  • CLI: voicethere deploy --mode force --wait for force, and voicethere deploy --wait for drain. Any other mode is rejected. See the CLI command reference.
  • API: POST /api/v1/deployments with the body {"project_id":"<uuid>","mode":"force"}. mode defaults to drain. See Control plane API.

← All documentation