V2 Controller-Based Architecture

Executive Summary

The V2 architecture represents a significant evolution of idpbuilder, transitioning from a CLI-driven installation model to a controller-based architecture. This change enables idpbuilder to function as a true Kubernetes-native platform, where infrastructure components and application workloads are managed declaratively through Kubernetes Custom Resources (CRs) and reconciliation loops.

Goals

• Kubernetes-Native Management: Enable all functionality to be managed through kubectl and GitOps tools like ArgoCD
• Separation of Concerns: Clearly delineate infrastructure provisioning from application/service management
• Production Readiness: Support production workloads and virtualized control planes (e.g., vCluster, Cluster API)
• Extensibility: Allow easier integration of additional services and customization by end users
• Operational Excellence: Improve observability, debugging, and lifecycle management through standard Kubernetes patterns

Key Benefits

• Kubernetes-Native: Everything manageable via kubectl, full GitOps compatibility, standard Kubernetes patterns
• Operational Excellence: Better observability through conditions, events, and metrics; easier debugging with kubectl describe and logs
• Flexibility: Easy component customization, support for alternative components, plugin architecture
• Production-Ready: HA configurations supported, proper separation of concerns, infrastructure-agnostic
• Extensibility: Third-party controllers can integrate, package ecosystem enablement, easier community contributions

High-Level Design

The new architecture introduces a composable, provider-based system where platform components are defined as separate Custom Resources with duck-typed interfaces. This enables:

• Multiple provider implementations running simultaneously
• Pluggable Git providers (Gitea, GitHub, GitLab)
• Pluggable Gateway providers (Nginx Ingress, Envoy Gateway, Istio Gateway)
• GitOps management (ArgoCD, Flux)

Key Architecture Principles

1. Duck Typing: Providers expose common status fields without requiring a shared interface type
2. Composition: Platform references multiple provider CRs by name and kind
3. Extensibility: New provider types can be added without modifying Platform CR
4. Independence: Each provider CR can exist and be managed independently
5. Flexibility: Components choose providers dynamically at runtime

Custom Resource Definitions

Platform CR

The Platform CR represents the entire IDP platform instance:

apiVersion: idpbuilder.cnoe.io/v1alpha1
kind: Platform
metadata:
  name: localdev
  namespace: idpbuilder-system
spec:
  domain: cnoe.localtest.me
  
  components:
    gitProviders:
      - name: gitea-local
        kind: GiteaProvider
        namespace: idpbuilder-system
    
    gateways:
      - name: nginx-gateway
        kind: NginxGateway
        namespace: idpbuilder-system
    
    gitOpsProviders:
      - name: argocd
        kind: ArgoCDProvider
        namespace: idpbuilder-system

status:
  conditions:
    - type: Ready
      status: "True"
  providers:
    gitProviders:
      - name: gitea-local
        ready: true
    gateways:
      - name: nginx-gateway
        ready: true
    gitOpsProviders:
      - name: argocd
        ready: true

Git Provider CRs

Git providers expose common status fields via duck-typing:

GiteaProvider Example

apiVersion: idpbuilder.cnoe.io/v1alpha1
kind: GiteaProvider
metadata:
  name: gitea-local
  namespace: idpbuilder-system
spec:
  namespace: gitea
  version: 1.24.3
  
  adminUser:
    username: giteaAdmin
    email: admin@cnoe.localtest.me
    autoGenerate: true
  
  organizations:
    - name: idpbuilder
      description: IDP Builder Bootstrap Organization

status:
  conditions:
    - type: Ready
      status: "True"
  # Duck-typed fields
  endpoint: https://gitea.cnoe.localtest.me
  internalEndpoint: http://gitea-http.gitea.svc.cluster.local:3000
  credentialsSecretRef:
    name: gitea-admin-secret
    namespace: gitea
    key: token

GitHubProvider Example

apiVersion: idpbuilder.cnoe.io/v1alpha1
kind: GitHubProvider
metadata:
  name: github-external
  namespace: idpbuilder-system
