Catalog Deployment

Deploy Porch using the Nephio catalog for production environments

This guide covers deploying Porch in production environments using the Nephio catalog.

Configuration Planning

Before deploying Porch, determine which features you need.

Cache Mode Selection

Choose your cache backend based on deployment scale and requirements:

CR Cache (default): Development and small deployments (<100 repositories)
DB Cache: Production deployments requiring scale and reliability

Important

If using DB Cache, you must configure database settings for both Porch Server and Repository Controller before deployment. See Cache Configuration for complete setup instructions including database initialization.

Optional Pre-deployment Configuration

These optional features must be configured before deployment if you need them:

Porch Server

Cert-Manager Webhooks - Enable cert-manager webhook integration (requires deployment env vars)
Jaeger Tracing - Enable distributed tracing (requires deployment env vars)
Git Custom TLS - Enable custom TLS certificates for Git repositories (requires --use-git-cabundle=true arg)

Function Runner

Private Registries - Configure private container registries (requires deployment args and volume mounts)

Post-deployment Configuration

These features can be configured after deployment:

Git Authentication - Configure Porch Server authentication for private Git repositories

Note

Repository Sync configuration is currently located in the system configuration section but should be moved to a more logical location as it’s about configuring individual Repository resources, not system-wide settings.

Prerequisites

Kubernetes cluster (v1.25+)
kubectl configured for your cluster
kpt CLI tool
Cluster admin permissions

Installation Steps

1. Get the Porch Package

kpt pkg get https://github.com/nephio-project/catalog/tree/main/nephio/core/porch

2. Customize Configuration (Optional)

If you need any pre-deployment features from the Configuration Planning section above, modify the package now:

cd porch/

# Example: Configure database cache for Porch Server
kpt fn eval --image gcr.io/kpt-fn/set-annotations:v0.1 -- \
  annotations='cache-type=DB'

# Review your changes
kpt pkg tree

3. Render and Apply

# Render the package with any customizations
kpt fn render porch

# Initialize the package for lifecycle management
kpt live init porch

# Apply to your cluster
kpt live apply porch

The catalog package includes:

Multiple pre-configured FunctionConfig resources for common KRM functions (apply-replacements, set-namespace, starlark, etc.)
Pod and service templates for pod-based function execution

Verification

Check Pod Status

Verify all Porch components are running:

kubectl get pods -n porch-system

Expected output:

NAME                                 READY   STATUS    RESTARTS   AGE
function-runner-xxx-xxx              1/1     Running   0          2m
function-runner-xxx-xxx              1/1     Running   0          2m
porch-controllers-xxx-xxx            1/1     Running   0          2m
porch-server-xxx-xxx                 1/1     Running   0          2m

Verify API Resources

Confirm Porch CRDs are registered:

kubectl api-resources | grep porch

Check FunctionConfig Resources

Verify FunctionConfig resources are deployed:

kubectl get functionconfigs -n porch-fn-system

You should see several pre-configured function configurations for common KRM functions such as:

NAME                    SERVER APPLIED   FNRUNNER APPLIED   CONTROLLER APPLIED
apply-replacements      1                1                  1
apply-setters           1                1                  1
create-setters          1                1                  1
enable-gcp-services     1                1                  1
ensure-name-substring   1                1                  1
export-terraform        1                1                  1
gatekeeper              1                1                  1
...

These FunctionConfig resources define how KRM functions are executed (using pod, binary, or go executors) and streamline function configuration compared to the older ConfigMap-based approach.

Check ServiceTemplate Resources

Verify ServiceTemplate CRDs are available:

kubectl get crd servicetemplates.config.porch.kpt.dev

ServiceTemplate resources define pod and service templates for pod-based function execution.

Troubleshooting

Common Issues

Pods not starting:

kubectl describe pods -n porch-system
kubectl logs -n porch-system -l app=porch-server

CRDs not registered:

kubectl get crd | grep porch

FunctionConfig resources not applied:

Ensure FunctionConfig resources are created in the porch-fn-system namespace:

kubectl get functionconfigs -n porch-fn-system

Check if the FunctionConfig reconciler is running in function-runner and porch-server pods:

kubectl logs -n porch-system -l app=function-runner | grep -i functionconfig
kubectl logs -n porch-system -l app=porch-server | grep -i functionconfig

View FunctionConfig status to see which components have applied the configuration:

kubectl get functionconfigs -n porch-fn-system -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status}{"\n"}{end}'

Getting Help

For additional support:

Check the Porch GitHub issues
Join the Nephio community