Building an IDP with Backstage: The Story of Personally Implementing a Self-Service Deployment Environment

"Why do I have to wait for the infrastructure team again?" — This is a thought you have likely swallowed at least once while developing. Everyone has likely experienced wasting days on environment setup or deployment approval after finishing the code. I certainly have. The attempt to structurally resolve that frustration is Platform Engineering, and its core deliverable is the IDP (Internal Developer Platform).

After reading this article, you will be able to personally assess the core components of an IDP, from software catalogs to Golden Paths and scorecards. You will learn which tools to adopt and when, and even where you most frequently fail. Whether you are a backend or frontend team, this will be helpful if your team is heading in this direction—or if you feel they should.

Let me mention one thing in advance: Philosophy comes before tools. I have actually seen several teams that had well-established IDPs but no one used them, and I noticed they had something in common. I will explain that at the end.

Key Concepts

What is IDP: "One-stop self-service for developers"

An IDP is an abstracted platform that enables developers to handle infrastructure, deployment, secret management, and monitoring directly in one place. Platform Engineering goes a step beyond the "development-operations team collaboration" of DevOps to the field of building the platform itself into a product. This is precisely the core role of the Platform Team as described by Team Topologies—providing an environment that reduces developers' cognitive load, allowing the team to focus solely on business logic.

The key components can be diagrammed as follows:

Platform as a Product: IDP is based on the philosophy that "the platform team builds a product for internal customers (developers)." It is essentially the same product mindset, differing only in that the customers are fellow developers instead of external users.

Core Tool Ecosystem and BACK Stack

This part might feel a bit overwhelming at first, but when I actually connected these tools for the first time, I had the feeling, "Wow, this really works?" This is the most widely used stack as of 2025–2026:

Wait, while Crossplane and Terraform are both grouped under "infrastructure provisioning," their operational methods are actually quite different. Crossplane acts as a Kubernetes controller, declaring AWS and GCP resources using K8s manifests, whereas Terraform is an independent, declarative tool executed via the CLI. If you already have a K8s environment, Crossplane integrates naturally; otherwise, Terraform is a more versatile choice.

Since GitOps is a new concept, let me briefly go over it — it is a method where Git acts as a Single Source of Truth to automatically synchronize deployments. It involves managing not only the code but also the infrastructure state using Git.

A combination frequently seen in practice is the BACK Stack:

Backstage (포털)
  + ArgoCD (GitOps 배포)
  + Crossplane (인프라 프로비저닝)
  + Kyverno (정책 관리)

When these four elements work together, a single workflow is completed, ranging from "Developer clicks button on portal → Automatic infrastructure generation → Code push → Automatic deployment → Automatic policy check."

Practical Application

Example 1: Software Catalog — Service Ownership Visualization

The first step in building an IDP is usually "identifying what our company currently has." Honestly, this is the most surprising step. It is very common for even a 100-person organization not to know, "Who created this service?" When you first fill out the catalog, there is bound to be a moment when you think, "Was there a service like this?"

The Backstage catalog is registered by adding just one catalog-info.yaml file to each service repository:

# catalog-info.yaml (서비스 루트에 배치)
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment-service
  description: 결제 처리 마이크로서비스
  tags:
    - java
    - payments
  annotations:
    github.com/project-slug: my-org/payment-service
    backstage.io/techdocs-ref: dir:.
    pagerduty.com/service-id: P12345
spec:
  type: service
  lifecycle: production
  owner: payments-team
  dependsOn:
    - component:user-service
    - resource:payments-database
  providesApis:
    - payment-api

Example 2: Golden Path — A design that reduces choices

I also initially wondered, "Why bother enforcing a standard path?" but after experiencing it firsthand in the field, I realized this is the core issue. If you force new developers to constantly worry about "Which framework should I use?", "How do I connect CI/CD?", and "What about monitoring?" during onboarding, their cognitive load explodes.

The Golden Path has already made this decision in advance. Let's look at a Backstage Software Template example:

# template.yaml (Backstage Software Template 예시)
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: nodejs-service-template
  title: Node.js 백엔드 서비스
  description: 팀 표준 Node.js 서비스 스캐폴딩 템플릿
