memory-journal-mcp 7.7.0 → 8.0.0

package/skills/cloudflare/references/terraform/gotchas.md

@@ -0,0 +1,150 @@
+# Terraform Troubleshooting & Best Practices
+
+Common issues, security considerations, and best practices.
+
+## State Drift Issues
+
+Some resources have known state drift. Add lifecycle blocks to prevent perpetual diffs:
+
+| Resource                    | Drift Attributes                      | Workaround                                             |
+| --------------------------- | ------------------------------------- | ------------------------------------------------------ |
+| `cloudflare_pages_project`  | `deployment_configs.*`                | `ignore_changes = [deployment_configs]`                |
+| `cloudflare_workers_script` | secrets returned as REDACTED          | `ignore_changes = [secret_text_binding]`               |
+| `cloudflare_load_balancer`  | `adaptive_routing`, `random_steering` | `ignore_changes = [adaptive_routing, random_steering]` |
+| `cloudflare_workers_kv`     | special chars in keys (< 5.16.0)      | Upgrade to 5.16.0+                                     |
+
+```hcl
+# Example: Ignore secret drift
+resource "cloudflare_workers_script" "api" {
+  account_id = var.account_id
+  name = "api-worker"
+  content = file("worker.js")
+  secret_text_binding { name = "API_KEY"; text = var.api_key }
+
+  lifecycle {
+    ignore_changes = [secret_text_binding]
+  }
+}
+```
+
+## v5 Breaking Changes
+
+Provider v5 is current (auto-generated from OpenAPI). v4→v5 has breaking changes:
+
+**Resource Renames:**
+
+| v4 Resource                | v5 Resource                 | Notes                |
+| -------------------------- | --------------------------- | -------------------- |
+| `cloudflare_record`        | `cloudflare_dns_record`     |                      |
+| `cloudflare_worker_script` | `cloudflare_workers_script` | Note: plural         |
+| `cloudflare_worker_*`      | `cloudflare_workers_*`      | All worker resources |
+| `cloudflare_access_*`      | `cloudflare_zero_trust_*`   | Access → Zero Trust  |
+
+**Attribute Changes:**
+
+| v4 Attribute    | v5 Attribute | Resources            |
+| --------------- | ------------ | -------------------- |
+| `zone`          | `name`       | zone                 |
+| `account_id`    | `account.id` | zone (object syntax) |
+| `key`           | `key_name`   | KV                   |
+| `location_hint` | `location`   | R2                   |
+
+**State Migration:**
+
+```bash
+# Rename resources in state after v5 upgrade
+terraform state mv cloudflare_record.example cloudflare_dns_record.example
+terraform state mv cloudflare_worker_script.api cloudflare_workers_script.api
+```
+
+## Resource-Specific Gotchas
+
+### R2 Location Case Sensitivity
+
+**Problem:** Terraform creates R2 bucket but fails on subsequent applies  
+**Cause:** Location must be UPPERCASE  
+**Solution:** Use `WNAM`, `ENAM`, `WEUR`, `EEUR`, `APAC` (not `wnam`, `enam`, etc.)
+
+```hcl
+resource "cloudflare_r2_bucket" "assets" {
+  account_id = var.account_id
+  name = "assets"
+  location = "WNAM"  # UPPERCASE required
+}
+```
+
+### KV Special Characters (< 5.16.0)
+
+**Problem:** Keys with `+`, `#`, `%` cause encoding issues  
+**Cause:** URL encoding bug in provider < 5.16.0  
+**Solution:** Upgrade to 5.16.0+ or avoid special chars in keys
+
+### D1 Migrations
+
+**Problem:** Terraform creates database but schema is empty  
+**Cause:** Terraform only creates D1 resource, not schema  
+**Solution:** Run migrations via wrangler after Terraform apply
+
+```bash
+# After terraform apply
+wrangler d1 migrations apply <db-name>
+```
+
+### Worker Script Size Limit
+
+**Problem:** Worker deployment fails with "script too large"  
+**Cause:** Worker script + dependencies exceed 10 MB limit  
+**Solution:** Use code splitting, external dependencies, or minification
+
+### Pages Project Drift
+
+**Problem:** Pages project shows perpetual diff on `deployment_configs`  
+**Cause:** Cloudflare API adds default values not in Terraform state  
+**Solution:** Add lifecycle ignore block (see State Drift table above)
+
+## Common Errors
+
+### "Error: couldn't find resource"
+
+**Cause:** Resource was deleted outside Terraform  
+**Solution:** Import resource back into state with `terraform import cloudflare_zone.example <zone-id>` or remove from state with `terraform state rm cloudflare_zone.example`
+
+### "409 Conflict on worker deployment"
+
+**Cause:** Worker being deployed by both Terraform and wrangler simultaneously  
+**Solution:** Choose one deployment method; if using Terraform, remove wrangler deployments
+
+### "DNS record already exists"
+
+**Cause:** Existing DNS record not imported into Terraform state  
+**Solution:** Find record ID in Cloudflare dashboard and import with `terraform import cloudflare_dns_record.example <zone-id>/<record-id>`
+
+### "Invalid provider configuration"
+
+**Cause:** API token missing, invalid, or lacking required permissions  
+**Solution:** Set `CLOUDFLARE_API_TOKEN` environment variable or check token permissions in dashboard
+
+### "State locking errors"
+
+**Cause:** Multiple concurrent Terraform runs or stale lock from crashed process  
+**Solution:** Remove stale lock with `terraform force-unlock <lock-id>` (use with caution)
+
+## Limits
+
+| Resource              | Limit              | Notes                                    |
+| --------------------- | ------------------ | ---------------------------------------- |
+| API token rate limit  | Varies by plan     | Use `api_client_logging = true` to debug |
+| Worker script size    | 10 MB              | Includes all dependencies                |
+| KV keys per namespace | Unlimited          | Pay per operation                        |
+| R2 storage            | Unlimited          | Pay per GB                               |
+| D1 databases          | 50,000 per account | Free tier: 10                            |
+| Pages projects        | 500 per account    | 100 for free accounts                    |
+| DNS records           | 3,500 per zone     | Free plan                                |
+
+## See Also
+
+- [README](./README.md) - Provider setup
+- [Configuration](./configuration.md) - Resources
+- [API](./api.md) - Data sources
+- [Patterns](./patterns.md) - Use cases
+- Provider docs: https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs

