Doc: review pages organization

docs/docs/configuration.md

@@ -1,16 +1,18 @@
 ---
-sidebar_position: 6
+sidebar_position: 3
 ---
 
 import CodeBlock from '@theme/CodeBlock';
 import StanzaCustom from '!!raw-loader!../../examples/stanza_custom.yaml';
 import PluginConfig from '!!raw-loader!../../examples/plugin_config.yaml';
+import StanzaS3 from '!!raw-loader!../../examples/stanza.yaml';
+import StanzaAzure from '!!raw-loader!../../examples/stanza_azure.yaml';
 
 # Configuration
 
 This pgBackRest plugin supports three levels of configuration:
 
-- **Managed configuration:** Options defined via the Stanza or
+- **Managed configuration:** Options defined via the `Stanza` or
   `PluginConfig` CRD.
 - **Environment variables:** Free-form variables that can be specified
   using `CustomEnvVars`. `CustomEnvVars` is a list of variables.
@@ -76,6 +78,29 @@ PGBACKREST_MY_CUSTOM=CNPG_ROCKS
 To run pgBackRest with parameters not directly managed by this plugin,
 the `CustomEnvVar` option can be used.
 
+## Supported repositories type (S3 and Azure)
+
+The pgBackRest plugin enables PostgreSQL backup files to be stored in:
+
+- Amazon s3
+- Microsoft Azure Blob Storage
+
+The plugin relies on the protocols that pgBackRest supports natively. To
+configure the repositories for pgBackRest, you must define a `Stanza`
+object, which establishes the link between your PostgreSQL `Cluster` and
+the repository or repositories.
+
+Below are a few examples of how to use the supported backup storage
+backend.
+
+### Amazon S3, or S3 compatible solutions
+
+<CodeBlock language="yaml">{StanzaS3}</CodeBlock>
+
+### Azure Blob Storage
+
+<CodeBlock language="yaml">{StanzaAzure}</CodeBlock>
+
 <!--
     vim: spelllang=en spell
   -->

docs/docs/contribute.md

@@ -4,6 +4,41 @@ sidebar_position: 7
 
 # Contribute
 
+## Basic info on how a CNPG plugin works
+
+Here are some basic informations about how this plugin should work:
+
+- When installing the plugin, a new deployment is created to run a Pod
+  for the controller (`pgbackrest-controller`) of our plugin in the same
+  namespace as the CNPG operator.
+
+- The CNPG operator detects the plugin when a dedicated Kubernetes
+  Service (with some specific annotations) is created.
+
+- Our specialized controller exposes the supported capabilities (at
+  least those required to manage the
+  [lifecycle](https://pkg.go.dev/github.com/cloudnative-pg/cnpg-i@v0.1.0/pkg/lifecycle)
+  of our CNPG instances) to the CNPG operator.
+
+- When initializing a new Cluster configured with our plugin, the
+  pgBackRest controller will be called by the CloudNativePG operator.
+
+- The plugin controller modifies the resources (Deployment / Pods /
+  Jobs) requested by the CNPG operator (this is done before requesting
+  the Kubernetes API), and inject some configuration if needed.
+
+  For our pgbackrest plugin, the controller inject a sidecar container
+  for `pgBackRest` within the PostgreSQL Pods. This sidecar container
+  executes a manager dedicated to `pgBackRest` (which expose the
+  required capabilities archive the WAL and backup the PostgreSQL
+  instance).
+
+- Our newly created PostgreSQL instance will call the dedicated
+  `pgBackRest` manager (on the side container) when the archive command
+  is triggered.
+
+https://github.com/cloudnative-pg/cnpg-i/blob/main/docs/protocol.md#cnpgi-wal-v1-WALCapability-RPC
+
 ## Deploy CloudNativePG on kind
 
 To contribute and test the pgBackRest plugin, a dedicated Kubernetes

docs/docs/installation.md

@@ -4,16 +4,10 @@ sidebar_position: 2
 
 # Installation
 
-To install and use this plugin, Kubernetes and CloudNativePG users should :
+## Install prod-ready version
 
-1. Install the plugin by applying the manifest located in the 
-`kubernetes` directory :
-
-``` console
-kubectl apply -k ./kubernetes/prod
-```
-
-Users can also use the manifest file from GitHub:
+This plugin can be installed and used by Kubernetes and CloudNativePG
+users via the manifest located at the root of the repository.
 
 ``` console
 $ kubectl apply -f \
@@ -22,71 +16,76 @@ $ kubectl apply -f \
 
 This will install the plugin in the same `Namespace` as the operator.
 
-# Verifications
+### Verifications
 
-The installation can be verified by checking the presence and status
-of the `pgbackrest-controller` deployment in the namespace used by the
+The installation can be verified by checking the presence and status of
+the `pgbackrest-controller` deployment in the namespace used by the
 CloudNativePG operator (e.g., `cnpg-system`).
 
-```console
+``` console
 kubectl get pod -n cnpg-system
 NAME                                       READY   STATUS    RESTARTS   AGE
 cnpg-controller-manager-65bfdb64c9-hwvpd   1/1     Running   0          9m4s
 pgbackrest-controller-fc9f4d5f4-5w6wt      1/1     Running   0          15s
 ```
 
-And also by confirming
-that the `Custom Resource Definition` `stanza.pgbackrest.dalibo.com`
-is installed.
+And also by confirming that the `Custom Resource Definition`
+`stanza.pgbackrest.dalibo.com` is installed.
 
-```console
+``` console
 kubectl api-resources --api-group pgbackrest.dalibo.com
 NAME      SHORTNAMES   APIVERSION                 NAMESPACED   KIND
 stanzas                pgbackrest.dalibo.com/v1   true         Stanza
 ```
 
-# Testing versions
+## Testing versions
 
-To use the latest testing or unstable version of this plugin,
-apply the `test` kustomize overlay. It is configured to pull
-the latest alpha/beta images from Docker Hub. You can simply run :
-```console
+To use the latest testing or unstable version of this plugin, apply the
+`test` kustomize overlay. It is configured to pull the latest alpha/beta
+images from Docker Hub. You can simply run :
+
+``` console
 kubectl apply -k kubernetes/test
 ```
 
 ## Dev version
 
-1. Build locally the Docker images and load them to a registry that is accessible 
-by your Kubernetes cluster.
+1.  Build locally the Docker images and load them to a registry that is
+    accessible by your Kubernetes cluster.
 
 You can build them locally with the command :
-```console
+
+``` console
 make build-images
 ```
 
 It will execute the appropriate `docker build` commands.
 
-2. Install the plugin by applying the manifest located in the 
-`kubernetes` directory :
+2.  Install the plugin by applying the manifest located in the
+    `kubernetes` directory :
 
 ``` console
 kubectl apply -k ./kubernetes/dev
 ```
 
 :::note
-Kustomize layers and overlays are available in the `kubernetes` directory.
-You can add your own customisation to patch the resources provided by default.
+
+Kustomize layers and overlays are available in the `kubernetes`
+directory. You can add your own customisation to patch the resources
+provided by default.
+
 :::
 
-# Customisation
+## Customisation
 
-The image used by the CloudNativePG instance sidecar container can be customised 
-by adding the `SIDECAR_IMAGE` environment variable to the pgbackrest plugin
-controller container.
+The image used by the CloudNativePG instance sidecar container can be
+customised by adding the `SIDECAR_IMAGE` environment variable to the
+pgbackrest plugin controller container.
 
-For example, this patch can be used to add the `SIDECAR_IMAGE` variable :
+For example, this patch can be used to add the `SIDECAR_IMAGE` variable
+:
 
-```yaml
+``` yaml
 apiVersion: apps/v1
 kind: Deployment
 metadata: