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.

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: sazon-node-service
  title: Sazón Node Service
  description: Generate a new Node service in the sazon-foods GitHub org
spec:
  owner: platform-sazon
  type: service
  parameters:
    - title: Fill in some steps
      required: [name, owner, repoUrl]
      properties:
        name:
          title: Name
          type: string
          description: Unique service name (kebab-case)
        owner:
          title: Owner
          type: string
          description: Owning group
        repoUrl:
          title: Repository URL
          type: string
  steps:
    - id: fetch
      name: Fetch template
      action: fetch:template
      input:
        url: ./skeleton
        copyWithoutRender:
          - .github/workflows/*.yml
    - id: publish
      name: Publish to GitHub
      action: publish:github
      input:
        repoUrl: ${{ parameters.repoUrl }}
        sourcePath: ./result
        defaultBranch: main
    - id: register
      name: Register in catalog
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
        catalogInfoPath: /catalog-info.yaml

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:

    - id: fetch
      name: Fetch template
      action: fetch:template
      input:
        url: ./skeleton
        copyWithoutRender:
          - .github/workflows/*.yml

Figure 14. Flujo de un template

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.

    - id: publish
      name: Publish to GitHub
      action: publish:github
      input:
        repoUrl: ${{ parameters.repoUrl }}
        sourcePath: ./result
        defaultBranch: main
    - id: register
      name: Register in catalog
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
        catalogInfoPath: /catalog-info.yaml

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.