Cloudflare Secrets Manager: Variables vs. Secretos

Cloudflare Secrets Manager es el conjunto de herramientas que Cloudflare ofrece para gestionar credenciales sensibles en Workers: por un lado, los secretos per-Worker (disponibles desde siempre vía Wrangler), y por otro, el nuevo Cloudflare Secrets Store, lanzado en public beta durante Developer Week 2025, que centraliza la gestión a nivel de cuenta para compartir secretos entre múltiples Workers.

Cloudflare es una plataforma de red y seguridad desarrollada por Cloudflare, Inc. que proporciona servicios de CDN, caché, protección DDoS y optimización del rendimiento para sitios web.

Qué es Cloudflare Secrets Manager

Si alguna vez deployaste un Worker de Cloudflare que necesitaba conectarse a una API externa, sabés el dolor de cabeza que es manejar las credenciales bien. La opción fácil (y mala) es hardcodear la key en el código. La opción medianamente correcta es usar variables de entorno. La opción que deberías usar es Cloudflare Secrets Manager.

Cloudflare Secrets Manager es el sistema de Cloudflare para almacenar y acceder a datos sensibles (claves API, tokens, contraseñas) desde Workers y Snippets, con encriptación en reposo, acceso write-only y sin posibilidad de leer el valor una vez guardado. No es un producto único: engloba los secretos per-Worker (gestionados con Wrangler) y el nuevo Secrets Store, que centraliza todo a nivel de cuenta.

Según el anuncio oficial en el blog de Cloudflare, Secrets Store entró en public beta durante Developer Week 2025, respondiendo a una necesidad concreta: equipos que manejan decenas de Workers terminaban duplicando los mismos secretos en cada servicio por separado, sin auditoría y sin control de acceso granular. El Store resuelve eso.

Variables vs. Secretos: diferencias clave

Acá está la confusión más común. Cloudflare ofrece variables de entorno y secretos, y aunque ambos se acceden igual desde el código del Worker (env.NOMBRE), son muy distintos en cómo se almacenan y quién puede verlos.

Característica	Variables de entorno	Secretos
Encriptación	No (texto plano o JSON)	Sí, en reposo y en tránsito
Legibles por admin	Sí, visibles en el dashboard	No, write-only siempre
Visibles en logs	Posible si se imprime	Nunca en texto plano
Casos de uso	Configuración no sensible (entorno, flags, URLs públicas)	API keys, tokens, contraseñas
Modificación	Editable desde dashboard	Sólo reemplazar (no editar)
Compartible entre Workers	No nativamente	Sí, con Secrets Store

La regla es simple: si el dato es sensible, va como secreto. Si es configuración que podría estar en un README, va como variable. Muchos equipos usan variables para cosas como tokens de acceso a sus propias APIs internas (¡error!) porque “es más fácil de ver en el dashboard”. Eso es un problema de seguridad esperando pasar.

Cómo configurar secretos con Wrangler paso a paso

El flujo con Wrangler y secretos per-Worker es directo. Primero, autenticarse:

wrangler login

Después, para agregar un secreto:

wrangler secret put OPENAI_API_KEY

Wrangler te pide el valor de forma interactiva (no queda en el historial de comandos del shell). Para producción con un archivo de secretos, podés usar wrangler deploy --secrets-file secrets.json, donde el archivo tiene el formato {"OPENAI_API_KEY": "sk-..."}. Te puede servir nuestra cobertura de integración de secrets en pipelines de CI/CD.

Para desarrollo local, el equivalente es el archivo .dev.vars en la raíz del proyecto. Tiene formato similar a .env:

OPENAI_API_KEY=sk-tu-key-aqui
STRIPE_SECRET=sk_test_...

Ese archivo nunca debe subir al repositorio. Agregalo a .gitignore junto con cualquier .env. Si ya lo commiteaste una vez, rotar las credenciales y asumir que están comprometidas.

¿Y cómo accedés al secreto desde el Worker? Exactamente igual que a una variable:

export default {
  async fetch(request, env) {
    const apiKey = env.OPENAI_API_KEY;
    // nunca loguear apiKey
  }
};

Cloudflare Secrets Store: gestión centralizada a nivel de cuenta

El problema con los secretos per-Worker es que no escalan. Si tenés 15 Workers que todos usan la misma API key de Stripe, tenés ese secreto duplicado 15 veces. Cuando rotás la key, tenés que actualizarla en 15 lugares. (Y siempre te olvidás de uno, garantizado.)

Secrets Store resuelve eso. Según el anuncio de la beta pública, las capacidades nuevas incluyen:

• Almacenamiento a nivel de cuenta: un secreto se define una vez y se puede vincular a múltiples Workers.
• RBAC granular: los roles de Cloudflare determinan quién puede crear, leer metadatos, o administrar secretos. El valor en sí nunca es legible.
• Auditoría de cambios: cada creación, rotación o eliminación queda registrada con timestamp y actor.
• Límites actuales en beta: 100 secretos por cuenta, máximo 1 KB por secreto.
• Integración con Workers y Snippets: el binding se declara en wrangler.toml.

