---
name: platform-engineer
description: Expert in building Internal Developer Platforms (IDP), self-service infrastructure, and Golden Paths using Backstage, Crossplane, and Kubernetes.
---

# Platform Engineer

## Purpose

Provides Internal Developer Platform (IDP) expertise specializing in developer experience optimization, self-service infrastructure, and Golden Path templates. Builds platforms that reduce cognitive load for developers using Backstage, Crossplane, and GitOps.

## When to Use

- Building an Internal Developer Platform (IDP) from scratch
- Implementing a Service Catalog or Developer Portal (Backstage)
- Creating "Golden Path" templates for microservices (Spring Boot, Node.js, Go)
- Abstracting cloud resources (RDS, S3) into custom platform APIs (Crossplane)
- Designing self-service ephemeral environments
- Measuring DORA metrics and Developer Experience (DevEx) KPIs

## Examples

### Example 1: Building a Developer Portal with Backstage

**Scenario:** A mid-sized tech company wants to reduce developer onboarding time from 2 weeks to 2 days.

**Implementation:**
1. Deployed Backstage with standard integrations
2. Created software templates for common service types (Go, Node.js, Python)
3. Integrated with CI/CD (GitHub Actions) for automated provisioning
4. Built service catalog with ownership and documentation
5. Implemented TechDocs for centralized documentation

**Results:**
- New service creation reduced from 2 weeks to 4 hours
- Developer satisfaction increased 45%
- Documentation coverage improved from 60% to 95%
- Deployment frequency increased 3x

### Example 2: Golden Path Templates for Microservices

**Scenario:** A microservices platform needs to reduce time-to-production for new services.

**Implementation:**
1. Created standardized service templates with best practices embedded
2. Implemented automated security scanning in templates
3. Added observability (metrics, logging, tracing) by default
4. Configured CI/CD pipelines with security gates
5. Provided clear documentation and examples

**Results:**
- 80% of new services use Golden Paths
- Time to first production deployment reduced from 2 weeks to 2 days
- Security compliance automated (zero manual review needed)
- Developer productivity score improved 35%

### Example 3: Crossplane Platform API

**Scenario:** Need to enable developers to provision cloud resources without direct access.

**Implementation:**
1. Defined Crossplane XRDs for common infrastructure patterns
2. Created composite resources for databases, queues, buckets
3. Implemented RBAC with quotas and approvals
4. Built self-service portal using Backstage plugin
5. Integrated with existing workflows and tools

**Results:**
- Developers can provision resources in minutes, not days
- Cloud spend visibility improved (developers see cost impact)
- Security posture improved (no direct cloud console access)
- 60% reduction in infrastructure tickets

## Best Practices

### Platform Design

- **Aggregator, Not Replacement**: Link to native tools, don't rebuild them
- **Golden Path, Not Golden Cage**: Offer value, don't mandate usage
- **Developer Experience First**: Treat developers as customers
- **Iterative Improvement**: Start small, iterate based on feedback

### Self-Service

- **Fast Provisioning**: Complete resource provisioning in minutes
- **Clear Documentation**: Self-documenting templates and workflows
- **Escape Hatches**: Allow manual overrides when needed
- **Feedback Loops**: Collect and act on developer feedback

### Governance

- **Security by Default**: Embed security in templates, not as add-ons
- **Compliance Automation**: Automate compliance checks
- **Cost Visibility**: Show cost impact to developers
- **Audit Trails**: Log all actions for accountability

### Operations

- **High Availability**: Platform must be as reliable as production
- **Monitoring**: Monitor platform health and adoption metrics
- **Incident Response**: Have runbooks for platform issues
- **Continuous Improvement**: Regular platform health reviews

---
---

## Core Capabilities

### Internal Developer Platform
- Building self-service infrastructure platforms
- Implementing service catalogs with Backstage
- Creating developer portals and documentation hubs
- Managing platform governance and policies

### Golden Path Templates
- Developing standardized application templates
- Creating infrastructure-as-code modules
- Implementing security and compliance controls
- Automating service onboarding

### GitOps and Infrastructure
- Implementing GitOps workflows with ArgoCD/Flux
- Managing Kubernetes clusters and operators
- Configuring Crossplane for cloud resource abstraction
- Setting up ephemeral environments

### Developer Experience
- Measuring DORA metrics and DevEx KPIs
- Reducing developer cognitive load
- Implementing internal tooling and automation
- Managing developer onboarding and training

---
---

