Platform Engineering Complete Guide 2025: Internal Developer Platform, Backstage, Golden Path

Developer Cognitive Load Over Time:

Early 2010s:                 Today:
┌───────────────┐            ┌───────────────┐
│ Business Logic│            │ Business Logic│
│               │            ├───────────────┤
│               │            │ CI/CD Pipelines│
│               │            ├───────────────┤
│               │            │ Infrastructure │
│               │            ├───────────────┤
│               │            │ Observability  │
│               │            ├───────────────┤
│               │            │ Security/Compl.│
│               │            ├───────────────┤
│               │            │ Kubernetes     │
└───────────────┘            └───────────────┘

# Comparison based on Team Topologies
devops_team:
  role: "Bridge between development and operations"
  approach: "Embed DevOps engineers in each team"
  problems:
    - "DevOps engineers become bottlenecks"
    - "Different tools and processes per team"
    - "Knowledge concentrated in individuals"
    - "Repetitive infrastructure tasks"

platform_team:
  role: "Build and operate the internal platform product"
  approach: "Provide self-service platform"
  advantages:
    - "Increased developer autonomy"
    - "Standardized tools and processes"
    - "Knowledge embedded in the platform"
    - "Automated guardrails"

team_topologies_mapping:
  stream_aligned_team: "Teams building business features (developers)"
  platform_team: "Team building and operating the IDP"
  enabling_team: "Team helping adopt new technologies"
  complicated_subsystem_team: "Specialists for complex subsystems"

┌─────────────────────────────────────────────────────┐
│               Developer Portal Layer                  │
│     (Backstage, Port, Humanitec Score UI)            │
├─────────────────────────────────────────────────────┤
│              Integration & Delivery Layer              │
│     (CI/CD: GitHub Actions, ArgoCD, Tekton)           │
├─────────────────────────────────────────────────────┤
│             Security & Compliance Layer                │
│     (OPA, Kyverno, Vault, Policy-as-Code)            │
├─────────────────────────────────────────────────────┤
│               Resource Management Layer               │
│     (Terraform, Crossplane, Pulumi, Helm)            │
├─────────────────────────────────────────────────────┤
│               Infrastructure Layer                    │
│     (AWS, GCP, Azure, Kubernetes)                    │
└─────────────────────────────────────────────────────┘

# Core IDP components
service_catalog:
  description: "Central catalog of all services, APIs, and infrastructure"
  capabilities:
    - "Service ownership and dependency tracking"
    - "Automatic API documentation"
    - "Service maturity scorecards"
  tools: "Backstage Software Catalog, Port"

software_templates:
  description: "Create new projects in a standardized way"
  capabilities:
    - "Microservice scaffolding"
    - "Automatic CI/CD pipeline setup"
    - "Monitoring/logging included by default"
  tools: "Backstage Software Templates, Cookiecutter"

self_service_infrastructure:
  description: "Developers provision infrastructure directly"
  capabilities:
    - "Database creation"
    - "Cache cluster provisioning"
    - "Message queue setup"
  tools: "Crossplane, Terraform modules, Pulumi"

documentation:
  description: "Technical docs integrated with code repositories"
  capabilities:
    - "Markdown-based documentation"
    - "API documentation automation"
    - "Architecture diagrams"
  tools: "Backstage TechDocs, ReadTheDocs"

developer_portal:
  description: "Unified UI that ties everything together"
  capabilities:
    - "Browse service catalog"
    - "Execute templates"
    - "Search documentation"
    - "View costs"
  tools: "Backstage, Port, Cortex"

Backstage Core Features:

