Skip to main content
Version: Next

Manage Functions

tip

This page only shows some frequently used operations. For the latest and complete information, see the reference docs below.

CategoryMethodIf you want to manage functions...
Pulsar CLIpulsar-admin, which lists all commands, flags, descriptions, and more.See the functions command
Pulsar admin APIsREST API, which lists all parameters, responses, samples, and more.See the /admin/v3/functions endpoint
Pulsar admin APIsJava admin API, which lists all classes, methods, descriptions, and more.See the functions method of the PulsarAdmin object

You can perform the following operations on functions.

Create a function​

You can create a Pulsar function in cluster mode (deploy it on a Pulsar cluster) using the Admin CLI, the REST API or the Java admin API. Every interface takes the same two inputs:

  • the configuration: the fields of FunctionConfig (tenant, namespace, name, className, inputs, output, parallelism, userConfig, resources, ...). Every field is available in every interface under the same name: as command-line options or the keys of the YAML file for the CLI, the keys of the JSON functionConfig part for the REST API, and the setters of the FunctionConfig object in Java, for both create and update;
  • the package, in one of three forms:
PackageHow to pass itNotes
A fileCLI: --jar, --py or --go; REST: the data file part; Java: the file name argumentUploaded to the function worker.
A URLCLI: jar: <url> in the configuration file; REST: the url form field; Java: createFunctionWithUrlFetched by the function worker; the URL must be allowed, see below.
A built-in functionjar: builtin://<function name> in the configuration, no packageThe worker uses the function from its functionsDirectory.

A package URL is fetched by the function worker and must be allowed by its configuration in conf/functions_worker.yml; a URL that is not allowed fails with 400 Function Package url is not valid:

  • file:///path/on/the/worker: the path must lie inside the worker's functionsDirectory, with enableReferencingFunctionsDirectoryFiles: true (the default).
  • http://... or https://...: the URL must match one of the regular expressions in additionalEnabledFunctionsUrlPatterns (empty by default). A file:// path outside the functions directory can be allowed the same way.
  • function://tenant/namespace/name@version: a package uploaded to package management; requires functionsWorkerEnablePackageManagement: true.
  • Sources and sinks use connectorsDirectory, enableReferencingConnectorDirectoryFiles and additionalEnabledConnectorUrlPatterns instead.

Use the create subcommand. The configuration can be given as command-line options:

pulsar-admin functions create \
    --tenant public \
    --namespace default \
    --name exclamation \
    --classname org.apache.pulsar.functions.api.examples.ExclamationFunction \
    --inputs persistent://public/default/test-input-topic \
    --output persistent://public/default/test-output-topic \
    --parallelism 1 \
    --jar $PWD/examples/api-examples.jar

or kept in a YAML file passed with --function-config-file, which is easier to maintain: it can live in version control, and the same file serves update later. Command-line options override the values in the file.

cat > exclamation.yaml <<EOF
tenant: public
namespace: default
name: exclamation
className: org.apache.pulsar.functions.api.examples.ExclamationFunction
inputs:
  - persistent://public/default/test-input-topic
output: persistent://public/default/test-output-topic
parallelism: 1
EOF

pulsar-admin functions create \
    --function-config-file exclamation.yaml \
    --jar $PWD/examples/api-examples.jar

