Platform Engineering: Internal Developer Platform con Backstage, Crossplane e Golden Path

🧰 Materiali necessari

• Cluster Kubernetes 1.28+
• Node.js 20+ e Yarn 4+ per Backstage development
• PostgreSQL 14+ per Backstage production
• Backstage 1.25+
• Crossplane 1.15+ con provider AWS o Azure
• GitHub con repository per template e config
• GitHub App o Personal Access Token
• ArgoCD per CD integration
• Helm 3.14+
• Cloud account per Crossplane provisioning
• Infracost API token per cost estimation
• Trivy per security scanning integration
• PagerDuty o Opsgenie per on-call integration
• mkdocs per TechDocs documentation
• Domain e TLS certificate per portal pubblico

📋 Passi

1. 1
   Installazione Backstage development
   {"step":1,"title":"Installazione Backstage development","description":"Setup Node.js 20+ e Yarn 4+. Crea Backstage instance con npx @backstage\/create-app@latest. Setup interattivo: inserisci nome del portal aziendale. Avvia con yarn dev che avvia frontend su porta 3000 e backend su porta 7007. Verifica accesso a localhost:3000 con UI default e catalog di esempio precaricato. Familiarizza con struttura: packages\/app frontend, packages\/backend, app-config.yaml configurazione centrale. Database SQLite per development, PostgreSQL richiesto per production."}
2. 2
   Deploy production su Kubernetes con PostgreSQL
   {"step":2,"title":"Deploy production su Kubernetes con PostgreSQL","description":"Per production deployment, configura PostgreSQL backend con Helm: helm install backstage-db bitnami\/postgresql nel namespace dedicato. Aggiorna app-config.production.yaml con database connection: host, port, credential da secret. Build Backstage Docker image con yarn build:backend usando Dockerfile incluso nel progetto. Deploy a Kubernetes via Helm chart ufficiale con ingress.enabled e host configurati. Configura TLS con cert-manager. Verifica accesso production-grade tramite HTTPS."}
3. 3
   Integrazione GitHub per catalog discovery automatica
   {"step":3,"title":"Integrazione GitHub per catalog discovery automatica","description":"In app-config.yaml configura integrations.github con personal access token o GitHub App per enterprise. Abilita auth provider github per OAuth login degli utenti. Configura catalog.providers.github per discovery automatica di catalog-info.yaml files in tutti i repository della organizzazione. Backstage scansiona org repos periodicamente e ingerisce ogni catalog-info.yaml trovato. Aggiungi catalog-info.yaml di esempio in un repo esistente e verifica catalog popolato in UI."}
4. 4
   Software template per nuovo microservizio
   {"step":4,"title":"Software template per nuovo microservizio","description":"Crea repository templates con struttura templates\/nodejs-microservice. Template.yaml con metadata, spec parameters (service name, description, owner come input form), spec steps (fetch boilerplate da skeleton directory, fill template variable con Nunjucks, publish.github crea repo, catalog.register aggiunge a Backstage). Registra template in app-config.yaml catalog.locations. Testa completamente: in UI click Create, seleziona template, compila form, submit. Nuovo repo creato in GitHub con codice scaffolded e registrato."}
5. 5
   TechDocs per documentation centralizzata
   {"step":5,"title":"TechDocs per documentation centralizzata","description":"Abilita techdocs plugin in app-config.yaml. Configura builder local per development o external con S3 o GCS storage per production. Per ogni component aggiungi annotation backstage.io\/techdocs-ref: dir:. in catalog-info.yaml. Repository contiene mkdocs.yml e directory docs con markdown files strutturati. Backstage builds docs on-demand o su push via CI integration. Verifica docs accessibili da component page con search funzionante across tutta la documentazione."}
6. 6
   Installazione Crossplane e primo Provider AWS
   {"step":6,"title":"Installazione Crossplane e primo Provider AWS","description":"Installa Crossplane via Helm in namespace crossplane-system: helm install crossplane crossplane-stable\/crossplane. Verifica pod running correttamente. Installa AWS Provider applicando manifest Kind Provider con spec.package puntando a provider-aws-s3 da xpkg.upbound.io. Crea ProviderConfig con AWS credential come Kubernetes secret. Verifica provider healthy con kubectl get providers. Provider aggiunge nuovi CRD per tutte le resource AWS gestibili da Kubernetes."}
7. 7
   Primo Crossplane resource S3 bucket
   {"step":7,"title":"Primo Crossplane resource S3 bucket","description":"Applica manifest Bucket con apiVersion s3.aws.upbound.io\/v1beta1, nome bucket unico, region us-east-1. Crossplane controller osserva, chiama AWS API, provisiona actual S3 bucket. Verifica in AWS console bucket creato con stesso nome. Modifica spec e osserva Crossplane reconciliare automaticamente la differenza. Delete CR: bucket deleted seguendo deletionPolicy configurata. Pattern Kubernetes-native per cloud resource lifecycle completo senza Terraform."}
