Skip to content

Improve recommendations for gRPC network handlers #2336

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jbellerb merged 2 commits into from
Jan 20, 2026
Merged

Improve recommendations for gRPC network handlers #2336

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1c36e6f
Improve recommendations for gRPC network handlers
jbellerb Jan 19, 2026
8049093
Update networking/services.html.markerb
jbellerb Jan 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 9 additions & 6 deletions networking/services.html.markerb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
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.

Check failure on line 16 in networking/services.html.markerb

View workflow job for this annotation

GitHub Actions / Vale linter 

[vale] reported by reviewdog 🐶
[Vale.Terms] Use 'IPs' instead of 'ips'.

Raw Output:
{"message": "[Vale.Terms] Use 'IPs' instead of 'ips'.", "location": {"path": "networking/services.html.markerb", "range": {"start": {"line": 16, "column": 165}}}, "severity": "ERROR"}
</div>

### About Anycast
Expand All @@ -25,7 +25,7 @@
A new Fly App running a public service configured in [`fly.toml`](/docs/reference/configuration/) automatically gets a dedicated Anycast IPv6 address when it's first deployed.

<div class="note icon">
If you create apps with public services in their Machine config by using [`fly machine` commands](/docs/machines/flyctl/fly-machine-run/#define-a-fly-proxy-network-service) or the [Machines API](https://fly.io/docs/machines/api/), then you need to run `fly ips allocate-v6` to get a dedicated IPv6 address.

Check failure on line 28 in networking/services.html.markerb

View workflow job for this annotation

GitHub Actions / Vale linter 

[vale] reported by reviewdog 🐶
[Vale.Terms] Use 'IPs' instead of 'ips'.

Raw Output:
{"message": "[Vale.Terms] Use 'IPs' instead of 'ips'.", "location": {"path": "networking/services.html.markerb", "range": {"start": {"line": 28, "column": 258}}}, "severity": "ERROR"}

Check failure on line 28 in networking/services.html.markerb

View workflow job for this annotation

GitHub Actions / Vale linter 

[vale] reported by reviewdog 🐶
[Vale.Terms] Use 'APIs?\b' instead of 'api'.

Raw Output:
{"message": "[Vale.Terms] Use 'APIs?\\b' instead of 'api'.", "location": {"path": "networking/services.html.markerb", "range": {"start": {"line": 28, "column": 225}}}, "severity": "ERROR"}
</div>

### Shared IPv4
Expand All @@ -48,7 +48,7 @@
```

<div class= "note icon">
If you create apps with public services in their Machine config using [`fly machine` commands](/docs/machines/flyctl/fly-machine-run/#define-a-fly-proxy-network-service) or the [Machines API](https://fly.io/docs/machines/api/), then you need to run `fly ips allocate-v4 --shared` to get a shared IPv4 address.

Check failure on line 51 in networking/services.html.markerb

View workflow job for this annotation

GitHub Actions / Vale linter 

[vale] reported by reviewdog 🐶
[Vale.Terms] Use 'IPs' instead of 'ips'.

Raw Output:
{"message": "[Vale.Terms] Use 'IPs' instead of 'ips'.", "location": {"path": "networking/services.html.markerb", "range": {"start": {"line": 51, "column": 255}}}, "severity": "ERROR"}

Check failure on line 51 in networking/services.html.markerb

View workflow job for this annotation

GitHub Actions / Vale linter 

[vale] reported by reviewdog 🐶
[Vale.Terms] Use 'APIs?\b' instead of 'api'.

Raw Output:
{"message": "[Vale.Terms] Use 'APIs?\\b' instead of 'api'.", "location": {"path": "networking/services.html.markerb", "range": {"start": {"line": 51, "column": 222}}}, "severity": "ERROR"}
</div>

### Dedicated IPv4
Expand Down Expand Up @@ -112,7 +112,7 @@

Many apps have limited HTTP support, the `http` handler normalizes HTTP connections and sends HTTP 1.1 requests to the application process. This is roughly how `nginx` and other reverse proxies work, and allows your app to globally accept modern HTTP protocols (like HTTP/2) without extra complexity.

If your application stack has good HTTP/2 support (like Go), you will get better performance accepting TCP connections directly, and using the TLS handler to terminate SSL. Your app _does_ need to understand `h2c` for this to work, however.
If your application needs HTTP/2 (like gRPC does), enable the `h2_backend` to talk directly over HTTP/2. Just make sure your app speaks `h2c` (that’s HTTP/2 without TLS), or it won’t work.

The HTTP handler adds a number of standard HTTP headers to requests, and a few Fly.io-specific headers for convenience:

Expand Down Expand Up @@ -151,7 +151,7 @@
Fly-Force-Instance-Id: instance-number
```

Configuration example in `fly.toml`:
Configuration examples in `fly.toml`:

```toml
[[services]]
Expand All @@ -162,16 +162,19 @@
force_https = true # optional
```

```toml
[http_service]
...
[http_service.http_options]
h2_backend = true
```

### TLS handler

The `tls` handler terminates TLS using Fly.io-managed application certificates, then forwards a plaintext connection to the application process. This is useful for running TCP services and offloading `TLS` to the Fly Proxy.

For performance purposes, the Fly Proxy will terminate TLS on the host a client connects to, and then forward the connection to the nearest available Machine.

<div class="note icon">
**Note:** The TLS handler includes ALPN negotiation for HTTP/2. When possible, apps will connect to these kinds of Fly.io services using HTTP/2, and we will forward an unencrypted HTTP/2 connection (`h2c`) to the application process.
</div>

Configuration examples in `fly.toml`:

```toml
Expand Down Expand Up @@ -229,7 +232,7 @@

Fly Machines have IPv6 addresses from which they make requests to the wider internet without going through the Fly Proxy.

By default, we don’t offer static IPs or regional IP ranges, and we discourage the use of our outbound IPs to bypass firewalls. A Machine's outbound IP is liable to change without notice. This shouldn't be a daily occurrence, but it will happen if a Machine is moved for whatever reason, such as a load-balancing of Fly Machines between servers in one region.

Check warning on line 235 in networking/services.html.markerb

View workflow job for this annotation

GitHub Actions / Vale linter 

[vale] reported by reviewdog 🐶
[Fly.WordList] Consider using 'firewall rules' instead of 'firewalls'.

Raw Output:
{"message": "[Fly.WordList] Consider using 'firewall rules' instead of 'firewalls'.", "location": {"path": "networking/services.html.markerb", "range": {"start": {"line": 235, "column": 118}}}, "severity": "INFO"}

If you do need a static outbound IP, you can assign one on a per-machine basis. You can allocate one to a machine with `fly machine egress-ip allocate <machine-id>. This will assign both an IPv4 and IPv6 address to the machine. Like dedicated IPv4 addresses, these are [billed](/docs/about/pricing/#static-machine-ip) monthly.

Expand Down
Loading