[camel-k] branch main updated: chore(doc): add upgrade instructions

[pc...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

pcongiusti pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel-k.git


The following commit(s) were added to refs/heads/main by this push:
     new f4ae922dd chore(doc): add upgrade instructions
f4ae922dd is described below

commit f4ae922ddb7c4c6e60f8d00c5a34e197cb186b0c
Author: Pasquale Congiusti <pa...@gmail.com>
AuthorDate: Thu Apr 13 15:45:13 2023 +0200

    chore(doc): add upgrade instructions
---
 docs/modules/ROOT/nav-end.adoc                     |  1 -
 docs/modules/ROOT/nav.adoc                         |  2 ++
 .../pages/{ => contributing}/uninstalling.adoc     |  2 +-
 docs/modules/ROOT/pages/contributing/upgrade.adoc  | 33 ++++++++++++++++++++++
 4 files changed, 36 insertions(+), 2 deletions(-)

diff --git a/docs/modules/ROOT/nav-end.adoc b/docs/modules/ROOT/nav-end.adoc
index 06a882fe4..311dee8d1 100644
--- a/docs/modules/ROOT/nav-end.adoc
+++ b/docs/modules/ROOT/nav-end.adoc
@@ -17,7 +17,6 @@
 * API
 ** xref:apis/camel-k.adoc[Camel K API]
 ** xref:apis/kamelets.adoc[Kamelets API]
-* xref:uninstalling.adoc[Uninstalling]
 * xref:contributing/developers.adoc[Contributing]
 ** xref:contributing/local-development.adoc[Local development]
 ** xref:contributing/local-deployment-olm.adoc[Local OLM deployment]
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
index 5615c3d8c..8ff177a9f 100644
--- a/docs/modules/ROOT/nav.adoc
+++ b/docs/modules/ROOT/nav.adoc
@@ -23,6 +23,8 @@
 *** xref:installation/advanced/http-proxy.adoc[HTTP Proxy]
 *** xref:installation/advanced/maven.adoc[Maven]
 *** xref:installation/advanced/multi-architecture.adoc[Multi Architecture]
+** xref:installation/upgrade.adoc[Upgrade]
+** xref:installation/uninstalling.adoc[Uninstalling]
 * Command Line Interface
 ** xref:cli/cli.adoc[Kamel CLI]
 ** xref:cli/file-based-config.adoc[File-based Config]
diff --git a/docs/modules/ROOT/pages/uninstalling.adoc b/docs/modules/ROOT/pages/contributing/uninstalling.adoc
similarity index 92%
rename from docs/modules/ROOT/pages/uninstalling.adoc
rename to docs/modules/ROOT/pages/contributing/uninstalling.adoc
index 105e39e8a..88f376f39 100644
--- a/docs/modules/ROOT/pages/uninstalling.adoc
+++ b/docs/modules/ROOT/pages/contributing/uninstalling.adoc
@@ -1,7 +1,7 @@
 [[uninstalling]]
 = Uninstalling Camel K
 
-If you really need to, it is possible to completely uninstall Camel K from OpenShift or Kubernetes with the following command:
+We're sad to see you go, but If you really need to, it is possible to completely uninstall Camel K from OpenShift or Kubernetes with the following command:
 
 [source]
 ----
diff --git a/docs/modules/ROOT/pages/contributing/upgrade.adoc b/docs/modules/ROOT/pages/contributing/upgrade.adoc
new file mode 100644
index 000000000..ee46d25bd
--- /dev/null
+++ b/docs/modules/ROOT/pages/contributing/upgrade.adoc
@@ -0,0 +1,33 @@
+[[upgrade]]
+= Upgrading Camel K
+
+Camel K is delivering new features with each new release, so, you'll be probably running the upgrade process quite often. OLM installation method gives you the possibility to even perform this operation automatically, selecting the auto-upgrade feature when installing. Here we're providing the steps required for non-OLM installation procedure. This is working when using CLI but it can be adapted to any other installation methodology.
+
+When a new release is available, you need to perform a forcefully installation on top of the existing installation. This is required in order to upgrade the CRDs and any other configuration required by the new operator. You need to replace your `kamel` CLI binary with the new one released. Once you have replaced your `kamel` you can proceed with the installation:
+
+[source]
+----
+kamel install --force --olm=false
+----
+
+This operation will install all the required configuration for the new operator version, replacing the previous one. Mind that the `Integration` resources running won't be affected, so they will keep running with the default runtime details provided in the previous operator version.
+
+[[refresh-integrations]]
+== Refresh integrations
+
+Once the operator is up to date, you may want to refresh the `Integration` resources with the new default configuration provided by the upgraded operator (for instance, the default runtime). In such case you'll need to run a `kamel rebuild` operation for each integration you want to update, or `kamel rebuild --all` if you want to upgrade all the Integrations at once.
+
+NOTE: we suggest a controlled approach and rebuild one integration after another.
+
+[[maintain-runtime-integrations]]
+== Stick runtime version
+
+Since Camel K version 2, we're able to run any Camel K runtime version from the same operator. However, if you upgrade and you rebuild an Integration, this one will be rebuilt using the default runtime version of the new operator. In order to stick to a runtime fixed version you need to use the `Camel` trait and the `runtime-version` property, which pin the exact runtime version to use, regardless the default one used by the operator:
+
+----
+kamel run /tmp/Test.java -t camel.runtime-version=1.17.0
+kamel install --force //ie, version 2.0.0
+kamel rebuild test
+kamel logs test
+[1] 2023-04-13 13:38:43,648 INFO  [org.apa.cam.k.Runtime] (main) Apache Camel K Runtime 1.17.0
+----