┌─────────────────────────────────────────────────────┐
│                   Backstage                           │
│                                                       │
│  ┌─────────────┐ ┌──────────────┐ ┌──────────────┐  │
│  │  Software    │ │  Software    │ │   TechDocs   │  │
│  │  Catalog    │ │  Templates   │ │              │  │
│  │             │ │              │ │  Code-based   │  │
│  │ Service list│ │ Project      │ │  tech docs   │  │
│  │             │ │ creation     │ │              │  │
│  └─────────────┘ └──────────────┘ └──────────────┘  │
│                                                       │
│  ┌─────────────┐ ┌──────────────┐ ┌──────────────┐  │
│  │  Kubernetes │ │   Search     │ │   Plugins    │  │
│  │  Plugin     │ │              │ │  Ecosystem   │  │
│  │             │ │  Full-text   │ │              │  │
│  │ K8s integ.  │ │  search     │ │  100+ plugins│  │
│  └─────────────┘ └──────────────┘ └──────────────┘  │
└─────────────────────────────────────────────────────┘

# catalog-info.yaml - Service registration file
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: user-service
  description: "User management microservice"
  annotations:
    github.com/project-slug: "myorg/user-service"
    backstage.io/techdocs-ref: "dir:."
    pagerduty.com/service-id: "PXXXXXX"
    grafana/dashboard-selector: "user-service"
    sonarqube.org/project-key: "myorg_user-service"
  tags:
    - java
    - spring-boot
    - user-management
  links:
    - url: "https://grafana.internal/d/user-service"
      title: "Grafana Dashboard"
      icon: dashboard
    - url: "https://user-service.internal/swagger-ui"
      title: "API Docs"
      icon: docs
spec:
  type: service
  lifecycle: production
  owner: team-backend
  system: user-platform
  providesApis:
    - user-api
  consumesApis:
    - auth-api
    - notification-api
  dependsOn:
    - resource:default/user-database
    - resource:default/redis-cache
---
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: user-api
  description: "User management REST API"
spec:
  type: openapi
  lifecycle: production
  owner: team-backend
  system: user-platform
  definition:
    $text: ./api/openapi.yaml
---
apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
  name: user-database
  description: "User service PostgreSQL database"
spec:
  type: database
  owner: team-backend
  system: user-platform

# template.yaml - Microservice creation template
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: spring-boot-microservice
  title: "Spring Boot Microservice"
  description: "Create a standard Spring Boot microservice project"
  tags:
    - java
    - spring-boot
    - recommended
spec:
  owner: team-platform
  type: service

  parameters:
    - title: "Service Basics"
      required:
        - serviceName
        - owner
        - description
      properties:
        serviceName:
          title: "Service Name"
          type: string
          description: "kebab-case format (e.g., user-service)"
          pattern: "^[a-z][a-z0-9-]*$"
        owner:
          title: "Owning Team"
          type: string
          ui:field: OwnerPicker
          ui:options:
            allowedKinds:
              - Group
        description:
          title: "Service Description"
          type: string
        javaVersion:
          title: "Java Version"
          type: string
          enum: ["17", "21"]
          default: "21"

    - title: "Infrastructure"
      properties:
        database:
          title: "Database"
          type: string
          enum: ["postgresql", "mysql", "none"]
          default: "postgresql"
        cache:
          title: "Cache"
          type: string
          enum: ["redis", "none"]
          default: "redis"
        messageQueue:
          title: "Message Queue"
          type: string
          enum: ["kafka", "rabbitmq", "sqs", "none"]
          default: "none"

  steps:
    - id: fetch-template
      name: "Fetch template code"
      action: fetch:template
      input:
        url: "./skeleton"
        values:
          serviceName: "${{ parameters.serviceName }}"
          owner: "${{ parameters.owner }}"
          description: "${{ parameters.description }}"
          javaVersion: "${{ parameters.javaVersion }}"
          database: "${{ parameters.database }}"
          cache: "${{ parameters.cache }}"

    - id: publish
      name: "Create GitHub repository"
      action: publish:github
      input:
        allowedHosts: ["github.com"]
        repoUrl: "github.com?owner=myorg&repo=${{ parameters.serviceName }}"
        description: "${{ parameters.description }}"
        defaultBranch: main
        protectDefaultBranch: true
        repoVisibility: internal

    - id: register
      name: "Register in Backstage catalog"
      action: catalog:register
      input:
        repoContentsUrl: "${{ steps.publish.output.repoContentsUrl }}"
        catalogInfoPath: "/catalog-info.yaml"

    - id: create-argocd-app
      name: "Create ArgoCD application"
      action: argocd:create-resources
      input:
        appName: "${{ parameters.serviceName }}"
        argoInstance: "main"
        namespace: "${{ parameters.serviceName }}"
        repoUrl: "${{ steps.publish.output.remoteUrl }}"
        path: "k8s/overlays/development"

  output:
    links:
      - title: "GitHub Repository"
        url: "${{ steps.publish.output.remoteUrl }}"
      - title: "Backstage Catalog"
        icon: catalog
        entityRef: "${{ steps.register.output.entityRef }}"

