Scaffolder: el libro de recetas

Objetivos del capítulo

Diseñar un template YAML del Scaffolder.
Componer con actions built-in (fetch:template, publish:github, catalog:register).
Definir parámetros con un schema JSON Schema.

Scaffolder, el libro de recetas de la IDP

Un chef con prisa no improvisa: coge la receta, sigue los pasos, y al final tiene un plato listo. El Scaffolder es eso: un catálogo de recetas que el developer ejecuta y obtiene un repositorio completo en GitHub, con su catalog-info.yaml registrado en Backstage. Repetible, versionado, auditado.

Construimos el primer template de Sazón Foods en el crate del capítulo.

Anatomía de un template

Un template es un YAML con apiVersion, kind, metadata y spec. La pieza clave es spec.steps: una lista de acciones que el Scaffolder ejecuta en orden.

Unresolved directive in chapters/cap-12-scaffolder-concepto-y-templates.adoc - include::../../chapters/chapter-12-scaffolder/templates/sazon-node-service/template.yaml[tag=template-skeleton]

Las tres partes clave

:code:`parameters` — lo que el developer rellena en el formulario.
:code:`steps` — acciones que se ejecutan (pueden ser built-in o custom).
:code:`output` — qué expone el template al terminar (links, valores).

Actions built-in

Tres actions cubren el 80% de los casos:

Unresolved directive in chapters/cap-12-scaffolder-concepto-y-templates.adoc - include::../../chapters/chapter-12-scaffolder/templates/sazon-node-service/template.yaml[tag=actions-list]

Flujo de un template

Failed to generate image: Could not find the 'mmdc' executable in PATH; add it to the PATH or specify its location using the 'mmdc' document attribute
flowchart LR
  Form["Form parameters"] --> Fetch["fetch:template"]
  Fetch --> Render["Render skeleton con Nunjucks"]
  Render --> Publish["publish:github"]
  Publish --> Repo[("GitHub repo")]
  Publish --> Catalog["catalog:register"]
  Catalog --> Backstage[("Backstage catalog")]

fetch:cookiecutter está deprecado

El plugin fetch:cookiecutter está marcado como deprecated en el repo oficial. Usa :code:`fetch:template` (Nunjucks) en su lugar. Más info en :cap-13.

El template completo

El flujo completo: fetch del esqueleto, publicación en GitHub, registro en el catalog.

Unresolved directive in chapters/cap-12-scaffolder-concepto-y-templates.adoc - include::../../chapters/chapter-12-scaffolder/templates/sazon-node-service/template.yaml[tag=full-template]

input.copyWithoutRender

Algunos archivos del esqueleto (workflows de GitHub, archivos binarios) no deben pasar por Nunjucks. Usa :code:`copyWithoutRender` para evitar el templating en rutas concretas.

Cargar el template en Backstage

Para que el Scaffolder vea el template, lo registramos como una Location del catalog:

catalog:
  locations:
    - type: file
      target: ../../templates/sazon-node-service/template.yaml
      rules:
        - allow: [Template]

Tras reiniciar, aparece en Create… del Scaffolder.

El esqueleto: skeleton/

El esqueleto es un directorio con archivos plantilla. Usa sintaxis Nunjucks:

templates/sazon-node-service/
  template.yaml
  skeleton/
    package.json
    src/index.ts
    README.md
    catalog-info.yaml

Los {{ values.name }} se sustituyen al ejecutar el template.

Example 12. Receta del capítulo

Crea templates/<nombre>/template.yaml y skeleton/.
Define parameters con JSON Schema.
Lista steps con fetch:template, publish:github, catalog:register.
Registra la Location en app-config.yaml.
Ejecuta desde Create… y revisa el repo y el catalog.

Resumen

El Scaffolder es un catálogo de templates YAML.
parameters se valida con JSON Schema.
steps ejecuta acciones built-in o custom.
fetch:template, publish:github y catalog:register cubren el flujo típico.

Glosario del capítulo

template: YAML con apiVersion: scaffolder.backstage.io/v1beta3 que define un flujo generador.
action: Pieza ejecutable de un step. Hay built-in y custom.
Nunjucks: Motor de templating que usa fetch:template para sustituir {{ values.x }}.
skeleton: Directorio con archivos que se renderizan al ejecutar el template.
Location: Apunte en el catalog que carga entidades desde archivos, GitHub o APIs.

Próximo capítulo

Forms, dry-run y un template serio —conditional fields, validación custom, dry-run para auditar.