Platform Lifecycle — IDP Module Specification

Golden Path: Web Service (AKS Deployment) Required

# golden-paths/web-service/main.tf
module "web_service" {
  source  = "app.terraform.io/acme/web-service/azurerm"
  version = "~> 2.0"

  service_name    = var.service_name
  team            = var.team
  container_image = var.container_image
  environment     = var.environment  # dev | staging | production

  # AKS cluster reference
  aks_cluster_name    = var.aks_cluster_name
  aks_resource_group  = var.aks_resource_group

  # Optional overrides
  replicas        = var.replicas        # default: based on environment
  cpu_request     = var.cpu_request     # default: "250m"
  memory_request  = var.memory_request  # default: "256Mi"
  custom_domain   = var.custom_domain
}

variable "service_name" {
  description = "Name of the service"
  type        = string
}
variable "team" {
  description = "Owning team"
  type        = string
}
variable "container_image" {
  description = "Container image URI"
  type        = string
}
variable "environment" {
  description = "Target environment"
  type        = string
  validation {
    condition     = contains(["dev", "staging", "production"], var.environment)
    error_message = "Must be dev, staging, or production."
  }
}
variable "aks_cluster_name" {
  description = "AKS cluster name"
  type        = string
}
variable "aks_resource_group" {
  description = "Resource group containing AKS cluster"
  type        = string
}
variable "replicas" {
  description = "Number of replicas (overrides env default)"
  type        = number
  default     = null
}
variable "cpu_request" {
  description = "CPU request per pod"
  type        = string
  default     = null
}
variable "memory_request" {
  description = "Memory request per pod"
  type        = string
  default     = null
}
variable "custom_domain" {
  description = "Custom domain for ingress"
  type        = string
  default     = null
}

Environment Defaults

# Generated: deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ service_name }}
  namespace: {{ team }}
  labels:
    app.kubernetes.io/name: {{ service_name }}
    app.kubernetes.io/managed-by: terraform
    acme.com/team: {{ team }}
    acme.com/golden-path: web-service-v2
spec:
  replicas: {{ replicas }}
  selector:
    matchLabels:
      app.kubernetes.io/name: {{ service_name }}
  template:
    metadata:
      labels:
        app.kubernetes.io/name: {{ service_name }}
    spec:
      containers:
        - name: {{ service_name }}
          image: {{ container_image }}
          resources:
            requests:
              cpu: {{ cpu_request }}
              memory: {{ memory_request }}
            limits:
              cpu: {{ cpu_limit }}
              memory: {{ memory_limit }}
          ports:
            - containerPort: 8080
          livenessProbe:
            httpGet:
              path: /health
              port: 8080
            initialDelaySeconds: 15
          readinessProbe:
            httpGet:
              path: /ready
              port: 8080

Golden Path: Data Store (PostgreSQL Flexible Server) Required

module "database" {
  source  = "app.terraform.io/acme/postgresql-flexible/azurerm"
  version = "~> 1.0"

  db_name         = var.db_name
  team            = var.team
  environment     = var.environment
  size            = var.size  # small | medium | large

  resource_group_name = var.resource_group_name
  vnet_id            = var.vnet_id
  subnet_id          = var.delegated_subnet_id

  # Defaults enforced by golden path:
  # - ssl_enforcement_enabled = true
  # - geo_redundant_backup = (production only)
  # - threat_detection_policy = enabled
  # - azure_ad_authentication = enabled
  # - private_dns_zone = auto-configured
}

Size Mapping

Golden Path: Azure Storage Account Recommended

Data Lake or static asset storage with encryption, private endpoint, and lifecycle management enforced by default.

module "storage" {
  source  = "app.terraform.io/acme/storage-account/azurerm"
  version = "~> 1.0"

  storage_name        = var.storage_name
  team                = var.team
  environment         = var.environment
  resource_group_name = var.resource_group_name
  location            = var.location

  # Enforced defaults:
  # - account_tier            = "Standard"
  # - account_replication     = env == "production" ? "GRS" : "LRS"
  # - min_tls_version         = "TLS1_2"
  # - enable_https_only       = true
  # - public_network_access   = false
  # - private_endpoint        = auto-configured
  # - lifecycle_management    = 90-day archive, 365-day delete
  # - blob_versioning         = true
}

Scaffolding Template (Backstage Software Template)

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: aks-web-service
  title: AKS Web Service
  description: Deploy a web service to AKS using the golden path
  tags: ['aks', 'web-service', 'golden-path', 'azure']
