Add documentation for app-scoped egress IPs

Author: PeterCxy

networking/egress-ips.html.md

@@ -9,10 +9,10 @@ date: 2025-10-02
 ## Overview
 
 - By default, outbound (egress) IPs from Fly Machines are **unstable** and may change.
-- You can allocate **static egress IPs** per machine (both IPv4 and IPv6) via `fly machine egress-ip`.
-- Static egress IPs come with trade-offs: cost, binding to machine lifecycle, and deployment quirks.
-- A common workaround is to front outbound traffic through a **proxy** app that _does_ have static egress IPs.
-- App-scoped egress IPs are in development and may simplify this in the future.
+- You can allocate **static egress IPs** for an app (both IPv4 and IPv6) via `fly ips allocate-egress`.
+- App-scoped Static egress IPs are per-region: you need one for every region where you have machines.
+- Static egress IPs come with trade-offs: cost, concurrent machines / connections.
+- Legacy machine-scoped static egress IPs are still availble, but no longer recommended due to their limitations and quirks.
 
 ---
 
@@ -26,8 +26,52 @@ Some external services—APIs, databases, payment providers—require allowlisti
 
 ---
 
+## Static Egress IPs (App-Scoped)
+
+App-scoped static egress IPs can be shared between multiple machines in a region belonging to the same app, and will not be deleted when machines are recreated. They are recommended over our legacy, machine-scoped static egress IPs.
+
+### Allocate an App-scoped Static Egress IP
+
+```bash
+fly ips allocate-egress --app <app-name> -r <region>
+```
+
+This allocates a pair of static egress IPv4 and IPv6 for your app in a region.
+
+If your app has Machines in multiple regions, you must allocate at least 1 app-scoped static egress IP address __per region__.
+Only machines located in the same region can use static egress IPs allocated in the region.
+
+<div class="note icon">
+You can allocate multiple pairs of static egress IPv4 and IPv6 in the same region. Machines will randomly choose a pair from all static Egress IPs available in the region.
+</div>
+
+### View and Manage
+
+```bash
+fly ips list
+fly ips release-egress <ip-address>
+```
+
+### Billing
+
+Each app-scoped static egress IPv4 cost $3.60/mo, billed hourly. IPv6 is currently free, but must be allocated along with an IPv4.
+
+### Caveats
+
+- Each static egress IP can support up to 64 Machines. If you need more than 64 Machines in one region, you will need to allocate multiple static egress IPs.
+- When using App-scoped static egress IPs, a Machine can make up to 1000 connections to _each_ external IP address. There is no limit on the _total_ number of concurrent connections.
+  - We do not expect this to be a concern for most apps. However, feel free to talk to us if this limits your use case!
+- When you have multiple static egress IPs assigned in one region, there is currently no way to specify exactly which IP each machine will use.
+- When new machines are created, there might be a brief window when an app-scoped egress IP is not applied to the machine. This may happen more often with more machines or during bluegreen deployment. Allocating multiple pairs of static egress IPs alleviates the issue.
+
+---
+
 ## Static Egress IPs (Machine-Scoped)
 
+<div class="warning icon">
+Machine-scoped static egress IPs are considered a legacy feature and may be removed in the future. This document section is kept for reference purposes only. New apps should use [app-scoped static egress IPs](#static-egress-ips-app-scoped).
+</div>
+
 ### Allocate a Static Egress IP
 
 ```bash
@@ -45,7 +89,7 @@ fly machine egress-ip release <machine-id> --app <app-name>
 
 ### Caveats
 
-Static egress IPs are **per-machine**, not per-app.
+Because legacy static egress IPs are **per-machine**, not per-app:
 
 - IPs are released when a machine is destroyed.
 - IPs don’t automatically transfer across deploys.
@@ -54,12 +98,16 @@ Static egress IPs are **per-machine**, not per-app.
 - Extra latency and connectivity issues are possible in some regions.
 
 <div class="callout">
-Static egress IPs are billed per hour per machine.
+Machine-scoped static egress IPs are billed per hour per machine.
 </div>
 
 ---
 
-## The Proxy Pattern
+## The Proxy Pattern (for Machine-Scoped Static Egress IPs)
+
+<div class="warning icon">
+This section only applies to existing apps using machine-scoped static egress IPs. New apps should use [app-scoped static egress IPs](#static-egress-ips-app-scoped) instead.
+</div>
 
 To avoid assigning static IPs to every machine, route traffic through a shared proxy app.
 

networking/services.html.markerb

@@ -12,6 +12,10 @@ Fly.io has public and private network services available. The public network ser
 
 IPv6 addresses and shared IPv4 Anycast addresses are free. Dedicated IPv4 addresses are [billed](/docs/about/pricing/#anycast-ip-addresses) monthly.
 
+<div class="note icon">
+Anycast IP addresses described on this page are __not used__ for outbound connections made from within a Machine. See [Egress IP Addresses](/docs/networking/egress-ips/) for details.
+</div>
+
 ### About Anycast
 
 We announce global IP blocks from all of our datacenters over BGP, otherwise known as Anycast. Anycast is a core internet routing mechanism that connects clients to the "nearest" server advertising a block of IPs. You can read [all about it on Wikipedia](https://en.wikipedia.org/wiki/Anycast+external).