# mkdocs.yml - TechDocs configuration
site_name: "User Service"
site_description: "User management microservice technical docs"

nav:
  - Home: index.md
  - Architecture:
    - Overview: architecture/overview.md
    - Data Model: architecture/data-model.md
    - API Design: architecture/api-design.md
  - Development:
    - Getting Started: development/getting-started.md
    - Local Setup: development/local-setup.md
    - Testing Guide: development/testing.md
  - Operations:
    - Deployment: operations/deployment.md
    - Monitoring: operations/monitoring.md
    - Runbook: operations/runbook.md

plugins:
  - techdocs-core

# Popular Backstage plugins
kubernetes_plugin:
  feature: "View K8s cluster service status"
  usage: "Check Pod status, logs, events directly in Backstage"

github_actions_plugin:
  feature: "Display CI/CD pipeline status"
  usage: "View build/deployment status on service pages"

pagerduty_plugin:
  feature: "On-call schedule and incident integration"
  usage: "Show service owner on-call status"

cost_insights_plugin:
  feature: "Cloud cost analysis"
  usage: "Per-service cost tracking and trend analysis"

tech_radar_plugin:
  feature: "Technology radar visualization"
  usage: "Manage organization's technology adoption status"

sonarqube_plugin:
  feature: "Code quality metrics display"
  usage: "View per-service code quality scores"

grafana_plugin:
  feature: "Grafana dashboard embedding"
  usage: "View service monitoring dashboards within Backstage"

Golden Path Core Principles:

1. Suggestion, not Mandate
   ├── Not forced, but easiest when followed
   ├── Can deviate, but lose platform team support
   └── "You can take the dirt road, but the paved one is faster"

2. Production-ready from Day 1
   ├── CI/CD pipeline included by default
   ├── Monitoring/logging/alerting pre-configured
   ├── Security scanning automated
   └── Health check endpoints

3. Continuously Evolving
   ├── Developer feedback incorporated
   ├── New technologies/tools integrated
   └── Regular updates

# Golden Path: From scaffolding to production deployment
golden_path_microservice:
  step_1_scaffolding:
    tool: "Backstage Software Template"
    result:
      - "GitHub repository created"
      - "Project structure (src, tests, k8s, docs)"
      - "Dockerfile, docker-compose.yml"
      - "CI/CD pipeline (.github/workflows)"
      - "catalog-info.yaml (Backstage registration)"
      - "mkdocs.yml (TechDocs)"

  step_2_development:
    tool: "Standard development environment"
    result:
      - "devcontainer configuration"
      - "pre-commit hooks (lint, format, security)"
      - "Integration test framework"
      - "Local dev environment (docker-compose)"

  step_3_ci_cd:
    tool: "GitHub Actions + ArgoCD"
    result:
      - "On PR: build, test, security scan, code review"
      - "On merge: Docker image build, registry push"
      - "ArgoCD auto-sync (dev -> staging -> prod)"
      - "Canary or Blue-Green deployment"

  step_4_observability:
    tool: "OpenTelemetry + Grafana Stack"
    result:
      - "Metrics: Prometheus + Grafana"
      - "Logs: Loki + Grafana"
      - "Tracing: Tempo + Grafana"
      - "Alerts: Grafana Alerting -> Slack/PagerDuty"

  step_5_security:
    tool: "Automated security guardrails"
    result:
      - "SAST: SonarQube"
      - "DAST: OWASP ZAP"
      - "SCA: Dependabot, Snyk"
      - "Image scanning: Trivy"
      - "Policy-as-Code: OPA/Kyverno"

