docs(self-hosted): Add PostgreSQL upgrade guides for AWS, GCP, and Azure (#1026)

* Add official PostgreSQL 17 support

We've been running PostgreSQL 17 internally for long enough to confidently
add it to the officially supported versions list.

* Add PostgreSQL upgrade guides for AWS, GCP, and Azure

New "Upgrading PostgreSQL" section covering:
- Minor vs major version differences and recommendations
- What to expect during upgrades (UI downtime, missed webhooks)
- Worker scale-down procedure before upgrading
- Cloud provider-specific instructions with downtime estimates
- AWS Blue/Green Deployments option for near-zero downtime

Also adds changelog entry for the new documentation.

* Add AWS module updates for PostgreSQL upgrades to changelog

Document the base infra (v2.1.1) and EKS (v3.2.0) module changes that
enable major PostgreSQL version upgrades:

- RDS parameter groups now use name_prefix for create-before-destroy
- New rds_apply_immediately variable (defaults to true)
- New rds_engine_version_actual output

Also notes that GCP and Azure already handle upgrades natively.

Author: peterdeme

docs/installing-spacelift/changelog.md

@@ -8,7 +8,8 @@ description: Find out about the latest changes to the Self-Hosted Spacelift.
 
 ### Features
 
-- **VCS Gateway support for EKS, GKE, and AKS**: The [EKS](https://github.com/spacelift-io/terraform-aws-eks-spacelift-selfhosted){: rel="nofollow"}, [GKE](https://github.com/spacelift-io/terraform-google-spacelift-selfhosted){: rel="nofollow"}, and [AKS](https://github.com/spacelift-io/terraform-azure-spacelift-selfhosted){: rel="nofollow"} Terraform modules now include optional configuration for the VCS Gateway service.
+- **Rego v1 support**: Self-hosted installations now support [Rego v1](../concepts/policy/README.md#rego-version-support) for policies. We recommend using Rego v1 for all new policies and migrating existing policies to v1 as soon as possible. Rego v1 introduces improved syntax and stricter semantics that make policies more robust and easier to maintain. For migration guidance, see the [OPA migration guide](https://www.openpolicyagent.org/docs/v0-upgrade#changes-to-rego-in-opa-v10){: rel="nofollow"}.
+- **VCS Gateway support for EKS, GKE, and AKS**: The [EKS](https://github.com/spacelift-io/terraform-aws-eks-spacelift-selfhosted){: rel="nofollow"}, [GKE](https://github.com/spacelift-io/terraform-google-spacelift-selfhosted){: rel="nofollow"}, and [AKS](https://github.com/spacelift-io/terraform-azure-spacelift-selfhosted){: rel="nofollow"} Terraform modules now include optional configuration for the VCS Gateway service. Requires [Helm chart v0.56.0](https://github.com/spacelift-io/spacelift-helm-charts/releases/tag/v0.56.0){: rel="nofollow"} or later.
 
     By default, Spacelift communicates with your VCS provider directly, but some organizations need to host their VCS systems internally where Spacelift can't reach them. The VCS Gateway is the backend component that enables [VCS Agent Pools](../concepts/vcs-agent-pools.md) to bridge this gap - VCS Agents running in your infrastructure connect to the gateway and proxy requests to your private GitLab, GitHub Enterprise, Bitbucket Data Center, or Azure DevOps instances.
 
@@ -20,10 +21,9 @@ description: Find out about the latest changes to the Self-Hosted Spacelift.
     - [GKE](./reference-architecture/guides/deploying-to-gke.md#vcs-gateway-service)
     - [AKS](./reference-architecture/guides/deploying-to-aks.md#vcs-gateway-service)
 
-- **Rego Version Selector**: Added support for switching between Rego v0 and v1 when editing policies. A version selector is now available in the policy editor, allowing you to easily switch between versions. We recommend using Rego v1 for all new policies. See the [policy documentation](../concepts/policy/README.md#rego-version-support) for more information.
-
 ### Documentation
 
+- **PostgreSQL upgrade guides**: Added a comprehensive [Upgrading PostgreSQL](./reference-architecture/external-dependencies.md#upgrading-postgresql) section covering everything you need to know before upgrading your database: expected downtime for minor and major upgrades, what happens to your Spacelift installation during the upgrade, and cloud provider-specific instructions for AWS, GCP, and Azure. For AWS users, we also published a dedicated [RDS Upgrade Guide](https://github.com/spacelift-io/terraform-aws-spacelift-selfhosted/blob/main/docs/rds-upgrade-guide.md){: rel="nofollow"} with step-by-step instructions for our Terraform modules.
 - **GKE deployment guide**: Updated [database configuration steps](./reference-architecture/guides/deploying-to-gke.md#configure-database) to include schema permissions required for PostgreSQL 15+, which no longer grants CREATE privileges on the public schema by default.
 - **AKS and GKE deployment guides**: Bumped the cert-manager Helm chart version to v1.19.2. We recommend upgrading your cert-manager deployment to stay current with security patches and bug fixes.
 

docs/installing-spacelift/reference-architecture/external-dependencies.md

@@ -30,10 +30,9 @@ On the other hand, the components below are mandatory and **must be provided**:
 Spacelift only supports **PostgreSQL**.
 
 !!! warning
+    Creating a database in Kubernetes, while possible, is not recommended. If you choose to do so, set up a volume for continuity of operations in the event of a power outage.
 
-        Creating a database in Kubernetes, while possible, is not recommended. If you choose to do so, set up a volume for continuity of operations in the event of a power outage.
-
-While PostgreSQL versions higher than 16 may work with Spacelift, please note that these versions have not been officially tested or supported.
+While PostgreSQL versions higher than 17 may work with Spacelift, please note that these versions have not been officially tested or supported.
 
 As such, we cannot guarantee compatibility or provide assistance for any issues that may arise. We recommend using these versions at your own discretion and risk.
 
@@ -49,7 +48,40 @@ If you already have an existing PostgreSQL instance running, you can reuse it. S
 | PostgreSQL 14.x |               ✅                |
 | PostgreSQL 15.x |               ✅                |
 | PostgreSQL 16.x |               ✅                |
-| PostgreSQL ≥ 17 | ⚠️ **not officially supported** |
+| PostgreSQL 17.x |               ✅                |
+| PostgreSQL ≥ 18 | ⚠️ **not officially supported** |
+
+### Upgrading PostgreSQL
+
+PostgreSQL uses a `major.minor` versioning scheme. **Minor upgrades** (e.g., 16.1 → 16.4) contain bug fixes and security patches without changing the internal storage format, making them low-risk and quick to apply. **Major upgrades** (e.g., 16 → 17) introduce new features and improvements but require data migration due to internal storage format changes, which is why they take longer and require more planning.
+
+We recommend staying current with minor versions for security and stability. For major upgrades, plan ahead and review the considerations below before proceeding.
+
+Minor upgrades across all cloud providers come with no downtime or at most a few seconds of interruption. Major upgrades typically require 15-30 minutes of downtime. All Spacelift services are designed to self-heal once the database is back online, so you don't need scale down, up, redeploy or restart any Spacelift components during the upgrade.
+
+During a major upgrade:
+
+- The Spacelift UI will be unavailable and return internal errors.
+- **Spacelift won't receive webhooks from your VCS provider** - any pushes or pull request events during this window will be missed. Schedule major upgrades outside of working hours when traffic is low.
+- Cloud providers typically create a database snapshot before starting the upgrade, but verify this in your provider's documentation.
+- Scale [worker](../../concepts/worker-pools/README.md) replica counts to 0 before initiating the upgrade. This is a graceful operation: in-flight runs will complete first, then workers will shut down. Wait until all workers are down before starting the database upgrade to prevent runs from failing to report run results back to the unavailable Spacelift API.
+
+=== "AWS"
+    Minor upgrades can use Zero-Downtime Patching on Aurora PostgreSQL, resulting in zero downtime or at most a few failed queries. Major upgrades require 12-30 minutes of downtime depending on instance size and data volume.
+
+    For near-zero downtime, [Blue/Green Deployments](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/blue-green-deployments.html){: rel="nofollow"} allow you to upgrade a staging copy first, then switch over in under a minute - though this approach requires more setup and coordination.
+
+    For step-by-step instructions using our Terraform modules, see the [RDS Upgrade Guide](https://github.com/spacelift-io/terraform-aws-spacelift-selfhosted/blob/main/docs/rds-upgrade-guide.md){: rel="nofollow"}. For general Aurora/RDS upgrades, see the [AWS documentation](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_UpgradeDBInstance.PostgreSQL.html){: rel="nofollow"}.
+
+=== "GCP"
+    Minor upgrades are applied automatically during maintenance windows or can be triggered manually with minimal downtime. Major upgrades require downtime, typically completing in 15-30 minutes depending on database size. Running a precheck operation before upgrading is recommended.
+
+    See [Upgrade PostgreSQL in-place](https://cloud.google.com/sql/docs/postgres/upgrade-major-db-version-inplace){: rel="nofollow"} in the Cloud SQL documentation.
+
+=== "Azure"
+    Minor upgrades are handled automatically by Azure. Major upgrades are performed in-place and typically complete in around 20 minutes, though duration depends on database size. Read replicas must be deleted before upgrading.
+
+    See [Major version upgrade](https://learn.microsoft.com/en-us/azure/postgresql/flexible-server/concepts-major-version-upgrade){: rel="nofollow"} in the Azure Database for PostgreSQL documentation.
 
 ## Object storage backend
 

docs/vendors/terraform/terraform-provider.md

@@ -25,6 +25,7 @@ The following table shows the latest version of the Terraform provider known to
 
 | Self-Hosted Version | Max Provider Version |
 | ------------------- | -------------------- |
+| 4.1.0               | 1.43.0               |
 | 4.0.0               | 1.42.0               |
 | 3.8.0               | 1.40.0               |
 | 3.7.0               | 1.37.0               |