doc: Init troubleshooting guide

docs/modules/ROOT/nav-end.adoc

@@ -1,2 +1,3 @@
+* xref:troubleshooting.adoc[Troubleshooting]
 * xref:uninstalling.adoc[Uninstalling]
-* xref:developers.adoc[Contributing to Camel K]
+* xref:developers.adoc[Contributing]

docs/modules/ROOT/pages/developers.adoc

@@ -3,29 +3,29 @@
 
 We love contributions!
 
-The project is written in https://golang.org/[go] and contains some parts written in Java for the https://github.com/apache/camel-k-runtime/[integration runtime]
-Camel K is built on top of Kubernetes through *Custom Resource Definitions*. The https://github.com/operator-framework/operator-sdk[Operator SDK] is used
-to manage the lifecycle of those custom resources.
+The project is written in https://golang.org/[go] and contains some parts written in Java for the https://github.com/apache/camel-k-runtime/[integration runtime].
+Camel K is built on top of Kubernetes through *Custom Resource Definitions*.
+The https://github.com/operator-framework/operator-sdk[Operator SDK] is used to manage the lifecycle of those custom resources.
 
 [[requirements]]
 == Requirements
 
 In order to build the project, you need to comply with the following requirements:
 
 * **Go version 1.13+**: needed to compile and test the project. Refer to the https://golang.org/[Go website] for the installation.
-* **Operator SDK v0.9.0+**: used to build the operator and the Docker images. Instructions in the https://github.com/operator-framework/operator-sdk[Operator SDK website] (binary downloads available in the release page).
+* **Operator SDK v0.17.1+**: used to build the operator, and the Docker images. Instructions in the https://github.com/operator-framework/operator-sdk[Operator SDK website] (binary downloads available in the release page).
 * **GNU Make**: used to define composite build actions. This should be already installed or available as package if you have a good OS (https://www.gnu.org/software/make/).
 
 The Camel K Java runtime (camel-k-runtime) requires:
 
-* **Java 11**: needed for compilation.
+* **Java 11**: needed for compilation
 * **Maven**: needed for building
 
 [[checks]]
 == Running checks
 Checks rely on `golangci-lint` being installed, to install it look at the https://github.com/golangci/golangci-lint#local-installation[Local Installation] instructions.
 
-You can run checks via `make lint` or you can install a GIT pre-commit hook and have the checks run via https://pre-commit.com[pre-commit]; then make sure to install the pre-commit hooks after installing pre-commit by running
+You can run checks via `make lint`, or you can install a GIT pre-commit hook and have the checks run via https://pre-commit.com[pre-commit]; then make sure to install the pre-commit hooks after installing pre-commit by running:
 
  $ pre-commit install
 
@@ -63,7 +63,7 @@ To build the whole project you now need to run:
 make
 ----
 
-This execute a full build of both the Java and Go code. If you need to build the components separately you can execute:
+This executes a full build of the Go code. If you need to build the components separately you can execute:
 
 * `make build-operator`: to build the operator binary only.
 * `make build-kamel`: to build the `kamel` client tool only.
@@ -144,11 +144,10 @@ If you want to install everything you have in your source code and see it runnin
 === For Red Hat CodeReady Containers (CRC)
 
 * You need to have https://docs.docker.com/get-docker/[Docker] installed and running (or connected to a Docker daemon)
-* You need to setup Docker daemon to https://docs.docker.com/registry/insecure/[trust] CRC's insecure Docker registry which is exposed by default through the route `default-route-openshift-image-registry.apps-crc.testing`. One way of doing that is to instruct the Docker daemon to trust the certificate:
+* You need to set up Docker daemon to https://docs.docker.com/registry/insecure/[trust] CRC's insecure Docker registry which is exposed by default through the route `default-route-openshift-image-registry.apps-crc.testing`. One way of doing that is to instruct the Docker daemon to trust the certificate:
 ** `oc extract secret/router-ca --keys=tls.crt -n openshift-ingress-operator`: to extract the certificate
 ** `sudo cp tls.crt /etc/docker/certs.d/default-route-openshift-image-registry.apps-crc.testing/ca.crt`: to copy the certificate for Docker daemon to trust
 ** `docker login -u kubeadmin -p $(oc whoami -t) default-route-openshift-image-registry.apps-crc.testing`: to test that the certificate is trusted
-
 * Run `make install-crc`: to build the project and install it in the current namespace on CRC
 * You can specify a different namespace with `make install-crc project=myawesomeproject`
 * To uninstall Camel K, run `kamel uninstall --all --olm=false`
@@ -205,9 +204,9 @@ You are going to run the operator code **outside** OpenShift in your IDE so, fir
 oc scale deployment/camel-k-operator --replicas 0
 ----
 
-You can scale it back to 1 when you're done and you have updated the operator image.
+You can scale it back to 1 when you're done, and you have updated the operator image.
 
-You can setup the IDE (e.g. Goland) to execute the https://github.com/apache/camel-k/blob/master/cmd/manager/main.go[/cmd/manager/main.go] file in debug mode with `operator` as argument.
+You can set up the IDE (e.g. Goland) to execute the https://github.com/apache/camel-k/blob/master/cmd/manager/main.go[/cmd/manager/main.go] file in debug mode with `operator` as argument.
 
 When configuring the IDE task, make sure to add all required environment variables in the *IDE task configuration screen*:
 
@@ -216,8 +215,7 @@ When configuring the IDE task, make sure to add all required environment variabl
 * Set the `OPERATOR_NAME` environment variable to `camel-k`.
 
 
-After you setup the IDE task, with Java 11+ to be used by default, you can run and debug the operator process.
+After you set up the IDE task, with Java 11+ to be used by default, you can run and debug the operator process.
 
 NOTE: The operator can be fully debugged in Minishift, because it uses OpenShift S2I binary builds under the hood.
-The build phase cannot be (currently) debugged in Minikube because the Kaniko builder requires that the operator and the publisher pod
-share a common persistent volume.
+The build phase cannot be (currently) debugged in Minikube because the Kaniko builder requires that the operator, and the publisher pod share a common persistent volume.

docs/modules/ROOT/pages/observability/monitoring.adoc

@@ -15,15 +15,17 @@ To take fully advantage of the Camel K monitoring capabilities, it is recommende
 
 You can deploy the Prometheus operator by running:
 
-```sh
+[source,sh]
+----
 $ kubectl apply -f https://raw.githubusercontent.com/coreos/prometheus-operator/v0.38.0/bundle.yaml
-```
+----
 
 WARNING: Beware this installs the operator in the `default` namespace. You must download the file locally and replace the `namespace` fields to deploy the resources into another namespace.
 
 Then, you can create a `Prometheus` resource, that the operator will use as configuration to deploy a managed Prometheus instance:
 
-```sh
+[source,sh]
+----
 $ cat <<EOF | kubectl apply -f -
 apiVersion: monitoring.coreos.com/v1
 kind: Prometheus
@@ -35,7 +37,7 @@ spec:
       - key: camel.apache.org/integration
         operator: Exists
 EOF
-```
+----
 
 By default, the Prometheus instance discovers applications to be monitored in the same namespace.
 You can use the `serviceMonitorNamespaceSelector` field from the `Prometheus` resource to enable cross-namespace monitoring.
@@ -83,15 +85,17 @@ The xref:traits:prometheus.adoc[Prometheus trait] automates the configuration of
 
 The Prometheus trait can be enabled when running an integration, e.g.:
 
-```sh
+[source,sh]
+----
 $ kamel run -t prometheus.enabled=true ...
-```
+----
 
 Alternatively, the Prometheus trait can be enabled globally once, by updating the integration platform, e.g.:
 
-```sh
+[source,sh]
+----
 $ kubectl patch ip camel-k --type=merge -p '{"spec":{"traits":{"prometheus":{"configuration":{"enabled":"true"}}}}}'
-```
+----
 
 The underlying instrumentation mechanism depends on the configured integration runtime.
 As a result, the set of registered metrics, as well as the naming convention they follow, also depends on it.
@@ -102,9 +106,10 @@ When the default, a.k.a. _main_, runtime is configured for the integration, the
 
 A custom configuration for the JMX exporter can be used by setting the `prometheus.configmap` parameter from the Prometheus trait with the name of a ConfigMap containing a `prometheus-jmx-exporter.yaml` key, e.g.:
 
-```sh
+[source,sh]
+----
 $ kamel run -t prometheus.enabled=true -t prometheus.configmap=<jmx_exporter_config>...
-```
+----
 
 Otherwise, the Prometheus trait uses a default configuration.
 
@@ -131,15 +136,17 @@ The Prometheus trait automatically configures the resources necessary for the Pr
 By default, the Prometheus trait creates a `ServiceMonitor` resource, with the `camel.apache.org/integration` label, which must match the `serviceMonitorSelector` field from the `Prometheus` resource.
 Additional labels can be specified with the `service-monitor-labels` parameter from the Prometheus trait, e.g.:
 
-```sh
+[source,sh]
+----
 $ kamel run -t prometheus.service-monitor-labels="label_to_be_match_by=prometheus_selector" ...
-```
+----
 
 The creation of the `ServiceMonitor` resource can be disabled using the `service-monitor` parameter, e.g.:
 
-```sh
+[source,sh]
+----
 $ kamel run -t prometheus.service-monitor=false ...
-```
+----
 
 More information can be found in the xref:traits:prometheus.adoc[Prometheus trait] documentation.
 
@@ -153,7 +160,8 @@ The Prometheus Operator declares the `AlertManager` resource that can be used to
 
 Assuming an `AlertManager` resource already exists in your cluster, you can register a `PrometheusRule` resource that is used by Prometheus to trigger alerts, e.g.:
 
-```sh
+[source,sh]
+----
 $ cat <<EOF | kubectl apply -f -
 apiVersion: monitoring.coreos.com/v1
 kind: PrometheusRule
@@ -169,7 +177,7 @@ spec:
     - alert: CamelKAlert
       expr: application_camel_context_exchanges_failed_total > 0
 EOF
-```
+----
 
 More information can be found in the Prometheus Operator https://github.com/coreos/prometheus-operator/blob/v0.38.0/Documentation/user-guides/alerting.md[Alerting] user guide. You can also find more details in https://docs.openshift.com/container-platform/4.4/monitoring/monitoring-your-own-services.html#creating-alerting-rules_monitoring-your-own-services[Creating alerting rules] from the OpenShift documentation.
 
@@ -180,7 +188,8 @@ If you have an OpenShift cluster, you can follow https://docs.openshift.com/cont
 
 Assuming you have the Prometheus adapter up and running, you can create a `HorizontalPodAutoscaler` resource, e.g.:
 
-```sh
+[source,sh]
+----
 $ cat <<EOF | kubectl apply -f -
 apiVersion: autoscaling/v2beta2
 kind: HorizontalPodAutoscaler
@@ -202,6 +211,6 @@ spec:
         type: AverageValue
         averageValue: 1k
 EOF
-```
+----
 
 More information can be found in https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/[Horizontal Pod Autoscaler] from the Kubernetes documentation.

docs/modules/ROOT/pages/troubleshooting.adoc

@@ -0,0 +1,32 @@
+[[troubleshooting]]
+= Troubleshooting
+
+== `Error during unshare(CLONE_NEWUSER): Invalid argument`
+
+Buildah is best used with the OCI container runtime.
+When used with the Docker container runtime, it may not have the permissions to perform some required system calls.
+
+From https://github.com/containers/buildah/issues/1901[containers/buildah#1901], it seems a system call, that's forbidden by default with the Docker container runtime, is still necessary when the user doesn't have the `CAP_SYS_ADMIN` capability.
+
+The only option is to change the Docker container runtime to use a different _seccomp_ profile, e.g.:
+
+[source,sh]
+----
+$ docker run --security-opt seccomp=/usr/share/containers/seccomp.json
+----
+
+However, that requires being able to configure your cluster container runtime.
+
+A work-around is to use another builder strategy, like Kaniko or Spectrum, e.g. when installing Camel K:
+
+[source,sh]
+----
+$ kamel install --build-publish-strategy=kaniko
+----
+
+Or by patching your `IntegrationPlatform` resource directly if you have Camel K already installed, e.g.:
+
+[source,sh]
+----
+$ kubectl patch ip camel-k --type='merge' -p '{"spec":{"build":{"publishStrategy":"kaniko"}}}'
+----