Skip to content

Commit 0661e38

Browse files
gbartoliniNiccoloFeimnencia
authored
feat: add pg_crash container image (#126)
Adds the `pg_crash` extension, a tool for chaos engineering in PostgreSQL environments. It allows for scheduled or random process termination (SIGKILL/SIGTERM/SIGQUIT) to validate high availability (HA) and failover mechanisms. Closes #123 Signed-off-by: Gabriele Bartolini <gabriele.bartolini@enterprisedb.com> Signed-off-by: Niccolò Fei <niccolo.fei@enterprisedb.com> Signed-off-by: Marco Nenciarini <marco.nenciarini@enterprisedb.com> Co-authored-by: Niccolò Fei <niccolo.fei@enterprisedb.com> Co-authored-by: Marco Nenciarini <marco.nenciarini@enterprisedb.com>
1 parent 0fd2107 commit 0661e38

5 files changed

Lines changed: 145 additions & 3 deletions

File tree

‎.github/workflows/bake.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ on:
1212
- pgvector
1313
- postgis
1414
- pgaudit
15+
- pg-crash
1516

1617
defaults:
1718
run:
@@ -52,6 +53,9 @@ jobs:
5253
pgaudit:
5354
- 'pgaudit/**'
5455
- *shared
56+
pg-crash:
57+
- 'pg-crash/**'
58+
- *shared
5559
5660
# Compute a matrix containing the list of all extensions that have been modified
5761
- name: Compute matrix

‎README.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -34,9 +34,10 @@ they are maintained by their respective authors, and PostgreSQL Debian Group
3434

3535
| Extension | Description | Project URL |
3636
| :--- | :--- | :--- |
37-
| **[pgAudit](pgaudit)** | PostgreSQL audit extension | [https://github.com/pgaudit/pgaudit](https://github.com/pgaudit/pgaudit) |
38-
| **[pgvector](pgvector)** | Vector similarity search for PostgreSQL | [https://github.com/pgvector/pgvector](https://github.com/pgvector/pgvector) |
39-
| **[PostGIS](postgis)** | Geospatial database extension for PostgreSQL | [https://postgis.net/](https://postgis.net/) |
37+
| **[pgAudit](pgaudit)** | PostgreSQL audit extension | [github.com/pgaudit/pgaudit](https://github.com/pgaudit/pgaudit) |
38+
| **[pg_crash](pg-crash)** | **Disruptive** fault injection and chaos engineering extension | [github.com/cybertec-postgresql/pg_crash](https://github.com/cybertec-postgresql/pg_crash) |
39+
| **[pgvector](pgvector)** | Vector similarity search for PostgreSQL | [github.com/pgvector/pgvector](https://github.com/pgvector/pgvector) |
40+
| **[PostGIS](postgis)** | Geospatial database extension for PostgreSQL | [postgis.net/](https://postgis.net/) |
4041

4142

4243
Extensions are provided only for the OS versions already built by the

‎pg-crash/Dockerfile‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# SPDX-FileCopyrightText: Copyright © contributors to CloudNativePG, established as CloudNativePG a Series of LF Projects, LLC.
2+
# SPDX-License-Identifier: Apache-2.0
3+
4+
ARG BASE=ghcr.io/cloudnative-pg/postgresql:18-minimal-trixie
5+
FROM $BASE AS builder
6+
7+
ARG PG_MAJOR
8+
ARG EXT_VERSION
9+
10+
USER 0
11+
12+
# Install extension via `apt-get`
13+
RUN apt-get update && apt-get install -y --no-install-recommends \
14+
"postgresql-${PG_MAJOR}-pg-crash=${EXT_VERSION}"
15+
16+
FROM scratch
17+
ARG PG_MAJOR
18+
19+
# Licenses
20+
COPY --from=builder /usr/share/doc/postgresql-${PG_MAJOR}-pg-crash/copyright /licenses/postgresql-${PG_MAJOR}-pg-crash/
21+
22+
# Libraries
23+
COPY --from=builder /usr/lib/postgresql/${PG_MAJOR}/lib/pg_crash* /lib/
24+
COPY --from=builder /usr/lib/postgresql/${PG_MAJOR}/lib/bitcode/ /lib/bitcode/
25+
26+
USER 65532:65532

‎pg-crash/README.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# `pg_crash`
2+
<!--
3+
SPDX-FileCopyrightText: Copyright © contributors to CloudNativePG, established as CloudNativePG a Series of LF Projects, LLC.
4+
SPDX-License-Identifier: Apache-2.0
5+
-->
6+
7+
[pg_crash](https://github.com/cybertec-postgresql/pg_crash) is a PostgreSQL
8+
extension designed for **fault injection** and **chaos engineering**. It allows
9+
administrators to simulate various failure scenarios—such as backend crashes
10+
and signal handling issues—to verify the resilience of High Availability (HA)
11+
clusters and self-healing mechanisms.
12+
13+
> [!CAUTION]
14+
> **DO NOT USE THIS IMAGE IN PRODUCTION.**
15+
> This extension is designed to intentionally destabilize and terminate
16+
> PostgreSQL processes. Deploying it in production will cause service downtime
17+
> and potential data availability issues.
18+
>
19+
> Only deploy this extension in **dedicated test or staging namespaces**.
20+
> Consider using Kubernetes admission controllers or OPA/Gatekeeper policies
21+
> to prevent accidental deployment to production clusters.
22+
23+
This extension image is maintained by the CNPG project and supersedes the
24+
[`pgcrash-containers` project](https://github.com/cloudnative-pg/pgcrash-containers).
25+
26+
## Usage
27+
28+
The `pg_crash` extension must be loaded via `shared_preload_libraries`. It
29+
operates by periodically sending random signals (selected from a user-defined
30+
list) to PostgreSQL backend processes.
31+
32+
The following example configures a cluster to experience "Chaos" by randomly
33+
sending signals every 60 seconds. This is ideal for testing how quickly
34+
CloudNativePG detects a failure and promotes a new primary.
35+
36+
```yaml
37+
apiVersion: postgresql.cnpg.io/v1
38+
kind: Cluster
39+
metadata:
40+
name: cluster-pg-crash
41+
spec:
42+
imageName: ghcr.io/cloudnative-pg/postgresql:18-minimal-trixie
43+
instances: 3
44+
45+
storage:
46+
size: 1Gi
47+
48+
postgresql:
49+
extensions:
50+
- name: pg-crash
51+
image:
52+
# renovate: suite=trixie-pgdg depName=postgresql-18-pg-crash
53+
reference: ghcr.io/cloudnative-pg/pg-crash:0.3-18-trixie
54+
shared_preload_libraries:
55+
- pg_crash
56+
parameters:
57+
log_min_messages: 'DEBUG1'
58+
# See https://www.postgresql.org/docs/current/server-shutdown.html
59+
# SIGHUP (1) - Reload
60+
# SIGINT (2) - Fast shutdown
61+
# SIGQUIT (3) - Immediate shutdown
62+
# SIGTERM (15) - Smart shutdown
63+
crash.signals: '1 2 3 15'
64+
crash.delay: '60'
65+
```
66+
67+
---
68+
69+
## Licenses and Copyright
70+
71+
`pg_crash`:
72+
73+
- **Copyright:** (c) 2017, 2025 CYBERTEC PostgreSQL International GmbH
74+
- **License:** BSD 3-Clause License
75+
76+
All relevant license and copyright information for the `pg-crash` extension
77+
and its dependencies are bundled within the image at:
78+
79+
```text
80+
/licenses/
81+
```
82+
83+
By using this image, you agree to comply with the terms of the licenses
84+
contained therein.

‎pg-crash/metadata.hcl‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# SPDX-FileCopyrightText: Copyright © contributors to CloudNativePG, established as CloudNativePG a Series of LF Projects, LLC.
2+
# SPDX-License-Identifier: Apache-2.0
3+
metadata = {
4+
name = "pg-crash"
5+
sql_name = "pg_crash"
6+
image_name = "pg-crash"
7+
licenses = ["BSD-3-Clause"]
8+
shared_preload_libraries = ["pg_crash"]
9+
extension_control_path = []
10+
dynamic_library_path = []
11+
ld_library_path = []
12+
bin_path = []
13+
auto_update_os_libs = false
14+
required_extensions = []
15+
create_extension = false
16+
17+
versions = {
18+
bookworm = {
19+
// renovate: suite=bookworm-pgdg depName=postgresql-18-pg-crash
20+
"18" = "0.3-2.pgdg12+1"
21+
}
22+
trixie = {
23+
// renovate: suite=trixie-pgdg depName=postgresql-18-pg-crash
24+
"18" = "0.3-2.pgdg13+1"
25+
}
26+
}
27+
}

0 commit comments

Comments
 (0)