spec:
  organization: my-organization
  endpoint: https://api.github.com
  
  credentialsSecretRef:
    name: github-credentials
    namespace: idpbuilder-system
    key: token
  
  repositoryDefaults:
    visibility: private
    defaultBranch: main

status:
  conditions:
    - type: Ready
      status: "True"
  # Duck-typed fields
  endpoint: https://github.com/my-organization
  internalEndpoint: https://api.github.com
  credentialsSecretRef:
    name: github-credentials
    namespace: idpbuilder-system
    key: token

Gateway Provider CRs

Gateway providers manage ingress and routing:

NginxGateway Example

apiVersion: idpbuilder.cnoe.io/v1alpha1
kind: NginxGateway
metadata:
  name: nginx-gateway
  namespace: idpbuilder-system
spec:
  namespace: ingress-nginx
  version: 1.13.0
  
  config:
    controller:
      service:
        type: NodePort
        nodePorts:
          http: 30080
          https: 30443
  
  ingressClass:
    name: nginx
    isDefault: true

status:
  conditions:
    - type: Ready
      status: "True"
  # Duck-typed fields
  ingressClassName: nginx
  loadBalancerEndpoint: http://172.18.0.2
  internalEndpoint: http://ingress-nginx-controller.ingress-nginx.svc.cluster.local

GitOps Provider CRs

GitOps providers manage continuous deployment:

ArgoCDProvider Example

apiVersion: idpbuilder.cnoe.io/v1alpha1
kind: ArgoCDProvider
metadata:
  name: argocd
  namespace: idpbuilder-system
spec:
  namespace: argocd
  version: v2.12.0
  
  adminCredentials:
    autoGenerate: true
  
  projects:
    - name: default
      description: Default project
    - name: platform
      description: Platform components

status:
  conditions:
    - type: Ready
      status: "True"
  # Duck-typed fields
  endpoint: https://argocd.cnoe.localtest.me
  internalEndpoint: http://argocd-server.argocd.svc.cluster.local
  credentialsSecretRef:
    name: argocd-admin-secret
    namespace: argocd
    key: password

Multi-Provider Support

The V2 architecture allows multiple providers of the same type to coexist, enabling flexible configurations:

Multiple Git Providers Example

apiVersion: idpbuilder.cnoe.io/v1alpha1
kind: Platform
metadata:
  name: hybrid
spec:
  domain: cnoe.localtest.me
  components:
    gitProviders:
      # Local development repositories
      - name: gitea-dev
        kind: GiteaProvider
        namespace: idpbuilder-system
      # Production repositories in GitHub
      - name: github-prod
        kind: GitHubProvider
        namespace: idpbuilder-system

Multiple Gateway Providers Example

apiVersion: idpbuilder.cnoe.io/v1alpha1
kind: Platform
metadata:
  name: multi-gateway
spec:
  domain: cnoe.localtest.me
  components:
    gateways:
      # Public-facing services
      - name: nginx-public
        kind: NginxGateway
        namespace: idpbuilder-system
      # Internal service mesh
      - name: envoy-internal
        kind: EnvoyGateway
        namespace: idpbuilder-system

Use Cases

Local Development

Developers can spin up a complete IDP environment locally with Gitea for Git repositories, Nginx for ingress, and ArgoCD for GitOps.

Hybrid Cloud

Organizations can use Gitea for development environments while leveraging GitHub or GitLab for production repositories, all managed through a single Platform CR.

Service Mesh Integration

Teams can deploy Istio Gateway for service mesh capabilities alongside traditional Nginx ingress for different application requirements.

Multi-Team GitOps

Different teams can use different GitOps tools - ArgoCD for application deployments and Flux for infrastructure management - within the same platform.

Migration Path

The V2 architecture maintains backward compatibility with the existing CLI experience:

• The CLI automatically generates provider CRs from command-line flags
• Controllers are installed transparently during cluster creation
• Users can continue using idpbuilder create without changes
• Advanced users can directly create and manage CRs for fine-grained control

Next Steps

The V2 architecture is currently in the proposal phase. To learn more or provide feedback:

• Review the full technical specification
• Join discussions on the CNCF Slack channel
• Contribute to the GitHub repository