12 Jan 2036 06:39:36 GMT
ETag: "e11166774e33484b67bb9934edcf442dc4e0eec5"

# CLI utility for creating Cluster aware CLI tools for Gluster
cliutils is a Python library which provides wrapper around `gluster system::
execute` command to extend the functionalities of Gluster.

Example use cases:
- Start a service in all peer nodes of Cluster
- Collect the status of a service from all peer nodes
- Collect the config values from each peer nodes and display latest
  config based on version.
- Copy a file present in GLUSTERD_WORKDIR from one peer node to all
  other peer nodes.(Geo-replication create push-pem is using this to
  distribute the SSH public keys from all master nodes to all slave
  nodes)
- Generate pem keys in all peer nodes and collect all the public keys
  to one place(Geo-replication gsec_create is doing this)
- Provide Config sync CLIs for new features like `gluster-eventsapi`,
  `gluster-restapi`, `gluster-mountbroker` etc.

## Introduction

If a executable file present in `$GLUSTER_LIBEXEC` directory in all
peer nodes(Filename startswith `peer_`) then it can be executed by
running `gluster system:: execute` command from any one peer node.

- This command will not copy any executables to peer nodes, Script
  should exist in all peer nodes to use this infrastructure. Raises
  error in case script not exists in any one of the peer node.
- Filename should start with `peer_` and should exist in
  `$GLUSTER_LIBEXEC` directory.
- This command can not be called from outside the cluster.

To understand the functionality, create a executable file `peer_hello`
under $GLUSTER_LIBEXEC directory and copy to all peer nodes.

    #!/usr/bin/env bash
    echo "Hello from $(gluster system:: uuid get)"

Now run the following command from any one gluster node,

    gluster system:: execute hello

**Note:** Gluster will not copy the executable script to all nodes,
  copy `peer_hello` script to all peer nodes to use `gluster system::
  execute` infrastructure.

It will run `peer_hello` executable in all peer nodes and shows the
output from each node(Below example shows output from my two nodes
cluster)

    Hello from UUID: e7a3c5c8-e7ad-47ad-aa9c-c13907c4da84
    Hello from UUID: c680fc0a-01f9-4c93-a062-df91cc02e40f

## cliutils
A Python wrapper around `gluster system:: execute` command is created
to address the following issues

- If a node is down in the cluster, `system:: execute` just skips it
  and runs only in up nodes.
- `system:: execute` commands are not user friendly
- It captures only stdout, so handling errors is tricky.

**Advantages of cliutils:**

- Single executable file will act as node component as well as User CLI.
- `execute_in_peers` utility function will merge the `gluster system::
  execute` output with `gluster peer status` to identify offline nodes.
- Easy CLI Arguments handling.
- If node component returns non zero return value then, `gluster
  system:: execute` will fail to aggregate the output from other
  nodes. `node_output_ok` or `node_output_notok` utility functions
  returns zero both in case of success or error, but returns json
  with ok: true or ok:false respectively.
- Easy to iterate on the node outputs.
- Better error handling - Geo-rep CLIs `gluster system:: execute
  mountbroker`, `gluster system:: execute gsec_create` and `gluster
  system:: add_secret_pub` are suffering from error handling. These
  tools are not notifying user if any failures during execute or if a node
  is down during execute.

### Hello World
Create a file in `$LIBEXEC/glusterfs/peer_message.py` with following
content.

    #!/usr/bin/python3
    from gluster.cliutils import Cmd, runcli, execute_in_peers, node_output_ok

    class NodeHello(Cmd):
        name = "node-hello"