Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

Exemplos executáveis

Para começar, Primeiros passos instala o Aggrega e percorre passo a passo dois destes exemplos.

Workspaces completos, que podem receber fork, que você pode compilar com a CLI aggrega. Cada um é um diretório autossuficiente — um Aggregate escrito pelo desenvolvedor e um ou mais pares Release/Manifest — cujo build não exige nenhuma configuração além do que a sua página indica. Para encontrar um pelo produto que ele implanta ou pelo que mostra, use Exemplos por produto e capacidade, que lista todos os exemplos daqui.

Os exemplos vêm em dois modos — as duas pontas de um mesmo currículo:

  • Consumo — o workspace referencia entidades do catálogo da biblioteca padrão e escreve localmente apenas o seu próprio conteúdo didático específico. O build é feito sem a flag --catalog:

    Terminal window
    aggrega build --release release.yaml

    De onde essas entidades referenciadas são lidas depende do workspace. Um diretório catalog/ na raiz do workspace é lido quer algo o nomeie ou não, então um workspace que escreve conteúdo didático próprio pode simplesmente mantê-lo ali. Um workspace que contém um .aggrega-config.yaml também lê cada diretório listado em catalog_dirs, cada um deles um diretório em que mantém entidades. Os diretórios listados são pesquisados primeiro e catalog/ por último, e na pilha vence a primeira ocorrência, então uma entidade em um diretório pesquisado antes oculta outra de mesma identidade em um posterior. O que nenhum diretório local declara — as entidades da biblioteca padrão — é resolvido a partir do registro que a configuração nomeia como default_registry, hub.aggrega.ai. Um workspace que não escreve nada localmente não precisa de nenhuma entrada local, e um que não contém nem um diretório catalog/ nem um .aggrega-config.yaml é resolvido inteiramente pelo registro configurado. Escrever catalog_dirs como uma lista vazia indica que o workspace não tem nenhum catálogo local. Cada caminho em catalog_dirs nomeia um diretório dentro do workspace, então uma cópia do workspace inteiro levada para outro lugar faz o build como está.

    Um workspace com vários destinos que mantém um catálogo separado por destino nomeia os diretórios de cada destino em workspace.releases, tendo como chave o seu arquivo de Release, então cada Release faz o build com o seu próprio catálogo.

  • Criação — o workspace constrói do zero as entidades do catálogo (Components, Features, Recipes) em diretórios locais catalog-*/. mariadb-adminer é o exemplo de criação detalhado; as entidades que ele constrói são do mesmo tipo que os exemplos de consumo consomem.

Faça o build de uma release por execução com aggrega build --release <release file>; a página de cada exemplo fornece os seus próprios comandos. O workspace fornece o seu catálogo como descrito acima; passe você mesmo --catalog para um diretório de catálogo que o workspace não nomeia, como mostram as páginas que precisam disso.

Os lockfiles são gerados em vez de distribuídos, então um clone recém-feito não tem nenhum e o primeiro build precisa de um. aggrega build é somente leitura por padrão: sem lockfile, ele é interrompido e nomeia os dois caminhos possíveis. Passe --auto-pull nesse primeiro build — aggrega build --release release.yaml --auto-pull — para resolver o lockfile durante o build; executar aggrega pull --release <release file> uma vez antes faz o mesmo e permite que todos os builds seguintes sejam executados sem flag.

Em um checkout do repositório da documentação, a maioria dos workspaces também contém um script auxiliar build-release.sh por meio do qual as verificações próprias do repositório fazem o build. Ele executa aggrega build para uma release, exibindo primeiro o comando, e informa qual binário aggrega usou e de onde esse binário veio; defina AGGREGA_BIN para escolher o binário. Uma cópia escrita por aggrega scaffold --example contém o script auxiliar sem o script compartilhado que ele chama, então faça o build de uma cópia assim diretamente com aggrega build.

Onde um exemplo daqui menciona um checkout do catálogo da biblioteca padrão, Importação diz onde obter um.

Estes complementam as páginas de conceito descritas em Visão geral dos exemplos: uma página de conceito explica uma ideia e aponta para o workspace que a mostra; os workspaces daqui são pilhas completas que você pode compilar, ler e adaptar.

Onde uma página mostra o que um build produziu, esse bloco é copiado de uma execução real para que você possa comparar a sua própria saída com ele — e as linhas omitidas são marcadas. Lendo a saída nestas páginas enuncia essa convenção e a marca que usa.

Nem todo diretório daqui é um único workspace. Os exemplos de início rápido contêm um workspace por etapa, e os exemplos de importação, um por estágio de uma importação, como descreve o próximo parágrafo. Um diretório não contém nenhum workspace: policy-in-ci contém dois scripts de regras que leem o diretório de saída de um build e o recusam quando ele viola uma regra, com a etapa de pipeline de cada um. Eles são executados sobre as saídas dos workspaces daqui, e sobre as suas.

Cada exemplo import-* — listado sob a capacidade import em Exemplos por produto e capacidade — mantém um projeto escrito em outro formato tal como aggrega import o encontra, em duas pastas: source/, o projeto, o .aggrega-config.yaml que o torna um workspace e o arquivo de respostas do qual a importação lê os valores que nenhuma fonte pode conter; e draft/, os arquivos que a importação escreveu, inalterados, um workspace que compila tal como foi escrito, com o que ela imprimiu na saída padrão (stdout.txt) e na saída de erro padrão (import.txt). O passo a passo correspondente em Importação ensina cada estágio. O seu check.sh executa o scripts/check-import-example.sh compartilhado deste repositório, que importa novamente, compara o que escreve e imprime com draft/ e os blocos que o passo a passo cita com os arquivos do exemplo, e então valida e faz o build da Release redigida.