spec:
  owner: platform-engineering
  type: service
  parameters:
    - title: Service Details
      required: [service_name, team]
      properties:
        service_name:
          title: Service Name
          type: string
          pattern: '^[a-z][a-z0-9-]{2,28}[a-z0-9]$'
        team:
          title: Team
          type: string
          enum: [payments, catalog, orders, identity]
        environment:
          title: Initial Environment
          type: string
          enum: [dev, staging]
          default: dev
  steps:
    - id: terraform-init
      name: Initialize Terraform
      action: terraform:init
    - id: terraform-apply
      name: Apply Infrastructure
      action: terraform:apply
    - id: register-catalog
      name: Register in Software Catalog
      action: catalog:register

Glossary

Demo: Self-Service Infrastructure Provisioning

This demo screen shows the developer experience for provisioning infrastructure through the IDP portal.

Wireframe Description

Mock Data

{
  "golden_paths": [
    {
      "id": "aks-web-service",
      "name": "AKS Web Service",
      "version": "2.1.0",
      "description": "Deploy a containerized web service to AKS",
      "adoption_pct": 87,
      "last_updated": "2024-01-10",
      "tags": ["aks", "web", "production-ready"]
    },
    {
      "id": "postgresql-flexible",
      "name": "PostgreSQL Flexible Server",
      "version": "1.3.0",
      "description": "Managed PostgreSQL with VNet integration",
      "adoption_pct": 92,
      "last_updated": "2024-01-08",
      "tags": ["database", "postgresql", "managed"]
    },
    {
      "id": "storage-datalake",
      "name": "Storage Account (Data Lake)",
      "version": "1.1.0",
      "description": "ADLS Gen2 with private endpoint and lifecycle",
      "adoption_pct": 78,
      "last_updated": "2024-01-05",
      "tags": ["storage", "data-lake", "analytics"]
    }
  ]
}

Environment Definition (Dev)

# environments/dev/main.tf
module "dev_environment" {
  source = "../../modules/environment"

  environment     = "dev"
  location        = "eastus2"
  subscription_id = var.dev_subscription_id

  vnet_config = {
    address_space   = ["10.0.0.0/16"]
    aks_subnet      = "10.0.1.0/24"
    db_subnet       = "10.0.2.0/24"
    services_subnet = "10.0.3.0/24"
  }

  aks_config = {
    kubernetes_version  = "1.29"
    node_pool_vm_size   = "Standard_D2s_v5"
    node_count          = 2
    max_count           = 4
    availability_zones  = []  # No AZ requirement for dev
  }

  monitoring = {
    log_analytics_retention_days = 30
    alert_action_group          = null  # No paging in dev
    grafana_enabled             = false
  }

  cost_management = {
    budget_amount    = 500
    budget_currency  = "USD"
    alert_thresholds = [80, 100]
  }

  tags = {
    Environment = "dev"
    CostCenter  = "engineering"
    ManagedBy   = "terraform"
  }
}

Environment Definition (Production)

# environments/production/main.tf
module "prod_environment" {
  source = "../../modules/environment"

  environment     = "production"
  location        = "eastus2"
  subscription_id = var.prod_subscription_id

  vnet_config = {
    address_space   = ["10.2.0.0/16"]
    aks_subnet      = "10.2.1.0/24"
    db_subnet       = "10.2.2.0/24"
    services_subnet = "10.2.3.0/24"
  }

  aks_config = {
    kubernetes_version  = "1.29"
    node_pool_vm_size   = "Standard_D4s_v5"
    node_count          = 3
    max_count           = 20
    availability_zones  = ["1", "2", "3"]
  }

  monitoring = {
    log_analytics_retention_days = 90
    alert_action_group          = "pagerduty-critical"
    grafana_enabled             = true
  }

  cost_management = {
    budget_amount    = 8000
    budget_currency  = "USD"
    alert_thresholds = [70, 85, 100]
  }

  tags = {
    Environment = "production"
    CostCenter  = "engineering"
    ManagedBy   = "terraform"
    Compliance  = "soc2"
  }
}

Azure Deployment Environment Definition

# environment-definitions/dev-aks/environment.yaml
name: dev-aks-environment
version: 1.0.0
summary: Development AKS environment with supporting services
description: |
  Provisions an AKS cluster with Azure Database for PostgreSQL,
  Key Vault, and Container Registry for development workloads.
runner: Terraform
templatePath: ./main.tf

parameters:
  - id: serviceName
    name: Service Name
    description: Name of the service to deploy
    type: string
    required: true
  - id: teamName
    name: Team
    description: Owning team
    type: string
    required: true
  - id: nodeCount
    name: Node Count
    description: Number of AKS nodes
    type: int
    default: 2

Key Vault + App Configuration

