docs: upgrading notes (postgres archive and ARGO_TEMPLATE) (#13803)

Signed-off-by: Alan Clucas <[email protected]>

Author: Joibel

docs/upgrading.md

@@ -30,6 +30,15 @@ Use `ARGO_ALLOWED_LINK_PROTOCOL` and `ARGO_BASE_HREF` instead.
 
 For the Emissary executor to work properly, you must set up RBAC. See [workflow RBAC](workflow-rbac.md)
 
+### Archived Workflows on PostgreSQL
+
+This upgrade will transform an archived workflow column from type `json` to type `jsonb`.
+This will take some time if you have a lot of archived workflows.
+This requires PostgreSQL version 9.4 or higher.
+
+You can perform this modification prior to upgrading with `alter table argo_archived_workflows alter column workflow set data type jsonb using workflow::jsonb`.
+This is considered safe to do whilst running version 3.5 as the column types are compatible.
+
 ### Metrics changes
 
 You can now retrieve metrics using the OpenTelemetry Protocol using the [OpenTelemetry collector](https://opentelemetry.io/docs/collector/), and this is the recommended mechanism.
@@ -95,6 +104,11 @@ To disable this set `metricsConfig.secure` to `false`.
 When returning a map or array in an expression, you would get a Golang representation.
 This now returns plain JSON.
 
+### `ARGO_TEMPLATE` removed from main container
+
+The environment variable `ARGO_TEMPLATE` which is an internal implementation detail is no longer available inside the `main` container of your workflow pods.
+This is documented here as we are aware that some users of Argo Workflows use this.
+
 ## Upgrading to v3.5
 
 There are no known breaking changes in this release.

docs/workflow-archive.md

@@ -2,7 +2,7 @@
 
 > v2.5 and after
 
-If you want to keep completed workflows for a long time, you can use the workflow archive to save them in a Postgres or MySQL (>= 5.7.8) database.
+If you want to keep completed workflows for a long time, you can use the workflow archive to save them in a Postgres (>=9.4) or MySQL (>= 5.7.8) database.
 The workflow archive stores the status of the workflow, which pods have been executed, what was the result etc.
 The job logs of the workflow pods will not be archived.
 If you need to save the logs of the pods, you must setup an [artifact repository](artifact-repository-ref.md) according to [this doc](configure-artifact-repository.md).
@@ -17,7 +17,7 @@ To enable archiving of the workflows, you must configure database parameters in
 
 Example:
 
-    persistence: 
+    persistence:
       archive: true
       postgresql:
         host: localhost
@@ -56,7 +56,7 @@ In this case you can delete all the above tables and restart the workflow-contro
 
 If you know what are you doing you also have an option to skip migration:
 
-    persistence: 
+    persistence:
       skipMigration: true
 
 ## Required database permissions
@@ -72,7 +72,7 @@ The default is forever.
 
 Example:
 
-    persistence: 
+    persistence:
       archiveTTL: 10d
 
 The `ARCHIVED_WORKFLOW_GC_PERIOD` variable defines the periodicity of running the garbage collection function.
@@ -86,7 +86,7 @@ Optionally you can set a unique name of your Kubernetes cluster. This name will
 
 Example:
 
-    persistence: 
+    persistence:
       clusterName: dev-cluster
 
 ## Disabling Workflow Archive
@@ -95,5 +95,5 @@ To disable archiving of the workflows, set `archive:` to  `false` in the `persis
 
 Example:
 
-    persistence: 
+    persistence:
       archive: false