chore: Add Backstage Catalog file

[backstage-me-stg]

O que este PR faz?

Este PR cria um arquivo para a catalogação da aplicação no Backstage Service Catalog.

(Este PR foi criado automaticamente para repositórios contindos na Planilha de System Mapping de GovTI.)

Abaixo segue algumas explicações sobre as formas de catalogação e como adicionar as informações adicionais.

Component

Um `Component` descreve um componente de software. Tipicamente, um componente:

• Pode ser ligado ao código-fonte que o constitui;
• Possui um deployable artifact;
• É uma entrada no nosso System Mapping;
• Pode ser considerado uma “unidade de software”;

Parâmetros suportados

• type - (Required) O nome do tipo do Component. Os valores possíveis são: website, service, library, cli, infra-as-code, mobile e desktop.
• lifecycle - (Required) O estado de lifecycle do Component. Os valores possíveis são:
  • production: um componente produtivo, mantido e bem estabelecido;
  • experimental: um componente em estágios iniciais, não-produtivo. Esse lifecycle sinaliza que o componente não possui garantias de reliability e que os consumidores podem preferir não consumir esse componente no lugar de outros com lifecycle de production;
  • deprecated: um componente no final de seu lifecycle. Pode ser descontinuado/removido em breve.
• owner - (Required) Uma referência ao nome do time responsável pelo componente. O formato deve ser: <github-org>/<github-team>. Veja o exemplo na subsessão abaixo.
• system - (Opcional) Uma referência ao nome do System que engloba esse componente.
• subcomponentOf - (Opcional) Uma referência ao nome de outro Component que este componente faz parte. O formato aceito é: component:<nome-do-componente>.
• providesApis - (Opcional) Uma lista de referências aos nomes de APIs expostas por esse componente.
• consumesApis - (Opcional) Uma lista de referências aos nomes de APIs que são consumidas por esse componente.
• dependsOn - (Opcional) Uma lista de referências aos nomes de Components ou Resources que esse componente depende. O formato aceito é: <tipo-da-entidade>:<nome-da-entidade>. Veja o exemplo na subsessão abaixo.

O Component possui alguns metadados obrigatórios a mais quando comparado com outras entidades. Todos esses metadados devem ser inseridos no bloco metadata do manifesto. Abaixo estão definidos cada um dos campos.

Annotations especiais

Os campos abaixo devem estar definidos dentro de metadata.annotations:

• legacy.stone.tech/owner-email (Required) E-mail do owner do Component. O valor deve ser um e-mail válido.
• legacy.stone.tech/prod-date - (Opcional) A data, no formato yyyy-mm-dd que a aplicação entrou em produção. Campo se torna Required se spec.lifecycle: production.
• stone.tech/cloud-accounts - (Opcional) Uma lista em formato de String separada por vírgulas que elenca todas cloud accounts que o Component está deployado. Campo se torna obrigatório se spec.lifecycle: production e stone.tech/on-prem-sites estiverem omitidos. As clouds suportadas são: aws, gcp, azure, ibm e oracle. O formato deve ser <cloud>/<account-name> separado por vírgulas. Por exemplo: aws/pagarme-tools,gcp/sreplatform.
• stone.tech/on-prem-sites (Opcional) Uma lista em formato de String separada por vírgulas que elenca todos datacenters on-premises que o Component está deployado. Campo se torna obrigatório se spec.lifecycle: production e stone.tech/cloud-accounts estiverem omitidos. Os valores possíveis são: atlanta1, chicago1, sp1 e rio1. O formato deve ser o nome do(s) datacenter(s) separado por vírgulas. Por exemplo: chicago1,atlanta1.

Labels especiais

Os campos abaixo devem estar definidos dentro de metadata.labels:

• stone.tech/endpoint-type (Required) Enum que representa o tipo de endpoint exposto pelo Component. As opções são: public, private, internal e none.
• legacy.stone.tech/internal-user-auth-base (Required) Informa qual base de autenticação é utilizada pelo Component. As opções são: sso, own-user-base not-applicable e other.
• legacy.stone.tech/customer-auth-method (Required) Enum que representa o método de autenticação utilizado por usuários do Component. As opções são: api-key, user-password, other e not-applicable.
• legacy.stone.tech/handle-lgpd (Opcional) String que representa um valor booleano indicando se algum ativo de infra associado ao Component realiza o processamento de Dados Pessoais ou Dados Pessoais Sensíveis, para apoiar a LGPD. Campo se torna obrigatório se spec.lifecycle: production. Os valores possíveis são: "true" ou "false".
• legacy.stone.tech/access-request-type (Opcional) Informa qual é o método de solicitação de acesso ao Component. O campo se torna obrigatório se spec.lifecycle: production. Os valores suportados são: jira, service-now-stone, service-now-pagarme, github, my-access, email, other, not-applicable.

Links especiais

O campo metadata.links do Component possui 3 links obrigatórios para o Component se spec.lifecycle: production, que são relacionados ao CD Pipeline, Monitoring e Incident Manager. Esses três nomes são os títulos obrigatórios que devem ser inseridos em cada um dos itens. Veja o exemplo abaixo:

...
metadata:
  links:
    - url: https://github.com/platform-test-org/actions/deploy
      title: CD Pipeline
    - url: https://newrelic.com/stone/my-app
      title: Monitoring
    - url: https://pagerduty.com/stone/myservice
      title: Incident Manager
...

Demais itens são opcionais, mas esses três exemplificado acima são obrigatórios para o Component.

