canonical · a-velasco · Jul 11, 2025 · Jun 27, 2025 · Jun 27, 2025 · Jul 10, 2025
diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt
@@ -1,40 +1,152 @@
 # Leave a blank line at the end of this file to support concatenation
+airgap
+airgapped
+analyze
+artifact
+Artifactory
+artifacts
+async
+aws
+AWS
+AZ
+AZs
 backend
 backends
+backport
+balancer
+balancers
+benchmark
+benchmarking
+CharmBase
 Charmcraft
+charmhub
+checksum
+checksums
+CIS
 cjk
+codebase
+config
+configs
 cryptographically
+CSR
+CSRs
+databag
+databags
+dev
 dvipng
+eks
+EKS
+entrypoint
+failover
+filesystem
+filesystems
 fonts
 freefont
+gapped
+gce
+GCE
+gcloud
+GCloud
+GCP
 github
+GLAuth
 GPG
 gyre
+HLD
+hostname
+hostnames
 https
+IAAS
+integration
+integrations
 Intersphinx
+io
+IPs
+IPv
+Jira
+jitter
+Juju
+Juju's
 lang
 LaTeX
 latexmk
+LDAP
+libs
+lifecycle
+LXD
+LXD's
+MicroK8s
+MinIO
 Multipass
+nameserver
+nameservers
+Nextcloud
 otf
+Parca
+Parca's
+Patroni
+patronictl
+pgbackrest
+pgBackRest
+pgbouncer
+pgsql
+PITR
 plantuml
 PNG
+pooler
+postgres
+postgresql
+PPA
+PPAs
+pqsql
+programmatically
+PSC
+PVCs
+py
 Pygments
 QEMU
+RadosGW
+requirer
+rockcraft
 Rockcraft
+routable
 rst
+scalable
+sdk
+SHA
+snap
+snapcraft
+SoS
+squashfs
+SquashFS
+src
+SSL
+stateful
 SVG
+Sysbench
+terraform
 tex
 texlive
+TimescaleDB
 TOC
 toctree
+Traefik
 txt
+ubuntu
 uncommenting
+uncordon
 utils
+vm
 VMs
+WAL
+walkthrough
 WCAG
+wget
 whitespace
 whitespaces
+WIP
 wordlist
 xetex
+XID
 xindy
+yaml
diff --git a/docs/.sphinx/spellingcheck.yaml b/docs/.sphinx/spellingcheck.yaml
@@ -9,7 +9,7 @@ matrix:
         - .custom_wordlist.txt
       output: .sphinx/.wordlist.dic
     sources:
-      - _build/**/*.html
+      - _build/**/*.html|!_build/reference/alert-rules/index.html
     pipeline:
       - pyspelling.filters.html:
           comments: false

diff --git a/docs/conf.py b/docs/conf.py
@@ -208,7 +208,8 @@
 linkcheck_ignore = [
     "http://127.0.0.1:8000",
     "https://github.com/canonical/ACME/*",
-    "https://matrix.to/*"
+    "https://matrix.to/*",
+    "https://portal.azure.com/#browse/Microsoft.Compute/VirtualMachines"
     ]
 
 # A regex list of URLs where anchors are ignored by 'make linkcheck'

diff --git a/docs/explanation/architecture.md b/docs/explanation/architecture.md
@@ -83,7 +83,7 @@ GLAuth is a secure, easy-to-use and open-sourced LDAP server which provides capa
 
 ### Grafana
 
-Grafana is an open-source visualization tools that allows to query, visualize, alert on, and visualize metrics from mixed datasources in configurable dashboards for observability. This charms is shipped with its own Grafana dashboard and supports integration with the [Grafana Operator](https://charmhub.io/grafana-k8s) to simplify observability. Please follow [COS Monitoring](/how-to/monitoring-cos/enable-monitoring) setup.
+Grafana is an open-source visualisation tools that allows to query, visualise, alert on, and visualise metrics from mixed data sources in configurable dashboards for observability. This charms is shipped with its own Grafana dashboard and supports integration with the [Grafana Operator](https://charmhub.io/grafana-k8s) to simplify observability. Please follow [COS Monitoring](/how-to/monitoring-cos/enable-monitoring) setup.
 
 ### Loki
 
@@ -105,25 +105,25 @@ Accordingly to the [Juju SDK](https://juju.is/docs/sdk/event): “an event is a
 
 For this charm, the following events are observed:
 
-1. [`on_install`](https://juju.is/docs/sdk/install-event): install the snap "charmed-postgresql" and perform basic preparations to bootstrap the cluster on the first leader (or join the already configured cluster). 
-2. [`leader-elected`](https://juju.is/docs/sdk/leader-elected-event): generate all the secrets to bootstrap the cluster.
-3. [`leader-settings-changed`](https://juju.is/docs/sdk/leader-settings-changed-event): Handle the leader settings changed event.
-4. [`start`](https://juju.is/docs/sdk/start-event): Init/setting up the cluster node.
-5. [`config_changed`](https://juju.is/docs/sdk/config-changed-event): usually fired in response to a configuration change using the GUI or CLI. Create and set default cluster and cluster-set names in the peer relation databag (on the leader only).
-6. [`update-status`](https://juju.is/docs/sdk/update-status-event): Takes care of workload health checks.
+1. [`on_install`](https://documentation.ubuntu.com/juju/3.6/reference/hook/#install): install the snap "charmed-postgresql" and perform basic preparations to bootstrap the cluster on the first leader (or join the already configured cluster). 
+2. [`leader-elected`](https://documentation.ubuntu.com/juju/3.6/reference/hook/#leader-elected): generate all the secrets to bootstrap the cluster.
+3. [`leader-settings-changed`](https://documentation.ubuntu.com/juju/3.6/reference/hook/#leader-settings-changed): Handle the leader settings changed event.
+4. [`start`](https://documentation.ubuntu.com/juju/3.6/reference/hook/#start): Init/setting up the cluster node.
+5. [`config_changed`](https://documentation.ubuntu.com/juju/3.6/reference/hook/#config-changed): usually fired in response to a configuration change using the GUI or CLI. Create and set default cluster and cluster-set names in the peer relation databag (on the leader only).
+6. [`update-status`](https://documentation.ubuntu.com/juju/3.6/reference/hook/#update-status): Takes care of workload health checks.
 <!--- 7. database_storage_detaching: TODO: ops? event?
-8. TODO: any other events?
+1. TODO: any other events?
 --->
 
 ### Charm code overview
 
-[`src/charm.py`](https://github.com/canonical/postgresql-operator/blob/main/src/charm.py) is the default entry point for a charm and has the `PostgresqlOperatorCharm` Python class which inherits from CharmBase.
+[`src/charm.py`](https://github.com/canonical/postgresql-operator/blob/main/src/charm.py) is the default entry point for a charm and has the `PostgresqlOperatorCharm` Python class which inherits from `CharmBase`.
 
-CharmBase is the base class from which all Charms are formed, defined by [Ops](https://juju.is/docs/sdk/ops) (Python framework for developing charms). See more information in [Charm](https://juju.is/docs/sdk/constructs#charm).
+`CharmBase` is the base class from which all Charms are formed, defined by [Ops](https://ops.readthedocs.io/en/latest/) (Python framework for developing charms). See more information in the [Ops documentation for `CharmBase`](https://ops.readthedocs.io/en/latest/reference/ops.html#ops.CharmBase).
 
 The `__init__` method guarantees that the charm observes all events relevant to its operation and handles them.
 
-The VM and K8s charm flavors shares the codebase via [charm libraries](https://juju.is/docs/sdk/libraries) in [lib/charms/postgresql_k8s/v0/](https://github.com/canonical/postgresql-k8s-operator/blob/main/lib/charms/postgresql_k8s/v0/postgresql.py) (of K8s flavor of the charm!):
+The VM and K8s charm flavours shares the codebase via charm libraries in [`lib/charms/postgresql_k8s/v0/`](https://github.com/canonical/postgresql-k8s-operator/blob/main/lib/charms/postgresql_k8s/v0/postgresql.py) (of K8s flavour of the charm!):
 ```text
 > charmcraft list-lib postgresql-k8s                                                                                                                                                                                                               
 Library name    API    Patch                                                                                                                                                                                                                          

diff --git a/docs/explanation/index.md b/docs/explanation/index.md
@@ -3,51 +3,32 @@
 Additional context about key concepts behind the PostgreSQL charm, including design and legacy information.
 
 ## Core concepts and design
-* [Architecture]
-* [Interfaces and endpoints]
-* [Juju]
-* [Legacy charm]
-
-## Operational concepts
-* [Units]
-* [Users]
-* [Roles]
-* [Logs]
-* [Connection pooling]
-
-## Security and hardening
-* [Security hardening guide][Security]
-  * [Cryptography]
-
-
-<!-- Links -->
-
-[Architecture]: /explanation/architecture
-[Interfaces and endpoints]: /explanation/interfaces-and-endpoints
-[Units]: /explanation/units
-[Users]: /explanation/users
-[Roles]: /explanation/roles
-[Logs]: /explanation/logs
-[Juju]: /explanation/juju
-[Legacy charm]: /explanation/legacy-charm
-[Connection pooling]: /explanation/connection-pooling
-[Security]: /explanation/security/index
-[Cryptography]: /explanation/security/cryptography
-
 
 ```{toctree}
 :titlesonly:
-:maxdepth: 2
-:glob:
-:hidden:
 
 Architecture <architecture>
 Interfaces and endpoints <interfaces-and-endpoints>
 Juju <juju>
 Legacy charm <legacy-charm>
+```
+
+## Operational concepts
+
+```{toctree}
+:titlesonly:
+
 Units <units>
 Users <users>
 Roles <roles>
 Logs <logs>
 Connection pooling <connection-pooling>
+```
+
+## Security and hardening
+
+```{toctree}
+:titlesonly:
+
 Security <security/index>
+```
diff --git a/docs/explanation/juju.md b/docs/explanation/juju.md
@@ -26,7 +26,7 @@ In the context of this documentation, the pertinent changes are as follows:
 |`run`|`exec`|
 |`run-action --wait`|`run`|
 
-See the [Juju 3.0 release notes](https://juju.is/docs/juju/roadmap#juju-3-0-0---22-oct-2022) for the comprehensive list of changes.
+See the [Juju 3.0 release notes](https://documentation.ubuntu.com/juju/3.6/reference/juju/juju-roadmap-and-releases/#juju-3-0-0-22-oct-2022) for the comprehensive list of changes.
 
 Example substitutions:
 

diff --git a/docs/explanation/legacy-charm.md b/docs/explanation/legacy-charm.md
@@ -1,9 +1,9 @@
 # Legacy charm
 
-There are [two types of charms](https://juju.is/docs/sdk/charm-taxonomy#charm-types-by-generation) stored under the same charm name `postgresql`:
+There are [two types of charms](https://documentation.ubuntu.com/juju/3.6/reference/charm/#by-generation) stored under the same charm name `postgresql`:
 
-1. [Reactive](https://juju.is/docs/sdk/charm-taxonomy#reactive)  charm in the channel `latest/stable` (called `legacy`)
-2. [Ops-based](https://juju.is/docs/sdk/ops) charm in the channel `14/stable` (called `modern`)
+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`)
 
 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).
 
@@ -35,7 +35,7 @@ The "modern" charm provides temporary support for the legacy interfaces:
 
 Reactive charms cannot be upgraded to an operator-framework-based version. To move database data, the new DB application must be launched nearby, and data should be copied from "legacy" application to the "modern" one. 
 
-Please [contact us](https://chat.charmhub.io/charmhub/channels/data-platform) if you need migration instructions.
+Please [contact us](/reference/contacts) if you need migration instructions.
 ```
 
 ## How to deploy old "legacy" PostgreSQL charm
@@ -60,7 +60,7 @@ A common error message is: `cannot deploy application "postgresql": unknown opti
 
 The legacy charm config options were not moved to the modern charm due to no need. The modern charm applies the best possible configuration automatically. 
 
-Feel free to [contact us](https://chat.charmhub.io/charmhub/channels/data-platform) about the DB tuning/config options.
+Feel free to [contact us](/reference/contacts) about the DB tuning/config options.
 
 ## Extensions supported by modern charm
 
@@ -80,7 +80,7 @@ For more information about migrating the new interface, see [this guide](/how-to
 
 At the moment, the modern charms support PostgreSQL 14 (based on Jammy/22.04 series) only.
 
-Please [contact us](https://chat.charmhub.io/charmhub/channels/data-platform) if you need different versions/series.
+Please [contact us](/reference/contacts) if you need different versions/series.
 
 ## Supported architectures
 

diff --git a/docs/explanation/logs.md b/docs/explanation/logs.md
@@ -98,5 +98,5 @@ Charmed PostgreSQL is configured to rotate PostgreSQL text logs every minute and
 
 For PostgreSQL, logs will be truncated when the week turns and the same minute of the same hour of the same weekday comes to pass. E.g. at 12:01 UTC on Monday either a new log file will be created or last week's log will be overwritten.
 
-Due to Patroni only supporting size based rotation, it has been configured to retain logs for a comparatively similar timeframe as PostgreSQL. The assumed size of a minute of Patroni logs is 600 bytes, but the estimation is bound to be imprecise. Patroni will retain 10,080 log files (for every minute of a week). The current log is `patroni.log`, when rotating Patroni will append a number to the name of the file and remove logs over the limit.
+Due to Patroni only supporting size based rotation, it has been configured to retain logs for a comparatively similar time frame as PostgreSQL. The assumed size of a minute of Patroni logs is 600 bytes, but the estimation is bound to be imprecise. Patroni will retain 10,080 log files (for every minute of a week). The current log is `patroni.log`, when rotating Patroni will append a number to the name of the file and remove logs over the limit.
 
diff --git a/docs/explanation/security/cryptography.md b/docs/explanation/security/cryptography.md
@@ -30,7 +30,7 @@ Charmed PostgreSQL can be used to deploy a secure PostgreSQL cluster that provid
 * PgBouncer connections
 * External clients connections
 
-To set up a secure connection Charmed PostgreSQL and Charmed PgBouncer need to be integrated with TLS Certificate Provider charms, e.g. self-signed-certificates operator. Certificate Signing Requests (CSRs) are generated for every unit using the tls_certificates_interface library that uses the cryptography Python library to create X.509 compatible certificates. The CSR is signed by the TLS Certificate Provider, returned to the units, and stored in Juju secret. The relation also provides the CA certificate, which is loaded into Juju secret.
+To set up a secure connection Charmed PostgreSQL and Charmed PgBouncer need to be integrated with TLS Certificate Provider charms, e.g. self-signed-certificates operator. Certificate Signing Requests (CSRs) are generated for every unit using the `tls_certificates_interface` library that uses the cryptography Python library to create X.509 compatible certificates. The CSR is signed by the TLS Certificate Provider, returned to the units, and stored in Juju secret. The relation also provides the CA certificate, which is loaded into Juju secret.
 
 Encryption at rest is currently not supported, although it can be provided by the substrate (cloud or on-premises).
 

diff --git a/docs/explanation/security/index.md b/docs/explanation/security/index.md
@@ -11,22 +11,22 @@ The environment where Charmed PostgreSQL operates can be divided into two compon
 
 ### Cloud
 
-Charmed PostgreSQL can be deployed on top of several clouds and virtualization layers:
+Charmed PostgreSQL can be deployed on top of several clouds and virtualisation layers:
 
 |Cloud|Security guides|
 | --- | --- |
 |OpenStack|[OpenStack Security Guide](https://docs.openstack.org/security-guide/)|
-|AWS|[Best Practices for Security, Identity and Compliance](https://aws.amazon.com/architecture/security-identity-compliance), [AWS security credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html#access-keys-and-secret-access-keys)|
+|AWS|[Best Practices for Security, Identity and Compliance](https://aws.amazon.com/architecture/security-identity-compliance), [AWS security credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html)|
 |Azure|[Azure security best practices and patterns](https://learn.microsoft.com/en-us/azure/security/fundamentals/best-practices-and-patterns), [Managed identities for Azure resource](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/)|
 |GCP|[Google security overview](https://cloud.google.com/docs/security)|
 
 ### 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://canonical-juju.readthedocs-hosted.com/en/latest/user/explanation/juju-security/) and the [How to harden your deployment](https://juju.is/docs/juju/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://canonical-juju.readthedocs-hosted.com/en/latest/user/explanation/juju-security/) and the [How to harden your deployment](https://documentation.ubuntu.com/juju/latest/howto/manage-your-deployment/#harden-your-deployment) guide.
 
 #### Cloud credentials
 
-When configuring cloud credentials to be used with Juju, ensure that users have correct permissions to operate at the required level. Juju superusers responsible for bootstrapping and managing controllers require elevated permissions to manage several kinds of resources, such as virtual machines, networks, storages, etc. Please refer to the links below for more information on the policies required to be used depending on the cloud.
+When configuring cloud credentials to be used with Juju, ensure that users have correct permissions to operate at the required level. Juju superusers responsible for bootstrapping and managing controllers require elevated permissions to manage several kinds of resources, such as virtual machines, networks, storage, etc. Please refer to the links below for more information on the policies required to be used depending on the cloud.
 
 |Cloud|Cloud user policies|
 | --- | --- |
@@ -39,7 +39,7 @@ When configuring cloud credentials to be used with Juju, ensure that users have
 
 It is very important that Juju users are set up with minimal permissions depending on the scope of their operations. Please refer to the [User access levels](https://juju.is/docs/juju/user-permissions) documentation for more information on the access levels and corresponding abilities.
 
-Juju user credentials must be stored securely and rotated regularly to limit the chances of unauthorized access due to credentials leakage.
+Juju user credentials must be stored securely and rotated regularly to limit the chances of unauthorised access due to credentials leakage.
 
 ## Applications
 
@@ -93,9 +93,5 @@ For details on the cryptography used by Charmed PostgreSQL, see the [Cryptograph
 
 
 ```{toctree}
-:titlesonly:
-:maxdepth: 2
-:glob:
-:hidden:
-
 Cryptography <cryptography>
+```
Original file line number	Diff line number	Diff line change
Expand Up		@@ -98,5 +98,5 @@ Charmed PostgreSQL is configured to rotate PostgreSQL text logs every minute and

		For PostgreSQL, logs will be truncated when the week turns and the same minute of the same hour of the same weekday comes to pass. E.g. at 12:01 UTC on Monday either a new log file will be created or last week's log will be overwritten.

		Due to Patroni only supporting size based rotation, it has been configured to retain logs for a comparatively similar timeframe as PostgreSQL. The assumed size of a minute of Patroni logs is 600 bytes, but the estimation is bound to be imprecise. Patroni will retain 10,080 log files (for every minute of a week). The current log is `patroni.log`, when rotating Patroni will append a number to the name of the file and remove logs over the limit.
		Due to Patroni only supporting size based rotation, it has been configured to retain logs for a comparatively similar time frame as PostgreSQL. The assumed size of a minute of Patroni logs is 600 bytes, but the estimation is bound to be imprecise. Patroni will retain 10,080 log files (for every minute of a week). The current log is `patroni.log`, when rotating Patroni will append a number to the name of the file and remove logs over the limit.