For a package URL or a built-in function, put it in the jar key of the file (jar: https://... or jar: builtin://<function name>) and drop --jar.

Update a function​

You can update a function that is already deployed using the Admin CLI, the REST API or the Java admin API. An update takes the same configuration and package as create and uses the same requests, so the examples above apply; what differs is how the function worker treats them:

  • The configuration is merged into the deployed one: settings you leave out keep their current values, and the tenant, namespace and name must match the deployed function. You can therefore send either the complete configuration the function was created with, or only its identity (tenant, namespace, name) and the settings to change.
  • Some settings cannot be changed by an update: the input topics, the subscription name, the processing guarantees, the ordering guarantees and the runtime. To change those, delete the function and create it again.
  • The package is optional: leave it out to keep the deployed code, or provide it to roll out a new build.
  • An update that changes neither the configuration nor the package is rejected with 400 Update contains no change.
  • The update-only option --update-auth-data (updateOptions.updateAuthData in the REST and Java APIs) makes the worker replace the authentication data stored for the function, for example the token the function uses to connect to Pulsar, with the credentials of the caller.

Use the update subcommand. Update merges into the deployed configuration, so you can pass the same configuration file as in the create example, a file with only tenant, namespace, name and the settings to change, or just command-line options; either way, pass --jar (or --py, --go) to also roll out a new implementation, and leave it out to keep the deployed one.

Example

# roll out a new build of the function (with whatever the file contains, changed or not)
pulsar-admin functions update \
    --function-config-file exclamation.yaml \
    --jar $PWD/examples/api-examples-2.jar

# change only the configuration, for example after setting parallelism: 2 in the file;
# the deployed implementation is kept
pulsar-admin functions update \
    --function-config-file exclamation.yaml

# the same change with command-line options only: the function's identity and the settings to change
pulsar-admin functions update \
    --tenant public \
    --namespace default \
    --name exclamation \
    --parallelism 2

Start a function​

You can start an instance of a function or start all instances of a function.

Start an instance of a function​

You can start a stopped function instance with instance-id using Admin CLI, REST API or Java Admin API.

Use the start subcommand.

pulsar-admin functions start \
    --tenant public \
    --namespace default \
    --name (the name of Pulsar Functions) \
    --instance-id 1

Start all instances of a function​

You can start all stopped function instances using Admin CLI, REST API or Java Admin API.

Use the start subcommand.

Example

pulsar-admin functions start \
    --tenant public \
    --namespace default \
    --name (the name of Pulsar Functions) \

Stop a function​

You can stop an instance of a function or stop all instances of a function.

Stop an instance of a function​

You can stop a function instance with instance-id using Admin CLI, REST API or Java Admin API.

Use the stop subcommand.

Example

pulsar-admin functions stop \
	--tenant public \
	--namespace default \
	--name (the name of Pulsar Functions) \
	--instance-id 1

Stop all instances of a function​

You can stop all function instances using Admin CLI, REST API or Java Admin API.

Use the stop subcommand.

Example

pulsar-admin functions stop \
	--tenant public \
	--namespace default \
	--name (the name of Pulsar Functions)

Restart a function​

You can restart an instance of a function or restart all instances of a function.

Restart an instance of a function​

Restart a function instance with instance-id using Admin CLI, REST API or Java Admin API.

Use the restart subcommand.

Example

pulsar-admin functions restart \
	--tenant public \
	--namespace default \
	--name (the name of Pulsar Functions) \
	--instance-id 1

Restart all instances of a function​

You can restart all function instances using Admin CLI, REST API or Java admin API.

Use the restart subcommand.

Example

pulsar-admin functions restart \
	--tenant public \
	--namespace default \
	--name (the name of Pulsar Functions)

List all functions​

You can list all Pulsar functions running under a specific tenant and namespace using Admin CLI, REST API or Java Admin API.

Use the list subcommand.

Example

pulsar-admin functions list \
	--tenant public \
	--namespace default

Delete a function​

You can delete a Pulsar function that is running on a Pulsar cluster using Admin CLI, REST API or Java Admin API.

Use the delete subcommand.

Example

pulsar-admin functions delete \
	--tenant public \
	--namespace default \
	--name (the name of Pulsar Functions)

Get info about a function​

You can get information about a Pulsar function currently running in cluster mode using Admin CLI, REST API or Java Admin API.

Use the get subcommand.

Example

pulsar-admin functions get \
	--tenant public \
	--namespace default \
	--name (the name of Pulsar Functions)

Get status of a function​

You can get the status of an instance of a function or get the status of all instances of a function.

Get status of an instance of a function​

You can get the current status of a Pulsar function instance with instance-id using Admin CLI, REST API or Java Admin API.

Use the status subcommand.

Example

pulsar-admin functions status \
	--tenant public \
	--namespace default \
	--name (the name of Pulsar Functions) \
	--instance-id 1

Get status of all instances of a function​

You can get the current status of a Pulsar function instance using Admin CLI, REST API or Java Admin API.

Use the status subcommand.

Example

pulsar-admin functions status \
	--tenant public \
	--namespace default \
	--name (the name of Pulsar Functions)

Get stats of a function​

You can get stats of an instance of a function or get stats of all instances of a function.

Get stats of an instance of a function​

You can get the current stats of a Pulsar Function instance with instance-id using Admin CLI, REST API or Java admin API.

Use the stats subcommand.

Example

pulsar-admin functions stats \
	--tenant public \
	--namespace default \
	--name (the name of Pulsar Functions) \
	--instance-id 1

Get stats of all instances of a function​

You can get the current stats of a Pulsar function using Admin CLI, REST API or Java admin API.

Use the stats subcommand.

Example

pulsar-admin functions stats \
	--tenant public \
	--namespace default \
	--name (the name of Pulsar Functions)

Trigger a function​

You can trigger a specified Pulsar function with a supplied value using Admin CLI, REST API or Java admin API.

Use the trigger subcommand.

Example

pulsar-admin functions trigger \
	--tenant public \
	--namespace default \
	--name (the name of Pulsar Functions) \
	--topic (the name of input topic) \
	--trigger-value \"hello pulsar\"
	# or --trigger-file (the path of trigger file)

Put state associated with a function​

You can put the state associated with a Pulsar function using Admin CLI, REST API or Java admin API.

Use the putstate subcommand.

Example

pulsar-admin functions putstate \
	--tenant public \
	--namespace default \
	--name (the name of Pulsar Functions) \
	--state "{\"key\":\"pulsar\", \"stringValue\":\"hello pulsar\"}"

Fetch state associated with a function​

You can fetch the current state associated with a Pulsar function using Admin CLI, REST API or Java admin API.

Use the querystate subcommand.

Example

pulsar-admin functions querystate \
	--tenant public \
	--namespace default \
	--name (the name of Pulsar Functions) \
	--key (the key of state)
Was this helpful?
💡 Suggest changes🛟 Get support