Para vincular un secreto del Store a un Worker, el wrangler.toml queda así: Tema relacionado: automatizar la gestión de secretos en CI/CD.

[[secrets_store_secrets]]
binding = "STRIPE_KEY"
secret_name = "stripe-production-key"
store_id = "tu-store-id"

Y desde el código, accedés igual: env.STRIPE_KEY. Sin cambios en la lógica del Worker.

Casos de uso prácticos

Ponele que tenés un Worker que actúa como proxy para OpenAI: recibe requests de tu app, agrega la API key y reenvía. Con secretos per-Worker configurás el OPENAI_API_KEY una vez y listo. Si sólo es ese Worker, alcanza.

Pero si también tenés un Worker de logging, otro de rate limiting, y un Snippet de WAF que hace autorización condicional (verificar si el token del request es válido contra un servicio propio), los tres necesitan credenciales. Acá Secrets Store tiene sentido: un secreto internal-auth-token se define a nivel de cuenta y los tres servicios lo consumen. Cuando lo rotás, lo cambiás en un lugar.

Otros casos concretos que aparecen seguido:

• Tokens de GitHub para Workers de CI/CD que comentan en PRs automáticamente.
• Credenciales de base de datos para Workers que actúan como BFF (backend-for-frontend).
• API keys de servicios de email transaccional en Workers de formularios de contacto.
• Tokens de webhook para verificar firmas en eventos de Stripe o GitHub.

Herramientas y automatización

Para equipos que manejan secretos en pipelines de CI/CD, el flujo con GitHub Actions es bastante limpio. Las keys van como secrets del repositorio en GitHub, y en el workflow se pasan a Wrangler:

- name: Deploy Worker
  env:
    CLOUDFLARE_API_TOKEN: ${ secrets.CF_API_TOKEN }
  run: wrangler deploy --secrets-file <(echo '{"OPENAI_API_KEY":"${ secrets.OPENAI_KEY }"}') Más contexto en configuración multiidioma en aplicaciones.

Hay un proyecto open source, cloudflare-secrets-manager en GitHub, que permite sincronizar automáticamente desde un archivo .env a los Workers. Es útil para migraciones o equipos que ya tienen un flujo basado en .env y quieren adoptarlo en Cloudflare sin reescribir todo. Tomalo con pinzas en producción, igual: el proyecto es comunitario, no oficial de Cloudflare.

La CLI oficial de Cloudflare también permite gestionar Secrets Store directamente:

wrangler secrets-manager secret create --name "stripe-key" --store-id "tu-id"

Mejores prácticas de seguridad

La parte técnica es la fácil. Lo que falla en producción es el proceso:

• Nunca hardcodear secretos en el código. Parece obvio hasta que ves el commit con la key en el historial de un repo público.
• Nunca usar variables de entorno para datos sensibles. Las vars son visibles en el dashboard para cualquier miembro del equipo con acceso.
• El .dev.vars y los .env van en .gitignore antes del primer commit, no después.
• Rotar secretos regularmente, especialmente claves de servicios de pago y APIs con permisos amplios.
• Usar RBAC en Secrets Store para limitar quién puede crear o administrar secretos. No todos necesitan acceso de escritura.
• Auditar el acceso periódicamente. Con Secrets Store podés ver quién creó o modificó cada secreto y cuándo.

Eso sí: el cifrado en tránsito y en reposo que ofrece Cloudflare no te exime de buenas prácticas del lado de tu código. Si loqueás el valor de env.API_KEY en un console.log de debugging (que queda en los Workers Logs), de nada sirve que el secreto esté encriptado en el storage.

Qué está confirmado y qué no

Confirmado según la documentación oficial y el blog de Cloudflare:

• Secrets Store está en public beta desde Developer Week 2025.
• Límite de 100 secretos por cuenta y 1 KB por secreto durante la beta.
• RBAC y auditoría de cambios disponibles en la beta.
• Compatibilidad con Workers y Snippets confirmada; Pages Functions no mencionada en la beta.
• Secretos encriptados en reposo y en tránsito; write-only (ningún rol puede leer el valor en texto plano).

No confirmado / pendiente:

• Precios post-beta. Cloudflare no anunció un modelo de precios para Secrets Store en producción.
• Límites finales (los 100 secretos son límite de beta, pueden cambiar).
• Soporte nativo para rotación automática de secretos (no mencionado en los anuncios).
• Disponibilidad en todos los planes o sólo planes pagos.

Errores comunes al gestionar secretos en Cloudflare Workers

Error 1: Commitear el archivo .dev.vars. Es el más frecuente y el más costoso. Pasa porque el archivo se crea, se lo usa en local, y nadie recuerda agregarlo al .gitignore hasta que ya está en el historial. La solución es agregarlo a .gitignore antes de crear el archivo, no después. Si ya está commiteado: rotar todas las credenciales del archivo, punto.

