Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Portugal)
Esta página foi traduzida automaticamente. Ler 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 ser bifurcados, que é possível compilar com a CLI aggrega. Cada um é um diretório autónomo — um Aggregate escrito pelo programador e um ou mais pares Release/Manifest — que é compilado sem qualquer configuração para além do que a sua página indica. Para encontrar um pelo produto que implementa ou pelo que mostra, use-se Exemplos por produto e capacidade, que enumera todos os exemplos aqui presentes.

Os exemplos existem em dois modos — as duas extremidades de um mesmo percurso de aprendizagem:

  • Consumo — o workspace referencia entidades do catálogo da biblioteca standard e escreve localmente apenas o seu próprio conteúdo didático específico. É compilado sem a flag --catalog:

    Terminal window
    aggrega build --release release.yaml

    O local de onde essas entidades referenciadas são lidas depende do workspace. Um diretório catalog/ na raiz do workspace é lido quer algo o nomeie, quer não, pelo que um workspace que escreve conteúdo didático próprio pode simplesmente mantê-lo aí. Um workspace que contém um .aggrega-config.yaml lê também cada diretório enumerado em catalog_dirs, cada um deles um diretório onde guarda entidades. Os diretórios enumerados são pesquisados primeiro e catalog/ em último lugar, e na pilha ganha a primeira ocorrência, pelo que uma entidade num diretório pesquisado antes oculta outra com a mesma identidade num posterior. O que nenhum diretório local declara — as entidades da biblioteca standard — é resolvido a partir do registo que a configuração indica 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 através do registo 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, pelo que uma cópia do workspace inteiro levada para outro local é compilada tal 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 respetivo ficheiro de Release, pelo que cada Release é compilada com o seu próprio catálogo.

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

Compile-se uma release por execução com aggrega build --release <release file>; a página de cada exemplo indica os seus próprios comandos. O workspace fornece o seu catálogo como descrito acima; é necessário passar --catalog para um diretório de catálogo que o workspace não nomeia, como mostram as páginas que precisam dele.

Os lockfiles são gerados em vez de distribuídos, pelo que um clone novo não tem nenhum e a primeira compilação precisa de um. aggrega build é apenas de leitura por predefinição: sem lockfile, é interrompido e indica os dois caminhos possíveis. É necessário passar --auto-pull nessa primeira compilação — aggrega build --release release.yaml --auto-pull — para resolver o lockfile durante a compilação; executar aggrega pull --release <release file> uma vez antes faz o mesmo e permite que todas as compilações seguintes sejam executadas sem flag.

Num checkout do repositório da documentação, a maioria dos workspaces contém também um script auxiliar build-release.sh através do qual as verificações próprias do repositório compilam. Executa aggrega build para uma release, mostrando primeiro o comando, e indica que binário aggrega usou e de onde veio esse binário; AGGREGA_BIN permite escolher o binário. Uma cópia escrita por aggrega scaffold --example contém o script auxiliar sem o script partilhado que este chama, pelo que uma cópia assim deve ser compilada diretamente com aggrega build.

Quando um exemplo aqui refere um checkout do catálogo da biblioteca standard, Importação indica 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 remete para o workspace que a mostra; os workspaces aqui são pilhas completas que é possível compilar, ler e adaptar.

Quando uma página mostra o que uma compilação produziu, esse bloco é copiado de uma execução real para que seja possível comparar a própria saída com ele — e as linhas omitidas estão assinaladas. Ler a saída nestas páginas enuncia essa convenção e a marca que usa.

Nem todos os diretórios aqui são um único workspace. Os exemplos de início rápido contêm um workspace por passo, e os exemplos de importação um por fase de uma importação, como descreve o parágrafo seguinte. 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 uma compilação e o recusam quando viola uma regra, com o passo de pipeline de cada um. São executados sobre as saídas dos workspaces aqui presentes, e sobre as de cada utilizador.

