feat: add Cloudflare DNS tool suite with multi-instance support

- zone-list, record-list, record-create, record-update, record-delete
- Named instance support (-a flag) with configurable default
- Zone name-to-ID auto-resolution in shared _lib.sh
- Updated credentials loader with cloudflare/cloudflare-<name> services
- TOOLS.md and INFRASTRUCTURE.md guide documentation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-02-22 21:31:52 -06:00
parent a9623e9219
commit e5c4bf25b3
9 changed files with 545 additions and 3 deletions

View File

@@ -153,6 +153,75 @@ The human is escalation-only for missing access, hard policy conflicts, or irrev
- Magic variables (`SERVICE_FQDN_*`) require list-style env syntax, not dict-style
- Rate limit: 200 requests per interval
### Cloudflare DNS Operations
Use the Cloudflare tools for any DNS configuration: pointing domains at services, adding TXT verification records, managing MX records, etc.
**Multi-instance support**: Credentials support named instances (e.g. `personal`, `work`). A `default` key in credentials.json determines which instance is used when `-a` is omitted. Pass `-a <instance>` to target a specific account.
```bash
# List all zones (domains) in the account
~/.config/mosaic/tools/cloudflare/zone-list.sh [-a instance]
# List DNS records for a zone (accepts zone name or ID)
~/.config/mosaic/tools/cloudflare/record-list.sh -z <zone> [-t type] [-n name]
# Create a DNS record
~/.config/mosaic/tools/cloudflare/record-create.sh -z <zone> -t <type> -n <name> -c <content> [-p] [-l ttl] [-P priority]
# Update a DNS record (requires record ID from record-list)
~/.config/mosaic/tools/cloudflare/record-update.sh -z <zone> -r <record-id> -t <type> -n <name> -c <content> [-p]
# Delete a DNS record
~/.config/mosaic/tools/cloudflare/record-delete.sh -z <zone> -r <record-id>
```
**Flag reference:**
| Flag | Purpose |
|------|---------|
| `-z` | Zone name (e.g. `mosaicstack.dev`) or 32-char zone ID |
| `-a` | Named Cloudflare instance (omit for default) |
| `-t` | Record type: `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `SRV`, etc. |
| `-n` | Record name: short (`app`) or FQDN (`app.example.com`) |
| `-c` | Record content/value (IP, hostname, TXT string, etc.) |
| `-r` | Record ID (from `record-list.sh` output) |
| `-p` | Enable Cloudflare proxy (orange cloud) — omit for DNS-only (grey cloud) |
| `-l` | TTL in seconds (default: `1` = auto) |
| `-P` | Priority for MX/SRV records |
| `-f` | Output format: `table` (default) or `json` |
**Common workflows:**
```bash
# Point a new subdomain at a server (proxied through Cloudflare)
~/.config/mosaic/tools/cloudflare/record-create.sh \
-z example.com -t A -n myapp -c 203.0.113.10 -p
# Add a TXT record for domain verification (never proxied)
~/.config/mosaic/tools/cloudflare/record-create.sh \
-z example.com -t TXT -n _verify -c "verification=abc123"
# Check what records exist before making changes
~/.config/mosaic/tools/cloudflare/record-list.sh -z example.com -t CNAME
# Update an existing record (get record ID from record-list first)
~/.config/mosaic/tools/cloudflare/record-update.sh \
-z example.com -r <record-id> -t A -n myapp -c 10.0.0.5 -p
```
**DNS + Deployment integration**: When deploying a new service via Coolify or Portainer that needs a public domain, the typical sequence is:
1. Create the DNS record pointing at the host IP (with `-p` for Cloudflare proxy if desired)
2. Deploy the service via Coolify/Portainer
3. Verify the domain resolves and the service is reachable
**Proxy (`-p`) guidance:**
- Use proxy (orange cloud) for web services — provides CDN, DDoS protection, and hides origin IP
- Skip proxy (grey cloud) for non-HTTP services (mail, SSH), wildcard records, or when the service handles its own TLS termination and needs direct client IP visibility
- Proxy is NOT compatible with non-standard ports outside Cloudflare's supported range
### Stack Health Check
Verify all infrastructure services are reachable: