Platform engineering na prática: IDP com Kubernetes, CI/CD e infraestrutura como código

A platform engineering transforma contas cloud fragmentadas, templates CI e conhecimento tribal num produto: a Internal Developer Platform (IDP). Para empresas a enviar funcionalidades de IA, plataformas tradicionais devem estender-se a routing de modelos, gateways seguros de ferramentas, pipelines de dados governados e guardrails FinOps sem forçar cada esquadrão a tornar-se admin de cluster. Este guia define capacidades IDP, arquitetura de referência, golden paths, topologias de equipa e métricas que ressoam com líderes de engenharia europeus. Liga-se a arquitetura empresarial de IA agéntica, FinOps para Kubernetes e IA e governação de dados pronta para IA. A Damascode, Digital Agency, Lda constrói e moderniza plataformas através de consultoria de TI, desenvolvimento nearshore e outsourcing de desenvolvimento de software quando precisa de esquadrões de plataforma sustentados.

Índice

• O que é uma IDP (e o que não é)
• Mentalidade plataforma como produto
• Mapa de capacidades para empresas modernas
• Arquitetura de referência
• Golden paths e templates
• Self-service vs ticket ops
• Integração de segurança e conformidade
• Extensões de plataforma IA e agentes
• Métricas de developer experience
• Topologias de equipa e staffing
• Build vs buy vs parceiro
• Roteiro de implementação
• Exemplos de código e configuração
• Rituais operacionais
• FAQ
• Referências

O que é uma IDP (e o que não é)

Uma IDP não é só Kubernetes, nem um depósito de Helm charts. É a interface curada através da qual equipas de aplicação provisionam, fazem deploy, observam e protegem software com guardrails.

Sucesso parece programadores a enviar um novo microserviço ou funcionalidade IA para staging em horas, com logging, métricas, segredos e tags de custo já ligados.

Mentalidade plataforma como produto

Trate programadores internos como clientes:

• Entreviste-os trimestralmente.
• Publique roteiro e changelog.
• Meça adoção, não contagem de tickets fechados.
• Deprecie com janelas de migração.

           +------------------+
           |  Esquadrões app  |
           +--------+---------+
                    |
                    v
           +--------+---------+
           |  Portal IDP / CLI |
           +--------+---------+
                    |
      +-------------+-------------+
      |             |             |
 +----v----+   +----v----+   +----v----+
 | Pipeline|   | Catálogo|   | Gateway |
 | deploy  |   | dados   |   | svc IA  |
 +----+----+   +----+----+   +----+----+
      |             |             |
      +-------------+-------------+
                    v
           +--------+---------+
           | Infra partilhada |
           | (K8s, IAM, VPC)  |
           +------------------+

Mapa de capacidades para empresas modernas

Capacidades em falta forçam equipas a abrir contas shadow IT, o anti-padrão IDP principal.

Arquitetura de referência

Camadas lógicas:

1. Experiência: portal (Backstage, Port, custom), CLI, plugins IDE.
2. Control plane: software templates, definições de ambiente, verificações de política.
3. Execução: runners CI, GitOps (Argo CD, Flux), Terraform Cloud ou equivalente.
4. Infraestrutura: clusters, networking, serviços partilhados (operadores Kafka, Postgres).

 Portal (Backstage)
      |
      | scaffolder template
      v
 Git repo --> CI (test, scan) --> GitOps --> K8s prod
      ^                                |
      |                                v
 Policy OPA / Kyverno            Secrets / IAM

Alinhe segurança com segurança empresarial de IA: templates IDP embebem defaults seguros (network policy, resource limits, no root).

Golden paths e templates

Um golden path é a forma abençoada de construir uma classe de sistema:

Fragmento template Backstage (YAML ilustrativo):

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: ai-feature-service
  title: AI Feature Service
spec:
  parameters:
    - title: Service
      properties:
        name: { type: string }
        owner: { type: string }
        costCenter: { type: string }
        aiTier: { type: string, enum: [T0, T1, T2] }
  steps:
    - id: fetch
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}
          labels:
            team: ${{ parameters.owner }}
            cost-center: ${{ parameters.costCenter }}
            ai.tier: ${{ parameters.aiTier }}

