starred/headscale
1
0
Fork 0
mirror of https://github.com/juanfont/headscale.git synced 2026-01-11 20:00:28 +01:00
Code Issues 98 Packages Projects Releases 10 Wiki Activity

[Feature] healthcheck command #873

New Issue
Closed
opened 2025-12-29 02:25:06 +01:00 by adam · 9 comments
adam commented 2025-12-29 02:25:06 +01:00
Owner
Copy Link

Originally created by @LucaRickli on GitHub (Dec 9, 2024).

Use case

Docker HEALTHCHECK

Description

Headscale does not come with a (easy) way of checking health using only the CLI. This is especially painful when running Headscale inside a docker container

Contribution

  • I can write the design doc for this feature
  • I can contribute this feature

How can it be implemented?

Should be pretty simple as it could tie into the already existing /health endpoint

Originally created by @LucaRickli on GitHub (Dec 9, 2024). ### Use case Docker HEALTHCHECK ### Description Headscale does not come with a (easy) way of checking health using only the CLI. This is especially painful when running Headscale inside a docker container ### Contribution - [X] I can write the design doc for this feature - [X] I can contribute this feature ### How can it be implemented? Should be pretty simple as it could tie into the already existing `/health` endpoint
adam added the enhancementhelp wantedgood first issueno-stale-bot labels 2025-12-29 02:25:06 +01:00
adam closed this issue 2025-12-29 02:25:06 +01:00
adam commented 2025-12-29 02:25:06 +01:00
Author
Owner
Copy Link

@kradalby commented on GitHub (Dec 10, 2024):

Can't you just use curl?

@kradalby commented on GitHub (Dec 10, 2024): Can't you just use curl?
adam commented 2025-12-29 02:25:07 +01:00
Author
Owner
Copy Link

@LucaRickli commented on GitHub (Dec 10, 2024):

Can't you just use curl?

@kradalby Unfortunately not an option for some Environments. For example: inside the provided distroless Docker container (non debug) there is no curl nor shell.

@LucaRickli commented on GitHub (Dec 10, 2024): > Can't you just use curl? @kradalby Unfortunately not an option for some Environments. For example: inside the provided distroless Docker container (non debug) there is no curl nor shell.
adam commented 2025-12-29 02:25:07 +01:00
Author
Owner
Copy Link

@kradalby commented on GitHub (Dec 11, 2024):

fair enough, I wont prioritise this but sounds like a good issue for someone who wants to help out.

If this is implemented, it needs to be added to the API, and if we do that, we should probably remove the old endpoint and only use the API one for other uses.

Alternatively, the CLI can not use the gRPC API at all and just call the endpoint that currently exists. The downside of that is that you dont get to verify that the gRPC stack works, so I would prefer the first option.

@kradalby commented on GitHub (Dec 11, 2024): fair enough, I wont prioritise this but sounds like a good issue for someone who wants to help out. If this is implemented, it needs to be added to the API, and if we do that, we should probably remove the old endpoint and only use the API one for other uses. Alternatively, the CLI can not use the gRPC API at all and just call the endpoint that currently exists. The downside of that is that you dont get to verify that the gRPC stack works, so I would prefer the first option.
adam commented 2025-12-29 02:25:07 +01:00
Author
Owner
Copy Link

@mikelococo commented on GitHub (Jan 5, 2025):

