From ed4a3cc4f67c6b77ceb175613eefe60e659940a2 Mon Sep 17 00:00:00 2001 From: Chad Ferman Date: Tue, 31 Mar 2026 18:50:28 -0500 Subject: [PATCH] docs: Fix CloudNativePG operator deployment issues MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fix issues reported by @sabre1041 during operator deployment: ## Issues Fixed ### 1. Incorrect Namespace References - Changed all references from `cnpg-system` to `postgresql-operator-system` - The EDB operator creates `postgresql-operator-system`, not `cnpg-system` - Updated in: - docs/quick-start-guide.md (OpenShift and CRC sections) - Expected output examples - Troubleshooting section ### 2. Missing Server-Side Apply Flag - Added `--server-side --force-conflicts` to all operator deployments - Required because CRDs are too large for client-side apply - Updated in: - docs/quick-start-guide.md (OpenShift Quick Start) - docs/quick-start-guide.md (CRC Quick Start) - docs/install-kubernetes-manual.md (Manual install) - Added explanatory notes about why this flag is required ### 3. Missing Pull Secret Documentation - Added pull secret creation step to OpenShift Quick Start - Added pull secret creation (commented) to CRC Quick Start - Documented when pull secret is required vs optional - Linked to EDB registry pull secret example ## Changes by File ### docs/quick-start-guide.md - **OpenShift Quick Start:** - Added Step 2: Create EDB Registry Pull Secret (optional) - Renumbered subsequent steps (2→3, 3→4, 4→5, 5→6, 6→7) - Changed `oc apply` to `oc apply --server-side --force-conflicts` - Fixed namespace from `cnpg-system` to `postgresql-operator-system` - Updated expected output to show correct namespace and deployment names - **CRC Quick Start:** - Added commented pull secret creation - Changed `oc apply` to `oc apply --server-side --force-conflicts` - Fixed namespace from `cnpg-system` to `postgresql-operator-system` - **Troubleshooting:** - Fixed operator logs command to use `postgresql-operator-system` ### docs/install-kubernetes-manual.md - Changed direct `oc apply` to download + server-side apply - Added wait command for operator readiness - Added explanatory note about server-side apply requirement ## Testing - ✅ Verified no remaining `cnpg-system` references in docs/ - ✅ All operator deployment commands now use server-side apply - ✅ Pull secret documentation added where needed - ✅ Step numbering corrected in quick-start guide ## Fixes Resolves deployment issues reported by @sabre1041: - CRDs too big → Fixed with --server-side --force-conflicts - Wrong namespace → Fixed all cnpg-system → postgresql-operator-system - Missing pull secret → Added documentation with examples Co-Authored-By: Claude Sonnet 4.5 --- docs/install-kubernetes-manual.md | 15 +++++++-- docs/quick-start-guide.md | 56 ++++++++++++++++++++++--------- 2 files changed, 53 insertions(+), 18 deletions(-) diff --git a/docs/install-kubernetes-manual.md b/docs/install-kubernetes-manual.md index 292bc6f..77d8dce 100644 --- a/docs/install-kubernetes-manual.md +++ b/docs/install-kubernetes-manual.md @@ -31,10 +31,21 @@ For **Postgres on hosts** (VMs / bare metal), use **[TPA](install-tpa.md)** — # Create namespace oc create namespace postgresql-operator-system -# Install operator via OperatorHub (OpenShift) or Helm -oc apply -f https://get.enterprisedb.io/cnp/postgresql-operator-1.23.1.yaml +# Download and install operator with server-side apply (required for large CRDs) +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 + +# Wait for operator to be ready +oc wait --for=condition=Available deployment \ + -l app.kubernetes.io/name=cloudnativepg \ + -n postgresql-operator-system \ + --timeout=300s ``` +**Note:** The `--server-side --force-conflicts` flags are required because the operator CRDs are large and may exceed annotation size limits in client-side apply. + ## 2. Deploy a PostgreSQL cluster (manual) ### Registry pull secret (EDB images) diff --git a/docs/quick-start-guide.md b/docs/quick-start-guide.md index 540e3fe..f46f111 100644 --- a/docs/quick-start-guide.md +++ b/docs/quick-start-guide.md @@ -92,28 +92,45 @@ git clone https://github.com/Red-Hat-EnterpriseDB-Testing/EDB_Testing.git cd EDB_Testing ``` -### Step 2: Deploy EDB Postgres Operator (2 minutes) +### Step 2: (Optional) Create EDB Registry Pull Secret + +**Only required if using EDB subscription images from `docker.enterprisedb.com`** + +```bash +# Create pull secret for EDB registry +oc create secret docker-registry edb-pull-secret \ + --docker-server=docker.enterprisedb.com \ + --docker-username='YOUR_EDB_SUBSCRIPTION_USER' \ + --docker-password='YOUR_EDB_TOKEN_OR_PASSWORD' \ + -n edb-postgres +``` + +**Note:** This quick start uses the community CloudNativePG operator image, so this step is optional. However, if you plan to use EDB Postgres Advanced images (see [`db-deploy/sample-cluster/base/cluster-edb-registry.yaml`](../db-deploy/sample-cluster/base/cluster-edb-registry.yaml)), you'll need this pull secret. + +### Step 3: Deploy EDB Postgres Operator (2 minutes) ```bash -# Deploy CloudNativePG operator -oc apply -k db-deploy/operator/ +# Deploy CloudNativePG operator with server-side apply for large CRDs +oc apply --server-side --force-conflicts -k db-deploy/operator/ # Wait for operator to be ready oc wait --for=condition=Ready pod \ -l app.kubernetes.io/name=cloudnativepg \ - -n cnpg-system \ + -n postgresql-operator-system \ --timeout=120s ``` **Expected output:** ``` -namespace/cnpg-system created -customresourcedefinition.apiextensions.k8s.io/clusters.postgresql.cnpg.io created -deployment.apps/cnpg-controller-manager created -pod/cnpg-controller-manager-xxxxxxxxx-xxxxx condition met +namespace/postgresql-operator-system created +customresourcedefinition.apiextensions.k8s.io/clusters.postgresql.k8s.enterprisedb.io created +deployment.apps/postgresql-operator-controller-manager created +pod/postgresql-operator-controller-manager-xxxxxxxxx-xxxxx condition met ``` -### Step 3: Deploy PostgreSQL Cluster (5 minutes) +**Note:** The `--server-side --force-conflicts` flags are required because the CRDs are large and may exceed annotation size limits. + +### Step 4: Deploy PostgreSQL Cluster (5 minutes) ```bash # Create namespace and cluster @@ -133,7 +150,7 @@ postgresql 3m 2 2 Cluster in healthy state postgresql-1 Press `Ctrl+C` when `READY` shows `2`. -### Step 4: Verify PostgreSQL (2 minutes) +### Step 5: Verify PostgreSQL (2 minutes) ```bash # Check cluster status @@ -146,7 +163,7 @@ oc exec -n edb-postgres postgresql-1 -- \ **Expected:** PostgreSQL version output showing EDB Postgres Advanced. -### Step 5: Deploy AAP (5 minutes) +### Step 6: Deploy AAP (5 minutes) ```bash # Set required environment variables @@ -168,7 +185,7 @@ cd aap-deploy/openshift oc get pods -n ansible-automation-platform -w ``` -### Step 6: Access AAP (1 minute) +### Step 7: Access AAP (1 minute) ```bash # Get AAP route @@ -342,13 +359,20 @@ cd EDB_Testing eval $(crc oc-env) oc login -u kubeadmin https://api.crc.testing:6443 -# Deploy operator -oc apply -k db-deploy/operator/ +# (Optional) Create EDB pull secret if using EDB images +# oc create secret docker-registry edb-pull-secret \ +# --docker-server=docker.enterprisedb.com \ +# --docker-username='YOUR_EDB_SUBSCRIPTION_USER' \ +# --docker-password='YOUR_EDB_TOKEN_OR_PASSWORD' \ +# -n edb-postgres + +# Deploy operator with server-side apply for large CRDs +oc apply --server-side --force-conflicts -k db-deploy/operator/ # Wait for operator oc wait --for=condition=Ready pod \ -l app.kubernetes.io/name=cloudnativepg \ - -n cnpg-system \ + -n postgresql-operator-system \ --timeout=300s # Deploy cluster (use CRC storage class) @@ -677,7 +701,7 @@ Before going to production, complete: oc describe pod postgresql-1 -n edb-postgres # Check operator logs -oc logs -n cnpg-system -l app.kubernetes.io/name=cloudnativepg --tail=100 +oc logs -n postgresql-operator-system -l app.kubernetes.io/name=cloudnativepg --tail=100 ``` **Common causes:**