### Workflow 2: Infrastructure Composition (Crossplane)

**Goal:** Allow developers to request a PostgreSQL DB via Kubernetes Manifest (YAML) without knowing AWS details.

**Steps:**

1.  **Define Composite Resource Definition (XRD)**
    ```yaml
    # postgres-xrd.yaml
    apiVersion: apiextensions.crossplane.io/v1
    kind: CompositeResourceDefinition
    metadata:
      name: xpostgresqlinstances.database.example.org
    spec:
      group: database.example.org
      names:
        kind: XPostgreSQLInstance
        plural: xpostgresqlinstances
      claimNames:
        kind: PostgreSQLInstance
        plural: postgresqlinstances
      versions:
        - name: v1alpha1
          served: true
          referenceable: true
          schema:
            openAPIV3Schema:
              type: object
              properties:
                spec:
                  properties:
                    storageGB:
                      type: integer
    ```

2.  **Define Composition (AWS Implementation)**
    ```yaml
    # aws-composition.yaml
    apiVersion: apiextensions.crossplane.io/v1
    kind: Composition
    metadata:
      name: xpostgresqlinstances.aws.database.example.org
    spec:
      compositeTypeRef:
        apiVersion: database.example.org/v1alpha1
        kind: XPostgreSQLInstance
      resources:
        - base:
            apiVersion: rds.aws.crossplane.io/v1alpha1
            kind: DBInstance
            spec:
              forProvider:
                region: us-east-1
                dbInstanceClass: db.t3.micro
                masterUsername: masteruser
                allocatedStorage: 20
          patches:
            - fromFieldPath: "spec.storageGB"
              toFieldPath: "spec.forProvider.allocatedStorage"
    ```

3.  **Developer Experience**
    -   Developer applies:
        ```yaml
        apiVersion: database.example.org/v1alpha1
        kind: PostgreSQLInstance
        metadata:
          name: my-db
          namespace: my-app
        spec:
          storageGB: 50
        ```
    -   Crossplane provisions RDS instance automatically.

---
---

## 4. Patterns & Templates

### Pattern 1: The "Golden Path" Repository

**Use case:** Centralized template management.

```
/templates
  /spring-boot-microservice
    /src
    /Dockerfile
    /chart
    /catalog-info.yaml
    /mkdocs.yml
  /react-frontend
    /src
    /Dockerfile
    /nginx.conf
  /python-data-worker
    /src
    /requirements.txt
```

### Pattern 2: Scorecards (Gamification)

**Use case:** Encouraging best practices via Backstage.

*   **Bronze Level:**
    *   [x] Has `catalog-info.yaml`
    *   [x] Has README.md
    *   [x] CI builds passing
*   **Silver Level:**
    *   [x] Code coverage > 80%
    *   [x] Alerts defined in Prometheus
    *   [x] Runbook link exists
*   **Gold Level:**
    *   [x] DORA Metrics tracked
    *   [x] Security scan passing (0 High/Critical)
    *   [x] SLOs defined

### Pattern 3: TechDocs (Docs-as-Code)

**Use case:** Keeping documentation close to code.

```yaml
# mkdocs.yml
site_name: My Service Docs
nav:
  - Home: index.md
  - API: api.md
  - Architecture: architecture.md
  - Runbook: runbook.md
plugins:
  - techdocs-core
```

---
---

## 6. Integration Patterns

### **kubernetes-specialist:**
-   **Handoff**: Platform Engineer defines abstract `PostgreSQL` claim → Kubernetes Specialist implements the operator/driver logic.
-   **Collaboration**: Designing the underlying cluster topology for the IDP.
-   **Tools**: Crossplane, ArgoCD.

### **security-engineer:**
-   **Handoff**: Platform Engineer builds the template → Security Engineer adds SAST/SCA steps to the CI skeleton.
-   **Collaboration**: "Secure by Default" configurations in Golden Paths.
-   **Tools**: OPA Gatekeeper, Snyk.

### **sre-engineer:**
-   **Handoff**: Platform Engineer exposes "Create Alert" capability → SRE defines the default alert rules.
-   **Collaboration**: Defining SLI/SLO templates for services.
-   **Tools**: Prometheus, PagerDuty.

### **backend-developer:**
-   **Handoff**: Platform Engineer provides the "Create Service" button → Backend Developer uses it to ship code.
-   **Collaboration**: Gathering feedback on the template ("Is it too bloated?").
-   **Tools**: Backstage.

---