As a workaround for end-users, bash at least is included in docker.io/headscale/headscale:0.22.3. This enables using /dev/tcp to check if the API port is open via something like (assuming you're using the default API port): bash -c 'cat < /dev/null > /dev/tcp/localhost/8080'. See https://medium.com/@stefanos.kalandaridis/bash-ing-your-network-f7069ab7c5f4 for a decent primer on how it works.

This is among the weakest of healthcheck options in that it simply verifies that SOMETHING is able to accept a tcp connection on the API port. It says nothing about the health of the gRPC stack or any in-memory or on-disk state. It also says nothing about DERP, which could maybe be interrogated via /dev/udp but doing so requires knowing a valid message to send that will elicit a response and not leak resources along the way. I haven't configured a derp check myself.

This isn't a high-quality replacement for the stronger checks proposed in other comments... but it's start that allows monitoring frameworks to check that the API is at least healthy enough to complete a 3-way TCP handshake in image-flavors that have bash available.

@mikelococo commented on GitHub (Jan 5, 2025): As a workaround for end-users, bash at least is included in `docker.io/headscale/headscale:0.22.3`. This enables using `/dev/tcp` to check if the API port is open via something like (assuming you're using the default API port): `bash -c 'cat < /dev/null > /dev/tcp/localhost/8080'`. See https://medium.com/@stefanos.kalandaridis/bash-ing-your-network-f7069ab7c5f4 for a decent primer on how it works. This is among the weakest of healthcheck options in that it simply verifies that SOMETHING is able to accept a tcp connection on the API port. It says nothing about the health of the gRPC stack or any in-memory or on-disk state. It also says nothing about DERP, which could maybe be interrogated via `/dev/udp` but doing so requires knowing a valid message to send that will elicit a response and not leak resources along the way. I haven't configured a derp check myself. This isn't a high-quality replacement for the stronger checks proposed in other comments... but it's start that allows monitoring frameworks to check that the API is at least healthy enough to complete a 3-way TCP handshake in image-flavors that have bash available.
adam commented 2025-12-29 02:25:07 +01:00
Author
Owner
Copy Link

@Enissay commented on GitHub (Mar 30, 2025):

This enables using /dev/tcp to check if the API port is open via something like (assuming you're using the default API port): bash -c 'cat < /dev/null > /dev/tcp/localhost/8080'

No bash nor sh in headscale/headscale:v0.25

@Enissay commented on GitHub (Mar 30, 2025): > This enables using /dev/tcp to check if the API port is open via something like (assuming you're using the default API port): `bash -c 'cat < /dev/null > /dev/tcp/localhost/8080'` No **bash** nor **sh** in `headscale/headscale:v0.25`
adam commented 2025-12-29 02:25:07 +01:00
Author
Owner
Copy Link

@idefixcert commented on GitHub (Apr 14, 2025):

What I saw in other go programs is a health check made in main of the go program.
So you can make use of http client.

@idefixcert commented on GitHub (Apr 14, 2025): What I saw in other go programs is a health check made in main of the go program. So you can make use of http client.
adam commented 2025-12-29 02:25:08 +01:00
Author
Owner
Copy Link

@trillom commented on GitHub (Apr 28, 2025):

Hey all. Been using headscale for a while, love it, and wanted to start getting into your codebase further and take this one first, if possible. I have some ideas and I think this will be handy to have.

@trillom commented on GitHub (Apr 28, 2025): Hey all. Been using headscale for a while, love it, and wanted to start getting into your codebase further and take this one first, if possible. I have some ideas and I think this will be handy to have.
adam commented 2025-12-29 02:25:08 +01:00
Author
Owner
Copy Link

@github-actions[bot] commented on GitHub (Jul 27, 2025):

This issue is stale because it has been open for 90 days with no activity.

@github-actions[bot] commented on GitHub (Jul 27, 2025): This issue is stale because it has been open for 90 days with no activity.
adam commented 2025-12-29 02:25:08 +01:00
Author
Owner
Copy Link

@hugo-telecoop commented on GitHub (Oct 6, 2025):

Hello, any news on this ? Would be great for running it in an orchestrated environment (eg : docker swarm, k8s). Thank you

@hugo-telecoop commented on GitHub (Oct 6, 2025): Hello, any news on this ? Would be great for running it in an orchestrated environment (eg : docker swarm, k8s). Thank you
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
CLI
DERP
DNS
Nix
OIDC
SSH
bug
database
documentation
duplicate
enhancement
faq
good first issue
grants
help wanted
might-come
needs design doc
needs investigation
no-stale-bot
out of scope
performance
policy 📝
pull-request
Mirrored from GitHub Pull Request
 question
regression
routes
stale
tags
tailscale-feature-gap
well described ❤️
wontfix
No Label enhancement good first issue help wanted no-stale-bot
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adam
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/headscale#873
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?