srkukarni commented on a change in pull request #1357: Pulsar Functions
documentation follow-up
URL: https://github.com/apache/incubator-pulsar/pull/1357#discussion_r173002324
##
File path: site/docs/latest/functions/quickstart.md
##
@@ -1,29 +1,176 @@
---
title: Getting started with Pulsar Functions
+lead: Write and run your first Pulsar Function in just a few steps
---
-## The `pulsar-functions` CLI tool
+This tutorial will walk you through running a {% popover standalone %} Pulsar
{% popover cluster %} on your machine and then running your first Pulsar
Functions using that cluster. The first function will run in local run mode
(outside your Pulsar {% popover cluster %}), while the second will run in
cluster mode (inside your cluster).
-[`pulsar-functions`](../../reference/CliTools#pulsar-functions)
+{% include admonition.html content="In local run mode, your Pulsar Function
will communicate with your Pulsar cluster but will run outside of the cluster."
%}
+
+## Prerequisites
+
+In order to follow along with this tutorial, you'll need to have
[Maven](https://maven.apache.org/download.cgi) installed on your machine.
+
+## Run a standalone Pulsar cluster
+
+In order to run our Pulsar Functions, we'll need to run a Pulsar cluster
locally first. The easiest way to do that is to run Pulsar in {% popover
standalone %} mode. Follow these steps to start up a standalone cluster:
+
+```bash
+$ wget
https://github.com/streamlio/incubator-pulsar/releases/download/2.0.0-incubating-functions-preview/apache-pulsar-2.0.0-incubating-functions-preview-bin.tar.gz
+$ tar xvf apache-pulsar-2.0.0-incubating-functions-preview-bin.tar.gz
+$ cd apache-pulsar-2.0.0-incubating-functions-preview
+$ bin/pulsar standalone \
+ --advertised-address 127.0.0.1
+```
+
+When running Pulsar in standalone mode, the `sample` {% popover tenant %} and
`ns1` {% popover namespace %} will be created automatically for you. That
tenant and namespace will be used throughout this tutorial.
+
+## Run a Pulsar Function in local run mode
+
+To run a function in local mode, i.e. outside our Pulsar cluster:
+
+```bash
+$ bin/pulsar-admin functions localrun \
+ --jar examples/api-examples.jar \
+ --className org.apache.pulsar.functions.api.examples.ExclamationFunction \
+ --inputs persistent://sample/standalone/ns1/exclamation-input \
+ --output persistent://sample/standalone/ns1/exclamation-output \
+ --name exclamation
+```
+
+The JAR file containing the function (written in Java) is included with the
binary distribution you downloaded above.
+
+We can use the [`pulsar-client`](../../reference/CliTools#pulsar-client) CLI
tool to publish a message to the input topic:
+
+```bash
+$ bin/pulsar-client produce
persistent://sample/standalone/ns1/exclamation-input \
+ --num-produce 1 \
+ --messages "Hello world"
+```
+
+Here's what happens next:
+
+* The `Hello world` message that we published to the input {% popover topic %}
(`persistent://sample/standalone/ns1/exclamation-input`) will be passed to the
exclamation function that we're now running on our laptop
+* The exclamation function will process the message (providing a result of
`Hello world!`) and publish the result to the output topic
(`persistent://sample/standalone/ns1/exclamation-output`).
+* Pulsar will durably store the message data published to the output topic in
[Apache BookKeeper](https://bookkeeper.apache.org) until a {% popover consumer
%} consumes and {% popover acknowledges %} the message
+
+To consume the message, we can use the same
[`pulsar-client`](../../reference/CliTools#pulsar-client) tool that we used to
publish the original message:
+
+```bash
+$ bin/pulsar-client consume
persistent://sample/standalone/ns1/exclamation-output \
+ --subscription-name my-subscription \
+ --num-messages 1
+```
+
+In the output, you should see the following:
+
+```
+- got message -
+Hello world!
+```
+
+Success! As you can see, the message has been successfully processed by the
exclamation function. To shut down the function, simply hit **Ctrl+C**.
+
+## Run a Pulsar Function in cluster mode
+
+[Local run mode](#run-a-pulsar-function-in-local-run-mode) is useful for
development and experimentation, but if you wanted to use Pulsar Functions in a
real Pulsar deployment, you'd want to run them in **cluster mode**. In cluster
mode, Pulsar Functions run *inside* your Pulsar cluster and are managed using
the same `pulsar-admin functions` interface that we've been using thus far.
Review comment:
wording can be changed here. Ppl can actually launch topologies in localrun
to be run on clusters like mesos/k8. Running inside Pulsar Cluster is just yet
another conv mode.
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, plea