# .github/workflows/golden-path-ci.yml
name: Golden Path CI

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: "${{ github.repository }}"

jobs:
  lint-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Java
        uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '21'
          cache: 'gradle'
      
      - name: Lint
        run: ./gradlew spotlessCheck
      
      - name: Unit Tests
        run: ./gradlew test
      
      - name: Integration Tests
        run: ./gradlew integrationTest

  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: SonarQube Scan
        uses: SonarSource/sonarqube-scan-action@v2
        env:
          SONAR_TOKEN: "${{ secrets.SONAR_TOKEN }}"
      
      - name: Dependency Check
        uses: dependency-check/Dependency-Check_Action@main
        with:
          project: "${{ github.repository }}"
          path: '.'
          format: 'HTML'

  build-and-push:
    needs: [lint-and-test, security-scan]
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      
      - name: Log in to Container Registry
        uses: docker/login-action@v3
        with:
          registry: "${{ env.REGISTRY }}"
          username: "${{ github.actor }}"
          password: "${{ secrets.GITHUB_TOKEN }}"
      
      - name: Build and Push
        uses: docker/build-push-action@v5
        with:
          push: true
          tags: |
            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}
            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
      
      - name: Scan Image
        uses: aquasecurity/trivy-action@master
        with:
          image-ref: "${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}"
          format: 'table'
          exit-code: '1'
          severity: 'CRITICAL,HIGH'

# Crossplane Composition: RDS PostgreSQL
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
  name: postgresql-aws
  labels:
    provider: aws
    database: postgresql
spec:
  compositeTypeRef:
    apiVersion: database.platform.io/v1alpha1
    kind: PostgreSQLInstance
  resources:
    - name: rds-instance
      base:
        apiVersion: rds.aws.crossplane.io/v1alpha1
        kind: DBInstance
        spec:
          forProvider:
            engine: postgres
            engineVersion: "15"
            dbInstanceClass: db.t3.medium
            allocatedStorage: 20
            masterUsername: admin
            skipFinalSnapshot: true
            publiclyAccessible: false
          providerConfigRef:
            name: aws-provider
      patches:
        - fromFieldPath: "spec.parameters.storageGB"
          toFieldPath: "spec.forProvider.allocatedStorage"
        - fromFieldPath: "spec.parameters.instanceClass"
          toFieldPath: "spec.forProvider.dbInstanceClass"
---
# What developers request (Claim)
apiVersion: database.platform.io/v1alpha1
kind: PostgreSQLInstance
metadata:
  name: user-db
  namespace: backend
spec:
  parameters:
    storageGB: 50
    instanceClass: db.t3.medium
  compositionSelector:
    matchLabels:
      provider: aws
      database: postgresql

# modules/microservice-infra/main.tf
# Standard microservice infrastructure module

variable "service_name" {
  type        = string
  description = "Microservice name"
}

variable "team" {
  type        = string
  description = "Owning team"
}

variable "environment" {
  type        = string
  description = "Environment (dev, staging, prod)"
}

variable "enable_database" {
  type    = bool
  default = false
}

variable "enable_cache" {
  type    = bool
  default = false
}

# EKS Namespace
resource "kubernetes_namespace" "service" {
  metadata {
    name = var.service_name
    labels = {
      team        = var.team
      environment = var.environment
      managed-by  = "terraform"
    }
  }
}

