diff --git a/docs/.md b/docs/.md new file mode 100644 index 0000000000..527681c0c7 --- /dev/null +++ b/docs/.md @@ -0,0 +1,106 @@ +[note type=caution] +The documentation for Charmed PostgreSQL K8s has moved to a [new home](https://canonical-charmed-postgresql-k8s.readthedocs-hosted.com/)! Please update your bookmarks, and [contact us](https://matrix.to/#/#charmhub-data-platform:ubuntu.com) if you have any questions. +[/note] + +# Charmed PostgreSQL K8s documentation +Charmed PostgreSQL is an open-source software operator designed to deploy and operate object-relational databases on Kubernetes. It packages the powerful database management system [PostgreSQL](https://www.postgresql.org/) into a charmed operator for deployment with [Juju](https://juju.is/docs/juju). + +To learn more about how to deploy and manage this charm, see the [official Charmed PostgreSQL K8s documentation](https://canonical-charmed-postgresql-k8s.readthedocs-hosted.com/) + +# Navigation + +[details=Navigation] + +| Level | Path | Navlink | +|--------|--------|-------------| +| 1 | | [Overview](/t/9307) | +| 2 | tutorial | [](/t/9296) | +| 2 | t-set-up | [](/t/9297) | +| 2 | t-deploy | [](/t/9298) | +| 2 | t-access | [](/t/13702) | +| 2 | t-scale | [](/t/9299) | +| 2 | t-manage-passwords | [](/t/9300) | +| 2 | t-integrate | [](/t/9301) | +| 2 | t-enable-tls | [](/t/9302) | +| 2 | t-clean-up | [](/t/9303) | +| 2 | how-to | [](/t/16767) | +| 2 | h-deploy | [](/t/16810) | +| 2 | h-deploy-canonical-k8s | [](/t/15937) | +| 2 | h-deploy-gke | [](/t/11237) | +| 2 | h-deploy-eks | [](/t/12106) | +| 2 | h-deploy-aks | [](/t/14307) | +| 2 | h-deploy-multi-az | [](/t/15678) | +| 2 | h-deploy-terraform | [](/t/14924) | +| 2 | h-deploy-airgapped | [](/t/15691) | +| 2 | h-integrate | [](/t/9594) | +| 2 | h-manage-passwords | [](/t/17860) | +| 2 | h-external-access | [](/t/15701) | +| 2 | h-scale | [](/t/9592) | +| 2 | h-enable-tls | [](/t/9593) | +| 2 | h-enable-ldap | [](/t/17189) | +| 2 | h-enable-plugins-extensions | [](/t/10907) | +| 2 | h-backup | []() | +| 2 | h-configure-s3-aws | [](/t/9595) | +| 2 | h-configure-s3-radosgw | [](/t/10316) | +| 2 | h-create-backup | [](/t/9596) | +| 2 | h-restore-backup | [](/t/9597) | +| 2 | h-manage-backup-retention | [](/t/14203) | +| 2 | h-migrate-cluster | [](/t/9598) | +| 2 | h-monitor | []() | +| 2 | h-enable-monitoring | [](/t/10812) | +| 2 | h-enable-alert-rules | [](/t/12982) | +| 2 | h-enable-tracing | [](/t/14786) | +| 2 | h-upgrade | [](/t/12092) | +| 2 | h-upgrade-minor | [](/t/12095) | +| 2 | h-rollback-minor | [](/t/12096) | +| 2 | h-async | [](/t/15413) | +| 2 | h-async-set-up | [](/t/13895) | +| 2 | h-async-integrate | [](/t/13896) | +| 2 | h-async-remove-recover | [](/t/13897) | +| 2 | h-development| []() | +| 2 | h-development-integrate | [](/t/11853) | +| 2 | h-migrate-pgdump | [](/t/12162) | +| 2 | h-migrate-backup-restore | [](/t/12161) | +| 2 | reference | [](/t/13977) | +| 2 | r-releases | [](/t/11872) | +| 2 | r-system-requirements | [](/t/11744) | +| 2 | r-software-testing | [](/t/11774) | +| 2 | r-performance | [](/t/11975) | +| 2 | r-troubleshooting | [](/t/11854) | +| 2 | r-plugins-extensions | [](/t/10945) | +| 2 | r-alert-rules | [](/t/15840) | +| 2 | e-statuses | [](/t/11855) | +| 2 | r-contacts | [](/t/11852) | +| 2 | explanation | [](/t/16769) | +| 2 | e-architecture | [](/t/11856) | +| 2 | e-interfaces-endpoints | [](/t/10252) | +| 2 | e-juju-details | [](/t/11986) | +| 2 | e-legacy-charm | [](/t/11013) | +| 2 | e-users | [](/t/10843) | +| 2 | e-logs | [](/t/12098) | +| 2 | e-connection-pooling| [](/t/15799) | +| 2 | e-security | [](/t/16850) | +| 2 | e-cryptography | [](/t/16851) | +| 2 | flowcharts | []() | +| 2 | e-flowchart-charm | [](/t/9305) | +| 2 | e-flowchart-peers | [](/t/9306) | +| 2 | e-flowchart-backups | [](/t/10248) | + +[/details] + + \ No newline at end of file diff --git a/docs/explanation/e-architecture.md b/docs/explanation/e-architecture.md index 5817eac91b..788684377b 100644 --- a/docs/explanation/e-architecture.md +++ b/docs/explanation/e-architecture.md @@ -12,8 +12,8 @@ Pebble is a lightweight, API-driven process supervisor that is responsible for c Pebble `services` are configured through [layers](https://github.com/canonical/pebble#layer-specification), and the following containers represent each one a layer forming the effective Pebble configuration, or `pebble plan`: -1. a [charm]() container runs Juju operator code: `juju ssh postgresql-k8s/0 bash` -1. a [postgresql](https://www.postgresql.owg/) (workload) container runs the PostgreSQL application along with other services (like monitoring metrics exporters, etc): `juju ssh --container postgresql postgresql-k8s/0 bash` +* a charm container runs Juju operator code: `juju ssh postgresql-k8s/0 bash` +* a workload container runs the [PostgreSQL application](https://www.postgresql.org/) along with other services (like monitoring metrics exporters, etc): `juju ssh --container postgresql postgresql-k8s/0 bash` As a result, if you run a `kubectl get pods` on a namespace named for the Juju model you’ve deployed the "Charmed PostgreSQL K8s" charm into, you’ll see something like the following: @@ -29,7 +29,7 @@ And if you run `kubectl describe pod postgresql-k8s-0`, all the containers will ## HLD (High Level Design) -The "Charmed PostgreSQL K8s" (`workload` container) based on `postgresql-image` resource defined in the [charm metadata.yaml](https://github.com/canonical/postgresql-k8s-operator/blob/main/metadata.yaml). It is an official Canonical "[charmed-postgresql](https://github.com/canonical/charmed-postgresql-rock)" [OCI/Rock](https://ubuntu.com/server/docs/rock-images/introduction) image, which is recursively based on Canonical SNAP “[charmed-postgresql](https://snapcraft.io/charmed-postgresql)” (read more about the SNAP details [here](/t/11857)). +The "Charmed PostgreSQL K8s" (`workload` container) based on `postgresql-image` resource defined in the [charm metadata.yaml](https://github.com/canonical/postgresql-k8s-operator/blob/main/metadata.yaml). It is an official Canonical "[charmed-postgresql](https://github.com/canonical/charmed-postgresql-rock)" [OCI/Rock](https://ubuntu.com/server/docs/rock-images/introduction) image, which is recursively based on Canonical SNAP “[charmed-postgresql](https://snapcraft.io/charmed-postgresql)”. [Charmcraft](https://juju.is/docs/sdk/install-charmcraft) uploads an image as a [charm resource](https://charmhub.io/postgresql-k8s/resources/postgresql-image) to [Charmhub](https://charmhub.io/postgresql-k8s) during the [publishing](https://github.com/canonical/postgresql-k8s-operator/blob/main/.github/workflows/release.yaml), as described in the [Juju SDK How-to guides](https://juju.is/docs/sdk/publishing). diff --git a/docs/how-to/h-async-integrate.md b/docs/how-to/h-async-integrate.md index 849f73f3c7..c2598caed0 100644 --- a/docs/how-to/h-async-integrate.md +++ b/docs/how-to/h-async-integrate.md @@ -5,7 +5,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](/t/11744) -* See [supported target/source model relationships](t/15413#substrate-dependencies). +* See [supported target/source model relationships](/t/15413#substrate-dependencies). * A cross-regional async replication setup * See [How to set up clusters](/t/13895) diff --git a/docs/overview.md b/docs/overview.md index 5fabd65c14..527681c0c7 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -1,37 +1,11 @@ -> This is a **Kubernetes** operator. To deploy on IAAS/VM, see [Charmed PostgreSQL VM](https://charmhub.io/postgresql). +[note type=caution] +The documentation for Charmed PostgreSQL K8s has moved to a [new home](https://canonical-charmed-postgresql-k8s.readthedocs-hosted.com/)! Please update your bookmarks, and [contact us](https://matrix.to/#/#charmhub-data-platform:ubuntu.com) if you have any questions. +[/note] # Charmed PostgreSQL K8s documentation +Charmed PostgreSQL is an open-source software operator designed to deploy and operate object-relational databases on Kubernetes. It packages the powerful database management system [PostgreSQL](https://www.postgresql.org/) into a charmed operator for deployment with [Juju](https://juju.is/docs/juju). -Charmed PostgreSQL K8s is an open-source operator designed to deploy and operate object-relational databases on IAAS/VM. It packages the powerful database management system [PostgreSQL](https://www.postgresql.org/) into a charmed operator for deployment with [Juju](https://juju.is/docs/juju). - -This charm offers automated operations management from day 0 to day 2. It is equipped with several features to securely store and scale complicated data workloads, including TLS encryption, backups, monitoring, password rotation, and easy integration with client applications. - -Charmed PostgreSQL K8s meets the need of deploying PostgreSQL in a structured and consistent manner while providing flexibility in configuration. It simplifies deployment, scaling, configuration and management of relational databases in large-scale production environments reliably. - -This charmed operator is made for anyone looking for a comprehensive database management interface, whether for operating a complex production environment or simply as a playground to learn more about databases and charms. - - - - -| | | -|--|--| -| [**Tutorials**](/t/9296)
[Get started](/t/9296) - a hands-on introduction to using Charmed PostgreSQL K8s operator for new users
| [**How-to guides**](/t/9592)
Step-by-step guides covering key operations such as [scaling](/t/9592), [encryption](/t/9593), and [restoring backups](/t/9597) | -| [**Reference**](/t/13976)
Technical information such as [requirements](/t/11744), [release notes](/t/11872), and [plugins](/t/10945) | [**Explanation**](/t/11856)
Concepts - discussion and clarification of key topics such as [architecture](/t/11856), [users](/t/10843), and [legacy charms](/t/11013)| - -## Project and community -Charmed PostgreSQL K8s is an official distribution of PostgreSQL. It’s an open-source project that welcomes community contributions, suggestions, fixes and constructive feedback. -- [Read our Code of Conduct](https://ubuntu.com/community/code-of-conduct) -- [Join the Discourse forum](https://discourse.charmhub.io/tag/postgresql) -- [Contribute](https://github.com/canonical/postgresql-k8s-operator/blob/main/CONTRIBUTING.md) and report [issues](https://github.com/canonical/postgresql-operator/issues/new/choose) -- Explore [Canonical Data Fabric solutions](https://canonical.com/data) -- [Contact us](/t/11852) for all further questions - -## Licencing & 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. - -PostgreSQL is a trademark or registered trademark of PostgreSQL Global Development Group. Other trademarks are the property of their respective owners. +To learn more about how to deploy and manage this charm, see the [official Charmed PostgreSQL K8s documentation](https://canonical-charmed-postgresql-k8s.readthedocs-hosted.com/) # Navigation @@ -39,78 +13,78 @@ PostgreSQL is a trademark or registered trademark of PostgreSQL Global Developme | Level | Path | Navlink | |--------|--------|-------------| -| 1 | tutorial | [Tutorial](/t/9296) | -| 2 | t-set-up | [1. Set up environment](/t/9297) | -| 2 | t-deploy | [2. Deploy PostgreSQL](/t/9298) | -| 2 | t-access | [3. Access PostgreSQL](/t/13702) | -| 2 | t-scale | [4. Scale replicas](/t/9299) | -| 2 | t-manage-passwords | [5. Manage passwords](/t/9300) | -| 2 | t-integrate | [6. Integrate with other applications](/t/9301) | -| 2 | t-enable-tls | [7. Enable TLS encryption](/t/9302) | -| 2 | t-clean-up | [8. Clean up environment](/t/9303) | -| 1 | how-to | [How-to guides](/t/16767) | -| 2 | h-deploy | [Deploy](/t/16810) | -| 3 | h-deploy-canonical-k8s | [Canonical K8s](/t/15937) | -| 3 | h-deploy-gke | [GKE](/t/11237) | -| 3 | h-deploy-eks | [EKS](/t/12106) | -| 3 | h-deploy-aks | [AKS](/t/14307) | -| 3 | h-deploy-multi-az | [Multi-AZ](/t/15678) | -| 3 | h-deploy-terraform | [Terraform](/t/14924) | -| 3 | h-deploy-airgapped | [Air-gapped](/t/15691) | -| 2 | h-integrate | [Integrate with another application](/t/9594) | -| 2 | h-manage-passwords | [Manage passwords](/t/17860) | -| 2 | h-external-access | [External network access](/t/15701) | -| 2 | h-scale | [Scale replicas](/t/9592) | -| 2 | h-enable-tls | [Enable TLS](/t/9593) | -| 2 | h-enable-ldap | [Enable LDAP](/t/17189) | -| 2 | h-enable-plugins-extensions | [Enable plugins/extensions](/t/10907) | -| 2 | h-backup | [Back up and restore]() | -| 3 | h-configure-s3-aws | [Configure S3 AWS](/t/9595) | -| 3 | h-configure-s3-radosgw | [Configure S3 RadosGW](/t/10316) | -| 3 | h-create-backup | [Create a backup](/t/9596) | -| 3 | h-restore-backup | [Restore a backup](/t/9597) | -| 3 | h-manage-backup-retention | [Manage backup retention](/t/14203) | -| 3 | h-migrate-cluster | [Migrate a cluster](/t/9598) | -| 2 | h-monitor | [Monitoring (COS)]() | -| 3 | h-enable-monitoring | [Enable monitoring](/t/10812) | -| 3 | h-enable-alert-rules | [Enable alert rules](/t/12982) | -| 3 | h-enable-tracing | [Enable tracing](/t/14786) | -| 2 | h-upgrade | [Upgrade](/t/12092) | -| 3 | h-upgrade-minor | [Perform a minor upgrade](/t/12095) | -| 3 | h-rollback-minor | [Perform a minor rollback](/t/12096) | -| 2 | h-async | [Cross-regional async replication](/t/15413) | -| 3 | h-async-set-up | [Set up clusters](/t/13895) | -| 3 | h-async-integrate | [Integrate with a client app](/t/13896) | -| 3 | h-async-remove-recover | [Remove or recover a cluster](/t/13897) | -| 2 | h-development| [Development]() | -| 3 | h-development-integrate | [Integrate with your charm](/t/11853) | -| 3 | h-migrate-pgdump | [Migrate data via pg_dump](/t/12162) | -| 3 | h-migrate-backup-restore | [Migrate data via backup/restore](/t/12161) | -| 1 | reference | [Reference](/t/13977) | -| 2 | r-releases | [Releases](/t/11872) | -| 2 | r-system-requirements | [System requirements](/t/11744) | -| 2 | r-software-testing | [Software testing](/t/11774) | -| 2 | r-performance | [Performance and resources](/t/11975) | -| 2 | r-troubleshooting | [Troubleshooting](/t/11854) | -| 2 | r-plugins-extensions | [Plugins/extensions](/t/10945) | -| 2 | r-alert-rules | [Alert rules](/t/15840) | -| 2 | e-statuses | [Statuses](/t/11855) | -| 2 | r-contacts | [Contacts](/t/11852) | -| 1 | explanation | [Explanation](/t/16769) | -| 2 | e-architecture | [Architecture](/t/11856) | -| 2 | e-interfaces-endpoints | [Interfaces/endpoints](/t/10252) | -| 2 | e-juju-details | [Juju](/t/11986) | -| 2 | e-legacy-charm | [Legacy charm](/t/11013) | -| 2 | e-users | [Users](/t/10843) | -| 2 | e-logs | [Logs](/t/12098) | -| 2 | e-connection-pooling| [Connection pooling](/t/15799) | -| 2 | e-security | [Security](/t/16850) | -| 3 | e-cryptography | [Cryptography](/t/16851) | -| 2 | flowcharts | [Flowcharts]() | -| 3 | e-flowchart-charm | [Charm](/t/9305) | -| 3 | e-flowchart-peers | [Relations](/t/9306) | -| 3 | e-flowchart-backups | [Backups](/t/10248) | -| 1 | search | [Search](https://canonical.com/data/docs/postgresql/k8s) | +| 1 | | [Overview](/t/9307) | +| 2 | tutorial | [](/t/9296) | +| 2 | t-set-up | [](/t/9297) | +| 2 | t-deploy | [](/t/9298) | +| 2 | t-access | [](/t/13702) | +| 2 | t-scale | [](/t/9299) | +| 2 | t-manage-passwords | [](/t/9300) | +| 2 | t-integrate | [](/t/9301) | +| 2 | t-enable-tls | [](/t/9302) | +| 2 | t-clean-up | [](/t/9303) | +| 2 | how-to | [](/t/16767) | +| 2 | h-deploy | [](/t/16810) | +| 2 | h-deploy-canonical-k8s | [](/t/15937) | +| 2 | h-deploy-gke | [](/t/11237) | +| 2 | h-deploy-eks | [](/t/12106) | +| 2 | h-deploy-aks | [](/t/14307) | +| 2 | h-deploy-multi-az | [](/t/15678) | +| 2 | h-deploy-terraform | [](/t/14924) | +| 2 | h-deploy-airgapped | [](/t/15691) | +| 2 | h-integrate | [](/t/9594) | +| 2 | h-manage-passwords | [](/t/17860) | +| 2 | h-external-access | [](/t/15701) | +| 2 | h-scale | [](/t/9592) | +| 2 | h-enable-tls | [](/t/9593) | +| 2 | h-enable-ldap | [](/t/17189) | +| 2 | h-enable-plugins-extensions | [](/t/10907) | +| 2 | h-backup | []() | +| 2 | h-configure-s3-aws | [](/t/9595) | +| 2 | h-configure-s3-radosgw | [](/t/10316) | +| 2 | h-create-backup | [](/t/9596) | +| 2 | h-restore-backup | [](/t/9597) | +| 2 | h-manage-backup-retention | [](/t/14203) | +| 2 | h-migrate-cluster | [](/t/9598) | +| 2 | h-monitor | []() | +| 2 | h-enable-monitoring | [](/t/10812) | +| 2 | h-enable-alert-rules | [](/t/12982) | +| 2 | h-enable-tracing | [](/t/14786) | +| 2 | h-upgrade | [](/t/12092) | +| 2 | h-upgrade-minor | [](/t/12095) | +| 2 | h-rollback-minor | [](/t/12096) | +| 2 | h-async | [](/t/15413) | +| 2 | h-async-set-up | [](/t/13895) | +| 2 | h-async-integrate | [](/t/13896) | +| 2 | h-async-remove-recover | [](/t/13897) | +| 2 | h-development| []() | +| 2 | h-development-integrate | [](/t/11853) | +| 2 | h-migrate-pgdump | [](/t/12162) | +| 2 | h-migrate-backup-restore | [](/t/12161) | +| 2 | reference | [](/t/13977) | +| 2 | r-releases | [](/t/11872) | +| 2 | r-system-requirements | [](/t/11744) | +| 2 | r-software-testing | [](/t/11774) | +| 2 | r-performance | [](/t/11975) | +| 2 | r-troubleshooting | [](/t/11854) | +| 2 | r-plugins-extensions | [](/t/10945) | +| 2 | r-alert-rules | [](/t/15840) | +| 2 | e-statuses | [](/t/11855) | +| 2 | r-contacts | [](/t/11852) | +| 2 | explanation | [](/t/16769) | +| 2 | e-architecture | [](/t/11856) | +| 2 | e-interfaces-endpoints | [](/t/10252) | +| 2 | e-juju-details | [](/t/11986) | +| 2 | e-legacy-charm | [](/t/11013) | +| 2 | e-users | [](/t/10843) | +| 2 | e-logs | [](/t/12098) | +| 2 | e-connection-pooling| [](/t/15799) | +| 2 | e-security | [](/t/16850) | +| 2 | e-cryptography | [](/t/16851) | +| 2 | flowcharts | []() | +| 2 | e-flowchart-charm | [](/t/9305) | +| 2 | e-flowchart-peers | [](/t/9306) | +| 2 | e-flowchart-backups | [](/t/10248) | [/details]