Managing Topologies with Heron CLI

The Heron CLI us used to to manage every aspect of the topology lifecycle.

Deploying the heron CLI Executable

To 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:

Alternatively, generate a full Heron release and distribute the resulting heron CLI to all machines used to manage topologies.

Common CLI Args

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.

Optional CLI Flags

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:

Submitting a Topology

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:

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.

Example Topology Submission Command

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:

Other Topology Submission Options

Activating a Topology

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:

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.

Example Topology Activation Command

Deactivating a Topology

You can deactivate a running topology at any time using the deactivate command. Here’s the basic syntax:

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.

Restarting a Topology

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).

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.

Example Topology Restart Command

Killing a 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: