Skip to content

Add Tailscale device cleanup runbook #83

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
noahwhite merged 3 commits into from
Jan 30, 2026
Merged

Add Tailscale device cleanup runbook #83

noahwhite merged 3 commits into from
Jan 30, 2026

Conversation

@noahwhite
Copy link
Owner

@noahwhite noahwhite commented Jan 30, 2026 •
edited
Loading

Summary

  • Add runbook for manual Tailscale device cleanup before instance recreation
  • Add warnings to CLAUDE.md in Alloy and Tailscale sysext update sections

Context

When a Ghost instance is destroyed and recreated, Tailscale keeps the old device registration. The new instance receives a suffixed hostname (e.g., ghost-dev-01-1) to avoid conflicts. This can cause:

  • Confusion with SSH access (tailscale ssh core@ghost-dev-01-1 vs expected name)
  • First-boot failures in tailscale-monitor.service (prefix matching finds stale device)
  • Documentation/script mismatches

Changes

New: docs/runbooks/tailscale-device-cleanup.md

  • Documents when cleanup is needed (any change that recreates instance)
  • Step-by-step procedures for manual cleanup via admin console
  • Alternative methods (CLI, API) for future automation
  • Troubleshooting section for common issues
  • Post-recreation verification steps

Updated: CLAUDE.md

  • Added "Important" note to "Updating Alloy Sysext Version" section
  • Added "Important" note to "Updating Tailscale Sysext Version" section
  • Both notes link to the new runbook

Test plan

  • Runbook steps are clear and actionable
  • CLAUDE.md warnings appear in correct sections
  • Links to runbook are correct

@noahwhite
Add Tailscale device cleanup runbook and update CLAUDE.md
13d82d6 
Add runbook documenting the manual cleanup process for removing stale
Tailscale devices before instance recreation. This prevents naming
conflicts where new instances receive suffixed hostnames (e.g.,
ghost-dev-01-1 instead of ghost-dev-01).

Also adds warnings to CLAUDE.md in both the Alloy and Tailscale sysext
update sections, reminding operators to clean up Tailscale devices
before any change that triggers instance recreation.
@linear
Copy link

linear bot commented Jan 30, 2026

GHO-45 [User Story] Implement workaround for Vultr block storage attachment bug

@noahwhite noahwhite self-assigned this Jan 30, 2026
@noahwhite
Add known issue note for alloy.service not auto-starting
d4a5702 
Document that alloy.service may not start automatically after instance
recreation due to a timing issue with Ignition and systemd-sysext.
Include manual fix command.
@noahwhite
Use read -s for secure API key input in runbook
7e044fd 
Avoid exposing sensitive TAILSCALE_API_KEY in command line history.
Use zsh read -s to securely read the key, export it, and unset when done.
@noahwhite noahwhite merged commit 1a885a9 into develop Jan 30, 2026
2 checks passed
@noahwhite noahwhite deleted the feature/gho-45-tailscale-cleanup-runbook branch January 30, 2026 06:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@noahwhite noahwhite

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@noahwhite