Merge pull request #3219 from balena-io/rahul/cloudlink-guidance

Add guidance for features enabled by cloudlink

Author: flowzone-app[bot]

pages/learn/manage/actions.md

@@ -66,6 +66,10 @@ The `Delete Device` action is an extremely dangerous action and results in disas
 
 {{ $names.company.upper }} currently exposes **port 80** for web forwarding. This setting enables web forwarding and generates a web accessible url for any applicable devices. The URLs will be of the form `<{{ $names.company.allCaps }}_DEVICE_UUID>.balena-devices.com`, where `<{{ $names.company.allCaps }}_DEVICE_UUID>` is the unique ID of the device which you can see on your dashboard. Currently only HTTP traffic (level 7 OSI traffic) is supported via the device URLs.
 
+The Public Device URL feature is a tool for remote configuration, debugging, and other intermittent or periodic use cases. The feature is built on [Cloudlink](/learn/welcome/security/#cloudlink) and not designed for high availability. We do not recommend using the Public Device URL feature for continuous use as part of your application.
+
+For applications that require a stable, continuously available public endpoint, we recommend using a dedicated tunneling service designed for production use. Popular services include [Cloudflare Tunnels][cloudflare-tunnel](See our [blog post][cloudflare-tunnel-blog-post]), [Tailscale](https://tailscale.com/) and [Ngrok](https://ngrok.com/).
+
 <img alt="Toggle public device URL" src="/img/common/settings/toggle-public-url.webp">
 
 To see what your device is serving on port 80, click on the [public URL][public-url]. If no service inside your app is serving anything on port 80 or your webserver on the device crashes, you should see something like this:
@@ -188,3 +192,5 @@ __Info:__ If you have a device [preloaded][preload-devices] with an OS version l
 [fleet-members]:/learn/accounts/fleet-members
 [docker-data-persistence-strategies]:https://docs.docker.com/storage/
 [public-url]:/learn/develop/runtime/#public-device-urls
+[cloudflare-tunnel]:https://www.cloudflare.com/products/tunnel/
+[cloudlare-tunnel-blog-post]:https://www.balena.io/blog/expose-your-balena-device-to-the-internet-with-cloudflare-tunnel/

pages/learn/manage/device-statuses.md

@@ -31,7 +31,7 @@ The balena device uses two mechanisms to maintain communication with balenaCloud
 
 - **Cloudlink available, but heartbeat not**: The device is unable to communicate with the {{ $names.cloud.lower }} API. A device with cloudlink only is not able to apply any new changes made such as deploying new releases, applying service configuration values, or switching to local mode. However, since cloudlink is available, the device is accessible via SSH or the web terminal. When a device exhibits this state, the first troubleshooting step is to [run a healthcheck](https://docs.balena.io/reference/diagnostics/#device-health-checks) and pull [device diagnostics](https://docs.balena.io/reference/diagnostics/#device-diagnostics). This should help determine the reason the supervisor is not communicating with the balenaCloud backend.
 
-- **Heartbeat available, but cloudlink not**: The device is unable to connect to cloudlink (e.g. a firewall is blocking VPN traffic), and terminal access to the device is thus unavailable. A device with Heartbeat Only status has internet connectivity, is able to reach the API, and can poll the cloud for new updates to apply, but actions that take immediate effect, such as purging data, restarting services, rebooting or shutting down, will not be available as they are performed via cloudlink.
+- **Heartbeat available, but Cloudlink not**: The device is unable to connect to Cloudlink (e.g. a firewall is blocking VPN traffic). [Features enabled by Cloudlink][cloudlink] such as [SSH access][ssh-access] will not be available. A device with Heartbeat Only status has internet connectivity, is able to reach the API, and can poll the cloud for new updates to apply, but actions that take immediate effect, such as purging data, restarting services, rebooting or shutting down, will not be available as they are performed via Cloudlink.
 
 __Note:__ If the device is powered off or loses all network connectivity, the `heartbeat` indicator will show as connected (green) until enough time has passed to cover the device [API polling interval][poll-interval], at which time it will be marked as `Disconnected`.
 
@@ -73,3 +73,4 @@ If you find your device to be displaying a status which is unclear even with the
 [debugging-masterclass]:/learn/more/masterclasses/device-debugging
 [cloudlink]:/learn/welcome/security/#cloudlink
 [bandwidth-reduction]:/reference/supervisor/bandwidth-reduction/#side-effects--warnings
+[ssh-access]:/learn/manage/ssh-access/

pages/learn/welcome/security.md

@@ -55,15 +55,23 @@ Both the Docker pull request and the actual image download process are performed
 
 ### Cloudlink
 
-{{ $names.company.upper }} uses Cloudlink to control the device state (e.g. device reboot, device shutdown, service(s) restart, etc.). Currently, Cloudlink uses [OpenVPN](https://openvpn.net/) as an underlying technology to achieve these things but this is subject to change with better technology, this is why we abstract away from the technology and call the component as Cloudlink. As mentioned above, devices only connect outbound to the Cloudlink and all traffic over the Cloudlink is encrypted with TLS.
+Cloudlink status in the dashboard represents a device connection to the {{ $names.cloud.lower }} backend. This connection is the underlying technology that enables the following functionalities within {{ $names.cloud.lower }}, and as such we indicate the status of Cloudlink to help you to understand the status of your device and what functionality may or may not be available.
 
-When Cloudlink is enabled, SSH access is available to the service using the {{ $names.company.lower }} dashboard or the CLI.
+- [SSH access](/learn/manage/ssh-access/) via CLI or web terminal
+- [Public Device Url](/learn/manage/actions/#public-device-url)
+- [Device actions](/learn/manage/actions/#device-actions) that allow controlling device state
+- [Host OS Updates](/reference/OS/updates/self-service/)
+- [Device Diagnostics](/reference/diagnostics/)
+
+Currently, Cloudlink uses [OpenVPN](https://openvpn.net/) as an underlying technology to achieve its functionality. Devices only connect outbound to Cloudlink, and all traffic over Cloudlink is encrypted with TLS.
 
 Cloudlink disallows device-to-device traffic and prohibits outbound traffic to the Internet.  If a device were compromised, this ensures that it cannot contaminate another device. To achieve this the Cloudlink service is configured to run with iptables default `FORWARD` policy set to `DROP` and we do not enable OpenVPN [--client-to-client](https://www.mankier.com/8/openvpn#--client-to-client) config option server side, so there is no way for the traffic between clients to traverse the interface(s).
 
 Currently, authentication against Cloudlink is performed with API token authentication.  API keys can be managed and revoked in the {{ $names.company.lower }} dashboard.
 
-This Cloudlink connection is optional and [can be disabled](/reference/supervisor/bandwidth-reduction/) to conserve bandwidth or to remove the option of outside device control through the {{ $names.company.lower }} dashboard or API.  When disabled, the Cloudlink connection is not established from the device and no traffic will be transmitted or received through this channel.  If desired, the Cloudlink can be enabled and disabled programmatically so that it is turned on only when in active use (e.g. for interactive debugging) and disabled normally.
+Cloudlink connection is optional and [can be disabled](/reference/supervisor/bandwidth-reduction/) to conserve bandwidth or to remove the option of outside device control through the {{ $names.cloud.lower }} dashboard or API.  When disabled, the Cloudlink connection will not be established from the device. No traffic will be transmitted or received through this channel.  If desired, Cloudlink can be enabled and disabled programmatically so that it is turned on only when in active use (e.g. for interactive debugging) and disabled normally.
+
+It is important to understand that due to its current design, Cloudlink is not architected for high availability. Cloudlink will periodically drop connections momentarily due to re-configuration or scaling, but it reconnects with the device automatically. For mission-critical workflows, we recommend designing your solution to be resilient to the potential brief unavailability of these specific interactive features. Furthermore, to protect overall platform stability for all users, devices that send/receive large amounts of data via Cloudlink continuously may be throttled. 
 
 ### Support access
 

pages/reference/supervisor/bandwidth-reduction.md

@@ -31,11 +31,7 @@ The Network Metrics Logger is a generic, client-side tool to measure bandwidth.
 
 ## Side Effects / Warnings
 
-**Cloudlink:** Allows the device to be notified instantly of state changes. Turning off Cloudlink has several consequences:
-
-- CLI access via the web terminal or SSH is disabled.
-- Updates to configuration, environment variables, and other states are not picked up by the device immediately; instead, they are delayed until the next time the device polls the API.
-- The Device Public URL feature is not available.
+**Cloudlink:** Allows the device to be notified instantly of state changes. Turning off Cloudlink disables [certain functionality](/learn/welcome/security/#cloudlink). Also, updates to configuration, environment variables, and other states are not picked up by the device immediately; instead, they are delayed until the next time the device polls the API.
 
 You can re-enable Cloudlink via the dashboard after turning it off. The device will re-establish the link the next time it polls the API, as defined by the poll interval.
 

shared/general/container-ssh.md

@@ -2,6 +2,8 @@ To help you debug, develop, and work with your fleets, we've provided a browser-
 
 __Note:__ Host OS SSH access is available for devices running {{ $names.os.lower }} version 2.7.5 and above.
 
+SSH access is built on [Cloudlink](/learn/welcome/security/#cloudlink) and it not designed for high availability. It is not intended for use in the critical path of your application - you should not depend on it for continuous use as part of your own application.
+
 ## Using the dashboard web terminal
 
 To use this feature, navigate to your fleet and select the device you want to access. You will see a *Terminal* window below the *Logs* window: