How to Set Up an Internal Developer Platform (IDP): A Beginner’s Step-by-Step Guide

An Internal Developer Platform (IDP) is a combination of tools, APIs, and a self-service interface designed to empower developers in building, deploying, and operating applications seamlessly. This guide provides a comprehensive overview of setting up an IDP, focusing on improving developer experience, enhancing delivery speed, and centralizing compliance. Ideal for development teams and operations personnel who want streamlined workflows, this article delves into the setup process, benefits, key components, and best practices to ensure success in your IDP journey.

What is an Internal Developer Platform (IDP)?

An Internal Developer Platform (IDP) consolidates various automation tools, discoverability mechanisms, and guardrails to create a standardized workspace for developers. In simple terms:

• IDP components include developer-focused automation, discoverability, and compliance guardrails.
• Core objective: enhance developer experience (DX) while accelerating delivery and maintaining compliance.
• An IDP is not just a tool but an architectural framework encompassing service catalogs, CI/CD templates, infrastructure provisioning, secrets management, and observability.

How an IDP Differs from Related Concepts

• DevOps represents a cultural shift towards improved software delivery.
• Site Reliability Engineering (SRE) emphasizes reliability and operational excellence within systems.
• Platform Engineering is responsible for developing and maintaining the IDP, serving as the backbone for the platform.

Who Benefits from an IDP?

• Developers: Enjoy simple onboarding and predictable deployments.
• Operations/SRE Teams: Gain consistent observability and automated guardrails.
• Product Teams: Achieve faster time-to-market and reduced operational churn.

For more insight, check out Humanitec’s explanation of IDPs.

Why an IDP Matters — Key Benefits and Indicators for Implementation

Benefits

• Faster Time-to-Market: Self-service templates and standardized pipelines lower friction in development processes.
• Consistency & Compliance: Implementing policy-as-code and standardized modules minimizes drift in infrastructure.
• Reduced Cognitive Load: Fewer platform choices and clear defaults decrease decision fatigue for developers.
• Streamlined Onboarding: Well-defined templates and documentation allow new engineers to contribute sooner.
• Lower Operational Load: The platform team centralizes maintenance and other routine tasks.

Signs You Need an IDP

• Duplication of Efforts: Multiple teams repeatedly creating similar infrastructure code or pipeline processes.
• Slow Onboarding: New engineers experience extensive delays (days/weeks) before contributing fully.
• Frequent Operational Interruptions: Regular interruptions for routine tasks such as database provisioning.
• Inconsistent Deployment Patterns: Variations in deployment processes increase the likelihood of incidents.

Trade-offs and Prerequisites

• Initial Investment: Allocate resources for tooling and a dedicated platform team.
• Cultural Shift: Teams must adapt to new workflows and trust in the platform’s capabilities.
• MVP Scope Definition: Clearly decide an MVP scope to prevent overengineering.

Gain insights into when platform engineering makes sense with ThoughtWorks’ Radar and articles.

Core Components of a Practical IDP

A practical IDP comprises well-integrated capabilities. Below are essential components and recommended tools:

1. Developer Portal / Service Catalog: A central hub for creating services, finding templates, and accessing documentation.

   • Popular Tool: Backstage (open-source).

2. CI/CD and Build/Deploy Pipelines: Provide reusable pipeline templates such as linting, unit tests, builds, scanning, and deployment.

   • Options: GitHub Actions/GitLab CI, Tekton, or Jenkins X for Kubernetes-focused pipelines.

3. Infrastructure Provisioning and IaC: Offer reusable Infrastructure as Code (IaC) modules (e.g., Terraform, Pulumi).

   • Approach: Enable developers to request infrastructure easily via the portal.

4. Secrets and Identity Management: Centralize secrets using HashiCorp Vault or cloud KMS.

   • Implement Single Sign-On (SSO) and Role-Based Access Control (RBAC) to manage credentials securely.

5. Observability, Logging, and Metrics: Utilize libraries and dashboards like Prometheus, Grafana, and OpenTelemetry for monitoring and alerting.

6. Platform Templates & Self-Service Tools: Create CLI/UI wrappers for commonplace tasks to avoid custom scripts.

7. Policy, Governance, and Access Controls: Automate policy enforcement through checks and policy-as-code (e.g., OPA/Gatekeeper).

Here’s a quick comparison table highlighting common choices for core components:

Step-by-Step Setup: A Beginner-Friendly Roadmap

Here’s a staged approach to build a Minimum Viable Product (MVP) IDP that swiftly delivers value:

1. Assess Needs and Set Clear Goals (MVP Scope)

   • Select one or two product teams.
   • Choose a standard language/framework (e.g., Node.js or Spring Boot).
   • Decide on a runtime—Kubernetes is recommended for flexibility; consider serverless or VMs depending on team preferences.
   • Define success metrics like time-to-create-service and deployment frequency.

2. Choose an Approach and Core Tooling

   • Use Backstage for the developer portal (Backstage documentation).
   • Opt for GitHub or GitLab for repository management.
   • Choose GitHub Actions or Tekton/Argo for CI/CD pipelines.
   • Utilize Terraform or Pulumi for Infrastructure as Code.
   • Employ Vault or cloud KMS for secret management.
   • Implement Prometheus, Grafana, and OpenTelemetry for observability.

3. Design Service Templates and Repository Structure

   • Determine whether to use a monorepo or multi-repo setup. For guidance, refer to our Monorepo vs Multi-repo guide.
   • Scaffold a sample service template using the selected framework along with a standard Dockerfile, health checks, logging, and OpenTelemetry instrumentation.
   • Leverage Backstage software templates or Cookiecutter to scaffold repositories.

   Example Backstage software template snippet (template.yaml):

   apiVersion: backstage.io/v1beta3
   kind: ComponentTemplate
   metadata:
     name: node-service
   spec:
     owner: platform-team
     type: service
     path: ./templates/node-service
   

4. Build Simple CI/CD Templates and Deploy Pipeline

   • Create a standardized pipeline that includes linting, unit tests, builds, scanning, and deployment to staging environments.
   • Initially focus on a single environment (staging) and use manual approvals for production.

   Example minimal GitHub Actions workflow (.github/workflows/ci-cd.yml):

   name: CI/CD
   on:
     push:
       branches: [ main ]
   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v3
         - name: Set up Node.js
           uses: actions/setup-node@v3
           with:
             node-version: '18'
         - name: Install
           run: npm ci
         - name: Lint
           run: npm run lint
         - name: Test
           run: npm test -- --ci --reporter=jest-junit
         - name: Build Docker image
           run: |
             docker build -t ghcr.io/${{ github.repository }}:${{ github.sha }} .
         - name: Scan image
           uses: aquasecurity/[email protected]
           with:
             image-ref: ghcr.io/${{ github.repository }}:${{ github.sha }}
         - name: Push image
           run: docker push ghcr.io/${{ github.repository }}:${{ github.sha }}
         - name: Deploy to staging (GitOps)
           run: echo "Triggering ArgoCD sync via repo update"
   

5. Provision Infrastructure Modules and Automation

   • Publish Terraform modules for networking, databases, and shared services.
   • Create a request flow in the portal: “Request a Database” triggers a Terraform run with necessary parameters.

   Example Terraform module interface (modules/db/main.tf):

   variable "db_name" {}
   variable "env" {}
   resource "aws_db_instance" "default" {
     identifier = "${var.db_name}-${var.env}"
     engine     = "postgres"
     # ...
   }
   

6. Add Secrets, SSO, and RBAC

   • Integrate SSO (OAuth/OIDC/SAML) aligned with platform roles. For practical setup, see our SSO integration guide.
   • Centralize secrets via Vault or KMS, employing short-lived credentials for least-privilege access.

7. Add Observability and Standardized Alerts

   • Supply libraries and sidecars for metrics and tracing using OpenTelemetry.
   • Provide pre-configured Grafana dashboards and standardized alerting rules using Prometheus.

8. Onboard First Team, Gather Feedback, Iterate

   • Document all workflows in the developer portal and conduct hands-on workshops with the first team.
   • Measure key performance indicators (KPIs) like lead time for changes, deployment frequency, and developer satisfaction, iterating accordingly.

Practical Example: Minimal IDP Architecture for an MVP

Essential components provide a robust yet simplistic architecture:

• Backstage (portal & templates)
• GitHub (source control)
• GitHub Actions (CI) + ArgoCD (GitOps deployment)
• Terraform modules (IaC)
• Vault (secrets)
• Prometheus & Grafana + OpenTelemetry (observability)

Example Flow

1. Developer uses the Backstage portal to create a service from a template.
2. The template generates a repository with code, CI workflow, and IaC module references.
3. CI builds the image, executes scans, and pushes it to the registry.
4. GitOps (ArgoCD) manages the desired state and deploys to the cluster.
5. Observability agents automatically instrument the service, providing accessible dashboards.

This setup maintains simplicity while allowing for future adjustments as needs evolve.

