docs: Fix CloudNativePG operator deployment issues

[chadmf]

Summary

Fix operator deployment issues reported by @sabre1041 during testing:

1. ✅ CRDs too large for client-side apply
2. ✅ Incorrect namespace references (cnpg-system vs postgresql-operator-system)
3. ✅ Missing pull secret creation documentation

Issues Reported by @sabre1041

Issue 1: CRDs Too Big

• Problem: "needed to use server side apply to get around it"
• Root cause: Operator CRDs exceed annotation size limits for client-side apply
• Fix: Added --server-side --force-conflicts flags to all deployment commands

Issue 2: Wrong Namespace

• Problem: "the namespace created is postgresql-operator-system and not cnpg-system as the guide shares"
• Root cause: Documentation referenced community CloudNativePG namespace, but EDB operator creates different namespace
• Fix: Changed all references from cnpg-system to postgresql-operator-system

Issue 3: Missing Pull Secret

• Problem: "also need a step for creating the pull secret"
• Root cause: Pull secret creation not documented in quick start guides
• Fix: Added pull secret creation steps with examples

Changes Made

docs/quick-start-guide.md

OpenShift Quick Start (15 min):

• Added Step 2: Create EDB Registry Pull Secret (optional)
• Renumbered subsequent steps
• Changed: oc apply -k → oc apply --server-side --force-conflicts -k
• Fixed namespace: cnpg-system → postgresql-operator-system
• Updated expected output to show correct resource names
• Added note explaining why server-side apply is required

CRC Quick Start (30 min):

• Added commented pull secret creation example
• Changed: oc apply -k → oc apply --server-side --force-conflicts -k
• Fixed namespace: cnpg-system → postgresql-operator-system

Troubleshooting Section:

• Fixed operator logs command to use correct namespace

docs/install-kubernetes-manual.md

Operator Installation:

• Changed from direct oc apply to download + server-side apply
• Added wait command for operator readiness
• Added explanatory note about server-side apply requirement

# Before
oc apply -f https://get.enterprisedb.io/cnp/postgresql-operator-1.23.1.yaml

# After
curl -sL -o /tmp/edb-cnp-operator.yaml \
  "https://get.enterprisedb.io/cnp/postgresql-operator-1.23.1.yaml"
oc apply --server-side --force-conflicts -f /tmp/edb-cnp-operator.yaml

Technical Details

Why Server-Side Apply?

The CloudNativePG CRDs contain extensive schemas that result in very large manifests. When using client-side apply, kubectl/oc stores the entire manifest in a kubectl.kubernetes.io/last-applied-configuration annotation, which can exceed Kubernetes' annotation size limits (~256KB).

Server-side apply:

• Stores field ownership on the server, not in annotations
• Handles large CRDs without size limits
• Required for CloudNativePG operator deployment

Namespace Naming

The EDB operator manifest creates:

• Namespace: postgresql-operator-system
• Deployment: postgresql-operator-controller-manager
• CRD Group: postgresql.k8s.enterprisedb.io

This differs from the community CloudNativePG operator which uses:

• Namespace: cnpg-system
• Deployment: cnpg-controller-manager
• CRD Group: postgresql.cnpg.io

Pull Secret Requirements

Pull secret is needed ONLY when using EDB subscription images:

• Required for: docker.enterprisedb.com/edb/edb-postgres-advanced:*
• Not required for: Community CloudNativePG images
• Location: Must be in the same namespace as the PostgreSQL cluster (e.g., edb-postgres)

Testing

Verification

• ✅ No remaining cnpg-system references in documentation
• ✅ All operator deployments use server-side apply
• ✅ Pull secret documented in appropriate sections
• ✅ Step numbering corrected
• ✅ Expected outputs updated

Manual Testing Recommended

Before merging, recommend testing on a fresh cluster:

# Should work without annotation size errors
oc apply --server-side --force-conflicts -k db-deploy/operator/

# Should create postgresql-operator-system namespace
oc get namespace postgresql-operator-system

# Should show operator pod running
oc get pods -n postgresql-operator-system

Documentation Impact

Files modified: 2

• docs/quick-start-guide.md (+35 lines, -12 lines)
• docs/install-kubernetes-manual.md (+16 lines, -6 lines)

Sections updated:

• Quick Start: OpenShift (15 min)
• Quick Start: CRC (30 min)
• Manual Installation Guide
• Troubleshooting section

Credit

Issues reported and tested by: @sabre1041

Thank you for the detailed feedback! These fixes should resolve all three deployment issues.

Checklist

• Fixed CRD deployment with server-side apply
• Fixed namespace references (cnpg-system → postgresql-operator-system)
• Added pull secret documentation
• Updated expected outputs
• Added explanatory notes
• Verified no remaining incorrect references
• Commit message follows guidelines

---

Ready to merge - Fixes critical operator deployment issues preventing successful installation.

cc: @sabre1041