A ordem didática

Cada exemplo daqui tem um lugar em uma única ordem didática, dada pelo tier e pela position em seu cabeçalho: nível por nível, na ordem que a lista de níveis dá, e o mais simples primeiro dentro de cada nível. Em ordem didática lista cada exemplo dessa forma, e a seção Exemplos da barra lateral segue a mesma ordem. Leia os níveis de cima para baixo, ou vá direto para aquele que corresponde ao que você está fazendo; para encontrar, em vez disso, um exemplo pelo que ele implanta ou pelo que ele mostra, a mesma página os lista por produto e por capacidade.

Um build também pode executar plugins sobre o que renderiza — veja Quando recorrer a uma etapa de pipeline.

O cabeçalho de cada exemplo

O README de cada exemplo começa com um cabeçalho curto, escrito como front matter YAML, que diz o que o exemplo é: o seu nível, o seu lugar na ordem de aprendizado, os produtos que implanta e o que mostra. Exemplos por produto e capacidade é gerado a partir desses cabeçalhos.

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

level é um destes níveis:

  • start — o nível Somente catálogo: montado a partir de entidades do catálogo, sem nada escrito além do Aggregate, do Manifest e da Release.
  • authoring — o nível Criação: escreve um Component, uma Feature ou uma Recipe, ou mostra como um deles é estruturado.
  • advanced — o nível Avançado: fronteiras, política de governança, Features orientadas por anotações e stacks de nuvem montadas.

tier é a parte da ordem de aprendizado à qual o exemplo pertence, uma destas faixas, ensinadas nesta ordem:

  • start-here — Comece aqui: os dois exemplos que o guia “Primeiros passos” faz crescer um passo de cada vez, depois os dois exemplos iniciais para a nuvem.
  • catalog-only — Somente catálogo: montado a partir de entidades do catálogo, sem nada escrito além do Aggregate, do Manifest e da Release.
  • authoring — Criação: escreve um Component, uma Feature ou uma Recipe próprios, ou mostra como um deles é estruturado.
  • advanced — Avançado: fronteiras, políticas de governança, Features orientadas por anotações e stacks de nuvem montados, vários deles combinados em um único build.
  • importers — Importadores: um projeto escrito em outro formato, convertido em rascunhos de arquivos Aggrega por aggrega import, depois revisado e compilado.

position é o lugar do exemplo dentro da sua faixa, um número inteiro positivo que nenhum outro exemplo dessa faixa ocupa; uma faixa lista os seus exemplos da posição mais baixa para cima, o mais simples primeiro.

products lista cada Component do catálogo que o exemplo implanta, pelo nome que a sua entrada de catálogo carrega. Um componente de computação genérico (core/compute/server, por exemplo) e uma entidade que o exemplo declara para si mesmo não são listados, então um exemplo pode não listar nenhum.

shows lista o que o exemplo demonstra, cada entrada tirada desta lista:

  • multi-target — um Aggregate submetido a build para dois ou mais destinos, ou realizado de duas ou mais maneiras.
  • recipe-selection — o Manifest escolhendo qual Recipe realiza um componente, ou qual FeatureRecipe realiza uma vinculação: por tipo, por instância ou por destino.
  • modules — um Aggregate do catálogo importado como módulo.
  • connections — componentes conectados por meio de sockets uses, com valores encaminhados através de cada aresta.
  • credentials — vinculações de credenciais e como cada destino as entrega.
  • parameters — valores elevados a parâmetros que uma Release atende.
  • features — Features vinculadas para algo diferente de uma credencial, como roteamento, monitoramento, um orçamento, um cache ou mascaramento.
  • boundaries — componentes ou módulos colocados em fronteiras, e o que passa de uma para outra.
  • policy — política de governança que aceita ou recusa um build, durante o build ou sobre a sua saída.
  • guardrails — uma Release feita para ser interrompida, e a mensagem com que é interrompida.
  • catalog-authoring — um Component, uma Feature ou uma Recipe escritos para o exemplo, mantidos ao lado dele ou publicados no catálogo.
  • cloud-infrastructure — saída Terraform ou CloudFormation para serviços de nuvem gerenciados.
  • external-sources — uma Recipe que obtém o que renderiza: um chart upstream, um repositório git ou um módulo.
  • import — um projeto escrito em outro formato, convertido em rascunhos de arquivos Aggrega por aggrega import e depois revisado e compilado.

Um exemplo lista pelo menos um produto ou uma capacidade, para que o índice possa posicioná-lo. O seu README também traz uma seção ## Scaffold the example, contendo aggrega scaffold --example <name> no primeiro bloco de comandos e cd <name> no segundo, seguida diretamente de uma seção ## Build cujo primeiro bloco de comandos é o que aggrega scaffold --example imprime como próximo passo a executar depois desse cd. scripts/gen-examples-index.sh --check, executado a partir da raiz deste repositório, verifica cada cabeçalho em relação a essas listas, recusa um exemplo ao qual falte uma das duas seções, e um que não tenha nem um check.sh executável nem um build-release.sh, e confirma que o índice está atualizado; execute-o sem --check para escrever o índice novamente.