diff --git a/code-samples/eventing/bookstore-sample-app/slack-sink/README.md b/code-samples/eventing/bookstore-sample-app/slack-sink/README.md new file mode 100644 index 000000000..737e6cf59 --- /dev/null +++ b/code-samples/eventing/bookstore-sample-app/slack-sink/README.md @@ -0,0 +1,181 @@ +# Bookstore Notification Service: with Apache Camel K and Knative Eventing + + +As a bookstore owner, you aim to receive instant notifications in a Slack channel whenever a customer submits a new review comment. By leveraging Knative Eventing and Apache Camel K, you can set up an event-driven service that automates these notifications, ensuring you're always informed. +## What Knative features will we learn about? +- Knative's ability to connect with third-party services, such as Slack, through event-driven integration using Apache Camel K. + +## What does the final deliverable look like? +When a CloudEvent with the type `new-review-comment` is sent to the Knative Eventing Broker, it triggers a message to be sent in a designated Slack channel. + +## Install prerequisites + +### Prerequisite 1: Install Camel CLI +Install the Camel K CLI (`kamel`) on your local machine. You can find the installation instructions [here](https://camel.apache.org/camel-k/2.2.x/cli/cli.html). + +**Troubleshot**: If after installation you run `kamel version` and you get an error message, you may need to add the `kamel` binary to your system's PATH. You can do this by moving the `kamel` binary to a directory that is already in your PATH, or by adding the directory where `kamel` is located to your PATH. + +```bash +$ export PATH=$PATH: +``` + + +### Prerequisite 2: Install Apache Camel-Kamelets +Next, install Camel K on your cluster using the Camel K CLI: + +```bash +$ kamel install --registry docker.io --organization --registry-auth-username --registry-auth-password +``` + +Replace the placeholders with your actual Docker registry information. + +If you are using other container registries, you may need to read more [here](https://camel.apache.org/camel-k/2.2.x/installation/registry/registry.html) for the installation. + +You will see this message if the installation is successful: + +``` +OLM is not available in the cluster. Fallback to regular installation. +Camel K installed in namespace default +``` +### Prerequisite 3: Create a Slack App and Generate an Incoming Webhook URL +Follow the instruction here on how to create the slack workspace and generate an incoming webhook URL for your designated channel where notifications will be sent. + +## Implementation +### Step 1: Create the Broker + +This broker is created solely for testing purposes and is intended for temporary use during this part of the tutorial only. + +**Method 1**: Initialize a broker within your Kubernetes cluster using the Knative CLI: + +```bash +$ kn broker create book-review-broker +``` +You will see this message if the broker is created successfully: + +``` +Broker ‘book-review-broker’ successfully created in namespace ‘default’. +``` +**Method 2**: You can create a new YAML file to create the broker: + +*new-knative-broker.yaml* +```yaml +apiVersion: eventing.knative.dev/v1 +kind: Broker +metadata: + name: book-review-broker + namespace: default +``` +After you saved the file, you can apply the configuration to your Kubernetes cluster: + +```bash +$ kubectl apply -f new-knative-broker.yaml +``` +You will see this message if the broker is created successfully: + +``` +broker.eventing.knative.dev/book-review-broker created +``` + + +### Step 2: Configure the Slack Sink + +We use a feature called "Pipe" in Camel K to link event sources and destinations. Specifically, the Pipe connects events from a Broker, our source, to a Slack channel through a Slack sink Kamelet, our destination. This setup automatically sends notifications to Slack whenever new events occur, streamlining the flow of information. + + +1. Create a Slack app and generate an incoming webhook URL for your designated channel where notifications will be sent. Refer to Slack documentation for how to do this. + +2. Prepare the YAML configuration for the Slack sink, which will forward events to your Slack channel: + +*slack-sink.yaml* +```yaml +apiVersion: camel.apache.org/v1 # Specifies the API version of Camel K. +kind: Pipe # This resource type is a Pipe, a custom Camel K resource for defining integration flows. +metadata: + name: bookstore-notification-service # The name of the Pipe, which identifies this particular integration flow. +spec: + source: # Defines the source of events for the Pipe. + ref: + kind: Broker # Specifies the kind of source, in this case, a Knative Eventing Broker. + apiVersion: eventing.knative.dev/v1 # The API version of the Knative Eventing Broker. + name: book-review-broker # The name of the Broker, "book-review-broker" in this case + properties: + type: new-review-comment # A filter that specifies the type of events this Pipe will listen for, here it's listening for events of type "new-review-comment". You have to have this type specified. + sink: # Defines the destination for events processed by this Pipe. + ref: + kind: Kamelet # Specifies that the sink is a Kamelet, a Camel K component for connecting to external services. + apiVersion: camel.apache.org/v1 # The API version for Kamelet. + name: slack-sink # The name of the Kamelet to use as the sink, in this case, a predefined "slack-sink" Kamelet. + properties: + channel: “#bookstore-owner” # The Slack channel where notifications will be sent. + webhookUrl: "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK" # The Webhook URL provided by Slack for posting messages to a specific channel. + +``` + +Make sure to replace the `webhookUrl` with your actual Slack channel name and webhook URL. + + +3. Apply the configuration to your Kubernetes cluster: + +```bash +$ kubectl apply -f slack-sink.yaml +``` +You will see this message if the configuration is created successfully: + +``` +pipe.camel.apache.org/slack-sink-pipe created +``` +But this process will take a few seconds to complete. You can check the status of the pipe by running the following command: + +```bash +$ kubectl get pipe slack-sink-pipe + +NAME PHASE REPLICAS +slack-sink-pipe Ready 1 +``` + + + +### Step 3: Testing by Triggering Notifications + +To trigger notifications, you'll need to simulate an event that matches the criteria set in your Slack sink configuration. For example, submitting a book review could be an event of type `new-review-comment`. + +Directly sending CloudEvents to a broker using curl from an external machine (like your local computer) is typically **constrained** due to the networking and security configurations of Kubernetes clusters. + +Therefore, you need to create a new pod in your Kubernetes cluster to send a CloudEvent to the broker. You can use the following command to create a new pod: + +```bash +$ kubectl run curler --image=radial/busyboxplus:curl -it --restart=Never +``` +You will see this message if you successfully entered the pod's shell + +``` +If you don't see a command prompt, try pressing enter. +[root@curler:/]$ +``` + + +Using curl command to send a CloudEvent to the broker: +```bash +[root@curler:/]$ curl -v "" \ +-X POST \ +-H "Ce-Id: review1" \ +-H "Ce-Specversion: 1.0" \ +-H "Ce-Type: new-review-comment" \ +-H "Ce-Source: bookstore-web-app" \ +-H "Content-Type: application/json" \ +-d 'Hello from Knative!' +``` + +You can find the URI to your broker by running the following command: + +```bash +$ kubectl get broker book-review-broker + +NAME URL AGE READY REASON +book-review-broker http://broker-ingress.knative-eventing.svc.cluster.local/default/book-review-broker 5m37s True +``` + +Wait a few seconds, and you should see a notification in your Slack channel. Congratulations! You have successfully set up the notification service for your bookstore. +## Conclusion + +In this tutorial, you learned how to set up an event-driven service that automates notifications to a Slack channel using Knative Eventing and Apache Camel K. By leveraging these technologies, you can easily connect your applications to third-party services, and pass information between them in real-time. diff --git a/code-samples/eventing/bookstore-sample-app/slack-sink/slack-sink-camel-pipe.yaml b/code-samples/eventing/bookstore-sample-app/slack-sink/slack-sink-camel-pipe.yaml new file mode 100644 index 000000000..11d331564 --- /dev/null +++ b/code-samples/eventing/bookstore-sample-app/slack-sink/slack-sink-camel-pipe.yaml @@ -0,0 +1,20 @@ +apiVersion: camel.apache.org/v1 # Specifies the API version of Camel K. +kind: Pipe # This resource type is a Pipe, a custom Camel K resource for defining integration flows. +metadata: + name: bookstore-notification-service # The name of the Pipe, which identifies this particular integration flow. +spec: + source: # Defines the source of events for the Pipe. + ref: + kind: Broker # Specifies the kind of source, in this case, a Knative Eventing Broker. + apiVersion: eventing.knative.dev/v1 # The API version of the Knative Eventing Broker. + name: book-review-broker # The name of the Broker, "book-review-broker" in this case + properties: + type: new-review-comment # A filter that specifies the type of events this Pipe will listen for, here it's listening for events of type "new-review-comment". You have to have this type specified. + sink: # Defines the destination for events processed by this Pipe. + ref: + kind: Kamelet # Specifies that the sink is a Kamelet, a Camel K component for connecting to external services. + apiVersion: camel.apache.org/v1 # The API version for Kamelet. + name: slack-sink # The name of the Kamelet to use as the sink, in this case, a predefined "slack-sink" Kamelet. + properties: + channel: “#bookstore-owner” # The Slack channel where notifications will be sent. + webhookUrl: "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK" # The Webhook URL provided by Slack for posting messages to a specific channel. \ No newline at end of file