Developer Control Plane
The catalog, the app declaration and the golden paths: where the developer starts
Developer Control Plane
O catálogo, a declaração da app e os golden paths: por onde o dev começa
What we want to say: the developer enters the platform here: the catalog says who the app is, the declaration says what it needs, and the golden path creates both at once.
Route of this deck: the Software Catalog, the App Declaration and the Golden Paths, in the order a developer meets them.
O que queremos dizer: o dev entra na plataforma por aqui: o catálogo diz quem a app é, a declaração diz do que ela precisa, e o golden path cria os dois de uma vez.
Roteiro deste deck: o catálogo de software, a declaração da app e os golden paths, na ordem em que o dev os encontra.
The Developer Control Plane has three pieces: catalog, app declaration and golden paths
Developer Control Plane
Source: platformengineering.org/platform-tooling · planes as parallel layers; the journey order is ours
O Developer Control Plane tem três peças: catálogo, declaração da app e golden paths
Developer Control Plane
Fonte: platformengineering.org/platform-tooling · planes as parallel layers; the journey order is ours
What we want to say: the developer enters here: the catalog says who the app is, the declaration says what it needs, and the golden path creates both at once.
The three boxes are the three acts of this deck, one slide of the drawing for each.
O que queremos dizer: o dev entra por aqui: o catálogo diz quem a app é, a declaração diz do que ela precisa, e o golden path cria os dois de uma vez.
As três caixas são os três atos deste deck, um slide do desenho para cada uma.
The catalog says what exists and who owns it
Software Catalog
Source: platformengineering.org/platform-tooling · planes as parallel layers; the journey order is ours
O catálogo diz o que existe e quem é dono
Software Catalog
Fonte: platformengineering.org/platform-tooling · planes as parallel layers; the journey order is ours
What we want to say: the first item of the Developer Control Plane is the catalog: the map of what exists and of who answers for each thing.
Unlike the platformengineering.org landscape, the Portal is not in here: it becomes a client of the platform, like the CLI and the agents. We show that after the planes.
O que queremos dizer: o primeiro item do Developer Control é o catálogo: o mapa do que existe e de quem responde por cada coisa.
Diferente do landscape do platformengineering.org, o Portal não está aqui dentro: ele vira um cliente da plataforma, como a CLI e os agentes. Mostramos isso depois dos planes.
The catalog answers what exists and who owns it
The catalog answers
- Question: what exists?
- Question: who owns it?
O catálogo responde o que existe e quem é dono
O catálogo responde
- Pergunta: o que existe?
- Pergunta: quem é dono?
What we want to say: the catalog answers what exists and who owns it.
The catalog is the register of the organization's software, kept next to the code. The portal is one way to see it; it comes back after the planes, as a client of the platform.
What exists: the inventory of today's services, APIs, databases and queues.
Who owns it: the question that is worth the most. Every Component, API, Resource and System has an owner (the Backstage model). Without an owner, the catalog becomes a dead list.
It goes back to the tribal knowledge of the first act: "whom do I ask?" no longer depends on who happens to know, and gets a written answer that serves the developer and the agent.
An account from "The platform engineering illusion": a Backstage launched with 43 services in the catalog, 12 of them out of date, and everybody celebrating the launch.
Source: references/backstage-catalog.md, references/platform-illusion.md
Sources:
- Backstage Software Catalog: system model, FAQ and life of an entity
- The Platform Engineering Illusion
O que queremos dizer: o catálogo responde o que existe e quem é dono.
O catálogo é o registro do software da organização, mantido junto do código. O portal é uma das formas de vê-lo; ele volta depois dos planes, como cliente da plataforma.
O que existe: o inventário de serviços, APIs, bancos e filas de hoje.
Quem é dono: a pergunta que mais vale. Todo Component, API, Resource e System tem owner (modelo do Backstage). Sem dono, o catálogo vira lista morta.
Volta ao conhecimento tribal do primeiro ato: "a quem eu pergunto?" deixa de depender de quem sabe e passa a ter uma resposta escrita, que serve ao dev e ao agente.
Um relato de "The platform engineering illusion": um Backstage lançado com 43 serviços no catálogo, 12 deles desatualizados, e todo mundo comemorando o lançamento.
Fonte: references/backstage-catalog.md, references/platform-illusion.md
Fontes:
The catalog sees the software in two ways: through the business and through engineering
The catalog has two views
- Business view: how leadership sees it
- Engineering view: how teams build it
O catálogo enxerga o software de dois jeitos: pelo negócio e pela engenharia
O catálogo tem duas visões
- Visão de negócio: como a liderança o vê
- Visão de engenharia: como os times o constroem
What we want to say: the same catalog serves those who talk business and those who build.
Business view: how product and leadership see the software. Engineering view: how the teams build it.
The same catalog links the two: every piece that is built belongs to a business capability. The next two slides open each view.
Source: references/backstage-catalog.md
Sources:
O que queremos dizer: o mesmo catálogo serve a quem fala de negócio e a quem constrói.
Visão de negócio: como produto e liderança enxergam o software. Visão de engenharia: como os times o constroem.
O mesmo catálogo liga as duas: cada peça construída pertence a uma capacidade de negócio. Os próximos dois slides abrem cada visão.
Fonte: references/backstage-catalog.md
Fontes:
The business view groups the software by area and by capability
Business view
- Domain: a business area
- System: a capability with public APIs
A visão de negócio agrupa o software por área e por capacidade
Visão de negócio
- Domain: uma área de negócio
- System: uma capacidade com APIs públicas
What we want to say: the business view groups the software by area and by capability.
Domain: groups Systems that share terminology, model and business purpose, a bounded context.
System: the set of Components and Resources that delivers a capability and exposes one or more public APIs, hiding the implementation from those who consume it.
Source: references/backstage-catalog.md
Sources:
O que queremos dizer: a visão de negócio agrupa o software por área e por capacidade.
Domain: agrupa Systems que compartilham terminologia, modelo e propósito de negócio, um bounded context.
System: o conjunto de Components e Resources que entrega uma capacidade e expõe uma ou mais APIs públicas, escondendo a implementação de quem consome.
Fonte: references/backstage-catalog.md
Fontes:
The engineering view shows what is built, how the pieces talk and what they depend on
Engineering view
- Component: what you build and deploy
- API: the boundary between components
- Resource: what it needs at runtime
A visão de engenharia mostra o que se constrói, como as peças conversam e do que dependem
Visão de engenharia
- Component: o que você constrói e entrega
- API: a fronteira entre components
- Resource: o que ele precisa em runtime
What we want to say: the engineering view shows what is built, how the pieces talk and what they depend on.
Acronym: API (Application Programming Interface) is the boundary between Components.
Component: the piece of software: a service, a website, a data pipeline. API: the boundary between Components, in a machine-readable format. Resource: the infrastructure the Component needs at runtime: a database, a queue, a bucket.
Every Component belongs to a System, which belongs to a Domain, and that is where the two views meet. The next slides show each entity with a familiar example.
Source: references/backstage-catalog.md
Sources:
O que queremos dizer: a visão de engenharia mostra o que se constrói, como as peças conversam e do que dependem.
Sigla: API (Application Programming Interface) é a fronteira entre Components.
Component: a peça de software: serviço, site, pipeline de dados. API: a fronteira entre Components, em formato legível por máquina. Resource: a infraestrutura de que o Component precisa em runtime: banco, fila, bucket.
Cada Component pertence a um System, que pertence a um Domain, e é aí que as duas visões se encontram. Os próximos slides mostram cada entidade com um exemplo conhecido.
Fonte: references/backstage-catalog.md
Fontes:
A Component is a piece of software that someone maintains and delivers
Component
- What: software you build and deploy
Component é uma peça de software que alguém mantém e entrega
Component
- O quê: software que você constrói e entrega
What we want to say: a Component is the software that a team maintains and delivers: a service, a website, a library, a data pipeline.
Source: references/backstage-catalog.md
Sources:
O que queremos dizer: Component é o software que um time mantém e entrega: serviço, site, biblioteca, pipeline de dados.
Fonte: references/backstage-catalog.md
Fontes:
The seat-selection service, from the example catalog of Tailwind Air, is a Component
- Component:
seat-selection, a service - Does: shows the free seats, holds the seat a passenger picks
O seat-selection, do catálogo de exemplo da Tailwind Air, é um Component
- Component:
seat-selection, um serviço - Faz: mostra os assentos livres, guarda o assento que o passageiro escolhe
What we want to say: seat-selection is the service that shows the seat map and books the seat the passenger picks.
It comes from the example catalog of the first proof of concept, which models Tailwind Air, a fictional airline.
O que queremos dizer: seat-selection é o serviço que mostra o mapa de assentos e reserva o assento que o passageiro escolhe.
Vem do catálogo de exemplo da primeira prova de conceito, que modela a Tailwind Air, uma companhia aérea fictícia.
An API is the contract between Components
API
- What: the contract between components
API é o contrato entre Components
API
- O quê: o contrato entre components
What we want to say: the API is the contract; whoever consumes it depends on the contract, not on the implementation.
Acronym: API (Application Programming Interface).
It is a machine-readable boundary (OpenAPI, AsyncAPI, gRPC, GraphQL).
Source: references/backstage-catalog.md
Sources:
O que queremos dizer: API é o contrato; quem consome depende dele, não da implementação.
Sigla: API (Application Programming Interface).
É uma fronteira legível por máquina (OpenAPI, AsyncAPI, gRPC, GraphQL).
Fonte: references/backstage-catalog.md
Fontes:
The web-checkin Component consumes the seats API, provided by the seat-selection Component
- API:
seats, a REST API, provided byseat-selection - Consumed by:
web-checkin, a website
O Component web-checkin consome a API seats, fornecida pelo Component seat-selection
- API:
seats, uma API REST, fornecida peloseat-selection - Consumida por:
web-checkin, um site
What we want to say: the check-in website web-checkin (type: website) consumes the seats API (consumesApis), which the seat-selection microservice (type: service) exposes (providesApis). The type comes from the spec.type field of each Component in the Tailwind Air catalog.
seat-selection is the Component (type: service), the service that runs; the API is seats, the contract it provides and web-checkin consumes. The name says what the piece does, and the type stays in spec.type, which is what the catalog filters by: a Component named *-api confuses the service with the contract, and a *-service repeats the type.
O que queremos dizer: o site de check-in web-checkin (type: website) consome a API seats (consumesApis), que o microsserviço seat-selection (type: service) expõe (providesApis). O tipo vem do campo spec.type de cada Component no catálogo da Tailwind Air.
seat-selection é o Component (type: service), o serviço que roda; a API é seats, o contrato que ele fornece e que o web-checkin consome. O nome diz o que a peça faz, e o tipo fica no spec.type, por onde o catálogo filtra: um Component chamado *-api confunde o serviço com o contrato, e um *-service repete o tipo.
A Resource is the infrastructure a Component needs to run
Resource
- What: infrastructure needed at runtime
Resource é a infraestrutura de que o Component precisa para rodar
Resource
- O quê: infraestrutura necessária em runtime
What we want to say: a Resource is the infrastructure the Component needs to run: a database, a queue, a bucket.
A hook for the Resource Plane: here the Resource is described by its role (database); there it becomes a concrete service.
Source: references/backstage-catalog.md
Sources:
O que queremos dizer: Resource é a infraestrutura de que o Component precisa para rodar: banco, fila, bucket.
Gancho para o Resource Plane: aqui o Resource é descrito pelo papel (database); lá vira um serviço concreto.
Fonte: references/backstage-catalog.md
Fontes:
The seat-selection service depends on the passengers-db database
- Resource:
passengers-db, a database - Used by:
seat-selection, owned by thereservationssystem
O seat-selection depende do banco passengers-db
- Resource:
passengers-db, um banco de dados - Usado por:
seat-selection, de propriedade do systemreservations
What we want to say: the seat-selection microservice (type: service) depends on passengers-db (type: database), which holds the reservations and their passengers.
O que queremos dizer: o microsserviço seat-selection (type: service) depende de passengers-db (type: database), que guarda as reservas e os seus passageiros.
A System groups the Components, APIs and Resources that deliver a capability, and hides the rest
System
- What: components that deliver a capability
System junta Components, APIs e Resources que entregam uma capacidade, e esconde o resto
System
- O quê: components que entregam uma capacidade
What we want to say: a System groups the pieces that deliver a capability and hides what is inside.
Those outside see only the public APIs of the System; what is inside can change without telling anybody.
It is a team's unit of ownership.
Source: references/backstage-catalog.md
Sources:
O que queremos dizer: System junta as peças que entregam uma capacidade e esconde o que há dentro.
Quem está fora enxerga só as APIs públicas do System; o que há dentro pode mudar sem avisar ninguém.
É a unidade de ownership de um time.
Fonte: references/backstage-catalog.md
Fontes:
The seat-map System brings the previous pieces together
- System:
seat-map - Groups:
web-checkin,seat-selectionandseats
O System seat-map junta as peças anteriores
- System:
seat-map - Agrupa:
web-checkin,seat-selectioneseats
What we want to say: the seat-map System gathers the web-checkin website, the seat-selection microservice and the seats API between them, the pieces of the previous slides. A System groups Components, APIs and Resources.
The passengers-db database is a shared Resource: it belongs to the reservations System and is also used by boarding-pass and miles. seat-selection declares the dependency (dependsOn) without the database changing owner.
O que queremos dizer: o System seat-map reúne o site web-checkin, o microsserviço seat-selection e a API seats entre eles, as peças dos slides anteriores. Um System junta Components, APIs e Resources.
O banco passengers-db é um Resource compartilhado: pertence ao System reservations e é usado também por boarding-pass e miles. O seat-selection declara a dependência (dependsOn) sem que o banco mude de dono.
A Domain groups the Systems of the same business area
Domain
- What: systems of one business area
Domain agrupa Systems da mesma área de negócio
Domain
- O quê: systems de uma área de negócio
What we want to say: a Domain groups the Systems of the same business area.
Domain is a bounded context: the same terminology, the same metrics, the same purpose.
Domain is how leadership talks about the product.
Source: references/backstage-catalog.md
Sources:
O que queremos dizer: Domain agrupa Systems da mesma área de negócio.
Domain é um bounded context: a mesma terminologia, as mesmas métricas, o mesmo propósito.
Domain é como a liderança conversa sobre o produto.
Fonte: references/backstage-catalog.md
Fontes:
The tailwind Domain has one subdomain for each business area
- Domain:
tailwind - Contains: the
airportandbookingsubdomains
O Domain tailwind tem um subdomínio por área de negócio
- Domain:
tailwind - Contém: os subdomínios
airportebooking
What we want to say: tailwind, the airline's Domain, has one subdomain (subdomainOf) for each business area. On screen, two of them: airport (check-in, seats, boarding, baggage) and booking (search, fare, reservation). The others are flight-ops, loyalty and crew.
O que queremos dizer: tailwind, o Domain da companhia, tem um subdomínio (subdomainOf) por área de negócio. Na tela, dois deles: airport (check-in, assentos, embarque, bagagem) e booking (busca, tarifa, reserva). Os outros são flight-ops, loyalty e crew.
Putting it together: from the business to the service, a single tree
Tailwind Air catalog
- Domain:
tailwind - Subdomain:
airport - System:
seat-map - Component:
seat-selection
Juntando: do negócio ao serviço, uma árvore só
Catálogo da Tailwind Air
- Domain:
tailwind - Subdomínio:
airport - System:
seat-map - Component:
seat-selection
What we want to say: from the business to the code, the catalog is a single tree.
The tree: Domain tailwind, then the airport subdomain, then the System seat-map, then the Component seat-selection. It comes from the example catalog of a fictional airline in the first proof of concept.
For an executive audience, this slide replaces the five previous ones: the example without the theory.
Live demo: the first proof of concept had a script that brought Backstage up with only the Tailwind Air catalog, with each entity of these slides.
Source: references/backstage-catalog.md
Sources:
O que queremos dizer: do negócio ao código, o catálogo é uma árvore só.
A árvore: Domain tailwind, depois o subdomínio airport, depois o System seat-map, depois o Component seat-selection. Vem do catálogo de exemplo de uma companhia aérea fictícia, na primeira prova de conceito.
Para o público executive, este slide substitui os cinco anteriores: o exemplo sem a teoria.
Demo ao vivo: a primeira prova de conceito tinha um script que subia o Backstage só com o catálogo da Tailwind Air, com cada entidade destes slides.
Fonte: references/backstage-catalog.md
Fontes:
A flight delay becomes one event that reaches five subdomains, and the catalog shows who depends on it
Across the Tailwind domain
- Topic:
flight-events, written byflight-tracker - Readers: four services, in four other subdomains
Um atraso de voo vira um evento que chega a cinco subdomínios, e o catálogo mostra quem depende dele
Através do domínio Tailwind
- Tópico:
flight-events, escrito peloflight-tracker - Leitores: quatro serviços, em quatro outros subdomínios
What we want to say: the tree shows the path from top to bottom; the catalog also shows what crosses the branches.
A flight delay becomes an event on the flight-events topic. The one who writes to the topic is flight-tracker, in flight-ops; the readers are in four other subdomains: boarding-pass-issuer reissues the boarding pass and bag-tracker redirects the bags (airport), rebooking-assistant rebooks the passengers of a cancelled flight onto the next one with free seats (booking), miles-ledger reverses the miles of a cancelled flight (loyalty) and roster-planner redoes the crew roster (crew).
Whoever changes the event needs to know who reads it. The catalog answers without anybody asking in the chat: in Backstage, the page of flight-events lists the four Components. In the Nereus API this arrives when the Components enter the catalog through discovery.
The names come from the example catalog of the first proof of concept.
Source: references/backstage-catalog.md
Sources:
O que queremos dizer: a árvore mostra o caminho de cima para baixo; o catálogo também mostra o que atravessa os galhos.
Um atraso no voo vira um evento no tópico flight-events. Quem escreve no tópico é o flight-tracker, em flight-ops; quem lê está em quatro outros subdomínios: o boarding-pass-issuer reemite o cartão de embarque e o bag-tracker redireciona as malas (airport), o rebooking-assistant remarca os passageiros de um voo cancelado no próximo com assentos livres (booking), o miles-ledger estorna as milhas de um voo cancelado (loyalty) e o roster-planner refaz a escala da tripulação (crew).
Quem muda o evento precisa saber quem o lê. O catálogo responde sem ninguém perguntar no chat: no Backstage, a página do flight-events lista os quatro Components. Na API do Nereus isso chega quando os Components entram no catálogo pela discovery.
Os nomes vêm do catálogo de exemplo da primeira prova de conceito.
Fonte: references/backstage-catalog.md
Fontes:
In the catalog, the app is a short file next to the code, starting with its name and what it does
No catálogo, a app é um arquivo curto junto do código, começando pelo nome e pelo que ela faz
1kind: Component2metadata:3 name: seat-selection4 description: Serves the seat map and holds the seat a passenger picks5spec:6 system: seat-map7 type: service8 owner: team-airport9 lifecycle: production10 providesApis:11 - seats12 dependsOn:13 - resource:passengers-db
What we want to say: every app declares itself in the catalog with a short file next to the code; the first lines say the name and what the app does, in human language. That is what shows up in the catalog search.
Source: references/backstage-catalog.md
Sources:
O que queremos dizer: cada app se declara no catálogo com um arquivo curto, junto do código; as primeiras linhas dizem o nome e o que a app faz, em linguagem humana. É o que aparece na busca do catálogo.
Fonte: references/backstage-catalog.md
Fontes:
Which system it belongs to and what type it is
A que sistema pertence e de que tipo é
1kind: Component2metadata:3 name: seat-selection4 description: Serves the seat map and holds the seat a passenger picks5spec:6 system: seat-map7 type: service8 owner: team-airport9 lifecycle: production10 providesApis:11 - seats12 dependsOn:13 - resource:passengers-db
What we want to say: system places the app in the tree: it links to the System seat-map, which links to the airport subdomain of Tailwind Air.
type: service says the type of Component: it could be website or library.
Source: references/backstage-catalog.md
Sources:
O que queremos dizer: system posiciona a app na árvore: liga ao System seat-map, que liga ao subdomínio airport da Tailwind Air.
type: service diz o tipo de Component: poderia ser website ou library.
Fonte: references/backstage-catalog.md
Fontes:
Whose it is and where it is on the journey
De quem é e em que ponto da jornada está
1kind: Component2metadata:3 name: seat-selection4 description: Serves the seat map and holds the seat a passenger picks5spec:6 system: seat-map7 type: service8 owner: team-airport9 lifecycle: production10 providesApis:11 - seats12 dependsOn:13 - resource:passengers-db
What we want to say: owner says who answers for the app: it links to the Group team-airport.
lifecycle: production says how far it can be trusted; for an Internal Product, where it is on the journey.
Source: references/backstage-catalog.md
Sources:
O que queremos dizer: owner diz quem responde pela app: liga ao Group team-airport.
lifecycle: production diz o quanto dá para confiar nela; para um Internal Product, em que ponto da jornada ele está.
Fonte: references/backstage-catalog.md
Fontes:
The lifecycle marks the journey of an Internal Product, from idea to shared product, until it is retired
Lifecycle of an Internal Product
experimental: an idea being builtproduction: validated, shared with the orgdeprecated: being retired
O lifecycle marca a jornada de um Internal Product: de ideia a produto compartilhado, até a descontinuação
Lifecycle de um Internal Product
experimental: uma ideia em construçãoproduction: validado, compartilhado com a orgdeprecated: em descontinuação
What we want to say: sharing with the organization is a change of state, and the catalog already has the field for it.
Well-known Backstage values: experimental, production and deprecated, in the spec.lifecycle of Component, API, Resource and System (see the [descriptor format](https://backstage.io/docs/features/software-catalog/descriptor-format)). In the Tailwind Air catalog everything is production; the example catalog of the platform is experimental.
A proposal (an idea, not decided): experimental is where the owner provisions, tests and refines. production is validated and shared, so other teams may depend on it. deprecated is being retired, and whoever depends on it gets a warning and a deadline.
Moving up to production can become a platform gate: an owner, observability, attributed cost and security up to date.
Source: references/internal-products.md
Sources:
O que queremos dizer: compartilhar com a organização é uma mudança de estado, e o catálogo já tem o campo para isso.
Valores bem conhecidos do Backstage: experimental, production e deprecated, no spec.lifecycle de Component, API, Resource e System (veja o [descriptor format](https://backstage.io/docs/features/software-catalog/descriptor-format)). Na Tailwind Air, todo o catálogo está em production; o catálogo de exemplo da plataforma, em experimental.
Uma proposta (ideia, não decidida): experimental é onde o dono provisiona, testa e refina. production é validado e compartilhado, então outros times podem depender dele. deprecated está em descontinuação, e quem depende recebe aviso e prazo.
Subir para production pode virar gate da plataforma: dono, observabilidade, custo atribuído e segurança em dia.
Fonte: references/internal-products.md
Fontes:
The contract the app offers
O contrato que a app oferece
1kind: Component2metadata:3 name: seat-selection4 description: Serves the seat map and holds the seat a passenger picks5spec:6 system: seat-map7 type: service8 owner: team-airport9 lifecycle: production10 providesApis:11 - seats12 dependsOn:13 - resource:passengers-db
What we want to say: the app declares the contract it offers. providesApis points to the API entity seats; web-checkin declares consumesApis for it.
Whoever consumes declares consumesApis on the other side: the catalog draws the edge.
Source: references/backstage-catalog.md
Sources:
O que queremos dizer: a app declara o contrato que oferece. providesApis aponta para a entidade API seats; o web-checkin declara consumesApis dela.
Quem consome declara consumesApis do outro lado: o catálogo desenha a aresta.
Fonte: references/backstage-catalog.md
Fontes:
What it depends on to run, described by its role
Do que depende para rodar, descrito pelo papel
1kind: Component2metadata:3 name: seat-selection4 description: Serves the seat map and holds the seat a passenger picks5spec:6 system: seat-map7 type: service8 owner: team-airport9 lifecycle: production10 providesApis:11 - seats12 dependsOn:13 - resource:passengers-db
What we want to say: the app declares what it depends on by role, never by cloud service.
passengers-db is a relational database, and no line says which cloud product: the same principle that comes back in the app declaration.
It is a shared Resource: it belongs to the reservations System, and seat-selection only uses it (slide entity-resource-example). Based on the example catalog of the first proof of concept.
Source: references/backstage-catalog.md
Sources:
O que queremos dizer: a app declara do que depende pelo papel, nunca pelo serviço de nuvem.
O passengers-db é um banco relacional, e nenhuma linha diz qual produto de nuvem: o mesmo princípio que reaparece na declaração da app.
É um Resource compartilhado: pertence ao System reservations, e o seat-selection só o usa (slide entity-resource-example). Baseado no catálogo de exemplo da primeira prova de conceito.
Fonte: references/backstage-catalog.md
Fontes:
The portal finds the file and keeps the catalog up to date by itself
How the file reaches the catalog
- Source:
catalog-info.yamlin the repository - Discovery: the portal scans the GitHub organization
- Refresh: reprocessed on a schedule, no manual edits
O portal encontra o arquivo e mantém o catálogo em dia sozinho
Como o arquivo chega ao catálogo
- Origem:
catalog-info.yamlno repositório - Descoberta: o portal varre a organização no GitHub
- Atualização: reprocessado em intervalos, sem edição manual
What we want to say: nobody edits the catalog by hand; the portal finds the file and keeps it up to date.
Discovery: the file lives in the app's repository. The portal finds it in two ways: through a registered location (the URL of the YAML) or by scanning the GitHub organization for files with that name. The example in the documentation runs every 30 minutes.
Refresh: the processing loop reprocesses each entity periodically. When the file changes in the pull request (PR), the catalog follows.
Source: references/backstage-catalog.md
Sources:
O que queremos dizer: ninguém edita o catálogo à mão; o portal acha o arquivo e o mantém em dia.
Descoberta: o arquivo mora no repositório da app. O portal o encontra de dois jeitos: por uma location registrada (a URL do YAML) ou varrendo a organização no GitHub atrás de arquivos com esse nome. O exemplo da doc roda a cada 30 minutos.
Atualização: o processing loop reprocessa cada entidade periodicamente. Mudou o arquivo no pull request (PR), o catálogo acompanha.
Fonte: references/backstage-catalog.md
Fontes:
The catalog does not represent versions: it keeps the human concept of a thing, stable data curated by its owner
What the catalog stores
- Not: versions
- Only: the human concept
O catálogo não representa versões: guarda o conceito humano de uma coisa, dado estável, curado pelo dono
O que o catálogo guarda
- Não: versões
- Só: o conceito humano
What we want to say: the catalog is the human mental model of the platform, not its live state.
The Backstage documentation is explicit (catalog FAQ): "We do not recommend trying to represent fine grained versions in the catalog." It holds "the human concept of a thing", data that is "rarely changing, human curated", maintained by the owner.
Source: references/backstage-catalog.md
Sources:
O que queremos dizer: o catálogo é o modelo mental humano da plataforma, não o estado vivo dela.
A documentação do Backstage é explícita (FAQ do catálogo): "We do not recommend trying to represent fine grained versions in the catalog." Ele guarda "the human concept of a thing", dado "rarely changing, human curated", mantido pelo dono.
Fonte: references/backstage-catalog.md
Fontes:
seat-selection is one Component, with several versions running
- Component:
seat-selection, 1 component, N versions running
seat-selection é um Component, com várias versões rodando
- Component:
seat-selection, 1 component, N versões rodando
What we want to say: seat-selection, the seat service of Tailwind Air, is one Component, even with several versions running at the same time. That is an explicit recommendation of the Backstage documentation (catalog FAQ). The live state is kept somewhere else.
O que queremos dizer: o seat-selection, o serviço de assentos da Tailwind Air, é um Component, mesmo com várias versões rodando ao mesmo tempo. É uma recomendação explícita da documentação do Backstage (FAQ do catálogo). O estado vivo fica em outro lugar.
The exception is a broken contract: a major breaking change becomes a new entity
The exception: breaking change
- Rule: a major breaking change is a new entity
A exceção é a quebra de contrato: uma major breaking vira uma entidade nova
A exceção: quebra de contrato
- Regra: uma major breaking change é uma entidade nova
What we want to say: when the contract breaks, the concept changes, and the consumers need to migrate explicitly.
Source: references/backstage-catalog.md
Sources:
O que queremos dizer: quebrou o contrato, mudou o conceito, e os consumidores precisam migrar de forma explícita.
Fonte: references/backstage-catalog.md
Fontes:
Breaking the seats contract creates the seats2 API, next to seats
- Before: the
seatsAPI - After: the
seats2API, next toseats
Quebrar o contrato de assentos cria a API seats2, ao lado da seats
- Antes: a API
seats - Depois: a API
seats2, ao lado daseats
What we want to say: at Tailwind Air, changing the seats contract in an incompatible way creates the seats2 API, and web-checkin migrates explicitly, swapping its consumesApis. The two live together until seats is deprecated.
It is the same pattern as the Backstage FAQ example: customerinfo becomes customerinfo2.
O que queremos dizer: na Tailwind Air, mudar o contrato de seats de forma incompatível cria a API seats2, e o web-checkin migra de forma explícita, trocando o consumesApis. As duas convivem até a seats ser deprecated.
É o mesmo padrão do exemplo da FAQ do Backstage: customerinfo vira customerinfo2.
Versions and environments live in other systems and come back to the portal through plugins
Where versions live
- How: other systems feed the portal via plugins
Versões e ambientes vivem em outros sistemas e voltam ao portal por plugins
Onde vivem as versões
- Como: outros sistemas alimentam o portal por plugins
What we want to say: versions and environments are owned by other systems; the portal only shows them.
The fine-grained versions come from external systems (CI/CD, registry, deploy) and show up in the Backstage portal through its plugins.
A question that comes back in Integration & Delivery: which systems are those?
Source: references/backstage-catalog.md
Sources:
O que queremos dizer: versões e ambientes têm dono em outros sistemas; o portal só os mostra.
As versões de grão fino vêm de sistemas externos (CI/CD, registry, deploy) e aparecem no portal do Backstage por plugins.
Pergunta que volta no Integration & Delivery: que sistemas são esses?
Fonte: references/backstage-catalog.md
Fontes:
The app declares what it needs to run, without saying where or how
App Declaration
Source: platformengineering.org/platform-tooling · planes as parallel layers; the journey order is ours
A app declara do que precisa para rodar, sem dizer onde nem como
App Declaration
Fonte: platformengineering.org/platform-tooling · planes as parallel layers; the journey order is ours
What we want to say: the catalog says who the app is; the declaration says what it needs: container, port, database, route.
It is a workload spec in the model of Score: the developer describes the need, and the platform decides where and how to meet it.
Source: references/score.md
Sources:
O que queremos dizer: o catálogo diz quem a app é; a declaração diz do que ela precisa: container, porta, banco, rota.
É uma spec de workload no modelo do Score: o dev descreve a necessidade, e a plataforma decide onde e como atender.
Fonte: references/score.md
Fontes:
The app declares what it needs to run, starting with a postgres database: the type, not the product
A app declara do que precisa para rodar, começando por um banco postgres: o tipo, não o produto
1apiVersion: score.dev/v1b123metadata:4 name: seat-selection56resources:7 db:8 type: postgres9 dns:10 type: dns11 route:12 type: route13 params:14 host: ${resources.dns.host}15 path: /16 port: 801718containers:19 api:20 image: .21 variables:22 DATABASE_HOST: ${resources.db.host}23 DATABASE_NAME: ${resources.db.name}24 DATABASE_USER: ${resources.db.username}25 DATABASE_PASSWORD: ${resources.db.password}2627service:28 ports:29 http:30 port: 8031 targetPort: 8080
What we want to say: the app declaration says what the app needs, without saying where or how, and it starts with the resources, asked for by type.
The developer asks for a postgres database, and nothing else. The platform chooses the concrete service, per environment: the same principle as the catalog Resources, described by their role.
No line says which managed service, size, version or network: all of that comes from the environment profile.
Format: the Score model (score.dev/v1b1, see the [spec reference](https://docs.score.dev/docs/score-specification/score-spec-reference/)). Catalog is not declaration: catalog-info.yaml says who the app is; app-spec.yaml says what it needs.
Source: references/score.md
Sources:
O que queremos dizer: a declaração da app diz do que ela precisa, sem dizer onde nem como, e começa pelos recursos, pedidos por tipo.
O dev pede um banco postgres, e só isso. Quem escolhe o serviço concreto é a plataforma, por ambiente: o mesmo princípio dos Resources do catálogo, descritos pelo papel.
Nenhuma linha diz qual serviço gerenciado, tamanho, versão ou rede: tudo isso vem do perfil do ambiente.
Formato: o modelo do Score (score.dev/v1b1, veja a [referência da spec](https://docs.score.dev/docs/score-specification/score-spec-reference/)). Catálogo não é declaração: o catalog-info.yaml diz quem a app é; o app-spec.yaml, do que ela precisa.
Fonte: references/score.md
Fontes:
The container receives the database by reference, not by value
O container recebe o banco por referência, não por valor
1apiVersion: score.dev/v1b123metadata:4 name: seat-selection56resources:7 db:8 type: postgres9 dns:10 type: dns11 route:12 type: route13 params:14 host: ${resources.dns.host}15 path: /16 port: 801718containers:19 api:20 image: .21 variables:22 DATABASE_HOST: ${resources.db.host}23 DATABASE_NAME: ${resources.db.name}24 DATABASE_USER: ${resources.db.username}25 DATABASE_PASSWORD: ${resources.db.password}2627service:28 ports:29 http:30 port: 8031 targetPort: 8080
What we want to say: the variables have no value, they point to outputs of the resource (${resources.db.host}).
They are resolved at deploy time, with the value of the target environment: the same file serves development and production, and the password never sits in the repository.
Source: references/score.md
Sources:
O que queremos dizer: as variáveis não têm valor, apontam para outputs do recurso (${resources.db.host}).
São resolvidas no deploy, com o valor do ambiente de destino: o mesmo arquivo serve para dev e produção, e a senha nunca fica no repo.
Fonte: references/score.md
Fontes:
Name and route: how the app is reached from outside
Nome e rota: como a app é alcançada de fora
1apiVersion: score.dev/v1b123metadata:4 name: seat-selection56resources:7 db:8 type: postgres9 dns:10 type: dns11 route:12 type: route13 params:14 host: ${resources.dns.host}15 path: /16 port: 801718containers:19 api:20 image: .21 variables:22 DATABASE_HOST: ${resources.db.host}23 DATABASE_NAME: ${resources.db.name}24 DATABASE_USER: ${resources.db.username}25 DATABASE_PASSWORD: ${resources.db.password}2627service:28 ports:29 http:30 port: 8031 targetPort: 8080
What we want to say: the app asks for a name (dns) and a route (route), and a reference links the two (${resources.dns.host}).
No ingress, load balancer or certificate: that belongs to the platform.
Source: references/score.md
Sources:
O que queremos dizer: a app pede um nome (dns) e uma rota (route), e uma referência liga os dois (${resources.dns.host}).
Nada de ingress, load balancer ou certificado: isso é da plataforma.
Fonte: references/score.md
Fontes:
The port the service exposes
A porta que o serviço expõe
1apiVersion: score.dev/v1b123metadata:4 name: seat-selection56resources:7 db:8 type: postgres9 dns:10 type: dns11 route:12 type: route13 params:14 host: ${resources.dns.host}15 path: /16 port: 801718containers:19 api:20 image: .21 variables:22 DATABASE_HOST: ${resources.db.host}23 DATABASE_NAME: ${resources.db.name}24 DATABASE_USER: ${resources.db.username}25 DATABASE_PASSWORD: ${resources.db.password}2627service:28 ports:29 http:30 port: 8031 targetPort: 8080
What we want to say: the developer only says the port: logical port 80 forwarded to container port 8080.
Image: image: . means "the image the CI has just built"; the version is injected at delivery, not written here.
Source: references/score.md
Sources:
O que queremos dizer: o dev só diz a porta: porta lógica 80 encaminhada para a porta do container 8080.
Imagem: image: . significa "a imagem que a CI acabou de buildar"; a versão é injetada na entrega, não escrita aqui.
Fonte: references/score.md
Fontes:
No line says where, in which cloud, or with which tool
What the spec leaves out
- Where: no cluster, no region
- Cloud: no Azure, no AWS
- Tool: no Helm, no Terraform
Nenhuma linha diz onde, em qual nuvem, nem com qual ferramenta
O que a spec deixa de fora
- Onde: nem cluster, nem região
- Nuvem: nem Azure, nem AWS
- Ferramenta: nem Helm, nem Terraform
What we want to say: where, in which cloud and with which tool are decisions of the platform, not of the developer.
A question that stays for Integration & Delivery: who answers that? The orchestrator.
In "The platform engineering illusion", the best platform teams measure themselves "partly by what they refuse to expose to developers", not only by what they expose.
Source: references/score.md, references/platform-illusion.md
Sources:
O que queremos dizer: onde, em qual nuvem e com qual ferramenta são decisões da plataforma, não do dev.
Pergunta que fica para o Integration & Delivery: quem responde isso? O orquestrador.
Em "The platform engineering illusion", os melhores times de plataforma se medem "partly by what they refuse to expose to developers", não só pelo que expõem.
Fonte: references/score.md, references/platform-illusion.md
Fontes:
The golden path creates the repository, the declaration and the spec at once
Golden Paths
Source: platformengineering.org/platform-tooling · planes as parallel layers; the journey order is ours
O golden path cria o repo, a declaração e a spec de uma vez
Golden Paths
Fonte: platformengineering.org/platform-tooling · planes as parallel layers; the journey order is ours
What we want to say: nobody writes those files from scratch: the golden path creates the repository already with the catalog descriptor and the app declaration, the right way.
That is why it comes last in the Developer Control Plane: it joins the catalog and the declaration, and delivers a repository, which is where the next plane starts.
O que queremos dizer: ninguém escreve esses arquivos do zero: o golden path cria o repo já com o descritor do catálogo e a declaração da app, seguindo o jeito certo.
É por isso que vem por último no Developer Control: ele junta catálogo e declaração, e entrega um repo, que é onde o próximo plane começa.
The right way has to be the easiest: that is what makes the developer choose the golden path
Why developers choose it
- What: the supported path for a recurring task
- Rule: the easy way is the right way
O caminho certo precisa ser o mais fácil: é isso que faz o dev escolher o golden path
Por que o dev o escolhe
- O quê: o caminho suportado para uma tarefa recorrente
- Regra: o jeito fácil é o jeito certo
What we want to say: the right way has to be the easiest: it is the ease, not the obligation, that makes the developer follow it.
A golden path is the path the platform supports for a recurring task, like creating a service or asking for a database. When it is the easiest path, following the standard stops being an obligation.
The question that decides adoption, according to "The platform engineering illusion": "Why would a developer, mid-deadline, exhausted, half paying attention, choose your paved road over the goat trail they already know?"
Source: references/platform-illusion.md
Sources:
O que queremos dizer: o caminho certo precisa ser o mais fácil: é a facilidade, não a obrigação, que faz o dev segui-lo.
Golden path é o caminho suportado pela plataforma para uma tarefa recorrente, como criar um serviço ou pedir um banco. Quando ele é o caminho mais fácil, seguir o padrão deixa de ser obrigação.
A pergunta que decide a adoção, segundo "The platform engineering illusion": "Why would a developer, mid-deadline, exhausted, half paying attention, choose your paved road over the goat trail they already know?"
Fonte: references/platform-illusion.md
Fontes:
The golden path guides without trapping: it is optional and composes with others
How it guides
- Shape: optional and composable
- Risk: a golden cage breeds shadow platforms
O golden path guia sem prender: é opcional e se compõe com outros
Como ele guia
- Forma: opcional e composável
- Risco: uma golden cage gera shadow platforms
What we want to say: the golden path guides without becoming a cage.
Platform as a Product, p. 11: "abstractions should be composable and optional. They should guide without constraining. They should reduce complexity without hiding critical details."
A caveat: the "golden cage", a rigid path imposed from above, breeds shadow platforms, and there is no universal golden path (p. 11).
Imposing the path does not solve it: "mandated usage generates resentment rather than advocacy, and resentment metastasizes into shadow infrastructure" ("The platform engineering illusion"), a source independent of Syntasso for the same caveat.
Source: references/platform-as-a-product.md, references/platform-illusion.md
Sources:
O que queremos dizer: o golden path guia sem virar jaula.
Platform as a Product, p. 11: "abstractions should be composable and optional. They should guide without constraining. They should reduce complexity without hiding critical details."
Ressalva: a "golden cage", um caminho rígido imposto de cima, gera shadow platforms, e não existe golden path universal (p. 11).
Impor o caminho não resolve: "mandated usage generates resentment rather than advocacy, and resentment metastasizes into shadow infrastructure" ("The platform engineering illusion"), uma fonte independente da Syntasso para a mesma ressalva.
Fonte: references/platform-as-a-product.md, references/platform-illusion.md
Fontes:
The golden path joins the catalog and the declaration: it creates the repository with both files, the CI and the agent's context
What it creates
- Repo:
catalog-info.yaml+app-spec.yaml - Build: CI to the registry
- Agent:
AGENTS.md
O golden path junta catálogo e declaração: cria o repo já com os dois arquivos, a CI e o contexto do agente
O que ele cria
- Repo:
catalog-info.yaml+app-spec.yaml - Build: CI até o registry
- Agente:
AGENTS.md
What we want to say: nobody writes catalog-info.yaml and app-spec.yaml from scratch: the golden path creates the repository already with both.
It comes last in the Developer Control Plane because it joins the catalog and the declaration and delivers a repository, which is where the next plane starts.
Besides the two files, the repository is born with the CI that publishes the image to the registry and with AGENTS.md, the context of the agent that works on the code.
O que queremos dizer: ninguém escreve o catalog-info.yaml e o app-spec.yaml do zero: o golden path cria o repo já com os dois.
Vem por último no Developer Control porque junta catálogo e declaração e entrega um repo, que é onde o próximo plane começa.
Além dos dois arquivos, o repo nasce com a CI que publica a imagem no registry e com o AGENTS.md, o contexto do agente que trabalha no código.
The next Nereid is born from the nereid-python template, and one apply registers it in the catalog next to Triton
O próximo Nereid nasce do template nereid-python, e um apply o registra no catálogo ao lado do Triton
# The golden path: the edge-cloudflare Nereid from the nereid-python template (a Template of the catalog, an idea)$ nereus template render nereid-python \ --path controllers/edge-cloudflare/ \ --param name=edge-cloudflare✓ catalog/templates/nereid-python rendered at controllers/edge-cloudflare/ (15 files, catalog/workloads/edge-cloudflare.yaml written) # Register what the repository says it has: the new entry, and Triton already imported$ nereus catalog apply \ --from-file catalog/✓ catalog/workloads/edge-cloudflare created (owner: Project/nereids, type: controller) catalog/workloads/triton unchanged (owner: Project/triton, type: service) Next steps: nereus catalog check
What we want to say: the template comes first, because it writes the files; the catalog only registers what exists. The nereid-python template renders the next Nereid of the backlog, edge-cloudflare (#470, publishing a reef's endpoint at a hostname), 15 files, with its catalog entry written next to the code; then one nereus catalog apply registers it and leaves Triton, imported earlier the same way, unchanged. The command has [its own slide](../../specs/cli/reefs/catalog.html#workload-apply) in the catalog reef's deck.
template render is a contract, not built yet; catalog apply is built (owner, 2026-10-30, #559, the catalog reef: Workload, Package and their types; 2026-11-02, #851, the Template kind): a Template is a kind of the catalog that writes files, and creating a repository stays with #279 (the repository reef); the catalog is a catalog/ folder in the repository, one file per entry, and the file is the truth, so registering an existing thing is apply (ADR 0013, command conventions). A Workload (what runs: controller, service, web-app, static-site, worker, job, function) replaces Backstage's Component, and a Package holds what is published; each names its owner in the tenancy tree, a Project that may sit under another one instead of a System and a Domain (#21, Organization and nested Projects).
It is Nereus itself in the example, not a hello-api: the catalog's first entries are the platform's own Nereids, Triton, the CLI and the images (dogfooding).
O que queremos dizer: o template vem primeiro, porque ele escreve os arquivos; o catálogo só registra o que existe. O template nereid-python renderiza o próximo Nereid do backlog, o edge-cloudflare (#470, publicar o endpoint de um reef num hostname), 15 arquivos, com a entrada do catálogo escrita ao lado do código; depois um nereus catalog apply o registra e deixa o Triton, importado antes do mesmo jeito, unchanged. O comando tem [o seu próprio slide](../../specs/cli/reefs/catalog.html#workload-apply) no deck do reef catalog.
O template render é um contrato, ainda não construído; o catalog apply está pronto (owner, 2026-10-30, #559, o reef catalog: Workload, Package e seus tipos; 2026-11-02, #851, o kind Template): um Template é um kind do catálogo que escreve arquivos, e criar um repositório fica com o #279 (o reef repository); o catálogo é uma pasta catalog/ no repositório, um arquivo por entrada, e o arquivo é a verdade, então registrar algo que já existe é apply (ADR 0013, convenções de comando). Um Workload (o que roda: controller, service, web-app, static-site, worker, job, function) substitui o Component do Backstage, e um Package guarda o que é publicado; cada um nomeia seu dono na árvore de tenancy, um Project que pode ficar debaixo de outro no lugar de System e Domain (#21, Organization e Projects aninhados).
O exemplo é o próprio Nereus, não um hello-api: as primeiras entradas do catálogo são os Nereids da plataforma, o Triton, a CLI e as imagens (dogfooding).
Sources
Fontes
- Backstage Software Catalog: system model, FAQ and life of an entity · Backstage documentation
- Score specification reference · Score documentation
- The Platform Engineering Illusion · David Iyanu Jonathan · 2026
- Platform as a Product · Abby Bangser, Daniel Bryant, Colin Humphreys and Cat Morris · 2025
Backstage Software Catalog: system model, FAQ and life of an entity
Backstage documentation
- About: The documentation of the Backstage software catalog: the entities (Component, API, Resource, System, Domain, Group), why the catalog does not hold versions, and how a file enters the catalog.
- For this talk: "We do not recommend trying to represent fine grained versions in the catalog." The catalog holds "the human concept of a thing".
Backstage Software Catalog: system model, FAQ and life of an entity
Backstage documentation
- Sobre: A documentação do catálogo de software do Backstage: as entidades (Component, API, Resource, System, Domain, Group), por que o catálogo não guarda versões e como um arquivo entra no catálogo.
- Para esta palestra: "We do not recommend trying to represent fine grained versions in the catalog." O catálogo guarda "the human concept of a thing".
https://backstage.io/docs/features/software-catalog/system-model#ecosystem-modeling
Score specification reference
Score documentation
- About: A platform- and environment-independent workload spec (apiVersion score.dev/v1b1): the developer describes what the app needs, the platform decides how and where.
- For this talk: Its sections (metadata, containers, service, resources) are the model of the app declaration on these slides; resources are asked for by type, never by cloud service.
Score specification reference
Score documentation
- Sobre: Uma especificação de workload independente de plataforma e de ambiente (apiVersion score.dev/v1b1): o dev descreve o que a app precisa, e a plataforma decide como e onde.
- Para esta palestra: As suas seções (metadata, containers, service, resources) são o modelo da declaração da app nestes slides; os recursos são pedidos por tipo, nunca por serviço de nuvem.
https://docs.score.dev/docs/score-specification/score-spec-reference/
The Platform Engineering Illusion
David Iyanu Jonathan · 2026
- About: An opinion piece: internal developer platforms fail because they are run as tooling initiatives when they are a product discipline.
- For this talk: "Why would a developer, mid-deadline, exhausted, half paying attention, choose your paved road over the goat trail they already know?" Its figures are the author's own account and stay off the screen.
The Platform Engineering Illusion
David Iyanu Jonathan · 2026
- Sobre: Um artigo de opinião: as plataformas internas falham porque são tocadas como iniciativas de ferramentas quando são uma disciplina de produto.
- Para esta palestra: "Why would a developer, mid-deadline, exhausted, half paying attention, choose your paved road over the goat trail they already know?" Os números são o relato do próprio autor e ficam fora da tela.
Platform as a Product
Abby Bangser, Daniel Bryant, Colin Humphreys and Cat Morris · 2025
- About: An O'Reilly report: a platform is a product, with users, a value proposition, a feedback loop and a focus on adoption, not an infrastructure project with a delivery date.
- For this talk: "abstractions should be composable and optional. They should guide without constraining." (p. 11), and the golden cage: a rigid, top-down golden path breeds shadow platforms. The four authors work for Syntasso, the company behind Kratix.
Platform as a Product
Abby Bangser, Daniel Bryant, Colin Humphreys and Cat Morris · 2025
- Sobre: Um relatório da O'Reilly: plataforma é produto, com usuários, proposta de valor, ciclo de feedback e foco em adoção, não um projeto de infraestrutura com data de entrega.
- Para esta palestra: "abstractions should be composable and optional. They should guide without constraining." (p. 11), e a golden cage: um golden path rígido, imposto de cima, gera shadow platforms. Os quatro autores trabalham na Syntasso, a empresa por trás do Kratix.
https://www.syntasso.io/platform-as-a-product-oreilly-report