Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

Ejemplos ejecutables

Para empezar, Primeros pasos instala Aggrega y recorre paso a paso dos de estos ejemplos.

Workspaces completos, que se pueden bifurcar, que puedes compilar con la CLI aggrega. Cada uno es un directorio autocontenido — un Aggregate escrito por el desarrollador y uno o más pares Release/Manifest — que se compila sin más configuración que la que nombra su página. Para encontrar uno por el producto que despliega o por lo que muestra, usa Ejemplos por producto y capacidad, que enumera todos los ejemplos de aquí.

Los ejemplos vienen en dos modos — los dos extremos de un mismo itinerario de aprendizaje:

  • Consumo — el workspace hace referencia a entidades del catálogo de la biblioteca estándar y solo escribe localmente su propio contenido didáctico específico. Se compila sin el flag --catalog:

    Terminal window
    aggrega build --release release.yaml

    De dónde se leen esas entidades referenciadas depende del workspace. Un directorio catalog/ en la raíz del workspace se lee tanto si algo lo nombra como si no, así que un workspace que escribe contenido didáctico propio puede simplemente guardarlo allí. Un workspace que lleva un .aggrega-config.yaml también lee cada directorio enumerado bajo catalog_dirs, cada uno un directorio en el que guarda entidades. Los directorios enumerados se buscan primero y catalog/ al final, y en la pila gana la primera coincidencia, así que una entidad en un directorio buscado antes oculta a otra de la misma identidad en uno posterior. Lo que ningún directorio local declara — las entidades de la biblioteca estándar — se resuelve desde el registro que la configuración nombra como default_registry, hub.aggrega.ai. Un workspace que no escribe nada localmente no necesita ninguna entrada local, y uno que no lleva ni un directorio catalog/ ni un .aggrega-config.yaml se resuelve por completo a través del registro configurado. Escribir catalog_dirs como una lista vacía indica que el workspace no tiene ningún catálogo local. Cada ruta de catalog_dirs nombra un directorio dentro del workspace, así que una copia del workspace completo llevada a otro lugar se compila tal cual.

    Un workspace con varios destinos que mantiene un catálogo separado por destino nombra los directorios de cada destino bajo workspace.releases, con su archivo de Release como clave, así que cada Release se compila contra su propio catálogo.

  • Creación — el workspace construye desde cero las entidades del catálogo (Components, Features, Recipes) en directorios locales catalog-*/. mariadb-adminer es el ejemplo de creación desarrollado; las entidades que construye son del mismo tipo que las que consumen los ejemplos de consumo.

Compila una release por ejecución con aggrega build --release <release file>; la página de cada ejemplo da sus propios comandos. El workspace aporta su catálogo como se describe arriba; pasa tú mismo --catalog para un directorio de catálogo que el workspace no nombra, como muestran las páginas que lo necesitan.

Los lockfiles se generan en lugar de distribuirse, así que un clon recién hecho no tiene ninguno y la primera compilación necesita uno. aggrega build es de solo lectura por defecto: sin lockfile se detiene y nombra las dos formas de continuar. Pasa --auto-pull para esa primera compilación — aggrega build --release release.yaml --auto-pull — para resolver el lockfile durante la compilación; ejecutar una vez antes aggrega pull --release <release file> hace lo mismo y permite que cada compilación posterior se ejecute sin flag.

En un checkout del repositorio de la documentación, la mayoría de los workspaces también incluyen un script auxiliar build-release.sh a través del cual compilan las comprobaciones propias del repositorio. Ejecuta aggrega build para una release, mostrando primero el comando, e informa de qué binario aggrega usó y de dónde procede ese binario; establece AGGREGA_BIN para elegir el binario. Una copia escrita por aggrega scaffold --example incluye el script auxiliar sin el script compartido al que llama, así que compila una copia así directamente con aggrega build.

Donde un ejemplo de aquí nombra un checkout del catálogo de la biblioteca estándar, Importación indica dónde conseguir uno.

Estos complementan las páginas de conceptos descritas en Resumen de los ejemplos: una página de concepto explica una idea y enlaza el workspace que la muestra; los workspaces de aquí son pilas completas que puedes compilar, leer y adaptar.

Donde una página muestra lo que produjo una compilación, ese bloque está copiado de una ejecución real para que puedas comparar tu propia salida con él — y las líneas omitidas están marcadas. Leer la salida en estas páginas enuncia esa convención y la marca que usa.

No todos los directorios de aquí son un solo workspace. Los ejemplos quickstart contienen un workspace por paso, y los ejemplos de importación uno por etapa de una importación, como describe el párrafo siguiente. Un directorio no contiene ningún workspace: policy-in-ci contiene dos scripts de reglas que leen el directorio de salida de una compilación y lo rechazan cuando incumple una regla, con el paso de pipeline de cada uno. Se ejecutan sobre las salidas de los workspaces de aquí, y sobre las tuyas.

Cada ejemplo import-* — listado bajo la capacidad import en Ejemplos por producto y capacidad — guarda un proyecto escrito en otro formato tal como lo encuentra aggrega import, en dos carpetas: source/, el proyecto, el .aggrega-config.yaml que lo convierte en un workspace y el archivo de respuestas del que la importación lee los valores que ninguna fuente puede contener; y draft/, los archivos que escribió la importación, sin cambios, un workspace que compila tal como está escrito, con lo que imprimió en la salida estándar (stdout.txt) y en la salida de error estándar (import.txt). Su recorrido guiado en Importación enseña cada etapa. Su check.sh ejecuta el script compartido scripts/check-import-example.sh de este repositorio, que vuelve a importar, compara lo que escribe e imprime con draft/ y los bloques que cita el recorrido con los archivos del ejemplo, y luego valida y compila la Release redactada.

