Private Registries

Configure porch-server access to private container registries

Note

KPT functions and KRM functions are synonymous terms referring to the same containerized functions.

Configure porch-server to access private container registries for KRM functions. These flags moved from Function Runner with the pod evaluator.

Use Cases

Private registries are commonly used for:

Enterprise environments - Internal Harbor or JFrog registries
Cloud providers - GitHub Container Registry (GHCR), AWS ECR, Azure ACR
Custom functions - Organization-specific KRM functions

Default Public Registries

By default, porch-server uses public registries:

ghcr.io/kptdev/krm-functions-catalog - GitHub Container Registry for KRM functions
Other public registries as configured

Private Registry Authentication

To use private container registries for KRM functions, configure authentication in the porch-server.

1. Create Docker Configuration Secret

Create a secret using Docker configuration format:

Note

The secret must be in the same namespace as the porch-server deployment. By default, this is the porch-system namespace.

kubectl create secret generic registry-auth-secret \
  --from-file=.dockerconfigjson=/path/to/your/config.json \
  --type=kubernetes.io/dockerconfigjson \
  --namespace=porch-system

Example config.json format:

{
    "auths": {
        "https://index.docker.io/v1/": {
            "auth": "bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ="
        },
        "ghcr.io": {
            "auth": "bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ="
        }
    }
}

The auth value is base64 encoded username:password.

2. Mount Secret in porch-server

Update the porch-server deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: porch-server
  namespace: porch-system
spec:
  template:
    spec:
      containers:
      - name: porch-server
        args:
        - --enable-private-registries=true
        - --registry-auth-secret-path=/var/tmp/auth-secret/.dockerconfigjson
        - --registry-auth-secret-name=registry-auth-secret
        volumeMounts:
        - name: docker-config
          mountPath: /var/tmp/auth-secret
          readOnly: true
      volumes:
      - name: docker-config
        secret:
          secretName: registry-auth-secret

3. Configuration Arguments

Required porch-server arguments:

--enable-private-registries=true - Enable private registry functionality
--registry-auth-secret-path - Path to mounted secret (default: /var/tmp/auth-secret/.dockerconfigjson)
--registry-auth-secret-name - Name of the secret (default: auth-secret)

Note

Use dedicated subdirectories for mount paths to avoid overwriting directory permissions. For example, use /var/tmp/auth-secret instead of /var/tmp.

How It Works

When configured, the porch-server:

Replicates the registry secret to the porch-fn-system namespace
Uses it as an imagePullSecret for KRM function pods
Enables function pods to pull images from private registries

TLS Configuration for Private Registries

For registries with custom TLS certificates:

1. Create TLS Secret

apiVersion: v1
kind: Secret
metadata:
  name: registry-tls-secret
  namespace: porch-system
data:
  ca.crt: <base64-encoded-pem-certificate>
type: kubernetes.io/tls

Note

The certificate must be in PEM format and the key must be named one of the following:

ca.crt
ca.pem
cacert.pem
ca-bundle.crt
root.crt

2. Mount TLS Secret

spec:
  template:
    spec:
      containers:
      - name: porch-server
        args:
        - --enable-private-registries-tls=true
        - --tls-secret-path=/var/tmp/tls-secret/
        volumeMounts:
        - name: tls-registry-config
          mountPath: /var/tmp/tls-secret/
          readOnly: true
      volumes:
      - name: tls-registry-config
        secret:
          secretName: registry-tls-secret

3. TLS Configuration Arguments

Additional arguments for TLS:

--enable-private-registries-tls=true - Enable TLS for private registries
--tls-secret-path - Path to TLS certificate (default: /var/tmp/tls-secret/)

TLS Connection Logic

When TLS is enabled, porch-server attempts connection in this order:

Using the mounted TLS certificate
Using system intermediate certificates (for well-known CAs)
Without TLS as fallback
Returns error if all attempts fail

Warning

Ensure Kubernetes nodes are configured with the same TLS certificate information. The porch-server can pull images, but KRM function pods need node-level certificate configuration to run successfully.

Complete Example

Combining both authentication and TLS:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: porch-server
  namespace: porch-system
spec:
  template:
    spec:
      containers:
      - name: porch-server
        args:
        - --enable-private-registries=true
        - --registry-auth-secret-path=/var/tmp/auth-secret/.dockerconfigjson
        - --registry-auth-secret-name=registry-auth-secret
        - --enable-private-registries-tls=true
        - --tls-secret-path=/var/tmp/tls-secret/
        volumeMounts:
        - name: docker-config
          mountPath: /var/tmp/auth-secret
          readOnly: true
        - name: tls-registry-config
          mountPath: /var/tmp/tls-secret/
          readOnly: true
      volumes:
      - name: docker-config
        secret:
          secretName: registry-auth-secret
      - name: tls-registry-config
        secret:
          secretName: registry-tls-secret

Last modified October 7, 2026: Move podevaluator to porch-server (#1119) (c1a10c97)