An Internal Developer Platform (IDP) bridges the gap between raw infrastructure primitives and developer velocity. The platform’s primary job is to establish “Golden Paths”—pre-approved, automated, self-service workflows that allow developers to provision infrastructure, run microservices, and manage environments without needing deep Kubernetes or Cloud expertise.
Below is an architectural blueprint for an IDP powered by Backstage, Terraform, GitHub Actions, ArgoCD, and Kubernetes.
1. High-Level Architectural Topology

2. Core Platform Components & Layering
Layer 1: Developer Interaction (Backstage)
- Software Catalog & Templates: Developers choose from predefined “Golden Path” templates (e.g., Create New Node.js Service with PostgreSQL).
- Scaffolder: Collects parameters (App Name, Region, Database Size) and auto-generates a new GitHub repository populated with application code, Helm/Kustomize charts, and Terraform definitions.
Layer 2: Pipeline & Provisioning Engine (GitHub Actions & Terraform)
- Infrastructure Pipeline: Runs
terraform planon Pull Requests andterraform applyon merges to provision cloud-native dependencies (e.g., Azure Database for PostgreSQL, AWS S3, IAM Roles). - Workload Identity Federation (OIDC): Authenticates GitHub Actions directly to cloud providers and Kubernetes without storing static credentials or access keys.
Layer 3: Application Delivery & State Reconciliation (ArgoCD & Kubernetes)
- GitOps Controller: ArgoCD monitors application manifest repositories. When GitHub Actions pushes a updated Helm chart or image tag, ArgoCD automatically reconciles state in the Kubernetes cluster.
- Environment Isolation: Uses Kubernetes Namespaces augmented with NetworkPolicies, ResourceQuotas, and LimitRanges to provide multi-tenant team isolation.
3. End-to-End Self-Service Workflow Sequence
1.Template Selection in Portal:Developer Action.
- A developer logs into Backstage and selects the “New Microservice” catalog template.
- They fill out a form providing parameters:
- App Name:
payment-service - Language: Go
- Database Required: Yes (PostgreSQL)
- Environment:
Staging
- App Name:
2.Repository Scaffolding:Portal Orchestration.
- Backstage executes the template engine, creating a target GitHub repository:
org/payment-service. - It populates the repository with:
- Base application skeleton code.
- A
/terraformdirectory with pre-approved modules for RDS/PostgreSQL. - A
/helmchart for Kubernetes deployment. - A
.github/workflows/deploy.ymlpipeline.
- Backstage registers the new entity in its software catalog and registers the deployment with ArgoCD.
3.Infrastructure Provisioning via Terraform:CI/CD & IaC Execution.
- GitHub Actions triggers the initial workflow.
- It authenticates to the Cloud Provider via OIDC.
- Runs
terraform applyinside/terraformto spin up the isolated cloud database, creating an output secret in HashiCorp Vault or Azure Key Vault / AWS Secrets Manager.
4.Kubernetes Deployment via ArgoCD:GitOps Delivery.
- GitHub Actions builds the Docker container, scans it using Trivy, and pushes it to container registry.
- The workflow updates the
/helm/values.yamlimage tag parameter in Git. - ArgoCD detects the commit and pulls the updated Helm chart, creating the deployment, service, ingress, and pod resources inside the
team-paymentsnamespace.
4. Key Engineering Guardrails & Governance
IaC & Terraform Governance
- Module Registry: Force developers to consume pre-tested, platform-team-maintained Terraform modules via a private module registry rather than writing raw IaC.
- Policy-as-Code: Run static security checks (
checkovortfsec) and policy validation (OPA / Sentinel) inside GitHub Actions beforeterraform applyexecutes.
Kubernetes Runtime Security
- Pod Security Standards (PSS): Enforce
restrictedorbaselinesecurity profiles cluster-wide using Kyverno or OPA Gatekeeper. - Secret Injection: Never store raw database passwords in Git. Inject secrets into Kubernetes pods at runtime using External Secrets Operator (ESO) connected to AWS Secrets Manager or HashiCorp Vault.
5. Summary Matrix: Responsibility Partitioning
| Component | Platform Team Role (Maintainers) | Developer Team Role (Consumers) |
|---|---|---|
| Backstage Portal | Maintains golden-path templates, UI plugins, catalog RBAC. | Selects templates, views operational metrics, reads service docs. |
| Terraform Code | Authors reusable, hardened modules (S3, VPC, DB). | Supplies module inputs via Backstage forms (e.g., db_size = “small”). |
| GitHub Actions | Owns reusable global workflow templates and security scans. | Triggers builds via standard git push or PRs. |
| Kubernetes Cluster | Operates cluster infrastructure, ingress controllers, CNI, and ArgoCD. | Configures runtime environment variables and application scaling params. |