Error 2: Usar variables de entorno para tokens de autenticación. Las vars se muestran en texto plano en el dashboard de Cloudflare a cualquier usuario del equipo con acceso. Un AUTH_TOKEN como variable de entorno es básicamente público para el equipo. Tiene que ser secreto. Lo explicamos a fondo en optimizar e-commerce con Cloudflare.

Error 3: No rotar los secretos después de cambios de equipo. Cuando alguien que tenía acceso de escritura a los secretos de Workers se va del equipo, esos secretos deberían rotarse. No hay una alerta automática para esto. Si no tenés un proceso documentado, no va a pasar.

Error 4: Usar Secrets Store beta en Workers de producción críticos sin un plan de fallback. Es beta. Los límites pueden cambiar, el comportamiento también. Para Workers de alto tráfico o pagos, los secretos per-Worker (el método clásico) son más estables por ahora.

Preguntas Frecuentes

¿Cómo almacenar claves API de forma segura en Cloudflare Workers?

Usá wrangler secret put NOMBRE_CLAVE para crear un secreto encriptado asociado a tu Worker. El valor queda encriptado en reposo y en tránsito, y se accede desde el código con env.NOMBRE_CLAVE sin que sea legible en el dashboard. Para desarrollo local, creá un archivo .dev.vars con el valor en texto plano y agregalo a .gitignore de inmediato.

¿Cuál es la diferencia entre variables y secretos en Cloudflare?

Las variables de entorno son texto o JSON sin encriptar, visibles en el dashboard de Cloudflare para cualquier miembro del equipo. Los secretos están encriptados, son write-only (una vez guardados, nadie puede leer el valor, ni administradores ni Cloudflare), y están pensados para datos sensibles como API keys o contraseñas. La forma de accederlos desde el código del Worker es idéntica en ambos casos.

¿Cómo usar Cloudflare Secrets Store en múltiples Workers?

Creás el secreto una vez en Secrets Store a nivel de cuenta, y lo vinculás a cada Worker que lo necesite a través del wrangler.toml con un bloque [[secrets_store_secrets]]. Cuando rotás el secreto en el Store, todos los Workers vinculados usan el valor nuevo automáticamente sin necesidad de redesplegar. Esta funcionalidad está en public beta desde Developer Week 2025.

¿Qué comando usar para sincronizar secretos con Wrangler?

wrangler secret put NOMBRE agrega o reemplaza un secreto para el Worker actual. Para subir múltiples secretos en un deploy, usá wrangler deploy --secrets-file archivo.json donde el JSON tiene el formato {"CLAVE": "valor"}. Para listar los secretos existentes (sólo los nombres, no los valores): wrangler secret list.

¿Cuánto cuesta Cloudflare Secrets Store?

Durante la beta pública no hay información de precios publicada por Cloudflare. El producto está disponible para cuentas con acceso a la beta, con un límite de 100 secretos por cuenta y 1 KB por secreto. Los precios finales post-beta no fueron anunciados al momento de publicación de este artículo.

Conclusión

Cloudflare Secrets Manager, en sus dos formas (per-Worker y Secrets Store centralizado), cubre una necesidad real que antes se resolvía con parches: duplicar secretos en cada Worker, confiar en que nadie miraba el dashboard, o peor, hardcodear credenciales en el código.

El lanzamiento de Secrets Store en beta durante 2025 es el paso que le faltaba para equipos con infraestructura distribuida en Workers. RBAC, auditoría y un secreto único para múltiples Workers son características que en otros servicios de gestión de secretos (como HashiCorp Vault o AWS Secrets Manager) existen hace años. Cloudflare las trae integradas en su propio ecosistema, sin necesidad de un servicio externo adicional.

Si hoy ya tenés Workers en producción, la migración a secretos (si aún usás variables para datos sensibles) debería ser prioritaria. Si tenés más de 5 Workers compartiendo secretos, vale la pena entrar a la beta de Secrets Store y evaluar si reemplaza tu flujo actual. Los límites de la beta (100 secretos, 1 KB) son suficientes para la mayoría de los casos de uso. Si tu infraestructura está hosteada en donweb.com y migrás parte de tu edge logic a Workers, este es el momento de hacerlo bien desde el principio.

¿El único punto pendiente? Los precios post-beta. Hasta que Cloudflare los publique, para Workers críticos de producción los secretos per-Worker siguen siendo la opción más predecible.

Fuentes

• Cloudflare Blog – Secrets Store: anuncio oficial
• Cloudflare Developers – Configuración de secretos en Workers
• Cloudflare Developers – Documentación de Secrets Store
• Cloudflare Blog – Secrets Store beta pública
• GitHub – cloudflare-secrets-manager (herramienta comunitaria)