Guide: Local & Remote Development

This document explains the different methods for interacting with the cluster from your local machine, both for direct management and for application development.

1. Direct Remote Management (SSH & `kubectl`)

Thanks to Tailscale, you can securely manage the Raspberry Pi and the Kubernetes cluster from anywhere without a VPN or port forwarding. Cloudflare Tunnel is still used for public ingress to your applications, but for internal cluster management and node communication, Tailscale provides a simpler and more direct secure channel.

1.1. Remote SSH Access

While Cloudflare Tunnel can proxy SSH, with Tailscale you can connect directly to your Pi's private Tailscale IP.

Ensure Tailscale is installed on your local machine and your Raspberry Pi. Follow the official instructions at tailscale.com/download.
Log in to Tailscale on both devices (your local machine and your Raspberry Pi) using tailscale up.
Find your Raspberry Pi's Tailscale IP address. You can find this in the Tailscale admin console or by running tailscale ip -4 on the Raspberry Pi. Let's assume it's 100.X.Y.Z.
Connect: You can now simply run ssh [email protected] (replacing 100.X.Y.Z with your Pi's actual Tailscale IP).

1.2. Remote `kubectl` Access via Tailscale

To securely connect kubectl to the cluster, you will use Tailscale to establish a direct, encrypted connection to your K3s server's API endpoint. This method connects directly to the K3s server on its Tailscale IP, without deploying the Tailscale Kubernetes operator or its API server proxy. While the operator offers advanced features like RBAC integration, this direct approach is simpler for single-server K3s setups and local development.

Ensure Tailscale is installed and running on both your local machine and your Raspberry Pi (as described in 1.1).
Configure K3s to trust the Tailscale IP: The Kubernetes API server certificate must be updated to include the new Tailscale IP address, or kubectl will reject the connection.
- SSH into your Raspberry Pi.
- Create or edit the K3s configuration file:
```
sudo mkdir -p /etc/rancher/k3s
sudo nano /etc/rancher/k3s/config.yaml
```
- Add the tls-san configuration:
```
tls-san:
  - "YOUR_TAILSCALE_IP"
```
  (Replace YOUR_TAILSCALE_IP with the actual IP, e.g., 100.X.Y.Z)
- Restart K3s:
```
sudo systemctl restart k3s
```
Get the original kubeconfig from the Pi: sudo cat /etc/rancher/k3s/k3s.yaml
Copy it to your local ~/.kube/config.
Crucially, change only the server line to point to your Raspberry Pi's Tailscale IP address (e.g., 100.X.Y.Z) obtained in step 1.1:
```
- server: https://127.0.0.1:6443
+ server: https://100.X.Y.Z:6443
```
(Replace 100.X.Y.Z with your Pi's actual Tailscale IP.)

The tailscale configure kubeconfig command is primarily for connecting to an operator-managed proxy; for this direct connection method, manual editing of the kubeconfig as shown above is the correct approach. Your kubectl commands will now work seamlessly over the secure Tailscale tunnel.

2. Local Application Development with Telepresence

When you are actively developing a service on your local machine and need it to communicate with other services running inside the cluster, Telepresence is the best tool.

Remote kubectl is for managing the cluster.
Telepresence is for developing applications that run against the cluster.

Setup and Usage

Install the CLI (macOS):

brew install datawire/telepresence/telepresence

Install the Traffic Manager:
```
telepresence helm install
```
Connect to the Cluster:
```
sudo telepresence connect
```
Run your local service (e.g., pnpm dev). Any code that connects to an in-cluster service (e.g., my-api.my-namespace.svc.cluster.local) will now succeed.
Disconnect:
```
telepresence quit
```