# modules/config-management/main.tf
resource "azurerm_key_vault" "service" {
  name                = "kv-${var.environment}-${var.service_name}"
  location            = var.location
  resource_group_name = var.resource_group_name
  tenant_id           = data.azurerm_client_config.current.tenant_id
  sku_name            = "standard"

  purge_protection_enabled   = var.environment == "production"
  soft_delete_retention_days = var.environment == "production" ? 90 : 7

  network_acls {
    default_action = "Deny"
    bypass         = "AzureServices"
    ip_rules       = var.allowed_ips
    virtual_network_subnet_ids = [var.aks_subnet_id]
  }
}

resource "azurerm_app_configuration" "service" {
  name                = "appconf-${var.environment}-${var.service_name}"
  location            = var.location
  resource_group_name = var.resource_group_name
  sku                 = "standard"

  identity {
    type = "SystemAssigned"
  }
}

Glossary

Demo: Environment Dashboard & Provisioning

Mock Data

{
  "services": [
    {
      "name": "payment-api",
      "team": "payments",
      "environments": {
        "dev":        { "version": "3.2.1", "health": "healthy", "last_deployed": "2024-01-14T10:30:00Z", "policy_compliant": true },
        "staging":    { "version": "3.2.0", "health": "healthy", "last_deployed": "2024-01-13T14:00:00Z", "policy_compliant": true },
        "production": { "version": "3.1.8", "health": "healthy", "last_deployed": "2024-01-10T09:00:00Z", "policy_compliant": true }
      }
    },
    {
      "name": "catalog-service",
      "team": "catalog",
      "environments": {
        "dev":        { "version": "2.5.0", "health": "healthy", "last_deployed": "2024-01-14T11:00:00Z", "policy_compliant": true },
        "staging":    { "version": "2.4.3", "health": "degraded", "last_deployed": "2024-01-12T16:00:00Z", "policy_compliant": false },
        "production": { "version": "2.4.2", "health": "healthy", "last_deployed": "2024-01-08T08:00:00Z", "policy_compliant": true }
      }
    }
  ],
  "ephemeral_environments": [
    { "name": "pr-1234-payment-api", "owner": "jsmith", "ttl_hours": 48, "remaining_hours": 22 },
    { "name": "pr-1267-catalog-svc", "owner": "adoe", "ttl_hours": 72, "remaining_hours": 65 }
  ]
}

Platform Version Manifest

# platform-manifest.yaml
apiVersion: platform.acme.com/v1
kind: PlatformManifest
metadata:
  version: "2024.Q1"
  effective_date: "2024-01-15"

components:
  terraform:
    version: "1.7.x"
    provider_azurerm: "~> 3.90"
    state_backend: "azurerm"

  aks:
    kubernetes_version: "1.29"
    node_image_channel: "NodeImage"
    upgrade_channel:
      dev: "rapid"
      staging: "stable"
      production: "none"

  databases:
    postgresql_flexible:
      versions: ["15", "16"]
    cosmos_db:
      api: ["SQL", "MongoDB"]

  monitoring:
    grafana_version: "10.x"
    log_analytics_agent: "ama-logs"
    prometheus: "azure-managed"

  security:
    defender_plans: ["Containers", "KeyVaults", "DNS", "Databases"]
    tls_minimum: "1.2"
    azure_policy_set: "acme-baseline-v2"

  container_registry:
    acr_sku: "Premium"
    geo_replication: ["eastus2", "westus2"]
    content_trust: true

AKS Namespace Resource Quota

apiVersion: v1
kind: ResourceQuota
metadata:
  name: team-payment-quota
  namespace: payments
spec:
  hard:
    requests.cpu: "8"
    requests.memory: 16Gi
    limits.cpu: "16"
    limits.memory: 32Gi
    pods: "20"
    services: "10"
    persistentvolumeclaims: "5"
---
apiVersion: v1
kind: LimitRange
metadata:
  name: default-limits
  namespace: payments
spec:
  limits:
    - default:
        cpu: "500m"
        memory: "512Mi"
      defaultRequest:
        cpu: "100m"
        memory: "128Mi"
      type: Container

Azure Budget & Cost Alert

resource "azurerm_consumption_budget_resource_group" "team" {
  name              = "budget-${var.team}-${var.environment}"
  resource_group_id = var.resource_group_id

  amount     = var.monthly_budget
  time_grain = "Monthly"

  time_period {
    start_date = "2024-01-01T00:00:00Z"
  }

  notification {
    enabled        = true
    threshold      = 80
    operator       = "GreaterThan"
    contact_emails = var.team_leads
    contact_groups = [var.action_group_id]
  }

  notification {
    enabled        = true
    threshold      = 100
    operator       = "GreaterThan"
    contact_emails = var.team_leads
    contact_groups = [var.action_group_id, var.finops_action_group_id]
  }
}

