Advanced Internal Platform

A comprehensive skill for building and managing internal developer platforms — covering self-service tooling, CI/CD orchestration, developer experience portals, infrastructure abstraction layers, and platform engineering best practices.

When to Use This Skill

Choose Advanced Internal Platform when you need to:

• Design an Internal Developer Platform (IDP) for your organization
• Build self-service infrastructure provisioning workflows
• Create developer portals with service catalogs and documentation
• Abstract infrastructure complexity behind simple interfaces
• Standardize deployment pipelines across multiple teams

Consider alternatives when:

• You need cloud infrastructure setup (use a cloud/DevOps skill)
• You need CI/CD pipeline configuration (use a CI/CD skill)
• You need Kubernetes cluster management (use a K8s skill)

Quick Start

Copy
# Generate a platform service catalog entry
claude "Create an internal platform service catalog entry for a PostgreSQL database provisioning service, including self-service form fields, provisioning workflow, and SLA."

Copy
# service-catalog/postgresql.yaml
apiVersion: platform/v1
kind: ServiceOffering
metadata:
  name: postgresql-database
  category: data-stores
  tier: gold
spec:
  displayName: "PostgreSQL Database"
  description: "Managed PostgreSQL instance with automated backups"
  owner: platform-team
  sla:
    provisioning: "< 10 minutes"
    availability: "99.95%"
    backup_rpo: "1 hour"
    backup_rto: "4 hours"

  parameters:
    - name: instance_size
      type: select
      required: true
      options:
        - { value: "small", label: "Small (2 vCPU, 4GB)", cost: "$50/mo" }
        - { value: "medium", label: "Medium (4 vCPU, 8GB)", cost: "$120/mo" }
        - { value: "large", label: "Large (8 vCPU, 16GB)", cost: "$280/mo" }
    - name: environment
      type: select
      required: true
      options: ["dev", "staging", "production"]
    - name: database_name
      type: text
      required: true
      validation: "^[a-z][a-z0-9_]{2,30}$"
    - name: enable_read_replica
      type: boolean
      default: false
      production_only: true

  provisioning:
    workflow: terraform-apply
    template: modules/postgresql
    approval_required:
      production: true
      dev: false

Core Concepts

Platform Architecture Layers

Layer	Purpose	Tools/Examples
Developer Portal	Service catalog, docs, self-service	Backstage, Port, Cortex
Workflow Engine	Orchestrate provisioning requests	Argo Workflows, Temporal
Infrastructure	Provision and manage resources	Terraform, Pulumi, Crossplane
Observability	Monitoring, logging, tracing	Grafana, Datadog, Jaeger
Security	Auth, secrets, policy enforcement	Vault, OPA, Falco

Self-Service Provisioning Flow

Copy
## Request → Approve → Provision → Deliver

### 1. Developer submits request
   - Selects service from catalog
   - Fills parameters (size, env, name)
   - Reviews cost estimate

### 2. Automated validation
   - Parameter validation (naming, sizing)
   - Budget check against team allocation
   - Security policy compliance (OPA)

### 3. Approval (if required)
   - Auto-approved for dev/staging
   - Manager approval for production
   - Security review for sensitive services

### 4. Provisioning
   - Terraform/Pulumi applies configuration
   - DNS records created
   - Credentials stored in Vault
   - Monitoring dashboards generated

### 5. Delivery
   - Developer receives connection details
   - Service appears in team's service map
   - Documentation link provided

Golden Path Templates

Copy
# golden-paths/web-service.yaml
apiVersion: platform/v1
kind: GoldenPath
metadata:
  name: web-service
  description: "Production-ready web service scaffold"
spec:
  scaffolds:
    - repo structure (src/, tests/, docs/)
    - Dockerfile with multi-stage build
    - CI/CD pipeline (build, test, deploy)
    - Kubernetes manifests (deploy, service, ingress)
    - Monitoring (Prometheus metrics, Grafana dashboard)
    - Alerting rules (latency, error rate, saturation)

  includes:
    - health check endpoint (/healthz)
    - readiness probe endpoint (/readyz)
    - structured logging (JSON format)
    - distributed tracing headers
    - graceful shutdown handling

  guardrails:
    - container runs as non-root
    - resource limits set
    - network policies applied
    - secrets from Vault (not env vars)

Configuration

Parameter	Description	Example
platform_name	Internal platform name	"DevHub"
catalog_backend	Service catalog tool	"backstage" / "custom"
iac_tool	Infrastructure as code tool	"terraform" / "pulumi"
approval_engine	Workflow approval system	"slack" / "jira"
secret_manager	Secrets management tool	"vault" / "aws-sm"
output_format	Template output format	"yaml" / "json"

Best Practices

1. Start with the developer's workflow, not the infrastructure — Map how developers currently go from "I need a database" to "I have a working database." Identify every manual step, approval bottleneck, and context-switch. Automate the painful steps first, then expand.

2. Offer golden paths but don't mandate them — Golden paths should make the right thing the easy thing, not the only thing. Teams with legitimate reasons to deviate should be able to, with clear documentation of what they're taking responsibility for.

3. Measure platform adoption with developer surveys, not usage metrics — High usage might mean developers have no choice. Low usage might mean the platform doesn't solve their problems. Regular developer experience surveys reveal whether the platform is genuinely helpful.

4. Build for self-service from day one — If provisioning requires a Slack message to the platform team, you've built a ticketing system, not a platform. Even v1 should let developers click a button and get a working resource without human intervention.

5. Treat the platform as a product with its own roadmap — Internal platforms fail when treated as side projects. Assign a dedicated team, track feature requests, run retrospectives with users, and publish a roadmap. Your developers are your customers.

Common Issues

Platform team becomes a bottleneck instead of an enabler — If every request still requires platform team involvement, you've centralized the bottleneck rather than eliminating it. Audit how many requests can complete without human intervention and target 90%+ self-service completion for standard operations.

Golden paths are outdated and developers bypass them — Templates that were created once and never updated lose developer trust quickly. Set up automated testing for golden path templates, pin dependency versions with a quarterly update cadence, and measure how many new services use the template vs. start from scratch.

Cost visibility is missing until the monthly bill arrives — Developers provision resources without understanding cost implications because the platform doesn't surface pricing. Show estimated monthly costs during the provisioning flow, send weekly cost summaries per team, and flag resources running in dev/staging environments over the weekend.