From e4c68d64670e619c866510d78b3ec63ebd544291 Mon Sep 17 00:00:00 2001 From: Andrea Anderson Date: Fri, 9 Aug 2024 19:03:24 -0400 Subject: [PATCH] Flycast in the spotlight, or at least its own page (#1747) * flycast in the spotlight * fix links and redirects * edits * rm --network until confirmed --- blueprints/autostart-internal-apps.html.md | 2 +- .../index.html.md | 2 +- networking/flycast.html.markerb | 62 +++++++++++++++++++ networking/index.html.markerb | 6 +- networking/private-networking.html.md | 59 +----------------- partials/_firecracker_nav.html.erb | 3 +- reference/fly-proxy.html.markerb | 2 +- 7 files changed, 74 insertions(+), 62 deletions(-) create mode 100644 networking/flycast.html.markerb diff --git a/blueprints/autostart-internal-apps.html.md b/blueprints/autostart-internal-apps.html.md index d55fb967b7..945ba98653 100644 --- a/blueprints/autostart-internal-apps.html.md +++ b/blueprints/autostart-internal-apps.html.md @@ -10,7 +10,7 @@ To use the Fly Proxy autostart and autostop feature you need to configure servic This blueprint focuses on using autostart and autostop to control Machines based on incoming requests. But when you use Flycast for private apps you also get other Fly Proxy features like geographically aware load balancing. -Learn more about [Flycast](/docs/networking/private-networking/#flycast-private-fly-proxy-services). +Learn more about [Flycast](/docs/networking/flycast/). ## Create a new private app with a Flycast address diff --git a/blueprints/connect-private-network-wireguard/index.html.md b/blueprints/connect-private-network-wireguard/index.html.md index 77533c0df2..838940feb8 100644 --- a/blueprints/connect-private-network-wireguard/index.html.md +++ b/blueprints/connect-private-network-wireguard/index.html.md @@ -11,7 +11,7 @@ date: 2024-06-14

-Every [Fly.io](http://Fly.io) organization comes with a [private network](https://fly.io/docs/networking/private-networking/) that lets all your apps connect to each other. This is super convenient when you need to have microservices call each other’s endpoints or use [Flycast](https://fly.io/docs/networking/private-networking/#flycast-private-fly-proxy-services) to let your private apps turn off when you’re not using them. However, this isn’t just limited to your apps. You can jack into this network with WireGuard. +Every [Fly.io](http://Fly.io) organization comes with a [private network](https://fly.io/docs/networking/private-networking/) that lets all your apps connect to each other. This is super convenient when you need to have microservices call each other’s endpoints or use [Flycast](/docs/networking/flycast/) to let your private apps turn off when you’re not using them. However, this isn’t just limited to your apps. You can jack into this network with WireGuard. This blueprint shows you how to create a WireGuard peer to your private network and connect to it so that you can access it from anywhere. diff --git a/networking/flycast.html.markerb b/networking/flycast.html.markerb new file mode 100644 index 0000000000..ac8a10f884 --- /dev/null +++ b/networking/flycast.html.markerb @@ -0,0 +1,62 @@ +--- +title: "Flycast - Private Fly Proxy services" +layout: docs +nav: firecracker +redirect_from: /docs/networking/private-networking/#flycast-private-fly-proxy-services +--- + +Flycast provides network addressing and routing for private apps on Fly.io private networks. With Flycast, requests to your private apps get routed through the Fly Proxy, rather than Machine-to-Machine using `.internal` addresses (the [private networking](/docs/networking/private-networking/) available by default on every app). Unlike `.internal` addresses, with a Flycast address, you don't need to keep Machines running for the app to be reachable. + +Use Flycast to do the following entirely within your organization's private network: + +* Use [Fly Proxy autostop/autostart](/docs/launch/autostart-stop/) for Machines based on network requests. +* Get Fly Proxy's [geographically aware load balancing](/docs/reference/load-balancing/) for private services. +* Connect to a service from another app that can't use DNS. +* Connect from third-party software, like a database, that doesn't support round-robin DNS entries. +* Access specific ports or services in your app from other Fly.io organizations. +* Use advanced Fly Proxy features like TLS termination or PROXY protocol support. + +## Flycast quickstart + +The basic steps to set up Flycast: + +1. Allocate a private IPv6 address for your app on one of your Fly.io organization networks. +2. Make sure your app binds to `0.0.0.0:port`. Binding to `fly-local-6pn:` won't work for Flycast. +3. Expose services in your app's `fly.toml` with an [`[http_service]`](/docs/reference/configuration/#the-http_service-section) or [`[services]`](/docs/reference/configuration/#the-services-sections) section. Don't use `force_https`; Flycast is HTTP-only. +4. Deploy your app. +5. Access the services on the private IPv6 address, or with `my-app-name.flycast`, from the target organization network. + +
+**Warning:** If you have a public IP address assigned to your app, then services in `fly.toml` are exposed to the public internet. Verify your app's IP addresses with `fly ips list`. +
+ +## Allocate a Flycast address + +A Flycast address is an app-wide private IPv6 address that the Fly Proxy can route to over the private network. By default, the Flycast IP address is allocated on an app's default organization network. + +```cmd + fly ips allocate-v6 --private + ``` + ```output +VERSION IP TYPE REGION CREATED AT +v6 fdaa:0:22b7:0:1::3 private global just now +``` + +You can use Flycast to expose an app in one Fly.io organization to another Fly.io organization by using the `--org` option when you allocate the Flycast address: + +```cmd + fly ips allocate-v6 --private --org my-other-org + ``` + ```output +VERSION IP TYPE REGION CREATED AT +v6 fdaa:0:22b7:0:1::3 private global just now +``` + +## Flycast and Fly.io DNS + +Flycast addresses can also be found by using the Fly.io DNS. If an app has a Flycast address allocated to it, there will be an AAAA record at `my-app-name.flycast`. + +## More Flycast + +- [Run private apps with Flycast](/docs/blueprints/private-applications-flycast/) +- [Autostop/autostart for private apps](/docs/blueprints/autostart-internal-apps/) \ No newline at end of file diff --git a/networking/index.html.markerb b/networking/index.html.markerb index 8cfe30c62f..16df35b2d1 100644 --- a/networking/index.html.markerb +++ b/networking/index.html.markerb @@ -9,11 +9,13 @@ order: 10 Networking on Fly.io. - **[Connect to an App Service](/docs/networking/app-services/):** An overview of how to connect to your app over the private WireGuard network (6PN), and how to make your app reachable from the internet. - -- **[Private networking](/docs/networking/private-networking):** Learn about Fly.io's IPv6 private network (6PN), DNS on Fly Machines, and how to use Flycast for load balancing and other Fly Proxy features on a private network. - **[Public networking](/docs/networking/services):** Details about public network services on Fly.io, including allocating IP addresses, finding a Machine's outbound IP, connection handlers, and redirects. +- **[Private networking](/docs/networking/private-networking):** Learn about Fly.io's IPv6 private network (6PN), DNS on Fly Machines, and how to use Flycast for load balancing and other Fly Proxy features on a private network. + +- **[Flycast - Private Fly Proxy Services](/docs/networking/flycast):** Route requests to private apps through Fly Proxy to take advantage of features like load balancing and autostop/autostart based on traffic. + - **[Dynamic request routing](/docs/networking/dynamic-request-routing/):** Use the `fly-replay` response header to route requests to other apps and regions. - **[Custom domains](/docs/networking/custom-domain/):** Add a custom domain for your app and troubleshoot certificate creation. diff --git a/networking/private-networking.html.md b/networking/private-networking.html.md index 6e4ff42b63..dc6cb720a2 100644 --- a/networking/private-networking.html.md +++ b/networking/private-networking.html.md @@ -7,17 +7,15 @@ redirect_from: - /docs/reference/private-networking/ --- -Fly Apps are connected by a mesh of WireGuard tunnels using IPv6. +Fly Apps are connected by a mesh of WireGuard tunnels using IPv6. Private networking is always available to apps by default; you don't have to do anything special to get it. Applications within the same organization are assigned special addresses (6PN addresses) tied to the organization. Those applications can talk to each other because of their 6PN addresses, but applications from other organizations can't. The Fly.io platform won't forward packets between different 6PN networks. -Private networking is always available to apps by default; you don't have to do anything special to get it. - You can connect apps running outside of Fly.io to your 6PN network using WireGuard. You can even connect your dev laptop to your 6PN network. To do that, you'll use flyctl, the Fly.io CLI, to generate a WireGuard configuration that has a 6PN address. ## Fly.io `.internal` DNS -A Fly Machine is configured to resolve domain names with a custom DNS server from the Fly Platform. This DNS server can resolve arbitrary DNS queries, so you can look up `google.com` with it. But it’s also aware of 6PN addresses, and will let you look up 6PN addresses for other apps in your organization. Those addresses live under the custom top-level domain `.internal`. You might want to use `.internal` domains to connect your app to databases, API servers, or other apps in your 6PN network. +A Fly Machine is configured to resolve domain names with a custom DNS server from the Fly Platform. This DNS server can resolve arbitrary DNS queries, so you can look up `google.com` with it. But it’s also aware of 6PN addresses, and will let you look up 6PN addresses for other apps in your organization. Those addresses live under the custom top-level domain `.internal`. You might want to use `.internal` domains to connect your app to databases, API servers, or other apps in your 6PN network. If you don't need the second-level domains available with `.internal` and you want to use of Fly Proxy features for your internal apps, then you should use [Flycast](/docs/networking/flycast/) instead. Underneath `.internal` there are second-level domains for every app in your Fly organization. For example, if your app is in an organization with another app called `my-app-name`, then there will be a AAAA record at `my-app-name.internal`. The AAAA record will contain *all* the 6PN addresses of the started Fly Machines that make up the `my-app-name` Fly App. Note that different libraries and tools will use multi-address AAAA records differently; most will only use the first address that is returned, but others might round-robin between entries for every request -- if you'd like to know more, consult the documentation for the library or tool you are using for DNS lookup. @@ -81,7 +79,7 @@ In uncommon circumstances, such as having an unusual file system layout, or usin In most cases, connecting to other Machines via the `.internal` DNS is the most convenient and accessible way to connect your Fly Apps and Machines.
-**Note:** 6PN addresses directly connect one Fly Machine with another, bypassing the Fly Proxy. To use Fly Proxy features like auto start and stop on your private network, you can use a [Flycast address](#flycast---private-fly-proxy-services). +**Note:** 6PN addresses directly connect one Fly Machine with another, bypassing the Fly Proxy. To use Fly Proxy features like autostop/autostart on your private network, you can use [Flycast](/docs/networking/flycast/).
Most of the time, the `.internal` DNS is all you'll need for routing. If you need more complicated routing, you might be able to take advantage of the structure of 6PN addresses in your app's design. Rather than a single address, each Fly Machine is assigned a `/112` 6PN subnet, which is structured as follows: @@ -99,57 +97,6 @@ Most of the time, the `.internal` DNS is all you'll need for routing. If you nee The machine identifier portion of the 6PN address is not related to the 14 character Machine ID; the two are independent. A Fly Machine's current 6PN address can be found in the environment variable `FLY_PRIVATE_IP`. As noted above, a Machine's 6PN address is not static, so do not assume that a Fly Machine's Machine ID can be permanently mapped to a particular 6PN address. 6PN addresses will change when an app is moved into a new Fly Org, or when a Fly Machine is migrated onto a new host server. However, an 6PN address change can only happen on a reboot, so supplying a procedure to check for a change in 6PN address on Machine startup is sufficient to handle this event. -## Flycast - Private Fly Proxy services - -A Flycast address is an app-wide IPv6 address that the Fly Proxy can route to privately. Use a Flycast address to direct private network traffic through the Fly Proxy to take advantage of features like geographically aware load balancing and autostart/autostop based on traffic. - -Use Flycast to do the following entirely within your organization's private network: - -* [Autostart and/or autostop](/docs/launch/autostart-stop/) Machines based on network requests. -* Use Fly Proxy's [geographically aware load balancing](/docs/reference/load-balancing/) for private services. -* Connect to a service from another app that can't use DNS. -* Connect from third-party software, like a database, that doesn't support round-robin DNS entries. -* Access specific ports or services in your app from other Fly.io organizations. -* Use advanced proxy features like TLS termination or PROXY protocol support. - -The general flow for setting up Flycast is: - -1. Allocate a private IPv6 address for your app on one of your Fly.io organization networks. -2. Make sure your app binds to `0.0.0.0:port`. **Binding to `fly-local-6pn:` is insufficient for Flycast.** -3. Expose services in your app's `fly.toml` `[services]` or `[http_service]` block; **do not use `force_https` as Flycast is HTTP-only**. -4. Deploy your app. -5. Access the services on the private IP from the target organization network. - -
-**Warning:** If you have a public IP address assigned to your app, then services in `fly.toml` are exposed to the public internet. Verify your app's IP addresses with `fly ips list`. -
- -### Assign a Flycast address - -By default, the Flycast IP address is allocated on an app's parent organization network. - -```cmd - fly ips allocate-v6 --private - ``` - ```output -VERSION IP TYPE REGION CREATED AT -v6 fdaa:0:22b7:0:1::3 private global just now -``` - -You can also use Flycast to expose an app in one Fly organization to another Fly organization by using the `--org` option when you allocate the Flycast address: - -```cmd - fly ips allocate-v6 --private --org my-other-org - ``` - ```output -VERSION IP TYPE REGION CREATED AT -v6 fdaa:0:22b7:0:1::3 private global just now -``` - -### Flycast and Fly.io DNS - -Flycast addresses can also be found by using the Fly.io DNS. If an app has a Flycast address allocated to it, there will be an AAAA record at `.flycast`. - ## Private Network VPN You can use the [WireGuard](https://wireguard.com/+external) VPN to connect to the 6PN private network. WireGuard is a flexible and secure way to plug into each one of your Fly.io organizations and connect to any app within that organization. diff --git a/partials/_firecracker_nav.html.erb b/partials/_firecracker_nav.html.erb index 33e6c789a1..7c21fe2708 100644 --- a/partials/_firecracker_nav.html.erb +++ b/partials/_firecracker_nav.html.erb @@ -123,8 +123,9 @@ open: false, links: [ { text: "Connect to an App Service", path: "/docs/networking/app-services/" }, - { text: "Private Networking", path: "/docs/networking/private-networking/" }, { text: "Public Networking", path: "/docs/networking/services/" }, + { text: "Private Networking", path: "/docs/networking/private-networking/" }, + { text: "Flycast - Private Proxy Services", path: "/docs/networking/flycast/" }, { text: "Dynamic Request Routing", path: "/docs/networking/dynamic-request-routing/" }, { text: "Custom Domains", path: "/docs/networking/custom-domain/" }, { text: "Automate Certificates via API", path: "/docs/networking/custom-domain-api/" }, diff --git a/reference/fly-proxy.html.markerb b/reference/fly-proxy.html.markerb index ea40034a8c..f2a21c6fb8 100644 --- a/reference/fly-proxy.html.markerb +++ b/reference/fly-proxy.html.markerb @@ -27,7 +27,7 @@ Fly Proxy gets all its information about apps and Machines and services from cor ## How Fly Proxy routes requests over your private network (6PN) -Apps can communicate with each other by default on your [private network](/docs/networking/private-networking/) without Fly Proxy's help, but if you want to use Fly Proxy features, then you can do that with [Flycast](/docs/networking/private-networking/#flycast-private-fly-proxy-services). +Apps can communicate with each other by default on your [private network](/docs/networking/private-networking/) without Fly Proxy's help, but if you want to use Fly Proxy features, then you can do that with [Flycast](/docs/networking/flycast/). When you assign a Flycast address to your app, the traffic gets routed through Fly Proxy while remaining entirely in your private network. When App 1 makes a request to App 2 in the same private network, Fly Proxy on the worker hosting App 1's Machines checks out the details of the request, adds the appropriate headers, and routes the request through the same WireGuard tunnel backhaul to the nearest healthy worker that hosts Machines for App 2. Fly Proxy on that server sends the request to a Machine running App 2.