feat: Deploy Headscale server to tiny Kubernetes cluster for lab VPN evaluation

[Copilot]

Overview

This PR deploys Headscale, a self-hosted Tailscale control server, to the tiny Kubernetes cluster for lab VPN evaluation. Headscale provides an open-source alternative to Twingate for VPN connectivity management in the lab environment.

What's Changed

Helm Repository Configuration

• Added gabe565 Helm repository to Flux (kubernetes/flux/repositories/helm/gabe565.yaml)
• Repository provides the official Headscale Helm chart from https://charts.gabe565.com

Headscale Deployment

Created complete application manifests in kubernetes/apps/base/headscale/:

• namespace.yaml - Dedicated headscale namespace for isolation

• release.yaml - HelmRelease with production-ready configuration:

  • Headscale v0.25.0 container image
  • HTTP API on port 8080 for client connections
  • gRPC API on port 50443 for authentication
  • Prometheus metrics on port 9090
  • SQLite database with 1Gi persistent volume
  • MagicDNS enabled with lab.local domain
  • Built-in DERP servers with automatic updates

• secret.sops.yaml - SOPS-encrypted secret template for OIDC and Noise protocol keys

• kustomization.yaml - Kustomize configuration for the application

• README.md - Comprehensive documentation including deployment steps, usage instructions, and troubleshooting

Network Configuration

The deployment is configured to integrate with the existing lab infrastructure:

• VPN IP Ranges: 100.64.0.0/10 (IPv4), fd7a:115c:a1e0::/48 (IPv6)
• Lab Network Integration: 10.151.16.0/24 (matching the tiny_k8s network)
• DNS: MagicDNS enabled with lab.local base domain
• Database: SQLite with persistent storage for evaluation

Access Control Configuration

ACLs are configured with three groups inspired by the existing Twingate structure:

1. group:admins - Full access to all resources (mapped from Twingate "all" group)
2. group:lab-users - Access to lab network and limited VPN services like SSH (22), HTTP (80), HTTPS (443) (mapped from Twingate "tiny_k8s", "wanda_k8s" groups)
3. group:services - Service account access to lab network (mapped from Twingate service accounts)

Cluster Integration

• Updated kubernetes/apps/tiny/kustomization.yaml to include Headscale deployment
• Updated main README.md with reference to Headscale documentation
• Flux will automatically deploy Headscale when changes are merged

Deployment Process

Once merged, Flux GitOps will automatically:

1. Add the gabe565 Helm repository
2. Deploy Headscale to the tiny cluster
3. Create namespace, services, and persistent storage
4. Apply the HelmRelease configuration

Usage

After deployment, administrators can:

# Create users
kubectl exec -n headscale -it deployment/headscale -- headscale users create admin

# Generate pre-auth keys
kubectl exec -n headscale -it deployment/headscale -- headscale preauthkeys create --user admin --reusable --expiration 24h

# Connect clients using Tailscale
tailscale up --login-server=http://headscale.headscale.svc.cluster.local:8080 --authkey=<preauthkey>

Full usage instructions and troubleshooting steps are available in kubernetes/apps/base/headscale/README.md.

Future Enhancements

This deployment is configured for evaluation. For production use, consider:

• Configuring TLS/HTTPS with Traefik ingress
• Setting up OIDC authentication with an identity provider
• Deploying custom DERP servers for improved performance
• Integrating with existing AdGuard DNS servers
• Adding Grafana dashboards for monitoring

Testing

All YAML manifests have been validated with yamllint and follow repository conventions. The configuration has been verified against existing deployment patterns (Twingate, monitoring stack, etc.).

Closes #[issue-number]

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Deploy and configure Headscale server for lab VPN</issue_title>
<issue_description>Set up a self-hosted Headscale server to manage Tailscale clients for lab operations.

Tasks:

• Choose hosting location (cloud/on-prem)
• Set up TLS and persistent storage
• Configure authentication (OIDC/manual)
• Integrate with DERP servers as needed
• Test connectivity and performance
• Document deployment steps

Acceptance Criteria:

• Headscale server operational and reachable
• Users can authenticate and connect via Tailscale
• Network ACLs validated
• Deployment steps documented
  </issue_description>

<agent_instructions>Deploy headscale to the tiny kubernetes cluster via flux for evaluation. Ideally some example configuration based on the current Twingate config in Terraform should be applied.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

Fixes #783

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[autonomous-bancey]

Plan Result (test_vpn_gateway)

No changes. Your infrastructure matches the configuration.

[autonomous-bancey]

Plan Result (generate_ansible_inventory)

No changes. Your infrastructure matches the configuration.

[autonomous-bancey]

Plan Result (prod_twingate)

No changes. Your infrastructure matches the configuration.

[autonomous-bancey]

Plan Result (prod_vpn_gateway)

No changes. Your infrastructure matches the configuration.

[autonomous-bancey]

Plan Result (test_gameserver)

No changes. Your infrastructure matches the configuration.

[autonomous-bancey]

Plan Result (prod_gameserver)

No changes. Your infrastructure matches the configuration.

[autonomous-bancey]

Plan Result (prod_dns)

No changes. Your infrastructure matches the configuration.

[autonomous-bancey]

Plan Result (tiny_virtual_machines)

No changes. Your infrastructure matches the configuration.