package/skills/cloudflare/references/terraform/patterns.md

@@ -0,0 +1,174 @@
+# Terraform Patterns & Use Cases
+
+Architecture patterns, multi-environment setups, and real-world use cases.
+
+## Recommended Directory Structure
+
+```
+terraform/
+├── environments/
+│   ├── production/
+│   │   ├── main.tf
+│   │   └── terraform.tfvars
+│   └── staging/
+│       ├── main.tf
+│       └── terraform.tfvars
+├── modules/
+│   ├── zone/
+│   ├── worker/
+│   └── dns/
+└── shared/          # Shared resources across envs
+    └── main.tf
+```
+
+**Note:** Cloudflare recommends avoiding modules for provider resources due to v5 auto-generation complexity. Prefer environment directories + shared state instead.
+
+## Multi-Environment Setup
+
+```hcl
+# Directory: environments/{production,staging}/main.tf + modules/{zone,worker,pages}
+module "zone" {
+  source = "../../modules/zone"; account_id = var.account_id; zone_name = "example.com"; environment = "production"
+}
+module "api_worker" {
+  source = "../../modules/worker"; account_id = var.account_id; zone_id = module.zone.zone_id
+  name = "api-worker-prod"; script = file("../../workers/api.js"); environment = "production"
+}
+```
+
+## R2 State Backend
+
+```hcl
+terraform {
+  backend "s3" {
+    bucket = "terraform-state"
+    key = "cloudflare.tfstate"
+    region = "auto"
+    endpoints = { s3 = "https://<account_id>.r2.cloudflarestorage.com" }
+    skip_credentials_validation = true
+    skip_region_validation = true
+    skip_requesting_account_id = true
+    skip_metadata_api_check = true
+    skip_s3_checksum = true
+  }
+}
+```
+
+## Worker with All Bindings
+
+```hcl
+locals { worker_name = "full-stack-worker" }
+resource "cloudflare_workers_kv_namespace" "app" { account_id = var.account_id; title = "${local.worker_name}-kv" }
+resource "cloudflare_r2_bucket" "app" { account_id = var.account_id; name = "${local.worker_name}-bucket" }
+resource "cloudflare_d1_database" "app" { account_id = var.account_id; name = "${local.worker_name}-db" }
+
+resource "cloudflare_worker_script" "app" {
+  account_id = var.account_id; name = local.worker_name; content = file("worker.js"); module = true
+  compatibility_date = "2025-01-01"
+  kv_namespace_binding { name = "KV"; namespace_id = cloudflare_workers_kv_namespace.app.id }
+  r2_bucket_binding { name = "BUCKET"; bucket_name = cloudflare_r2_bucket.app.name }
+  d1_database_binding { name = "DB"; database_id = cloudflare_d1_database.app.id }
+  secret_text_binding { name = "API_KEY"; text = var.api_key }
+}
+```
+
+## Wrangler Integration
+
+**CRITICAL**: Wrangler and Terraform must NOT manage same resources.
+
+**Terraform**: Zones, DNS, security rules, Access, load balancers, worker deployments (CI/CD), KV/R2/D1 resource creation  
+**Wrangler**: Local dev (`wrangler dev`), manual deploys, D1 migrations, KV bulk ops, log streaming (`wrangler tail`)
+
+### CI/CD Pattern
+
+```hcl
+# Terraform creates infrastructure
+resource "cloudflare_workers_kv_namespace" "app" { account_id = var.account_id; title = "app-kv" }
+resource "cloudflare_d1_database" "app" { account_id = var.account_id; name = "app-db" }
+output "kv_namespace_id" { value = cloudflare_workers_kv_namespace.app.id }
+output "d1_database_id" { value = cloudflare_d1_database.app.id }
+```
+
+```yaml
+# GitHub Actions: terraform apply → envsubst wrangler.jsonc.template → wrangler deploy
+- run: terraform apply -auto-approve
+- run: |
+    export KV_NAMESPACE_ID=$(terraform output -raw kv_namespace_id)
+    envsubst < wrangler.jsonc.template > wrangler.jsonc
+- run: wrangler deploy
+```
+
+## Use Cases
+
+### Static Site + API Worker
+
+```hcl
+resource "cloudflare_pages_project" "frontend" {
+  account_id = var.account_id; name = "frontend"; production_branch = "main"
+  build_config { build_command = "npm run build"; destination_dir = "dist" }
+}
+resource "cloudflare_worker_script" "api" {
+  account_id = var.account_id; name = "api"; content = file("api-worker.js")
+  d1_database_binding { name = "DB"; database_id = cloudflare_d1_database.api_db.id }
+}
+resource "cloudflare_dns_record" "frontend" {
+  zone_id = cloudflare_zone.main.id; name = "app"; content = cloudflare_pages_project.frontend.subdomain; type = "CNAME"; proxied = true
+}
+resource "cloudflare_worker_route" "api" {
+  zone_id = cloudflare_zone.main.id; pattern = "api.example.com/*"; script_name = cloudflare_worker_script.api.name
+}
+```
+
+### Multi-Region Load Balancing
+
+```hcl
+resource "cloudflare_load_balancer_pool" "us" {
+  account_id = var.account_id; name = "us-pool"; monitor = cloudflare_load_balancer_monitor.http.id
+  origins { name = "us-east"; address = var.us_east_ip }
+}
+resource "cloudflare_load_balancer_pool" "eu" {
+  account_id = var.account_id; name = "eu-pool"; monitor = cloudflare_load_balancer_monitor.http.id
+  origins { name = "eu-west"; address = var.eu_west_ip }
+}
+resource "cloudflare_load_balancer" "global" {
+  zone_id = cloudflare_zone.main.id; name = "api.example.com"; steering_policy = "geo"
+  default_pool_ids = [cloudflare_load_balancer_pool.us.id]
+  region_pools { region = "WNAM"; pool_ids = [cloudflare_load_balancer_pool.us.id] }
+  region_pools { region = "WEU"; pool_ids = [cloudflare_load_balancer_pool.eu.id] }
+}
+```
+
+### Secure Admin with Access
+
+```hcl
+resource "cloudflare_pages_project" "admin" { account_id = var.account_id; name = "admin"; production_branch = "main" }
+resource "cloudflare_access_application" "admin" {
+  account_id = var.account_id; name = "Admin"; domain = "admin.example.com"; type = "self_hosted"; session_duration = "24h"
+  allowed_idps = [cloudflare_access_identity_provider.google.id]
+}
+resource "cloudflare_access_policy" "allow" {
+  account_id = var.account_id; application_id = cloudflare_access_application.admin.id
+  name = "Allow admins"; decision = "allow"; precedence = 1; include { email = var.admin_emails }
+}
+```
+
+### Reusable Module
+
+```hcl
+# modules/cloudflare-zone/main.tf
+variable "account_id" { type = string }; variable "domain" { type = string }; variable "ssl_mode" { default = "strict" }
+resource "cloudflare_zone" "main" { account = { id = var.account_id }; name = var.domain }
+resource "cloudflare_zone_settings_override" "main" {
+  zone_id = cloudflare_zone.main.id; settings { ssl = var.ssl_mode; always_use_https = "on" }
+}
+output "zone_id" { value = cloudflare_zone.main.id }
+
+# Usage: module "prod" { source = "./modules/cloudflare-zone"; account_id = var.account_id; domain = "example.com" }
+```
+
+## See Also
+
+- [README](./README.md) - Provider setup
+- [Configuration Reference](./configuration.md) - All resource types
+- [API Reference](./api.md) - Data sources
+- [Troubleshooting](./gotchas.md) - Best practices, common issues

