Add documentation for cloudsql migration

docs/operate/cli/reference/postgres.md

@@ -159,3 +159,69 @@ nais postgres password rotate appname
 | Argument    | Required  | Description                                                 |
 |-------------|-----------|-------------------------------------------------------------|
 | appname     | Yes       | Name of application owning the database                     |
+
+
+## migrate 
+
+Commands used for migrating to a new postgres instance.
+
+See also [Migrating to a new SQLInstance](../../../persistence/postgres/how-to/migrate-to-new-instance.md)
+
+### migrate setup
+
+Setup will create a new (target) instance with updated configuration, and enable continuous replication of data from the source instance.
+
+```bash
+nais postgres migrate setup appname new-instance-name
+```
+
+| Argument          | Required | Description                                     |
+|-------------------|----------|-------------------------------------------------|
+| appname           | Yes      | Name of application owning the database         |
+| new-instance-name | Yes      | Name of the new postgres instance to migrate to |
+
+
+| Flag      | Description                                                                                                                     |
+|-----------|---------------------------------------------------------------------------------------------------------------------------------|
+| tier      | Tier of new instance. See [Postgres reference](../../../persistence/postgres/reference/README.md#server-size).                  |
+| type      | Postgres version of new instance. See [Postgres reference](../../../persistence/postgres/reference/README.md#postgres-version). |
+| disk-size | Disk size of new instance.                                                                                                      |
+
+### migrate promote
+
+Promote will promote the target instance to the new primary instance, and update the application to use the new instance.
+
+```bash
+nais postgres migrate promote appname new-instance-name
+```
+
+| Argument          | Required | Description                                     |
+|-------------------|----------|-------------------------------------------------|
+| appname           | Yes      | Name of application owning the database         |
+| new-instance-name | Yes      | Name of the new postgres instance to migrate to |
+
+### migrate finalize
+
+Finalize will remove the source instance and associated resources after a successful migration.
+
+```bash
+nais postgres migrate finalize appname new-instance-name
+```
+
+| Argument          | Required | Description                                     |
+|-------------------|----------|-------------------------------------------------|
+| appname           | Yes      | Name of application owning the database         |
+| new-instance-name | Yes      | Name of the new postgres instance to migrate to |
+
+### migrate rollback
+
+Rollback will roll back the migration, and restore the application to use the original instance.
+
+```bash
+nais postgres migrate rollback appname new-instance-name
+```
+
+| Argument          | Required | Description                                     |
+|-------------------|----------|-------------------------------------------------|
+| appname           | Yes      | Name of application owning the database         |
+| new-instance-name | Yes      | Name of the new postgres instance to migrate to |

docs/persistence/postgres/README.md

@@ -8,7 +8,8 @@ tags: [explanation, persistence, services]
     Postgres 15 has changed the security model around the public schema and it is no longer world writeable. If you and your team
     make use of the public schema for interactive sessions and experimentation you will have to create separate schemas for separate users and share these role or user grants. Normal app usage will function normally.
 
-[PostgreSQL](https://www.postgresql.org/) is a relational database service provided by Google Cloud Platform. It is a good choice for storing data that is relational in nature.
+[PostgreSQL](https://www.postgresql.org/) is a relational database which is a good choice for storing data that is relational in nature.
+In the nais platform, we use CloudSQL from the Google Cloud Platform to provide managed PostgreSQL databases.
 
 Minimal configuration needed to provision a database for your application:
 
@@ -29,7 +30,7 @@ spec:
           - name: mydb
 ```
 
-The default configuration sets up the instance with:
+The default configuration sets up the [instance](explanations/cloud-sql-instance.md) with:
 
 - 10 GB of SSD storage
 - no automatic storage increase

docs/persistence/postgres/explanations/cloud-sql-instance.md

@@ -0,0 +1,94 @@
+---
+title: Cloud SQL Instance
+tags: [postgres, cloudsql, cloud, sql, explanation, sqlinstance]
+---
+
+# Cloud SQL Instance
+
+A Cloud SQL instance is a managed database server provided by Google Cloud Platform.
+In nais, these are used to provide PostgreSQL databases for your applications.
+
+You manage your Cloud SQL instance by defining it in your [application manifest](../../../workloads/application/reference/application-spec.md#gcpsqlinstances).
+
+```yaml title="app.yaml"
+...
+apiVersion: nais.io/v1alpha1
+kind: Application
+metadata:
+  name: myapp
+...
+spec:
+  ...
+  gcp:
+    sqlInstances:
+      - type: POSTGRES_16
+        tier: db-f1-micro
+        databases:
+          - name: mydb
+```
+
+A Cloud SQL Instance can have more than one database, but in nais we have decided to limit it to one database per instance.
+
+In nais, an Application can only have one SQL Instance. 
+We believe that an application should not need more than one database. 
+If you have a need for more than one database, you should consider splitting your application into multiple applications. 
+
+## Attributes of an SQL Instance
+
+### Machine type
+
+SQL Instances are sized by the tier.
+Tier are predefined configurations of CPU and memory. 
+See the [reference](../reference/README.md#server-size) for possible tiers.
+
+The tier you select also influence other properties of the instance, such as max number of connections.
+
+### Networking
+
+SQL Instances are created with a private IP address, ensuring that database communication never leaves the Google Cloud network.
+
+Prior to 2024-04-18, SQL Instances were created with a single public IP address, and required using [Cloud SQL Proxy](https://cloud.google.com/sql/docs/postgres/sql-proxy) to connect.
+Cloud SQL proxy ensures that the database communication over the open internet happened in a secure tunnel, authenticated with automatically rotated credentials.
+
+By using private IP, you can avoid the need for Cloud SQL Proxy, and connect directly to the database from your application.
+
+### Disks
+
+SQL Instances are created with a default disk size of 10 GB.
+If you need more, you can increase the disk size in the `app.yaml` file.
+
+SSD disks are the default.
+You can use HDD disks if you wish to reduce cost a bit.
+
+Consult the [Google documentation for details](https://cloud.google.com/sql/docs/postgres/choosing-ssd-hdd).
+
+## Making changes to an SQL Instance
+
+Most changes you wish to do to your SQL Instance can be done by modifying the `app.yaml` file and redeploying your application.
+Simple changes will be applied to your SQL Instance with virtually no downtime, but other changes may take longer.
+
+Some of these changes can not be undone, such are changing the major version of PostgreSQL or increasing disk size.
+
+There are also some changes that can not be done without creating a new SQL Instance.
+
+Some changes that will work, but require a non-trivial amount of downtime:
+
+* [Changing the tier](../how-to/change-tier.md)
+* [Upgrade major version](../how-to/upgrade-postgres.md)
+
+Most other changes will require a restart of the SQL Instance, which typically takes less than a minute.
+
+Changes that can not be done without creating a new SQL Instance:
+
+* Switching from Cloud SQL Proxy to private IP
+* Reducing disk size
+
+### Migrating your application to a new SQL Instance
+
+Use cases where migrating to a new SQL instances may be preferable or required:
+
+* Upgrading to a new major version of PostgreSQL with an option to roll back to the previous version.
+* Reducing disk size.
+* Switching from Cloud SQL Proxy to private IP.
+
+Learn [how to create a new SQL Instance and migrate your application](../how-to/migrate-to-new-instance.md).

docs/persistence/postgres/how-to/migrate-to-new-instance.md

@@ -0,0 +1,78 @@
+---
+title: Migrate to new instance
+tags: [postgres, migrate, how-to]
+---
+
+# Migrating to a new SQLInstance
+
+This guide describes how to migrate your PostgreSQL database to a new [SQLInstance](../explanations/cloud-sql-instance.md).
+
+## Preparations
+
+* During migration, you can't make DDL changes (changing structure of tables, adding or removing tables, etc.) to your database. 
+  Check with your team to avoid any problems during the migration.
+* Make sure to have the latest version of the [nais CLI](../../../operate/cli/README.md) installed.
+* Decide on a new name for the new SQLInstance. It must be different from the current SQLInstance name.
+* naisdevice connected.
+* Access to the nais cluster where the application is running.
+
+## Setting up the migration
+
+1. Select the correct kubernetes context and namespace
+
+   ```shell
+   kubectl config use-context <cluster>
+   kubectl config set-context --current --namespace=<namespace>
+   ```
+
+2. Run the [setup](../../../operate/cli/reference/postgres.md#migrate-setup) command and follow the prompts
+
+    ```shell
+    nais migrate postgres setup <appname> <new-sql-instance-name>
+    ```
+
+3. Check that the new instance contains expected data
+4. Check that the replication is up to date by checking the URL you got from the setup command.
+   This may take some time, depending on how much data needs to be transferred. 
+
+## Promoting the new SQLInstance
+
+!!! warning
+
+    Promoting the new SQLInstance will cause downtime for your application.
+    Before proceeding, decide on a time when your application can have downtime to perform the promotion.
+
+1. Run the [promote](../../../operate/cli/reference/postgres.md#migrate-promote) command and follow the instructions
+
+    ```shell
+    nais migrate postgres promote <appname> <new-sql-instance-name>
+    ```
+
+2. Check that the application is running as expected, and that all data is available in the new SQLInstance.
+3. If everything is working as expected, you can proceed to the next step.
+   If something is not working, and you need to roll back, go to the [rollback section](#rolling-back-the-migration).
+
+## Finalizing the migration
+
+!!! warning
+
+    This will delete the old SQLInstance and all data in it. 
+    Make sure you have verified that all data is available in the new SQLInstance before proceeding.
+
+    There is no rollback option after this point.
+
+1. Run the [finalize](../../../operate/cli/reference/postgres.md#migrate-finalize) command
+
+    ```shell
+    nais migrate postgres finalize <appname> <new-sql-instance-name>
+    ```
+
+## Rolling back the migration
+
+If you decide to not go through with the migration, you can roll back to the old SQLInstance at any point (unless you have run finalize).
+
+1. Run the [rollback](../../../operate/cli/reference/postgres.md#migrate-rollback) command
+
+    ```shell
+    nais migrate postgres rollback <appname> <new-sql-instance-name>
+    ```

docs/persistence/postgres/reference/README.md

@@ -39,7 +39,7 @@ You can customize these environment variable names by setting `.spec.gcp.sqlInst
 
 For instance, setting this to `DB` will give you `DB_HOST`, `DB_USERNAME`, etc. Note that changing or adding `envVarPrefix` requires you to manually delete the `google-sql-<MYAPP>` secret and `SQLUser` with the same name as the application, see below.
 
-If you habe hyphens (`-`) in your application name or database name, they will be converted to underscores (`_`). E.g. `my-awesome-app` = `MY_AWESOME_APP`.
+If you have hyphens (`-`) in your application name or database name, they will be converted to underscores (`_`). E.g. `my-awesome-app` = `MY_AWESOME_APP`.
 
 !!! info
     Note that if you change your application name, database name or envVarPrefix, and then change it later,
@@ -143,7 +143,7 @@ For further reading see [google Cloud SQL PIT recovery](https://cloud.google.com
 
 In case of catastrophic failure in GCP we are running a daily complete backup of the postgresql databases in GCP to an on-prem location. This backup currently runs at 5 am. This is in addition to the regular backups in GCP.
 
-## Postgres vesion
+## Postgres version
 
 The Postgres version can be configured in the application spec. The version is defined by the `type` field in the `nais.yaml` file.
 
@@ -160,7 +160,8 @@ The full list of supported versions can be found in the [application spec refere
 
 ## Server size
 
-The server instance size can be configured in the application spec. The instance size is defined by the `tier` field in the `nais.yaml` file.
+The [server instance](../explanations/cloud-sql-instance.md) size can be configured in the application spec.
+The instance size is defined by the `tier` field in the `nais.yaml` file.
 
 ```yaml title="app.yaml" hl_lines="5"
 spec: