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 4de4417b1 feat(doc): registry configuration
4de4417b1 is described below
commit 4de4417b1d61cab1898643d0fec5feb92e202875
Author: Pasquale Congiusti <[email protected]>
AuthorDate: Fri Aug 4 11:32:36 2023 +0200
feat(doc): registry configuration
---
.../ROOT/images/architecture/camel-k-registry.svg | 1 +
docs/modules/ROOT/nav.adoc | 18 +----
.../ROOT/pages/installation/advanced/maven.adoc | 2 +-
.../ROOT/pages/installation/installation.adoc | 19 +++---
.../ROOT/pages/installation/registry/own.adoc | 77 ++++++++++++++++++++++
.../ROOT/pages/installation/registry/registry.adoc | 47 +++++++++----
6 files changed, 123 insertions(+), 41 deletions(-)
diff --git a/docs/modules/ROOT/images/architecture/camel-k-registry.svg
b/docs/modules/ROOT/images/architecture/camel-k-registry.svg
new file mode 100644
index 000000000..e1096fab5
--- /dev/null
+++ b/docs/modules/ROOT/images/architecture/camel-k-registry.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg";
xmlns:xlink="http://www.w3.org/1999/xlink"; xmlns:lucid="lucid" width="1055.34"
height="696.83"><g transform="translate(514.8395061728396 -36.166666666666686)"
lucid:page-tab-id="0_0"><path d="M-340 126a6 6 0 0 1 6-6h848a6 6 0 0 1 6
6v408a6 6 0 0 1-6 6h-848a6 6 0 0 1-6-6z" stroke="#3a414a" fill="#fff"/><path
d="M-220.34 163.17c-1.14.1-2.05.34-2.96.8l-39.44 19.43c-2.16 1.02-3.64 2.84-4.1
5.23l-9.77 43.76c-.47 2.04-.13 4.08 1 5.9.13.23.24.34.47.57l27. [...]
\ No newline at end of file
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
index 1438204d3..5fb9a82ea 100644
--- 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
index 334e1b2e3..6ce49386a 100644
--- 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
index ebd4bfcb9..605dd6ff6 100644
--- 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
new file mode 100644
index 000000000..1f2c15698
--- /dev/null
+++ 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.
\ No newline at end of file
diff --git a/docs/modules/ROOT/pages/installation/registry/registry.adoc
b/docs/modules/ROOT/pages/installation/registry/registry.adoc
index 903b721ba..4c98f50cc 100644
--- 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.
