[incubator-pulsar] branch master updated: Document default values for Pulsar Functions (#1657)

[mm...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

mmerli pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-pulsar.git


The following commit(s) were added to refs/heads/master by this push:
     new e5f2e32  Document default values for Pulsar Functions (#1657)
e5f2e32 is described below

commit e5f2e32c526bf88592ce7ce9e6261ccabe9aa858
Author: Luc Perkins <lu...@gmail.com>
AuthorDate: Thu May 3 14:23:48 2018 -0700

    Document default values for Pulsar Functions (#1657)
    
    * add section on default values
    
    * clarify default tenants and namespaces
---
 site/docs/latest/functions/api.md        | 12 ++++++----
 site/docs/latest/functions/deployment.md | 39 ++++++++++++++++++++++++++++++++
 site/docs/latest/functions/overview.md   |  4 ++--
 3 files changed, 49 insertions(+), 6 deletions(-)

diff --git a/site/docs/latest/functions/api.md b/site/docs/latest/functions/api.md
index ca45b94..4f92012 100644
--- a/site/docs/latest/functions/api.md
+++ b/site/docs/latest/functions/api.md
@@ -45,10 +45,14 @@ Deploying Pulsar Functions is handled by the [`pulsar-admin`](../../reference/Cl
 
 ```bash
 $ bin/pulsar-admin functions localrun \
-  --py sanitizer.py \
-  --className sanitizer \
-  --tenant sample \
-  --namespace ns1
+  --py sanitizer.py \          # The Python file with the function's code
+  --className sanitizer \      # The class or function holding the processing logic
+  --tenant sample \            # The function's tenant (derived from the topic name by default)
+  --namespace ns1 \            # The function's namespace (derived from the topic name by default)
+  --name sanitizer-function \  # The name of the function (the class name by default)
+  --inputs dirty-strings-in \  # The input topic(s) for the function
+  --output clean-strings-out \ # The output topic for the function
+  --logTopic sanitizer-logs    # The topic to which all functions logs are published
 ```
 
 For instructions on running functions in your Pulsar cluster, see the [Deploying Pulsar Functions](../deployment) guide.
diff --git a/site/docs/latest/functions/deployment.md b/site/docs/latest/functions/deployment.md
index 25c0c2f..3dbe6dd 100644
--- a/site/docs/latest/functions/deployment.md
+++ b/site/docs/latest/functions/deployment.md
@@ -22,6 +22,45 @@ In order to deploy and manage Pulsar Functions, you need to have a Pulsar {% pop
 
 If you're running a non-{% popover standalone %} cluster, you'll need to obtain the service URL for the cluster. How you obtain the service URL will depend on how you deployed your Pulsar cluster.
 
+## Command-line interface {#cli}
+
+Pulsar Functions are deployed and managed using the [`pulsar-admin functions`](../../reference/CliTools#pulsar-admin-functions) interface, which contains commands such as [`create`](../../reference/CliTools#pulsar-admin-functions-create) for deploying functions in [cluster mode](#cluster-mode), [`trigger`](../../reference/CliTools#pulsar-admin-functions-trigger) for [triggering](#triggering) functions, [`list`](../../reference/CliTools#pulsar-admin-functions-list) for listing deployed fu [...]
+
+### Fully Qualified Function Name (FQFN) {#fqfn}
+
+Each Pulsar Function has a **Fully Qualified Function Name** (FQFN) that consists of three elements: the function's {% popover tenant %}, {% popover namespace %}, and function name. FQFN's look like this:
+
+{% include fqfn.html tenant="tenant" namespace="namespace" name="name" %}
+
+FQFNs enable you to, for example, create multiple functions with the same name provided that they're in different namespaces.
+
+### Default arguments
+
+When managing Pulsar Functions, you'll need to specify a variety of information about those functions, including {% popover tenant %}, {% popover namespace %}, input and output topics, etc. There are some parameters, however, that have default values that will be supplied if omitted. The table below lists the defaults:
+
+Parameter | Default
+:---------|:-------
+Function name | Whichever value is specified for the class name. For example, `--className org.example.MyFunction` would give the function a name of `MyFunction`
+Tenant | Derived from the input topics' names. If the input topics are under the `marketing` tenant---i.e. the topic names have the form `persistent://marketing/{namespace}/{topicName}`---then the tenant will be `marketing`.
+Namespace | Derived from the input topics' names. If the input topics are under the `asia` namespace under the `marketing` tenant---i.e. the topic names have the form `persistent://marketing/asia/{topicName}`, then the namespace will be `asia`.
+Output topic | `{input topic}-{function name}-output`. A function with an input topic name of `incoming` and a function name of `exclamation`, for example, would have an output topic of `incoming-exclamation-output`.
+Subscription type | For at-least-once and at-most-once [processing guarantees](../guarantees), the [`SHARED`](../../getting-started/ConceptsAndArchitecture#shared) is applied by default; for effectively-once guarantees, [`FAILOVER`](../../getting-started/ConceptsAndArchitecture#failover) is applied
+Processing guarantees | [`ATLEAST_ONCE`](../guarantees)
+Pulsar service URL | `pulsar://localhost:6650`
+
+#### Example use of defaults
+
+Take this `create` command:
+
+```bash
+$ bin/pulsar-admin functions create \
+  --jar my-pulsar-functions.jar \
+  --className org.example.MyFunction \
+  --inputs my-function-input-topic1,my-function-input-topic2
+```
+
+The created function would have default values supplied for the function name (`MyFunction`), tenant (`public`), namespace (`default`), subscription type (`SHARED`), processing guarantees (`ATLEAST_ONCE`), and Pulsar service URL (`pulsar://localhost:6650`).
+
 ## Local run mode {#local-run}
 
 If you run a Pulsar Function in **local run** mode, it will run on the machine from which the command is run (this could be your laptop, an [AWS EC2](https://aws.amazon.com/ec2/) instance, etc.). Here's an example [`localrun`](../../CliTools#pulsar-admin-functions-localrun) command:
diff --git a/site/docs/latest/functions/overview.md b/site/docs/latest/functions/overview.md
index d99c280..a904f81 100644
--- a/site/docs/latest/functions/overview.md
+++ b/site/docs/latest/functions/overview.md
@@ -264,8 +264,8 @@ The Pulsar Functions feature was built to support a variety of deployment option
 
 Deployment mode | Description
 :---------------|:-----------
-Local run mode | The function runs in your local environment, for example on your laptop
-Cluster mode | The function runs *inside of* your Pulsar cluster, on the same machines as your Pulsar {% popover brokers %}
+[Local run mode](#local-run) | The function runs in your local environment, for example on your laptop
+[Cluster mode](#cluster-run) | The function runs *inside of* your Pulsar cluster, on the same machines as your Pulsar {% popover brokers %}
 
 ### Local run mode {#local-run}
 

-- 
To stop receiving notification emails like this one, please contact
mmerli@apache.org.