apache · squakez · Aug 7, 2023 · Aug 4, 2023
diff --git a/docs/modules/ROOT/images/architecture/camel-k-registry.svg b/docs/modules/ROOT/images/architecture/camel-k-registry.svg
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
@@ -1,28 +1,12 @@
 * xref:installation/installation.adoc[Installation]
-** Kubernetes Platform
-*** xref:installation/platform/minikube.adoc[Minikube]
-*** xref:installation/platform/docker-desktop.adoc[Docker Desktop]
-*** xref:installation/platform/crc.adoc[CRC]
-*** xref:installation/platform/digitalocean.adoc[DigitalOcean]
-*** xref:installation/platform/gke.adoc[GKE]
-*** xref:installation/platform/openshift.adoc[OpenShift]
-*** xref:installation/platform/iks.adoc[IKS]
-*** xref:installation/platform/k3s.adoc[K3s]
-*** xref:installation/platform/kind.adoc[Kind]
+** xref:installation/advanced/maven.adoc[Configuring Maven]
 ** xref:installation/registry/registry.adoc[Configuring Registry]
-*** xref:installation/registry/digitalocean.adoc[DigitalOcean]
-*** xref:installation/registry/dockerhub.adoc[Docker Hub]
-*** xref:installation/registry/github.adoc[Github Packages]
-*** xref:installation/registry/gcr.adoc[Gcr.io]
-*** xref:installation/registry/icr.adoc[IBM Container Registry]
-*** xref:installation/registry/k3s.adoc[K3s]
 ** xref:installation/advanced/advanced.adoc[Advanced]
 *** 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]
 *** xref:installation/advanced/http-proxy.adoc[HTTP Proxy]
-*** xref:installation/advanced/maven.adoc[Maven]
 *** xref:installation/advanced/multi-architecture.adoc[Multi Architecture]
 ** xref:contributing/upgrade.adoc[Upgrade]
 ** xref:contributing/uninstalling.adoc[Uninstalling]

diff --git a/docs/modules/ROOT/pages/installation/advanced/maven.adoc b/docs/modules/ROOT/pages/installation/advanced/maven.adoc
@@ -1,4 +1,4 @@
-= Configure Maven
+= Configuring Maven
 
 Camel K builds are performed by Maven. For this reason it may requires certain Maven best practices that will make your application to run faster, more secure and more resiliently. The Maven configuration is defined at IntegrationPlatform level. Have a look at the following sections to discover how to configure Maven in Camel K.
 

diff --git a/docs/modules/ROOT/pages/installation/installation.adoc b/docs/modules/ROOT/pages/installation/installation.adoc
@@ -6,10 +6,9 @@ Camel K allows us to run Camel integrations directly on a Kubernetes or OpenShif
 [[cli]]
 == Installation via Kamel CLI
 
-To start using Camel K you need the **"kamel"** CLI tool, that can be used to both configure the cluster and run integrations.
-Look into the https://github.com/apache/camel-k/releases[release page] for the latest version of the *camel-k-client* tool for your specific platform.
+To start using Camel K you need the **"kamel"** CLI tool, that can be used to both configure the cluster and run integrations. Look into the https://github.com/apache/camel-k/releases[release page] for the latest version of the *camel-k-client* tool for your specific platform.
 
-Download and uncompress the archive. It contains a small binary file named `kamel` that you should put into your system path. For example, if you're using Linux, you can put `kamel` in `/usr/bin`.
+Download and deflate the archive. It contains a small binary file named `kamel` that you should put into your system path. For example, if you're using Linux, you can put `kamel` in `/usr/bin`.
 
 Once you have put the `kamel` CLI in the path, log into your cluster using the standard `oc` (OpenShift) or `kubectl` (Kubernetes) client tool and execute the following command to install Camel K:
 
@@ -18,10 +17,11 @@ 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.
+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]]
@@ -82,14 +82,15 @@ Once you've completed any of the above installation procedure, you'll be ready t
 
 Camel K installation is usually straightforward, but for certain cluster types you need to apply specific configuration settings before installing it. You need customized instructions for the following cluster types:
 
