Chapter 5 Automating Volume Lifecycle with Heketi

Heketi is a service that provides a RESTful interface (the Heketi API) for managing the full lifecycle of Gluster Storage for Oracle Linux trusted storage pools and volumes. For example, Heketi can fully automate the steps defined in Section 2.5, “Creating the Trusted Storage Pool” and Section 3.1, “Creating Volumes”. You can write scripts to dynamically create, alter and destroy any clusters and volumes that Heketi manages.

Heketi uses the term cluster for Gluster trusted storage pools. This chapter uses the term cluster, which can be interchanged with the term trusted storage pool.

Heketi is especially helpful in managed cloud-based deployments where you can create volumes in a fast, stable and fully-automated way using the Heketi API, without any manual systems administration.

The Heketi client includes a CLI (heketi-cli) for creating and managing clusters, nodes, devices, and volumes. Although the Heketi CLI is available, you should use the Heketi API for automated management of clusters and volumes.

The latest Heketi documentation is available upstream at

5.1 Installing the Heketi API

To set up the Heketi API, install the Heketi service on a node in the proposed cluster (trusted storage pool), or on a separate server that is not part of the cluster.

To install and set up the Heketi API:

  1. Prepare the hosts and make sure the glusterd service is running on each node to be used in the Heketi cluster.

    Do not create Gluster trusted storage pools or volumes using the gluster command.

    Do not format the disks to use for volumes. The disks must be in RAW format to use them with Heketi.

    For information on preparing nodes and installing the glusterd service, see Section 2.4, “Installing and Configuring Gluster”.

  2. Install the Heketi server on a node in the Heketi cluster, or on a separate server:

    # yum install heketi
  3. The Heketi server node must have password-less SSH key access to all nodes in the Heketi cluster.

    You can either use the root user on each node in the Heketi cluster to set up SSH access, or you can use a non-root user. If you use a non-root user, set the user up on each node in the cluster, and make sure the user has sudo permissions. The user is not required on the Heketi server node unless the server node is also part of the Heketi cluster.

    On the Heketi server node, generate a password-less SSH key. For example:

    # ssh-keygen -f /mypath/heketi_key -t rsa -N ''

    Copy the public key to each node in the Heketi cluster. For example:

    # ssh-copy-id -i /mypath/heketi_key
    # ssh-copy-id -i /mypath/heketi_key
    # ssh-copy-id -i /mypath/heketi_key

    You can test the key has been set up correctly by using it to log into a Heketi cluster node from the Heketi server node. For example:

    # ssh -i /mypath/heketi_key

    On the Heketi server node, add this user to the sshexec section in the Heketi service configuration file, /etc/heketi/heketi.json. For example, for the root user with the SSH private key located at /mypath/heketi_key:

        "_sshexec_comment": "SSH username and private key file information",
        "sshexec": {
          "keyfile": "/mypath/heketi_key",
          "user": "root"
  4. (Optional) Configure other Heketi service options in the Heketi service configuration file, /etc/heketi/heketi.json. For example, set the API service port number (the default is 8080), or set up user access credentials.

  5. Start and enable the heketi service:

    # systemctl enable --now heketi
  6. You can verify the heketi service is running by sending a GET request to the Heketi API:

    # curl http://localhost:8080/hello
    Hello from Heketi