Referencia de templates

Un template es un documento YAML con hasta cinco claves de nivel superior. Solo resources es obligatoria; cualquier sección desconocida es un error de validación.

version: "2026-07"          # opcional, informativo
description: Qué hace       # opcional
parameters: { ... }         # entradas del template
resources: { ... }          # los recursos a materializar
outputs: { ... }            # valores que expone el stack

Parámetros

Cada parámetro declara su tipo y, opcionalmente, valor por defecto, valores permitidos y si es sensible:

parameters:
  Ambiente:
    type: string            # string | number | boolean
    description: Ambiente objetivo
    default: sandbox
    allowedValues: [sandbox, production]
  CrmApiKey:
    type: string
    noEcho: true            # sensible: nunca se persiste ni se muestra

• noEcho: true marca el parámetro como sensible: su valor solo existe en memoria durante el despliegue y queda redactado (***noEcho***) en todo lo persistido y en toda respuesta de la API. Un parámetro noEcho no puede tener default.
• Los valores se pasan al crear el stack o al proponer un changeset (parameters en el body, o el formulario del portal).

Recursos

Cada recurso tiene un nombre lógico (la clave), un type de la familia Cortex::* y sus properties. Las dependencias se derivan automáticamente de las referencias; dependsOn existe para forzar orden cuando no hay referencia explícita:

resources:
  CrmTools:
    type: Cortex::ToolSource
    properties:
      kind: mcp
      name: crm
      config: { url: https://crm.example.test/mcp }
    dependsOn: [OtroRecurso]   # opcional

Los ocho tipos disponibles y sus propiedades están en Tipos de recurso.

Nombres. Nombres lógicos y de parámetro siguen ^[A-Za-z][A-Za-z0-9]{0,127}$ (alfanuméricos, empiezan por letra). Un parámetro y un recurso no pueden compartir nombre — haría ambiguo a !Ref.

Funciones intrínsecas

Tres funciones conectan el template:

outputs:
  agentId: !GetAtt Asistente.id
  saludo:
    value: !Sub "Agente ${Asistente.id} desplegado en ${Ambiente}"
    description: Ejemplo de interpolación

Los outputs aceptan la forma corta (nombre: !GetAtt X.id) o la forma con value/description. Un output no puede exponer un valor noEcho.

Forma JSON equivalente. Los tags YAML son azúcar sintáctico; la forma JSON es idéntica tras normalizar, útil para templates generados por máquina:

apiKey: !Ref OpenaiApiKey        # equivale a:
apiKey: { Ref: OpenaiApiKey }

agentId: !GetAtt Asistente.id    # equivale a:
agentId: { "Fn::GetAtt": [Asistente, id] }

texto: !Sub "hola ${Nombre}"     # equivale a:
texto: { "Fn::Sub": "hola ${Nombre}" }

Ningún otro tag YAML personalizado se acepta: el parser corre en modo seguro (sin merge keys, alias limitados).

Orden de despliegue

De las referencias entre recursos Cortex construye un grafo dirigido acíclico y despliega en orden topológico (las dependencias primero); al eliminar, usa el orden inverso. Un ciclo de referencias es un error de validación, igual que un !Ref a un nombre inexistente o un dependsOn roto.

También puedes referenciar por id físico literal (p. ej. modelId: mdl_01H…) un recurso que ya existe en tu tenant y que no forma parte del stack. La validación verifica que exista y sea visible para tu tenant; los ids de otros tenants se rechazan.

Límites

Errores de validación frecuentes

La validación (POST /v1/iac/templates/validate, o el editor del portal) devuelve una lista de errores con la ruta exacta de cada uno. Los más comunes:

• Tipo de recurso desconocido, o sección de nivel superior desconocida.
• Nombre lógico o de parámetro que no cumple el patrón, o colisión parámetro↔recurso.
• !Ref / !GetAtt / dependsOn a un nombre que no existe; ciclos en el grafo.
• Propiedades que violan el contrato del gestor (campo faltante, tipo incorrecto).
• Una credencial escrita como literal donde va una referencia noEcho (apiKey, value).
• Un output que expone un parámetro noEcho.
• Id físico literal inexistente o de otro tenant.
• Template por encima de los límites de tamaño.