Deprecation Notice Template

apiVersion: platform.acme.com/v1
kind: DeprecationNotice
metadata:
  id: "DEP-2024-003"
  severity: warning
spec:
  component: "aks"
  affected_version: "1.27"
  replacement_version: "1.29"
  announcement_date: "2024-01-01"
  sunset_date: "2024-04-01"
  migration_guide: "https://portal.acme.com/guides/aks-1.27-to-1.29"
  affected_teams: ["payments", "catalog", "orders"]
  breaking_changes:
    - "Deprecated PodSecurityPolicy removed"
    - "API version batch/v1beta1 removed"

AKS Upgrade Runbook Template

apiVersion: platform.acme.com/v1
kind: UpgradeRunbook
metadata:
  name: aks-cluster-upgrade
  version: "1.0"
spec:
  pre_checks:
    - name: "Verify PDB coverage"
      command: "kubectl get pdb --all-namespaces"
    - name: "Check deprecated API usage"
      command: "kubectl get --raw /metrics | grep apiserver_requested_deprecated_apis"
    - name: "Validate node pool health"
      command: "az aks nodepool list --cluster-name $CLUSTER --resource-group $RG"
  upgrade_steps:
    - name: "Upgrade control plane"
      command: "az aks upgrade --resource-group $RG --name $CLUSTER --kubernetes-version $TARGET --control-plane-only"
    - name: "Upgrade system node pool"
      command: "az aks nodepool upgrade --cluster-name $CLUSTER --name system --resource-group $RG --kubernetes-version $TARGET"
    - name: "Upgrade user node pools (rolling)"
      command: "az aks nodepool upgrade --cluster-name $CLUSTER --name $POOL --resource-group $RG --kubernetes-version $TARGET --max-surge 33%"
  post_checks:
    - name: "Verify all nodes ready"
      command: "kubectl get nodes"
    - name: "Run smoke tests"
      command: "./scripts/smoke-test.sh"
  rollback:
    - name: "Scale up old node pool"
    - name: "Cordon new nodes"
    - name: "Drain and delete new node pool"

Glossary

Demo: Platform Version & Capacity Dashboard

Mock Data

{
  "clusters": [
    { "name": "aks-dev-eastus2", "current": "1.29.2", "available": "1.30.0", "channel": "rapid", "status": "up-to-date" },
    { "name": "aks-staging-eastus2", "current": "1.29.0", "available": "1.29.2", "channel": "stable", "status": "update-available" },
    { "name": "aks-prod-eastus2", "current": "1.28.5", "available": "1.29.2", "channel": "none", "status": "upgrade-required" }
  ],
  "quotas": {
    "payments": { "cpu_used": 6.2, "cpu_limit": 8, "memory_used_gi": 12.4, "memory_limit_gi": 16, "pods_used": 14, "pods_limit": 20 },
    "catalog":  { "cpu_used": 3.1, "cpu_limit": 8, "memory_used_gi": 5.8, "memory_limit_gi": 16, "pods_used": 8, "pods_limit": 20 }
  },
  "budgets": [
    { "team": "payments", "budget": 3000, "spent": 2340, "burn_rate": 78 },
    { "team": "catalog",  "budget": 2500, "spent": 1875, "burn_rate": 75 }
  ]
}

Azure Policy: Encryption Required

{
  "properties": {
    "displayName": "Require encryption at rest for storage accounts",
    "policyType": "Custom",
    "mode": "All",
    "parameters": {},
    "policyRule": {
      "if": {
        "allOf": [
          {
            "field": "type",
            "equals": "Microsoft.Storage/storageAccounts"
          },
          {
            "field": "Microsoft.Storage/storageAccounts/encryption.services.blob.enabled",
            "notEquals": true
          }
        ]
      },
      "then": {
        "effect": "deny"
      }
    }
  }
}

Azure Policy: Approved AKS Node Sizes

{
  "properties": {
    "displayName": "Allowed AKS node pool VM sizes",
    "policyType": "Custom",
    "mode": "All",
    "parameters": {
      "allowedSizes": {
        "type": "Array",
        "metadata": {
          "displayName": "Allowed VM Sizes",
          "description": "Approved VM sizes for AKS node pools"
        },
        "defaultValue": [
          "Standard_D2s_v5",
          "Standard_D4s_v5",
          "Standard_D8s_v5",
          "Standard_E4ds_v5",
          "Standard_E8ds_v5"
        ]
      }
    },
    "policyRule": {
      "if": {
        "allOf": [
          {
            "field": "type",
            "equals": "Microsoft.ContainerService/managedClusters/agentPools"
          },
          {
            "field": "Microsoft.ContainerService/managedClusters/agentPools/vmSize",
            "notIn": "[parameters('allowedSizes')]"
          }
        ]
      },
      "then": {
        "effect": "deny"
      }
    }
  }
}