-- xref:installation/platform/openshift.adoc[OpenShift]
-- xref:installation/platform/minikube.adoc[Minikube]
+- xref:installation/platform/digitalocean.adoc[DigitalOcean]
 - xref:installation/platform/docker-desktop.adoc[Docker Desktop]
-- xref:installation/platform/kind.adoc[Kind]
-- xref:installation/platform/crc.adoc[Red Hat CodeReady Containers (CRC)]
 - xref:installation/platform/gke.adoc[Google Kubernetes Engine (GKE)]
 - xref:installation/platform/iks.adoc[IBM Kubernetes Services (IKS)]
 - xref:installation/platform/k3s.adoc[K3s]
+- xref:installation/platform/kind.adoc[Kind]
+- xref:installation/platform/minikube.adoc[Minikube]
+- 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.
 

diff --git a/docs/modules/ROOT/pages/installation/registry/own.adoc b/docs/modules/ROOT/pages/installation/registry/own.adoc
@@ -0,0 +1,77 @@
+= Run your own container registry
+If you operate the container registry, the most important thing from Camel K and cluster perspective is that you need to make sure that both the operator and the cluster can reach the registry using the same address.
+
+WARNING: any cluster configuration must be performed by experienced users or platform administrators.
+
+Here we propose some possible options, each of them has its pros and cons.
+
+[[configuring-registry-run-infra]]
+== Run in the same infrastructure of the Cluster
+
+With this topology we may expect that the container registry is operated in the same infrastructure of the cluster and the cluster's components can reach it accordingly. As each registry and each cluster can have different configuration, we cannot give specific hints on how to deploy such configuration.
+
+[[configuring-registry-run-pod]]
+== Run as a Pod
+
+This is the approach used by Minikube. Basically it deploys a container registry as a Pod, and you can use the service cluster IP. We cannot use the service URL as it won't be available in the Kubernetes components which are in charge to run the Deployment (it does not use Service/Pod cluster DNS). However, it can use the Cluster IP which is available throughout all the cluster or any Ingress which would expose the service publicly.
+
+NOTE: if you make sure that the registry cluster IP does not change over time or you use a public address, the approach could be used for production use cases.
+
+The following example can be used as a base for your solution and should not be considered for production use cases as it does not configure any storage neither any security measure:
+
+```yaml
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: registry
+spec:
+  selector:
+    app: registry
+  ports:
+    - protocol: TCP
+      port: 80
+      targetPort: 5000
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: registry
+spec:
+  selector:
+    matchLabels:
+      app: registry
+  template:
+    metadata:
+      labels:
+        app: registry
+    spec:
+      containers:
+        - name: registry
+          image: registry:2
+          ports:
+            - containerPort: 5000
+              name: 5000-tcp
+          volumeMounts:
+            - name: registry-data
+              mountPath: /registry-data
+      volumes:
+        - name: registry-data
+          emptyDir: {}
+```
+If you apply this configuration, a registry Pod will be started and you can use it by checking the Service cluster IP:
+```
+NAME       TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)   AGE
+registry   ClusterIP   10.96.112.40   <none>        80/TCP    23h
+
+$ kamel install --registry 10.96.112.40
+```
+
+The above installation should be able to push and pull Integration images correctly.
+
+[[configuring-registry-run-docker]]
+== Run as a Docker image
+
+This is the approach used by https://kind.sigs.k8s.io/docs/user/local-registry/[Kind in order to make a registry available]. You can follow the guidelines and it may work in particular situations in any cluster beside Kind. However, as it involves hacks in the cluster configuration, make sure to understand the effects of the changes you're going to perform.
+
+WARNING: not recommended for production use cases unless you know what you're doing.
diff --git a/docs/modules/ROOT/pages/installation/registry/registry.adoc b/docs/modules/ROOT/pages/installation/registry/registry.adoc
@@ -1,26 +1,32 @@
-[[configuring-registry]]
 = Configuring Registry
 
-Every Camel K installation needs a container registry that will be used to host integration container images.
+Every Camel K installation needs a container registry that will be used to host integration container images. This is required to host the images that will be used by Kubernetes to execute the Camel application you've built.
 
-A **default registry** is present in all the following supported installations:
+image::architecture/camel-k-registry.svg[Container registry in action, width=800]
 
