From c65e0008b0aae6e1b7ac33e24ce9a5510b350dde Mon Sep 17 00:00:00 2001 From: Uyloal Date: Fri, 10 Apr 2026 11:11:34 +0800 Subject: [PATCH] feat: Update Headscale template to v0.28.0 - Headscale: 0.24.1-debug -> 0.28.0-debug - Headplane: 0.3.9 -> 0.6.2 - Fix hardcoded server_url to use dynamic variable - Add new v0.28.0 configuration options (database, DERP, DNS, OIDC, taildrop) - Update documentation references and comments --- template/headscale/index.yaml | 183 +++++++++++++++++++++++++--------- 1 file changed, 135 insertions(+), 48 deletions(-) diff --git a/template/headscale/index.yaml b/template/headscale/index.yaml index c28c28d..cd009ac 100644 --- a/template/headscale/index.yaml +++ b/template/headscale/index.yaml @@ -67,7 +67,7 @@ kind: StatefulSet metadata: name: headscale-${{ defaults.app_suffix }} annotations: - originImageName: headscale/headscale:0.24.1-debug + originImageName: headscale/headscale:0.28.0-debug deploy.run.claw.cloud/minReplicas: '1' deploy.run.claw.cloud/maxReplicas: '1' labels: @@ -103,7 +103,7 @@ spec: subPath: ./tmp/config.yaml containers: - name: headscale-${{ defaults.app_suffix }} - image: headscale/headscale:0.24.1-debug + image: headscale/headscale:0.28.0-debug command: ["headscale", "serve"] resources: requests: @@ -135,7 +135,7 @@ spec: timeoutSeconds: 5 periodSeconds: 15 - name: headscale-headplane-${{ defaults.app_suffix }} - image: ghcr.io/tale/headplane:0.3.9 + image: ghcr.io/tale/headplane:0.6.2 env: - name: COOKIE_SECRET value: 'abcdefghijklmnopqrstuvwxyz' @@ -259,7 +259,7 @@ data: # # https://myheadscale.example.com:443 # - server_url: https://headscale-rewcdzwp.clawcloudhzh.site + server_url: https://headscale-${{ defaults.app_suffix }}.${{ CLAWCLOUD_CLOUD_DOMAIN }} # Address to listen to / bind to on the server # @@ -267,10 +267,9 @@ data: # listen_addr: 0.0.0.0:8080 listen_addr: 0.0.0.0:8080 - # Address to listen to /metrics, you may want - # to keep this endpoint private to your internal - # network - # + # Address to listen to /metrics and /debug, you may want + # to keep this endpoint private to your internal network + # Use an emty value to disable the metrics listener. metrics_listen_addr: 0.0.0.0:9090 # Address to listen for gRPC. @@ -292,9 +291,9 @@ data: # The Noise section includes specific configuration for the # TS2021 Noise protocol noise: - # The Noise private key is used to encrypt the - # traffic between headscale and Tailscale clients when - # using the new Noise-based protocol. + # The Noise private key is used to encrypt the traffic between headscale and + # Tailscale clients when using the new Noise-based protocol. A missing key + # will be automatically generated. private_key_path: /var/lib/headscale/noise_private.key # List of IP prefixes to allocate tailaddresses from. @@ -311,7 +310,9 @@ data: v4: 100.64.0.0/10 # Strategy used for allocation of IPs to nodes, available options: - # - sequential (default): assigns the next free IP from the previous given IP. + # - sequential (default): assigns the next free IP from the previous given + # IP. A best-effort approach is used and Headscale might leave holes in the + # IP range or fill up existing holes in the IP range. # - random: assigns the next free IP from a pseudo-random IP generator (crypto/rand). allocation: sequential @@ -335,7 +336,10 @@ data: # Region code and name are displayed in the Tailscale UI to identify a DERP region region_code: "headscale" region_name: "Headscale Embedded DERP" - + + # Only allow clients associated with this server access + verify_clients: true + # Listens over UDP at the configured address for STUN connections - to help with NAT traversal. # When the embedded DERP server is enabled stun_listen_addr MUST be defined. # @@ -355,8 +359,8 @@ data: # For better connection stability (especially when using an Exit-Node and DNS is not working), # it is possible to optionally add the public IPv4 and IPv6 address to the Derp-Map using: - ipv4: 1.2.3.4 - ipv6: 2001:db8::1 + # ipv4: 1.2.3.4 + # ipv6: 2001:db8::1 # List of externally available DERP maps encoded in JSON urls: @@ -379,7 +383,7 @@ data: auto_update_enabled: true # How often should we check for DERP updates? - update_frequency: 24h + update_frequency: 3h # Disables the automatic check for headscale updates on startup disable_check_updates: false @@ -388,17 +392,44 @@ data: ephemeral_node_inactivity_timeout: 30m database: + # Database type. Available options: sqlite, postgres + # Please note that using Postgres is highly discouraged as it is only supported for legacy reasons. + # All new development, testing and optimisations are done with SQLite in mind. type: sqlite - + + # Enable debug mode. This setting requires the log.level to be set to "debug" or "trace". + debug: false + + # GORM configuration settings. + gorm: + # Enable prepared statements. + prepare_stmt: true + + # Enable parameterized queries. + parameterized_queries: true + + # Skip logging "record not found" errors. + skip_err_record_not_found: true + + # Threshold for slow queries in milliseconds. + slow_threshold: 1000 + # SQLite config sqlite: path: /var/lib/headscale/db.sqlite - + # Enable WAL mode for SQLite. This is recommended for production environments. # https://www.sqlite.org/wal.html write_ahead_log: true + + # Maximum number of WAL file frames before the WAL file is automatically checkpointed. + # https://www.sqlite.org/c3ref/wal_autocheckpoint.html + # Set to 0 to disable automatic checkpointing. + wal_autocheckpoint: 1000 # # Postgres config + # Please note that using Postgres is highly discouraged as it is only supported for legacy reasons. + # See database.type for more information. # postgres: # # If using a Unix socket to connect to Postgres, set the socket path in the 'host' field and leave 'port' blank. # host: localhost @@ -437,7 +468,7 @@ data: # Type of ACME challenge to use, currently supported types: # HTTP-01 or TLS-ALPN-01 - # See [docs/tls.md](docs/tls.md) for more information + # See: docs/ref/tls.md for more information tls_letsencrypt_challenge_type: HTTP-01 # When HTTP-01 challenge is chosen, letsencrypt must set up a # verification endpoint, and it will be listening on: @@ -449,9 +480,11 @@ data: tls_key_path: "" log: + # Valid log levels: panic, fatal, error, warn, info, debug, trace + level: info + # Output formatting for logs: text or json format: text - level: info ## Policy # headscale supports Tailscale's ACL policies. @@ -489,7 +522,11 @@ data: dns: # Whether to use [MagicDNS](https://tailscale.com/kb/1081/magicdns/). magic_dns: true - + + # Whether to use the local DNS settings of a node or override the local DNS + # settings (default) and force the use of Headscale's DNS configuration. + override_local_dns: true + # Defines the base domain to create the hostnames for MagicDNS. # This domain _must_ be different from the server_url domain. # `base_domain` must be a FQDN, without the trailing dot. @@ -543,70 +580,120 @@ data: unix_socket: /var/run/headscale/headscale.sock unix_socket_permission: "0770" # - # headscale supports experimental OpenID connect support, - # it is still being tested and might have some bugs, please - # help us test it. # OpenID Connect # oidc: + # # Block startup until the identity provider is available and healthy. # only_start_if_oidc_is_available: true + # + # # OpenID Connect Issuer URL from the identity provider # issuer: "https://your-oidc.issuer.com/path" + # + # # Client ID from the identity provider # client_id: "your-oidc-client-id" + # + # # Client secret generated by the identity provider + # # Note: client_secret and client_secret_path are mutually exclusive. # client_secret: "your-oidc-client-secret" # # Alternatively, set `client_secret_path` to read the secret from the file. # # It resolves environment variables, making integration to systemd's # # `LoadCredential` straightforward: - # client_secret_path: "${CREDENTIALS_DIRECTORY}/oidc_client_secret" - # # client_secret and client_secret_path are mutually exclusive. + # # client_secret_path: "${CREDENTIALS_DIRECTORY}/oidc_client_secret" # - # # The amount of time from a node is authenticated with OpenID until it - # # expires and needs to reauthenticate. + # # The amount of time a node is authenticated with OpenID until it expires + # # and needs to reauthenticate. # # Setting the value to "0" will mean no expiry. # expiry: 180d # # # Use the expiry from the token received from OpenID when the user logged - # # in, this will typically lead to frequent need to reauthenticate and should - # # only been enabled if you know what you are doing. + # # in. This will typically lead to frequent need to reauthenticate and should + # # only be enabled if you know what you are doing. # # Note: enabling this will cause `oidc.expiry` to be ignored. # use_expiry_from_token: false # - # # Customize the scopes used in the OIDC flow, defaults to "openid", "profile" and "email" and add custom query - # # parameters to the Authorize Endpoint request. Scopes default to "openid", "profile" and "email". + # # The OIDC scopes to use, defaults to "openid", "profile" and "email". + # # Custom scopes can be configured as needed, be sure to always include the + # # required "openid" scope. + # scope: ["openid", "profile", "email"] + # + # # Only verified email addresses are synchronized to the user profile by + # # default. Unverified emails may be allowed in case an identity provider + # # does not send the "email_verified: true" claim or email verification is + # # not required. + # email_verified_required: true # - # scope: ["openid", "profile", "email", "custom"] + # # Provide custom key/value pairs which get sent to the identity provider's + # # authorization endpoint. # extra_params: # domain_hint: example.com # - # # List allowed principal domains and/or users. If an authenticated user's domain is not in this list, the - # # authentication request will be rejected. - # + # # Only accept users whose email domain is part of the allowed_domains list. # allowed_domains: # - example.com - # # Note: Groups from keycloak have a leading '/' - # allowed_groups: - # - /headscale + # + # # Only accept users whose email address is part of the allowed_users list. # allowed_users: # - alice@example.com # - # # If `strip_email_domain` is set to `true`, the domain part of the username email address will be removed. - # # This will transform `first-name.last-name@example.com` to the user `first-name.last-name` - # # If `strip_email_domain` is set to `false` the domain part will NOT be removed resulting to the following - # user: `first-name.last-name.example.com` + # # Only accept users which are members of at least one group in the + # # allowed_groups list. + # allowed_groups: + # - /headscale # + # # If `strip_email_domain` is set to `true`, the domain part of the username email address will be + # # removed. This will transform `first-name.last-name@example.com` to the user `first-name.last-name` + # # If `strip_email_domain` is set to `false` the domain part will NOT be removed resulting to the + # # following user: `first-name.last-name.example.com` # strip_email_domain: true + # + # # Optional: PKCE (Proof Key for Code Exchange) configuration + # # PKCE adds an additional layer of security to the OAuth 2.0 authorization code flow + # # by preventing authorization code interception attacks + # # See https://datatracker.ietf.org/doc/html/rfc7636 + # pkce: + # # Enable or disable PKCE support (default: false) + # enabled: false + # + # # PKCE method to use: + # # - plain: Use plain code verifier + # # - S256: Use SHA256 hashed code verifier (default, recommended) + # method: S256 # Logtail configuration - # Logtail is Tailscales logging and auditing infrastructure, it allows the control panel - # to instruct tailscale nodes to log their activity to a remote server. + # Logtail is Tailscales logging and auditing infrastructure, it allows the + # control panel to instruct tailscale nodes to log their activity to a remote + # server. To disable logging on the client side, please refer to: + # https://tailscale.com/kb/1011/log-mesh-traffic#opting-out-of-client-logging logtail: - # Enable logtail for this headscales clients. - # As there is currently no support for overriding the log server in headscale, this is + # Enable logtail for tailscale nodes of this Headscale instance. + # As there is currently no support for overriding the log server in Headscale, this is # disabled by default. Enabling this will make your clients send logs to Tailscale Inc. enabled: false - + # Enabling this option makes devices prefer a random port for WireGuard traffic over the # default static port 41641. This option is intended as a workaround for some buggy # firewall devices. See https://tailscale.com/kb/1181/firewalls/ for more information. randomize_client_port: false + + # Taildrop configuration + # Taildrop is the file sharing feature of Tailscale, allowing nodes to send files to each other. + # https://tailscale.com/kb/1106/taildrop/ + taildrop: + # Enable or disable Taildrop for all nodes. + # When enabled, nodes can send files to other nodes owned by the same user. + # Tagged devices and cross-user transfers are not permitted by Tailscale clients. + enabled: true + + # Advanced performance tuning parameters. + # The defaults are carefully chosen and should rarely need adjustment. + # Only modify these if you have identified a specific performance issue. + # + # tuning: + # # NodeStore write batching configuration. + # # The NodeStore batches write operations before rebuilding peer relationships, + # # which is computationally expensive. Batching reduces rebuild frequency. + # # + # # node_store_batch_size: 100 + # # node_store_batch_timeout: 500ms vn-etcvn-headscalevn-derpvn-yaml: |- regions: