Saltar al contenido principal

Buenas Prácticas

Recomendaciones de uso de la plataforma Nukk, reunidas a partir de las capacidades documentadas en cada área. El objetivo es ayudar a decidir cuándo usar qué — Flow, Backend App, Frontend App, Add-on, ZTNA, Secret, Config Map, MCP — en lugar de listar funcionalidades aisladas.

1. Secrets y Config Maps​

  • Nunca pongas una credencial en texto plano dentro de un Flow, Backend App o Frontend App. Si el valor es sensible (contraseña, token, clave de API, connection string con credencial embebida), es un Secret — el valor queda enmascarado incluso después de guardado.
  • Si el valor es solo configuración por entorno, pero no es confidencial (URL de un servicio, nombre de host, flag de feature), usa un Config Map — no crees un Secret solo para evitar el hardcode; eso esconde información que podría consultarse libremente y dificulta el debugging.
  • Regla práctica: si el valor puede mostrarse en texto plano sin riesgo, es Config Map; si concede acceso a algo, es Secret.
  • Vincula siempre de forma explícita el Secret/Config Map al Flow/App que va a usarlo, en la pestaña correspondiente — que el Secret exista en la plataforma no es suficiente, tiene que ser seleccionado en el consumidor.
  • Usa properties diferentes por entorno (test, production) dentro del mismo Secret/Config Map (ej: HOST, PASSWORD) en lugar de crear un Secret por entorno — así la misma expresión ({$.env.nombre.property}) sigue funcionando en cualquier entorno sin cambiar el código del Flow/App.
  • Nombra Secrets y Config Maps de forma que el propósito quede obvio (db-credentials, db-config) — facilita auditar quién usa qué.

2. API Management​

  • Trata el API Gateway como la única puerta de entrada para las APIs — no crees caminos alternativos de exposición directa de un Backend App o Flow más allá de lo necesario; centralizar en Routes facilita seguridad, rate limit y observabilidad.
  • Toda API que va a producción debería tener Security Type = API Key (o equivalente), con un Consumer dedicado por integración/cliente — evita reutilizar el mismo Consumer para múltiples sistemas, para poder revocar/limitar el acceso de un consumidor sin afectar a los demás.
  • Configura rate limits (por segundo y por minuto) compatibles con la capacidad real del backend — un Consumer sin límite puede tumbar un Flow/App downstream en caso de uso indebido o de un bug del lado del cliente.
  • Ajusta los timeouts (read/send/connect) al comportamiento real de la integración — mantener el valor por defecto de ~60s en toda ruta esconde lentitud; las rutas rápidas deberían tener timeouts más agresivos para fallar rápido, y las integraciones lentas por naturaleza necesitan timeouts mayores para no cortar respuestas válidas.
  • Crea una Route solo cuando la intención sea realmente exponer la API al consumidor final — los Flows y Backend Apps internos, que solo se comunican entre sí, no necesitan una Route pública.

3. Cuándo usar un Flow (integración y automatización)​

Usa un Flow cuando el problema sea esencialmente orquestar llamadas entre sistemas — consultar una base de datos, llamar a una API externa, transformar un payload, enviar una notificación, reaccionar a un evento o a una programación. Es el lugar correcto para:

  • Integraciones con CRMs, ERPs, proveedores de nube, bases de datos, mensajería — el catálogo de conectores ya resuelve autenticación, serialización y retry, así que la integración queda solo en la configuración de los campos, no en código de bajo nivel.
  • Automatizaciones disparadas por Scheduler, webhook (HTTP), evento (Event Consumer) o mensaje (WhatsApp Trigger) — cualquier proceso que "ocurre cuando pasa X", sin necesidad de una interfaz propia.
  • Lógica que se beneficia de IA dentro del propio flujo (componente AI Agent) — interpretar texto libre, resumir documentos, decidir dinámicamente entre múltiples subtareas.

No fuerces a un Flow a convertirse en una aplicación completa. Si la necesidad es una interfaz de usuario rica, o una lógica de dominio compleja con muchas reglas de negocio versionadas en código, considera un Backend/Frontend App y usa el Flow solo para la parte de integración/orquestación.

Buenas prácticas dentro del Flow:

  • Configura siempre caminos de error (executionOnError) en los conectores críticos — un Flow sin manejo de errores falla silenciosamente o tumba la ejecución entera por un problema puntual de un sistema externo.
  • Sepáralo en módulos cuando el Flow crece — aísla la lógica de negocio reutilizable de la parte que es solo disparador/exposición (API, Scheduler), para poder reaprovechar la misma lógica desde diferentes triggers sin duplicar conectores.
  • Usa el FlowSpec (JSON) para revisar la configuración completa antes de publicar un cambio importante, especialmente en flujos con muchos conectores encadenados.
  • Después del build, configura una Route en API Management solo si el Flow realmente necesita ser llamado desde afuera — los Flows disparados por Scheduler o Event Consumer normalmente no necesitan ninguna ruta.

4. Backend Apps vs. Frontend Apps​

  • Usa Backend App para APIs y workers con lógica de dominio propia, versionada como código (no como configuración visual) — especialmente cuando la lógica es demasiado compleja para caber cómodamente en un Flow, o cuando el equipo ya tiene un servicio existente para importar vía GitHub.
  • Usa Frontend App para pantallas, dashboards y páginas — la publicación es más simple (build + deploy ya genera un link público), sin necesidad de una Route en API Management.
  • En ambos, un Dockerfile correcto es obligatorio al importar desde GitHub — valida localmente que la imagen se construye y levanta en el puerto configurado antes de importar, para no descubrir el problema recién en el build de la plataforma. Al crear vía vibe code, la plataforma ya resuelve esto — prefiere ese camino cuando no haya necesidad de traer un repositorio ya existente.
  • Backend App: configura correctamente el endpoint de documentación de la API para obtener el preview en Swagger — funciona de forma nativa en Java Quarkus, y también en otros stacks (ej: Node/Next.js) siempre que el endpoint del Swagger esté expuesto por la aplicación. Es la forma más rápida de validar contratos de API durante el desarrollo. Después del deploy, recuerda configurar la Route en API Management si la API debe ser pública — ese paso es fácil de olvidar y es una causa común de "la API está deployada pero no responde desde afuera".
  • Frontend App: usa el Preview (live preview) para validar la interfaz antes de cada build, y el AI Copilot para acelerar tareas repetitivas (error handling, refactor, tests) directamente en el IDE del app.
  • Vincula Secrets/Config Maps por entorno desde el principio (ej: URL de API diferente en test y production) — evita hardcodear URL/configuración que solo aparece como bug al momento de promover a producción.

5. Piensa en Add-ons antes de construir la infraestructura tú mismo​

Antes de levantar una base de datos, un caché o una capa de autenticación manualmente dentro de un Backend/Frontend App, verifica si un Add-on ya lo resuelve:

  • ¿Necesitas autenticación/SSO/OAuth2? Usa el add-on FusionAuth en lugar de implementar el login desde cero.
  • ¿Necesitas una base relacional? Usa el add-on PostgreSQL — ya viene con backups automáticos configurables, evitando tener que montar una rutina de backup manualmente.
  • ¿Necesitas caché, sesión o pub/sub en memoria? Usa el add-on Cache (Valkey), eligiendo el Persistence Mode según la necesidad real (caché puro descartable vs. dato que necesita sobrevivir a un reinicio).

Esto reduce el tiempo de setup, centraliza el parcheo/mantenimiento de la infraestructura en la plataforma, y mantiene al Backend/Frontend App enfocado solo en la lógica de la aplicación.

Cuándo usar Cloudflare ZTNA​

Usa el add-on Cloudflare ZTNA cuando necesites exponer un Flow, App u otro Add-on sin abrir puertos en el entorno y sin depender de una Route pública tradicional en API Management — por ejemplo, para dar acceso a un panel administrativo interno, a un entorno de homologación restringido a un grupo de usuarios, o a cualquier servicio que no debería quedar expuesto directamente en internet. Prefiere API Management cuando el objetivo sea una API pública, con Consumers y rate limit; prefiere ZTNA cuando el objetivo sea acceso controlado vía Zero Trust, especialmente para interfaces administrativas o entornos no destinados al público general.

6. Usa el MCP en tu flujo de desarrollo​

Conecta tu asistente de IA (Claude Code, Claude, GitHub Copilot) vía MCP desde el inicio de un proyecto, no solo cuando ya ocurrió un problema:

  • Pídele al asistente que consulte los Secrets y Config Maps vinculados a un Flow/App antes de investigar un bug de configuración — es más rápido que navegar manualmente por la plataforma.
  • Usa el asistente para subir un Flow, hacer deploy de un app, o inspeccionar Routes/Consumers directamente desde la conversación, manteniendo el contexto de código e infraestructura en el mismo lugar.
  • Aprovecha la consulta de observabilidad (logs, métricas) por MCP para acelerar el debugging sin cambiar de pantalla a cada hipótesis.
  • Recuerda que ninguna operación de eliminación es expuesta por el MCP — es seguro para diagnóstico y acciones constructivas, pero la remoción de recursos todavía tiene que hacerse manualmente en la plataforma.

7. Observabilidad y costo — hábito, no excepción​

  • Configura Monitoring y revisa Top Errored Executions con regularidad, no solo cuando un usuario reclama — los problemas suelen aparecer en el monitoreo antes de convertirse en incidente.
  • Usa el Trace para entender exactamente en qué etapa una ejecución lenta o con error está gastando tiempo, en lugar de adivinar por el comportamiento externo.
  • Sigue Usage por entorno y por tipo de recurso — comparar Test con Production, y separar el costo de infraestructura del costo de tokens de IA, ayuda a identificar rápidamente si un recurso está sobredimensionado o si el gasto de IA está sano.