-* **OpenShift**: all OpenShift installations (including CRC and real clusters) provide an internal container registry that is used for the S2I (source to image)
-  feature. Camel K is able to leverage that registry.
-* **Minikube**: Minikube comes with a "registry addon" that can be enabled upon installation (see xref:installation/platform/minikube.adoc[install guide for Minikube]). Camel K automatically detects the address of the registry and configures
-  it on the `IntegrationPlatform` when using the CLI (on `kamel install`).
-* **Docker Desktop**: Docker provides an https://github.com/distribution/distribution[open source Docker Registry] that can be started upon installation (see xref:installation/platform/docker-desktop.adoc[install guide for Docker Desktop]).
+The Camel K operator is in charge to build a Camel application and to "containerize" it, storing the result into a container registry. The same registry is used by the cluster to run the Camel application. Basically the operator push the image and the cluster pull it from the same source.
 
-Other platforms do not provide a default container registry and need to be configured accordingly.
+For the reason above it's important that you provide a container registry which is accessible from both the operator Pod and the cluster internal mechanisms. However, a **default registry** is present in certain platforms such as _Minikube_, _Openshift_ or _Docker Desktop_.
+
+For any other platform that do not provide a default container registry, then, a registry must be provided accordingly.
+
+[[configuring-registry-install-time]]
+== Configure the registry at installation time
 
 Registry configuration can be set upon installation using command:
 
 [source,bash]
 ----
-$ kamel install --registry registry-host.io --organization your-user-id-or-org --registry-secret the-push-kubernetes-secret-name
+$ kamel install --registry registry-host.io [--organization your-user-id-or-org] [--registry-secret my-secret-registry-conf]
 ----
 
-Alternatively, the same settings can be set in the `.spec.pipeline.registry` section of the `IntegrationPlatform` resource.
+Although optionals, the `organization` and `registry-secret` parameters are strongly suggested in order to secure the pull/push operations on a registry that is private, although accessible through the Internet. The secret is something that will https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#create-a-pod-that-uses-your-secret[included at deployment time] as `imagePullSecret` configuration.
+
+As each registry may have a slightly different way of securing the access you can use the guidelines provided in xref:installation/registry/dockerhub.adoc[Docker Hub] registry configuration and adjust accordingly.
+
+[[configuring-registry-after-install]]
+== Configure the registry after installation
+The settings you've provided in the chapter above are applied to the `IntegrationPlatform` custom resource. In particular you can find them in the `.spec.pipeline.registry`.
 
 [source,yaml]
 ----
@@ -35,9 +41,22 @@ spec:
     registry:
       address: registry-host.io
       organization: your-user-id-or-org
-      secret: the-push-kubernetes-secret-name
+      secret: my-secret-registry-conf
 ----
 
-Additional information on setting up registries can be found in the registry specific sub-section.
+You can therefore update the values in the `IntegrationPlatform` in order to perform any change to the registry configuration after the Camel K operator is installed. The changes will be immediately reconciled and ready to use.
+
+[[configuring-registry-list]]
+== Special container registry requirements
+Each platform may have its default registry of choice. And each container registry may have a slight different configuration. We have some hints that can help you configuring on the most common platforms:
+
+- xref:installation/registry/digitalocean.adoc[DigitalOcean]
+- xref:installation/registry/dockerhub.adoc[Docker Hub]
+- xref:installation/registry/github.adoc[Github Packages]
+- xref:installation/registry/gcr.adoc[Gcr.io]
+- xref:installation/registry/icr.adoc[IBM Container Registry]
+- xref:installation/registry/k3s.adoc[K3s]
 
-NOTE: if your repository is not listed in any sub-section, you can try setting it up using the xref:installation/registry/dockerhub.adoc[instructions for Docker Hub].
+[[configuring-registry-run-it-yours]]
+== Run your own container registry
+You can also xref:installation/registry/own.adoc[run your own registry], but this option is recommended only for advanced use cases as it may requires certain changes in the cluster configuration, so, make sure to understand how each change may affect your cluster. As you've seen in the diagram above, the cluster has to be aware of the presence of the registry in order to pull the images pushed by the operator.