Azure Policy: Required Tags

{
  "properties": {
    "displayName": "Require mandatory resource tags",
    "policyType": "Custom",
    "mode": "Indexed",
    "parameters": {},
    "policyRule": {
      "if": {
        "anyOf": [
          { "field": "tags['CostCenter']", "exists": false },
          { "field": "tags['Team']", "exists": false },
          { "field": "tags['Service']", "exists": false },
          { "field": "tags['Environment']", "exists": false },
          { "field": "tags['ManagedBy']", "exists": false }
        ]
      },
      "then": {
        "effect": "deny"
      }
    }
  }
}

NSG Baseline (AKS)

resource "azurerm_network_security_group" "aks" {
  name                = "nsg-${var.service_name}-${var.environment}"
  location            = var.location
  resource_group_name = var.resource_group_name

  security_rule {
    name                       = "AllowHTTPSInbound"
    priority                   = 100
    direction                  = "Inbound"
    access                     = "Allow"
    protocol                   = "Tcp"
    source_port_range          = "*"
    destination_port_range     = "443"
    source_address_prefix      = "AzureLoadBalancer"
    destination_address_prefix = var.aks_subnet_prefix
    description                = "Allow HTTPS from Azure LB"
  }

  security_rule {
    name                       = "DenyAllInbound"
    priority                   = 4096
    direction                  = "Inbound"
    access                     = "Deny"
    protocol                   = "*"
    source_port_range          = "*"
    destination_port_range     = "*"
    source_address_prefix      = "*"
    destination_address_prefix = "*"
    description                = "Deny all other inbound"
  }

  tags = var.common_tags
}

Defender for Cloud Custom Compliance

resource "azurerm_policy_set_definition" "compliance" {
  name         = "acme-security-standard-v1"
  policy_type  = "Custom"
  display_name = "Acme Security Standard v1"
  description  = "Internal security requirements for all Azure workloads"

  metadata = jsonencode({
    category = "Regulatory Compliance"
    ASC = {
      complianceStandard = {
        displayName = "Acme Security Standard v1"
        version     = "1.0"
      }
    }
  })

  policy_definition_group {
    name         = "ACME-1.1"
    display_name = "ACME-1.1: Data encrypted at rest"
    category     = "Data Protection"
  }

  policy_definition_group {
    name         = "ACME-1.2"
    display_name = "ACME-1.2: Private endpoints only"
    category     = "Network Security"
  }

  policy_definition_group {
    name         = "ACME-2.1"
    display_name = "ACME-2.1: Privileged MFA required"
    category     = "Identity"
  }

  policy_definition_reference {
    policy_definition_id = "/providers/Microsoft.Authorization/policyDefinitions/6fac406b-40ca-413b-bf8e-0bf964659c25"
    reference_id         = "storageEncryption"
    policy_group_names   = ["ACME-1.1"]
  }
}

FinOps Cost Anomaly Alert

resource "azurerm_cost_anomaly_alert" "finops" {
  name            = "anomaly-alert-${var.team}"
  display_name    = "Cost anomaly alert for ${var.team}"
  email_subject   = "Azure Cost Anomaly Detected - ${var.team}"
  email_addresses = var.finops_team_emails
  message         = "An unexpected cost increase was detected."

  subscription_id = var.subscription_id
}

Glossary

Demo: Security & Compliance Scorecard

Mock Data

{
  "secure_score": 82,
  "services": [
    {
      "name": "payment-api",
      "policy_violations": 0,
      "cve_count": 2,
      "tag_compliance_pct": 100,
      "secrets_rotated": true,
      "defender_score": 95
    },
    {
      "name": "catalog-service",
      "policy_violations": 3,
      "cve_count": 7,
      "tag_compliance_pct": 85,
      "secrets_rotated": true,
      "defender_score": 78
    }
  ],
  "finops": {
    "total_budget": 15000,
    "total_spent": 11200,
    "recommendations": [
      { "type": "right-sizing", "savings": 320, "resource": "Standard_D8s_v5 -> Standard_D4s_v5" },
      { "type": "reserved-instance", "savings": 1200, "resource": "3x Standard_D4s_v5 (1yr)" }
    ]
  }
}