# PostgreSQL (optional)
module "database" {
  count  = var.enable_database ? 1 : 0
  source = "../rds-postgresql"

  name        = "${var.service_name}-db"
  environment = var.environment
  
  instance_class    = var.environment == "prod" ? "db.r6g.large" : "db.t3.medium"
  allocated_storage = var.environment == "prod" ? 100 : 20
  multi_az          = var.environment == "prod" ? true : false
  
  tags = {
    Service     = var.service_name
    Team        = var.team
    Environment = var.environment
  }
}

# Redis Cache (optional)
module "cache" {
  count  = var.enable_cache ? 1 : 0
  source = "../elasticache-redis"

  name        = "${var.service_name}-cache"
  environment = var.environment
  
  node_type       = var.environment == "prod" ? "cache.r6g.large" : "cache.t3.medium"
  num_cache_nodes = var.environment == "prod" ? 3 : 1
}

# Auto-generated monitoring dashboard
module "monitoring" {
  source = "../grafana-dashboard"

  service_name = var.service_name
  namespace    = kubernetes_namespace.service.metadata[0].name
  
  enable_database_metrics = var.enable_database
  enable_cache_metrics    = var.enable_cache
}

output "namespace" {
  value = kubernetes_namespace.service.metadata[0].name
}

output "database_endpoint" {
  value     = var.enable_database ? module.database[0].endpoint : null
  sensitive = true
}

# DORA Metrics (DevOps Research and Assessment)
dora_metrics:
  deployment_frequency:
    description: "How often you deploy to production"
    elite: "Multiple times per day"
    high: "Once per week to once per day"
    medium: "Once per month to once per week"
    low: "Less than once per month"

  lead_time_for_changes:
    description: "Time from commit to production deployment"
    elite: "Less than 1 hour"
    high: "1 day to 1 week"
    medium: "1 week to 1 month"
    low: "More than 1 month"

  change_failure_rate:
    description: "Percentage of deployments causing failures/rollbacks"
    elite: "0-15%"
    high: "16-30%"
    medium: "16-30%"
    low: "31% or more"

  time_to_restore:
    description: "Time from failure to service restoration"
    elite: "Less than 1 hour"
    high: "Less than 1 day"
    medium: "1 day to 1 week"
    low: "More than 1 week"

# SPACE Framework for Developer Productivity
space_framework:
  S_satisfaction:
    description: "Developer satisfaction and wellbeing"
    measures:
      - "Quarterly developer satisfaction survey (NPS)"
      - "Burnout risk assessment"
      - "Tool/platform satisfaction scores"

  P_performance:
    description: "Performance of code and systems"
    measures:
      - "Code review quality scores"
      - "Service reliability (SLO achievement)"
      - "Customer-impacting incident count"

  A_activity:
    description: "Quantitative measures of development activity"
    measures:
      - "PR count and size"
      - "Deployment frequency"
      - "Code review participation"
    caution: "Do not judge productivity by activity alone"

  C_communication:
    description: "Effectiveness of cross-team collaboration"
    measures:
      - "PR review response time"
      - "Documentation freshness rate"
      - "Cross-team collaboration frequency"

  E_efficiency:
    description: "Efficiency of development processes"
    measures:
      - "Build time"
      - "Test execution time"
      - "Environment provisioning time"
      - "Onboarding time (to first PR)"

# Platform effectiveness measurement
# platform_metrics.py

import statistics