package/skills/cloudflare/references/tunnel/README.md

@@ -0,0 +1,137 @@
+# Cloudflare Tunnel
+
+Secure outbound-only connections between infrastructure and Cloudflare's global network.
+
+## Overview
+
+Cloudflare Tunnel (formerly Argo Tunnel) enables:
+
+- **Outbound-only connections** - No inbound ports or firewall changes
+- **Public hostname routing** - Expose local services to internet
+- **Private network access** - Connect internal networks via WARP
+- **Zero Trust integration** - Built-in access policies
+
+**Architecture**: Tunnel (persistent object) → Replica (`cloudflared` process) → Origin services
+
+**Terminology:**
+
+- **Tunnel**: Named persistent object with UUID
+- **Replica**: Individual `cloudflared` process connected to tunnel
+- **Config Source**: Where ingress rules stored (local file vs Cloudflare dashboard)
+- **Connector**: Legacy term for replica
+
+## Quick Start
+
+### Local Config
+
+```bash
+# Install cloudflared
+brew install cloudflared  # macOS
+
+# Authenticate
+cloudflared tunnel login
+
+# Create tunnel
+cloudflared tunnel create my-tunnel
+
+# Route DNS
+cloudflared tunnel route dns my-tunnel app.example.com
+
+# Run tunnel
+cloudflared tunnel run my-tunnel
+```
+
+### Dashboard Config (Recommended)
+
+1. **Zero Trust** > **Networks** > **Tunnels** > **Create**
+2. Name tunnel, copy token
+3. Configure routes in dashboard
+4. Run: `cloudflared tunnel --no-autoupdate run --token <TOKEN>`
+
+## Decision Tree
+
+**Choose config source:**
+
+```
+Need centralized config updates?
+├─ Yes → Token-based (dashboard config)
+└─ No → Local config file
+
+Multiple environments (dev/staging/prod)?
+├─ Yes → Local config (version controlled)
+└─ No → Either works
+
+Need firewall approval?
+└─ See networking.md first
+```
+
+## Core Commands
+
+```bash
+# Tunnel lifecycle
+cloudflared tunnel create <name>
+cloudflared tunnel list
+cloudflared tunnel info <name>
+cloudflared tunnel delete <name>
+
+# DNS routing
+cloudflared tunnel route dns <tunnel> <hostname>
+cloudflared tunnel route list
+
+# Private network
+cloudflared tunnel route ip add 10.0.0.0/8 <tunnel>
+
+# Run tunnel
+cloudflared tunnel run <name>
+```
+
+## Configuration Example
+
+```yaml
+# ~/.cloudflared/config.yml
+tunnel: 6ff42ae2-765d-4adf-8112-31c55c1551ef
+credentials-file: /root/.cloudflared/6ff42ae2-765d-4adf-8112-31c55c1551ef.json
+
+ingress:
+  - hostname: app.example.com
+    service: http://localhost:8000
+  - hostname: api.example.com
+    service: https://localhost:8443
+    originRequest:
+      noTLSVerify: true
+  - service: http_status:404
+```
+
+## Reading Order
+
+**New to Cloudflare Tunnel:**
+
+1. This README (overview, quick start)
+2. [networking.md](./networking.md) - Firewall rules, connectivity pre-checks
+3. [configuration.md](./configuration.md) - Config file options, ingress rules
+4. [patterns.md](./patterns.md) - Docker, Kubernetes, production deployment
+5. [gotchas.md](./gotchas.md) - Troubleshooting, best practices
+
+**Enterprise deployment:**
+
+1. [networking.md](./networking.md) - Corporate firewall requirements
+2. [gotchas.md](./gotchas.md) - HA setup, security best practices
+3. [patterns.md](./patterns.md) - Kubernetes, rolling updates
+
+**Programmatic control:**
+
+1. [api.md](./api.md) - REST API, TypeScript SDK
+
+## In This Reference
+
+- [networking.md](./networking.md) - Firewall rules, ports, connectivity pre-checks
+- [configuration.md](./configuration.md) - Config file options, ingress rules, TLS settings
+- [api.md](./api.md) - REST API, TypeScript SDK, token-based tunnels
+- [patterns.md](./patterns.md) - Docker, Kubernetes, Terraform, HA, use cases
+- [gotchas.md](./gotchas.md) - Troubleshooting, limitations, best practices
+
+## See Also
+
+- [workers](../workers/) - Workers with Tunnel integration
+- [access](../access/) - Zero Trust access policies
+- [warp](../warp/) - WARP client for private networks

