Skip to content

Add security event logging documentation #1136

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 21, 2025
Merged

Add security event logging documentation #1136

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f9030f7
Add security event logging documentation
marceloneppel Oct 18, 2025
f3db29f
Ignore terraform URLs in link checker
a-velasco Oct 20, 2025
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
3 changes: 3 additions & 0 deletions docs/.custom_wordlist.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ CSR
CSRs
databag
databags
DDL
dev
dvipng
eks
Expand Down Expand Up @@ -69,6 +70,7 @@ LDAP
libs
lifecycle
MinIO
misconfiguration
Multipass
nameserver
nameservers
Expand All @@ -77,6 +79,7 @@ otf
Parca
Patroni
Patroni*
pgAudit
pgbackrest
pgBackRest
pgbouncer
Expand Down
4 changes: 3 additions & 1 deletion docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -208,7 +208,9 @@
linkcheck_ignore = [
"http://127.0.0.1:8000",
"https://github.com/canonical/ACME/*",
"https://matrix.to/*"
"https://matrix.to/*",
"https://developer.hashicorp.com/*",
"https://www.terraform.io/*"
]

# A regex list of URLs where anchors are ignored by 'make linkcheck'
Expand Down
4 changes: 2 additions & 2 deletions docs/explanation/legacy-charm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@

There are [two types of charms](https://documentation.ubuntu.com/juju/3.6/reference/charm/#by-generation) stored under the same charm name `postgresql-k8s`:

1. [Reactive](https://documentation.ubuntu.com/juju/3.6/reference/charm/#reactive) charm in the channel `latest/stable` (called `legacy`)
2. [Ops-based](https://documentation.ubuntu.com/juju/3.6/reference/charm/#ops) charm in the channel `14/stable` (called `modern`)
1. [Reactive](https://documentation.ubuntu.com/juju/3.6/reference/charm/#reactive-charm) charm in the channel `latest/stable` (called `legacy`)
2. [Ops-based](https://documentation.ubuntu.com/juju/3.6/reference/charm/#ops-charm) charm in the channel `14/stable` (called `modern`)

The legacy charm provided endpoints `db` and `db-admin` (for the interface `pgsql`). The modern charm provides old endpoints as well + new endpoint `database` (for the interface `postgresql_client`). Read more details about the available [endpoints/interfaces](/explanation/interfaces-and-endpoints).

Expand Down
17 changes: 16 additions & 1 deletion docs/explanation/security/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ Charmed PostgreSQL K8s can be deployed on top of several Kubernetes distribution

### Juju

Juju is the component responsible for orchestrating the entire lifecycle, from deployment to Day 2 operations. For more information on Juju security hardening, see the [Juju security page](https://documentation.ubuntu.com/juju/latest/explanation/juju-security/index.html) and the [How to harden your deployment](https://documentation.ubuntu.com/juju/3.6/howto/manage-your-deployment/#harden-your-deployment) guide.
Juju is the component responsible for orchestrating the entire lifecycle, from deployment to Day 2 operations. For more information on Juju security hardening, see the [Juju security page](https://documentation.ubuntu.com/juju/latest/explanation/juju-security/index.html) and the [How to harden your deployment](https://documentation.ubuntu.com/juju/3.6/howto/manage-your-juju-deployment/harden-your-juju-deployment/#harden-your-deployment) guide.

#### Cloud credentials

Expand Down Expand Up @@ -91,6 +91,21 @@ Charmed PostgreSQL K8s provides native integration with the [Canonical Observabi

PostgreSQL logs are stored in `/var/log/postgresql` within the postgresql container of each unit. It’s recommended to integrate the charm with [COS](https://canonical.com/data/docs/postgresql/k8s/h-enable-monitoring), from where the logs can be easily persisted and queried using [Loki](https://charmhub.io/loki-k8s)/[Grafana](https://charmhub.io/grafana).

### Security event logging

Charmed PostgreSQL K8s provides [PostgreSQL Audit Extension (or pgAudit)](https://www.pgaudit.org/) enabled by default. These logs are stored in the `/var/log/postgresql/` directory of each unit along with the regular workload logs, and rotated minutely. If COS is enabled, audit logs are also persisted there.

The following information is configured to be logged:

* Statements related to roles and privileges, such as GRANT, REVOKE, CREATE, ALTER, and DROP ROLE.
* Data Definition Language (DDL) statements.
* Miscellaneous commands like DISCARD, FETCH, CHECKPOINT, VACUUM, SET.
* Miscellaneous SET commands.

Other events, like connections and disconnections, are logged depending on the value of the charm configuration options related to them. For more information, check the configuration options with the `logging` prefix in the [configuration reference](https://charmhub.io/postgresql-k8s/configurations#logging_log_connections).

No secrets are logged.

## Additional Resources

For details on the cryptography used by Charmed PostgreSQL K8s, see the [Cryptography](/explanation/security/cryptography) explanation page.
Expand Down
12 changes: 6 additions & 6 deletions docs/reference/alert-rules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,12 +50,12 @@ This page contains a markdown version of the alert rules described in the `postg

## `PgbackrestExporterK8s`

| Alert | Severity | Notes |
| ----- | -------- | ----- |
| `PgBackRestBackupError` | ![critical] | Backup failed for a stanza.<br>The last pgBackRest backup ended with error status > 0.<br>Check the pgBackRest logs for the stanza. |
| `PgBackRestBackupTooOld` | ![warning] | No recent backup available.<br>The last pgBackRest backup is older than 7 days.<br>Consider checking your backup schedule, capacity, and logs. |
| `PgBackRestStanzaError` | ![warning] | A stanza has reported errors.<br>Status > 0 indicates problems such as missing stanza path or no valid backups.<br>Check pgBackRest logs for details. |
| `PgBackRestRepoError` | ![warning] | A repository has reported errors.<br>Status > 0 indicates the repo may be inaccessible, out of space, or otherwise unhealthy.<br>Check pgBackRest logs and storage system. |
| Alert | Severity | Notes |
| ----- | -------- |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `PgBackRestBackupError` | ![critical] | Backup failed for a stanza.<br>The last pgBackRest backup ended with error status > 0.<br>Check the pgBackRest logs for the stanza. |
| `PgBackRestBackupTooOld` | ![warning] | No recent backup available.<br>The last pgBackRest backup is older than 7 days.<br>Consider checking your backup schedule, capacity, and logs. |
| `PgBackRestStanzaError` | ![warning] | A stanza has reported errors.<br>Status > 0 indicates problems such as missing stanza path or no valid backups.<br>Check pgBackRest logs for details. |
| `PgBackRestRepoError` | ![warning] | A repository has reported errors.<br>Status > 0 indicates the repository may be inaccessible, out of space, or otherwise unhealthy.<br>Check pgBackRest logs and storage system. |
| `PgBackRestExporterError` | ![critical] | The pgBackRest exporter failed to fetch data.<br>Metric `pgbackrest_exporter_status == 0` indicates exporter-side issues.<br>This may be a misconfiguration or runtime error; check exporter logs. |

<!-- Badges -->
Expand Down