Esquadrões podem sair do golden path com revisão de arquitetura, não forks silenciosos.

Self-service vs ticket ops

Automatize aprovações com política: quota GPU pequena em dev auto-aprova; prod requer ticket.

Integração de segurança e conformidade

Embebido em cada template:

• Federação OIDC de CI para cloud
• Imagens assinadas (Cosign)
• Geração SBOM
• NetworkPolicy default deny
• Pod Security Standards (restricted quando possível)

Exemplo política Kyverno (exigir labels):

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: require-finops-labels
spec:
  validationFailureAction: Enforce
  rules:
    - name: check-labels
      match:
        any:
          - resources:
              kinds: [Deployment]
      validate:
        message: "cost-center and team labels are required"
        pattern:
          metadata:
            labels:
              cost-center: "?*"
              team: "?*"

Mapeie para controlos SOC2/ISO via exports de evidência de GitOps e CI.

Extensões de plataforma IA e agentes

Equipas de plataforma tornam-se enablers para IA agéntica:

Esboço middleware TypeScript para orçamento token numa biblioteca partilhada:

export function withTokenBudget(maxTokens: number) {
  let used = 0;
  return async (next: (n: number) => Promise<string>, n: number) => {
    if (used + n > maxTokens) {
      throw new Error("Token budget exceeded for this request");
    }
    used += n;
    return next(n);
  };
}

Documente tier (T0-T2) no catálogo de serviços para segurança conhecer raio de explosão.

Métricas de developer experience

Métricas DORA ainda aplicam; acrescente NPS plataforma e tempo à espera de ticket plataforma.

Topologias de equipa e staffing

Padrões comuns:

• Enabling team: coaches, plataforma fina.
• Platform team: detém a IDP, SRE para serviços partilhados.
• Esquadrões stream-aligned: consomem IDP, são donos das apps.

Guideline de staffing (ilustrativo, ajustar à escala):

Parceiro com desenvolvimento nearshore para picos de capacidade; retenha ownership de produto internamente.

Build vs buy vs parceiro

Compre portal, construa diferenciação (políticas, paths IA, integração dados).

Catálogo de serviços e ownership

catalog-info.yaml Backstage (ou equivalente) deve ser obrigatório para serviços de produção:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: invoice-summary
  annotations:
    backstage.io/techdocs-ref: dir:.
  labels:
    ai.tier: T1
spec:
  type: service
  lifecycle: production
  owner: group:team-billing
  system: billing
  dependsOn:
    - resource:default/ai-inference-gateway

Ligações a runbooks TechDocs, dashboards SLO e rotações on-call. Serviços IA declaram dependência de recursos gateway partilhados para análise de raio de explosão em incidentes.

Paridade de ambiente e stacks preview

Programadores confiam na IDP quando ambientes preview espelham política prod em escala menor:

Namespaces efémeros por pull request reduzem surpresas de integração. Desmontar após merge com controlador TTL automatizado para controlar desperdício FinOps.

Platform API vs portal

Algumas equipas preferem CLI/API a UI. Exponha ações IDP via Platform API REST ou GraphQL estável:

• POST /v1/namespaces com perfil quota
• POST /v1/services/from-template/{id}
• GET /v1/cost/team/{id}/month-to-date

Portal torna-se um cliente; automação e service accounts integram CI e chatops. Versione APIs; deprecie com aviso de seis meses.

Gerir dívida técnica de plataforma

Equipas de plataforma acumulam dívida quando pedidos urgentes de produto saltam atualizações de template. Agende sprints refactor plataforma cada trimestre:

• Colapsar workflows CI duplicados
• Upgrade versão minor cluster em non-prod primeiro
• Remover templates não usados (telemetria em uso scaffolder)

Métricas dívida: número de serviços fora golden path, tempo médio para upgrade add-ons cluster, percentagem políticas enforced vs advisory.

Onboarding de programadores na IDP

Checklist primeira semana para novos engenheiros:

• Acesso portal e grupo SSO
• Executar tutorial golden path (deploy serviço exemplo)
• Ler defaults segurança para tier IA
• Entrar canal Slack plataforma e office hours

