Portainer/cloudflared/README.md

Cloudflare DNS y cloudflared

Esta carpeta contiene dos piezas independientes:

• cloudflare_dns.py: administra registros DNS A que apuntan directamente a este servidor.
• docker-compose.yml: definición opcional de Cloudflare Tunnel, actualmente no desplegada.

La herramienta DNS no crea, activa, consulta ni modifica túneles.

Configuración DNS

cloudflare_dns.py lee el .env local de esta carpeta. Necesita:

CLOUDFLARE_API_TOKEN=<token con Zone DNS Edit>
CLOUDFLARE_ZONE_ID=<id de la zona>
CLOUDFLARE_DOMAIN=sherlockhomeless.net
# Opcional: destino predeterminado para create/update
CLOUDFLARE_SERVER_IP=<IPv4 pública de este servidor>

El API token sólo necesita permiso Zone > DNS > Edit sobre la zona indicada. No necesita permisos de cuenta ni de Cloudflare Tunnel.

CLOUDFLARE_SERVER_IP es opcional. Si se configura, se usa como destino predeterminado; si se omite, create y update exigen --server-ip. El script nunca autodetecta la IP: así evita modificar registros hacia una dirección inesperada por un fallo de red o de un servicio externo.

Operaciones

Lista todos los registros A e indica cuáles apuntan a CLOUDFLARE_SERVER_IP:

cd cloudflared
./cloudflare_dns.py list

Crea registros nuevos:

./cloudflare_dns.py create immich recipes

Sin IP predeterminada en .env:

./cloudflare_dns.py --server-ip 203.0.113.10 create immich recipes

--server-ip siempre tiene prioridad sobre el valor del .env, lo que permite un cambio puntual sin editar el archivo local.

Actualiza registros A existentes para que apunten a este servidor:

./cloudflare_dns.py update immich recipes

Elimina registros A; requiere escribir DELETE:

./cloudflare_dns.py delete immich

Para automatización no interactiva:

./cloudflare_dns.py delete --yes immich

Antes de crear, modificar o eliminar, puede revisarse la intención sin llamar a la API:

./cloudflare_dns.py --dry-run create immich
./cloudflare_dns.py --dry-run update immich
./cloudflare_dns.py --dry-run delete immich

También se acepta el dominio completo o @ para el dominio raíz. Se rechazan nombres fuera de CLOUDFLARE_DOMAIN.

Comportamiento deliberado

• Sólo gestiona registros A.
• Usa --server-ip como destino o, si no se pasa, CLOUDFLARE_SERVER_IP como valor predeterminado.
• Siempre crea registros DNS-only (proxied: false, nube gris).
• create falla si el nombre ya existe; no sobrescribe silenciosamente un CNAME u otro registro.
• update y delete fallan si no hay exactamente un registro A para el nombre.
• Las operaciones múltiples continúan con el resto de nombres y terminan con código distinto de cero si alguno falla.

Estas restricciones evitan convertir registros a túnel o proxy de Cloudflare accidentalmente.

Compose de cloudflared

El Compose conserva la definición del agente de Cloudflare Tunnel, pero no hay actualmente ningún contenedor cloudflared desplegado. Si no se va a volver a usar el túnel, puede retirarse en un cambio separado junto con CLOUDFLARE_TUNNEL_TOKEN, CLOUDFLARE_ACCOUNT_ID y CLOUDFLARE_TUNNEL_ID.

La utilidad DNS no necesita levantar este Compose.

Seguridad

• Mantén el token y la IP reales únicamente en .env, que está ignorado por Git.
• Usa un token dedicado limitado a edición DNS de esta zona.
• Revisa --dry-run antes de operaciones masivas.
• La salida nunca imprime el token, pero list sí muestra nombres e IP de los registros.
• Rota el token si aparece en logs, historial de shell o commits.