| :toc: macro |
| :toclevels: 3 |
| |
| = Apache Camel K |
| |
| image:https://github.com/apache/camel-k/workflows/build/badge.svg["Build", link="https://github.com/apache/camel-k/actions"] |
| image:https://goreportcard.com/badge/github.com/apache/camel-k["Go Report Card", link="https://goreportcard.com/report/github.com/apache/camel-k"] |
| image:https://godoc.org/github.com/apache/camel-k?status.svg["GoDoc", link="https://godoc.org/github.com/apache/camel-k"] |
| image:https://img.shields.io/github/license/openshift/origin.svg?maxAge=2592000["Licensed under Apache License version 2.0", link="https://www.apache.org/licenses/LICENSE-2.0"] |
| image:https://img.shields.io/badge/zulip-join_chat-brightgreen.svg["Chat on Zulip", link="https://camel.zulipchat.com"] |
| |
| image:https://github.com/apache/camel-k/workflows/kubernetes/badge.svg["Kubernetes", link="https://github.com/apache/camel-k/actions"] |
| image:https://github.com/apache/camel-k/workflows/knative/badge.svg["Knative", link="https://github.com/apache/camel-k/actions"] |
| image:https://img.shields.io/travis/apache/camel-k/master.svg?label=openshift["OpenShift", link="https://travis-ci.org/apache/camel-k"] |
| |
| Apache Camel K is a lightweight integration platform, born on Kubernetes, with serverless superpowers. |
| |
| toc::[] |
| |
| [[getting-started]] |
| == Getting Started |
| |
| Camel K allows to run 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. |
| |
| If you need help on how to create a local development environment based on *Minishift* or *Minikube*, you can follow the https://camel.apache.org/camel-k/latest/installation/installation.html[local cluster setup guide]. |
| |
| [[installation]] |
| === Installation |
| |
| Make sure you apply specific configuration settings for your cluster before installing Camel K. Customized instructions are needed for |
| the following cluster types: |
| |
| - https://camel.apache.org/camel-k/latest/installation/minikube.html[Minikube] |
| - https://camel.apache.org/camel-k/latest/installation/minishift.html[Minishift] |
| - https://camel.apache.org/camel-k/latest/installation/gke.html[Google Kubernetes Engine (GKE)] |
| - https://camel.apache.org/camel-k/latest/installation/openshift.html[OpenShift] |
| - https://camel.apache.org/camel-k/latest/installation/iks.html[IBM Kubernetes Service (IKS)] |
| |
| Other cluster types (such as OpenShift clusters) should not need prior configuration. |
| |
| To start using Camel K you need the **"kamel"** binary, 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 latest version of the `kamel` tool. |
| |
| If you want to contribute, you can also **build it from source!** Refer to the https://camel.apache.org/camel-k/latest/developers.html[contributing guide] |
| for information on how to do it. |
| |
| Once you have the "kamel" binary, log into your cluster using the standard "oc" (OpenShift) or "kubectl" (Kubernetes) client tool and execute the following command to install Camel K: |
| |
| ``` |
| kamel install |
| ``` |
| |
| This will configure the cluster with the Camel K custom resource definitions and install the operator on the current namespace. |
| |
| 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 Minishift, this means executing `oc login -u system:admin` then `kamel install --cluster-setup` only for first-time installation. |
| |
| === Running an Integration |
| |
| After the initial setup, you can run a Camel integration on the cluster by executing: |
| |
| ``` |
| kamel run examples/Sample.java |
| ``` |
| |
| During your first run you may see your console stuck with the following message: |
| |
| ``` |
| integration "sample" created |
| integration "sample" in phase Waiting For Platform |
| ``` |
| |
| NOTE: It will take some time for your integration to get started for the first time. This is because the camel-k operator has to pull and cache the camel-k builder images into the cluster's registry. |
| |
| You can follow this process by watching the pods in the namespace where the operator is running: |
| |
| ``` |
| kubectl get pods -w |
| ``` |
| |
| You should see something like: |
| |
| ``` |
| $ kubectl get pods -w |
| NAME READY STATUS RESTARTS AGE |
| camel-k-cache 0/1 Completed 0 3m29s |
| camel-k-groovy-builder 1/1 Running 0 32s |
| camel-k-jvm 0/1 Completed 0 61s |
| camel-k-jvm-builder 0/1 Completed 0 2m13s |
| camel-k-operator-587b579567-fkz54 1/1 Running 1 43m |
| camel-k-groovy 0/1 Pending 0 0s |
| camel-k-groovy 0/1 ContainerCreating 0 0s |
| camel-k-groovy 1/1 Running 0 2s |
| camel-k-groovy 0/1 Completed 0 4s |
| camel-k-kotlin-builder 0/1 Pending 0 0s |
| camel-k-kotlin-builder 0/1 Pending 0 0s |
| camel-k-kotlin-builder 0/1 ContainerCreating 0 0s |
| camel-k-groovy-builder 0/1 Completed 0 75s |
| ... |
| ``` |
| |
| After a couple of minutes you can see your integration runnning. To see the output log of your integration container get the pod id: |
| |
| ``` |
| kubectl get pods | grep sample |
| sample-67699569c4-724dv 1/1 Running 0 15m |
| ``` |
| |
| And then see the logs using: |
| |
| ``` |
| kubectl logs -f sample-67699569c4-724dv |
| ``` |
| |
| An output like this should appear: |
| |
| ``` |
| Starting the Java application using /opt/run-java/run-java.sh ... |
| ... |
| 2019-05-08 19:35:21.883 INFO [main] DefaultCamelContext - Apache Camel 2.23.2 (CamelContext: camel-k) started in 0.874 seconds |
| 2019-05-08 19:35:22.889 INFO [Camel (camel-k) thread #2 - timer://tick] route1 - Hello Camel K! |
| 2019-05-08 19:36:22.881 INFO [Camel (camel-k) thread #2 - timer://tick] route1 - Hello Camel K! |
| ... |
| ``` |
| |
| A "Sample.java" file is included in the link:/examples[/examples] folder of this repository. You can change the content of the file and execute the command again to see the changes. |
| |
| ==== Configure Integration properties |
| |
| Properties associated to an integration can be configured either using a ConfigMap/Secret or by setting using the "--property" flag, i.e. |
| |
| ``` |
| kamel run --property my.message=test examples/props.js |
| ``` |
| ``` |
| kamel run --configmap=<your name here> examples/props.js |
| ``` |
| Note: to create the config map first create a file called application.properties which contains lines with key=value pairs |
| e.g. my.message="The text to display" |
| Create the config map in the usual manner e.g. |
| ``` |
| kubectl create configmap <your name here> --from-file=application.properties |
| ``` |
| |
| ==== Configure Integration Logging |
| |
| camel-k runtime uses log4j2 as logging framework and can be configured through integration properties. |
| If you need to change the logging level of various loggers, you can do so by using the `logging.level` prefix: |
| |
| ``` |
| logging.level.org.apache.camel = DEBUG |
| ``` |
| |
| ==== Configure Integration Components |
| |
| camel-k component can be configured programmatically inside an integration or using properties with the following syntax. |
| |
| ``` |
| camel.component.${scheme}.${property} = ${value} |
| ``` |
| |
| As example if you want to change the queue size of the seda component, you can use the following property: |
| |
| ``` |
| camel.component.seda.queueSize = 10 |
| ``` |
| |
| ==== Configure Maven settings |
| |
| Maven settings can be configured by providing a custom settings.xml through a ConfigMap or secret. |
| The source for maven settings can be configured using either the `kamel` CLI at installation time or by editing Camel K's IntegrationPlatform: |
| |
| - cli: |
| + |
| .Syntax |
| [source] |
| ---- |
| kamel install --maven-settings=configmap|secret:name[/key] |
| ---- |
| + |
| .Example |
| [source] |
| ---- |
| kamel cmd --maven-settings=configmap:maven-settings/settings.xml |
| ---- |
| |
| - IntegrationPlatform: |
| + |
| [source,yaml] |
| ---- |
| apiVersion: camel.apache.org/v1 |
| kind: IntegrationPlatform |
| metadata: |
| labels: |
| app: camel-k |
| name: camel-k |
| spec: |
| build: |
| maven: |
| settings: |
| configMapKeyRef: |
| key: settings.xml |
| name: maven-settings |
| ---- |
| |
| To quickly create a config map you can use the following command: |
| |
| [source] |
| ---- |
| kubectl create configmap maven-settings --from-file=settings.xml |
| ---- |
| |
| |
| As an installation shortcut, additional maven repositories can be alternatively added using the `--maven-repository` option |
| |
| |
| [source] |
| ---- |
| kamel cmd --maven-repository http://repo1.my-company.com --maven-repository http://repo2.my-company.com |
| ---- |
| |
| A repository url follow conventions used to configure additional repositories in https://karaf.apache.org[_Apache Karaf_] so it can be appended with zero or more of the following flags: |
| |
| * **@snapshots**: the repository contains snapshots |
| * **@noreleases**: the repository does not contain any released artifacts |
| * **@id=repository.id**: the id for the repository |
| |
| [source] |
| ---- |
| kamel install --maven-repository http://repository.apache.org/content/groups/snapshots-group@id=apache@snapshots@noreleases |
| ---- |
| |
| This results in: |
| |
| [source,xml] |
| ---- |
| <repositories> |
| <repository> |
| <id>apache</id> |
| <url>http://repository.apache.org/content/groups/snapshots-group</url> |
| <snapshots> |
| <enabled>true</enabled> |
| </snapshots> |
| <releases> |
| <enabled>false</enabled> |
| </releases> |
| </repository> |
| </repositories> |
| ---- |
| |
| IMPORTANT |
| ==== |
| the options `--maven-settings` and `--maven-repository` are mutually exclusive |
| ==== |
| |
| ==== Configure Integration Volumes |
| |
| It's possible to mount persistent volumes into integration containers by using the `-v` or `--volume` flag. The format of volume flag value is similar to that of the docker CLI. But instead of specifying a host path to mount from, you reference the name of a `PersistentVolumeClaim` that you have already configured within the cluster. E.g |
| |
| ``` |
| kamel run examples/Sample.java -v myPvcName:/some/path |
| ``` |
| |
| ==== Configure Environment Variables |
| |
| It's possible to configure environment variables for integration containers by using the `-e` or `--env` flag: |
| |
| ``` |
| kamel run examples/Sample.java -e MY_ENV_VAR=some-value |
| ``` |
| |
| === Running Integrations in "Dev" Mode for Fast Feedback |
| |
| If you want to iterate quickly on an integration to have fast feedback on the code you're writing, you can use by running it in **"dev" mode**: |
| |
| ``` |
| kamel run examples/Sample.java --dev |
| ``` |
| |
| The `--dev` flag deploys immediately the integration and shows the integration logs in the console. You can then change the code and see |
| the **changes automatically applied (instantly)** to the remote integration pod. |
| |
| The console follows automatically all redeploys of the integration. |
| |
| Here's an example of the output: |
| |
| ``` |
| [nferraro@localhost camel-k]$ kamel run examples/Sample.java --dev |
| integration "sample" created |
| integration "sample" in phase Building |
| integration "sample" in phase Deploying |
| integration "sample" in phase Running |
| [1] Monitoring pod sample-776db787c4-zjhfr[1] Starting the Java application using /opt/run-java/run-java.sh ... |
| [1] exec java -javaagent:/opt/prometheus/jmx_prometheus_javaagent.jar=9779:/opt/prometheus/prometheus-config.yml -XX:+UseParallelGC -XX:GCTimeRatio=4 -XX:AdaptiveSizePolicyWeight=90 -XX:MinHeapFreeRatio=20 -XX:MaxHeapFreeRatio=40 -XX:+ExitOnOutOfMemoryError -cp .:/deployments/* org.apache.camel.k.jvm.Application |
| [1] [INFO ] 2018-09-20 21:24:35.953 [main] Application - Routes: file:/etc/camel/conf/Sample.java |
| [1] [INFO ] 2018-09-20 21:24:35.955 [main] Application - Language: java |
| [1] [INFO ] 2018-09-20 21:24:35.956 [main] Application - Locations: file:/etc/camel/conf/application.properties |
| [1] [INFO ] 2018-09-20 21:24:36.506 [main] DefaultCamelContext - Apache Camel 2.22.1 (CamelContext: camel-1) is starting |
| [1] [INFO ] 2018-09-20 21:24:36.578 [main] ManagedManagementStrategy - JMX is enabled |
| [1] [INFO ] 2018-09-20 21:24:36.680 [main] DefaultTypeConverter - Type converters loaded (core: 195, classpath: 0) |
| [1] [INFO ] 2018-09-20 21:24:36.777 [main] DefaultCamelContext - StreamCaching is not in use. If using streams then its recommended to enable stream caching. See more details at http://camel.apache.org/stream-caching.html |
| [1] [INFO ] 2018-09-20 21:24:36.817 [main] DefaultCamelContext - Route: route1 started and consuming from: timer://tick |
| [1] [INFO ] 2018-09-20 21:24:36.818 [main] DefaultCamelContext - Total 1 routes, of which 1 are started |
| [1] [INFO ] 2018-09-20 21:24:36.820 [main] DefaultCamelContext - Apache Camel 2.22.1 (CamelContext: camel-1) started in 0.314 seconds |
| |
| ``` |
| |
| === Dependencies and Component Resolution |
| |
| Camel components used in an integration are automatically resolved. For example, take the following integration: |
| |
| ``` |
| from("imap://admin@myserver.com") |
| .to("seda:output") |
| ``` |
| |
| Since the integration is using the **"imap:" prefix**, Camel K is able to **automatically add the "camel-mail" component** to the list of required dependencies. |
| This will be transparent to the user, that will just see the integration running. |
| |
| Automatic resolution is also a nice feature in `--dev` mode, because you are allowed to add all components you need without exiting the dev loop. |
| |
| You can also use the `-d` flag to pass additional explicit dependencies to the Camel client tool: |
| |
| ``` |
| kamel run -d mvn:com.google.guava:guava:26.0-jre -d camel-mina2 Integration.java |
| ``` |
| |
| === Not Just Java |
| |
| Camel K supports multiple languages for writing integrations: |
| |
| .Languages |
| [options="header"] |
| |======================= |
| | Language | Description |
| | Java | Integrations written in Java DSL are supported. |
| | XML | Integrations written in plain XML DSL are supported (Spring XML with <beans> or Blueprint XML with <blueprint> not supported). |
| | YAML | Integrations written in YAML DSL are supported. |
| | Groovy | Groovy `.groovy` files are supported (experimental). |
| | JavaScript | JavaScript `.js` files are supported (experimental). |
| | Kotlin | Kotlin Script `.kts` files are supported (experimental). |
| |======================= |
| |
| More information about supported languages is provided in the https://camel.apache.org/camel-k/latest/languages/languages.html[languages guide]. |
| |
| Integrations written in different languages are provided in the link:/examples[examples] directory. |
| |
| An example of integration written in JavaScript is the link:/examples/dns.js[/examples/dns.js] integration. |
| Here's the content: |
| |
| ``` |
| // Lookup every second the 'www.google.com' domain name and log the output |
| from('timer:dns?period=1000') |
| .routeId('dns') |
| .setHeader('dns.domain') |
| .constant('www.google.com') |
| .to('dns:ip') |
| .to('log:dns'); |
| ``` |
| |
| To run it, you need just to execute: |
| |
| ``` |
| kamel run examples/dns.js |
| ``` |
| |
| === Traits |
| |
| The details of how the integration is mapped into Kubernetes resources can be *customized using traits*. |
| More information is provided in the https://camel.apache.org/camel-k/latest/traits/traits.html[traits section]. |
| |
| === Monitoring the Status |
| |
| Camel K integrations follow a lifecycle composed of several steps before getting into the `Running` state. |
| You can check the status of all integrations by executing the following command: |
| |
| ``` |
| kamel get |
| ``` |
| |
| [[contributing]] |
| == Contributing |
| |
| We love contributions and we want to make Camel K great! |
| |
| Contributing is easy, just take a look at our https://camel.apache.org/camel-k/latest/developers.html[developer's guide]. |
| |
| [[uninstalling]] |
| == Uninstalling |
| |
| If you really need to, it is possible to completely uninstall Camel K from OpenShift or Kubernetes with the following command, using the "oc" or "kubectl" tool: |
| |
| ``` |
| # kubectl on plain Kubernetes |
| oc delete all,pvc,configmap,rolebindings,clusterrolebindings,secrets,sa,roles,clusterroles,crd -l 'app=camel-k' |
| ``` |
| |
| [[licensing]] |
| == Licensing |
| |
| This software is licensed under the terms you may find in the file named LICENSE in this directory. |