docs(workspace): Add warnings to kong migrations

app/_includes/md/enterprise/migration-finish-warning.md

@@ -0,0 +1 @@
+When adding new plugins to the existing installation (either manually or via the extension of `bundled` plugins), the `kong migrations finish` or `kong migrations up` must be run with the `-f` flag to forcefully upgrade the plugin schemas.

app/_src/gateway/admin-api/workspaces/reference.md

@@ -300,6 +300,9 @@ Attributes | Description
 `name or id`<br>**required** | The unique identifier **or** the name of the workspace to delete
 `cascade` | The `cascade` option lets you delete a workspace and all of its entities in one request.
 
+{:.important}
+> **Caution**: If deleting with the `cascade` option fails with a `foreign key violation` error, you may need to upgrade the schema with `kong migrations -f finish`.
+
 
 **Response**
 

app/_src/gateway/breaking-changes/34x.md

@@ -88,3 +88,5 @@ The `/consumer_groups/:id/overrides` endpoint has been deprecated. While this en
 Some referenceable configuration fields, such as the `http_endpoint` field
 of the `http-log` plugin and the `endpoint` field of the `opentelemetry` plugin,
 do not accept reference values due to incorrect field validation.
+
+{% include_cached /md/enterprise/migration-finish-warning.md %}

app/_src/gateway/migrate-ce-to-ke.md

@@ -30,8 +30,11 @@ to be up to date on any pending migration:
 
    ```shell
    kong migrations up [-c configuration_file]
-   kong migrations finish [-c configuration_file]
+   kong migrations -f finish [-c configuration_file]
    ```
 
+   {:.important}
+   > **Caution**: {% include_cached /md/enterprise/migration-finish-warning.md %}
+
 2. Confirm that all of the entities are now available on your
    {{site.ee_product_name}} node.

app/_src/gateway/reference/cli.md

@@ -284,6 +284,8 @@ Options:
 
 ```
 
+{:.important}
+> **Caution**: {% include_cached /md/enterprise/migration-finish-warning.md %}
 ---
 
 

app/_src/gateway/upgrade/blue-green.md

@@ -138,3 +138,6 @@ Write updates to {{site.base_gateway}} can now be performed, though we suggest y
 {:.note}
 > **Note**: This upgrade strategy is not the same thing as the [Blue-green (Canary) Deployment](/gateway/{{page.release}}/production/canary/). 
 That process is meant for upgrading your upstream services and is not related to {{site.base_gateway}} upgrades.
+
+{:.important}
+> **Caution**: {% include_cached /md/enterprise/migration-finish-warning.md %}

app/_src/gateway/upgrade/in-place.md

@@ -96,3 +96,5 @@ Prioritize the database-level restoration method over the application-level meth
 Write updates to {{site.base_gateway}} can now be performed, though we suggest you keep monitoring metrics for a while.
 
 
+{:.important}
+> **Caution**: {% include_cached /md/enterprise/migration-finish-warning.md %}

app/gateway/changelog.md

@@ -3511,6 +3511,8 @@ hang when attempting to expand an API.
   of the `http-log` plugin and the `endpoint` field of the `opentelemetry` plugin,
   do not accept reference values due to incorrect field validation.
 
+* {% include_cached /md/enterprise/migration-finish-warning.md %}
+
 ## 3.3.1.1
 **Release Date** 2023/10/12