temptunnels

Files (5)

• SKILL.md
• cloudflared-docker-compose.md · examples/
• cloudflared-helm-sidecar.md · examples/
• ngrok-docker-compose.md · examples/
• ngrok-helm-sidecar.md · examples/

SKILL.md (first lines)

# Temporary Tunnels (`temptunnels`) Skill

This skill guides the AI agent in adding temporary public tunnel containers—supporting both **Ngrok (`ngrok`)** and **Cloudflare Quick Tunnels (`cloudflared`)**—to **Kubernetes Helm charts** and **Docker Compose (`docker-compose.yml` / `docker-compose.yaml`)** files so applications can be exposed publicly without requiring DNS, public LoadBalancers, or Ingress controllers.

## When to Use This Skill

Activate this skill when the user wants to:
- Add an **Ngrok** (`ngrok/ngrok`) or **Cloudflare** (`cloudflare/cloudflared`) tunnel sidecar container to a **Helm chart** (`deployment.yaml`, `values.yaml`, `NOTES.txt`, `secret.yaml`).
- Create or update a **Docker Compose file** (`docker-compose.yml` / `docker-compose.yaml` and `.env` / `.env.example`) with an **Ngrok** or **Cloudflare (`cloudflared`)** tunnel companion service.
- Expose a Kubernetes or Docker Compose service temporarily via a public HTTPS URL (`*.ngrok-free.app` / `*.ngrok.app` or `*.trycloudflare.com`).
- Configure tunnel ports, metrics/health probes, target URLs, or authentication tokens/secrets in Helm or Docker Compose.

## Choosing Between Ngrok and Cloudflare (`cloudflared`)

| Feature | Option 1: Ngrok (`ngrok/ngrok`) | Option 2: Cloudflare (`cloudflare/cloudflared`) |
| :--- | :--- | :--- |
| **Public URL Domain** | `*.ngrok-free.app` / `*.ngrok.app` | `*.trycloudflare.com` (Quick Tunnel) |
| **Required Secrets / Tokens** | **Requires `authtoken`** (`--authtoken` or `NGROK_AUTHTOKEN`) | **None required** for Quick Tunnels (optional `TUNNEL_TOKEN` for Named Tunnels) |
| **Target URL (Helm / K8s Pod)** | `http://localhost:<service.targetPort>` | `http://localhost:<service.targetPort>` via `--url` |
| **Target URL (Docker Compose)** | `http://<app-service>:<port>` (or `http://localhost:<port>` with `network_mode: "service:<app-service>"`) | `http://<app-service>:<port>` via `--url` (or `http://localhost:<port>` with `network_mode: "service:<app-service>"`) |
| **Container / Sidecar Ports** | Optional `4040/TCP` (Inspector UI/API) | `2000/TCP` (`cf-metrics`) for `--metrics` & `/ready` `livenessProbe` |
| **Outbound Ports** | `443/TCP` (TLS to Ngrok edge) | `443/TCP` (HTTPS) & `7844/TCP+UDP` (QUIC/HTTP2 to Cloudflare edge) |

> **Important Difference Between Kubernetes `command` and Docker Compose `command`:**
> - In **Kubernetes (`deployment.yaml`)**, `command` overrides the image's `ENTRYPOINT`, so the binary name (`ngrok` or `cloudflared`) **must** be the first element.
> - In **Docker Compose (`docker-compose.yml`)**, `command` overrides the image's `CMD` and is appended to the image's default `ENTRYPOINT` (`["ngrok"]` or `["cloudflared", "--no-autoupdate"]`). Therefore, `command` in `docker-compose.yml` **must start with the subcommand** (`http` for Ngrok, `tunnel` for Cloudflare) rather than repeating the binary name.

---

## Option 1: Ngrok (`ngrok`)

- **Helm Chart Reference**: [examples/ngrok-helm-sidecar.md](./examples/ngrok-helm-sidecar.md)
- **Docker Compose Reference**: [examples/ngrok-docker-compose.md](./examples/ngrok-docker-compose.md)

### 1. Port Requirements & Networking (Ngrok)