package/skills/cloudflare/references/tunnel/api.md

@@ -0,0 +1,205 @@
+# Tunnel API
+
+## Cloudflare API Access
+
+**Base URL**: `https://api.cloudflare.com/client/v4`
+
+**Authentication**:
+
+```bash
+Authorization: Bearer ${CF_API_TOKEN}
+```
+
+## TypeScript SDK
+
+Install: `npm install cloudflare`
+
+```typescript
+import Cloudflare from 'cloudflare'
+
+const cf = new Cloudflare({
+  apiToken: process.env.CF_API_TOKEN,
+})
+
+const accountId = process.env.CF_ACCOUNT_ID
+```
+
+## Create Tunnel
+
+### cURL
+
+```bash
+curl -X POST "https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels" \
+  -H "Authorization: Bearer ${CF_API_TOKEN}" \
+  -H "Content-Type: application/json" \
+  --data '{
+    "name": "my-tunnel",
+    "tunnel_secret": "<base64-secret>"
+  }'
+```
+
+### TypeScript
+
+```typescript
+const tunnel = await cf.zeroTrust.tunnels.create({
+  account_id: accountId,
+  name: 'my-tunnel',
+  tunnel_secret: Buffer.from(crypto.randomBytes(32)).toString('base64'),
+})
+
+console.log(`Tunnel ID: ${tunnel.id}`)
+```
+
+## List Tunnels
+
+### cURL
+
+```bash
+curl -X GET "https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels" \
+  -H "Authorization: Bearer ${CF_API_TOKEN}"
+```
+
+### TypeScript
+
+```typescript
+const tunnels = await cf.zeroTrust.tunnels.list({
+  account_id: accountId,
+})
+
+for (const tunnel of tunnels.result) {
+  console.log(`${tunnel.name}: ${tunnel.id}`)
+}
+```
+
+## Get Tunnel Info
+
+### cURL
+
+```bash
+curl -X GET "https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels/{tunnel_id}" \
+  -H "Authorization: Bearer ${CF_API_TOKEN}"
+```
+
+### TypeScript
+
+```typescript
+const tunnel = await cf.zeroTrust.tunnels.get(tunnelId, {
+  account_id: accountId,
+})
+
+console.log(`Status: ${tunnel.status}`)
+console.log(`Connections: ${tunnel.connections?.length || 0}`)
+```
+
+## Update Tunnel Config
+
+### cURL
+
+```bash
+curl -X PUT "https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels/{tunnel_id}/configurations" \
+  -H "Authorization: Bearer ${CF_API_TOKEN}" \
+  -H "Content-Type: application/json" \
+  --data '{
+    "config": {
+      "ingress": [
+        {"hostname": "app.example.com", "service": "http://localhost:8000"},
+        {"service": "http_status:404"}
+      ]
+    }
+  }'
+```
+
+### TypeScript
+
+```typescript
+const config = await cf.zeroTrust.tunnels.configurations.update(tunnelId, {
+  account_id: accountId,
+  config: {
+    ingress: [
+      { hostname: 'app.example.com', service: 'http://localhost:8000' },
+      { service: 'http_status:404' },
+    ],
+  },
+})
+```
+
+## Delete Tunnel
+
+### cURL
+
+```bash
+curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels/{tunnel_id}" \
+  -H "Authorization: Bearer ${CF_API_TOKEN}"
+```
+
+### TypeScript
+
+```typescript
+await cf.zeroTrust.tunnels.delete(tunnelId, {
+  account_id: accountId,
+})
+```
+
+## Token-Based Tunnels (Config Source: Cloudflare)
+
+Token-based tunnels store config in Cloudflare dashboard instead of local files.
+
+### Via Dashboard
+
+1. **Zero Trust** > **Networks** > **Tunnels**
+2. **Create a tunnel** > **Cloudflared**
+3. Configure routes in dashboard
+4. Copy token
+5. Run on origin:
+
+```bash
+cloudflared service install <TOKEN>
+```
+
+### Via Token
+
+```bash
+# Run with token (no config file needed)
+cloudflared tunnel --no-autoupdate run --token ${TUNNEL_TOKEN}
+
+# Docker
+docker run cloudflare/cloudflared:latest tunnel --no-autoupdate run --token ${TUNNEL_TOKEN}
+```
+
+### Get Tunnel Token (TypeScript)
+
+```typescript
+// Get tunnel to retrieve token
+const tunnel = await cf.zeroTrust.tunnels.get(tunnelId, {
+  account_id: accountId,
+})
+
+// Token available in tunnel.token (only for config source: cloudflare)
+const token = tunnel.token
+```
+
+## DNS Routes API
+
+```bash
+# Create DNS route
+curl -X POST "https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels/{tunnel_id}/connections" \
+  -H "Authorization: Bearer ${CF_API_TOKEN}" \
+  --data '{"hostname": "app.example.com"}'
+
+# Delete route
+curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels/{tunnel_id}/connections/{route_id}" \
+  -H "Authorization: Bearer ${CF_API_TOKEN}"
+```
+
+## Private Network Routes API
+
+```bash
+# Add IP route
+curl -X POST "https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels/{tunnel_id}/routes" \
+  -H "Authorization: Bearer ${CF_API_TOKEN}" \
+  --data '{"ip_network": "10.0.0.0/8"}'
+
+# List IP routes
+curl -X GET "https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels/{tunnel_id}/routes" \
+  -H "Authorization: Bearer ${CF_API_TOKEN}"
+```