Meça time-to-first-successful-deploy para cohorts onboarding; se acima de dois dias, melhore docs ou defaults template.

Roteiro de implementação

Fase 0 (mês 0-1): discovery

• Entrevistas programadores, mapa de dor
• Inventário clusters, sistemas CI, caminhos deploy shadow
• Definir primeiro golden path (muitas vezes REST ou site estático)

Fase 1 (mês 2-4): MVP

• Software template + env GitOps
• Bundle observabilidade
• Site documentação no portal

Fase 2 (mês 5-8): scale

• Fluxo promoção produção
• Visibilidade custo (guia FinOps)
• Políticas segurança enforced

Fase 3 (mês 9+): IA

• Template ingest RAG (governação dados)
• Gateway inference
• Gateway ferramentas agente com MCP

Exemplos de código e configuração

Chamada workflow reutilizável GitHub Actions (conceptual)

jobs:
  deploy:
    uses: org/platform-pipelines/.github/workflows/deploy-k8s.yml@v2
    with:
      service: ${{ github.event.repository.name }}
      environment: staging
    secrets: inherit

Bash: wrapper CLI programador

#!/usr/bin/env bash
set -euo pipefail
idp service create --template ai-feature-service \
  --param name=invoice-summary \
  --param owner=team-billing \
  --param costCenter=CC-2201 \
  --param aiTier=T1

Consumo módulo Terraform

module "service_namespace" {
  source = "git::https://github.com/terraform-aws-modules/terraform-aws-eks.git?ref=v20.0.0"

  name         = "invoice-summary"
  cluster_name = "prod-eu-west"
  labels = {
    team        = "team-billing"
    cost-center = "CC-2201"
  }
  quota = {
    cpu    = "20"
    memory = "40Gi"
  }
}

Fixe versões de módulo; semver da equipa plataforma comunica breaking changes.

Rituais operacionais

Publique página de estado para serviços partilhados (ingress, CI, artifact registry).

Quando dívida plataforma bloqueia OKRs produto, escale ao fórum arquitetura; Damascode pode facilitar via consultoria de TI. Contacto ou leia sobre nós.

FAQ

Backstage é obrigatório?
Não. Qualquer portal mais templates mais docs funciona se adoção for medida.

Como evitar equipa plataforma tornar-se bottleneck?
Expanda self-service, melhore docs, automatize aprovações, contrate skills produto.

Programadores perdem flexibilidade?
Ganham velocidade no path 80%; exceções permanecem com revisão.

Como IDP se relaciona com DevOps?
DevOps é cultura; IDP é implementação produtizada de estradas pavimentadas.

Uma plataforma pode suportar multi-cloud?
Sim, com camadas abstração e disciplina política mais forte; custo é maior.

E VMs legacy?
Integre via mesmos links portal e strangulation gradual; não finja que tudo é K8s no dia um.

Quanto até programadores sentirem valor?
Alvo primeiro deploy golden path em menos de um dia dentro de oito semanas após launch MVP; comunique vitórias em town halls.

Equipa plataforma deve fazer on-call de todas as apps?
Não. On-call plataforma cobre serviços partilhados (ingress, CI, clusters). Esquadrões app são responsáveis pelos SLOs da aplicação. Limites paging claros reduzem burnout.

Como medir qualidade template?
Acompanhe taxa sucesso scaffolder, time-to-first-green pipeline e tickets suporte etiquetados platform/template.

A IDP pode impor tier IA no deploy?
Sim via política: Deployments com label ai.tier=T2 requerem annotation security-review-id presente ou admission nega.

Template scorecard para liderança plataforma

Revisão trimestral com diretores engenharia; ligue pedidos funding a lacunas scorecard.

Marketing interno para a plataforma

Programadores adoptam ferramentas de que ouvem falar de pares. Equipa plataforma deve:

• Correr demo days mensais mostrando deploy golden path em menos de dez minutos.
• Publicar guias migração ao depreciar jobs Jenkins antigos.
• Celebrar equipas que melhoraram defaults template via pull requests contribuídos.
• Manter roteiro interno público com datas realistas.

Plataformas sub-comunicadas tornam-se prateleira enquanto CI shadow persiste.

