Skip to content
Merged
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 62 additions & 24 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,23 +8,80 @@ container images** containing PostgreSQL extensions supported by
integrate seamlessly with the [`image volume extensions` feature](https://cloudnative-pg.io/documentation/current/imagevolume_extensions/)
in CloudNativePG.

For detailed instructions on building the images, see the [BUILD.md file](BUILD.md).
For detailed instructions on building the images, see the [`BUILD.md` file](BUILD.md).

---

## Requirements

- **CloudNativePG** ≥ 1.27
- **PostgreSQL** ≥ 18 (requires the `extension_control_path` feature)
- **Kubernetes** 1.33+ with [ImageVolume feature enabled](https://kubernetes.io/blog/2024/08/16/kubernetes-1-31-image-volume-source/)
- **Kubernetes** 1.33+ (with [ImageVolume feature enabled in 1.33 and 1.34](https://kubernetes.io/blog/2024/08/16/kubernetes-1-31-image-volume-source/))

---

## Supported Extensions

- [pgvector](pgvector) - Vector similarity search for PostgreSQL
- [PostGIS](postgis) - Geospatial database extension for PostgreSQL
- [pgAudit](pgaudit) - PostgreSQL Audit Extension
CloudNativePG actively maintains the following third-party extensions, provided
they are maintained by their respective authors, and PostgreSQL Debian Group
(PGDG) packages are available.

| Extension | Description | Project URL |
| :--- | :--- | :--- |
| **[pgAudit](pgaudit)** | PostgreSQL audit extension | [https://github.com/pgaudit/pgaudit](https://github.com/pgaudit/pgaudit) |
| **[pgvector](pgvector)** | Vector similarity search for PostgreSQL | [https://github.com/pgvector/pgvector](https://github.com/pgvector/pgvector) |
| **[PostGIS](postgis)** | Geospatial database extension for PostgreSQL | [https://postgis.net/](https://postgis.net/) |


Extensions are provided only for the OS versions already built by the
[`cloudnative-pg/postgres-containers`](https://github.com/cloudnative-pg/postgres-containers) project,
specifically Debian `stable` and `oldstable`.

---

## Contribution and Maintenance Policy

Contributors are welcome to propose and maintain additional extensions.

### Governance and Compliance

The project adheres to the following frameworks:

- **Governance Model:** complies with the CloudNativePG (CNPG) Governance
Model, as defined in [`GOVERNANCE.md`](GOVERNANCE.md).
- **Code of Conduct:** follows the CNCF Code of Conduct, as defined in
[`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md).

### Extension Requirements

When proposing a new extension, the following criteria must be met:

- **Licensing and IP ownership:** the extension's licensing must be compatible
with the project's goals. We approve all licences that are on the CNCF
Allowed Third-Party Licence Policy list (see
[CNCF Allowed Licence Policy](https://github.com/cncf/foundation/blob/main/policies-guidance/allowed-third-party-license-policy.md#cncf-allowlist-license-policy)).
- **Structure:** only one extension can be included within an extension folder.
- **Debian packages:** extension images must be built using a [Debian package provided by the PGDG](https://wiki.postgresql.org/wiki/Apt).
- **Licence inclusion:** all necessary licence agreements for the extension and
its dependencies must be included within the extension folder (refer to the
examples in the `pgvector` and `postgis` folders).

### Submission Process

1. **Request and commitment:** Open a new issue requesting the extension.
The contributor(s) must agree to become "component owners" and maintainers
for that extension.
2. **Approval:** Once approved by maintainers, the component owner(s) will be
added to the `CODEOWNERS` file for the specific folder.
3. **Submission:** Component owner(s) open a Pull Request (PR) to introduce the
new extension. The PR is reviewed, approved, and merged.
4. **Naming:** The name of the extension is the registry name.

### Removal Policy

If component owners decide to stop maintaining their extension, and no other
contributors are found, the main project maintainers reserve the right to
**unconditionally remove that extension**.

---

Expand Down Expand Up @@ -56,22 +113,3 @@ This scheme ensures:
- Alignment with the upstream `postgres-containers` base images
- Explicit PostgreSQL and extension versioning
- Multi-distro support

---

## Roadmap / Open Questions

- Should each extension live in its **own dedicated folder**? (YES!)
- Should each extension follow its **own release cycle**? (YES!)
- Should we track dependencies? (YES: TODO)
- Should we test/rebuild the extensions that depend on the new one and so forth?
- Must every release pass **smoke tests** (e.g. via [Kind](https://kind.sigs.k8s.io/))? (YES!)
- Should we define policies for:

- Licensing (must be open source)?
- Contribution and ownership
- Governance aligned with the [CloudNativePG project](https://cloudnative-pg.io/)?
- Can contributors propose and maintain additional extensions? (YES)
- Shall we have a template for a new extension?
- Should each extension have designated **component owners** responsible for
maintenance, reviews, and release management? (YES)