Installing Porch

Install guide for the Porch system on a Kubernetes cluster.

Deploying Porch on a cluster

Create a new directory for the kpt package and navigate into it:

mkdir porch-1.5.7 && cd porch-1.5.7

Download the latest Porch kpt package blueprint:

curl -LO "https://github.com/kptdev/porch/releases/download/v1.5.7/porch-kpt-package.tar.gz"

Extract the Porch kpt package contents:

tar -xzf porch-kpt-package.tar.gz

Initialize and apply the Porch kpt package:

kpt live init && kpt live apply

Verify Installation

Check that Porch components are running:

kubectl get all -n porch-system

A healthy Porch installation should show:

NAME                                   READY   STATUS    RESTARTS   AGE
pod/function-runner-567ddc76d-7k8sj    1/1     Running   0          4m3s
pod/function-runner-567ddc76d-x75lv    1/1     Running   0          4m3s
pod/porch-controllers-d8dfccb4-8lc6j   1/1     Running   0          4m3s
pod/porch-server-7dc5d7cd4f-smhf5      1/1     Running   0          4m3s

NAME                      TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)            AGE
service/api               ClusterIP   10.96.108.221   <none>        443/TCP,8443/TCP   4m3s
service/function-runner   ClusterIP   10.96.237.108   <none>        9445/TCP           4m3s

NAME                                READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/function-runner     2/2     2            2           4m3s
deployment.apps/porch-controllers   1/1     1            1           4m3s
deployment.apps/porch-server        1/1     1            1           4m3s

NAME                                         DESIRED   CURRENT   READY   AGE
replicaset.apps/function-runner-567ddc76d    2         2         2       4m3s
replicaset.apps/porch-controllers-d8dfccb4   1         1         1       4m3s
replicaset.apps/porch-server-7dc5d7cd4f      1         1         1       4m3s

Verify the Porch API is accessible:

kubectl api-resources | grep porch

You should see Porch API resources:

functionconfigs                                  config.porch.kpt.dev/v1alpha1     true         FunctionConfig
packagerevs                                      config.porch.kpt.dev/v1alpha1     true         PackageRev
packagevariants                                  config.porch.kpt.dev/v1alpha1     true         PackageVariant
packagevariantsets                               config.porch.kpt.dev/v1alpha2     true         PackageVariantSet
repositories                                     config.porch.kpt.dev/v1alpha1     true         Repository
servicetemplates                                 config.porch.kpt.dev/v1alpha1     true         ServiceTemplate
packagerevisionresources                         porch.kpt.dev/v1alpha1            true         PackageRevisionResources
packagerevisions                                 porch.kpt.dev/v1alpha1            true         PackageRevision
packages                                         porch.kpt.dev/v1alpha1            true         PorchPackage

Verify that FunctionConfig resources were deployed into the function-pod namespace (default porch-fn-system, configured on the function-runner with --pod-namespace).

kubectl get functionconfigs -n porch-fn-system

A healthy install shows one FunctionConfig per bundled catalog function (apply-replacements, set-namespace, starlark, kubeconform, and others). The Server Applied, FnRunner Applied, and Controller Applied columns are the generations each component has loaded; they should match the resource generation when the spec is in sync.

These FunctionConfig objects replace the older static config-file / ConfigMap approach. They tell porch-server, function-runner, and porch-controllers which executor (pod, binary, or Go) to use for each function image. See Function Configuration for the spec and Pod Templates for the PodTemplate and ServiceTemplate used by the pod executor.

Troubleshooting

Pods not starting

If pods are in Pending or ImagePullBackOff state:

kubectl describe pod -n porch-system <pod-name>

Common causes:

  • No internet access: Cluster cannot pull images from GitHub Container Registry. Pre-pull images or use a local registry.
  • Insufficient resources: Cluster doesn’t have enough CPU/memory. Check node resources with kubectl top nodes.
  • Image pull secrets: If using a private registry, ensure image pull secrets are configured.

kpt live apply fails

If kpt live apply fails with errors:

“resource mapping not found”: CRDs may not be installed yet. Wait a few seconds and retry:

kpt live apply

“context deadline exceeded”: Cluster is slow to respond. Increase timeout or check cluster health:

kubectl get nodes
kubectl get pods -A

API resources not appearing

If kubectl api-resources | grep porch shows nothing:

  1. Check porch-server pod logs:

    kubectl logs -n porch-system deployment/porch-server

  2. Verify API service registration:

    kubectl get apiservice | grep porch

  3. Check aggregated API server connectivity:

    kubectl get apiservice v1alpha1.porch.kpt.dev -o yaml

Function runner issues

If function execution fails:

  1. Check function-runner logs:

    kubectl logs -n porch-system deployment/function-runner

  2. Verify function-runner service:

    kubectl get svc -n porch-system function-runner

Next Steps

Porch is now installed. To start using it:

  1. See Tutorials and How-Tos to learn how to:

    • Register a Git repository
    • Create and manage packages

  2. If you need to remove Porch, see Uninstalling Porch.

Last modified August 31, 2026: address other copilot comments (0793c641)