def calculate_platform_metrics(data):
    """Calculate core platform effectiveness metrics"""
    
    metrics = {}
    
    # 1. Service creation time
    creation_times = data.get('service_creation_times', [])
    if creation_times:
        metrics['avg_service_creation_minutes'] = round(
            statistics.mean(creation_times), 1
        )
        metrics['target_service_creation'] = 15  # Target: 15 min
    
    # 2. Onboarding time (to first commit)
    onboarding_hours = data.get('onboarding_hours', [])
    if onboarding_hours:
        metrics['avg_onboarding_hours'] = round(
            statistics.mean(onboarding_hours), 1
        )
        metrics['target_onboarding_hours'] = 4  # Target: 4 hours
    
    # 3. Self-service rate
    total_requests = data.get('total_infra_requests', 0)
    self_service = data.get('self_service_requests', 0)
    if total_requests > 0:
        metrics['self_service_rate'] = round(
            (self_service / total_requests) * 100, 1
        )
        metrics['target_self_service_rate'] = 80  # Target: 80%
    
    # 4. Golden Path adoption rate
    total_svc = data.get('total_services', 0)
    gp_svc = data.get('golden_path_services', 0)
    if total_svc > 0:
        metrics['golden_path_adoption_rate'] = round(
            (gp_svc / total_svc) * 100, 1
        )
    
    # 5. Platform NPS
    nps_scores = data.get('nps_scores', [])
    if nps_scores:
        promoters = len([s for s in nps_scores if s >= 9])
        detractors = len([s for s in nps_scores if s <= 6])
        total = len(nps_scores)
        metrics['platform_nps'] = round(
            ((promoters - detractors) / total) * 100
        )
    
    return metrics

# Platform as a Product principles
principles:
  developer_is_customer:
    description: "Developers are the platform's customers"
    practices:
      - "Regular user interviews"
      - "NPS measurement"
      - "Usability testing"
      - "Feedback loops"

  product_roadmap:
    description: "The platform needs a product roadmap"
    practices:
      - "Quarterly roadmap sharing"
      - "Priority-based feature development"
      - "Published release notes"
      - "Change announcements"

  sla_and_support:
    description: "Internal SLAs and support structure"
    practices:
      - "Platform availability SLA (e.g., 99.9%)"
      - "Response time SLA (e.g., 30 minutes)"
      - "Dedicated support channel (Slack)"
      - "Regular office hours"

  marketing:
    description: "Internal marketing to drive adoption"
    practices:
      - "Showcase sessions"
      - "Use case sharing"
      - "Champion program"
      - "Internal blog/newsletter"

┌──────────────┬──────────────┬──────────────┬──────────────┬──────────────┐
│              │ Backstage    │ Port         │ Humanitec    │ Kratix       │
├──────────────┼──────────────┼──────────────┼──────────────┼──────────────┤
│ Type          │ Open source  │ SaaS/Self    │ SaaS         │ Open source  │
│ Created by    │ Spotify/CNCF │ Port         │ Humanitec    │ Syntasso     │
│ Key strength  │ Extensibility│ Quick setup  │ Score engine │ K8s native   │
│ Plugins       │ 100+         │ Built-in     │ Built-in     │ K8s CRDs     │
│ Self-service  │ Template-based│ Action-based │ Score-based  │ Promise-based│
│ Learning curve│ High         │ Medium       │ Low          │ High         │
│ Customization │ Very high    │ High         │ Medium       │ High         │
│ Community     │ Very active  │ Growing      │ Small        │ Growing      │
│ Ideal size    │ 50+ engineers│ 20+ engineers│ 20+ engineers│ K8s experts  │
└──────────────┴──────────────┴──────────────┴──────────────┴──────────────┘

# ArgoCD Application definition
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: user-service
  namespace: argocd
  labels:
    team: backend
    managed-by: backstage
spec:
  project: default
  source:
    repoURL: "https://github.com/myorg/user-service"
    targetRevision: HEAD
    path: k8s/overlays/production
  destination:
    server: "https://kubernetes.default.svc"
    namespace: user-service
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
    retry:
      limit: 5
      backoff:
        duration: 5s
        factor: 2
        maxDuration: 3m

# ArgoCD ApplicationSet - per-environment auto-deployment
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: user-service-environments
  namespace: argocd
