docs: documentation overhaul (#22)

Define the scope of the project in the README and explain how the users
can run the plugin. Merge the details of the implementation in a single,
separate markdown file.

Signed-off-by: Francesco Canovai <francesco.canovai@enterprisedb.com>
Signed-off-by: Jaime Silvela <jaime.silvela@enterprisedb.com>
Signed-off-by: Niccolò Fei <niccolo.fei@enterprisedb.com>
Co-authored-by: Jaime Silvela <jaime.silvela@enterprisedb.com>
Co-authored-by: Niccolò Fei <niccolo.fei@enterprisedb.com>

Author: 3 people

.spellcheck.yaml

@@ -10,6 +10,15 @@ matrix:
       lang: en
       d: en_US
     pipeline:
+      - pyspelling.filters.context:
+          context_visible_first: true
+          delimiters:
+            # Ignore multiline content between fences (fences can have 3 or more back ticks)
+            # ```
+            # content
+            # ```
+            - open: '(?s)^(?P<open> *`{3,})'
+              close: '^(?P=open)$'
       - pyspelling.filters.markdown:
       - pyspelling.filters.html:
           comments: false

.wordlist.txt

@@ -1,8 +1,14 @@
 ClusterLifecycle
 CloudNativePG
+cloudnative
+cnpg
 CNPG
+CNPG's
 finalizers
+github
 GRPC
+https
+kubectl
 kubernetes
 Kubernetes
 lifecycle
@@ -14,12 +20,15 @@ OperatorValidateClusterChangeResult
 OperatorValidateClusterCreateRequest
 OperatorValidateClusterCreateResult
 pluginhelper
+proto
 Postgres
 reconcilers
 rpc
 struct
+TLS
 ValidateClusterChange
 ValidateClusterCreate
 ValidateCreate
 webhook
 webhooks
+yaml

README.md

@@ -1,10 +1,64 @@
-# CNPG-I-EXAMPLE
+# CNPG-I Hello World Plugin
 
-A "hello world" example implementation of the
-[CloudNativePG](https://github.com/cloudnative-pg/cloudnative-pg/)
-plugin interface [CNPG-I](https://github.com/cloudnative-pg/cnpg-i).
+A [CNPG-I](https://github.com/cloudnative-pg/cnpg-i) plugin to add labels and
+annotations
+to [CloudNativePG](https://github.com/cloudnative-pg/cloudnative-pg/) clusters.
 
-- [Concepts](doc/concepts.md)
-- [Workflow](doc/workflow.md)
+This project serves as an introductory guide to bootstrapping
+a [CNPG-I](https://github.com/cloudnative-pg/cnpg-i) plugin and leveraging
+lifecycle hooks within a development environment. While similar results can be
+achieved through simpler methods such as mutating webhooks or CNPG's built-in
+features, this project is specifically designed to familiarize developers with
+the plugin workflow. By understanding how lifecycle hooks interact with other
+interfaces, developers can gain a deeper insight into implementing complex
+resource changes in real-world applications.
 
-This plugin uses the [pluginhelper](https://github.com/cloudnative-pg/cnpg-i-machinery/tree/main/pkg/pluginhelper) from [`cnpg-i-machinery`](https://github.com/cloudnative-pg/cnpg-i-machinery) to simplify the plugin's implementation.
+This plugin uses
+the [pluginhelper](https://github.com/cloudnative-pg/cnpg-i-machinery/tree/main/pkg/pluginhelper)
+from [`cnpg-i-machinery`](https://github.com/cloudnative-pg/cnpg-i-machinery) to
+simplify the plugin's implementation.
+
+## Running the plugin
+
+To see the plugin in execution, you need to have a Kubernetes cluster running
+(we'll use [Kind](https://kind.sigs.k8s.io)) and the
+[CloudNativePG](https://github.com/cloudnative-pg/cloudnative-pg/) operator
+installed. The plugin also requires certificates to communicate with the
+operator, hence we are also installing [cert-manager](https://cert-manager.io/)
+to manage them.
+
+``` shell
+kind create cluster --name cnpg-i-hello-world
+# Choose the latest version of CloudNativePG (at least 1.24)
+kubectl apply --server-side -f \
+  https://github.com/cloudnative-pg/cloudnative-pg/releases/download/vX.Y.Z/cnpg-X.Y.Z.yaml
+# Choose the latest version of cert-manager
+kubectl apply -f \
+  https://github.com/cert-manager/cert-manager/releases/download/vX.Y.Z/cert-manager.yaml
+```
+
+Then install the plugin by applying the manifest:
+
+<!-- TODO: reevaluate on release and set release-please to automatically update it-->
+
+``` shell
+kubectl apply -f https://github.com/cloudnative-pg/cnpg-i-hello-world/releases/download/v0.1.0/manifest.yaml
+```
+
+Finally, create a cluster resource to see the plugin in action. There are three
+examples in the `doc/examples` directory:
+
+1. [Cluster with labels and annotations](doc/examples/cluster-example.yaml):
+   adds the defined labels and annotations to the pods. Showcases the plugin
+   capability of altering the lifecycle of the CloudNativePG resources.
+2. [Cluster with no parameters](doc/examples/cluster-example-no-parameters.yaml):
+   defaults the plugin settings of the cluster. Showcases the plugin capability
+   of altering the defaulting webhook behavior.
+3. [Cluster with wrong parameters](doc/examples/cluster-example-with-mistake.yaml):
+   includes an error in the configuration. Showcases the plugin capability of
+   validating its own configuration.
+
+## Plugin development
+
+For additional details on the plugin implementation refer to
+the [development documentation](doc/development.md).

Taskfile.yml

@@ -181,9 +181,9 @@ tasks:
     desc: Build a container image for the plugin locally
     vars:
       IMAGE_VERSION: '{{.IMAGE_VERSION | default "latest"}}'
-      IMAGE_NAME: ghcr.io/cloudnative-pg/cnpg-i-hello-world:{{.IMAGE_VERSION}}
+      IMAGE_NAME: cnpg-i-hello-world:{{.IMAGE_VERSION}}
     cmds:
-      - docker build -t ${IMAGE_NAME} .
+      - docker build -t {{.IMAGE_NAME}} .
     sources:
       - ./**
 
@@ -192,5 +192,7 @@ tasks:
     desc: Apply the plugin to a local kind cluster
     deps:
       - local-dev-image
+    env:
+      VERSION: '{{.IMAGE_VERSION | default "latest"}}'
     cmds:
       - ./scripts/run.sh