Returns the cluster-wide blue-green deployment status.

Queries every reachable parent node's PeerManager for its state, and checks peer connectivity from the caller's perspective. Callable from any node (parent or peer).

Return Value

A list of machine status maps:

[
  %{
    machine_id: "abc123def456",
    region: "iad",
    parent: :"fly_deploy_parent_123@fd00::1",
    active_peer: :"sprites_peer_abc123_1@fd00::1",
    active_peer_alive: true,
    peer_connected: true,
    upgrading: false
  },
  ...
]

Fields:

• :machine_id - Fly machine ID
• :region - Fly region code
• :parent - Parent node name on this machine
• :active_peer - The currently active peer node name
• :active_peer_alive - Whether the peer OS process is alive (from parent's view)
• :peer_connected - Whether the active peer is reachable from the caller
• :upgrading - Whether a blue-green upgrade is in progress on this machine

If a parent is unreachable, returns %{parent: node, error: :unreachable}.

Example

FlyDeploy.blue_green_cluster_status()
#=> [
#     %{machine_id: "28715e9ad771", region: "iad", parent: ..., active_peer: ...,
#       active_peer_alive: true, peer_connected: true, upgrading: false},
#     %{machine_id: "d8de3d0b2d91", region: "ord", parent: ..., active_peer: ...,
#       active_peer_alive: true, peer_connected: true, upgrading: false}
#   ]

Returns a child specification for the FlyDeploy poller.

Add this to your supervision tree to enable automatic hot upgrade polling:

def start(_type, _args) do
  children = [
    {FlyDeploy, otp_app: :my_app},
    # ... rest of your children
  ]

  Supervisor.start_link(children, strategy: :one_for_one)
end

Options

• :otp_app - The OTP application name (required)
• :poll_interval - How often to poll S3 in ms (default: 1000)
• :suspend_timeout - Timeout for suspending processes during upgrade in ms (default: 10_000)

Important

Place {FlyDeploy, otp_app: :my_app} at the TOP of your children list. The poller blocks during init/1 to apply any pending hot upgrades before the rest of the supervision tree starts. This ensures new code is loaded before other processes start.

Returns the current code version fingerprint.

The fingerprint is a map containing:

• :base_image_ref - The base Docker image (FLY_IMAGE_REF)
• :hot_ref - The hot upgrade source image ref (nil if no hot upgrade applied)
• :version - The hot upgrade version (nil if no hot upgrade applied)
• :fingerprint - A short 12-character hash combining base + hot refs

Returns nil if poller hasn't been started or version not yet initialized.

Example

FlyDeploy.current_vsn()
#=> %{
#     base_image_ref: "registry.fly.io/my-app:deployment-01K93Q...",
#     hot_ref: "registry.fly.io/my-app:deployment-01K94R...",
#     version: "0.1.5",
#     fingerprint: "a1b2c3d4e5f6"
#   }

Gets current hot upgrade information for this machine.

Returns a map with the current deployment state, including whether a hot upgrade has been applied and details about the upgrade.

This is typically called via RPC from mix fly_deploy.status.

Parameters

• app - The OTP application name (atom)

Returns

• %{hot_upgrade_applied: false} - No hot upgrade applied (running base image)
• %{hot_upgrade_applied: true, version: "...", source_image_ref: "...", deployed_at: "..."} - Hot upgrade applied

Example

# Via RPC
FlyDeploy.get_current_hot_upgrade_info(:my_app)
#=> %{
#     hot_upgrade_applied: true,
#     version: "0.1.1",
#     source_image_ref: "registry.fly.io/my-app:deployment-01K94R...",
#     deployed_at: "2024-01-15T10:30:00Z",
#     current_image_ref: "registry.fly.io/my-app:deployment-01K93Q..."
#   }

Performs a hot upgrade on a running machine.

Downloads a tarball from S3, extracts and copies beam files to disk, then safely upgrades all running processes.

This is typically invoked via RPC from the orchestrator machine.

Parameters

• tarball_url - S3 URL of the tarball containing new beam files
• app - OTP application name
• opts - Options (optional)
  • :suspend_timeout - Timeout in ms for suspending each process (default: 10_000)

Process

1. Download tarball from S3 (with AWS SigV4 auth)
2. Extract and copy beam files to loaded paths
3. Suspend all processes using changed modules
4. Load new code
5. Call code_change/3 on each process
6. Resume all processes

Safety

• Processes are suspended during upgrade (typically < 1 second)
• State is preserved via code_change/3 callbacks
• Errors are caught and logged without crashing

Returns the incoming peer node that is replacing this peer, or nil.

Only meaningful on the outgoing peer during a blue-green upgrade — set just before :init.stop() is called. User processes that trap exits can call this in their terminate/2 to discover the incoming peer and hand off state directly via :erpc.call/4.

Returns nil on the initial boot, if not running as a peer, or if no upgrade is in progress.

Example

# In a GenServer that traps exits
def terminate(_reason, state) do
  case FlyDeploy.incoming_peer() do
    nil -> :ok
    node -> :erpc.call(node, MyApp.Cache, :warm, [state.entries])
  end
end

Returns a list of blue-green peer nodes visible to this node.

Peer nodes are named with a _peer_ segment (e.g., my_app_peer_123@fd00::1). This filters Node.list/0 to only return peer nodes, excluding parent nodes, remsh sessions, and other non-peer nodes.

Useful for clustering logic where you want to ignore the hidden parent nodes and only interact with the peers that actually serve traffic.

Example

FlyDeploy.list_remote_peers()
#=> [:"my_app_peer_818@fdaa:28:186d:a7b:577:86b0:d474:2"]

Orchestrates a hot upgrade across all machines in the application.

This is typically called by mix fly_deploy.hot on a temporary orchestrator machine. It builds a tarball of all .beam files, uploads to S3, updates deployment metadata, and triggers upgrades on all running machines via RPC.

Options

• :app - The OTP application name (required)
• :image_ref - The Docker image reference for this deployment (required)

Bucket is discovered from Application config or BUCKET_NAME environment variable.

Example

# Usually called by mix fly_deploy.hot
FlyDeploy.orchestrate(
  app: :my_app,
  image_ref: "registry.fly.io/my_app:deployment-01K93Q..."
)

Process

1. Build tarball from /app/lib/**/ebin/*.beam
2. Upload to S3 at releases/<app>-<version>.tar.gz
3. Update metadata at releases/<app>-current.json
4. Get list of running machines from Fly API
5. Trigger hot_upgrade/2 on each machine via RPC
6. Wait for all machines to complete

Returns the outgoing peer node that this peer is replacing, or nil.

Only meaningful during a blue-green upgrade — the incoming peer can call this during its boot sequence to discover the outgoing peer for handoff coordination (e.g., releasing a volume lock, draining connections, transferring state).

Returns nil on the initial boot (no outgoing peer) or if not running as a peer.

Example

# In your Application.start/2 or a GenServer init
case FlyDeploy.outgoing_peer() do
  nil -> :ok
  node -> :erpc.call(node, MyApp.Lock, :release, [])
end

See FlyDeploy.BlueGreen.PeerManager.peer_node/0.

Deprecated: Use {FlyDeploy, otp_app: :my_app} in your supervision tree instead.

This function is kept for backwards compatibility but simply starts the poller.

Migration

Replace:

def start(_type, _args) do
  :ok = FlyDeploy.startup_reapply_current(:my_app)
  children = [...]
  Supervisor.start_link(children, strategy: :one_for_one)
end

With:

def start(_type, _args) do
  children = [
    {FlyDeploy, otp_app: :my_app},
    # ... rest of your children
  ]
  Supervisor.start_link(children, strategy: :one_for_one)
end

Subscribes the calling process to FlyDeploy lifecycle events.

The subscriber receives messages of the form {:fly_deploy, event, metadata}.

Events

Hot upgrade events (delivered on the machine being upgraded):

• {:fly_deploy, :hot_upgrade_started, %{app: atom, tarball_url: String.t}}
• {:fly_deploy, :hot_upgrade_complete, %{app: atom, modules_reloaded: integer, processes_upgraded: integer, processes_failed: integer, duration_ms: integer}}

Blue-green events (delivered to the appropriate peer via erpc):

• {:fly_deploy, :blue_green_upgrade_started, %{app: atom}} — sent to the old peer
• {:fly_deploy, :blue_green_incoming_peer_started, %{incoming_node: node, outgoing_node: node, start_ms: integer}} — sent to the old peer
• {:fly_deploy, :blue_green_upgrade_complete, %{active_node: node, start_ms: integer, shutdown_ms: integer}} — sent to the new peer

Example

defmodule MyApp.DeployListener do
  use GenServer

  def start_link(_), do: GenServer.start_link(__MODULE__, [])

  def init(_) do
    FlyDeploy.subscribe()
    {:ok, %{}}
  end

  def handle_info({:fly_deploy, event, meta}, state) do
    Logger.info("Deploy event: #{event} #{inspect(meta)}")
    {:noreply, state}
  end
end