IDP Builder Documentation

Welcome to the IDP Builder documentation. This guide will help you get started with creating your internal developer platform.

Version 2 Architecture

Version 2 introduces a controller-based architecture with clear separation between the CLI and controllers:

CLI and Controller Separation

The new architecture separates responsibilities:

  • CLI Responsibilities:
    • Infrastructure provisioning (creating Kind clusters)
    • Controller deployment to the cluster
    • Custom Resource (CR) instantiation for common use cases
    • Developer-friendly workflow automation
  • Controller Responsibilities:
    • Platform orchestration and lifecycle management
    • Provider installation and configuration (Git, Gateway, GitOps)
    • GitOps integration and repository management
    • Continuous reconciliation of desired state

Two Deployment Modes

IDP Builder v2 supports two deployment modes:

Mode 1: CLI-Driven (Development)

For local development, use the CLI for a quick setup:

idpbuilder create

This will:

  • Provision a Kind cluster
  • Deploy idpbuilder controllers
  • Create Platform and Provider Custom Resources
  • Configure all components automatically

Mode 2: GitOps-Driven (Production)

For production deployments, bypass the CLI entirely:

# Install controllers via Helm
helm repo add idpbuilder https://cnoe-io.github.io/idpbuilder
helm install idpbuilder-controllers idpbuilder/idpbuilder-controllers \
  --namespace idpbuilder-system --create-namespace

# Or use kubectl with static manifests
kubectl apply -f https://github.com/cnoe-io/idpbuilder/releases/latest/download/install.yaml

Then manage Platform and Provider CRs via your GitOps tool (ArgoCD, Flux, etc.)

Pluggable Providers

Choose the components that fit your needs:

  • Git Providers: Gitea (in-cluster), GitHub, GitLab
  • Gateway Providers: Nginx Ingress, Envoy Gateway, Istio Gateway
  • GitOps Providers: ArgoCD, Flux

Installation

Using Homebrew (macOS/Linux)

The easiest way to install IDP Builder is through Homebrew:

# Install stable version
brew install cnoe-io/tap/idpbuilder

# Install specific version
brew install cnoe-io/tap/idpbuilder@<version>

# Install nightly version
brew install cnoe-io/tap/idpbuilder-nightly

From Releases

Download the binary for your platform from the releases page:

arch=$(if [[ "$(uname -m)" == "x86_64" ]]; then echo "amd64"; else uname -m; fi)
os=$(uname -s | tr '[:upper:]' '[:lower:]')

idpbuilder_latest_tag=$(curl --silent "https://api.github.com/repos/cnoe-io/idpbuilder/releases/latest" | grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/')
curl -LO https://github.com/cnoe-io/idpbuilder/releases/download/$idpbuilder_latest_tag/idpbuilder-$os-$arch.tar.gz
tar xvzf idpbuilder-$os-$arch.tar.gz

Getting Started

Development Mode (Quick Start)

For local development, use the CLI for a quick setup:

./idpbuilder create

This will:

  • Set up a local Kind Kubernetes cluster
  • Deploy idpbuilder controllers to the cluster
  • Install and configure Git provider (Gitea by default)
  • Install and configure Gateway (Nginx Ingress by default)
  • Install and configure GitOps provider (ArgoCD by default)
  • Configure necessary resources and integrations

Production Mode (GitOps)

For production deployments to existing Kubernetes clusters:

# 1. Install controllers
helm repo add idpbuilder https://cnoe-io.github.io/idpbuilder
helm install idpbuilder-controllers idpbuilder/idpbuilder-controllers \
  --namespace idpbuilder-system --create-namespace

# 2. Create Provider CRs (via GitOps repo)
# - GiteaProvider, NginxGateway, ArgoCDProvider, etc.

# 3. Create Platform CR (via GitOps repo)
# - References the Provider CRs

All configuration is done declaratively through Custom Resources, managed by your GitOps workflow.

Minimum Requirements

The requirements for your cluster will depend on what it is running, but we recommend a minimum of:

  • 4 CPU cores
  • 4 GiB of RAM
  • Docker installed and running

Configuration

Private Registry Authentication

IDP Builder can be configured to use private registry authentication from the host filesystem by using the --registry-config flag with the create command.

By default, this will look for a registry config file in the default podman and docker paths. You can optionally specify a file:

idpbuilder create --registry-config=$HOME/path/to/auth.json

Pluggable Packages

IDP Builder supports pluggable packages to extend functionality. Check the full documentation for details on available packages and how to create custom ones.

Contributing

We welcome contributions! Check out our contribution guidelines to get started.

Community

Additional Resources

For more comprehensive documentation, please visit: