diff --git a/docs/public/installation.md b/docs/public/installation.md index c84c7564..b2f19879 100644 --- a/docs/public/installation.md +++ b/docs/public/installation.md @@ -33,7 +33,7 @@ Both charts can be installed separately, but `Postgres` should be always initial The prerequisites to deploy the Postgres Service are as follows: * The project or namespace should be created. -* The Custom Resource Definition (CRD) should be created by the cloud administrator, if deploy user do not have rights for CRD creation role. +* The Custom Resource Definition (CRD) should be created by the cloud administrator, if deploy user do not have rights for CRD creation role. See [CRD Installation Approaches](#crd-installation-approaches) for available options. * If Dynamic Volume Provisioning is not available, all the persistence volumes for Patroni and Backup Daemon should be created manually, and NodeSelectors (that selects particular nodes) should be specified explicitly (or NodeAffinity are set on PVs). * In case of using `cinder` as Dynamic Volume Provisioning, you have to set `patroni.securityContext.fsGroupChangePolicy` as `OnRootMismatch` in deploy parameter. * In case of using `cinder` as Dynamic Volume Provisioning, you have to set both `backupDaemon.securityContext.runAsUser` and `backupDaemon.securityContext.fsGroup` in deploy parameter. @@ -772,6 +772,36 @@ Patroni Core Operator allows configuration of TLS for PostgreSQL. By default, re # Installation +## CRD Installation Approaches + +CRDs (`PatroniCore` and `PostgresService`) are cluster-scoped resources and require cluster-wide permissions to install. There are two approaches depending on the deployment environment. + +### Dedicated CRDs Application (Recommended) + +In standard environments where cluster-wide permissions are available, CRDs are managed as a **separate application** that is installed before the main microservice charts. This is the recommended approach because it makes CRD lifecycle management explicit and independent of the operator deployment. + +**Deployment order:** + +1. Install/sync the dedicated CRDs application first: + + ```bash + kubectl create -f ./operator/charts/patroni-core/crds/netcracker.com_patronicores.yaml + kubectl create -f ./operator/charts/patroni-services/crds/netcracker.com_patroniservices.yaml + ``` + +2. Wait for the CRD application to reach a synced/healthy state before proceeding. + +3. Install the main microservice applications (`patroni-core`, `patroni-services`). These deployments rely on the CRDs being pre-installed and **must not** attempt to install CRDs themselves. + +### Restricted Environments (No Cluster-Wide Permissions) + +In restricted environments where the deployment user does **not** have cluster-wide permissions (e.g., no rights to create `ClusterRole`, `ClusterRoleBinding`, or CRD resources), the dedicated CRDs application **must not be installed**. Instead: + +- The CRDs must be pre-installed by a cluster administrator out-of-band. +- Set the `DISABLE_CRD=true` flag on the main microservice application to prevent it from attempting CRD installation. + +> **Deprecated:** `DISABLE_CRD=true` is deprecated for all environments where cluster-wide permissions are available. Use the dedicated CRDs application approach instead. The flag is retained only for restricted environments where cluster-wide permissions are unavailable. + ### Helm For pure installation, please, follow [Quick Start Guide](quickstart.md). diff --git a/docs/public/quickstart.md b/docs/public/quickstart.md index c0cb7822..00f0e05b 100644 --- a/docs/public/quickstart.md +++ b/docs/public/quickstart.md @@ -59,15 +59,31 @@ For `backupDaemon.storage` section point your PV the same way, but in a single c When setup is complete, we can proceed to install the postgres operator. -Manually install CRD for Patroni-Core: +### CRD Installation + +CRDs are cluster-scoped resources managed as a **dedicated application** that must be installed and synced before the main operator charts. The main microservice deployments rely on pre-installed CRDs and must not attempt to install them independently. + +Install the CRD application first: + ``` kubectl create -f ./operator/charts/patroni-core/crds/netcracker.com_patronicores.yaml +kubectl create -f ./operator/charts/patroni-services/crds/netcracker.com_patroniservices.yaml ``` -Manually install CRD for Postgres-Services + +Wait for the CRDs to be registered before proceeding: + ``` -kubectl create -f ./operator/charts/patroni-services/crds/netcracker.com_patroniservices.yaml +kubectl get crd netcracker.com_patronicores.yaml patroniservices.netcracker.com ``` +#### Restricted Environments + +In environments where the deployment user lacks cluster-wide permissions, the dedicated CRDs application must **not** be installed. Instead, a cluster administrator must pre-install the CRDs out-of-band, and the `DISABLE_CRD=true` flag must be set on the main microservice application. + +> **Note:** `DISABLE_CRD=true` is deprecated for environments with cluster-wide permissions. Use the dedicated CRDs application approach in all other cases. + +### Install Patroni-Core Operator + Install Patroni-Core Operator via Helm by following command: ``` helm install --namespace=postgres --create-namespace -f ./operator/charts/patroni-core/patroni-core-quickstart-sample.yaml patroni-core ./operator/charts/patroni-core