Security, Compliance, and Governance: What Beginners Must Know

Automated Guardrails

• Implement policies through policy-as-code (e.g., OPA/Gatekeeper) within admission controllers or CI checks.
• Ensure image scanning and Software Bill of Materials (SBOM) generation as part of CI workflows.

Secrets Management Best Practices

• Avoid storing secrets in repositories.
• Use sealed-secrets or Vault with dynamic credentials.
• Expose secrets through environment variables or mounted files with minimal privileges.

Access Control and Least Privilege

• Integrate SSO and map identities to Role-Based Access Control (RBAC).
• Use short-lived tokens and refined Identity Access Management (IAM) policies for security.

Supply Chain Security

• Regularly scan images for vulnerabilities, blocking risky images whenever necessary.
• Implement image signing (e.g., cosign) and verify signatures before deployment.
• Generate SBOMs for critical services to enhance security practices.

Document incident response playbooks and create links in the portal to the respective documents.

Common Pitfalls and How to Avoid Them

1. Overbuilding Before Validation: Start with an MVP that addresses the most urgent issues, avoiding feature overload from day one.
2. Too Many Options for Developers: Provide opinionated defaults while allowing customization for experienced teams where applicable.
3. Poor Onboarding and Discoverability: Ensure that documentation is easily accessible in the portal and that workshops are conducted.
4. Neglecting Metrics: Instrument both the platform and applications. Focus on tracking adoption rates and overall developer satisfaction.

Operationalizing & Scaling the Platform

Team Model

• Platform Team: Responsible for core components, templates, and Service Level Agreements (SLAs).
• Consider embedding platform engineers within product teams to foster closer collaboration.

SLA, Support Model, and Catalog Lifecycle

• Provide tiered support options like office hours, ticketing systems, and on-call escalation paths.
• Develop a deprecation policy for maintaining templates and modules.

KPIs to Measure Success

• Lead time for changes
• Deployment frequency
• Mean time to recovery (MTTR)
• Developer satisfaction score
• Cost per deployment or environment

For more frameworks on measuring ROI on platform initiatives, refer to Humanitec’s articles.

Checklist for Launching Your First IDP MVP

Minimum Deliverables

• Developer portal (Backstage) featuring at least one service template.
• A functional CI/CD pipeline template including linting, testing, building, and scanning.
• At least one IaC module (e.g., for a database or VPC) with the necessary automation.
• Basic integration for secrets (Vault or KMS) and SSO.
• A functional observability dashboard and basic alerting setup.

Validation Steps with the Initial Team

• Onboard 1–2 teams, host an end-to-end workshop, and collect feedback for improvements.
• Monitor metrics such as time-to-create-service, time-to-first-deploy, and deployment frequency.

30/60/90 Day Priorities

• 30 Days: Solidify templates, addressing early usability challenges.
• 60 Days: Implement automated policies and extend template offerings to other programming languages.
• 90 Days: Introduce SSO/RBAC if not included in the MVP, expand to additional teams, and initiate cost monitoring initiatives.

Download a printable 1-page MVP checklist here.

Conclusion and Next Steps

Summary

• Start small and practical; focus on enhancing developer experience, establishing guardrails, and ensuring repeatability.
• Utilize opinionated templates and automated policies to lighten cognitive loads without sacrificing flexibility.
• Continuously measure adoption rates and iterate processes based on developer feedback.

Actionable Next Steps

1. Define an MVP scope focused on a single team and runtime.
2. Choose a foundational stack, such as Backstage, GitHub, GitHub Actions, Terraform, Vault, and Prometheus.
3. Execute a pilot program and gather feedback for improvements.

Resources & Further Reading

• Humanitec — What is an Internal Developer Platform?: Link
• Backstage (Spotify) — Backstage documentation: Link
• ThoughtWorks — Technology Radar & Platform Engineering guidance: Link

Recommended Open-Source Projects and Tools

• Backstage (Developer Portal)
• ArgoCD / Flux (GitOps)
• Tekton (Kubernetes-native CI)
• Terraform (IaC)
• HashiCorp Vault (Secrets Management)
• Prometheus, Grafana, OpenTelemetry (Observability)

Internal Links for Complementary Topics

• Monorepo vs Multi-repo Strategies — Beginners Guide
• Single Sign-On (SSO) Integration Guide — Beginners
• Redis Caching Patterns Guide
• Software Architecture — Ports and Adapters Pattern (Beginners Guide)
• Windows Deployment Services Setup — Beginners Guide