spec:
  generators:
    - list:
        elements:
          - environment: development
            cluster: dev-cluster
            namespace: user-service-dev
          - environment: staging
            cluster: staging-cluster
            namespace: user-service-staging
          - environment: production
            cluster: prod-cluster
            namespace: user-service-prod
  template:
    metadata:
      name: "user-service-{{ environment }}"
    spec:
      project: default
      source:
        repoURL: "https://github.com/myorg/user-service"
        targetRevision: HEAD
        path: "k8s/overlays/{{ environment }}"
      destination:
        server: "https://{{ cluster }}.internal:6443"
        namespace: "{{ namespace }}"
      syncPolicy:
        automated:
          prune: true
          selfHeal: true

# Gatekeeper ConstraintTemplate: Required labels validation
apiVersion: templates.gatekeeper.sh/v1
kind: ConstraintTemplate
metadata:
  name: requiredlabels
spec:
  crd:
    spec:
      names:
        kind: RequiredLabels
      validation:
        openAPIV3Schema:
          type: object
          properties:
            labels:
              type: array
              items:
                type: string
  targets:
    - target: admission.k8s.gatekeeper.sh
      rego: |
        package requiredlabels

        violation[{"msg": msg}] {
          provided := {label | input.review.object.metadata.labels[label]}
          required := {label | label := input.parameters.labels[_]}
          missing := required - provided
          count(missing) > 0
          msg := sprintf("Missing required labels: %v", [missing])
        }
---
apiVersion: constraints.gatekeeper.sh/v1beta1
kind: RequiredLabels
metadata:
  name: require-team-label
spec:
  match:
    kinds:
      - apiGroups: ["apps"]
        kinds: ["Deployment"]
  parameters:
    labels:
      - "team"
      - "environment"
      - "service"

# Kyverno policy: Restrict image registries
apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: restrict-image-registries
spec:
  validationFailureAction: Enforce
  rules:
    - name: validate-image-registry
      match:
        any:
          - resources:
              kinds:
                - Pod
      validate:
        message: "Only images from approved registries are allowed."
        pattern:
          spec:
            containers:
              - image: "ghcr.io/myorg/* | 123456789.dkr.ecr.*.amazonaws.com/*"
---
# Kyverno policy: Require resource limits
apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: require-resource-limits
spec:
  validationFailureAction: Enforce
  rules:
    - name: validate-resources
      match:
        any:
          - resources:
              kinds:
                - Pod
      validate:
        message: "All containers must have CPU/memory requests and limits."
        pattern:
          spec:
            containers:
              - resources:
                  requests:
                    memory: "?*"
                    cpu: "?*"
                  limits:
                    memory: "?*"
                    cpu: "?*"

# IDP adoption strategy by organization size
small_org:  # 20-50 engineers
  phase_1:
    - "Build standard CI/CD pipelines"
    - "Service catalog (simple Wiki or spreadsheet)"
    - "Standardize Terraform modules"
  phase_2:
    - "Adopt Backstage (Software Catalog)"
    - "1-2 Golden Path templates"
    - "Basic self-service (DB, cache)"
  timeline: "3-6 months"

medium_org:  # 50-200 engineers
  phase_1:
    - "Full-stack Backstage deployment"
    - "3-5 Golden Path templates"
    - "Crossplane or Terraform-based self-service"
    - "DORA metrics measurement"
  phase_2:
    - "Security guardrails (OPA/Kyverno)"
    - "Cost visibility integration"
    - "Developer satisfaction surveys"
    - "Plugin ecosystem expansion"
  timeline: "6-12 months"

large_org:  # 200+ engineers
  phase_1:
    - "Dedicated platform team (8-15 people)"
    - "Platform as a Product operating model"
    - "Comprehensive IDP architecture design"
  phase_2:
    - "Multi-cluster/multi-cloud support"
    - "Advanced security and compliance automation"
    - "FinOps integration"
    - "AI/ML platform integration"
  timeline: "12-18 months"