Modelo plugin e extensibilidade

Plugins estilo Backstage devem cumprir standards plataforma:

Forneça plugin starter kit com CI, lint e sample API client para Platform API. Esquadrões estendem portal sem fork core.

Disaster recovery para plataforma partilhada

Game days validam backups etcd cluster e state Terraform; documente ordem restore (rede, cluster, GitOps, apps).

Standards pipeline CI embebidos na IDP

Cada pipeline golden path deve incluir:

Centralize versão pipeline no repo plataforma; esquadrões fixam @v4 não copy-paste YAML. Breaking changes comunicadas via changelog e PR automatizado a repos consumidores quando possível.

Federação com equipas plataforma dados e IA

Grandes empresas dividem IDP core (compute, delivery, identity) de plataforma dados (warehouse, catálogo) e plataforma IA (gateway inference, MCP). Defina interfaces:

Conselho plataforma trimestral alinha roteiros e evita portais duplicados. SSO único num shell portal com deep links a consolas especializadas é aceitável se navegação for coerente.

Novos serviços IA registam-se no catálogo com dependências em gateway inference e datasets aprovados, ligando documentação governação dados e arquitetura agéntica a partir de TechDocs.

Product managers plataforma devem gastar pelo menos vinte por cento da capacidade sprint em pesquisa developer experience: shadowing deploys esquadrão, medir fricção em formulários scaffolder e corrigir papercuts. Uma IDP que poupa dez minutos por deploy em duzentos engenheiros semanalmente devolve mais valor que projeto abstração multi-cloud raro que ninguém pediu.

Acessibilidade e developer experience inclusiva

UX portal deve cumprir básicos orientados WCAG: navegação teclado em formulários scaffolder, contraste suficiente e labels screen reader em chips estado (deploy succeeded/failed). Plataformas internas ignoram muitas vezes acessibilidade porque utilizadores são empregados; design inclusivo reduz erros em incidentes quando engenheiros fazem deploy de portáteis sob stress.

Documente golden paths em linguagem clara com diagramas, não só dumps API auto-gerados. Ofereça traduções doc quando o hub engenharia abrange vários países UE.

Evolução plataforma longo prazo

Ano um entrega paths MVP. Ano dois consolida duplicados e enforced política. Ano três optimiza custo e acrescenta serviços específicos IA. Evite reiniciar plataforma cada vez que liderança muda preferência vendor; abstraia atrás de interfaces que os vossos templates controlam, e troque implementações no control plane sem forçar cada esquadrão a reescrever aplicações.

Publique avisos depreciação pelo menos noventa dias antes de remover versão template, com codemods ou scripts migração quando viável. Nada erode confiança mais rápido que botão deploy partido no dia release.

Acompanhe percentagem conclusão migração em dashboards plataforma e escale consumidores remanescentes via engineering managers, não só lembretes chat.

Recompense esquadrões que contribuem melhorias template com reconhecimento público em all-hands engenharia e aprovações quota mais rápidas para funcionalidades piloto.

Mantenha feed changelog plataforma RSS ou Slack para programadores verem novos golden paths, alterações política e postmortems incidentes que afetam serviços partilhados sem procurar Confluence. Fixe feed no canal onboarding engenharia.

Ao avaliar vendors IDP comerciais, pontue-os em extensibilidade API e hooks política, não só estética portal. A vossa diferenciação vive em templates e políticas que vendors não replicam de tenant demo.

Referências

• Team Topologies: https://teamtopologies.com/
• Documentação Backstage: https://backstage.io/docs/overview/what-is-backstage
• CNCF Platforms Whitepaper: https://tag-app-delivery.cncf.io/whitepapers/platforms/
• Documentação Kubernetes: https://kubernetes.io/docs/home/
• Argo CD: https://argo-cd.readthedocs.io/
• Flux: https://fluxcd.io/
• Open Policy Agent: https://www.openpolicyagent.org/
• Kyverno: https://kyverno.io/
• FinOps Foundation: https://www.finops.org/
• Model Context Protocol: https://modelcontextprotocol.io/
• Insights relacionados: IA agéntica, segurança IA, governação dados, FinOps