Cada exemplo import-* — listado sob a capacidade import em Exemplos por produto e capacidade — guarda um projeto escrito noutro formato tal como aggrega import o encontra, em duas pastas: source/, o projeto, o .aggrega-config.yaml que o torna um workspace e o ficheiro de respostas a partir do qual a importação lê os valores que nenhuma fonte pode conter; e draft/, os ficheiros que a importação escreveu, inalterados, um workspace que compila tal como foi escrito, com o que imprimiu na saída padrão (stdout.txt) e na saída de erro padrão (import.txt). O respetivo guia passo a passo em Importação ensina cada fase. O seu check.sh executa o scripts/check-import-example.sh partilhado deste repositório, que volta a importar, compara o que escreve e imprime com draft/ e os blocos que o guia cita com os ficheiros do exemplo, e depois valida e compila a Release redigida.

A ordem didática

Cada exemplo aqui tem um lugar numa única ordem didática, dada pelo tier e pela position no seu cabeçalho: nível a nível, pela ordem que a lista de níveis indica, e o mais simples primeiro dentro de cada nível. Por ordem didática lista todos os exemplos dessa forma, e a secção Exemplos da barra lateral segue a mesma ordem. Os níveis podem ser lidos de cima para baixo, ou é possível saltar para aquele que corresponde ao que se está a fazer; para encontrar antes um exemplo pelo que implementa ou pelo que mostra, a mesma página lista-os por produto e por capacidade.

Uma compilação também pode executar plugins sobre aquilo que renderiza — consulte Quando recorrer a um passo 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 aprendizagem, os produtos que implementa e o que mostra. Exemplos por produto e capacidade é gerado a partir destes 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 Apenas 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 governação, Features orientadas por anotações e stacks de nuvem montadas.

tier é a parte da ordem de aprendizagem a que o exemplo pertence, um destes escalões, ensinados por esta ordem:

  • start-here — Começar 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 — Apenas 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 governação, Features orientadas por anotações e stacks de nuvem montados, vários deles combinados num único build.
  • importers — Importadores: um projeto escrito noutro formato, convertido em rascunhos de ficheiros Aggrega por aggrega import, depois revisto e compilado.

position é o lugar do exemplo dentro do seu escalão, um número inteiro positivo que nenhum outro exemplo desse escalão ocupa; um escalão enumera os seus exemplos da posição mais baixa para cima, o mais simples primeiro.

products enumera cada Component do catálogo que o exemplo implementa, pelo nome que a sua entrada de catálogo tem. Um componente de computação genérico (core/compute/server, por exemplo) e uma entidade que o exemplo declara para si próprio não são enumerados, pelo que um exemplo pode não enumerar nenhum.

shows enumera o que o exemplo demonstra, cada entrada retirada desta lista:

  • multi-target — um Aggregate compilado para dois ou mais destinos, ou realizado de duas ou mais formas.
  • recipe-selection — o Manifest a escolher qual Recipe realiza um componente, ou qual FeatureRecipe realiza um anexo: por tipo, por instância ou por destino.
  • modules — um Aggregate do catálogo importado como módulo.
  • connections — componentes ligados através de sockets uses, com valores encaminhados através de cada aresta.
  • credentials — anexos de credenciais e a forma como cada destino as entrega.
  • parameters — valores elevados a parâmetros que uma Release cumpre.
  • features — Features anexadas para algo diferente de uma credencial, como encaminhamento, monitorização, um orçamento, uma cache ou mascaramento.
  • boundaries — componentes ou módulos colocados em fronteiras, e aquilo que passa de uma para outra.
  • policy — política de governação que aceita ou recusa uma compilação, durante a compilação ou sobre a sua saída.
  • guardrails — uma Release destinada a 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 geridos.
  • external-sources — uma Recipe que obtém aquilo que renderiza: um chart upstream, um repositório git ou um módulo.
  • import — um projeto escrito noutro formato, convertido em rascunhos de ficheiros Aggrega por aggrega import e depois revisto e compilado.

Um exemplo enumera pelo menos um produto ou uma capacidade, para que o índice o possa posicionar. O seu README inclui também uma secção ## Scaffold the example, que contém aggrega scaffold --example <name> no primeiro bloco de comandos e cd <name> no segundo, seguida diretamente de uma secção ## Build cujo primeiro bloco de comandos é o que aggrega scaffold --example imprime como passo seguinte a executar depois desse cd. scripts/gen-examples-index.sh --check, executado a partir da raiz deste repositório, verifica cada cabeçalho face a estas listas, recusa um exemplo a que falte uma das duas secçõ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 novamente o índice.