From 309c9026bb566e9b3d973276cf3821fa26b7788b Mon Sep 17 00:00:00 2001
From: Niklas Rosenstein <rosensteinniklas@gmail.com>
Date: Sun, 13 Oct 2024 21:39:44 +0200
Subject: [PATCH] feature: expose Headscale gRPC service

---
 README.md                             | 24 ++++++++++++++++++++++++
 fly.example.toml                      |  9 +++++++++
 headscale-fly-io/config.template.yaml |  7 ++-----
 3 files changed, 35 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 2869de0..6d07cc1 100644
--- a/README.md
+++ b/README.md
@@ -31,6 +31,8 @@ __Contents__
 * [Admitting machines to the network](#admitting-machines-to-the-network)
 * [Updates](#updates)
 * [Advanced configuration and usage](#advanced-configuration-and-usage)
+  * [Remote control Headscale via the CLI](#remote-control-headscale-via-the-cli)
+  * [Using ACLs](#using-acls)
   * [Configuring OIDC](#configuring-oidc)
   * [Using a custom domain](#using-a-custom-domain)
   * [Highly available Headscale deployment](#highly-available-headscale-deployment)
@@ -106,6 +108,28 @@ Simply run `fly deploy` after updating the `[build.image]`. Note that there will
 
 ## Advanced configuration and usage
 
+### Remote control Headscale via the CLI
+
+We expose the gRPC endpoint that allows you to remote-control Headscale via the CLI automatically. You need to generate
+API key via SSH before you can connect remotely:
+
+    $ fly ssh console
+    ssh > headscale apikeys create --expiration 90d
+
+Then, locally, make sure you have the same version of the Headscale CLI installed that is running on your Fly.io app
+and follow [as documented](https://headscale.net/ref/remote-cli/?h=api#download-and-configure-headscale). We use the
+same typical gRPC port (`50443`).
+
+    $ export HEADSCALE_CLI_ADDRESS=${FLY_APP_NAME}.fly.dev:50443
+    $ export HEADSCALE_CLI_API_KEY=...
+    $ headscale node list
+
+### Using ACLs
+
+We configure Headscale to store the ACL in the database instead of from file, this allows updating the ACLs without
+a `fly deploy` on every update. Follow the above steps to remote-control the Headscale server and then use the
+`headscale policy get` and `headscale policy set` commands.
+
 ### Configuring OIDC
 
 To enable OIDC, you must at the minimum provide the following environment variables:
diff --git a/fly.example.toml b/fly.example.toml
index b6c5f51..e2c549b 100644
--- a/fly.example.toml
+++ b/fly.example.toml
@@ -25,6 +25,15 @@ swap_size_mb = 128
     timeout = "5s"
     path = "/health"
 
+[[services]]
+  internal_port = 50443
+  protocol = "tcp"
+  [[services.ports]]
+    handlers = ["tls"]
+    port = "50443"
+  [services.ports.tls_options]
+    alpn = ["h2"]
+
 [[metrics]]
   port = 8081
   path = "/metrics"
diff --git a/headscale-fly-io/config.template.yaml b/headscale-fly-io/config.template.yaml
index 4ae7089..c95df9f 100644
--- a/headscale-fly-io/config.template.yaml
+++ b/headscale-fly-io/config.template.yaml
@@ -1,11 +1,8 @@
 server_url: https://${HEADSCALE_DOMAIN_NAME}
 listen_addr: 0.0.0.0:8080
 metrics_listen_addr: 0.0.0.0:8081
-
-# TODO: Expose GRPC API? So that it can be accessed with the headscale CLI
-#       externally, see https://github.com/juanfont/headscale/blob/main/docs/remote-cli.md
-# grpc_listen_addr: 0.0.0.0:8081
-# grpc_allow_insecure: true
+grpc_listen_addr: 0.0.0.0:50443
+grpc_allow_insecure: true # We use Fly.io's TLS termination.
 
 ephemeral_node_inactivity_timeout: ${HEADSCALE_EPHEMERAL_NODE_INACTIVITY_TIMEOUT}