- **Application Target Port**:
  - **Helm (Kubernetes Pod)**: Ngrok shares the Pod's `localhost` network namespace and forwards traffic to `{{ .Values.ngrok.url | default (printf "http://localhost:%v" .Values.service.targetPort) | quote }}`.
  - **Docker Compose**: By default, Ngrok runs on the shared Compose bridge network and forwards traffic to `http://<app-service>:<port>` (e.g., `${NGROK_URL:-http://<app-service>:8000}`). Alternatively, setting `network_mode: "service:<app-service>"` shares the application container's `localhost` namespace (`http://localhost:<port>`).
- **Ngrok Inspector Port (`4040`, Optional)**:
  - The Ngrok agent listens on port `4040` for its local inspection UI/API (`127.0.0.1:4040:4040` in Docker Compose).
- **Outbound Connectivity (`443`)**:
  - Requires outbound TCP/TLS on port `443` to connect to Ngrok edge servers.

### 2. Required Secrets & API Tokens (Ngrok)

- **Ngrok Authtoken (`ngrok.authtoken` / `NGROK_AUTHTOKEN`) — REQUIRED**:
  - Obtained from the [Ngrok Dashboard](https://dashboard.ngrok.com/get-started/your-authtoken).
  - Passed via `--authtoken` CLI flag or `NGROK_AUTHTOKEN` environment variable.
  - **Best Practice (Helm)**: Leave `ngrok.authtoken: ""` in `values.yaml` and pass at deploy time (`--set ngrok.authtoken="..."`) or inject from a Kubernetes `Secret`.
  - **Best Practice (Docker Compose)**: Inject `NGROK_AUTHTOKEN` from `.env` (and keep `NGROK_AUTHTOKEN=""` in `.env.example`).
- **Ngrok API Key (`NGROK_API_KEY`) — OPTIONAL**:
  - Only needed for REST API operations or automated edge configurations outside standard agent tunneling.

### 3A. Helm Changes for Ngrok

1. **`values.yaml`**:
   ```yaml
   # ----------------------------------------------------------------------------
   # ngrok Tunnel Sidecar Configuration
   # ----------------------------------------------------------------------------
   ngrok:
     enabled: true
     image:
       repository: ngrok/ngrok
       tag: "latest"
       pullPolicy: IfNotPresent
     # Target URL to tunnel to. Defaults to http://localhost:<service.targetPort> (8000)
     url: ""
     authtoken: ""
     log: "stdout"
     # Optional additional arguments to pass to `ngrok http`
     extraArgs: []
     resources:
       requests:
         cpu: 50m
         memory: 64Mi
       limits:
         cpu: 200m
         memory: 128Mi
   ```

2. **`templates/deployment.yaml`** (under `spec.template.spec.containers`):
   ```yaml
           {{- if .Values.ngrok.enabled }}
           - name: ngrok
             image: "{{ .Values.ngrok.image.repository }}:{{ .Values.ngrok.image.tag }}"
             imagePullPolicy: {{ .Values.ngrok.image.pullPolicy }}
             command:
               - ngrok
               - http
               - {{ .Values.ngrok.url | default (printf "http://localhost:%v" .Values.service.targetPort) | quote }}
               - --authtoken
               - {{ .Values.ngrok.authtoken | quote }}
               {{- if .Values.ngrok.log }}
               - --log
               - {{ .Values.ngrok.log | quote }}
               {{- end }}
               {{- range .Values.ngrok.extraArgs }}
               - {{ . | quote }}
               {{- end }}
             resources:
               {{- toYaml .Values.ngrok.resources | nindent 12 }}
           {{- end }}
   ```

3. **`templates/NOTES.txt`**:
   ```yaml
   {{- if .Values.ngrok.enabled }}

   ngrok Tunnel is enabled!
   To retrieve your generated ngrok URL, run:
     kubectl --namespace {{ .Release.Namespace }} logs deploy/{{ include "<chartname>.fullname" . }} -c ngrok | grep "url="
   {{- end }}
   ```

### 3B. Docker Compose Changes for Ngrok

1. **`docker-compose.yml`** (under `services:`):

From idjohnson/aiskills, MIT.

More from idjohnson/aiskills