El orden didáctico

Cada ejemplo de aquí tiene un lugar en un único orden didáctico, dado por tier y position en su encabezado: nivel por nivel, en el orden que da la lista de niveles, y el más sencillo primero dentro de cada nivel. En orden didáctico lista cada ejemplo de esa manera, y la sección Ejemplos de la barra lateral sigue el mismo orden. Lee los niveles de arriba abajo, o salta al que corresponda a lo que estás haciendo; para encontrar en cambio un ejemplo por lo que despliega o por lo que muestra, la misma página los lista por producto y por capacidad.

Una compilación también puede ejecutar plugins sobre lo que renderiza — consulta Cuándo recurrir a un paso de pipeline.

El encabezado de cada ejemplo

El README de cada ejemplo se abre con un breve encabezado, escrito como front matter de YAML, que dice qué es el ejemplo: su nivel, su lugar en el orden de aprendizaje, los productos que despliega y lo que muestra. Ejemplos por producto y capacidad se genera a partir de estos encabezados.

---
example:
level: start
tier: catalog-only
position: 1
products: [core/datastore/mariadb, core/devtool/adminer]
shows: [connections, credentials]
---

level es uno de estos niveles:

  • start — el nivel Solo catálogo: ensamblado a partir de entidades del catálogo, sin nada escrito salvo el Aggregate, el Manifest y la Release.
  • authoring — el nivel Creación: escribe un Component, una Feature o una Recipe, o muestra cómo se estructura uno.
  • advanced — el nivel Avanzado: límites, política de gobernanza, Features dirigidas por anotaciones y pilas cloud ensambladas.

tier es la parte del orden de aprendizaje a la que pertenece el ejemplo, uno de estos grupos, enseñados en este orden:

  • start-here — Empieza aquí: los dos ejemplos que la guía «Primeros pasos» hace crecer paso a paso, y después los dos ejemplos iniciales para la nube.
  • catalog-only — Solo catálogo: ensamblado a partir de entidades del catálogo, sin nada escrito salvo el Aggregate, el Manifest y la Release.
  • authoring — Creación: escribe un Component, una Feature o una Recipe propios, o muestra cómo se estructura uno.
  • advanced — Avanzado: límites, políticas de gobernanza, Features impulsadas por anotaciones y stacks de nube ensamblados, varios de ellos combinados en un mismo build.
  • importers — Importadores: un proyecto escrito en otro formato, convertido en borradores de archivos Aggrega por aggrega import, y después revisado y compilado.

position es el lugar del ejemplo dentro de su grupo, un número entero positivo que ningún otro ejemplo de ese grupo ocupa; un grupo enumera sus ejemplos desde la posición más baja hacia arriba, primero el más sencillo.

products enumera cada Component del catálogo que el ejemplo despliega, por el nombre que lleva su entrada de catálogo. Un componente de cómputo genérico (core/compute/server, por ejemplo) y una entidad que el ejemplo declara para sí mismo no se enumeran, así que un ejemplo puede no enumerar ninguno.

shows enumera lo que el ejemplo demuestra, cada entrada tomada de esta lista:

  • multi-target — un Aggregate compilado para dos o más destinos, o realizado de dos o más maneras.
  • recipe-selection — el Manifest que elige qué Recipe realiza un componente, o qué FeatureRecipe realiza una vinculación: por tipo, por instancia o por destino.
  • modules — un Aggregate del catálogo importado como módulo.
  • connections — componentes conectados mediante sockets uses, con valores canalizados a través de cada arista.
  • credentials — vinculaciones de credenciales y cómo las entrega cada destino.
  • parameters — valores elevados a parámetros que una Release cumple.
  • features — Features vinculadas para algo distinto de una credencial, como el enrutamiento, la monitorización, un presupuesto, una caché o el enmascaramiento.
  • boundaries — componentes o módulos colocados en límites, y lo que pasa de uno a otro.
  • policy — política de gobernanza que acepta o rechaza una compilación, durante la compilación o sobre su salida.
  • guardrails — una Release pensada para detenerse, y el mensaje con el que se detiene.
  • catalog-authoring — un Component, una Feature o una Recipe escritos para el ejemplo, guardados a su lado o publicados en el catálogo.
  • cloud-infrastructure — salida de Terraform o CloudFormation para servicios cloud gestionados.
  • external-sources — una Recipe que obtiene lo que renderiza: un chart upstream, un repositorio git o un módulo.
  • import — un proyecto escrito en otro formato, convertido en borradores de archivos Aggrega por aggrega import, y después revisado y compilado.

Un ejemplo enumera al menos un producto o una capacidad, para que el índice pueda ubicarlo. Su README también incluye una sección ## Scaffold the example, que contiene aggrega scaffold --example <name> en su primer bloque de comandos y cd <name> en el segundo, seguida directamente de una sección ## Build cuyo primer bloque de comandos es lo que aggrega scaffold --example imprime como siguiente paso a ejecutar después de ese cd. scripts/gen-examples-index.sh --check, ejecutado desde la raíz de este repositorio, comprueba cada encabezado con estas listas, rechaza un ejemplo al que le falte alguna de las dos secciones, y uno que no tenga ni un check.sh ejecutable ni un build-release.sh, y confirma que el índice está al día; ejecútalo sin --check para volver a escribir el índice.