Porch Controllers

The Porch controllers manage Repository synchronization, PackageRevisions, PackageVariants, and PackageVariantSets.

Global Configuration

These flags apply to the controllers binary, independent of which reconcilers are enabled:

Enabling Controllers

Command Line Arguments

The controllers support these command line arguments:

args:
- --reconcilers=repositories,packagevariants,packagevariantsets  # Comma-separated list
# OR use --reconcilers=* to enable all controllers

Repository Controller Configuration

The Repository Controller supports these additional flags:

args:
- --reconcilers=repositories
- --repositories.max-concurrent-reconciles=100
- --repositories.max-concurrent-syncs=50
- --repositories.health-check-frequency=5m
- --repositories.full-sync-frequency=1h
- --repositories.cache-type=CR  # or DB
- --repositories.push-drafts-to-git=false  # DB cache only: push Draft/Proposed to Git during sync

Configuration Parameters:

Cache Type:

The cache-type parameter determines how package data is stored:

• CR: Custom Resources for metadata, in-memory caching (simpler, no database required)
• DB: PostgreSQL database for metadata and content (production-grade, scalable)

Example (DB cache with draft push mode):

spec:
  template:
    spec:
      containers:
      - name: controller
        args:
        - --reconcilers=repositories
        - --repositories.cache-type=DB
        - --repositories.push-drafts-to-git=true
        env:
        # Database connection — see Cache Configuration
        - name: DB_HOST
          valueFrom:
            secretKeyRef:
              name: porch-db-config
              key: host

Tuning Guidance:

Adjust these parameters based on your deployment characteristics:

• Concurrency settings (max-concurrent-reconciles, max-concurrent-syncs):

  • Higher values increase throughput but consume more resources
  • Start with defaults and adjust based on observed CPU/memory usage
  • Monitor controller logs for reconciliation delays

• Frequency settings (health-check-frequency, full-sync-frequency):

  • More frequent checks detect issues faster but increase load
  • Less frequent checks reduce overhead but delay change detection
  • Balance based on your tolerance for sync lag vs resource usage

For detailed sync behavior and scheduling, see Repository Sync Configuration.

PackageRevision Controller Configuration

The PR Controller is enabled by adding packagerevisions to the --reconcilers flag:

args:
- --reconcilers=repositories,packagerevisions
- --packagerevisions.max-concurrent-reconciles=50
- --packagerevisions.max-concurrent-renders=20
- --packagerevisions.render-requeue-delay=2s
- --packagerevisions.repo-operation-retry-attempts=3
- --packagerevisions.max-grpc-message-size=6291456

Configuration Parameters:

Environment Variables:

Prerequisites:

The PR Controller requires:

• The Repository Controller to be running (provides the shared cache)
• The PackageRevision CRD (porch.kpt.dev/v1alpha2) to be installed in the cluster
• The function runner service to be reachable (if external KRM functions are used)

Tuning Guidance:

• Render concurrency: Controls how many packages can be rendered simultaneously. Rendering involves gRPC calls to the function runner, which is CPU and memory intensive. If the function runner is under-provisioned, reduce this limit. If you see frequent RequeueAfter from render throttling, increase it.

• Reconcile concurrency: Controls total parallel work. Source execution and lifecycle transitions are lightweight, so the bottleneck is usually rendering. A ratio of 2-3x reconciles to renders (e.g. 50 reconciles, 20 renders) works well for most clusters.

• gRPC message size: Increase this if packages contain large resource files (over 6MB total). This is uncommon for typical KRM packages.

Webhook Configuration

Both the PackageRevision and Repository webhooks run in the porch-controllers pod and provide admission-time validation. Unlike controllers which reconcile state continuously, webhooks validate operations at creation or update time and deny invalid requests immediately. This fail-closed approach prevents invalid configurations from being stored in Kubernetes etcd.

Webhook Server Flags

Example — override the certificate directory:

args:
- --cert-dir=/custom/path/to/certs

For webhook TLS certificate setup and management, see Webhook Certificate Management.

For details on webhook validation rules, see Webhook Validation Rules.