| Apache Camel K |
| ============== |
| |
| image:https://travis-ci.org/apache/camel-k.svg?branch=master["Build Status", link="https://travis-ci.org/apache/camel-k"] |
| 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://badges.gitter.im/apache/camel-k.png["Chat on Gitter", link="https://gitter.im/apache/camel-k"] |
| |
| Apache Camel K (a.k.a. Kamel) is a lightweight integration framework built from Apache Camel that runs natively on Kubernetes and is specifically designed for serverless and microservice architectures. |
| |
| [[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 link:/docs/cluster-setup.adoc[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: |
| |
| - link:/docs/cluster-setup.adoc[Minishift or Minikube] |
| - link:/docs/gke-setup.adoc[Google Kubernetes Engine (GKE)] |
| |
| 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 link:/contributing.adoc[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 |
| ``` |
| |
| 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 |
| ``` |
| |
| ==== 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 additional maven repositories |
| |
| Additional maven repositories can be defined at platform installation time or at integration/context build time: |
| |
| |
| [source] |
| ---- |
| kamel cmd --repository http://repo1.my-company.com --repository http://repo2.my-company.com |
| ---- |
| |
| A repository url follow conventions used to configuire 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 --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> |
| ---- |
| |
| [NOTE] |
| ==== |
| The final repositories list is the sum of the repositories defined on the resource (integration/context) and the platform ones |
| ==== |
| |
| === 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 | Both integrations in source `.java` files or compiled `.class` file can be run. |
| | XML | Integrations written in plain XML DSL are supported (Spring XML or Blueprint not 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 link:docs/languages.adoc[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=1s') |
| .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 link:docs/traits.adoc[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 link:/contributing.adoc[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. |