Platform Engineering: Building Internal Developer Platforms

# assessment.yaml
infrastructure:
  cloud_providers:
    - name: AWS
      services_used:
        - EKS
        - RDS
        - S3
        - Lambda
      monthly_cost: "$45,000"
  
  kubernetes:
    clusters: 5
    namespaces: 50
    workloads: 200

developer_survey:
  pain_points:
    - "Slow provisioning (2-3 days)"
    - "No clear deployment path"
    - "Inconsistent security configs"
    - "Hard to find documentation"
  
  requests:
    - "Self-service database provisioning"
    - "One-click deploy to staging"
    - "Unified authentication"
    - "Service catalog"

# golden-paths/application-template.yaml
apiVersion: platform.example.com/v1
kind: Application
metadata:
  name: my-service
  namespace: default
spec:
  language: go
  framework: gin
  
  infrastructure:
    database:
      type: postgresql
      version: "15"
      tier: small
    
    cache:
      type: redis
      tier: small
    
    queue:
      type: rabbitmq
  
  deployment:
    replicas: 2
    resources:
      cpu: "500m"
      memory: "512Mi"
    autoscaling:
      enabled: true
      min_replicas: 2
      max_replicas: 10
  
  observability:
    logging: true
    metrics: true
    tracing: true
    alert_channels:
      - slack
      - pagerduty

# app-config.yaml
app:
  title: My Company Developer Portal
  baseUrl: https://developer.internal.example.com

organization:
  name: My Company

backend:
  baseUrl: https://developer.internal.example.com
  cors:
    origin: https://developer.internal.example.com
  
database:
  client: better-sqlite3
  connection: ":memory:"

catalog:
  locations:
    - type: url
      target: https://github.com/org/backstage-catalog-info/blob/main/catalog.yaml
    
    - type: directory
      target: ./catalog

proxy:
  '/labrador':
    target: https://labrador.example.com
    changeOrigin: true

integrations:
  github:
    - token: ${GITHUB_TOKEN}
      apiBaseUrl: https://api.github.com
      
  jenkins:
    - baseUrl: https://jenkins.internal.example.com
      username: ${JENKINS_USER}
      token: ${JENKINS_TOKEN}

# catalog-info.yaml (in each service repo)
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment-service
  description: Payment processing service
  tags:
    - go
    - microservices
    - payments
  links:
    - title: Documentation
      url: https://docs.internal.example.com/payment-service
    - title: API Docs
      url: https://api.internal.example.com/payment-service/swagger
    - title: Grafana
      url: https://grafana.internal.example.com/d/payment-service

spec:
  type: service
  lifecycle: production
  owner: platform-team
  system: payments
  
  providesApis:
    - payment-api
  
  consumesApis:
    - user-api
    - notification-api

  dependsOn:
    - resource:payment-db
    - resource:payment-redis

---
apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
  name: payment-db
spec:
  type: database
  owner: platform-team
  system: payments

// environment-provisioner.ts
import { KubernetesClient } from './kubernetes';
import { DatabaseClient } from './database';

interface EnvironmentRequest {
  name: string;
  namespace: string;
  services: string[];
  databases: DatabaseConfig[];
  resources: ResourceSpec;
}

class EnvironmentProvisioner {
  async provisionEnvironment(request: EnvironmentRequest): Promise<Environment> {
    // 1. Create Kubernetes namespace
    await this.k8s.createNamespace(request.namespace);
    
    // 2. Deploy base services
    for (const service of request.services) {
      await this.k8s.deployService({
        name: service,
        namespace: request.namespace,
        image: `registry.internal/${service}:latest`,
        replicas: request.resources.replicas,
      });
    }
    
    // 3. Provision databases
    for (const db of request.databases) {
      await this.db.provision({
        ...db,
        namespace: request.namespace,
      });
    }
    
    // 4. Configure networking
    await this.k8s.createIngress({
      name: `${request.namespace}-ingress`,
      namespace: request.namespace,
      services: request.services,
    });
    
    // 5. Set up monitoring
    await this.monitoring.configure({
      namespace: request.namespace,
      services: request.services,
    });
    
    return new Environment(request.name, request.namespace);
  }
}

# Developer uses platform CLI
platform create service payment-service \
  --language go \
  --framework gin \
  --db postgresql \
  --add-ci \
  --add-cd

# This creates:
# - GitHub repository with template
# - CI/CD pipeline
# - Kubernetes manifests
# - Database credentials (sealed secrets)
# - Monitoring configuration
# - Documentation template

# Prioritization matrix
pain_points:
  high_impact:
    - "Environment provisioning (2+ days)"
    - "Database access"
    - "Certificate management"
  
  medium_impact:
    - "Finding documentation"
    - "Service discovery"
    - "Logs access"
  
  low_impact:
    - "Custom domain setup"
    - "Analytics configuration"

# ✅ Good: Opinionated but flexible
paths:
  standard:
    language: [go, python, typescript]
    deployment: [kubernetes, cloudrun]
    database: [postgresql, redis]
    # Developers choose from options
  
  # ❌ Bad: Too many choices
  # Let developers choose anything = chaos

metrics:
  developer:
    - time_to_first_deployment
    - deployment_frequency
    - onboarding_time
    - dx_satisfaction_score
  
  platform:
    - platform_availability
    - provisioning_success_rate
    - mean_time_to_recovery
    - automated_vs_manual_actions
  
  business:
    - feature_delivery_time
    - engineering_velocity
    - production_incidents

// Feedback collection
app.post('/api/feedback', async (req, res) => {
  const feedback = {
    user: req.user.id,
    rating: req.body.rating,
    category: req.body.category,
    comment: req.body.comment,
    timestamp: new Date(),
    context: {
      page: req.body.page,
      action: req.body.action,
    }
  };
  
  await feedbackStore.save(feedback);
  
  // Trigger alerts for critical issues
  if (feedback.rating <= 2) {
    await alertChannel.send({
      message: `Low DX feedback: ${feedback.category}`,
      priority: 'high',
    });
  }
});

# Built what we thought they needed
platform:
  features:
    - complex_workflows
    - many_approval_steps
    - custom_tooling
# Result: Nobody uses it

# Built what they actually needed
platform:
  features:
    - simple_deploy_button
    - automatic_docs
    - instant_feedback
# Result: High adoption

// Custom platform from scratch
class CustomPlatform {
  async doEverything(): Promise<any> {
    // 10,000 lines of custom code
  }
}

// Compose existing tools
const platform = new PlatformBuilder()
  .use(Backstage)
  .use(ArgoCD)
  .use(Tekton)
  .use(OPA)
  .build();

# Self-service only, no help
platform:
  docs_only: true
  support_channel: none

# Self-service + support
platform:
  docs: true
  slack_channel: "#platform-support"
  office_hours: "Thursdays 2pm"
  dedicated_sre: 1