Samza provides a REST service that is deployable on any node in the cluster and has pluggable interfaces to add custom Resources and Monitors. It is intended to be a node-local delegate for common actions such as starting jobs, sampling the local state, measuring disk usage, taking heap dumps, verifying liveness, and so on.
The Samza REST Service does not yet have SSL enabled or authentication, so it is initially geared for more backend and operations use cases. It would not be wise to expose it as a user-facing API in environments where users are not allowed to stop each other's jobs, for example.
Samza REST is packaged and configured very similarly to Samza jobs. A notable difference is Samza REST must be deployed and executed on each host you want it to run on, whereas a Samza Job is typically started on a master node in the cluster manager and the master deploys the job to the other nodes.
Samza REST is intended to be a proxy for all operations which need to be executed from the nodes of the Samza cluster. It can be deployed to all the hosts in the cluster and may serve different purposes on different hosts. In such cases it may be useful to deploy the same release tarball with different configs to customize the functionality for the role of the hosts. For example, Samza REST may be deployed on a YARN cluster with one config for the ResourceManager (RM) hosts and another config for the NodeManager (NM) hosts.
Deploying the service is very similar to running a Samza job. First build the tarball using: {% highlight bash %} ./gradlew samza-rest:clean releaseRestServiceTar {% endhighlight %}
Then from the extracted location, run the service using: {% highlight bash %} samza-example/target/bin/run-samza-rest-service.sh
--config job.config.loader.factory=org.apache.samza.config.loaders.PropertiesConfigLoaderFactory
--config job.config.loader.properties.path=$PWD/config/samza-rest.properties {% endhighlight %}
The two config parameters have the same purpose as they do for run-job.sh.
Follow the getting started tutorial to quickly deploy and test the Samza REST Service for the first time.
The Samza REST Service relies on the same configuration system as Samza Jobs. However, the Samza REST Service config file itself is completely separate and unrelated to the config files for your Samza jobs.
The configuration may provide values for the core configs as well as any additional configs needed for Resources or Monitors that you may have added to the service. A basic configuration file which includes configs for the core service as well as the JobsResource looks like this:
{% highlight jproperties %}
services.rest.port=9139
job.proxy.factory.class=org.apache.samza.rest.proxy.job.SimpleYarnJobProxyFactory
job.installations.path=/hello-samza-ROOT/deploy/samza {% endhighlight %}
Samza REST uses SLF4J for logging. The run-samza-rest-service.sh script mentioned above by default expects a log4j.xml in the package's bin directory and writes the logs to a logs directory in the package root. However, since the script invokes the same run-class.sh script used to run Samza jobs, it can be reconfigured very similarly to logging for Samza jobs.