diff --git a/.wordlist.txt b/.wordlist.txt index 5958397..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 @@ -118,6 +121,7 @@ kubernetes lifecycle lifecycle lsn +md pluggable pluginName postgres diff --git a/README.md b/README.md index 6894222..7730b74 100644 --- a/README.md +++ b/README.md @@ -1,63 +1,77 @@ # CloudNativePG Interface (CNPG-I) -**Status:** PROPOSAL - -## Why do we need CNPG-I? - -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 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. - -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. - -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 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)”. - -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. - -Some of the advantages of CNPG-I can bring are: - -* Remove complexity and responsibility from 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 - 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 - companies. - -## Some examples of plugins - -For example, plugins might involve: - -* WAL management (archive and restore) -* Backup and recovery management -* Logging and auditing -* Export of metrics -* Authentication and authorizations -* Management of extensions -* Management of an instance lifecycle -* Management of the configuration of an instance +**Status:** Experimental + +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. + +## What is CNPG-I? + +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. + +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 +challenges for developers contributing to the project and increasing the time +required to deliver new features. + +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). + +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, + 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. + +## 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 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