doc: kustomize

docs/modules/ROOT/nav.adoc

@@ -1,12 +1,11 @@
 * xref:installation/installation.adoc[Installation]
-** xref:installation/advanced/maven.adoc[Configure Maven]
 ** xref:installation/registry/registry.adoc[Configure Registry]
+** xref:installation/advanced/maven.adoc[Configure Maven]
 ** xref:installation/knative.adoc[Configure Knative]
 ** xref:installation/upgrade.adoc[Upgrade]
 ** xref:installation/uninstalling.adoc[Uninstalling]
 ** xref:installation/advanced/advanced.adoc[Advanced]
 *** xref:installation/advanced/build-config.adoc[Build tuning]
-*** xref:installation/advanced/kustomize.adoc[Install Using Kustomize]
 *** xref:installation/advanced/network.adoc[Network architecture]
 *** xref:installation/advanced/resources.adoc[Resource management]
 *** xref:installation/advanced/multi.adoc[Multiple Operators]

docs/modules/ROOT/pages/installation/installation.adoc

@@ -3,6 +3,11 @@
 
 Camel K allows us to run Camel integrations directly on a Kubernetes or OpenShift cluster. To use it, you need to be connected to a cloud environment or to a local cluster created for development purposes (ie, Minikube or Kind).
 
+[[registry]]
+== Registry requirements
+
+Camel K may require a container registry which is used to store the images built for your applications. Certain clusters may use their internal container registry (ie, Openshift, Minikube or https://github.com/kubernetes/enhancements/tree/master/keps/sig-cluster-lifecycle/generic/1755-communicating-a-local-registry[KEP-1755 compatible] clusters). If it's not the case for your cluster make sure to have a xref:installation/registry/registry.adoc#configuring-registry-install-time[container registry] available and set it according the specific installation methodology chosen.
+
 [[cli]]
 == Installation via Kamel CLI
 
@@ -17,96 +22,80 @@ Once you have put the `kamel` CLI in the path, log into your cluster using the s
 $ kamel install --olm=false
 ----
 
-NOTE: if you're not using Minikube or Openshift, make sure to have a xref:installation/registry/registry.adoc#configuring-registry-install-time[container registry] available and use also `--registry` parameter.
-
 This will configure the cluster with the Camel K custom resource definitions and install the operator on the current namespace with the default settings.
 
 IMPORTANT: Custom Resource Definitions (CRD) are cluster-wide objects and you need admin rights to install them. Fortunately, this operation can be done *once per cluster*. So, if the `kamel install` operation fails, you'll be asked to repeat it when logged as admin.
 For CRC, this means executing `oc login -u system:admin` then `kamel install --cluster-setup` only for the first-time installation.
 
-[[kustomize]]
-== Installation via Kustomize
-
-Camel K can be installed using https://kustomize.io[Kustomize], providing an interface for configuring more advanced features.
+[[helm]]
+== Installation via Helm Hub
 
-**First you need to get the kustomize files**
+Camel K is also available in Helm Hub:
 
 ```
-# Clone the project repository
-$ https://github.com/apache/camel-k.git
-$ cd camel-k
-# You can use any release branch or skip this step to use it the last code on `main`
-$ git checkout release-a.b.x
-$ cd install
+$ helm repo add camel-k https://apache.github.io/camel-k/charts/
+$ helm install camel-k [--set platform.build.registry.address=<my-registry>] camel-k/camel-k
 ```
 
-**Next you need to apply configuration at cluster level**
+More instructions on the https://hub.helm.sh/charts/camel-k/camel-k[Camel K Helm] page.
 
-```
-$ kubectl kustomize --load-restrictor LoadRestrictionsNone setup-cluster/ | kubectl create -f -
-```
+[[olm]]
+== Installation via Operator Hub
 
-**Then the roles and privileges needs to be added**
+Camel K is also available in Operator Hub. You will need the OLM framework to be properly installed in your cluster. More instructions on the https://operatorhub.io/operator/camel-k[Camel K Operator Hub] page.
 
 ```
-$ kubectl apply -k setup
-$ kubectl apply -k pkg/resources/config/rbac/namespaced
-# For openshift
-$ kubectl apply -k pkg/resources/config/rbac/openshift
-$ kubectl apply -k pkg/resources/config/rbac/openshift/namespaced
+$ kubectl create -f https://operatorhub.io/install/camel-k.yaml
 ```
 
-Should you want your operator operator to watch all namespaces (global operator), you will replace `pkg/resources/config/rbac/namespaced` by `pkg/resources/config/rbac/descoped` and `pkg/resources/config/rbac/openshift/namespaced` by `pkg/resources/config/rbac/openshift/descoped`.
+You can edit the `Subscription` custom resource, setting the channel you want to use. From Camel K version 2 onward, we're going to provide an installation channel for each major version we're releasing (ie, `stable-v2`). This will simplify the upgrade process if you choose to perform an automatic upgrade.
 
-**Finally the operator can be deployed**
+NOTE: Some Kubernetes clusters such as Openshift may let you to perform the same operation from a GUI as well. Refer to the cluster instruction to learn how to perform such action from user interface.
 
-```
-$ kubectl apply -k operator
-$ kubectl apply -k platform
-```
+[[kustomize]]
+== Installation via Kustomize
+
+https://kustomize.io[Kustomize] provides a declarative approach to the configuration customization of a Camel-K installation. Kustomize works either with a standalone executable or as a built-in to `kubectl`. The https://github.com/apache/camel-k/tree/main/install[/install] directory provides a series of base and overlays configuration that you can use. You can create your own overlays or customize the one available in the repository to accommodate your need.
 
-By default the operator is configured to get the registry information from a Configmap expected the namespace `kube-public` like this example:
+=== One liner operator installation procedure
+
+If you don't need to provide any configuration nor the registry (ie, in Openshift), you can apply this simple one liner:
 
 ```
-apiVersion: v1
-kind: ConfigMap
-metadata:
-  name: local-registry-hosting
-  namespace: kube-public
-data:
-  localRegistryHosting.v1: |
-    hostFromContainerRuntime: "registry:5000"
+$ kubectl apply -k github.com/apache/camel-k/install/overlays/kubernetes/descoped?ref=v2.4.0 --server-side
 ```
 
-NOTE: you probably want to edit the configuration. Please, do any change right after cloning the repository. Be careful to avoid making any modification in the `install/config` folder.
+You can specify as `ref` parameter the version you're willing to install (ie, `v2.4.0`). The command above will install a descoped (global) operator in the camel-k namespace.
 
-More information on the xref:installation/advanced/kustomize.adoc[Kustomize Camel K installation procedure] page.
+NOTE: if you're not installing in Openshift you will need to manually change the IntegrationPlatform registry configuration as the operator won't be able to find any valid registry address.
 
-[[olm]]
-== Installation via Operator Hub
+=== Custom configuration procedure
 
-Camel K is also available in Operator Hub. You will need the OLM framework to be properly installed in your cluster. More instructions on the https://operatorhub.io/operator/camel-k[Camel K Operator Hub] page.
+Most often you want to specify different parameters to configure the registry and other platform behaviors. In such case you can clone the project repository and use any of the overlays available, customizing to your needs.
 
 ```
-$ kubectl create -f https://operatorhub.io/install/camel-k.yaml
+# Clone the project repository
+$ https://github.com/apache/camel-k.git
+$ cd camel-k
+# You can use any release tag (recommended as it is immutable) or branch
+$ git checkout v2.4.0
+$ cd install/overlays
 ```
 
-You can edit the `Subscription` custom resource, setting the channel you want to use. From Camel K version 2 onward, we're going to provide an installation channel for each major version we're releasing (ie, `stable-v2`). This will simplify the upgrade process if you choose to perform an automatic upgrade.
-
-NOTE: Some Kubernetes clusters such as Openshift (or CRC) may let you to perform the same operation from a GUI as well. Refer to the cluster instruction to learn how to perform such action.
-
-
-[[helm]]
-== Installation via Helm Hub
-
-Camel K is also available in Helm Hub:
+In this directory you may find a series of default configuration for Kubernetes, Openshift and any other sensible profile. For Kubernetes, you can see we have prepared a `descoped` configuration and a `namespaced` which are installing the operator globally or in a specific namespace.
 
 ```
-$ helm repo add camel-k https://apache.github.io/camel-k/charts/
-$ helm install my-camel-k camel-k/camel-k
+# Default, use this namespace (edit `kustomize.yaml` to change it)
+$ kubectl create ns camel-k
+$ kubectl apply -k kubernetes/descoped --server-side
+# Change the registry address (edit the file for more configuration if required)
+$ sed -i 's/address: .*/address: my-registry-host.io/' kubernetes/descoped/integration-platform.yaml
+$ kubectl apply -k platform
 ```
 
-More instructions on the https://hub.helm.sh/charts/camel-k/camel-k[Camel K Helm] page.
+NOTE: you don't need to set the platform if running on Openshift.
+
+The above command will install a global Camel K operator in the `camel-k` namespace using the container registry you've provided. The `server-side` option is required in order to prevent some error while installing CRDs. We need to apply a separate platform configuration as Kustomize may not be yet aware of the CRDs if done in the same step.
 
 [[test]]
 == Test your installation
@@ -128,8 +117,6 @@ Camel K installation is usually straightforward, but for certain cluster types y
 - xref:installation/platform/openshift.adoc[OpenShift]
 - xref:installation/platform/crc.adoc[Red Hat CodeReady Containers (CRC)]
 
-NOTE: Minishift is no longer supported since Camel K 1.5.0. You can use xref:installation/platform/crc.adoc[CRC] for a local OpenShift cluster.
-
 [[fine-tuning]]
 == Fine Tuning
 

docs/modules/ROOT/pages/installation/uninstalling.adoc

@@ -1,7 +1,10 @@
 [[uninstalling]]
 = Uninstalling Camel K
 
-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:
+We're sad to see you go, but If you really need to, it is possible to completely uninstall Camel K from your cluster. The uninstalling procedure typically removes the operator but keeps Custom Resource Definition and any Integration which was previously running. They can be removed by the user by an additional cleaning operation.
+
+[[cli]]
+== Uninstall via Kamel CLI
 
 [source]
 ----
@@ -12,11 +15,66 @@ This will uninstall all Camel K resources along with the operator from the clust
 
 NOTE:  By _default_ the resources possibly shared between clusters such as https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources[CustomResourceDefinitions (CRD)], https://kubernetes.io/docs/reference/access-authn-authz/rbac[ClusterRole] and https://docs.openshift.com/container-platform/4.1/applications/operators/olm-understanding-olm.html[Operator Lifecycle Manager(OLM)] will be  **excluded**. To force the inclusion of all resources you can use the **--all** flag. If the **--olm=false** option was specified during installation, which is the case when installing Camel K from sources on CRC, then it also must be used with the uninstall command.
 
+[[helms]]
+== Uninstall via Helm
+
+The Helm procedure takes care to delete only the operator Deployment:
+
+```
+$ helm uninstall camel-k
+```
+
+Check instructions on https://hub.helm.sh/charts/camel-k/camel-k[Camel K Helm] page to remove CRDs and any other installation resource.
+
+[[operatorhub]]
+== Uninstall via Operator Hub
+
+In order to uninstall via OLM, you'll need to identify and remove the Subscription custom resource related to Camel K. Check instructions on https://olm.operatorframework.io/docs/tasks/uninstall-operator/[uninstall an operator] page from OLM.
+
+[[kustomize]]
+== Uninstall via Kustomize
+
+Uninstalling via Kustomize may require you to store the configuration you've used at install time and delete the applied resources. However this is something we discourage as it may remove also the application that are running and you may not want to delete (see generic cleaning for an alternative approach).
+
+WARNING: this operation may remove CRDs and any application that is still running.
+
+```
+$ kustomize build 'overlays/my-configuration' | kubectl delete -f -
+```
+
+[[generic]]
+== Uninstall cleaning cluster resources
+
+Another alternative is to delete the resources the operator is using in a controlled way by cleaning them one by one.
+
+== Uninstall operator only (keeps CRDs and any running Integration)
+
+In order to remove the operator and any configuration resource it uses you'll need to perform the following cleaning operation:
+
+```
+$ kubectl delete deploy,configmap,secret,sa,rolebindings,clusterrolebindings,roles,clusterroles,integrationplatform -l app=camel-k
+```
+
+NOTE: CRDs and Integration will be maintained alive and running.
+
+== Uninstall CRDs (and running Integration)
+
+In order to remove the CRDs you need to execute:
+
+```
+$ kubectl delete crd -l app=camel-k
+```
+
+NOTE: Integration will be garbage collected by the cluster and so any running application.
+
+[[verify]]
+== Verify your cluster
+
 To verify that all resources have been removed you can use the following command:
 
 [source]
 ----
-kubectl get all,pvc,configmap,rolebindings,clusterrolebindings,secrets,sa,roles,clusterroles,crd -l 'app=camel-k'
+kubectl get all,configmap,rolebindings,clusterrolebindings,secrets,sa,roles,clusterroles,crd -l 'app=camel-k'
 NAME                                   READY   STATUS        RESTARTS   AGE
 clusterrole.rbac.authorization.k8s.io/camel-k:edit   2020-05-28T20:31:39Z