The Heron CLI us used to to manage every aspect of the topology lifecycle.
heron CLI ExecutableTo use heron CLI, download the heron-client-install for your platfrom from release binaries and run the installation script. For example, if you have downloaded the version 0.13.5, you invoke the installation script as follows:
$ chmod +x heron-client-install-0.13.5-darwin.sh $ ./heron-client-install-0.13.5-darwin.sh --user Heron client installer ---------------------- Uncompressing...... Heron is now installed! Make sure you have "/Users/$USER/bin" in your path. See http://heronstreaming.io/docs/getting-started.html on how to use Heron! ....
Alternatively, generate a full Heron release and distribute the resulting heron CLI to all machines used to manage topologies.
All topology management commands (submit, activate, deactivate, restart, and kill) take the following required arguments:
cluster — The name of the cluster where the command needs to be executed.
role — This represents the user or the group depending on deployment. If not provided, it defaults to the unix user.
env — This is a tag for including additional information (e.g) a topology can be tagged as PROD or DEVEL to indicate whether it is in production or development. If env is not provided, it is given a value default
cluster, role and env are specified as a single argument in the form of cluster/role/env (e.g) local/ads/PROD to refer the cluster local with role ads and the environment PROD. If you just want to specify cluster, the argument will be simply local.
CLI supports a common set of optional flags for all topology management commands (submit, activate, deactivate, restart, and kill):
--config-path — Every heron cluster must provide a few configuration files that are kept under a directory named after the cluster. By default, when a cluster is provided in the command, it searches the conf directory for a directory with the cluster name. This flag enables you to specify a non standard directory to search for the cluster directory.
--config-property — Heron supports several configuration parameters that be overridden. These parameters are specified in the form of key=value.
--verbose — When this flag is provided, heron CLI prints logs that provide detailed information about the execution.
Below is an example topology management command that uses one of these flags:
$ heron activate --config-path ~/heronclusters devcluster/ads/PROD AckingTopology
To run a topology in a Heron cluster, submit it using the submit command. Topologies can be submitted in either an activated (default) or deactivated state (more on activation and deactivation below).
Here's the basic syntax:
$ heron help submit usage: heron submit [options] cluster/[role]/[env] topology-file-name topology-class-name [topology-args] Required arguments: cluster/[role]/[env] Cluster, role, and env to run topology topology-file-name Topology jar/tar/zip file topology-class-name Topology class name Optional arguments: --config-path (a string; path to cluster config; default: "/Users/$USER/.heron/conf") --config-property (key=value; a config key and its value; default: []) --deploy-deactivated (a boolean; default: "false") --topology-main-jvm-property Define a system property to pass to java -D when running main. --verbose (a boolean; default: "false")
Arguments of the submit command:
cluster/[role]/[env] — The cluster where topology needs to be submitted, optionally taking the role and environment. For example,local/ads/PROD or just local
topology-file-name — The path of the file in which you‘ve packaged the topology’s code. For Java topologies this will be a .jar file; for topologies in other languages (not yet supported), this could be a .tar file. For example, /path/to/topology/my-topology.jar
topology-class-name — The name of the class containing the main function for the topology. For example, com.example.topologies.MyTopology
topology-args (optional) — Arguments specific to the topology. You will need to supply additional args only if the main function for your topology requires them.
Below is an example command that submits a topology to a cluster named devcluster with a main class named com.example.topologies.MyTopology packaged in my-topology.jar, along with the optional --config-path where the config for devcluster can be found:
$ heron submit --config-path ~/heronclusters devcluster /path/to/topology/my-topology.jar \ com.example.topologies.MyTopology my-topology
| Flag | Meaning |
|---|---|
--deploy-deactivated | If set, the topology is deployed in a deactivated state. |
--topology-main-jvm-property | Defines a system property to pass to java -D when running topology main |
Topologies are submitted to the cluster in the activated state by default. To activate a deactivated topology use the activate command. Below is the basic syntax:
$ heron help activate usage: heron activate [options] cluster/[role]/[env] topology-name Required arguments: cluster/[role]/[env] Cluster, role, and env to run topology topology-name Name of the topology Optional arguments: --config-path (a string; path to cluster config; default: "/Users/$USER/.heron/conf") --config-property (key=value; a config key and its value; default: [])
Arguments of the activate command:
cluster/[role]/[env] — The cluster where topology needs to be submitted, optionally taking the role and environment. For exampple, local/ads/PROD or just local
topology-name — The name of the already-submitted topology that you'd like to activate.
$ heron activate local/ads/PROD my-topology
You can deactivate a running topology at any time using the deactivate command. Here's the basic syntax:
$ heron help deactivate usage: heron deactivate [options] cluster/[role]/[env] topology-name Required arguments: cluster/[role]/[env] Cluster, role, and env to run topology topology-name Name of the topology Optional arguments: --config-path (a string; path to cluster config; default: "/Users/kramasamy/.heron/conf") --config-property (key=value; a config key and its value; default: []) --verbose (a boolean; default: "false")
Arguments of the deactivate command:
cluster/[role]/[env] — The cluster where topology needs to be submitted, optionally taking the role and environment. For example, local/ads/PROD or just local
topology-name — The name of the topology that you'd like to deactivate.
You can restart a deactivated topology using the restart command (assuming that the topology has not yet been killed, i.e. removed from the cluster).
$ heron help restart usage: heron restart [options] cluster/[role]/[env] topology-name [container-id] Required arguments: cluster/[role]/[env] Cluster, role, and env to run topology topology-name Name of the topology container-id Identifier of the container to be restarted Optional arguments: --config-path (a string; path to cluster config; default: "/Users/kramasamy/.heron/conf") --config-property (key=value; a config key and its value; default: []) --verbose (a boolean; default: "false")
Arguments of the restart command:
cluster/[role]/[env] — The cluster where topology needs to be submitted, optionally taking the role and environment. For example, local/ads/PROD or just local
topology-name — The name of the topology that you'd like to restart.
container-id (optional) — This enables you to specify the container ID to be restarted if you want to restart only a specific container of the topology.
$ heron restart local/ads/PROD my-topology
If you‘ve submitted a topology to your Heron cluster and would like to remove knowledge of the topology entirely, you can remove it using the kill command. Here’s the basic syntax:
$ heron kill <killer-overrides> <topology>
Arguments of the kill command:
cluster/[role]/[env] — The cluster where topology needs to be submitted, optionally taking the role and environment. For example, local/ads/PROD or just local
topology-name — The name of the topology that you'd like to kill.
$ heron kill local my-topology
Run the version command at any time to see which version of heron you're using:
$ heron version heron.build.version : 0.13.5 heron.build.time : Wed May 11 23:49:00 PDT 2016 heron.build.timestamp : 1463035740000 heron.build.host : mbp-machine heron.build.user : userwhobuilt INFO: Elapsed time: 0.000s.