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/nephio-project/porch/releases/download/v1.5.7/porch_blueprint.tar.gz"

Extract the Porch kpt package contents:

tar -xzf porch_blueprint.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 are deployed:

kubectl get functionconfigs -n porch-fn-system

You should see several pre-configured FunctionConfig resources for common KRM functions:

NAME                             SERVER APPLIED   FNRUNNER APPLIED
apply-replacements               1                1
apply-setters                    1                1
create-setters                   1                1
ensure-name-substring            1                1
gatekeeper                       1                1
kubeconform                      1                1
search-replace                   1                1
set-annotations                  1                1
set-enforcement-action           1                1
set-image                        1                1
set-labels                       1                1
set-namespace                    1                1
starlark                         1                1
upsert-resource                  1                1
enable-gcp-services              1                1
export-terraform                 1                1
generate-folders                 1                1
remove-local-config-resources    1                1
set-project-id                   1                1

About these new resources:

FunctionConfig: Defines how KRM functions are executed (pod, binary, or go executors) and replaces the older ConfigMap-based configuration approach. The function-runner and porch-server both include embedded FunctionConfig reconcilers that populate an internal cache used to determine which executor to use and with what configuration.
ServiceTemplate: Defines pod and service templates for pod-based function execution. These templates are referenced by FunctionConfig resources that use 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:

Check porch-server pod logs:

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

Verify API service registration:
```
kubectl get apiservice | grep porch
```

Check aggregated API server connectivity:

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

Function runner issues

If function execution fails:

Check function-runner logs:

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

Verify function-runner service:

kubectl get svc -n porch-system function-runner

Next Steps

Porch is now installed. To start using it:

See Tutorials and How-Tos to learn how to:
- Register a Git repository
- Create and manage packages
If you need to remove Porch, see Uninstalling Porch.