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 8db5e0035 chore(doc): bring back support for local operator execution
8db5e0035 is described below
commit 8db5e00356a31eed81f316bf4c045e5e5490990d
Author: Pasquale Congiusti <pasquale.congiu...@gmail.com>
AuthorDate: Thu Oct 5 17:53:24 2023 +0200
chore(doc): bring back support for local operator execution
This was removed as we temporary introduced the dynamic builder. Now that
is gone, the local execution can be still a way to debug the operator.
Ref #4513
---
docs/modules/ROOT/nav-end.adoc | 3 +-
.../ROOT/pages/contributing/local-development.adoc | 4 +-
.../ROOT/pages/contributing/local-execution.adoc | 85 ++++++++++++++++++++++
3 files changed, 90 insertions(+), 2 deletions(-)
diff --git a/docs/modules/ROOT/nav-end.adoc b/docs/modules/ROOT/nav-end.adoc
index 2df74b5cb..69cf0c052 100644
--- a/docs/modules/ROOT/nav-end.adoc
+++ b/docs/modules/ROOT/nav-end.adoc
@@ -90,6 +90,7 @@
** xref:apis/java.adoc[Java API]
* xref:contributing/developers.adoc[Contributing]
** xref:contributing/local-development.adoc[Local development]
-*** xref:contributing/remote-debugging.adoc[Operator Remote Debug]
+*** xref:contributing/local-execution.adoc[Operator - local execution]
+*** xref:contributing/remote-debugging.adoc[Operator - remote debug]
** xref:contributing/local-deployment-olm.adoc[Local OLM deployment]
** xref:contributing/e2e.adoc[Local E2E testing]
diff --git a/docs/modules/ROOT/pages/contributing/local-development.adoc
b/docs/modules/ROOT/pages/contributing/local-development.adoc
index a5729205b..0ccece2b7 100644
--- a/docs/modules/ROOT/pages/contributing/local-development.adoc
+++ b/docs/modules/ROOT/pages/contributing/local-development.adoc
@@ -3,10 +3,12 @@
If you plan on contributing to Camel K, you will end up needing to run and
troubleshoot your operator code locally. Here is a guideline that will help you
configure your local operator running.
+NOTE: you can also run and debug the operator as a local process: see
xref:contributing/local-execution.adoc[Operator - local execution]
+
[[local-operator]]
== Running a development operator
-As soon as you build your operator locally you will ask yourself how to test
it. In the past, we used to have the possibility to run the operator on the
same development machine and connect to Kubernetes cluster. However, that
approach was quite cumbersome, so now we propose a way to locally install and
run your development Camel K operator as it was a "normal" installation.
+As soon as you build your operator locally you will ask yourself how to test
it. In this space we propose a way to locally install and run your development
Camel K operator as it was a "normal" installation.
Once you have done your development, you will need to build and push Camel K
Operator container image to the container registry your Kubernetes is later
going to use. If you're on a local machine, you are probably using Minikube or
Kind. In such case you can make your Docker daemon to use the cluster container
registry. In Minikube it would be like the following:
diff --git a/docs/modules/ROOT/pages/contributing/local-execution.adoc
b/docs/modules/ROOT/pages/contributing/local-execution.adoc
new file mode 100644
index 000000000..8e478f023
--- /dev/null
+++ b/docs/modules/ROOT/pages/contributing/local-execution.adoc
@@ -0,0 +1,85 @@
+= Running operator as a local process
+
+If you need a finer control on the operator process (ie, attaching a debugger
or quickly building and running the operator locally), then you can run and
debug the operator binary locally. The idea is that you execute it on your
machine and instruct the local process to **watch** a namespace on a Kubernetes
cluster (it may be remote or any local environment).
+
+NOTE: if you need a simpler approach you can build and run the operator on a
connected cluster (local or remote): see
xref:contributing/local-development.adoc[Local development]
+
+Let's use a namespace called `operator-test.
+
+You can start with setting the environment variable `WATCH_NAMESPACE` with the
namespace you'd like your operator to watch. You also need to specify the name
of the operator, as you may have different operators running on the cluster.
+----
+export WATCH_NAMESPACE=operator-test
+export OPERATOR_ID="camel-k-dev"
+----
+
+The next step is to install an `IntegrationPlatform` on the cluster namespace.
You probably need to tweak the registry parameters in order to be able to
authenticate against an image repository (see below paragraph for local
repository instructions). It's important to specify the target operator that
will take care of this IntegrationPlatform (`-x` or `--operator-id` option).
+----
+./kamel install --skip-operator-setup -n operator-test --registry
my-registry:5000 -x camel-k-dev
+----
+
+Finally, assuming you've built your application correctly we can run the
operator:
+-----
+./kamel operator
+-----
+
+Test the local operator by creating a test `Integration`.
+-----
+./kamel run xyz.abc -n operator-test -x camel-k-dev
+-----
+
+IMPORTANT: make sure no other Camel K Operators are watching this namespace,
neither you have a global Camel K Operator installed on your cluster. As you
may have more than one Camel K operator installed on the cluster, it's
important you specify the `-x` (or `--operator-id`) option.
+
+[[local-minikube]]
+== Local operator and local cluster
+
+If you want to run a local operator togheter with ``Minikube`` you will need
an additional step in order to let the local operator push images in the local
registry. We need to expose the local registry as described in
https://minikube.sigs.k8s.io/docs/handbook/registry/#docker-on-windows[this
procedure]:
+
+Enable the addon registry (this should be already in place):
+----
+minikube addons enable registry
+----
+
+Get the `Pod` name that is in charge to run the registry and proxy the
registry 5000 port to be used locally.
+----
+kubectl get pods -n kube-system
+NAME READY STATUS RESTARTS AGE
+...
+registry-fttbv 1/1 Running 40 89d
+...
+
+kubectl port-forward --namespace kube-system registry-fttbv 5000:5000
+----
+
+Update the ``IntegrationPlatform`` to instruct it to use the ``localhost``
registry:
+----
+./kamel install --skip-operator-setup -n operator-test --registry
localhost:5000 --force -x camel-k-dev
+----
+
+A similar procedure may work if you use other local environments. The idea is
to expose the docker registry and be able to use it from your local operator.
+
+IMPORTANT: using build strategy as `Pod` won't probably work as it will expect
the registry to be available at a URL not possible to reach from a local
machine.
+
+=== Local Camel K runtime
+
+Camel K integrations are based on
https://github.com/apache/camel-k-runtime[Camel K runtime], generally paired
with the operator release. If you need to specify a different runtime, or you
have a local Camel K runtime that you want to test, then you will need to
specify it in the `Integration Platform`:
+----
+./kamel install --skip-operator-setup -n operator-test --registry
localhost:5000 --force --runtime-version $version -x camel-k-dev
+----
+
+The `$version` variable must be replaced with the version you are building.
For example, `1.3.1-SNAPSHOT`. With these instructions, the operator will pick
up and use the snapshot version you have released locally. In order to use the
local maven repository, you will also need to edit your IntegrationPlatform as
follow:
+----
+$ k edit ip -n operator-test
+
+...
+ spec:
+ build:
+ maven:
+ cliOptions:
+ - -V
+ localRepository: /home/user/.m2/repository
+ settings: {}
+...
+----
+pointing the `localRepository` where your local maven is storing the artifacts
(it will look for the camel-k-runtime dependencies there).
+
+Alternatively, if no local registry is available, you can use another type of
registry as explained in xref:installation/registry/registry.adoc[the Registry
section].
\ No newline at end of file