spec:
  owner: platform-team
  type: service
 
  parameters:
    - title: 서비스 기본 정보
      properties:
        name:
          title: 서비스명
          type: string
        owner:
          title: 담당 팀
          type: string
          ui:field: OwnerPicker
 
  steps:
    - id: fetch-template
      name: 템플릿 코드 가져오기
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}
          owner: ${{ parameters.owner }}
 
    - id: publish
      name: GitHub 리포지토리 생성
      action: publish:github
      input:
        repoUrl: github.com?repo=${{ parameters.name }}&owner=my-org
 
    - id: register
      name: 카탈로그에 등록
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}

The key point is that the order of steps is fetch → publish → register. This exactly matches the actual execution order of Backstage Scaffolder. With this single template, the entire process from creating a new service to generating a GitHub repository and registering it in the catalog is automated. Spotify improved service onboarding speed by 60% using this method.

Example 3: Configuring a Self-Service Environment with ArgoCD + Crossplane

When a developer requests "I need another staging environment," the traditional process involved an infrastructure team ticket and a waiting period of a few days; however, with Crossplane, it is completed simply by pushing a single file to Git.

The file below represents a concept called a Composite Resource in Crossplane, which is a custom resource that extends K8s. The apiVersion and kind fields might look unfamiliar, but you can think of them as abstraction layers pre-defined by the company's platform team in the form of K8s extended resources:

# staging-env.yaml (Crossplane Composite Resource 예시)
apiVersion: platform.mycompany.com/v1alpha1
kind: DeveloperEnvironment
metadata:
  name: feature-payment-v2-env
  namespace: team-payments
spec:
  parameters:
    region: ap-northeast-2
    dbSize: db.t3.medium
    clusterSize: small
  compositeDeletePolicy: Foreground  # 리소스 삭제 시 하위 리소스가 모두 정리된 후 완료 처리
  writeConnectionSecretsToNamespace: team-payments

compositeDeletePolicy: Foreground is a deletion policy, so it requires a one-line explanation — when deleting this environment, the deletion is completed only after everything created under it, such as AWS RDS and network resources, is completely cleaned up. This setting is designed to prevent a situation where actual cloud resources remain after the environment is accidentally deleted.

# ArgoCD Application — Git 변경 감지 → 자동 배포
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: feature-payment-v2
  namespace: argocd
spec:
  project: payments-team
  source:
    repoURL: https://github.com/my-org/environments
    targetRevision: HEAD
    path: teams/payments/feature-payment-v2
  destination:
    server: https://kubernetes.default.svc
    namespace: feature-payment-v2
  syncPolicy:
    automated:
      prune: true      # Git에서 삭제된 리소스를 클러스터에서도 자동 제거
      selfHeal: true   # 클러스터 상태가 Git과 달라지면 자동으로 복원

prune and selfHeal are settings that are easy to overlook in practice; without them, a situation arises where they are "deleted from Git but still remain in the actual environment." Once this configuration is complete, the moment a developer uploads staging-env.yaml to Git, Crossplane creates AWS resources and ArgoCD automatically handles the K8s deployment.

After integrating dozens of internal tools into a single console using this method, Netflix reduced the number of deployment-dependent tickets for the central DevOps team by 65%. If you think about what this is like from an engineer's perspective—you don't really know the immense sense of autonomy it brings to be able to create and delete environments yourself without having to ask someone for help every time—until you actually try it.

Example 4: Measuring Operational Maturity with Scorecards

Scorecards are widely used to measure whether an IDP is operating well after implementation. SaaS tools like Port or Cortex allow you to use them immediately with a single YAML definition. Here is an example based on Port:

# Port 스코어카드 정의 예시 (Port 포털에서 직접 등록)
identifier: service-maturity
title: 서비스 운영 성숙도
levels:
  - color: red
    title: Basic
  - color: gold
    title: Silver
  - color: silver
    title: Gold
rules:
  - identifier: has-catalog-info
    title: 카탈로그 등록 여부
    level: Basic
    query:
      combinator: and
      rules:
        - property: $identifier
          operator: isNotEmpty
  - identifier: has-owner
    title: 오너십 지정
    level: Basic
    query:
      combinator: and
      rules:
        - property: $team
          operator: isNotEmpty
  - identifier: has-runbook
    title: 런북 문서화
    level: Silver
    query:
      combinator: and
      rules:
        - property: runbook_url
          operator: isNotEmpty
  - identifier: has-alerting
    title: PagerDuty 알람 연동
    level: Gold
    query:
      combinator: and
      rules:
        - property: pagerduty_service_id
          operator: isNotEmpty

Once each service is scored, platform teams can identify "which team is operating without a runbook" without conversation. According to Gartner's 2026 predictions, 80% of large engineering organizations will have dedicated platform teams, and the first thing those teams utilize is this kind of scorecard-based visibility.

Pros and Cons Analysis

Advantages

ROI figures are based on the State of Platform Engineering Report Vol. 4 (platformengineering.org).

Disadvantages and Precautions

DIY vs SaaS: With research showing that building and operating Backstage yourself requires up to 15 engineers, an increasing number of organizations are rapidly switching to SaaS solutions such as Port, Cortex, and Roadie. You can let go of the burden of having to "build it yourself from scratch."

The Most Common Mistakes in Practice

1. The Misconception that "If I build it, people will use it on their own": In fact, I experienced a case where a team invested six months to build an excellent portal, only to find that the number of users was in the single digits three months later. An IDP (Integrated Development Project) begins the moment developers actually start using it after launch. Without a loop of securing an early adopter team and improving based on their direct feedback, the portal you worked so hard to build will become an internal tool that no one uses.

2. Attempts to solve organizational problems with tools: IDP is a tool that automates already recognized problems such as "unclear service ownership" and "complex deployment processes." However, platforms do not solve cultural issues like a lack of trust between teams or unclear responsibilities. In fact, I have seen cases where confusion actually increased after teams thought, "We have adopted a tool, so we are now DevOps." Even if Crossplane automatically creates the environment, it is useless without an agreement on who is responsible for it.

3. The desire to make the Golden Path perfect from the start: Trying to cover every case from the beginning results in a template that is inconvenient for anyone to use. It is realistic to make the Golden Path for only the most common 80% of cases and leave the rest flexible.

In Conclusion

The core of Platform Engineering and IDP is to structurally eliminate the friction that keeps developers waiting. However, to make this possible, you must first clearly identify "what the most repetitive and unnecessary waiting is within our team" before considering tools. Tools come afterward. You don't need to start with anything grandiose. Simply introducing a software catalog can immediately reduce the time wasted on the question, "Who manages this service?"

3 Steps to Start Right Now:

1. It is a good idea to list the pain points within your team first. If you ask five colleagues, "What is the hardest part about deployment?", you will see what needs to be solved first in the IDP. Defining the problem comes before the tools.

2. You can start with the Software Catalog. If you find it burdensome to launch Backstage directly, registering a list of team services with the Port free tier is a good starting point. You can get started by adding just one file, catalog-info.yaml, to the repository.

3. It is also effective to create just one Golden Path template. If you organize the standard scaffolding for the types of services your team creates most frequently (e.g., Node.js API servers) in the form of a Backstage Template or cookiecutter, you will immediately feel the difference starting from the next new service creation.

Next Post: Developing Backstage Plugins Yourself — How to Implement Your Team's Custom Self-Service Actions with TypeScript

Reference Materials

• Platform Engineering in 2026: 5 Shifts Driving the Rise of Internal Developer Platforms | Growin
• Announcing the State of Platform Engineering Report Vol 4 | platformengineering.org
• Platform Engineering in 2026: Why DIY Is Dead | Roadie.io
• Top 10 Internal Developer Platforms (IDPs) Compared for 2025 | WSO2
• Navigating Internal Developer Platforms in 2025 | Infisical
• Platform Engineering, IDPs, and Golden Paths | Digital.ai
• Building an Internal Developer Portal with Backstage, AKS, Crossplane, and Argo CD | Medium
• The Golden Triangle of Platform Engineering: Backstage, ArgoCD, and Crossplane | Uplatz
• What is an Internal Developer Platform (IDP)? | Spacelift
• Netflix: Federated Platform Console to Unify Engineering Experience | platformengineering.org
• Top 10 platform engineering tools to use in 2025 | platformengineering.org
• Internal Developer Platform IDP 2026 Complete Guide | Calmops