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 the Cloudflare Tunnel, you can securely manage the Raspberry Pi and the Kubernetes cluster from anywhere without a VPN.

1.1. Remote SSH Access

The tunnel is configured to proxy SSH traffic. To connect:

Ensure cloudflared is installed on your local machine (brew install cloudflared).
Add the following to your ~/.ssh/config file:
```
Host cloud
  HostName ssh.taehoonlee.cloud
  ProxyCommand /opt/homebrew/bin/cloudflared access ssh --hostname %h
```
(Note: Verify the path to your cloudflared executable by running which cloudflared)
Connect: You can now simply run ssh cloud.

1.2. Remote `kubectl` Access via TCP Tunnel

To securely connect kubectl to the cluster, we use cloudflared to create a local TCP proxy that tunnels traffic to the Kubernetes API server.

Method A: Persistent Background Service (Recommended)

This is the best practice. It creates a background service that starts automatically when you log in.

Create a launchd agent file. Run the following command to create the service definition:

cat << EOF > ~/Library/LaunchAgents/com.cloudflare.cloudflared.k8s-proxy.plist
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.cloudflare.cloudflared.k8s-proxy</string>
    <key>ProgramArguments</key>
    <array>
        <string>/opt/homebrew/bin/cloudflared</string>
        <string>access</string>
        <string>tcp</string>
        <string>--hostname</string>
        <string>k8s.taehoonlee.cloud</string>
        <string>--url</string>
        <string>localhost:6443</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>
EOF

Load and start the service. This command enables the service to start on login.

launchctl load -w ~/Library/LaunchAgents/com.cloudflare.cloudflared.k8s-proxy.plist

Method B: Manual Terminal Session (Temporary)

Use this method if you only need temporary access.

Run the proxy command in a dedicated terminal window. You must leave this window open.
```
cloudflared access tcp --hostname k8s.taehoonlee.cloud --url localhost:6443
```

`kubeconfig` Setup (For Both Methods)

Your ~/.kube/config file should use the original certificate data from the Pi, but point to your local proxy.

Get the original kubeconfig from the Pi: sudo cat /etc/rancher/k3s/k3s.yaml
Copy it to your local ~/.kube/config.
Change only the server line to point to the local proxy: `diff
- server: https://127.0.0.1:6443
- server: https://localhost:6443 Yourkubectl` commands will now work seamlessly from any network.

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
```