The Heron CLI us used to to manage every aspect of the topology lifecycle.
heron
CLI ExecutableTo use heron
CLI, download the heron-install
for your platfrom from release binaries and run the installation script. For example, if you have downloaded the version 0.17.6
, you invoke the installation script as follows
$ chmod +x heron-install-0.17.6-darwin.sh $ ./heron-install-0.17.6-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
, update
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
, update
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).
Below is 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
You can update the parallelism of any of the components of a deployed topology using the update
command.
$ heron help update usage: heron update [options] cluster/[role]/[env] <topology-name> --component-parallelism <name:value> Required arguments: cluster/[role]/[env] Cluster, role, and environment to run topology topology-name Name of the topology Optional arguments: --component-parallelism COMPONENT_PARALLELISM Component name and the new parallelism value colon- delimited: [component_name]:[parallelism] --config-path (a string; path to cluster config; default: "/Users/billg/.heron/conf") --config-property (key=value; a config key and its value; default: []) --verbose (a boolean; default: "false")
Arguments of the update
command include cluster/[role]/[env] and topology-name as well as:
$ heron update local/ads/PROD my-topology \ --component-parallelism=my-spout:2 \ --component-parallelism=my-bolt:4
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
When using the Heron CLI tool to interact with Heron clusters, there are two ways to provide configuration for the tool:
--service-url
heron config
interface, which enables you to set, unset, and list configs in the local filesystemThe following parameters can currently be set using the heron config
interface:
Parameter | Description | Corresponding CLI flag |
---|---|---|
service_url | The service URL for the Heron cluster | --service-url |
You can set a config using the set
command. Here's an example:
$ heron config us-west-staging set service_url http://us-west.staging.example.com:9000
You can remove a parameter using the unset
command. Here's an example:
$ heron config apac-australia unset service_url
You can list all of the CLI configs for a Heron cluster using the list
command. This will return the configs as a list of parameter = value
pairs. Here's an example:
$ heron config local list service_url = http://localhost:9000
Let‘s say that you need to interact with a Heron cluster called apac-japan-staging
which has a service URL of http://apac-japan.staging.example.com:9000. If you specified the service URL via CLI flags, you’d need to set the flag every time you perform an operation involving that cluster:
$ heron deactivate apac-japan-staging MyTopology \ --service-url http://apac-japan.staging.example.com:9000
Using heron config
, however, you could set the service URL for that cluster once and for all:
$ heron config apac-japan-staging set service_url http://apac-japan.staging.example.com:9000 $ heron deactivate apac-japan-staging MyTopology
Run the version
command at any time to see which version of heron
you're using:
$ heron version heron.build.version : '0.17.6' heron.build.time : Wed Feb 28 12:08:52 PST 2018 heron.build.timestamp : 1519848532000 heron.build.host : ci-server-01 heron.build.user : release-agent1 heron.build.git.revision : ada6052f6f841e27416b9f9bb4be73183d5a8cd8 heron.build.git.status : Clean