8. 8
   Composition per PostgreSQL self-service
   {"step":8,"title":"Composition per PostgreSQL self-service","description":"Crea CompositeResourceDefinition per XPostgreSQL con spec che definisce input schema (size, version, environment) e claim names. Crea Composition implementing XPostgreSQL con RDSInstance, SecurityGroup, SecretsManager secret tutti parametrizzati. Applica XRD e Composition al cluster. Developer ora crea PostgreSQL claim con campi minimali. Crossplane provisiona tutti i resource sottostanti automaticamente. Developer non vede complessita implementativa, solo interface semplice."}
9. 9
   Backstage template con Crossplane self-service
   {"step":9,"title":"Backstage template con Crossplane self-service","description":"Aggiungi Backstage template che provisiona database via Crossplane in modo integrato. Template parameters: database name, size dropdown (small, medium, large), versione database. Steps: render Kubernetes manifest PostgreSQL claim, commit a Git config repo, ArgoCD sync triggera Crossplane provisioning. Output template mostra link a claim status nel Kubernetes plugin di Backstage. Developer self-service database in 5 minuti con full audit trail automatico."}
10. 10
    Kubernetes plugin per observability integrata
    {"step":10,"title":"Kubernetes plugin per observability integrata","description":"Installa Backstage Kubernetes plugin: yarn add @backstage\/plugin-kubernetes al frontend. Configura connessione a cluster via service account con token, URL, CA cert in app-config.yaml. Aggiungi annotation backstage.io\/kubernetes-id: myapp in catalog-info.yaml per identificare workload. Component page in Backstage mostra: deployment status, pod list, events, logs recenti. Developer non deve aprire kubectl o dashboard separato: tutto nel portal centralizzato."}
11. 11
    Plugin ArgoCD per CD visibility integrata
    {"step":11,"title":"Plugin ArgoCD per CD visibility integrata","description":"Installa ArgoCD plugin: yarn add @roadiehq\/backstage-plugin-argo-cd. Configura connessione a ArgoCD instance con URL e token come secret. Aggiungi annotation argocd\/app-name per mappare component ad ArgoCD application. Component page mostra: sync status, last sync time, health, links a ArgoCD UI per deep dive. Developer monitora deployment senza dashboard separato. Pattern uguale per Jenkins plugin (build status) e PagerDuty (on-call rotation)."}
12. 12
    Cost visibility con Infracost integration
    {"step":12,"title":"Cost visibility con Infracost integration","description":"Setup Infracost API token (free tier disponibile). Per template che provisionano infrastruttura aggiungi cost preview pre-submit form. Template form mostra estimated monthly cost basato su parametri di input prima del submit per awareness economica. Cost dashboard plugin in Backstage: per component mostra monthly cost corrente da actual usage cloud, top spending component, trend over time, anomaly detection. Cost ownership chiara per team tramite component owner mapping."}
13. 13
    Security posture dashboard aggregata
    {"step":13,"title":"Security posture dashboard aggregata","description":"Integra con Trivy per image vulnerability, tfsec per Terraform security scanning, Snyk per application dependency. Plugin custom o esistente aggrega security findings per component nel portal. Component page mostra: count open critical CVE, giorni dall ultimo scan, security score aggregato. Dashboard aggregate mostra org-wide security health, top vulnerable component, trend nel tempo. Combina con SLA: critical CVE deve essere patchata entro 7 giorni, dashboard traccia compliance."}
14. 14
    Golden path documentation e governance
    {"step":14,"title":"Golden path documentation e governance","description":"Documenta golden path esplicitamente in TechDocs sezione Platform Guide. Sezioni: come creare nuovo service (link a template), come deployare in production (procedura step-by-step), come aggiungere database, come configurare monitoring, come gestire incident. Visualizza golden path con diagrammi architetturali. Anti-pattern documentati: cosa NON fare e perche (costo, sicurezza, maintainability). Review trimestrale dei path: depreca obsoleti, introduce nuovi, comunica cambiamenti."}
15. 15
    Adoption metric e platform evolution continua
    {"step":15,"title":"Adoption metric e platform evolution continua","description":"Instrumenta metric platform: percentuale service usando template vs creazione ad-hoc, template completion rate, time-to-first-deploy per nuovo service, NPS survey developer trimestrale. Dashboard Grafana con metric chiave per platform team. Review trimestrale: identifica friction (template con high abandonment indica UX issue), prioritizza backlog (feature piu richieste dai team). OKR platform team allineati con developer productivity: esempio ridurre average time-to-production da 2 settimane a 2 giorni."}