Exemplos

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: backstage-portal
  namespace: stone
  title: Backstage Portal
  description: The StoneCo developer portal
  annotations:
    stone.tech/cloud-accounts: aws/pagarme-tools
    legacy.stone.tech/prod-date: "2023-03-01"
    legacy.stone.tech/owner-email: dmorales@stone.com.br
  labels:
    stone.tech/endpoint-type: private
    legacy.stone.tech/internal-user-auth-base: sso
    legacy.stone.tech/access-request-type: github
    legacy.stone.tech/handle-lgpd: "false"
    legacy.stone.tech/customer-auth-method: not-applicable
  links:
    - url: https://github.com/pagarme/backstage/actions/workflows/deploy_prd.yaml
      title: CD Pipeline
    - url: https://app.datadoghq.com/dashboard/fpr-ncq-gnm/backstage
      title: Monitoring
    - url: https://app.datadoghq.com/monitors/manage?q=service%3A%22backstage%22
      title: Incident Manager
spec:
  type: website
  lifecycle: production
  owner: stone-payments/platform-squad-writer
  system: platform
  dependsOn:
    - resource:backstage-database

API

Uma API descreve a interface que é exposta por um Component. Essa API pode ser definida em diferentes formatos, como OpenAPI, AsyncAPI, GraphQL, etc.

Parâmetros suportados

• type - (Required) O nome do tipo do schema da API. Os valores possíveis são: openapi, asyncapi, graphql e grpc.
• lifecycle - (Required) O estado de lifecycle da API. Os valores possíveis são:
  • production: uma API produtiva, mantida e bem estabelecida;
  • experimental: uma API em estágios iniciais, não-produtiva. Esse lifecycle sinaliza que a API não possui garantias de reliability e que os consumidores podem preferir não consumí-la no lugar de outras com lifecycle de production;
  • deprecated: uma API no final de seu lifecycle. Pode ser descontinuada/removida em breve.
• owner - (Required) Uma referência ao nome do time responsável pela API. O formato deve ser: <github-org>/<github-team>. Veja o exemplo na subsessão abaixo.
• definition - (Required) A definição da API com base no formato especificado no campo type. A definição pode ser em texto puro ou referenciando um arquivo que exista no mesmo repositório que o manifesto está sendo criado. Veja os dois exemplos na subsessão abaixo.
• system - (Opcional) Uma referência ao nome do System que engloba essa API.

Exemplos

API referenciando um arquivo swagger.json que contém sua definição:

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: backstage-api
  namespace: stone
  description: Backstage Backend System
  title: Backstage Backend API
spec:
  type: openapi
  lifecycle: production
  owner: stone-payments/platform-squad-writer
  system: platform
  definition: 
    $text: ./../swagger.json

API com definição em texto puro:

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: backstage-api
  namespace: stone
  description: Backstage Backend System
  title: Backstage Backend API
spec:
  type: openapi
  lifecycle: production
  owner: stone-payments/platform-squad-writer
  system: platform
  definition: |
    openapi: "3.0.0"
    info:
      version: 1.0.0
      title: Backstage API
      license:
        name: MIT
    servers:
      - url: https://backstage.stone.tech
    paths:
      /components:
        get:
          summary: List all components
    ...

Resource

Um `Resource` descreve um recurso de infraestrutura, por exemplo, _S3 buckets_, bancos de dados, tópicos de filas, etc.

Parâmetros suportados

• owner - (Required) Uma referência ao nome do time responsável pelo recurso. O formato deve ser: <github-org>/<github-team>. Veja o exemplo na subsessão abaixo.
• type - (Required) O nome do tipo do Resource. Se o Resource representar um banco de dados, o valor deve ser database. Para outros recursos de infraestrutura, o campo aceita qualquer valor.
• system - (Opcional) Uma referência ao nome do System que engloba essa API.
• dependsOn - (Opcional) Uma lista de referências aos nomes de Components ou Resources que esse recurso depende. O formato aceito é: <tipo-da-entidade>:<nome-da-entidade>. Veja o exemplo na subsessão abaixo.
• dependencyOf - (Opcional) Uma lista de referências aos nomes de Components ou Resources que esse recurso é dependência. O formato aceito é: <tipo-da-entidade>:<nome-da-entidade>.

Labels especiais

Os campos abaixo devem estar definidos dentro de metadata.labels:

• stone.tech/dbms (Optional) Enum que representa o Data Base Management System do Resource. Esse campo se torna obrigatório se spec.type: database. As opções são: mysql, postgresql, sqlserver e mongodb.

Exemplos

apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
  name: backstage-database
  namespace: stone
  description: Backstage PostgreSQL Database
  title: Backstage Database
  labels:
    stone.tech/dbms: postgresql
spec:
  type: database
  owner: stone-payments/platform-squad-writer
  system: platform
  dependsOn:
    - resource:platform-eks-cluster

Importante: verifique se este PR foi feito para a sua branch de trabalho correta. Caso negativo, altere a branch de destino!

Veja a nossa documentação explicando em mais detalhes sobre Backstage.

Em caso de duvidas, consultar nossa FAQ

[backstage-catalog-validator]

⚠️ Existe pelo menos um catálogo do Backstage inválido nesse pull request. ⚠️

67 tests: 57 passed, 0 warnings, 10 failures, 0 exceptions and 0 invalid files.

🔗 Clique aqui para mais detalhes. Por favor revise o(s) problema(s) e conserte antes do merge.
💁 Qualquer dúvida, sinta-se à vontade para entrar em contato conosco no canal do Slack #backstage .

📄 Mais detalhes sobre o funcionamento do backstage-catalog-validador nesta documentação.