What the AI Needs to Know About Your IDP
An Internal Developer Platform (IDP) provides abstractions over infrastructure and operational concerns. Instead of developers writing Terraform for a database, they request one through the platform. Instead of configuring Kubernetes manifests, they use the platform's deployment abstraction. The AI generating code must understand: what abstractions the IDP provides (database, cache, queue, storage, deployment), how to interact with them (API, CLI, declarative manifests), and what conventions to follow (naming, configuration, lifecycle).
Common IDP building blocks: Backstage (developer portal — service catalog, templates, plugins), Crossplane (infrastructure abstraction — Kubernetes-native resource provisioning), Argo CD (GitOps deployment — git-driven continuous delivery), and custom platform APIs (organization-specific abstractions). AI rule: 'Detect which IDP building blocks the project uses. If Backstage: follow the entity definition format. If Crossplane: use Composite Resource Definitions. If custom APIs: use the platform's SDK or API client.'
The AI rule file for IDP projects should include: available platform services (database, cache, queue — with provisioning endpoints), naming conventions (service-name-environment format), configuration sources (where secrets, configs, and feature flags come from), deployment method (GitOps, platform CLI, or API), and observability integration (how to emit metrics, logs, and traces to the platform).
Backstage Integration Patterns
Backstage service catalog: every service is defined by a catalog-info.yaml file in the repository root. The file declares: kind (Component, API, Resource, System), metadata (name, description, tags, owner), spec (type, lifecycle, system, dependsOn, providesApis). AI rule: 'Every repository must have a catalog-info.yaml. When the AI creates a new service: generate the catalog-info.yaml with all required fields. When the AI adds a new API: update the catalog to declare the API (providesApis) and create an API entity definition.'
Backstage software templates: Backstage templates automate service creation. Templates define: parameters (user inputs), steps (scaffolding actions — create repo, generate files, register in catalog), and outputs (links to the new service). AI rule: 'When creating scaffolding for new services: use or extend existing Backstage templates. Do not bypass the template system with manual scaffolding. Templates ensure every new service gets: standard structure, CI/CD pipeline, catalog registration, and initial documentation.'
Backstage plugins: extend the developer portal with custom functionality (deployment dashboards, cost viewers, security scorecards). AI rule for plugin development: 'Follow the Backstage plugin development guidelines: use the plugin API (@backstage/core-plugin-api), register with the plugin catalog, use the Backstage theme and components for consistent UI, and test with the Backstage test harness. Plugins must integrate with Backstage's permission framework for access control.'
Without a catalog-info.yaml: the service is invisible to Backstage. No one can find it in the catalog, discover its APIs, see its dependencies, or know who owns it. During an incident: invisible services are unmanageable. The AI should generate catalog-info.yaml as the very first file when creating a new service — before the application code, before the Dockerfile, before the CI pipeline. The catalog entry is the service's identity in the organization.
Crossplane and GitOps Patterns
Crossplane: Kubernetes-native infrastructure provisioning. Composite Resource Definitions (XRDs) define platform abstractions. Compositions map abstractions to cloud provider resources. Teams request infrastructure through Kubernetes manifests (Claims). AI rule: 'Infrastructure requests: use Crossplane Claims against the platform's XRDs. Do not write raw cloud provider Terraform or CloudFormation. The platform's XRDs enforce standards (naming, security groups, backup schedules) that raw resources would bypass.'
GitOps with Argo CD: the platform deploys applications through GitOps. Application configuration lives in a git repository. Argo CD syncs the desired state (git) to the actual state (Kubernetes). AI rule: 'Deployment changes: commit to the GitOps repository. Do not apply changes directly to Kubernetes (kubectl apply is for emergencies only). The GitOps flow ensures: version-controlled changes, automated rollback (revert the commit), audit trail (git history), and consistent environments (same manifests for staging and production with overlays).'
Environment promotion: the platform defines how changes flow through environments. Pattern: commit to main → deploy to dev (automatic) → promote to staging (manual approval or automated tests) → promote to production (manual approval). AI rule: 'Generate environment-specific overlays (Kustomize) or values (Helm) for each environment. The base manifests are the same. Only environment-specific values (replicas, resource limits, external URLs) differ. Never maintain separate manifest sets per environment.'
Directly applying Kubernetes manifests to production (kubectl apply -f) bypasses the GitOps flow. The actual state of the cluster drifts from what is in git. On the next Argo CD sync: the manual change is overwritten. Or worse: Argo CD is paused and the drift persists indefinitely, creating an undocumented configuration. The AI must generate changes as git commits to the GitOps repository. kubectl apply is for local development and emergency break-glass situations only.
Platform Conventions AI Rules Must Encode
Naming conventions: the platform defines how resources are named. Pattern: {team}-{service}-{environment} (acme-payments-prod, acme-payments-staging). AI rule: 'All resource names follow the platform naming convention. The AI must use the correct team prefix, service name, and environment suffix. Wrong naming: the resource is invisible to platform monitoring and does not get standard lifecycle management.'
Configuration management: the platform provides a configuration service (Consul, AWS Parameter Store, Vault). Applications read configuration from the platform, not from local files or environment variables. AI rule: 'Configuration: read from the platform's config service. Use the platform's config SDK. Do not hardcode values. Do not read from .env files in production (development is ok). Secret rotation: handled by the platform — the application re-reads secrets on rotation events.'
Health and readiness: the platform requires standard health check endpoints. /health (liveness — is the process running?), /ready (readiness — can the service handle requests?), and /metrics (Prometheus metrics endpoint). AI rule: 'Every service: implement /health, /ready, and /metrics. Health: return 200 if the process is alive. Ready: return 200 if all dependencies are connected (database, cache, upstream services). Metrics: expose RED metrics (rate, errors, duration) per endpoint.'
The /health endpoint tells Kubernetes the process is alive. The /ready endpoint tells Kubernetes the service can handle traffic. On startup: /health returns 200 immediately (process is running), but /ready returns 503 until the database connection is established, caches are warmed, and any initialization is complete. Kubernetes routes traffic only to ready pods. Without a proper /ready endpoint: users hit the service before it is initialized, causing errors during deployments and scaling events.
IDP AI Rules Summary
Summary of AI rules for teams building and consuming internal developer platforms.
- Platform abstractions: use IDP APIs for infrastructure, not raw cloud resources
- Backstage: catalog-info.yaml in every repo. Templates for scaffolding. Plugin development guidelines
- Crossplane: Claims against XRDs. Platform enforces standards through Compositions
- GitOps: deploy through git commits. No kubectl apply in production. Environment overlays
- Naming: {team}-{service}-{environment}. Consistent naming enables platform automation
- Configuration: platform config service (Consul/Vault). No hardcoded values. Secret rotation supported
- Health checks: /health, /ready, /metrics on every service. Platform monitors these endpoints
- Environment promotion: dev → staging → production through GitOps with gated approvals