Deploying Pulp on Kubernetes with the operator

This guide deploys Pulp on Kubernetes with the official operator: you install the controller with Helm, then describe the instance in a Pulp custom resource, and the operator provisions the whole stack (API, content, workers, PostgreSQL, Redis, reverse proxy). Intended audience: platform teams that want a declarative, scalable artifact manager. Prerequisites: a Kubernetes cluster, kubectl and helm. You will see the installation with the right versions pinned, the Pulp resource, access to the instance, and the PostgreSQL version setting that conditions both startup and backup.

On Kubernetes, you do not install Pulp by hand: you install the Pulp Operator, a controller that watches Pulp resources and reconciles the cluster to match them. This is the operator model, declarative and self-healing.

What you will learn

• Install the Pulp Operator with Helm, pinning the right versions.
• Describe an instance with a Pulp custom resource.
• Access the API and retrieve the admin password.
• Choose the PostgreSQL version that is compatible with backup.

Prerequisites

• A working Kubernetes cluster and kubectl configured.
• Helm 3+ installed.
• An available StorageClass. On a single-node cluster (k3d, Minikube), the local-path class in ReadWriteOnce is enough.

Shared storage in multi-node production

The api, content and worker components share the same artifact volume. On a multi-node cluster, these pods land on different nodes: a ReadWriteOnce volume is no longer enough. Plan for ReadWriteMany storage (NFS, CephFS) or, better, S3 object storage configured in the Pulp resource. Local ReadWriteOnce is only valid for a single-node lab.

Installing the operator

The operator is deployed through its Helm chart. It installs the controller and the custom resource definitions (pulps, pulpbackups, pulprestores).

One point deserves to be made upfront: the published Helm chart pins old default versions (operator 1.3 and PostgreSQL 13). But pulpcore requires PostgreSQL 14 or later. So you install by overriding the operator image (latest version, here 2.0) and the PostgreSQL image (version 15).

1. Add the Helm repository and create a namespace:

   helm repo add pulp-operator https://github.com/pulp/pulp-k8s-resources/raw/main/helm-charts/ --force-update
   kubectl create namespace pulp

2. Install the operator with the versions pinned:

   helm -n pulp install pulp pulp-operator/pulp-operator \
     --set image=quay.io/pulp/pulp-operator:v2.0.0 \
     --set operator.relatedImages.postgres=docker.io/library/postgres:15

3. Check that the controller is running:

   kubectl -n pulp rollout status deploy/pulp-operator-controller-manager
   kubectl get crd | grep pulpproject

   The three CRDs pulps, pulpbackups and pulprestores must appear: the operator is ready to receive a Pulp resource.

Why PostgreSQL 15 specifically?

The choice of PostgreSQL 15 is not arbitrary. The operator's backup tooling ships a pg_dump of a fixed version (15 in operator 2.0), and a pg_dump cannot dump a server of a higher version. By choosing 15 for the database, you satisfy both pulpcore (which wants 14 or later) and the backup tool. A database on 16 would start, but PulpBackup would fail.

Deploying Pulp with a custom resource

The instance is described in a Pulp object. The operator reads this resource and creates the matching deployments, services, secrets and volumes.

pulp.yaml

apiVersion: repo-manager.pulpproject.org/v1
kind: Pulp
metadata:
  name: pulp
  namespace: pulp
spec:
  image_version: stable
  ingress_type: nodeport
  api:
    replicas: 1
  content:
    replicas: 1
  worker:
    replicas: 1
  file_storage_access_mode: "ReadWriteOnce"
  file_storage_size: "10Gi"
  file_storage_storage_class: local-path
  database:
    postgres_storage_class: local-path
    postgres_image: docker.io/library/postgres:15

kubectl apply -f pulp.yaml

Two settings in the database section are decisive:

• postgres_storage_class is mandatory. Without it, the operator stops with the error could not find any storage definition for Database.
• postgres_image: postgres:15 aligns the database with the same version as the backup tooling (see the box above). Keep this value consistent with the --set operator.relatedImages.postgres of the installation.

Changing the PostgreSQL major version

If you have already deployed with another major version, changing the image is not enough: existing data is incompatible between major versions. Delete the Pulp resource and the database PVC before redeploying, otherwise PostgreSQL refuses to start on a directory initialized by another version.

Following the deployment and connecting

The operator provisions the components in order: database, migrations, content, API, workers, reverse proxy. The first deployment downloads large images, so allow a few minutes.

1. Wait for the pods to be ready:

   kubectl -n pulp get pods -w

   You should see pulp-database-0, pulp-api, pulp-content and pulp-worker as Running, and the migration and reset-admin-password jobs as Completed.

2. Retrieve the admin password, automatically generated in a secret:

   kubectl -n pulp get secret pulp-admin-password \
     -o jsonpath='{.data.password}' | base64 -d

3. Test the API. The pulp-web-svc service (here in NodePort) exposes the instance; for a quick test, a port-forward is enough:

   kubectl -n pulp port-forward svc/pulp-api-svc 24817:24817 &
   curl -s http://localhost:24817/pulp/api/v3/status/ | head

   A 200 response listing the components (core, file, container...) confirms that the instance is operational.

Exposing the instance properly

ingress_type: nodeport is fine for testing. In production, switch to ingress_type: ingress (or route on OpenShift) with a host name and a TLS certificate, as for the container installation. The parameter equivalent to CONTENT_ORIGIN is handled by the operator from this host. See Installing Pulp for the reasoning on HTTPS exposure.

Troubleshooting

Symptom	Cause	Solution
Operator stuck, could not find any storage definition for Database	postgres_storage_class missing	Add it under database: in the Pulp resource
pulp-api in CrashLoopBackOff, log PostgreSQL 14 or later is required	PostgreSQL 13 image, the chart default	Pin postgres:15 at installation and in the CR
pulp-database in CrashLoop, data directory ... version X ... not compatible	Leftover PVC from another major version	Delete the Pulp resource and the PVC, redeploy
PulpBackup fails, Failed to run pg_dump	Database on 16 against a pg_dump 15	Use PostgreSQL 15 for the database
api/worker pods Pending on volume	ReadWriteOnce on a multi-node cluster	Switch to ReadWriteMany or to S3 object storage

Swipe to see more

Key takeaways

• On Kubernetes, Pulp is deployed through the Pulp Operator and a declarative Pulp custom resource.
• The Helm chart pins old versions: override the operator image (2.0) and PostgreSQL (15) at installation.
• The operator provisions the whole stack: API, content, workers, PostgreSQL, Redis, reverse proxy.
• postgres_storage_class is mandatory; PostgreSQL 15 satisfies pulpcore and the backup tool.
• In multi-node production, artifact storage must be ReadWriteMany or S3, never local ReadWriteOnce.

Knowledge check

Six questions on what the operator provisions, what it does not take off your hands, and the storage access mode that decides whether the instance holds on several nodes.

Knowledge check

Check what you have learned with this interactive quiz

6 questions

6 min

70% to pass

How it works

• The timer starts when you click Start
• Multiple choice, true/false and short answer questions
• You can move between questions
• Detailed results are shown at the end

Start the quiz

Starts the quiz and the timer

×

See in the glossary →