From d0e094ad6182f98b3a0522b2173a0d3f083f0167 Mon Sep 17 00:00:00 2001 From: Francesco Canovai Date: Tue, 24 Dec 2024 11:53:13 +0100 Subject: [PATCH 1/4] docs: mark the status as experimental and improve the README * Mark CNPG-I status as experimental. * Added links to the known projects where CNPG-I is used. * Renamed the protocol documentation to protocol.md instead of a generic docs.md. * Small changes to the README.md Signed-off-by: Francesco Canovai --- .wordlist.txt | 1 + README.md | 73 ++++++++++++++++++----------------- Taskfile.yml | 4 +- docs/{docs.md => protocol.md} | 0 4 files changed, 41 insertions(+), 37 deletions(-) rename docs/{docs.md => protocol.md} (100%) diff --git a/.wordlist.txt b/.wordlist.txt index 5958397..9f41505 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -118,6 +118,7 @@ kubernetes lifecycle lifecycle lsn +md pluggable pluginName postgres diff --git a/README.md b/README.md index 6894222..8fecf2e 100644 --- a/README.md +++ b/README.md @@ -1,64 +1,67 @@ # CloudNativePG Interface (CNPG-I) -**Status:** PROPOSAL +**Status:** Experimental -## Why do we need CNPG-I? +## Protocol -The CloudNativePG code base has sensibly grown over the years, increasing the -cognitive load required to work with it and creating a bottleneck in the -submission of new pull requests in the open source project itself. +The CloudNativePG Interface (CNPG-I) is a gRPC-based protocol that defines the +interface between the CloudNativePG operator and its plugins. -The risk we are currently facing is that the delivery of new features is slowed -down further and further as the project grows both in code base and adoption. +For the full protocol specification, refer to the [protocol.md](docs/protocol.md) file. -As with every successful open source project indeed, everyday maintainers need -to face the dilemma to reject or approve a pull request in the code base -knowing that, when it gets committed, it’s forever. +## Rationale -We need to find a different and more pluggable way of adding new behaviors and -capabilities to the operator, not necessarily in the open source space. +The CloudNativePG code base has grown significantly over the years, increasing +the cognitive load required to work with it and creating challenges in the +submission of new pull requests in the open source project. -The proposal here is to follow a pattern that’s already been successfully -implemented in Kubernetes through the -[Container Storage Interface (CSI)](https://github.com/container-storage-interface/spec/blob/master/spec.md), -and give birth to a new open source initiative within CloudNativePG called the -“CloudNativePG Interface (CNPG-I)”. +As the project grows both in code base and adoption, it is important to ensure +that the delivery of new features remains efficient. -The CNPG-I standard API, based on gRPC, should enable new organizations to join -EDB (original creator of CloudNativePG) and develop a plugin or a collection of -them - instead of creating, maintaining, and distributing a fork of -CloudNativePG. +To address this, we propose a more modular approach to adding new behaviors and +capabilities to the operator, inspired by the successful implementation of the +[Container Storage Interface (CSI)](https://github.com/container-storage-interface/spec/blob/master/spec.md) +in Kubernetes. -Some of the advantages of CNPG-I can bring are: +The CloudNativePG Interface (CNPG-I) standard API, based on gRPC, aims to enable +developers and organizations to create plugins or collections of them, rather +than creating, maintaining, and distributing a fork of CloudNativePG. -* Remove complexity and responsibility from CloudNativePG open source code - base, by delegating them to external plugins that can run as sidecar +Some of the benefits of CNPG-I include: + +* Reducing complexity and responsibility within the CloudNativePG open source + code base by delegating them to external plugins that can run as sidecar containers alongside Postgres -* Remove bottleneck from CloudNativePG core team in terms of delivery of new - features, increasing velocity, fostering prototyping, and nurturing an - independent ecosystem of plugins -* A standard gRPC-based API specification covering the customizable aspects of - the operator and the operands, and providing a way to test the compliance - with it -* Encourage dynamic growth of the ecosystem through customizations that can be +* Increasing the velocity of feature delivery by removing bottlenecks from the + CloudNativePG core team, fostering prototyping, and nurturing an independent + ecosystem of plugins +* Providing a standard gRPC-based API specification that covers customizable + aspects of the operator and the operands, and offering a way to test + compliance with it +* Encouraging dynamic growth of the ecosystem through customizations that can be independently developed within the operands, as separate projects instead of operator forks, with a lower required cognitive load -* Facilitate the move to CloudNativePG for other Postgres and Kubernetes +* Facilitating the move to CloudNativePG for other Postgres and Kubernetes companies. -## Some examples of plugins +### Use cases for plugins For example, plugins might involve: -* WAL management (archive and restore) +* WAL management * Backup and recovery management * Logging and auditing * Export of metrics -* Authentication and authorizations +* Authentication and authorization * Management of extensions * Management of an instance lifecycle * Management of the configuration of an instance +## Projects using CNPG-I + +* [CNPG-I Hello World](https://github.com/cloudnative-pg/cnpg-i-hello-world/) +* [Barman Cloud CNPG-I Plugin](https://github.com/cloudnative-pg/plugin-barman-cloud) + ## Trademarks *[Postgres, PostgreSQL and the Slonik Logo](https://www.postgresql.org/about/policies/trademarks/) diff --git a/Taskfile.yml b/Taskfile.yml index fd4ab00..06b8041 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -45,7 +45,7 @@ tasks: # renovate: datasource=git-refs depName=protoc-gen-doc lookupName=https://github.com/cloudnative-pg/daggerverse currentValue=main DAGGER_PROTOC_GEN_DOC_SHA: 15ae21b03bab44124ddd7e3f3728f45503c6f185 cmds: - - GITHUB_REF= dagger -s call -m github.com/cloudnative-pg/daggerverse/protoc-gen-doc@${DAGGER_PROTOC_GEN_DOC_SHA} generate --proto-dir proto -o docs + - GITHUB_REF= dagger -s call -m github.com/cloudnative-pg/daggerverse/protoc-gen-doc@${DAGGER_PROTOC_GEN_DOC_SHA} generate --proto-dir proto --doc-opt "markdown,protocol.md" -o docs sources: - proto/**/*.proto @@ -96,6 +96,6 @@ tasks: clean: desc: Remove autogenerated artifacts cmds: - - rm -f docs/docs.md + - rm -f docs/protocol.md - rm -rf .task/ - rm -f pkg/*/*.pb.go diff --git a/docs/docs.md b/docs/protocol.md similarity index 100% rename from docs/docs.md rename to docs/protocol.md From 62b8fe28483d680fada13c3adca59a04ade2a02c Mon Sep 17 00:00:00 2001 From: Gabriele Bartolini Date: Tue, 24 Dec 2024 14:40:19 +0100 Subject: [PATCH 2/4] docs: review Signed-off-by: Gabriele Bartolini --- README.md | 111 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 66 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index 8fecf2e..75855db 100644 --- a/README.md +++ b/README.md @@ -2,65 +2,86 @@ **Status:** Experimental -## Protocol +The **CloudNativePG Interface (CNPG-I)** introduces a modular and extensible +approach to integrating plugins with the +[CloudNativePG operator for PostgreSQL](https://github.com/cloudnative-pg/cloudnative-pg), +enabling greater flexibility and ease of feature development in the +CloudNativePG ecosystem. -The CloudNativePG Interface (CNPG-I) is a gRPC-based protocol that defines the -interface between the CloudNativePG operator and its plugins. +--- -For the full protocol specification, refer to the [protocol.md](docs/protocol.md) file. +## What is CNPG-I? -## Rationale +The **CloudNativePG Interface** is a **gRPC-based protocol** that defines a +standardized interface between the CloudNativePG operator and external plugins. +This approach empowers developers and organizations to extend the operator's +functionality without the need to fork its codebase. -The CloudNativePG code base has grown significantly over the years, increasing -the cognitive load required to work with it and creating challenges in the -submission of new pull requests in the open source project. +For a detailed protocol specification, refer to the [protocol.md](docs/protocol.md) file. -As the project grows both in code base and adoption, it is important to ensure -that the delivery of new features remains efficient. +--- -To address this, we propose a more modular approach to adding new behaviors and -capabilities to the operator, inspired by the successful implementation of the -[Container Storage Interface (CSI)](https://github.com/container-storage-interface/spec/blob/master/spec.md) -in Kubernetes. +## Why CNPG-I? -The CloudNativePG Interface (CNPG-I) standard API, based on gRPC, aims to enable -developers and organizations to create plugins or collections of them, rather -than creating, maintaining, and distributing a fork of CloudNativePG. +Over the years, CloudNativePG's codebase has grown significantly, creating +challenges for developers contributing to the project and increasing the time +required to deliver new features. -Some of the benefits of CNPG-I include: +To address this, CNPG-I provides a **modular plugin architecture** inspired by +the success of Kubernetes' [Container Storage Interface (CSI)](https://github.com/container-storage-interface/spec/blob/master/spec.md). -* Reducing complexity and responsibility within the CloudNativePG open source - code base by delegating them to external plugins that can run as sidecar - containers alongside Postgres -* Increasing the velocity of feature delivery by removing bottlenecks from the - CloudNativePG core team, fostering prototyping, and nurturing an independent - ecosystem of plugins -* Providing a standard gRPC-based API specification that covers customizable - aspects of the operator and the operands, and offering a way to test - compliance with it -* Encouraging dynamic growth of the ecosystem through customizations that can be - independently developed within the operands, as separate projects instead of - operator forks, with a lower required cognitive load -* Facilitating the move to CloudNativePG for other Postgres and Kubernetes - companies. +CNPG-I fosters a thriving ecosystem by making it easier to integrate new +capabilities through independent plugins, allowing for faster innovation and +simplified maintenance. -### Use cases for plugins +--- -For example, plugins might involve: +### Key Benefits -* WAL management -* Backup and recovery management -* Logging and auditing -* Export of metrics -* Authentication and authorization -* Management of extensions -* Management of an instance lifecycle -* Management of the configuration of an instance +1. **Reduced Complexity**: Delegate responsibilities to external plugins, + reducing the cognitive load and size of the CloudNativePG core codebase. +2. **Faster Feature Delivery**: Accelerate development by fostering independent + plugin creation, prototyping, and ecosystem growth. +3. **Standardized gRPC API**: + Provide a robust, gRPC-based API specification for customizing operator and + operand behavior, complete with compliance testing tools. +4. **Ecosystem Expansion**: Encourage innovation by enabling developers to + create enhancements as separate projects, avoiding forks and lowering barriers + to entry. +5. **Ease of Adoption**: Simplify the move to CloudNativePG for Postgres and + Kubernetes users by facilitating custom enhancements and integrations. -## Projects using CNPG-I +--- -* [CNPG-I Hello World](https://github.com/cloudnative-pg/cnpg-i-hello-world/) -* [Barman Cloud CNPG-I Plugin](https://github.com/cloudnative-pg/plugin-barman-cloud) +## Use Cases for Plugins + +CNPG-I enables the creation of plugins for diverse use cases, such as: + +- **WAL Management** +- **Backup and Recovery** +- **Logging and Auditing** +- **Metrics Export** +- **Authentication and Authorization** +- **Extension Management** +- **Instance Lifecycle Management** +- **Configuration Management** + +By leveraging plugins, developers can extend CloudNativePG’s functionality +without modifying its core code. + +--- + +## Projects Built with CNPG-I + +Explore real-world applications of CNPG-I: + +- [CNPG-I Hello World](https://github.com/cloudnative-pg/cnpg-i-hello-world/): + A simple example plugin demonstrating CNPG-I. +- [Barman Cloud CNPG-I Plugin](https://github.com/cloudnative-pg/plugin-barman-cloud): + A plugin for seamless integration with Barman Cloud for Continuous Backup and + Recovery using object stores. + +--- ## Trademarks From c587e8a9f2e030faa7e4803b7a2770173ab253a0 Mon Sep 17 00:00:00 2001 From: Gabriele Bartolini Date: Tue, 24 Dec 2024 14:44:21 +0100 Subject: [PATCH 3/4] fix: cosmetic Signed-off-by: Gabriele Bartolini --- README.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/README.md b/README.md index 75855db..7730b74 100644 --- a/README.md +++ b/README.md @@ -8,8 +8,6 @@ approach to integrating plugins with the enabling greater flexibility and ease of feature development in the CloudNativePG ecosystem. ---- - ## What is CNPG-I? The **CloudNativePG Interface** is a **gRPC-based protocol** that defines a @@ -19,8 +17,6 @@ functionality without the need to fork its codebase. For a detailed protocol specification, refer to the [protocol.md](docs/protocol.md) file. ---- - ## Why CNPG-I? Over the years, CloudNativePG's codebase has grown significantly, creating @@ -34,8 +30,6 @@ CNPG-I fosters a thriving ecosystem by making it easier to integrate new capabilities through independent plugins, allowing for faster innovation and simplified maintenance. ---- - ### Key Benefits 1. **Reduced Complexity**: Delegate responsibilities to external plugins, @@ -51,8 +45,6 @@ simplified maintenance. 5. **Ease of Adoption**: Simplify the move to CloudNativePG for Postgres and Kubernetes users by facilitating custom enhancements and integrations. ---- - ## Use Cases for Plugins CNPG-I enables the creation of plugins for diverse use cases, such as: @@ -69,8 +61,6 @@ CNPG-I enables the creation of plugins for diverse use cases, such as: By leveraging plugins, developers can extend CloudNativePG’s functionality without modifying its core code. ---- - ## Projects Built with CNPG-I Explore real-world applications of CNPG-I: From 890424b351c37e6086e1a39a177703505b391734 Mon Sep 17 00:00:00 2001 From: Francesco Canovai Date: Tue, 24 Dec 2024 15:30:57 +0100 Subject: [PATCH 4/4] docs: update allowed words list Signed-off-by: Francesco Canovai --- .wordlist.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.wordlist.txt b/.wordlist.txt index 9f41505..db203f9 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -6,6 +6,7 @@ BackupRequest BackupResult ByteString CloudNativePG +CloudNativePG's ConfigsEntry DEREGISTER Deregister @@ -99,6 +100,7 @@ bool boolean cncf cnpg +codebase config configs csi @@ -111,6 +113,7 @@ gRPC html https ietf +integrations json kube kubernetes