You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by ja...@apache.org on 2023/07/05 15:55:52 UTC
[camel-quarkus-examples] branch camel-quarkus-main updated: Fix README formatting, typos and grammar
This is an automated email from the ASF dual-hosted git repository.
jamesnetherton pushed a commit to branch camel-quarkus-main
in repository https://gitbox.apache.org/repos/asf/camel-quarkus-examples.git
The following commit(s) were added to refs/heads/camel-quarkus-main by this push:
new d3963dd Fix README formatting, typos and grammar
d3963dd is described below
commit d3963dd3431c7652badba2747bf3605a51d467f9
Author: James Netherton <ja...@gmail.com>
AuthorDate: Wed Jul 5 15:03:41 2023 +0100
Fix README formatting, typos and grammar
---
aws-lambda/README.adoc | 34 ++++----
cluster-leader-election/README.adoc | 5 +-
cxf-soap/README.adoc | 17 +++-
file-split-log-xml/README.adoc | 4 +-
jdbc-datasource/README.adoc | 2 +-
jms-jpa/README.adoc | 30 +++++--
jta-jpa/README.adoc | 23 +++++-
kafka/README.adoc | 5 +-
kamelet-chucknorris/README.adoc | 2 +-
observability/README.adoc | 56 ++++++++-----
.../main/java/org/acme/observability/Routes.java | 9 +--
platform-http-security-keycloak/README.adoc | 91 ++++++++++++++--------
12 files changed, 185 insertions(+), 93 deletions(-)
diff --git a/aws-lambda/README.adoc b/aws-lambda/README.adoc
index 1fef057..3f20def 100644
--- a/aws-lambda/README.adoc
+++ b/aws-lambda/README.adoc
@@ -75,24 +75,24 @@ https://quarkus.io/guides/amazon-lambda#extra-build-generated-files[Please click
== Deploying the Quarkus JVM application to AWS Lambda via AWS Web Console
1. Go to AWS Web console and search for Lambda Service
-
-2. Click Create Function and select Author From Scratch
+
+2. Click Create Function and select Author From Scratch
3. Give the name for your function which should be unique
-4. Select Java 11 (Corretto) as Runtime
+4. Select Java 17 (Corretto) as Runtime
5. Under Permission feel free to create / use existing role to give the required permission for your lambda function
-6. Once the function is created click the function name to upload the generated function.zip file and configure it.
+6. Once the function is created click the function name to upload the generated function.zip file and configure it
-7. Scroll down and select the Code tab. Click the upload from dropdown on right-hand side of the screen and select .zip or .jar file
+7. Scroll down and select the Code tab. Click the upload from dropdown on right-hand side of the screen and select .zip or .jar file
8. Click upload and browse to the path where the generated zip file `target/function.zip` was created and select the function.zip file and click save
-9. Under the Code tab scroll down to the Runtime settings and click edit
+9. Under the Code tab scroll down to the Runtime settings and click edit
-10. For the Handler details please provide the Quarkus Handler
+10. For the Handler details please provide the Quarkus Handler
[source,shell]
----
@@ -101,7 +101,7 @@ io.quarkus.amazon.lambda.runtime.QuarkusStreamHandler::handleRequest
=== Testing the AWS Lambda Function
-1. Now select the Test tab for executing a quick test. Copy paste the below json payload and hit Test
+1. Now select the Test tab for executing a quick test. Copy paste the below json payload and hit Test
{
"name": "Ravishankar"
@@ -119,34 +119,34 @@ io.quarkus.amazon.lambda.runtime.QuarkusStreamHandler::handleRequest
====
1. Go to AWS Web console and search for Lambda Service
-
-2. Click Create Function and select Author From Scratch
+
+2. Click Create Function and select Author From Scratch
3. Give the name for your function which should be unique
-4. For Runtime please scroll down and Select Provide your own bootstrap on Amazon Linux 2 under Custom Runtime
+4. For Runtime please scroll down and Select Provide your own bootstrap on Amazon Linux 2 under Custom Runtime
5. Under Permission feel free to create / use existing role to give the required permission for your lambda function
-6. Once the function is created click the function name to upload the generated function.zip file and configure it.
+6. Once the function is created click the function name to upload the generated function.zip file and configure it.
-7. Scroll down and select the Code tab. Click the upload from dropdown on right-hand side of the screen and select .zip or .jar file
+7. Scroll down and select the Code tab. Click the upload from dropdown on right-hand side of the screen and select .zip or .jar file
8. Click upload and browse to the path where the generated zip file `target/function.zip` was created and select the function.zip file and click save
-9. Under the Code tab scroll down to the Runtime settings and click edit
+9. Under the Code tab scroll down to the Runtime settings and click edit
-10. For the Handler details please provide the below Handler
+10. For the Handler details please provide the below Handler
not.used.in.provided.runtime
-11. Then Select the Configuration tab and click Environment Variables
+11. Then Select the Configuration tab and click Environment Variables
12. For Key enter `DISABLE_SIGNAL_HANDLERS` & for Value enter `true`
=== Testing the AWS Lambda Function
-1. Now select the Test tab for executing a quick test. Copy paste the below json payload and hit Test
+1. Now select the Test tab for executing a quick test. Copy paste the below json payload and hit Test
{
"name": "Ravishankar"
diff --git a/cluster-leader-election/README.adoc b/cluster-leader-election/README.adoc
index c8ddbe2..991aff7 100644
--- a/cluster-leader-election/README.adoc
+++ b/cluster-leader-election/README.adoc
@@ -12,6 +12,7 @@ The quick solution to this problem is actually a fundamental characteristic of K
This example shows you how to implement leader election in Kubernetes using Apache Camel.
== Hot-warm with leader election
+
To run an application as hot-warm means to have multiple instances of the application running and ready to serve requests, but only one instance actually doing the work. Within Kubernetes, this means having multiple pods ready at all times, but only one pod active for a particular process. In this scenario, the pods negotiate among themselves which one is active.
Apache Camel has a component (called master) that is built exactly for this scenario. As the docs explain, the Camel-Master endpoint lets us ensure only a single consumer in a cluster consumes from a given endpoint, with automatic failover if that Java virtual machine (JVM) dies. To achieve this goal, the endpoint requires a shared resource and locking. The component has multiple implementations for the locking mechanism, including camel-kubernetes.
@@ -87,11 +88,12 @@ Depending on which one will start faster, you should first see similar output:
INFO [clustered] (Camel (camel-quarkus-examples-cluster-leader-election) thread #3 - timer://clustered) Clustered route (timer) e54cc6a7-7b5f-4aa3-a9f8-4c31536c3b75 ...
----
-In other terminal you should not see `Clustered route` message.
+In the other terminal you should not see `Clustered route` message.
You can also close the application process with `CTRL+C` and watch the other terminal will take a lead and you should start seeing `Clustered route` messages.
== Kubernetes
+
In a local environment, we used the FileLockClusterService. Now that we are ready to deploy this application on Kubernetes, we will switch the implementation from using files to using https://kubernetes.io/docs/reference/kubernetes-api/cluster-resources/lease-v1/[Kubernetes leases]. To start, let’s take a look at the deployment manifest for the application.
=== Setup service account
@@ -110,6 +112,7 @@ kubectl apply -f src/main/kubernetes/service-account.yaml
=== Playground
==== Deploy
+
[source,shell]
----
mvn clean package -DskipTests -Dquarkus.kubernetes.deploy=true -Dkubernetes -Dquarkus.camel.cluster.file.enabled=false -Dquarkus.camel.cluster.kubernetes.enabled=true
diff --git a/cxf-soap/README.adoc b/cxf-soap/README.adoc
index a5f754e..8f8010f 100644
--- a/cxf-soap/README.adoc
+++ b/cxf-soap/README.adoc
@@ -50,18 +50,23 @@ TIP: Please refer to the Development mode section of
https://camel.apache.org/camel-quarkus/latest/first-steps.html#_development_mode[Camel Quarkus User guide] for more details.
[[playground]]
+
== Playground
-We can first try to add some contact with:
+We can first try to add a contact with:
+
[source,shell]
----
curl -X POST -H "Content-Type: text/xml;charset=UTF-8" -d @src/main/resources/requests/contact/add.xml http://localhost:8080/cxf/services/contact
----
+
Then verify it was added with:
+
[source,shell]
----
$ curl -X POST -H "Content-Type: text/xml;charset=UTF-8" -d @src/main/resources/requests/contact/getAll.xml http://localhost:8080/cxf/services/contact
----
+
Which should return:
[source,xml]
@@ -92,7 +97,8 @@ We can also test our customer service:
$ curl -X POST -H "Content-Type: text/xml;charset=UTF-8" -d @src/main/resources/requests/customer/getByName.xml http://localhost:8080/cxf/services/customer
----
-You can observe that we have hardcoded `test` name at SOAPBody part in `src/main/resources/requests/customer/getByName.soap` as follows:
+You can observe that we have hardcoded `test` as the name in the `SOAPBody` part in `src/main/resources/requests/customer/getByName.soap` as follows:
+
[source, xml]
----
<cus:getCustomersByName>
@@ -117,7 +123,7 @@ Once you invoke the service again, you should see the following exception:
</soap:Envelope>
----
-Last thing which could be tested, is trying to get non-existent customer (which `t` was obviously as well, but now we will pass through schema validation). So change the name to eg. `Non existent` and see result with `NoSuchCustomer`:
+The last thing which could be tested, is trying to get a non-existent customer (which `t` was obviously as well, but now we will pass it through schema validation). So change the name to `Non existent` and see result with `NoSuchCustomer`:
[source, xml]
----
@@ -140,6 +146,7 @@ Last thing which could be tested, is trying to get non-existent customer (which
TIP: To obtain WSDLs for any exposed CXF service, you can query URL `http://<hostname>/<cxf-path>?wsdl`. It can be handy in tools like _SoapUI_.
To discover WSDLs of our services, you can use:
+
[source, shell]
----
$ curl "http://localhost:8080/cxf/services/contact?wsdl"
@@ -175,7 +182,9 @@ $ ./target/*-runner
----
== Kubernetes
+
==== Deploy
+
[source,shell]
----
$ mvn clean package -DskipTests -Dquarkus.kubernetes.deploy=true -Dkubernetes
@@ -197,7 +206,7 @@ $ kubectl port-forward service/camel-quarkus-examples-cxf-soap 8080:8080
Open another terminal and then follow instructions from <<playground>>.
-To stop it you can CTRL+C the process in port-forwarding terminal and shutdown the Kubernetes cluster.
+To stop it you can CTRL+C the process in the port-forwarding terminal and shutdown the Kubernetes cluster.
== Feedback
diff --git a/file-split-log-xml/README.adoc b/file-split-log-xml/README.adoc
index 23c602b..dca293e 100644
--- a/file-split-log-xml/README.adoc
+++ b/file-split-log-xml/README.adoc
@@ -29,8 +29,8 @@ workspace. Any modifications in your project will automatically take effect in t
TIP: Please refer to the Development mode section of
https://camel.apache.org/camel-quarkus/latest/first-steps.html#_development_mode[Camel Quarkus User guide] for more details.
-Once the application has started it will wait 5 seconds and then read the file every 30 seconds. By default the row split
-is sequential however you can edit the properties file and set the parallel processing to true. The output should then be
+Once the application has started it will wait 5 seconds and then read the file every 30 seconds. By default, the row split
+is sequential, however, you can edit the properties file and set the parallel processing to true. The output should then be
a little more out of order i.e. non-sequential processing of rows.
=== Package and run the application
diff --git a/jdbc-datasource/README.adoc b/jdbc-datasource/README.adoc
index d3506a4..d44c5a0 100644
--- a/jdbc-datasource/README.adoc
+++ b/jdbc-datasource/README.adoc
@@ -6,7 +6,7 @@
In particular, it demonstrates the following:
1. Defining a DataSource
-2. Querying the Database defined in the previous DataSource
+2. Querying the Database defined in the previous `DataSource`
3. Usage of properties defined in `application.properties`
4. No Java code required or used, the route defined in XML can still be compiled to native code.
diff --git a/jms-jpa/README.adoc b/jms-jpa/README.adoc
index ca814a5..5706bab 100644
--- a/jms-jpa/README.adoc
+++ b/jms-jpa/README.adoc
@@ -37,6 +37,7 @@ https://camel.apache.org/camel-quarkus/latest/first-steps.html#_package_and_run_
==== External systems
Start MySQL:
+
[source, shell]
----
docker run --name db-mysql \
@@ -52,6 +53,7 @@ docker exec -it db-mysql mysql -uroot -proot -e \
----
Create `audit_log` if it is needed:
+
[source, shell]
----
docker exec -it db-mysql mysql -uadmin -padmin testdb -e \
@@ -63,6 +65,7 @@ docker exec -it db-mysql mysql -uadmin -padmin testdb -e \
----
Start Artemis:
+
[source, shell]
----
docker run --name artemis \
@@ -73,9 +76,11 @@ docker run --name artemis \
==== Prerequisites
-- Make sure `io.quarkus:quarkus-jdbc-mysql` has been added in `pom.xml`
-- Make sure `db-mysql` and `artemis` has been started and ready for servicing
+
+- Make sure `io.quarkus:quarkus-jdbc-mysql` has been added to the project `pom.xml`
+- Make sure `db-mysql` and `artemis` has been started and are ready for servicing
- Edit `src/main/resource/application.properties` to uncomment all `%prod` lines
+
[source, properties]
----
# Production Datasource
@@ -120,6 +125,7 @@ $ ./target/*-runner
----
==== How to run
+
Test the service endpoint from another terminal:
[source,shell]
@@ -130,28 +136,35 @@ curl $ADDRESS/api/messages
----
Test with normal "hello" content:
+
[source,shell]
----
curl -X POST $ADDRESS/api/messages/hello
----
-Check the audit_log
+Check the audit_log:
+
[source,shell]
----
curl $ADDRESS/api/messages
----
-You should get some results like
+
+You should get some results like:
+
[source]
----
[{message=hello}, {message=hello-ok}]
----
Test rollback by calling the service with "fail" content:
+
[source,shell]
----
curl -X POST $ADDRESS/api/messages/fail
----
-You should not find any trace of the message in the audit_log table. And some failures like
+
+You should not find any trace of the message in the audit_log table. And some failures like:
+
[source]
----
2022-07-01 11:03:10,257 INFO [route2] (executor-thread-0) Forced exception
@@ -166,20 +179,24 @@ Source ID Processo
Stacktrace
---------------------------------------------------------------------------------------------------------------------------------------: java.lang.RuntimeException: fail
-
----
Test crash recovery by calling the service with "crash" content:
+
[source,shell]
----
curl -X POST $ADDRESS/api/messages/crash
----
+
The application should be crashed, and you can not see any response.
+
[source]
----
curl: (52) Empty reply from server
----
+
Now restart the application, and wait about 10 seconds, then you can see the following messages that the application has recovered the transaction.
+
[source]
----
2022-09-16 12:35:39,994 INFO [io.quarkus] (main) camel-quarkus-examples-jta-jpa 2.13.0-SNAPSHOT on JVM (powered by Quarkus 2.13.0.CR1) started in 1.755s. Listening on: http://0.0.0.0:8080
@@ -188,6 +205,7 @@ Now restart the application, and wait about 10 seconds, then you can see the fol
2022-09-16 12:35:49,251 INFO [org.acm.DummyXAResourceRecovery] (Periodic Recovery) DummyXAResourceRecovery returning list of resources: [org.acme.DummyXAResource@35cdbf7a]
2022-09-16 12:35:49,270 INFO [org.acm.DummyXAResource] (Periodic Recovery) Committing DummyXAResource
----
+
check the audit_log table, you should see the message "crash" in the table.
== Feedback
diff --git a/jta-jpa/README.adoc b/jta-jpa/README.adoc
index 73309c1..436f795 100644
--- a/jta-jpa/README.adoc
+++ b/jta-jpa/README.adoc
@@ -37,6 +37,7 @@ https://camel.apache.org/camel-quarkus/latest/first-steps.html#_package_and_run_
==== External systems
Start MySQL:
+
[source, shell]
----
docker run --name db-mysql \
@@ -52,6 +53,7 @@ docker exec -it db-mysql mysql -uroot -proot -e \
----
Create `audit_log` if it is needed:
+
[source, shell]
----
docker exec -it db-mysql mysql -uadmin -padmin testdb -e \
@@ -63,9 +65,11 @@ docker exec -it db-mysql mysql -uadmin -padmin testdb -e \
----
==== Prerequisites
+
- Make sure `io.quarkus:quarkus-jdbc-mysql` has been added in `pom.xml`
- Make sure `db-mysql` has been started and ready for servicing
- Edit `src/main/resource/application.properties` to uncomment all `%prod` lines
+
[source, properties]
----
# Production Datasource
@@ -106,6 +110,7 @@ $ ./target/*-runner
----
==== How to run
+
Test the service endpoint from another terminal:
[source,shell]
@@ -116,28 +121,35 @@ curl $ADDRESS/api/messages
----
Test with normal "hello" content:
+
[source,shell]
----
curl -X POST $ADDRESS/api/messages/hello
----
-Check the audit_log
+Check the audit_log:
+
[source,shell]
----
curl $ADDRESS/api/messages
----
-You should get some results like
+
+You should get some results like:
+
[source]
----
[{message=hello}]
----
Test rollback by calling the service with "fail" content:
+
[source,shell]
----
curl -X POST $ADDRESS/api/messages/fail
----
-You should not find any trace of the message in the audit_log table. And some failures like
+
+You should not find any trace of the message in the audit_log table. And some failures like:
+
[source]
----
2022-07-01 11:03:10,257 INFO [route2] (executor-thread-0) Forced exception
@@ -156,16 +168,21 @@ Stacktrace
----
Test crash recovery by calling the service with "crash" content:
+
[source,shell]
----
curl -X POST $ADDRESS/api/messages/crash
----
+
The application should be crashed, and you can not see any response.
+
[source]
----
curl: (52) Empty reply from server
----
+
Now restart the application, and wait about 10 seconds, then you can see the following messages that the application has recovered the transaction.
+
[source]
----
2022-09-16 12:35:39,994 INFO [io.quarkus] (main) camel-quarkus-examples-jta-jpa 2.13.0-SNAPSHOT on JVM (powered by Quarkus 2.13.0.CR1) started in 1.755s. Listening on: http://0.0.0.0:8080
diff --git a/kafka/README.adoc b/kafka/README.adoc
index 99036b6..2071133 100644
--- a/kafka/README.adoc
+++ b/kafka/README.adoc
@@ -65,6 +65,7 @@ TIP: Find more details about the JVM mode and Native mode in the Package and run
https://camel.apache.org/camel-quarkus/latest/first-steps.html#_package_and_run_the_application[Camel Quarkus User guide]
==== Configure kafka client
+
Uncomment the corresponding commented section in `src/main/resources/application.properties`.
- The section Kafka instance without Authentication if no Authentication required.
@@ -73,6 +74,7 @@ Uncomment the corresponding commented section in `src/main/resources/application
You need to set the corresponding environment variables:
- Without Authentication
+
[source,shell]
----
$ export brokers=<YOUR_KAFKA_BROKERS_URL>
@@ -93,7 +95,8 @@ $ export secret=<YOUR_KAFKA_SASL_CLIENT_SECRET>
$ export token=<YOUR_KAFKA_SASL_OAUTHBEARER_TOKEN_URL>
----
-If you want to deploy on Kubernetes or Openshift, you'd need to define those in a secret named `camel-kafka`. Set the needed values in the `kubefiles/secret-example.yml`, then add the secret :
+If you want to deploy on Kubernetes or Openshift, you'd need to define the above environment variables in a secret named `camel-kafka`. Set the needed values in the `kubefiles/secret-example.yml`, then add the secret :
+
[source,shell]
----
$ kubectl apply -f kubefiles/secret-example.yml
diff --git a/kamelet-chucknorris/README.adoc b/kamelet-chucknorris/README.adoc
index 992cab9..fe2aefe 100644
--- a/kamelet-chucknorris/README.adoc
+++ b/kamelet-chucknorris/README.adoc
@@ -7,7 +7,7 @@ The kamelet is created as a YAML file in the `src/main/resources/kamelets` direc
We have developed a Chuck Norris Kamelet that periodically gets a joke from the Chuck Norris internet database.
A Camel route is coded in Java in the `src/main/java/org/acme/kamelet/MyRoute.java` file
-that uses the Kamelet, and log the result from the Kamelet to the console.
+that uses the Kamelet, and logs the result from the Kamelet to the console.
TIP: Check the https://camel.apache.org/camel-quarkus/latest/first-steps.html[Camel Quarkus User guide] for prerequisites
and other general information.
diff --git a/observability/README.adoc b/observability/README.adoc
index 6e5f073..831b2ae 100644
--- a/observability/README.adoc
+++ b/observability/README.adoc
@@ -19,9 +19,10 @@ workspace. Any modifications in your project will automatically take effect in t
TIP: Please refer to the Development mode section of
https://camel.apache.org/camel-quarkus/latest/first-steps.html#_development_mode[Camel Quarkus User guide] for more details.
-=== How to enable metrics
+=== Enabling metrics
+
To enable observability features in Camel Quarkus, we need to add some additional dependencies to the project's pom.xml file.
-The most important one (see link:pom.xml#L97-L100[pom.xml]):
+The most important one for metrics is `camel-quarkus-micrometer`:
[source, xml]
----
@@ -31,28 +32,45 @@ The most important one (see link:pom.xml#L97-L100[pom.xml]):
</dependency>
----
-After adding this dependency, you can benefit from both https://camel.apache.org/components/next/micrometer-component.html[Camel Micrometer] and https://quarkus.io/guides/micrometer[Quarkus Micrometer] worlds.
+After adding this dependency, you can benefit from both of the https://camel.apache.org/components/next/micrometer-component.html[Camel Micrometer] and https://quarkus.io/guides/micrometer[Quarkus Micrometer] worlds.
We are able to use multiple ways of creating meters for our custom metrics.
-First of them is using Camel micrometer component (see link:src/main/java/org/acme/observability/Routes.java[Routes.java]):
+First using Camel micrometer component (see link:src/main/java/org/acme/observability/Routes.java[Routes.java]):
[source, java]
----
.to("micrometer:counter:org.acme.observability.greeting-provider?tags=type=events,purpose=example")
----
-which will count each call to `platform-http:/greeting-provider` endpoint.
+Which will count each call to the `platform-http:/greeting-provider` endpoint.
+
+The second approach is to benefit from CDI dependnecy injection of the `MeterRegistry`:
+
+[source, java]
+----
+@Inject
+MeterRegistry registry;
+----
-Second approach is to benefit from auto-injected `MeterRegistry` (see link:src/main/java/org/acme/observability/Routes.java#L28[injection]) and use it directly (see link:src/main/java/org/acme/observability/Routes.java#L36[registry call]):
+Then using it directly in a Camel `Processor` method to publish metrics:
+
+[source, java]
+----
+void countGreeting(Exchange exchange) {
+ registry.counter("org.acme.observability.greeting", "type", "events", "purpose", "example").increment();
+}
+----
[source, java]
----
-registry.counter("org.acme.observability.greeting", "type", "events", "purpose", "example").increment();
+from("platform-http:/greeting")
+ .removeHeaders("*")
+ .process(this::countGreeting)
----
-which will count each call to `platform-http:/greeting` endpoint.
+This counts each call to the `platform-http:/greeting` endpoint.
-Finally last approach is to use Micrometer annotations (see https://quarkus.io/guides/micrometer#does-micrometer-support-annotations[which] are supported by Quarkus) by defining bean link:src/main/java/org/acme/observability/micrometer/TimerCounter.java[TimerCounter.java] as follows:
+Finally, the last approach is to use https://quarkus.io/guides/micrometer#does-micrometer-support-annotations[Micrometer annotations], by defining a bean link:src/main/java/org/acme/observability/micrometer/TimerCounter.java[TimerCounter.java] as follows:
[source, java]
----
@@ -66,22 +84,21 @@ public class TimerCounter {
}
----
-and invoking it from Camel via (see link:src/main/java/org/acme/observability/TimerRoute.java[TimerRoute.java]):
+It can then be invoked from Camel via the bean EIP (see link:src/main/java/org/acme/observability/TimerRoute.java[TimerRoute.java]):
[source, java]
----
.bean("timerCounter", "count")
----
-It will count each time the timer is fired.
-How to explore our custom metrics will be shown in the next chapter.
+It will increment the counter metric each time the Camel timer is fired.
-=== Metrics endpoint
+=== Browsing metrics
Metrics are exposed on an HTTP endpoint at `/q/metrics` on port `9000`.
-NOTE: Note we are using different port (9000) for the management endpoint then our application (8080) is listening on.
-This is caused by using link:src/main/resources/application.properties#L22[`quarkus.management.enabled = true`] (see https://quarkus.io/guides/management-interface-reference for more information).
+NOTE: Note we are using a different port (9000) for the management endpoint then our application (8080) is listening on.
+This is configured in `applcation.properties` via link:src/main/resources/application.properties#L22[`quarkus.management.enabled = true`]. See the https://quarkus.io/guides/management-interface-reference[Quarkus management interface guide] for more information.
To view all Camel metrics do:
@@ -99,7 +116,7 @@ $ curl -s localhost:9000/q/metrics | grep -i 'purpose="example"'
and you should see 3 lines of different metrics (with the same value, as they are all triggered by the timer).
-NOTE: Maybe you've noticed the Prometheus output format. If you would rather use JSON format, please follow https://quarkus.io/guides/micrometer#management-interface.
+NOTE: Maybe you've noticed the Prometheus output format. If you would rather use the JSON format, please follow the Quarkus Micrometer management interface https://quarkus.io/guides/micrometer#management-interface[configuration guide].
=== Health endpoint
@@ -127,7 +144,7 @@ You can also directly leverage MicroProfile Health APIs to create checks. Class
To be able to diagnose problems in Camel Quarkus applications, you can start tracing messages.
We will use OpenTelemetry standard suited for cloud environments.
-All you need is to add the `camel-quarkus-opentelemetry` dependency (see link:pom.xml#L101-L104[pom.xml]):
+All you need is to add the `camel-quarkus-opentelemetry` dependency to your project `pom.xml`:
[source, xml]
----
@@ -137,14 +154,15 @@ All you need is to add the `camel-quarkus-opentelemetry` dependency (see link:po
</dependency>
----
-and configure (we are using placeholder to be able to test this example in convenient way in cloud environment) the exporter (see link:src/main/resources/application.properties#L28[application.properties]) :
+Then configure the OpenTelemetry exporter in `application.properties`:
[source, text]
----
+# We are using a property placeholder to be able to test this example in convenient way in a cloud environment
quarkus.otel.exporter.otlp.traces.endpoint = http://${TELEMETRY_COLLECTOR_COLLECTOR_SERVICE_HOST:localhost}:4317
----
-NOTE: For further information eg. about other exporters, please follow https://camel.apache.org/camel-quarkus/next/reference/extensions/opentelemetry.html#extensions-opentelemetry-usage[usage] part of Camel Quarkus Opentelemetry extension documentation.
+NOTE: For information about other OpenTelemetry exporters, refer to the Camel Quarkus Opentelemetry https://camel.apache.org/camel-quarkus/next/reference/extensions/opentelemetry.html#extensions-opentelemetry-usage-exporters[extension documentation].
To view tracing events, start a tracing server. A simple way of doing this is with Docker Compose:
diff --git a/observability/src/main/java/org/acme/observability/Routes.java b/observability/src/main/java/org/acme/observability/Routes.java
index 86730d7..f783ffb 100644
--- a/observability/src/main/java/org/acme/observability/Routes.java
+++ b/observability/src/main/java/org/acme/observability/Routes.java
@@ -18,18 +18,15 @@ package org.acme.observability;
import io.micrometer.core.instrument.MeterRegistry;
import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
import org.apache.camel.Exchange;
import org.apache.camel.builder.RouteBuilder;
@ApplicationScoped
public class Routes extends RouteBuilder {
- // Quarkus will inject this automatically for us
- private final MeterRegistry registry;
-
- public Routes(MeterRegistry registry) {
- this.registry = registry;
- }
+ @Inject
+ MeterRegistry registry;
private void countGreeting(Exchange exchange) {
// This is our custom metric: just counting how many times the method is called
diff --git a/platform-http-security-keycloak/README.adoc b/platform-http-security-keycloak/README.adoc
index e492140..057c37f 100644
--- a/platform-http-security-keycloak/README.adoc
+++ b/platform-http-security-keycloak/README.adoc
@@ -12,22 +12,29 @@ and other general information.
The example application requires a Keycloak instance.
You do not need to provide the Keycloak instance yourself
-as long as you play with the example code in dev mode (a.k.a. `mvn quarkus:dev` - read more https://quarkus.io/guides/getting-started#development-mode[here]
+as long as you play with the example code in dev mode (a.k.a. `mvn quarkus:dev`) - read more https://quarkus.io/guides/getting-started#development-mode[here]
or as long as you only run the supplied tests (`mvn test`).
In those situations, Quarkus tooling starts a Keycloak image for you via https://quarkus.io/guides/security-openid-connect-dev-services[Quarkus Dev Services]
and it also configures the application so that you do not need touch anything in `application.properties`.
[[users-configuration]]
+
=== Users configuration
-In all scenarios which we will cover, we will need two users `boss` (with role `admin-role` and password `boss-pass`) and `employee` (with role `regular-role` and password `employee-pass`). Employee user can be authenticated and access secured HTTP endpoints and boss user can in addition access also restricted HTTP resources.
-=== Quarkus under the hood
+In all scenarios which we will cover, we will need two users `boss` (with role `admin-role` and password `boss-pass`) and `employee` (with role `regular-role` and password `employee-pass`).
+The `employee` user can be authenticated and access secured HTTP endpoints. The `boss` user can additionally access restricted HTTP resources.
+
+=== Quarkus OIDC
-We will use approach described in https://quarkus.io/guides/security-openid-connect[Quarkus Open ID Connect] (we want to use Keycloak as our OIDC provider) to protect service application. It will automatically protect (you can find more info in https://camel.apache.org/camel-quarkus/2.8.x/reference/extensions/platform-http.html#_securing_platform_http_endpoints[Securing platform-http endpoints]) our Camel Quarkus platform http routes, so all security configuration go through Quarkus exte [...]
+We will use the approach described in https://quarkus.io/guides/security-openid-connect-client-reference[Quarkus Open ID Connect] (we want to use Keycloak as our OIDC provider) to protect the application.
+It will automatically protect (you can find more info in https://camel.apache.org/camel-quarkus/latest/reference/extensions/platform-http.html#_securing_platform_http_endpoints[Securing platform-http endpoints]) our
+Camel Quarkus platform http routes, so all security configuration will be made with the support of Quarkus extensions.
== Start in Development mode
+
=== Run the app with Keycloak instance
-Run the application in development mode with Keycloak client credentials secret of your choice (see environment variable `QUARKUS_OIDC_CREDENTIALS_SECRET`) which will be used later on.
+
+Run the application in development mode with a Keycloak client credentials secret of your choice (see environment variable `QUARKUS_OIDC_CREDENTIALS_SECRET`) which will be used later on.
TIP: If you want to use another running instance, in dev mode. Change `%prod` profile to `%dev` property `quarkus.oidc.auth-server-url` in `src/main/resources/application.properties`.
@@ -46,54 +53,65 @@ https://camel.apache.org/camel-quarkus/latest/first-steps.html#_development_mode
Now you can move on to <<playground>> section with assumption that `KEYCLOAK_URL=http://localhost:8082` and `APP_URL=http://localhost:8080`.
[[playground]]
+
=== Playground
-First thing you need to do is to obtain Bearer token from the running Keycloak instance for each created user. Save those tokens for further authentication.
-For employee user (extract value from response of key `access_token` and call it `EMPLOYEE_TOKEN`):
+The First thing to do is to obtain the Bearer token from the running Keycloak instance for each created user. Save those tokens for further authentication.
+
+For the `employee` user, extract value from response of key `access_token` and call it `EMPLOYEE_TOKEN`:
+
[source,shell]
----
$ curl -d "client_id=quarkus-client" -d "client_secret=$QUARKUS_OIDC_CREDENTIALS_SECRET" -d "username=employee" -d "password=employee-pass" -d "grant_type=password" $KEYCLOAK_URL/realms/quarkus/protocol/openid-connect/token
----
-For boss user (extract value from response of key `access_token` and call it `BOSS_TOKEN`):
+
+For the `boss` use, extract value from response of key `access_token` and call it `BOSS_TOKEN`:
+
[source,shell]
----
$ curl -d "client_id=quarkus-client" -d "client_secret=$QUARKUS_OIDC_CREDENTIALS_SECRET" -d "username=boss" -d "password=boss-pass" -d "grant_type=password" $KEYCLOAK_URL/realms/quarkus/protocol/openid-connect/token
----
-Now we can finally try to play with the application which have those endpoints configured:
+Now we are ready to try some HTTP endpoints:
-- not-secured - anyone can access this endpoint
-- secured/authenticated - authenticated users with Bearer token can access this endpoint
-- secured/authorized - only users with role `admin-role` can access this endpoint
+- `not-secured` - anyone can access this endpoint
+- `secured/authenticated` - authenticated users with a Bearer token can access this endpoint
+- `secured/authorized` - only users with role `admin-role` can access this endpoint
-Try to access endpoints with various users:
+- `employee` accessing an authenticated endpoint (you should receive `200 OK` + `You are authenticated user so you can perform this action.` message):
-- Employee accessing authenticated endpoint (you should receive `200 OK` + `You are authenticated user so you can perform this action.` message):
[source,shell]
----
$ curl -i -X GET -H "Authorization: Bearer $EMPLOYEE_TOKEN" $APP_URL/secured/authenticated
----
-- Employee accessing authorized endpoint (you should receive `403 Forbidden`):
+
+- `employee` accessing an authorized endpoint (you should receive `403 Forbidden`):
+
[source,shell]
----
$ curl -i -X GET -H "Authorization: Bearer $EMPLOYEE_TOKEN" $APP_URL/secured/authorized
----
-- Boss accessing authenticated endpoint (you should receive `200 OK` + `You are authenticated user so you can perform this action.` message):
+
+- `boss` accessing an authenticated endpoint (you should receive `200 OK` + `You are authenticated user so you can perform this action.` message):
+
[source,shell]
----
$ curl -i -X GET -H "Authorization: Bearer $BOSS_TOKEN" $APP_URL/secured/authenticated
----
-- Boss accessing authorized endpoint (you should receive `200 OK` + `You are authorized to perform sensitive operation.`):
+
+- `boss` accessing an authorized endpoint (you should receive `200 OK` + `You are authorized to perform sensitive operation.`):
+
[source,shell]
----
$ curl -i -X GET -H "Authorization: Bearer $BOSS_TOKEN" $APP_URL/secured/authorized
----
[[external-keycloak-instance-configuration]]
-== Prerequisites for externally running Keycloak instance
-For next steps we need to have externally running Keycloak instance. It can be done easily via Keycloak docker image:
-=== Run the Keycloak
+== Prerequisites for an externally running Keycloak instance
+
+For the next steps, we need to have an externally running Keycloak instance. This can be done easily via the Keycloak docker image:
+
[source,shell]
----
$ docker run --name keycloak_test -p 8082:8080 \
@@ -101,16 +119,20 @@ $ docker run --name keycloak_test -p 8082:8080 \
quay.io/keycloak/keycloak:latest \
start-dev
----
-=== Import preconfigured realm
-Then go to `http://localhost:8082/` click on `Administrator console` and login with `admin:admin`. Then we are going to import already pre-configured realm (`realm-export.json`) stored within `config` folder placed at root of this example.
-Navigate to left upper panel and click on `Add realm` select file `config/realm-export.json` and `create` it.
+
+=== Import the preconfigured realm
+
+Then go to `http://localhost:8082/` click on `Administrator console` and login with `admin:admin`. Next, import the pre-configured realm (`realm-export.json`) stored within `config` folder placed at root of this example.
+Navigate to left upper panel and click on `Add realm`, select file `config/realm-export.json` and `create` it.
=== Setup users
+
You should create new users with credentials and roles based on <<users-configuration>>.
TIP: Don't use `temporary` passwords.
-=== Get client credentials secret
+=== Get the client credentials secret
+
Go to `Configure` left panel and select `quarkus-client` under `Clients`. Go to `Credentials` and `Regenerate Secret`. Save it as `QUARKUS_OIDC_CREDENTIALS_SECRET`.
== JVM mode
@@ -122,7 +144,7 @@ $ mvn clean package -DskipTests
$ java -jar target/quarkus-app/quarkus-run.jar
----
-Now you can go to <<playground>> section (with assumption that `KEYCLOAK_URL=http://localhost:8082` and `APP_URL=http://localhost:8080`) and try it yourselves.
+Now you can go to the <<playground>> section (with the assumption that `KEYCLOAK_URL=http://localhost:8082` and `APP_URL=http://localhost:8080`) and try it yourself.
== Native mode
@@ -138,7 +160,7 @@ $ mvn clean package -DskipTests -Pnative
$ ./target/*-runner
----
-Now you can go to <<playground>> section (with assumption that `KEYCLOAK_URL=http://localhost:8082` and `APP_URL=http://localhost:8080`) and try it yourselves.
+Now you can go to the <<playground>> section (with the assumption that `KEYCLOAK_URL=http://localhost:8082` and `APP_URL=http://localhost:8080`) and try it yourself.
== Deploying to Kubernetes
@@ -147,16 +169,18 @@ You can build a container image for the application like this. Refer to the http
This example uses Jib to create the container image for Kubernetes deployment.
=== Deploy Keycloak to Kubernetes
+
Follow https://www.keycloak.org/getting-started/getting-started-kube to install on Kubernetes cluster.
=== Configure Keycloak on Kubernetes
-Use the same configuration as in <<external-keycloak-instance-configuration>> and obtain `QUARKUS_OIDC_CREDENTIALS_SECRET` and Kubernetes base URL (BASE_KEYCLOAK_KUBERNETES_URL) to your keycloak instance.
+
+Use the same configuration as in <<external-keycloak-instance-configuration>> and obtain `QUARKUS_OIDC_CREDENTIALS_SECRET` and rhe Kubernetes base URL (BASE_KEYCLOAK_KUBERNETES_URL) to your keycloak instance.
=== Deploy Camel Quarkus application to Kubernetes
TIP: Because we use `quarkus.kubernetes.env.secrets=quarkus-keycloak` in `application.properties` all properties from the secret `quarkus-keycloak` will be presented as ENV variables to the pod.
-TIP: To trust self-signed certificates from Kubernetes API server use `-Dquarkus.kubernetes-client.trust-certs=true` in deploy command.
+TIP: To trust self-signed certificates from Kubernetes API server use `-Dquarkus.kubernetes-client.trust-certs=true` in the deploy command.
[source,shell]
----
@@ -190,7 +214,7 @@ camel-quarkus-examples-platform-http-security-6f658784dd-kxcg8 1/1 Running
keycloak-57d89d998-rfkk7
----
-Find the app url KUBERNETES_APP_URL from Kubernetes ingress.
+Find the app url `KUBERNETES_APP_URL` from Kubernetes ingress.
Then you can play with the example based on <<playground>> instructions (with assumption that `KEYCLOAK_URL=$BASE_KEYCLOAK_KUBERNETES_URL` and `APP_URL=$KUBERNETES_APP_URL`).
@@ -205,10 +229,13 @@ $ kubectl delete secret quarkus-keycloak
== Deploying to OpenShift
=== Deploy Keycloak to OpenShift
-Follow https://www.keycloak.org/getting-started/getting-started-openshift to install on OpenShift cluster.
+
+Follow https://www.keycloak.org/getting-started/getting-started-openshift to install on an OpenShift cluster.
=== Configure Keycloak on OpenShift
+
Use the same configuration as in <<external-keycloak-instance-configuration>> and obtain `QUARKUS_OIDC_CREDENTIALS_SECRET` and OpenShift route base URL to your keycloak instance as follows:
+
[source,shell]
----
$ export BASE_KEYCLOAK_OPENSHIFT_ROUTE_URL=$(oc get route keycloak --template='{{ .spec.host }}')
@@ -255,14 +282,14 @@ keycloak-1-9z2r9 1/1 Running 0
keycloak-1-deploy 0/1 Completed 0 25h
----
-Find the app url via
+Find the app url via:
[source,shell]
----
$ export OPENSHIFT_APP_URL=$(oc get route camel-quarkus-examples-platform-http-security --template='{{ .spec.host }}')
----
-Then you can play with the example based on <<playground>> instructions (with assumption that `KEYCLOAK_URL=https://$BASE_KEYCLOAK_OPENSHIFT_ROUTE_URL` and `APP_URL=$OPENSHIFT_APP_URL`).
+Then you can play with the example based on <<playground>> instructions (with the assumption that `KEYCLOAK_URL=https://$BASE_KEYCLOAK_OPENSHIFT_ROUTE_URL` and `APP_URL=$OPENSHIFT_APP_URL`).
To clean up do: