diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index 52d5f8c616..842cb0ceea 100644 --- 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 \ No newline at end of file diff --git a/docs/.sphinx/spellingcheck.yaml b/docs/.sphinx/spellingcheck.yaml index 9ee9ae7130..33aefd5e1b 100644 --- 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 index 8224800db0..eba2ae7345 100644 --- 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 index 5a518f2569..0690ecc1d9 100644 --- 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. ### 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 index 3218d9baff..49990c65f1 100644 --- 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] - - - - -[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 Interfaces and endpoints Juju Legacy charm +``` + +## Operational concepts + +```{toctree} +:titlesonly: + Units Users Roles Logs Connection pooling +``` + +## Security and hardening + +```{toctree} +:titlesonly: + Security +``` \ No newline at end of file diff --git a/docs/explanation/juju.md b/docs/explanation/juju.md index 0a40ae0069..ce57b981cc 100644 --- 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 index 6a1afbde03..edbbc3df7e 100644 --- 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 index 3bf4b00997..ecf91c03fb 100644 --- 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 index efc81e2f7e..ff4933a27c 100644 --- 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 index 8b82c56161..813cfcb0f9 100644 --- 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 +``` \ No newline at end of file diff --git a/docs/explanation/units.md b/docs/explanation/units.md index f53728bc25..9a8890c0eb 100644 --- a/docs/explanation/units.md +++ b/docs/explanation/units.md @@ -13,7 +13,7 @@ It is recommended to use 3+ units cluster size in production (due to [Raft conse All SQL transactions have to be confirmed by all Sync Standby unit(s) before Primary unit commit transaction to the client. Therefore, high-performance and high-availability is a trade-off between "sync standby" and "replica" unit count in the cluster. -Starting from revision 561, all Charmed PostgreSQL units are configured as Sync Standby members by default. It provides better guarantees for the data survival when two of three units gone simultaneously. Users can re-configure the necessary synchronous units count using Juju config option '[synchronous_node_count](https://charmhub.io/postgresql/configurations?channel=14/stable#synchronous_node_count)'. +Starting from revision 561, all Charmed PostgreSQL units are configured as Sync Standby members by default. It provides better guarantees for the data survival when two of three units gone simultaneously. Users can re-configure the necessary synchronous units count using Juju config option '[synchronous_node_count](https://charmhub.io/postgresql/configurations?channel=14/stable)'. ## Primary diff --git a/docs/explanation/users.md b/docs/explanation/users.md index 890092aff3..cceffbd9ed 100644 --- a/docs/explanation/users.md +++ b/docs/explanation/users.md @@ -14,7 +14,7 @@ The operator uses the following internal DB users: * `postgres` - the [initial/default](/how-to/manage-passwords) PostgreSQL user. Used for very initial bootstrap only. * `operator` - the user that `charm.py` uses to manage database/cluster. * `replication` - the user performs replication between database PostgreSQL cluster members. -* `rewind` - the internal user for synchronizing a PostgreSQL cluster with another copy of the same cluster. +* `rewind` - the internal user for synchronising a PostgreSQL cluster with another copy of the same cluster. * `monitoring` - the user for [COS integration](/how-to/monitoring-cos/enable-monitoring). * `backups` - the user to [perform/list/restore backups](/how-to/back-up-and-restore/create-a-backup). @@ -117,5 +117,5 @@ Read more about the supported charm interfaces in [](/explanation/interfaces-and The operator considers Identity users all those that are automatically created when the LDAP integration is enabled, or in other words, the [GLAuth](https://charmhub.io/glauth-k8s) charm is related/integrated. -When synchronized from the LDAP server, these users do not have any permissions by default, so the LDAP group they belonged to must be mapped to a PostgreSQL pre-defined authorization role by using the `ldap_map` configuration option. +When synchronised from the LDAP server, these users do not have any permissions by default, so the LDAP group they belonged to must be mapped to a PostgreSQL pre-defined authorisation role by using the `ldap_map` configuration option. diff --git a/docs/how-to/back-up-and-restore/configure-s3-radosgw.md b/docs/how-to/back-up-and-restore/configure-s3-radosgw.md index d2fb5f3fe3..170819cd74 100644 --- a/docs/how-to/back-up-and-restore/configure-s3-radosgw.md +++ b/docs/how-to/back-up-and-restore/configure-s3-radosgw.md @@ -9,7 +9,7 @@ This guide will teach you how to deploy and configure the s3-integrator charm on ``` ```{caution} -The Charmed PostgreSQL backup tool [pgBackRest](https://pgbackrest.org/) can currently only interact with S3-compatible storages if they work with [SSL/TLS](https://github.com/pgbackrest/pgbackrest/issues/2340). +The Charmed PostgreSQL backup tool [pgBackRest](https://pgbackrest.org/) can currently only interact with S3-compatible storage if they work with [SSL/TLS](https://github.com/pgbackrest/pgbackrest/issues/2340). Backup via plain HTTP is currently not supported. ``` diff --git a/docs/how-to/back-up-and-restore/index.md b/docs/how-to/back-up-and-restore/index.md index e6ef0f7020..f3f342d0b0 100644 --- a/docs/how-to/back-up-and-restore/index.md +++ b/docs/how-to/back-up-and-restore/index.md @@ -11,3 +11,4 @@ Create a backup Restore a backup Manage backup retention Migrate a cluster +``` \ No newline at end of file diff --git a/docs/how-to/back-up-and-restore/manage-backup-retention.md b/docs/how-to/back-up-and-restore/manage-backup-retention.md index c73b30afbb..123d90f67f 100644 --- a/docs/how-to/back-up-and-restore/manage-backup-retention.md +++ b/docs/how-to/back-up-and-restore/manage-backup-retention.md @@ -38,7 +38,7 @@ This configuration will be enforced in **every** Charmed PostgreSQL application ```{caution} The retention is **not** enforced automatically once a backup is older than the set amount of days. Backups older than the set retention time will only get expired only once a newer backup is created. -This behavior avoids complete backup deletion if no newer backups have been created in the charm. +This behaviour avoids complete backup deletion if no newer backups have been created in the charm. ``` The s3-integrator charm accepts many [configurations](https://charmhub.io/s3-integrator/configure) - enter whichever are necessary for your S3 storage. diff --git a/docs/how-to/cross-regional-async-replication/index.md b/docs/how-to/cross-regional-async-replication/index.md index dcf32076f3..12dd247896 100644 --- a/docs/how-to/cross-regional-async-replication/index.md +++ b/docs/how-to/cross-regional-async-replication/index.md @@ -4,7 +4,7 @@ Cross-regional (or multi-server) asynchronous replication focuses on disaster re ## Prerequisites * Juju `v.3.4.2+` -* Make sure your machine(s) fulfill the [system requirements](/reference/system-requirements) +* Make sure your machine(s) fulfil the [system requirements](/reference/system-requirements) ### Substrate dependencies @@ -18,24 +18,16 @@ The following table shows the source and target controller/model combinations th ## Guides -* [How to set up clusters for cross-regional async replication](/how-to/cross-regional-async-replication/set-up-clusters) -* [How to integrate with a client application](/how-to/cross-regional-async-replication/integrate-with-a-client-app) -* [How to remove or recover a cluster](/how-to/cross-regional-async-replication/remove-or-recover-a-cluster) - * [Switchover](/how-to/cross-regional-async-replication/remove-or-recover-a-cluster) - * [Detach](/how-to/cross-regional-async-replication/remove-or-recover-a-cluster) - * [Recover](/how-to/cross-regional-async-replication/remove-or-recover-a-cluster) - - -[check]: https://img.shields.io/badge/%E2%9C%93-brightgreen -[cross]: https://img.shields.io/badge/x-white - - ```{toctree} :titlesonly: :maxdepth: 2 -:glob: -:hidden: Set up clusters Integrate with a client app Remove or recover a cluster +``` + +[check]: https://img.shields.io/badge/%E2%9C%93-brightgreen +[cross]: https://img.shields.io/badge/x-white + + diff --git a/docs/how-to/cross-regional-async-replication/integrate-with-a-client-app.md b/docs/how-to/cross-regional-async-replication/integrate-with-a-client-app.md index 13f2c761bb..f9f6f3f46c 100644 --- a/docs/how-to/cross-regional-async-replication/integrate-with-a-client-app.md +++ b/docs/how-to/cross-regional-async-replication/integrate-with-a-client-app.md @@ -4,7 +4,7 @@ This guide will show you how to integrate a client application with a cross-regi ## Prerequisites * Juju `v.3.4.2+` -* Make sure your machine(s) fulfill the [system requirements](/reference/system-requirements) +* Make sure your machine(s) fulfil the [system requirements](/reference/system-requirements) * See [supported target/source model relationships](/how-to/cross-regional-async-replication/index). * A cross-regional async replication setup * See [How to set up clusters](/how-to/cross-regional-async-replication/set-up-clusters) diff --git a/docs/how-to/cross-regional-async-replication/remove-or-recover-a-cluster.md b/docs/how-to/cross-regional-async-replication/remove-or-recover-a-cluster.md index aa4d400dc6..6cf08bbdc6 100644 --- a/docs/how-to/cross-regional-async-replication/remove-or-recover-a-cluster.md +++ b/docs/how-to/cross-regional-async-replication/remove-or-recover-a-cluster.md @@ -4,7 +4,7 @@ This guide will cover how to manage clusters using an example PostgreSQL deploym ## Prerequisites * Juju `v.3.4.2+` -* Make sure your machine(s) fulfill the [system requirements](/reference/system-requirements) +* Make sure your machine(s) fulfil the [system requirements](/reference/system-requirements) * See [supported target/source model relationships](/how-to/cross-regional-async-replication/index). * A cross-regional async replication setup * See [How to set up clusters](/how-to/cross-regional-async-replication/set-up-clusters) diff --git a/docs/how-to/cross-regional-async-replication/set-up-clusters.md b/docs/how-to/cross-regional-async-replication/set-up-clusters.md index 8328e7b49b..7535e93f43 100644 --- a/docs/how-to/cross-regional-async-replication/set-up-clusters.md +++ b/docs/how-to/cross-regional-async-replication/set-up-clusters.md @@ -6,7 +6,7 @@ This guide will show you the basics of initiating a cross-regional async setup u ## Prerequisites * Juju `v.3.4.2+` -* Make sure your machine(s) fulfill the [system requirements](/reference/system-requirements) +* Make sure your machine(s) fulfil the [system requirements](/reference/system-requirements) * See [supported target/source model relationships](/how-to/cross-regional-async-replication/index). ## Deploy diff --git a/docs/how-to/deploy/air-gapped.md b/docs/how-to/deploy/air-gapped.md index 1d3a98781a..4c8469840b 100644 --- a/docs/how-to/deploy/air-gapped.md +++ b/docs/how-to/deploy/air-gapped.md @@ -9,23 +9,23 @@ Canonical does not prescribe how you should set up your specific air-gapped envi * A VM/hardware resources available for Juju. * DNS is configured to the local nameservers. -* [Juju is configured](https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/#configure-juju) to use local air-gapped services. +* DNS is configured to the local nameservers. +* [Juju is configured](https://documentation.ubuntu.com/enterprise-store/main/how-to/airgap-charmhub/#configure-juju) to use local air-gapped services. * The [`store-admin`](https://snapcraft.io/store-admin) tool is installed and configured. -* [Air-gapped CharmHub](https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/) is installed and running. -* [Air-gapped Snap Store Proxy](https://documentation.ubuntu.com/snap-store-proxy/) is installed and running. +* [Air-gapped Charmhub](https://documentation.ubuntu.com/enterprise-store/main/how-to/airgap-charmhub/#offline-charmhub-configuration) is installed and running. * Local APT and LXD Images caches are reachable. ## Air-gapped day-to-day example ### 1. Export snaps and charms -Exporting VM SNAPs and Charms and are currently independent processes. The `store-admin` tool is designed to simplify the process. +Exporting VM snaps and charms are currently independent processes. The `store-admin` tool is designed to simplify the process. -Future improvements are planned to the `store-admin` tool so that it could potentially export all necessary SNAP resource(s) from the official SnapStore with Charms simultaneously. Other planned improvements include supporting the export of specific charm and resource by revisions ([PF-5369](https://warthogs.atlassian.net/browse/PF-5369), [PF-5185](https://warthogs.atlassian.net/browse/PF-5185)). +Future improvements are planned to the `store-admin` tool so that it could potentially export all necessary snap resource(s) from the official Snap Store with charms simultaneously. Other planned improvements include supporting the export of specific charm and resource by revisions ([PF-5369](https://warthogs.atlassian.net/browse/PF-5369), [PF-5185](https://warthogs.atlassian.net/browse/PF-5185)). #### Charms - The necessary charm(s) can be exported as bundle or independently (charm-by-charm). See the Snap Proxy documentation: -* [Offline Charmhub configuration > Export charm bundle](https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/#export-charm-bundles) -* [Offline Charmhub configuration > Export charms](https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/#export-charms) +The necessary charm(s) can be exported as bundle or independently (charm-by-charm). See the Snap Proxy documentation: +* [Offline Charmhub configuration > Export charm bundle](https://documentation.ubuntu.com/enterprise-store/main/how-to/airgap-charmhub/#export-charm-bundles) +* [Offline Charmhub configuration > Export charms](https://documentation.ubuntu.com/enterprise-store/main/how-to/airgap-charmhub/#export-charms) The bundle export example: @@ -60,8 +60,8 @@ Successfully exported charm bundle postgresql-bundle: /home/ubuntu/snap/store-ad ``` -#### SNAPs -Usually charms require SNAPs (and some manually pin them). For the manual SNAP exports, follow the official Snap Store Proxy documentation: [Offline Charmhub configuration > Export SNAP](https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/#export-snap-resources). Data team is shipping the mapping [snap.yaml](https://github.com/canonical/postgresql-bundle/blob/main/releases/latest/) to the published [bundle.yaml](https://github.com/canonical/postgresql-bundle/blob/main/releases/latest/): +#### Snaps +Usually charms require snaps (and some manually pin them). For the manual snap exports, follow the official Snap Store Proxy documentation: [Offline Charmhub configuration > Export snap](https://documentation.ubuntu.com/enterprise-store/main/how-to/airgap-charmhub/#export-snap-resources). Data team is shipping the mapping [snap.yaml](https://github.com/canonical/postgresql-bundle/blob/main/releases/latest/) to the published [bundle.yaml](https://github.com/canonical/postgresql-bundle/blob/main/releases/latest/): > **Warning**: always use snap.yaml and bundle.yaml from the same Git commit (to match each other)! @@ -104,7 +104,7 @@ Always check [checksum](https://en.wikipedia.org/wiki/Checksum) for the transfer ### 3. Import snaps and charms - Import the [snap](https://documentation.ubuntu.com/snap-store-proxy/en/airgap/#importing-pushing-snaps) and [charm](https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/#import-packages) blobs into local air-gapped CharmHub: +Import the [snap](https://documentation.ubuntu.com/enterprise-store/main/how-to/airgap/#importing-pushing-snaps) and [charm](https://documentation.ubuntu.com/enterprise-store/main/how-to/airgap-charmhub/#import-packages) blobs into local air-gapped Charmhub: When importing machine charms that depend on a snap for functionality, you must first manually import the required snap. @@ -114,7 +114,7 @@ sudo snap-store-proxy push-snap /var/snap/snap-store-proxy/common/snaps-to-push/ sudo snap-store-proxy push-charm-bundle /var/snap/snap-store-proxy/common/charms-to-push/postgresql-bundle-20241003T104903.tar.gz ``` -When [re-importing](https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/#import-packages) charms or importing other revisions, make sure to provide the `--push-channel-map`. +When re-importing charms or importing other revisions, make sure to provide the `--push-channel-map`. ### 4. Deploy PostgreSQL @@ -132,10 +132,10 @@ Use [the official release notes](/reference/releases) as a reference. ## Additional resources -* https://docs.ubuntu.com/snap-store-proxy/en/airgap -* https://documentation.ubuntu.com/snap-store-proxy/ -* https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/ -* https://ubuntu.com/kubernetes/docs/install-offline +* `https://docs.ubuntu.com/snap-store-proxy/en/airgap` +* `https://documentation.ubuntu.com/snap-store-proxy/` +* `https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/` +* `https://ubuntu.com/kubernetes/docs/install-offline` * [Charmed Kubeflow > Install in an airgapped environment](https://charmed-kubeflow.io/docs/install-in-an-airgapped-environment) * [Wikipedia > Air gap (networking)](https://en.wikipedia.org/wiki/Air_gap_(networking)) diff --git a/docs/how-to/deploy/aws-ec2.md b/docs/how-to/deploy/aws-ec2.md index 24b88082ed..83f8d79e78 100644 --- a/docs/how-to/deploy/aws-ec2.md +++ b/docs/how-to/deploy/aws-ec2.md @@ -95,7 +95,8 @@ to create a new model to deploy workloads. ``` -You can check the [AWS EC2 instance availability](https://us-east-1.console.aws.amazon.com/ec2/home?region=us-east-1#Instances:instanceState=running) (ensure the right AWS region chosen!): + +You can check the AWS EC2 instance availability (ensure the right AWS region chosen!): ![image|690x118](aws-ec2-availability.png) Create a new Juju model: @@ -184,7 +185,7 @@ From here you can [use/scale/backup/restore/refresh](/tutorial/index) your newly ## Expose database (optional) -If necessary to access DB from outside of AWS (warning: [opening ports to public is risky](https://www.beyondtrust.com/blog/entry/what-is-an-open-port-what-are-the-security-implications)) open the AWS firewall using the simple [juju expose](https://juju.is/docs/juju/juju-expose) functionality: +If necessary to access DB from outside of AWS (warning: opening ports to public is risky) open the AWS firewall using the simple [juju expose](https://juju.is/docs/juju/juju-expose) functionality: ```text juju expose postgresql ``` diff --git a/docs/how-to/deploy/azure.md b/docs/how-to/deploy/azure.md index 9d3e1ef046..2439484116 100644 --- a/docs/how-to/deploy/azure.md +++ b/docs/how-to/deploy/azure.md @@ -142,7 +142,7 @@ Now you can run to create a new model to deploy workloads. ``` -You can check the [Azure instances availability](https://portal.azure.com/#browse/Microsoft.Compute%2FVirtualMachines): +You can check the [Azure instances availability](https://portal.azure.com/#browse/Microsoft.Compute/VirtualMachines): ![image|689x313](azure-availability.png) @@ -238,7 +238,7 @@ juju expose postgresql ``` ```{caution} -Be wary that [opening ports to the public is risky](https://www.beyondtrust.com/blog/entry/what-is-an-open-port-what-are-the-security-implications). +Be wary that opening ports to the public is risky. ``` Once exposed, you can connect your database using the same credentials as above. This time use the Azure VM public IP assigned to the PostgreSQL instance. You can see this with `juju status`: diff --git a/docs/how-to/deploy/gce.md b/docs/how-to/deploy/gce.md index 6f5618aafd..cd7839a950 100644 --- a/docs/how-to/deploy/gce.md +++ b/docs/how-to/deploy/gce.md @@ -56,7 +56,7 @@ created key [aaaaaaa....aaaaaaa] of type [json] as [sa-private-key.json] for [ju ## Bootstrap Juju controller on GCE -Move the newly exported GCloud json file into a snap-accessible folder due to a known Juju [issue](https://bugs.launchpad.net/juju/+bug/2007575). +Move the newly exported GCloud JSON file into a snap-accessible folder due to a known Juju [issue](https://bugs.launchpad.net/juju/+bug/2007575). ```text @@ -266,7 +266,7 @@ Remove GCloud credentials from Juju: > juju remove-credential google juju-gce-account ``` -Finally, remove GCloud jsonfile user credentials (to avoid forgetting and leaking): +Finally, remove GCloud JSON file user credentials (to avoid forgetting and leaking): ```text rm -f /var/snap/juju/common/sa-private-key.json ``` diff --git a/docs/how-to/deploy/index.md b/docs/how-to/deploy/index.md index a916ed60a4..d2108aa708 100644 --- a/docs/how-to/deploy/index.md +++ b/docs/how-to/deploy/index.md @@ -44,7 +44,7 @@ See also: * [How to connect from outside the local network] ## Airgapped -[How to deploy in an offline or air-gapped environment] goes over the special configuration steps for installing PostgreSQL in an airgapped environment via CharmHub and the Snap Store Proxy. +[How to deploy in an offline or air-gapped environment] goes over the special configuration steps for installing PostgreSQL in an airgapped environment via Charmhub and the Snap Store Proxy. ## Cluster-cluster replication @@ -53,7 +53,7 @@ Cluster-cluster, cross-regional, or multi-server asynchronous replication focuse The [Cross-regional async replication] guide goes through the steps to set up clusters for cluster-cluster replication, integrate with a client, and remove or recover a failed cluster. ## Juju storage -Charmed PostgreSQL uses the [Juju storage](https://documentation.ubuntu.com/juju/3.6/reference/storage/) abstraction to utilize data volume provided by different clouds while keeping the same UI/UX for end users. +Charmed PostgreSQL uses the [Juju storage](https://documentation.ubuntu.com/juju/3.6/reference/storage/) abstraction to use data volume provided by different clouds while keeping the same UI/UX for end users. See: [How to deploy on juju storage] diff --git a/docs/how-to/deploy/juju-storage.md b/docs/how-to/deploy/juju-storage.md index 7aa178ccb8..3573210fd4 100644 --- a/docs/how-to/deploy/juju-storage.md +++ b/docs/how-to/deploy/juju-storage.md @@ -1,6 +1,6 @@ # Deploy on Juju storage -Charmed PostgreSQL uses the [Juju storage](https://documentation.ubuntu.com/juju/3.6/reference/storage/) abstraction to utilize data volume provided by different [clouds](https://documentation.ubuntu.com/juju/3.6/reference/cloud/#cloud) while keeping the same UI/UX for end users. +Charmed PostgreSQL uses the [Juju storage](https://documentation.ubuntu.com/juju/3.6/reference/storage/) abstraction to utilise data volume provided by different [clouds](https://documentation.ubuntu.com/juju/3.6/reference/cloud/#cloud) while keeping the same UI/UX for end users. Charmed PostgreSQL 14 supports a single storage: `pgdata`. diff --git a/docs/how-to/deploy/maas.md b/docs/how-to/deploy/maas.md index 40650674d0..a904e6edb6 100644 --- a/docs/how-to/deploy/maas.md +++ b/docs/how-to/deploy/maas.md @@ -1,6 +1,6 @@ # How to deploy on MAAS -This guide aims to provide a quick start to deploying Charmed PostgreSQL on MAAS. It summarizes the instructions from the [Build a MAAS and LXD environment with Multipass Tutorial](https://discourse.maas.io/t/5360) to set up and tear down a **playground environment**. +This guide aims to provide a quick start to deploying Charmed PostgreSQL on MAAS. It summarises the instructions from the [Build a MAAS and LXD environment with Multipass Tutorial](https://discourse.maas.io/t/5360) to set up and tear down a **playground environment**. If you want to deploy PostgreSQL on MAAS in a **production environment**, refer to the official [Bootstrap MAAS Tutorial](https://maas.io/docs/tutorial-bootstrapping-maas) followed by the [Charmed PostgreSQL Tutorial](/tutorial/index). @@ -15,7 +15,7 @@ sudo snap install multipass wget -qO- https://raw.githubusercontent.com/canonical/maas-multipass/main/maas.yml \ | multipass launch --name maas -c8 -m12GB -d50GB --cloud-init - ``` -> The wget command provides a [cloud-init](https://github.com/canonical/maas-multipass/blob/main/maas.yml) file that will set up the VM's LXD and MAAS environment. +> The wget command provides a [cloud-init](https://github.com/canonical/maas-multipass/blob/main/maas.yml) file that will set up the LXD and MAAS environment. ## Configure MAAS diff --git a/docs/how-to/deploy/sunbeam.md b/docs/how-to/deploy/sunbeam.md index 8f55b35fe7..6d1b443a75 100644 --- a/docs/how-to/deploy/sunbeam.md +++ b/docs/how-to/deploy/sunbeam.md @@ -20,7 +20,7 @@ This guide assumes you have: Follow the official OpenStack guide: [Single-node deployment][Single-node guided]. -Pay attention to the `Caution` and `Note` sections - the `/etc/hosts` will require a [manual fqdn fix](https://github.com/canonical/multipass/issues/3277#issuecomment-2471434029). +Pay attention to the `Caution` and `Note` sections - the `/etc/hosts` will require a [manual {spellexception}`fqdn` fix](https://github.com/canonical/multipass/issues/3277#issuecomment-2471434029). ## Enable OpenStack images auto-sync @@ -30,7 +30,7 @@ Follow the official [Images Sync] guide to enable auto-sync and wait for the ima Follow the MicroStack guide [Manage workloads with Juju] from the beginning, and stop after the section "Create a Juju controller". -To summarize, the relevant sections are: +To summarise, the relevant sections are: * Set up the bastion * Install and configure the Juju client * Create a Juju controller diff --git a/docs/how-to/deploy/terraform.md b/docs/how-to/deploy/terraform.md index c3ba64c849..745fcfa211 100644 --- a/docs/how-to/deploy/terraform.md +++ b/docs/how-to/deploy/terraform.md @@ -1,6 +1,6 @@ # How to deploy using Terraform -[Terraform](https://www.terraform.io/) is an infrastructure automation tool to provision and manage resources in clouds or data centers. To deploy Charmed PostgreSQL using Terraform and Juju, you can use the [Juju Terraform Provider](https://registry.terraform.io/providers/juju/juju/latest). +[Terraform](https://www.terraform.io/) is an infrastructure automation tool to provision and manage resources in clouds or data centres. To deploy Charmed PostgreSQL using Terraform and Juju, you can use the [Juju Terraform Provider](https://registry.terraform.io/providers/juju/juju/latest). The easiest way is to start from [these examples of terraform modules](https://github.com/canonical/terraform-modules) prepared by Canonical. This page will guide you through a deployment using an example module for PostgreSQL on machines. diff --git a/docs/how-to/deploy/tls-vip-access.md b/docs/how-to/deploy/tls-vip-access.md index 9621beca1e..9e373110a2 100644 --- a/docs/how-to/deploy/tls-vip-access.md +++ b/docs/how-to/deploy/tls-vip-access.md @@ -15,7 +15,7 @@ The basic requirements to follow along with this example setup are the following * A fully deployed and running Juju machine environment * See the [PostgreSQL Tutorial](/tutorial/index) for a quick setup with Multipass * See the official [Juju deployment guide](https://juju.is/docs/juju/tutorial#deploy) for more details -* A spare virtual IP address for [hacluster](https://discourse.charmhub.io/t/pgbouncer-how-to-externally-access/15741#using-a-virtual-ip-to-connect-to-pgbouncer) +* A spare virtual IP address for [`hacluster`](https://discourse.charmhub.io/t/pgbouncer-how-to-externally-access/15741) * See the PgBouncer guide: [How to use a VIP to connect to PgBouncer](https://charmhub.io/pgbouncer/docs/h-external-access?channel=1/stable) * DNS record pointing to VIP above (`my-tls-example-db.local` is used as an example here) @@ -32,7 +32,7 @@ This setup deploys the following components: * The [`postgresql`](https://charmhub.io/postgresql) charm (3 units, as a single cluster). * The [`self-signed-certificates`](https://charmhub.io/self-signed-certificates) charm as the TLS provider. * Note that this is not suitable for production deployments. See the guide: [Security with X.509 certificates](https://charmhub.io/topics/security-with-x-509-certificates). -* The [`data-integrator`](https://charmhub.io/data-integrator) charm as a [principal](https://juju.is/docs/sdk/charm-taxonomy#principal-charms) charm for the [subordinated](https://juju.is/docs/sdk/charm-taxonomy#subordinate-charms) charms below (3 units for high availability): +* The [`data-integrator`](https://charmhub.io/data-integrator) charm as a [principal](https://documentation.ubuntu.com/juju/3.6/reference/charm/#principal) charm for the [subordinated](https://documentation.ubuntu.com/juju/3.6/reference/charm/#subordinate) charms below (3 units for high availability): * The latest [`pgbouncer`](https://charmhub.io/pgbouncer?channel=1/stable) charm as a load-balancer and connection pooler (3 units). * The [`hacluster`](https://charmhub.io/hacluster) charm for VIP handling (3 units are the minimum for HA). * (optional) The COS [`grafana-agent`](https://charmhub.io/grafana-agent) charm for Monitoring purposes. @@ -174,7 +174,7 @@ At this point, Juju is responsible for the health of the clusters/applications: * The PostgreSQL charm will restart the workload if PostgreSQL is not healthy. * The Juju agent will restart the unit/vm/container if it is no longer reachable/healthy (in the same AZ). * The Juju controller will make sure Juju agent is up and running and charm is healthy. -* The HACluster charm will make sure the VIP is always reachable and routes to a single PgBouncer. +* The HA Cluster charm will make sure the VIP is always reachable and routes to a single PgBouncer. * PgBouncer will balance incoming connections and makes sure write traffic goes to the primary PostgreSQL unit. * The TLS operator (in this example, the `self-signed-certificates` charm) is responsible for providing all components with signed ready-to-use TLS artifacts. diff --git a/docs/how-to/development/index.md b/docs/how-to/development/index.md index fd79237643..abbefea037 100644 --- a/docs/how-to/development/index.md +++ b/docs/how-to/development/index.md @@ -8,3 +8,4 @@ Integrate with your charm Migrate data via pg_dump Migrate data via backup/restore +``` \ No newline at end of file diff --git a/docs/how-to/development/integrate-with-your-charm.md b/docs/how-to/development/integrate-with-your-charm.md index 94221b4a4f..997480707d 100644 --- a/docs/how-to/development/integrate-with-your-charm.md +++ b/docs/how-to/development/integrate-with-your-charm.md @@ -12,7 +12,7 @@ Legacy charm details are described [here](/explanation/legacy-charm). ## Integrate your charm with PostgreSQL -**For an introduction** to the concepts of Juju integrations, see [Juju | Integration](https://juju.is/docs/juju/integration). +**For an introduction** to the concepts of Juju integrations, see [Juju | Integration](https://documentation.ubuntu.com/juju/3.6/reference/relation/). **For a detailed tutorial** about integrating your charm with the PostgreSQL charm, refer to [Juju | Integrate your charm with PostgreSQL](https://juju.is/docs/sdk/integrate-your-charm-with-postgresql). @@ -34,7 +34,7 @@ Legacy charm details are described [here](/explanation/legacy-charm). **Is there a charm library available, or does my charm need to compile the postgresql relation data on its own?** >Yes, a library is available: [data-platform-libs](https://github.com/canonical/data-platform-libs). The integration is trivial: [example](https://github.com/nextcloud-charmers/nextcloud-charms/pull/78). -**How do I obtain the database url/uri?** +**How do I obtain the database URL/URI?** >This feature is [planned](https://warthogs.atlassian.net/browse/DPE-2278) but currently missing. > >Meanwhile, use [this](https://github.com/nextcloud-charmers/nextcloud-charms/blob/91f9eebb4d40eaaff9c2f7513f66980df75c2a3b/operator-nextcloud/src/charm.py#L610-L631) example or refer to the function below. diff --git a/docs/how-to/development/migrate-data-via-pg-dump.md b/docs/how-to/development/migrate-data-via-pg-dump.md index b7858b93ae..46b2195adc 100644 --- a/docs/how-to/development/migrate-data-via-pg-dump.md +++ b/docs/how-to/development/migrate-data-via-pg-dump.md @@ -35,7 +35,7 @@ Always test migration in a safe environment before performing it in production! - **[Your application is compatible](/explanation/legacy-charm) with Charmed PostgreSQL VM** - A client machine with access to the deployed legacy charm -- `juju v.2.9` or later (check [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#juju-3-0-0---22-oct-2022) for more information about key differences) +- `juju v.2.9` or later (check [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 more information about key differences) - Enough storage in the cluster to support backup/restore of the databases. ## Obtain existing database credentials diff --git a/docs/how-to/enable-ldap.md b/docs/how-to/enable-ldap.md index bda04f3800..5e407f81f1 100644 --- a/docs/how-to/enable-ldap.md +++ b/docs/how-to/enable-ldap.md @@ -1,6 +1,6 @@ # How to enable LDAP authentication -The Lightweight Directory Access Protocol (LDAP) enables centralized authentication for PostgreSQL clusters, reducing the overhead of managing local credentials and access policies. +The Lightweight Directory Access Protocol (LDAP) enables centralised authentication for PostgreSQL clusters, reducing the overhead of managing local credentials and access policies. This guide goes over the steps to integrate LDAP as an authentication method with the PostgreSQL charm, all within the Juju ecosystem. @@ -107,7 +107,7 @@ juju integrate postgresql:receive-ca-cert send-ca-cert ## Map LDAP users to PostgreSQL -To have LDAP users available in PostgreSQL, provide a comma separated list of LDAP groups to already created PostgreSQL authorization groups. To create those groups before hand, refer to the [data integrator charm](https://charmhub.io/data-integrator). +To have LDAP users available in PostgreSQL, provide a comma separated list of LDAP groups to already created PostgreSQL authorisation groups. To create those groups before hand, refer to the [data integrator charm](https://charmhub.io/data-integrator). ```text juju config postgresql ldap_map="=" diff --git a/docs/how-to/enable-plugins-extensions/index.md b/docs/how-to/enable-plugins-extensions/index.md index 9e3b372321..912fc38537 100644 --- a/docs/how-to/enable-plugins-extensions/index.md +++ b/docs/how-to/enable-plugins-extensions/index.md @@ -42,4 +42,5 @@ Not all PostgreSQL extensions are available. The list of supported extensions is :glob: :hidden: -Enable TimescaleDB \ No newline at end of file +Enable TimescaleDB +``` \ No newline at end of file diff --git a/docs/how-to/external-network-access.md b/docs/how-to/external-network-access.md index d11e2480f5..d3e6dc123d 100644 --- a/docs/how-to/external-network-access.md +++ b/docs/how-to/external-network-access.md @@ -1,12 +1,12 @@ # How to connect from outside the local network -This page summarizes resources for setting up deployments where an external application must connect to a PostgreSQL database from outside the local area network. +This page summarises resources for setting up deployments where an external application must connect to a PostgreSQL database from outside the local area network. ## External application (non-Juju) **Use case**: The client application is a non-Juju application outside of the local area network where Juju and the database are running. -There are many possible ways to connect the Charmed PostgreSQL database from outside of the LAN where the database cluster is located. The available options are heavily dependent on the cloud/hardware/virtualization in use. +There are many possible ways to connect the Charmed PostgreSQL database from outside of the LAN where the database cluster is located. The available options are heavily dependent on the cloud/hardware/virtualisation in use. One of the possible options is to use [virtual IP addresses (VIP)](https://en.wikipedia.org/wiki/Virtual_IP_address) which the charm PgBouncer provides with assistance from the charm/interface `hacluster`. Please follow the [PgBouncer documentation](https://charmhub.io/pgbouncer/docs/h-external-access) for such configuration. diff --git a/docs/how-to/index.md b/docs/how-to/index.md index 12c5525a4a..6253aa03a9 100644 --- a/docs/how-to/index.md +++ b/docs/how-to/index.md @@ -128,4 +128,4 @@ Monitoring (COS) Upgrade Cross-regional async replication Development - +``` diff --git a/docs/how-to/manage-passwords.md b/docs/how-to/manage-passwords.md index b6317f1739..41d81ca2ef 100644 --- a/docs/how-to/manage-passwords.md +++ b/docs/how-to/manage-passwords.md @@ -12,7 +12,7 @@ juju run postgresql/leader get-password ## Set password -To change the operator's password to a new, randomized password: +To change the operator's password to a new, randomised password: ```text juju run postgresql/leader set-password diff --git a/docs/how-to/monitoring-cos/enable-alert-rules.md b/docs/how-to/monitoring-cos/enable-alert-rules.md index dab0c5dbd4..b9708d8a6d 100644 --- a/docs/how-to/monitoring-cos/enable-alert-rules.md +++ b/docs/how-to/monitoring-cos/enable-alert-rules.md @@ -21,7 +21,7 @@ For information about accessing and managing COS Alert Rules, refer to the [COS The following section is an example of the [Pushover](https://pushover.net/) alerts aggregator. -The first step is to create a new account on Pushover (or use an existing one). The goal is to have the 'user key' and 'token' to authorize alerts for the Pushover application. Follow this straightforward [Pushover guide](https://support.pushover.net/i175-how-to-get-a-pushover-api-or-pushover-application-token). +The first step is to create a new account on Pushover (or use an existing one). The goal is to have the 'user key' and 'token' to authorise alerts for the Pushover application. Follow this straightforward [Pushover guide](https://support.pushover.net/i175-how-to-get-a-pushover-api-or-pushover-application-token). Next, create a new [COS Alert Manager](https://charmhub.io/alertmanager-k8s) config (replace `user_key` and `token` with yours): ```text diff --git a/docs/how-to/monitoring-cos/enable-monitoring.md b/docs/how-to/monitoring-cos/enable-monitoring.md index 5c2386316b..3c1c40f34c 100644 --- a/docs/how-to/monitoring-cos/enable-monitoring.md +++ b/docs/how-to/monitoring-cos/enable-monitoring.md @@ -138,7 +138,7 @@ prometheus prometheus prometheus-k8s 103 1/1 receive-remote-write ### Connect Grafana web interface -To connect to the Grafana web interface, follow the [Browse dashboards](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s?_ga=2.201254254.1948444620.1704703837-757109492.1701777558#browse-dashboards) section of the MicroK8s "Getting started" guide. +To connect to the Grafana web interface, follow the [Browse dashboards](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s) section of the MicroK8s "Getting started" guide. ```text juju run grafana/leader get-admin-password --model : diff --git a/docs/how-to/monitoring-cos/enable-profiling.md b/docs/how-to/monitoring-cos/enable-profiling.md index b1f2d3acca..6d861305d6 100644 --- a/docs/how-to/monitoring-cos/enable-profiling.md +++ b/docs/how-to/monitoring-cos/enable-profiling.md @@ -9,14 +9,14 @@ Read the [](#prerequisites) section carefully if you are deploying PostgreSQL in ## Prerequisites * A juju model with [Charmed PostgreSQL deployed](/how-to/deploy/index). -* **If you are using an LXD model**, LXD's virtualization type must be set to `virtual-machine`. - * See [](#lxd-virtualization-type) for more details. -* **If your base is `ubuntu@22.4`**, you must use the `generic` flavor of Linux. +* **If you are using an LXD model**, LXD's virtualisation type must be set to `virtual-machine`. + * See [](#lxd-virtualisation-type) for more details. +* **If your base is `ubuntu@22.4`**, you must use the `generic` flavour of Linux. * See [](#base-ubuntu-version) for more details. -### LXD virtualization type +### LXD virtualisation type -If you are deploying Charmed PostgreSQL in a LXD model, ensure that LXD's virtualization type is set to `virtual-machine` for the Juju application. +If you are deploying Charmed PostgreSQL in a LXD model, ensure that LXD's virtualisation type is set to `virtual-machine` for the Juju application. This is because LXD does not allow `/sys/kernel/tracing` to be mounted in a system container (even in privileged mode) due to security isolation concerns. @@ -27,14 +27,14 @@ juju deploy postgresql --channel 14/stable --constraints="virt-type=virtual-mach ``` ### Base (Ubuntu version) -If your base is `ubuntu@22.04`, ensure that your are using the `generic` flavor of Linux. +If your base is `ubuntu@22.04`, ensure that your are using the `generic` flavour of Linux. You can confirm this with ``` uname -r ``` -If you do not have the `generic` flavor, you can enable it on a unit to be profiled as follows: +If you do not have the `generic` flavour, you can enable it on a unit to be profiled as follows: ```text juju ssh postgresql/0 bash @@ -103,7 +103,7 @@ juju integrate postgresql parca-agent #### 4. Integrate `parca-agent` with `parca-k8s` -Consume the parca offer from [Step 2](#parca-offer-interfaces) and integrate with them: +Consume the Parca offer from [Step 2](#parca-offer-interfaces) and integrate with them: ```text juju find-offers : diff --git a/docs/how-to/monitoring-cos/enable-tracing.md b/docs/how-to/monitoring-cos/enable-tracing.md index 856bcd56bb..c79ce56932 100644 --- a/docs/how-to/monitoring-cos/enable-tracing.md +++ b/docs/how-to/monitoring-cos/enable-tracing.md @@ -25,12 +25,12 @@ juju switch : ``` Then, deploy the dependencies of Tempo following [this tutorial](https://discourse.charmhub.io/t/tutorial-deploy-tempo-ha-on-top-of-cos-lite/15489). In particular, we would want to: -- Deploy the minio charm -- Deploy the s3 integrator charm -- Add a bucket into minio using a python script -- Configure s3 integrator with the minio credentials +- Deploy the MinIO charm +- Deploy the S3 integrator charm +- Add a bucket into MinIO using a python script +- Configure S3 integrator with the MinIO credentials -Finally, deploy and integrate with Tempo HA in [a monolithic setup](https://discourse.charmhub.io/t/tutorial-deploy-tempo-ha-on-top-of-cos-lite/15489#deploy-monolithic-setup). +Finally, deploy and integrate with Tempo HA in [a monolithic setup](https://discourse.charmhub.io/t/tutorial-deploy-tempo-ha-on-top-of-cos-lite/15489). ## Offer interfaces diff --git a/docs/how-to/monitoring-cos/index.md b/docs/how-to/monitoring-cos/index.md index 706b34cdd9..2c0fad0301 100644 --- a/docs/how-to/monitoring-cos/index.md +++ b/docs/how-to/monitoring-cos/index.md @@ -9,3 +9,4 @@ Enable monitoring Enable alert rules Enable tracing Enable profiling +``` \ No newline at end of file diff --git a/docs/how-to/scale-replicas.md b/docs/how-to/scale-replicas.md index f583fdaa87..89f4b75ab6 100644 --- a/docs/how-to/scale-replicas.md +++ b/docs/how-to/scale-replicas.md @@ -29,7 +29,7 @@ juju run postgresql/leader get-primary Similarly, the primary replica is displayed as a status message in `juju status`. However, one should note that this hook gets called on regular time intervals and the primary may be outdated if the status hook has not been called recently. ````{note} -**We highly suggest configuring the `update-status` hook to run frequently.** In addition to reporting the primary, secondaries, and other statuses, the [status hook](https://juju.is/docs/sdk/update-status-event) performs self-healing in the case of a network cut. +**We highly suggest configuring the `update-status` hook to run frequently.** In addition to reporting the primary, secondaries, and other statuses, the [status hook](https://documentation.ubuntu.com/juju/3.6/reference/hook/#update-status) performs self-healing in the case of a network cut. To change the frequency of the `update-status` hook, run diff --git a/docs/how-to/switchover-failover.md b/docs/how-to/switchover-failover.md index 171c530808..21f3e4ad43 100644 --- a/docs/how-to/switchover-failover.md +++ b/docs/how-to/switchover-failover.md @@ -22,9 +22,9 @@ Note that: Charmed PostgreSQL doesn't provide manual failover due to lack of data safety guarantees. -Advanced users can still execute it using [patronictl](/reference/troubleshooting/cli-helpers) and [Patroni REST API](/reference/troubleshooting/cli-helpers). The same time Charmed PostgreSQL allows the cluster recovery using the full PostgreSQL/Patroni/Raft cluster re-initialization. +Advanced users can still execute it using [patronictl](/reference/troubleshooting/cli-helpers) and [Patroni REST API](/reference/troubleshooting/cli-helpers). The same time Charmed PostgreSQL allows the cluster recovery using the full PostgreSQL/Patroni/Raft cluster re-initialisation. -## Raft re-initialization +## Raft re-initialisation ```{caution} This is the worst possible recovery case scenario when Primary and ALL Sync Standby units lost simultaneously and their data cannot be recovered from the disc. @@ -34,17 +34,17 @@ In this case, Patroni cannot perform automatic failover for the only available R A manual failover procedure cannot guarantee the latest SQL transactions' availability on the replica unit(s) due to the [lag distance](/explanation/units) to the primary. Additionally, Raft cluster consensus is not possible when one unit is left in a three-unit cluster. ``` -The command to re-initialize the Raft cluster should be executed when charm is ready: +The command to re-initialise the Raft cluster should be executed when charm is ready: * the last Juju unit is available in Juju application * the last unit was has detected Raft majority lost, status: `Raft majority loss, run: promote-to-primary` -To re-initialize Raft and fix the Partition/PostgreSQL cluster (when requested): +To re-initialise Raft and fix the Partition/PostgreSQL cluster (when requested): ```text juju run postgresql/x promote-to-primary scope=unit force=true ``` -
Example of Raft re-initialization +
Example of Raft re-initialisation Deploy PostgreSQL 3 units: @@ -108,7 +108,7 @@ Machine State Address Inst id Base AZ Message At this stage it is recommended to restore the lost nodes, they will rejoin the cluster automatically once Juju detects their availability. -To start Raft re-initialization, remove DEAD machines as a signal to charm that they cannot be restored/started and no risks for split-brain: +To start Raft re-initialisation, remove DEAD machines as a signal to charm that they cannot be restored/started and no risks for split-brain: ```text > juju remove-machine --force 0 @@ -136,7 +136,7 @@ postgresql/1* blocked executing 1 10.189.210.166 5432/tcp Raft majo ... ``` -Start Raft re-initialization: +Start Raft re-initialisation: ```text > juju run postgresql/1 promote-to-primary scope=unit force=true diff --git a/docs/how-to/upgrade/index.md b/docs/how-to/upgrade/index.md index 4c95507927..b1e65a7b4a 100644 --- a/docs/how-to/upgrade/index.md +++ b/docs/how-to/upgrade/index.md @@ -21,3 +21,4 @@ We will soon publish a migration guide with instructions on how to change from P Perform a minor upgrade Perform a minor rollback +``` \ No newline at end of file diff --git a/docs/how-to/upgrade/perform-a-minor-upgrade.md b/docs/how-to/upgrade/perform-a-minor-upgrade.md index 47e5bfff80..3cedcebc74 100644 --- a/docs/how-to/upgrade/perform-a-minor-upgrade.md +++ b/docs/how-to/upgrade/perform-a-minor-upgrade.md @@ -78,7 +78,7 @@ juju run postgresql/leader pre-upgrade-check ``` Make sure there are no errors in the result output. -This action will configure the charm to minimize the amount of primary switchover, among other preparations for a safe upgrade process. After successful execution, the charm is ready to be upgraded. +This action will configure the charm to minimise the amount of primary switchover, among other preparations for a safe upgrade process. After successful execution, the charm is ready to be upgraded. ## Step 3: Upgrade diff --git a/docs/index.md b/docs/index.md index 3ebd1abf5e..317d2dc791 100644 --- a/docs/index.md +++ b/docs/index.md @@ -25,7 +25,7 @@ Charmed PostgreSQL is an official distribution of PostgreSQL. It’s an open-sou - Explore [Canonical Data solutions](https://canonical.com/data) - [Contacts us](/reference/contacts) for all further questions -## Licencing & Trademark +## Licensing & Trademark The Charmed PostgreSQL Operator is distributed under the [Apache Software Licence version 2.0](https://github.com/canonical/postgresql-operator/blob/main/LICENSE). It depends on [PostgreSQL](https://www.postgresql.org/ftp/source/), which is licensed under the [PostgreSQL License](https://www.postgresql.org/about/licence/) - a liberal open-source licence similar to the BSD or MIT licences. @@ -43,4 +43,4 @@ Tutorial How-to guides Reference Explanation - +``` diff --git a/docs/reference/alert-rules.md b/docs/reference/alert-rules.md index a3c20c0a71..fa97edc3a5 100644 --- a/docs/reference/alert-rules.md +++ b/docs/reference/alert-rules.md @@ -19,7 +19,7 @@ This page contains a markdown version of the alert rules described in the `postg | PostgresqlTooManyConnections | ![warning] | PostgresSQL instance is using > 80% of the maximum connections.
Consider checking how many connections the client application is opening, or using PgBouncer in front of the database. | | PostgresqlNotEnoughConnections | ![info] | PostgresSQL instance does not have enough connections.
PostgreSQL instance should have more connections (> 5).
Consider double-checking how many connections the client application is opening and/or using PgBouncer in front of the database. | | PostgresqlDeadLocks | ![warning] | PostgresSQL instance has dead locks.
See more details with the pg_locks view. | -| PostgresqlHighRollbackRate | ![warning] | PostgresSQL instance has a high rollback rate instance.
The ratio of transactions being aborted compared to committed is > 2 %.
This is probably happening due to unoptimized configurations related to commit delay, connections, memory, and WAL files. | +| PostgresqlHighRollbackRate | ![warning] | PostgresSQL instance has a high rollback rate instance.
The ratio of transactions being aborted compared to committed is > 2 %.
This is probably happening due to unoptimised configurations related to commit delay, connections, memory, and WAL files. | | PostgresqlCommitRateLow | ![info] | PostgresSQL instance has a low commit rate.
PostgresSQL seems to be processing very few transactions.
Check for long-running queries and configuration issues, like insufficient cache size. | | PostgresqlLowXidConsumption | ![info] | PostgresSQL instance shows low XID consumption.
PostgresSQL seems to be consuming transaction IDs very slowly.
Run ANALYZE to update the optimizer statistics, ensure that query plans are correct, and double-check your VACUUM settings. | | PostgresqlHighRateStatementTimeout | ![critical] | PostgresSQL instance shows a high rate of statement timeout.
Either tune `statement_timeout` when sending queries or use EXPLAIN ANALYZE to understand how the queries can be improved. | diff --git a/docs/reference/contacts.md b/docs/reference/contacts.md index 7bc6b284ae..dbbe12750e 100644 --- a/docs/reference/contacts.md +++ b/docs/reference/contacts.md @@ -6,10 +6,6 @@ Charmed PostgreSQL is an open source project that warmly welcomes community cont * [Report](https://github.com/canonical/postgresql-operator/security/advisories/new) security issues * Contact the Canonical Data Platform team directly through our [Matrix](https://matrix.to/#/#charmhub-data-platform:ubuntu.com) channel. -```{note} -Our legacy [Mattermost](https://chat.charmhub.io/charmhub/channels/data-platform) channel is read-only until January 31, 2025. -``` - Useful links: * [Canonical Data Fabric](https://ubuntu.com/data/) diff --git a/docs/reference/performance-and-resources.md b/docs/reference/performance-and-resources.md index 784aee34a3..247c983c03 100644 --- a/docs/reference/performance-and-resources.md +++ b/docs/reference/performance-and-resources.md @@ -12,7 +12,7 @@ Charmed PostgreSQL resource allocation can be controlled via the charm's `profil |Value|Description|Details| | --- | --- | ----- | -|`production`
(default)|[Maximum performance](https://github.com/canonical/postgresql-operator/blob/main/lib/charms/postgresql_k8s/v0/postgresql.py#L437-L446)| 25% of the available memory for `shared_buffers` and the remain as cache memory (defaults mimic legacy charm behaviour).
The `max_connections`=max(4 * os.cpu_count(), 100).
Use [pgbouncer](https://charmhub.io/pgbouncer?channel=1/stable) if max_connections are not enough ([reasoning](https://www.percona.com/blog/scaling-postgresql-with-pgbouncer-you-may-need-a-connection-pooler-sooner-than-you-expect/)).| +|`production`
(default)|[Maximum performance](https://github.com/canonical/postgresql-operator/blob/main/lib/charms/postgresql_k8s/v0/postgresql.py#L437-L446)| 25% of the available memory for `shared_buffers` and the remain as cache memory (defaults mimic legacy charm behaviour).
`max_connections = max(4 * os.cpu_count(), 100)`.
Use [pgbouncer](https://charmhub.io/pgbouncer?channel=1/stable) if max_connections are not enough ([reasoning](https://www.percona.com/blog/scaling-postgresql-with-pgbouncer-you-may-need-a-connection-pooler-sooner-than-you-expect/)).| |`testing`|[Minimal resource usage](https://github.com/canonical/postgresql-operator/blob/main/lib/charms/postgresql_k8s/v0/postgresql.py#L437-L446)| PostgreSQL 14 defaults. | ```{caution} diff --git a/docs/reference/releases.md b/docs/reference/releases.md index f440c8b4d9..20b998ef9d 100644 --- a/docs/reference/releases.md +++ b/docs/reference/releases.md @@ -2,7 +2,7 @@ This page provides high-level overviews of the dependencies and features that are supported by each revision in every stable release. -To learn more about the different release tracks and channels, see the [Juju documentation about channels](https://juju.is/docs/juju/channel#risk). +To learn more about the different release tracks and channels, see the [Juju documentation about channels](https://documentation.ubuntu.com/juju/3.6/reference/charm/#risk). To see all releases and commits, check the [Charmed PostgreSQL Releases page on GitHub](https://github.com/canonical/postgresql-operator/releases). @@ -28,7 +28,7 @@ For a given release, this table shows: ## Architecture and base -Several [revisions](https://juju.is/docs/sdk/revision) are released simultaneously for different [bases/series](https://juju.is/docs/juju/base) using the same charm code. In other words, one release contains multiple revisions. +Several [revisions](https://documentation.ubuntu.com/juju/3.6/reference/charm/#charm-revision) are released simultaneously for different [bases/series](https://juju.is/docs/juju/base) using the same charm code. In other words, one release contains multiple revisions. If you do not specify a revision on deploy time, Juju will automatically choose the revision that matches your base and architecture. diff --git a/docs/reference/statuses.md b/docs/reference/statuses.md index 3ed8c2345a..0bf6c86db2 100644 --- a/docs/reference/statuses.md +++ b/docs/reference/statuses.md @@ -1,10 +1,10 @@ # Charm statuses ```{caution} -This reference is a work in progress and not fit for production. Contact [Canonical Data Platform team](https://chat.charmhub.io/charmhub/channels/data-platform) if you are interested in the topic. +This reference is a work in progress and not fit for production. [Contact us](/reference/contacts) if you are interested in the topic. ``` -The charm follows [standard Juju applications statuses](https://juju.is/docs/olm/status-values#application-status). Here you can find the expected end-users reaction on different statuses: +The charm follows [standard Juju applications statuses](https://documentation.ubuntu.com/juju/3.6/reference/status/#application-status). Here you can find the expected end-users reaction on different statuses: | Juju Status | Message | Expectations | Actions | |-------|-------|-------|-------| @@ -13,8 +13,8 @@ The charm follows [standard Juju applications statuses](https://juju.is/docs/olm | **maintenance** | any | Charm is performing the internal maintenance (e.g. cluster re-configuration, upgrade, ...) | No actions required | | **blocked** | the S3 repository has backups from another cluster | The bucket contains foreign backup. To avoid accident DB corruption, use clean bucket. The cluster identified by Juju app name + DB UUID. | Choose/change the new S3 [bucket](https://charmhub.io/s3-integrator/configuration#bucket)/[path](https://charmhub.io/s3-integrator/configuration#path) OR clean the current one. | | **blocked** | failed to update cluster members on member | TODO: error/retry? | | -| **blocked** | failed to install snap packages | There are issues with the network connection and/or the Snap Store | Check your internet connection and https://status.snapcraft.io/. Remove the application and when everything is ok, deploy the charm again | -| **blocked** | failed to patch snap seccomp profile | The charm failed to patch one issue that happens when pgBackRest restores a backup (this blocked status should be removed when https://github.com/pgbackrest/pgbackrest/releases/tag/release%2F2.46 is added to the snap) | Remove the unit and add it back again | +| **blocked** | failed to install snap packages | There are issues with the network connection and/or the Snap Store | Check your internet connection and https://status.snapcraft.io/. Remove the application and when everything is OK, deploy the charm again | +| **blocked** | failed to patch snap `seccomp` profile | The charm failed to patch one issue that happens when pgBackRest restores a backup (this blocked status should be removed when https://github.com/pgbackrest/pgbackrest/releases/tag/release%2F2.46 is added to the snap) | Remove the unit and add it back again | | **blocked** | failed to set up postgresql_exporter options | The charm failed to set up the metrics exporter | Remove the unit and add it back again | | **blocked** | failed to start Patroni | TODO: error/retry? | | | **blocked** | Failed to create postgres user | The charm couldn't create the default `postgres` database user due to connection problems | Connect to the database using the `operator` user and the password from the `get-password` action, then run `CREATE ROLE postgres WITH LOGIN SUPERUSER;` | diff --git a/docs/reference/system-requirements.md b/docs/reference/system-requirements.md index fe9a7db585..421206e033 100644 --- a/docs/reference/system-requirements.md +++ b/docs/reference/system-requirements.md @@ -7,17 +7,17 @@ The following are the minimum software and hardware requirements to run Charmed ### Juju -The charm supports several Juju releases from [2.9 LTS](https://juju.is/docs/juju/roadmap#juju-juju-29) onwards. The table below shows which minor versions of each major Juju release are supported by the stable Charmhub releases of PostgreSQL. +The charm supports several Juju releases from [2.9 LTS](https://documentation.ubuntu.com/juju/3.6/reference/juju/juju-roadmap-and-releases/#juju-2-9) onwards. The table below shows which minor versions of each major Juju release are supported by the stable Charmhub releases of PostgreSQL. | Juju major release | Supported minor versions | Compatible charm revisions |Comment | |:--------|:-----|:-----|:-----| | ![3.6 LTS] | `3.6.1+` | [552]+ | `3.6.0` is not recommended, while `3.6.1+` works excellent. Recommended for production! | -| [![3.5]](https://juju.is/docs/juju/roadmap#juju-juju-35) | `3.5.1+` | [363]+ | [Known Juju issue](https://bugs.launchpad.net/juju/+bug/2066517) in `3.5.0` | -| [![3.4]](https://juju.is/docs/juju/roadmap#juju-juju-34) | `3.4.3+` | [363]+ | Know Juju issues with previous minor versions | -| [![3.3]](https://juju.is/docs/juju/roadmap#juju-juju-33) | `3.3.0+` | from [363] to [430] | No known issues | -| [![3.2]](https://juju.is/docs/juju/roadmap#juju-juju-32) | `3.2.0+` | from [363] to [430] | No known issues | -| [![3.1]](https://juju.is/docs/juju/roadmap#juju-juju-31) | `3.1.7+` | from [336] to [430] | Juju secrets were stabilized in `3.1.7` | -| [![2.9 LTS]](https://juju.is/docs/juju/roadmap#juju-juju-29) | `2.9.49+` | [288]+ | | +| [![3.5]](https://documentation.ubuntu.com/juju/3.6/reference/juju/juju-roadmap-and-releases/#juju-3-5) | `3.5.1+` | [363]+ | [Known Juju issue](https://bugs.launchpad.net/juju/+bug/2066517) in `3.5.0` | +| [![3.4]](https://documentation.ubuntu.com/juju/3.6/reference/juju/juju-roadmap-and-releases/#juju-3-4) | `3.4.3+` | [363]+ | Know Juju issues with previous minor versions | +| [![3.3]](https://documentation.ubuntu.com/juju/3.6/reference/juju/juju-roadmap-and-releases/#juju-3-3) | `3.3.0+` | from [363] to [430] | No known issues | +| [![3.2]](https://documentation.ubuntu.com/juju/3.6/reference/juju/juju-roadmap-and-releases/#juju-3-2) | `3.2.0+` | from [363] to [430] | No known issues | +| [![3.1]](https://documentation.ubuntu.com/juju/3.6/reference/juju/juju-roadmap-and-releases/#juju-3-1) | `3.1.7+` | from [336] to [430] | Juju secrets were stabilised in `3.1.7` | +| [![2.9 LTS]](https://documentation.ubuntu.com/juju/3.6/reference/juju/juju-roadmap-and-releases/#juju-2-9) | `2.9.49+` | [288]+ | | | | `2.9.32+` | from [288] to [430] | No tests for older Juju versions. | ## Hardware diff --git a/docs/reference/troubleshooting/cli-helpers.md b/docs/reference/troubleshooting/cli-helpers.md index aa2fe3e443..9147553cfe 100644 --- a/docs/reference/troubleshooting/cli-helpers.md +++ b/docs/reference/troubleshooting/cli-helpers.md @@ -150,8 +150,8 @@ ubuntu@juju-b87344-2:~$ sudo -u snap_daemon patronictl -c /var/snap/charmed-post #### Re-initialisation -Sometimes the cluster member might stuck in the middle of nowhere, the easiest way to try is [reinit the Patroni cluster member](https://patroni.readthedocs.io/en/latest/patronictl.html#patronictl-reinit). -
Example: cluster member re-initialization +Sometimes the cluster member might stuck in the middle of nowhere, the easiest way to try is [`reinit` the Patroni cluster member](https://patroni.readthedocs.io/en/latest/patronictl.html#patronictl-reinit). +
Example: cluster member re-initialisation ```text ubuntu@juju-b87344-2:~$ sudo -u snap_daemon patronictl -c /var/snap/charmed-postgresql/current/etc/patroni/patroni.yaml reinit postgresql postgresql-1 @@ -248,7 +248,7 @@ Pay attention to TLS relation with PostgreSQL and access Patroni REST API accord ### Raft library -Patroni relies on the Raft library for the consensus handling and Primary election. It is implemented using [pySyncObj](https://github.com/bakwc/PySyncObj) and available as a CLI tool. +Patroni relies on the Raft library for the consensus handling and Primary election. It is implemented using [`pySyncObj`](https://github.com/bakwc/PySyncObj) and available as a CLI tool. While **you should not interact with Raft library manually**, you can check its internal status. Note that a password is mandatory to access Raft. @@ -315,23 +315,23 @@ charmed-postgresql.pg-config charmed-postgresql.pg-dropcluster char ```
-#### pg_dump / pg_dumpall +#### `pg_dump` / `pg_dumpall` These tools are designed to dump the PostgreSQL content. Due to the strictly confined SNAP, the context is limited to SNAP itself (and not the POSIX user triggered the tool). Also, due to security reasons the default `postgres` user cannot access DB, use user `operator` (you can find it's credential in Juju Secrets). -
Example: pg-dump/pg-dumpall usage +
Example: pg-dump/pg-dumpall usage ```text charmed-postgresql.pg-dump -c -C -U operator -W -h /tmp -d mydb | tee mydb.sql >/dev/null ``` -Also you can pass password using env variable PGPASSWORD, however it is NOT recommended for productions as DB password will be stored in shell history: +Also you can pass password using the environment variable `PGPASSWORD`, however it is NOT recommended for productions as the database password will be stored in the shell's history: ```text PGPASSWORD=my$ecretp@ss charmed-postgresql.pg-dumpall -c -U operator -h /tmp | tee all_DBs.txt >/dev/null ``` -Note, the local SNAP /tmp could be used as well: +Note, the local snap/`tmp` could be used as well: ```text PGPASSWORD=my$ecretp@ss charmed-postgresql.pg-dumpall -c -U operator -h /tmp -f /tmp/test.sql diff --git a/docs/reference/troubleshooting/index.md b/docs/reference/troubleshooting/index.md index 9dc223c414..8495ff0fa2 100644 --- a/docs/reference/troubleshooting/index.md +++ b/docs/reference/troubleshooting/index.md @@ -5,9 +5,10 @@ This page goes over some recommended tools and approaches to troubleshooting the Before anything, always run `juju status` to check the [list of charm statuses](/reference/statuses) and the recommended fixes. This alone may already solve your issue. Otherwise, this reference goes over how to troubleshoot this charm via: -- [`juju` logs](#juju-logs) -- [`snap-based charm`](#snap-based-charm) -- [Installing extra software](#install-extra-software) +- [Troubleshooting](#troubleshooting) + - [Juju logs](#juju-logs) + - [Snap-based charm](#snap-based-charm) + - [Install extra software](#install-extra-software) ```{caution} @@ -74,7 +75,7 @@ Name Version Rev Tracking Publisher Notes charmed-postgresql 14.9 70 latest/stable dataplatformbot held ``` -From here you can make sure all snap (systemd) services are running: +From here you can make sure all snap (`systemd`) services are running: ```text ubuntu@juju-fd7874-0# sudo snap services @@ -136,7 +137,7 @@ ubuntu 10234 0.0 0.0 17208 7944 ? R 21:47 0:00 sshd: ubuntu@ ubuntu@juju-fd7874-0:~$ ``` -The list of running snap/systemd services will depend on configured (enabled) [COS integration](/how-to/monitoring-cos/enable-monitoring) and/or [backup](/how-to/back-up-and-restore/create-a-backup) functionality. The snap service `charmed-postgresql.patroni` must always be active and currently running (the Linux processes `snapd`, `patroni` and `postgres`). +The list of running snap/`systemd` services will depend on configured (enabled) [COS integration](/how-to/monitoring-cos/enable-monitoring) and/or [backup](/how-to/back-up-and-restore/create-a-backup) functionality. The snap service `charmed-postgresql.patroni` must always be active and currently running (the Linux processes `snapd`, `patroni` and `postgres`). To access PostgreSQL, check the [charm users concept](/explanation/users) and request `operator` credentials to use `psql`: diff --git a/docs/reference/troubleshooting/sos-report.md b/docs/reference/troubleshooting/sos-report.md index 4dfa658256..31de46d1dd 100644 --- a/docs/reference/troubleshooting/sos-report.md +++ b/docs/reference/troubleshooting/sos-report.md @@ -7,7 +7,7 @@ You can use the [built-in version of SoS](#use-built-in-sos-recommended), or [re ```{caution} Always review the collected data before sharing it! -The generated archive may contain sensitive data. Its content should be reviewed by the originating organization before being passed to any third party. +The generated archive may contain sensitive data. Its content should be reviewed by the originating organisation before being passed to any third party. ``` ## Use built-in SoS (recommended) @@ -33,7 +33,7 @@ Your sos report has been generated and saved in: ... ``` -Use `juju scp` to copy logs from Juju unit to localhost: +Use `juju scp` to copy logs from Juju unit to `localhost`: ```text juju scp postgresql/0:/tmp/sosreport-juju-d4c067-1-2025-04-07-chdmwlz.tar.xz . ``` @@ -56,7 +56,7 @@ For more information on Canonical visit: Commercial Support : https://www.canonical.com The generated archive may contain data considered sensitive and its -content should be reviewed by the originating organization before being +content should be reviewed by the originating organisation before being passed to any third party. No changes will be made to system configuration. @@ -92,16 +92,16 @@ juju scp postgresql/0:/tmp/sosreport-juju-d4c067-1-2025-04-07-qntyqpz.tar.xz . ### Collect logs from several units -The sos tool allows you to collect logs from several Juju units (replace labels with proper Juju unit like `postgresql/0`). +The SoS tool allows you to collect logs from several Juju units (replace labels with proper Juju unit like `postgresql/0`). Run the following command from outside the Juju units: ```text sos collect --cluster-type juju --no-local -c "juju.units=,,<...>" --batch -o system,systemd,snap,charmed_postgresql --low-priority ``` -## Use the latest sos plugins from Git +## Use the latest SoS plugins from Git -The latest version of [sos plugins](https://github.com/sosreport/sos/tree/main/sos/report/plugins) can be retrieved from Git easily: +The latest version of [SoS plugins](https://github.com/sosreport/sos/tree/main/sos/report/plugins) can be retrieved from Git easily: ```text git clone https://github.com/sosreport/sos.git cd sos diff --git a/docs/reference/versions.md b/docs/reference/versions.md index 244507da6b..9787337944 100644 --- a/docs/reference/versions.md +++ b/docs/reference/versions.md @@ -79,7 +79,7 @@ Read more about Charmed PostgreSQL 14 features in the [release notes]. ### Deprecated -* The track `14` is in bug-fixing/support mode. New Charmed PostgreSQL `16` features will NOT be backported to track `14`. +* The track `14` is in bug-fixing/support mode. New Charmed PostgreSQL `16` features will NOT be back-ported to track `14`. * Charmed PostgreSQL 14 ships [Timescale Apache 2 edition](https://docs.timescale.com/about/latest/timescaledb-editions/) only. ## Legacy PostgreSQL charm diff --git a/docs/tutorial/index.md b/docs/tutorial/index.md index 41d35dbeb9..85c3b81109 100644 --- a/docs/tutorial/index.md +++ b/docs/tutorial/index.md @@ -188,10 +188,10 @@ You can see below the output for the list of databases. `postgres` is the defaul (3 rows) ``` -In order to execute queries, we should enter psql's interactive terminal by running the following command, again typing password when requested: +In order to execute queries, we should enter `psql`'s interactive terminal by running the following command, again typing password when requested: ```text - psql --host=10.1.110.80 --username=operator --password postgres +psql --host=10.1.110.80 --username=operator --password postgres ``` The output should be something like this: @@ -270,7 +270,7 @@ When you’re ready to leave the PostgreSQL shell, you can just type `exit`. Thi ## Scale your replicas -The Charmed PostgreSQL VM operator uses a [PostgreSQL Patroni-based cluster](https://patroni.readthedocs.io/en/latest/) for scaling. It provides features such as automatic membership management, fault tolerance, and automatic failover. The charm uses PostgreSQL’s [synchronous replication](https://patroni.readthedocs.io/en/latest/replication_modes.html#postgresql-k8s-synchronous-replication) with Patroni to handle replication. +The Charmed PostgreSQL VM operator uses a [PostgreSQL Patroni-based cluster](https://patroni.readthedocs.io/en/latest/) for scaling. It provides features such as automatic membership management, fault tolerance, and automatic failover. The charm uses PostgreSQL’s [synchronous replication](https://patroni.readthedocs.io/en/latest/replication_modes.html) with Patroni to handle replication. ```{caution} This tutorial hosts all replicas on the same machine. @@ -390,7 +390,7 @@ Learn more about managing user credentials in [](/how-to/manage-passwords) and [ ## Integrate with other applications -[Integrations](https://juju.is/docs/sdk/integration), known as "relations" in Juju 2.9, are the easiest way to create a user for PostgreSQL in Charmed PostgreSQL VM. +[Integrations](https://documentation.ubuntu.com/juju/3.6/reference/relation/), known as "relations" in Juju 2.9, are the easiest way to create a user for PostgreSQL in Charmed PostgreSQL VM. Integrations automatically create a username, password, and database for the desired user/application. The best practice is to connect to PostgreSQL via a specific user rather than the admin user. @@ -666,7 +666,7 @@ multipass delete --purge my-vm - Check out our other other charm offerings, like [MySQL](https://charmhub.io/mysql) and [Kafka](https://charmhub.io/kafka?channel=edge) - Read about [High Availability best practices](https://canonical.com/blog/database-high-availability) - [Report](https://github.com/canonical/postgresql-operator/issues) any problems you encountered -- [Give us your feedback](https://chat.charmhub.io/charmhub/channels/data-platform) +- [Give us your feedback](/reference/contacts) - [Contribute to the code base](https://github.com/canonical/postgresql-operator)